> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getgrasp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript/TypeScript SDK

> Official JavaScript/TypeScript SDK for Grasp

## Installation

Install the SDK using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @getgrasp/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @getgrasp/sdk
  ```

  ```bash yarn theme={null}
  yarn add @getgrasp/sdk
  ```
</CodeGroup>

## Quick Start

```javascript theme={null}
import { Grasp } from '@getgrasp/sdk';

const grasp = new Grasp({
  apiKey: 'your-api-key'
});

const container = await grasp.create();
console.log('Browser ready:', container.browser.wsEndpoint);

await container.shutdown();
```

## API Reference

### new Grasp(options)

Create a new Grasp client instance.

<ParamField body="options" type="object" optional>
  <Expandable title="Configuration object">
    <ParamField body="apiKey" type="string" optional>
      API key for authentication. Falls back to `GRASP_API_KEY` environment variable
    </ParamField>
  </Expandable>
</ParamField>

**Returns:** Grasp client instance

**Example:**

```javascript theme={null}
// Using environment variable
const grasp = new Grasp();

// With explicit API key
const grasp = new Grasp({
  apiKey: 'your-api-key'
});
```

### grasp.create(options)

Create and start a new container.

<ParamField body="options" type="object" optional>
  <Expandable title="Container configuration options">
    <ParamField body="idleTimeout" type="number" optional>
      Container idle timeout in milliseconds
    </ParamField>

    <ParamField body="proxy" type="TProxySettings" optional>
      Proxy configuration
    </ParamField>

    <ParamField body="browser" type="TBrowserSettings" optional>
      Browser settings
    </ParamField>

    <ParamField body="terminal" type="TTerminalSettings" optional>
      Terminal settings
    </ParamField>

    <ParamField body="filesystem" type="TFileSystemSettings" optional>
      Filesystem settings
    </ParamField>
  </Expandable>
</ParamField>

**Returns:** Promise\<GraspContainer>

**Example:**

```javascript theme={null}
// Create basic container
const container = await grasp.create();

// With idle timeout
const container = await grasp.create({
  idleTimeout: 60000  // 60 seconds
});

// With proxy settings
const container = await grasp.create({
  proxy: {
    enabled: true,
    type: 'residential',
    country: 'US'
  }
});
```

### grasp.connect(containerId)

Connect to an existing container by ID. If the container is sleeping, it will be awakened.

<ParamField body="containerId" type="string" required>
  The ID of the container to connect to
</ParamField>

**Returns:** Promise\<GraspContainer>

**Example:**

```javascript theme={null}
const containerId = 'existing-container-id';
const container = await grasp.connect(containerId);

console.log('Connected to:', container.id);
```

### GraspContainer

The container object returned by `grasp.create()` and `grasp.connect()`.

**Properties:**

<ParamField body="id" type="string">
  Unique container identifier
</ParamField>

<ParamField body="status" type="string">
  Container status
</ParamField>

<ParamField body="createdAt" type="string">
  ISO timestamp of creation
</ParamField>

<ParamField body="browser" type="GraspBrowserSession">
  Browser session details
</ParamField>

**Methods:**

#### container.shutdown()

Shut down and clean up the container.

**Returns:** Promise\<void>

**Example:**

```javascript theme={null}
await container.shutdown();
```

### GraspBrowserSession

Browser session details associated with a container.

**Properties:**

<ParamField body="wsEndpoint" type="string">
  Chrome DevTools Protocol WebSocket endpoint
</ParamField>

<ParamField body="liveURL" type="string">
  Live view URL for observing the browser
</ParamField>

**Example:**

```javascript theme={null}
console.log('CDP endpoint:', container.browser.wsEndpoint);
console.log('Live view:', container.browser.liveURL);
```

## Type Definitions

### TProxySettings

```typescript theme={null}
type TProxySettings = {
  enabled: boolean;
  type: 'mobile' | 'residential' | 'isp' | 'datacenter' | 'custom';
  country?: string;  // ISO 3166 country code (e.g., 'US')
  state?: string;    // State code (e.g., 'CA')
  city?: string;     // City name
};
```

### TBrowserSettings

```typescript theme={null}
type TBrowserSettings = {
  // Browser settings - not yet implemented
};
```

### TTerminalSettings

```typescript theme={null}
type TTerminalSettings = {
  // Terminal settings - not yet implemented
};
```

### TFileSystemSettings

```typescript theme={null}
type TFileSystemSettings = {
  // Filesystem settings - not yet implemented
};
```

## Environment Variables

* `GRASP_API_KEY` - Default API key (recommended)

## Error Handling

```javascript theme={null}
try {
  const container = await grasp.create();
  // Use container
  await container.shutdown();
} catch (error) {
  console.error('Failed to create container:', error.message);
  if (error.status) {
    console.error('HTTP status:', error.status);
  }
}
```

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

```typescript theme={null}
import { Grasp, type GraspCreateOptions, type GraspContainer } from '@getgrasp/sdk';

const options: GraspCreateOptions = {
  idleTimeout: 60000,
  proxy: {
    enabled: true,
    type: 'residential',
    country: 'US'
  }
};

const grasp = new Grasp({ apiKey: process.env.GRASP_API_KEY });
const container: GraspContainer = await grasp.create(options);
```

## Complete Example with Playwright

```javascript theme={null}
import { Grasp } from '@getgrasp/sdk';
import { chromium } from 'playwright';

const grasp = new Grasp();

// Create container
const container = await grasp.create({
  idleTimeout: 300000  // 5 minutes
});

// Connect Playwright to cloud browser
const browser = await chromium.connectOverCDP(container.browser.wsEndpoint);
const page = await browser.newPage();

// Perform automation
await page.goto('https://news.ycombinator.com');
const headlines = await page.$$eval('.titleline > a', links =>
  links.slice(0, 5).map(link => link.textContent?.trim())
);
console.log('Top stories:', headlines);

// Clean up
await browser.close();
await container.shutdown();
```

## Reconnecting to Containers

Save the container ID and reconnect later:

```javascript theme={null}
// First session - create and save ID
const container = await grasp.create();
const containerId = container.id;
console.log('Container ID:', containerId);
// Save containerId to database or file

// Later session - reconnect
const grasp = new Grasp();
const container = await grasp.connect(containerId);
console.log('Reconnected to:', container.id);
```