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

# TypeScript SDK

> Typed calls for every capability, jobs, retries and webhook verification.

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

```ts theme={null}
import { Pramaan } from "@pramaan/sdk";

const p = new Pramaan({ apiKey: process.env.PRAMAAN_API_KEY! });
```

The SDK uses only `fetch` and Web Crypto, so it works in Node, Next.js, Bun, Deno, Workers,
mobile apps and Tauri. Keep the API key on a server.

## Calling capabilities

| Method | Returns |
| - | - |
| `p.web.search(input)` | Typed sugar for every capability id (`ads.ad-sets.list` becomes `p.ads.adSets.list`). |
| `p.run(id, input, { idempotencyKey })` | The result for sync capabilities, a `Job` for async ones. |
| `p.call(id, input)` | The result; waits for async jobs and throws if they fail. |
| `p.info(id)` | Effect class, mode and whether it needs a connection. Offline, no request. |
| `p.capabilities.list()`, `p.capabilities.get(id)` | The live catalog, with prices and JSON Schemas. |
| `p.capabilities.describeAll({ namespace? })` | Many capabilities with their JSON Schemas at once, 200 per request, instead of one `get` each. `namespace: "web"` keeps it to the ids that start with `web.`. |
| `p.capabilities.estimate(id, input, options?)` | What a request would cost at most, without running it. See [prices and limits](https://docs.pramaan.dev/guides/pricing.md). |

Every call takes the same options as its last argument: `idempotencyKey`, `maxPriceMicro` (the
most this call may be priced at) and `secondOpinion` (ask one more source on a weak answer).

Request and result types are generated from the API's OpenAPI document, so your editor completes
fields and checks them.

## Jobs

| Method | Does |
| - | - |
| `p.jobs.get(id)` | Current status. |
| `p.jobs.wait(id, { timeoutMs })` | Polls every 2 seconds or more, with backoff, until the job ends. |
| `p.jobs.cancel(id)` | Cancels a running job. |

## Errors and retries

Errors are `PramaanError` (see [errors](https://docs.pramaan.dev/guides/errors.md)). Read-only calls are retried on `429`,
`5xx` and network failures, up to `maxRetries` times (default 2). Calls with an external effect
are never retried automatically.

## Options

| Option | Default |
| - | - |
| `apiKey` | Required. |
| `baseUrl` | `https://api.pramaan.dev` |
| `maxRetries` | `2` |
| `fetch` | The global `fetch`. |

## Webhooks

`verifyWebhook(secret, headers, rawBody)` checks a webhook signature and returns the event. See
[webhooks](https://docs.pramaan.dev/guides/webhooks.md).

## Other languages

Python and other SDKs are generated from the same OpenAPI document and add the same helpers: job
waiting, webhook verification, the retry rules and one error type. Until then, any HTTP client
works; see the **API reference** tab.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.