TypeScript SDK - Pramaan

npm install @pramaan/sdk

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.

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). 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.

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.