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

# JavaScript SDK

> Use Rako from Node.js, Deno, or Bun.

# JavaScript / TypeScript SDK

Use the JavaScript SDK when you want full control from Node.js, Deno, or Bun.

<Card title="Run the local JavaScript example" href="https://github.com/rakohq/developer-docs/tree/main/examples/js-sdk-basic">
  Try the SDK against the mock AAP server with `AAP_API_KEY=aap_demo_key` and fake checkout data.
</Card>

```bash Install theme={null}
npm install @rakohq/sdk
```

```ts quickstart.ts theme={null}
import { AAP } from '@rakohq/sdk';

const aap = new AAP({ apiKey: 'your-api-key' });

// 1. Search for offers
const { offers, sessionId } = await aap.search({
  vertical: 'sim',
  maxPrice: 10,
  contractMonths: 0,
});

// 2. Recommend an offer (records attribution)
const rec = await aap.recommend({
  sessionId,
  offerId: offers[0].id,
  context: 'User asked for cheap SIM with no contract',
});

// 3. Initiate checkout
const checkout = await aap.checkout({
  sessionId,
  recommendationId: rec.recommendationId,
});
```

## Client

### `new AAP(config)`

| Option    | Type   | Required | Default               |
| --------- | ------ | -------- | --------------------- |
| `apiKey`  | string | Yes      | —                     |
| `baseUrl` | string | No       | `https://api.rako.sh` |

## Methods

### `aap.search(options)`

Returns matching offers and a session ID.

| Option           | Type   | Description                                                    |
| ---------------- | ------ | -------------------------------------------------------------- |
| `vertical`       | string | `sim`, `broadband`, `energy`, `flights`, `hotels`, `insurance` |
| `provider`       | string | Filter by provider name                                        |
| `maxPrice`       | number | Maximum price                                                  |
| `minDataGb`      | number | Minimum data allowance for SIM offers                          |
| `contractMonths` | number | Contract length, where `0` means rolling                       |

### `aap.recommend(options)`

Record a recommendation. This is the attribution event.

| Option      | Type   | Description                    |
| ----------- | ------ | ------------------------------ |
| `sessionId` | string | Session from `search()`        |
| `offerId`   | string | Offer to recommend             |
| `context`   | string | Why this offer was recommended |

### `aap.checkout(options)`

Initiate checkout for a recommended offer.

| Option             | Type   | Description                        |
| ------------------ | ------ | ---------------------------------- |
| `sessionId`        | string | Session from `search()`            |
| `recommendationId` | string | Recommendation from `recommend()`  |
| `userDetails`      | object | Optional user details for checkout |

### `aap.getSession(sessionId)`

Get session details including recommendations and conversions.

### `aap.verifyCode(code)`

Verify an AAP Code is authentic.

## Mock conversion learning

The runnable SDK example reaches a mock checkout URL. To understand why checkout-link creation is separate from conversion recording, see [Mock Conversion Artifact](/guides/mock-conversion).

<CardGroup cols={2}>
  <Card title="npm" href="https://www.npmjs.com/package/@rakohq/sdk" />

  <Card title="GitHub" href="https://github.com/rakohq/aap-js" />
</CardGroup>