@sandstormapp/sdk 0.1.0 → 1.0.0

package/README.md

@@ -1,170 +1,137 @@
-# @sandstormapp/sdk
+# ads.dev
 
-Sandstorm's public API as a typed client for Node and edge runtimes: one method per tool in the catalogue, typed from the tool's own JSON Schema, and the tasks those calls start. It is generated from the API's OpenAPI document and depends on nothing at runtime but `fetch`.
+The [ads.dev](https://ads.dev) API for Node, Deno, Bun and edge runtimes: image, video and audio generation with 34 models on your brand, the brand kit and library, and the ads your competitors run. Every model's input is typed, so the model you name decides what `input` takes.
+
+It is published as `ads.dev`, `adsdotdev`, `sandstormapp` and `@sandstormapp/sdk`, the same package under four names, and needs nothing at runtime but `fetch` and Web Crypto.
 
 ```bash
-yarn add @sandstormapp/sdk
+npm install ads.dev
 ```
 
 ```ts
-import { Sandstorm } from '@sandstormapp/sdk'
+import { Sandstorm } from 'ads.dev'
 
-const sandstorm = new Sandstorm({ apiKey: process.env.SANDSTORM_API_KEY })
+const sandstorm = new Sandstorm()
 
-const task = await sandstorm.tools.generate_image_nano_banana_pro(
-  { prompt: 'A ceramic mug on a sunlit bench, steam rising, morning light', asset_name: 'Sunlit Mug' },
-  { wait: 120 },
-)
-if (task.status === 'succeeded') console.log(task.files)
-```
-
-```bash
-curl -X POST https://agent.sandstormapp.com/v1/tools/generate_image_nano_banana_pro \
-  -H "Authorization: Bearer $SANDSTORM_API_KEY" \
-  -H 'Content-Type: application/json' \
-  -H 'Prefer: wait=120' \
-  -d '{"prompt":"A ceramic mug on a sunlit bench, steam rising, morning light","asset_name":"Sunlit Mug"}'
+const generation = await sandstorm.generations.run('nano-banana-pro', {
+  prompt: 'A ceramic mug on a sunlit bench, steam rising',
+  aspect_ratio: '4:5',
+})
+console.log(generation.output[0]?.url)
 ```
 
 ## A key
 
-Settings → API keys mints a key, `sk_live_…`, shown once. A key works on one brand of your organization: the brand it was made on, or the one you name.
+`new Sandstorm()` reads `SANDSTORM_API_KEY`. Make a key in Sandstorm under Settings → API keys, or in one command, which signs you in in the browser and writes the key to `.env`:
+
+```bash
+curl -fsSL https://ads.dev/login.mjs -o sandstorm-login.mjs && node sandstorm-login.mjs
+```
 
 ```ts
-new Sandstorm({ apiKey, brand: '2f7fa2e7-c931-47b2-a66a-f1393233f2b3' })
+new Sandstorm({
+  apiKey: process.env.SANDSTORM_API_KEY,
+  brand: '6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f',
+  baseUrl: 'https://ads.dev',
+  maxRetries: 2,
+  timeoutMs: 60_000,
+})
 ```
 
-`brand` is sent as `x-sandstorm-brand` on every request. `baseUrl` points the client somewhere other than `https://agent.sandstormapp.com`, such as an API running locally.
+A key acts on the brand it was made on; `brand` names another brand of the same organization. `baseUrl` defaults to `SANDSTORM_API_URL`, then `https://ads.dev`. Keep the key on your server: anyone who holds it spends your credits.
 
-## Calling a tool
+## Generations
 
-Every tool is a method on `sandstorm.tools`, named as the catalogue names it, taking the body the API holds it to. A call starts a task and answers its id at once:
+`run` makes a generation and answers it once it has finished, holding each request on the API with `Prefer: wait` rather than polling. A generation that fails or is canceled throws `GenerationFailed`, which carries it.
 
 ```ts
-const started = await sandstorm.tools.search_assets({ types: ['image'], limit: 10 })
-// { task_id: '…', status: 'running' }
-```
+const still = await sandstorm.generations.run('nano-banana-2-lite', { prompt: 'Two lemons in a blue bowl' })
 
-```bash
-curl -X POST https://agent.sandstormapp.com/v1/tools/search_assets \
-  -H "Authorization: Bearer $SANDSTORM_API_KEY" -H 'Content-Type: application/json' \
-  -d '{"types":["image"],"limit":10}'
+const clip = await sandstorm.generations.run('seedance-2.5/image-to-video', {
+  start_image: still.output[0]!.id,
+  prompt: 'Slow push in as the light warms',
+  resolution: '720p',
+})
 ```
 
-With `wait`, the API holds the request up to that many seconds (at most 200) and answers the finished task, or the started shape when the time runs out:
-
-```ts
-const answer = await sandstorm.tools.search_assets({ types: ['image'], limit: 10 }, { wait: 30 })
-if (answer.status === 'running') console.log('still running', answer.task_id)
-else console.log(answer.result)
-```
+Every media input takes an asset id (`asset_…`) or a public https URL, so the output of one generation goes straight into the next.
 
-A tool that asks the person before it runs in the app takes `confirm: true` here, since nobody is there to ask; its input type requires it, and the API refuses the call with 403 without it:
+For work that runs long, queue it and come back to it, or take a webhook:
 
 ```ts
-await sandstorm.tools.revoke_asset_share({ slug: 'summer-drop', confirm: true })
-```
+const queued = await sandstorm.generations.create('kling-3-pro/image-to-video', input, { webhookUrl: 'https://yourapp.com/hooks/sandstorm' })
+const finished = await sandstorm.generations.wait(queued.id)
 
-```bash
-curl -X POST https://agent.sandstormapp.com/v1/tools/revoke_asset_share \
-  -H "Authorization: Bearer $SANDSTORM_API_KEY" -H 'Content-Type: application/json' \
-  -d '{"slug":"summer-drop","confirm":true}'
+await sandstorm.generations.get(queued.id)
+await sandstorm.generations.cancel(queued.id)
 ```
 
-The catalogue itself, every tool this key can call with its schema, hints and whether it asks first:
+A generation is `queued`, then `running`, then `succeeded`, `failed` or `canceled`; `credits` is what it was charged once it finished, and a failed one is free. Cancelling a queued generation costs nothing; one the model has already started stops where the model allows it, and otherwise finishes and is charged.
+
+`create` sends an `Idempotency-Key` with every call and keeps it across its retries, so a retry never makes a second generation. Pass your own to make a call safe across process restarts:
 
 ```ts
-const { tools } = await sandstorm.catalogue()
+await sandstorm.generations.create('nano-banana-pro', input, { idempotencyKey: 'campaign-42-hero' })
 ```
 
-```bash
-curl https://agent.sandstormapp.com/v1/tools -H "Authorization: Bearer $SANDSTORM_API_KEY"
-```
+## Lists
 
-## Following a task
+Every list answers one page when awaited and walks every page when iterated:
 
 ```ts
-const task = await sandstorm.tasks.get(taskId)
-```
+const page = await sandstorm.generations.list({ status: 'succeeded', limit: 50 })
 
-```bash
-curl https://agent.sandstormapp.com/v1/tasks/$TASK_ID -H "Authorization: Bearer $SANDSTORM_API_KEY"
+for await (const asset of sandstorm.assets.list({ type: 'image' })) console.log(asset.id, asset.url)
 ```
 
-A task is `{ task_id, tool, status, error, started_at, finished_at, result?, files? }`, where `status` is `running`, `succeeded`, `failed` or `cancelled`, `result` is the tool's own JSON once it succeeded and `files` are the files it made or showed, each with a `ref` other tools take and a `url` that keeps working. A task the API has only just started answers `{ task_id, status: 'running' }` until it is on record.
-
-`tasks.wait` polls that route every two seconds until the status leaves `running`, and resolves to the task with its result or error:
+## Everything else
 
 ```ts
-const finished = await sandstorm.tasks.wait(taskId)
-if (finished.status === 'failed') console.error(finished.error)
-```
+await sandstorm.models.list({ type: 'video' })
+await sandstorm.models.get('nano-banana-pro/edit')
 
-The twenty most recent calls of this key on its brand, newest first, without their results:
+await sandstorm.brand.get()
+await sandstorm.assets.import('https://yourcdn.com/hero.png', { name: 'Hero shot' })
+await sandstorm.assets.get('asset_9c1e77aa')
+await sandstorm.offers.list({ query: 'cold brew' })
+await sandstorm.offers.get('offer_0f8e2b6a4c1d4e7f9a3b5c7d9e1f2a4b')
+await sandstorm.characters.list({ kind: 'subject' })
+await sandstorm.voices.list({ use_case: 'advertisement', limit: 5 })
 
-```ts
-const { tasks } = await sandstorm.tasks.list()
+const [advertiser] = (await sandstorm.advertisers.list({ query: 'Liquid Death' })).data
+await sandstorm.ads.list({ advertiser: advertiser!.id, status: 'active' })
+await sandstorm.ads.get('ad_5e1c9a3b')
 ```
 
-```bash
-curl https://agent.sandstormapp.com/v1/tasks -H "Authorization: Bearer $SANDSTORM_API_KEY"
-```
+## Webhooks
 
-Stopping one that still runs; whatever it saved before it stopped stays in the library:
+A generation made with `webhookUrl` is POSTed to it once it finishes, signed in `Sandstorm-Signature`. Verify the raw body before you trust it:
 
 ```ts
-await sandstorm.tasks.stop(taskId)
-```
+import { verifyWebhook } from 'ads.dev'
 
-```bash
-curl -X POST https://agent.sandstormapp.com/v1/tasks/$TASK_ID/stop -H "Authorization: Bearer $SANDSTORM_API_KEY"
+const secret = await sandstorm.webhooks.secret()
+
+const event = await verifyWebhook({ secret, body: await request.text(), signature: request.headers.get('sandstorm-signature') })
+if (event.type === 'generation.succeeded') console.log(event.data.output)
 ```
 
-## Refusals
+It refuses a body that was changed, a signature from another secret and a delivery older than five minutes. An event's `id` is the same on every retry of it, so a handler can skip one it has seen.
+
+## Errors
 
-A response the API refuses throws a `SandstormError` with the HTTP `status`, the API's `code` and its message:
+A refusal throws `SandstormError` with the HTTP `status`, its `type` and `code`, the `param` at fault and the `requestId` to quote to support. Requests Sandstorm could not take (408, 429, 500, 502, 503, 504) and network failures are retried twice with backoff, after the `Retry-After` the API asks for.
 
 ```ts
-import { SandstormError } from '@sandstormapp/sdk'
+import { SandstormError } from 'ads.dev'
 
 try {
-  await sandstorm.tools.archive_offer({ offer: 'offer:1a2b3c4d' })
+  await sandstorm.generations.create('nano-banana-pro', { prompt: 'A mug on a bench' })
 } catch (error) {
-  if (error instanceof SandstormError && error.code === 'forbidden') console.log(error.message)
+  if (error instanceof SandstormError && error.code === 'insufficient_credits') console.log('Add credits in Sandstorm')
 }
 ```
 
-| status | code | when |
-| --- | --- | --- |
-| 400 | `bad_request` | the body does not match the tool's schema; the message names the mismatch |
-| 401 | `unauthorized` | the bearer is not a live key |
-| 402 | `billing` | the organization cannot run Sandstorm right now |
-| 403 | `forbidden` | the tool asks first and the body did not carry `confirm: true`, or the brand named is not one of the organization's |
-| 404 | `tool_not_found`, `task_not_found` | no such tool for this brand, or no such task |
-| 409 | `task_not_running` | the task to stop has already ended |
-| 429 | `rate_limited` | more than 300 requests in a minute from this key |
-
-An answer that is not the API's, such as one from the edge, throws with its `status`, no `code`, and the text of the answer.
-
-## The generated client
-
-`src/openapi.ts` and `openapi.json` are generated from the API's `GET /v1/openapi.json`, which the API produces from its live tool catalogue, and both are committed, so the package builds without an API. To regenerate:
-
-```bash
-yarn generate https://agent.sandstormapp.com/v1/openapi.json   # from a running API, replacing openapi.json
-yarn generate path/to/openapi.json                                # from a document on disk
-yarn generate                                                     # from the committed openapi.json
-```
-
-`yarn test` fails when the committed `src/openapi.ts` is not what the committed document generates, and a document regenerated from the API shows every catalogue change as a diff of `openapi.json`. `agent/README.md` says how to run the API locally; its document is at `http://localhost:8787/v1/openapi.json`.
-
 ## Developing
 
-```bash
-yarn install
-yarn typecheck   # src, test and scripts
-yarn test        # the client against a stubbed fetch, and the stale-output check
-yarn build       # dist/, which is what the package ships
-```
-
-Node 22.18 or newer runs `scripts/generate.ts` as it is.
+`openapi.json` is the API's own document, held to what the API serves by the agent project's tests; `yarn generate` turns it into `src/openapi.ts`, and `yarn ci:test` fails when the two disagree. `yarn release` publishes the build as `ads.dev`, `adsdotdev`, `sandstormapp` and `@sandstormapp/sdk`.

package/dist/index.d.ts

@@ -1,47 +1,139 @@
-import { toolNames, type components, type paths } from './openapi.ts';
-export { toolNames };
-export type Task = components['schemas']['Task'];
-export type Started = components['schemas']['Started'];
-export type Tool = components['schemas']['Tool'];
-export type Finished = Task & {
-    readonly status: Exclude<Task['status'], 'running'>;
+import type { components, operations } from './openapi.ts';
+type Schemas = components['schemas'];
+export type Generation = Schemas['Generation'];
+export type GenerationEvent = Schemas['GenerationEvent'];
+export type Model = Schemas['Model'];
+export type Asset = Schemas['Asset'];
+export type LibraryAsset = Schemas['LibraryAsset'];
+export type Brand = Schemas['Brand'];
+export type OfferSummary = Schemas['OfferSummary'];
+export type Offer = Schemas['Offer'];
+export type Character = Schemas['Character'];
+export type Voice = Schemas['Voice'];
+export type Advertiser = Schemas['Advertiser'];
+export type AdSummary = Schemas['AdSummary'];
+export type Ad = Schemas['Ad'];
+type CreateGeneration = Schemas['CreateGeneration'];
+type Refusal = Schemas['Error']['error'];
+export type ModelId = CreateGeneration['model'];
+export type ModelInput<Id extends ModelId> = Extract<CreateGeneration, {
+    model: Id;
+}>['input'];
+type Query<Operation extends keyof operations> = NonNullable<operations[Operation]['parameters']['query']>;
+type Flag<Value> = [Value] extends ['true' | 'false' | undefined] ? boolean : Value;
+type Params<Operation extends keyof operations> = {
+    readonly [Name in Exclude<keyof Query<Operation>, 'cursor'>]?: Flag<Query<Operation>[Name]>;
 };
-export type ToolName = (typeof toolNames)[number];
-export type ToolInput<Name extends ToolName> = paths[`/v1/tools/${Name}`]['post']['requestBody']['content']['application/json'];
-export type Catalogue = paths['/v1/tools']['get']['responses'][200]['content']['application/json'];
-export type TaskList = paths['/v1/tasks']['get']['responses'][200]['content']['application/json'];
-export type Stopped = paths['/v1/tasks/{taskId}/stop']['post']['responses'][202]['content']['application/json'];
-export interface Wait {
-    readonly wait: number;
-}
-export interface ToolCall<Name extends ToolName> {
-    (input: ToolInput<Name>): Promise<Started>;
-    (input: ToolInput<Name>, options: Wait): Promise<Task | Started>;
-}
-export type Tools = {
-    readonly [Name in ToolName]: ToolCall<Name>;
+export type GenerationParams = Params<'listGenerations'>;
+export type ModelParams = Params<'listModels'>;
+export type AssetParams = Params<'listAssets'>;
+export type OfferParams = Params<'listOffers'>;
+export type CharacterParams = Params<'listCharacters'>;
+export type VoiceParams = Params<'listVoices'>;
+export type AdvertiserParams = Params<'listAdvertisers'> & {
+    readonly query: string;
 };
-export interface Tasks {
-    list(): Promise<TaskList>;
-    get(taskId: string): Promise<Task | Started>;
-    stop(taskId: string): Promise<Stopped>;
-    wait(taskId: string): Promise<Finished>;
+export type AdParams = Params<'listAds'>;
+export interface List<Item> {
+    readonly object: 'list';
+    readonly data: Item[];
+    readonly has_more: boolean;
+    readonly next_cursor: string | null;
 }
 export interface Options {
-    readonly apiKey: string;
-    readonly brand?: string;
+    readonly apiKey?: string;
     readonly baseUrl?: string;
+    readonly brand?: string;
+    readonly maxRetries?: number;
+    readonly timeoutMs?: number;
+    readonly fetch?: typeof fetch;
+}
+export interface CreateOptions {
+    readonly webhookUrl?: string;
+    readonly wait?: number;
+    readonly idempotencyKey?: string;
+}
+export interface WaitOptions {
+    readonly timeoutMs?: number;
 }
 export declare class SandstormError extends Error {
     readonly name = "SandstormError";
     readonly status: number;
-    readonly code: string | undefined;
-    constructor(status: number, code: string | undefined, message: string);
+    readonly type: Refusal['type'];
+    readonly code: string;
+    readonly param: string | undefined;
+    readonly requestId: string | undefined;
+    constructor(status: number, refusal: Omit<Refusal, 'request_id'> & {
+        readonly request_id?: string;
+    });
+}
+export declare class GenerationFailed extends Error {
+    readonly name = "GenerationFailed";
+    readonly generation: Generation;
+    constructor(generation: Generation);
+}
+export declare const isFinished: (generation: Generation) => boolean;
+export declare class Page<Item> implements PromiseLike<List<Item>>, AsyncIterable<Item> {
+    #private;
+    constructor(read: (cursor: string | undefined) => Promise<List<Item>>);
+    then<Fulfilled = List<Item>, Rejected = never>(fulfilled?: ((list: List<Item>) => Fulfilled | PromiseLike<Fulfilled>) | null, rejected?: ((reason: unknown) => Rejected | PromiseLike<Rejected>) | null): Promise<Fulfilled | Rejected>;
+    [Symbol.asyncIterator](): AsyncIterator<Item>;
 }
 export declare class Sandstorm {
     #private;
-    readonly tools: Tools;
-    readonly tasks: Tasks;
-    constructor({ apiKey, brand, baseUrl }: Options);
-    catalogue(): Promise<Catalogue>;
+    constructor({ apiKey, baseUrl, brand, maxRetries, timeoutMs, fetch: fetcher, }?: Options);
+    readonly generations: {
+        create: <Id extends ModelId>(model: Id, input: ModelInput<Id>, { webhookUrl, wait, idempotencyKey }?: CreateOptions) => Promise<Generation>;
+        get: (id: string, { wait }?: {
+            readonly wait?: number;
+        }) => Promise<Generation>;
+        wait: (id: string, { timeoutMs }?: WaitOptions) => Promise<Generation>;
+        run: <Id extends ModelId>(model: Id, input: ModelInput<Id>, { timeoutMs, ...options }?: Omit<CreateOptions, "wait"> & WaitOptions) => Promise<Generation>;
+        cancel: (id: string) => Promise<Generation>;
+        list: (params?: GenerationParams) => Page<Generation>;
+    };
+    readonly models: {
+        list: (params?: ModelParams) => Page<Model>;
+        get: (id: ModelId) => Promise<Model>;
+    };
+    readonly assets: {
+        list: (params?: AssetParams) => Page<LibraryAsset>;
+        get: (id: string) => Promise<Asset>;
+        import: (url: string, { name, idempotencyKey }?: {
+            readonly name?: string;
+            readonly idempotencyKey?: string;
+        }) => Promise<Asset>;
+    };
+    readonly brand: {
+        get: () => Promise<Brand>;
+    };
+    readonly offers: {
+        list: (params?: OfferParams) => Page<OfferSummary>;
+        get: (id: string) => Promise<Offer>;
+    };
+    readonly characters: {
+        list: (params?: CharacterParams) => Page<Character>;
+    };
+    readonly voices: {
+        list: (params?: VoiceParams) => Page<Voice>;
+    };
+    readonly advertisers: {
+        list: (params: AdvertiserParams) => Page<Advertiser>;
+    };
+    readonly ads: {
+        list: (params?: AdParams) => Page<AdSummary>;
+        get: (id: string) => Promise<Ad>;
+    };
+    readonly webhooks: {
+        secret: () => Promise<string>;
+    };
+}
+export interface Delivery {
+    readonly secret: string;
+    readonly body: string;
+    readonly signature: string | null;
+    readonly toleranceSeconds?: number;
+    readonly now?: number;
 }
+export declare function verifyWebhook({ secret, body, signature, toleranceSeconds, now }: Delivery): Promise<GenerationEvent>;
+export {};