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

# JavaScript SDK Overview

> Overview of the Uplink JavaScript SDK for mobile browser automation

The Uplink JavaScript SDK provides a Puppeteer/Playwright-like API for controlling mobile browsers remotely. This reference covers all available classes, methods, and types.

<Info>
  **Key terminology:**

  * **Device**: A physical iOS or Android device
  * **Worker**: A worker created using the native Uplink SDK (a device can create multiple workers)
  * **Address**: A hex-encoded identifier used to reference specific workers
</Info>

## Installation

```bash theme={null}
npm install @uplink-code/uplink
```

### Optional: AI Automation

For AI-powered browser automation with natural language instructions:

```bash theme={null}
npm install @uplink-code/ai
```

See the [AI Automation](/api-reference/ai/overview) section for details.

## Quick example

```typescript theme={null}
import uplink from '@uplink-code/uplink'

const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)
const browser = await client.launch()
const page = await browser.newPage()

await page.goto('https://example.com')
const title = await page.evaluate(() => document.title)

await browser.close()
await client.close()
```

## API structure

The SDK is organized into four main classes, plus an optional AI automation package:

<CardGroup cols={2}>
  <Card title="Client" icon="plug" href="/api-reference/client">
    Main entry point for connecting to Uplink and managing workers
  </Card>

  <Card title="ClientWorker" icon="mobile" href="/api-reference/client-worker">
    Represents a worker (Uplink SDK running on a physical device)
  </Card>

  <Card title="Browser" icon="browser" href="/api-reference/browser">
    Browser instance running on a device
  </Card>

  <Card title="Page" icon="window-maximize" href="/api-reference/page/overview">
    Browser tab/window with automation methods
  </Card>

  <Card title="AI Automation" icon="wand-magic-sparkles" href="/api-reference/ai/overview">
    Optional: Natural language actions and data extraction
  </Card>
</CardGroup>

## TypeScript support

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

```typescript theme={null}
import type { Page, Cookie, Request } from '@uplink-code/uplink/page/types'
import type { Client } from '@uplink-code/uplink/client/types'
import type { Browser } from '@uplink-code/uplink/browser/types'
import type { Agent, ActResult, ExtractResult } from '@uplink-code/ai'
```

## Error handling

All async methods can throw errors. Always use try-catch for robust automation:

```typescript theme={null}
try {
  await page.goto('https://example.com')
} catch (error) {
  console.error('Navigation failed:', error)
}
```

## Common patterns

### Connection and cleanup

```typescript theme={null}
const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)

try {
  const browser = await client.launch()
  const page = await browser.newPage()

  // Your automation here

} finally {
  // Always clean up
  await page.close()
  await browser.close()
  await client.close()
}
```

### Waiting for workers

```typescript theme={null}
const session = await uplink.session('<project-api-key>', {
  include: { ecdsa: true, ecdh: true }
})
const client = await uplink.client.fromSession(session)

// Check currently connected workers
const workers = client.workers()
console.log(`${workers.length} workers connected`)

// Or handle workers as they connect
client.on('worker-connected', async (worker) => {
  console.log('Worker connected:', worker.address)
  const browser = await worker.launch()
  // ... automation
})
```

### Multi-page automation

```typescript theme={null}
const browser = await client.launch()

const page1 = await browser.newPage()
const page2 = await browser.newPage()

await Promise.all([
  page1.goto('https://example.com'),
  page2.goto('https://google.com')
])
```

## Next steps

<CardGroup cols={2}>
  <Card title="Client API" icon="plug" href="/api-reference/client">
    Connection and device management
  </Card>

  <Card title="Page API" icon="window-maximize" href="/api-reference/page/overview">
    Browser automation methods
  </Card>
</CardGroup>