sandstormapp 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Superstorm, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# ads.dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+npm install ads.dev
+```
+
+```ts
+import { Sandstorm } from 'ads.dev'
+
+const sandstorm = new Sandstorm()
+
+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
+
+`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: process.env.SANDSTORM_API_KEY,
+  brand: '6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f',
+  baseUrl: 'https://ads.dev',
+  maxRetries: 2,
+  timeoutMs: 60_000,
+})
+```
+
+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.
+
+## Generations
+
+`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 still = await sandstorm.generations.run('nano-banana-2-lite', { prompt: 'Two lemons in a blue bowl' })
+
+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',
+})
+```
+
+Every media input takes an asset id (`asset_…`) or a public https URL, so the output of one generation goes straight into the next.
+
+For work that runs long, queue it and come back to it, or take a webhook:
+
+```ts
+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)
+
+await sandstorm.generations.get(queued.id)
+await sandstorm.generations.cancel(queued.id)
+```
+
+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
+await sandstorm.generations.create('nano-banana-pro', input, { idempotencyKey: 'campaign-42-hero' })
+```
+
+## Lists
+
+Every list answers one page when awaited and walks every page when iterated:
+
+```ts
+const page = await sandstorm.generations.list({ status: 'succeeded', limit: 50 })
+
+for await (const asset of sandstorm.assets.list({ type: 'image' })) console.log(asset.id, asset.url)
+```
+
+## Everything else
+
+```ts
+await sandstorm.models.list({ type: 'video' })
+await sandstorm.models.get('nano-banana-pro/edit')
+
+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 })
+
+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')
+```
+
+## Webhooks
+
+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
+import { verifyWebhook } from 'ads.dev'
+
+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)
+```
+
+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 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 'ads.dev'
+
+try {
+  await sandstorm.generations.create('nano-banana-pro', { prompt: 'A mug on a bench' })
+} catch (error) {
+  if (error instanceof SandstormError && error.code === 'insufficient_credits') console.log('Add credits in Sandstorm')
+}
+```
+
+## Developing
+
+`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

@@ -0,0 +1,139 @@
+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 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 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 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 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;
+    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 {};

package/dist/index.js

@@ -0,0 +1,194 @@
+export class SandstormError extends Error {
+    name = 'SandstormError';
+    status;
+    type;
+    code;
+    param;
+    requestId;
+    constructor(status, refusal) {
+        super(refusal.message);
+        this.status = status;
+        this.type = refusal.type;
+        this.code = refusal.code;
+        this.param = refusal.param;
+        this.requestId = refusal.request_id;
+    }
+}
+export class GenerationFailed extends Error {
+    name = 'GenerationFailed';
+    generation;
+    constructor(generation) {
+        super(generation.error?.message ?? `${generation.id} was ${generation.status}`);
+        this.generation = generation;
+    }
+}
+const BASE_URL = 'https://ads.dev';
+const LONGEST_WAIT_S = 60;
+const RUN_TIMEOUT_MS = 60 * 60_000;
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+const FINISHED = new Set(['succeeded', 'failed', 'canceled']);
+export const isFinished = (generation) => FINISHED.has(generation.status);
+const environment = (name) => globalThis.process?.env?.[name];
+export class Page {
+    #read;
+    constructor(read) {
+        this.#read = read;
+    }
+    then(fulfilled, rejected) {
+        return this.#read(undefined).then(fulfilled, rejected);
+    }
+    async *[Symbol.asyncIterator]() {
+        for (let cursor;;) {
+            const page = await this.#read(cursor);
+            yield* page.data;
+            if (!page.has_more || page.next_cursor === null)
+                return;
+            cursor = page.next_cursor;
+        }
+    }
+}
+export class Sandstorm {
+    #baseUrl;
+    #headers;
+    #maxRetries;
+    #timeoutMs;
+    #fetch;
+    constructor({ apiKey = environment('SANDSTORM_API_KEY'), baseUrl = environment('SANDSTORM_API_URL') ?? BASE_URL, brand, maxRetries = 2, timeoutMs = 60_000, fetch: fetcher = (input, init) => fetch(input, init), } = {}) {
+        this.#baseUrl = baseUrl.replace(/\/+$/, '');
+        if (apiKey === undefined || apiKey === '') {
+            throw new Error(`Pass apiKey or set SANDSTORM_API_KEY. To make a key: curl -fsSL ${this.#baseUrl}/login.mjs -o sandstorm-login.mjs && node sandstorm-login.mjs`);
+        }
+        this.#headers = { authorization: `Bearer ${apiKey}`, ...(brand === undefined ? {} : { 'sandstorm-brand': brand }) };
+        this.#maxRetries = maxRetries;
+        this.#timeoutMs = timeoutMs;
+        this.#fetch = fetcher;
+    }
+    generations = {
+        create: (model, input, { webhookUrl, wait, idempotencyKey = crypto.randomUUID() } = {}) => this.#send({
+            method: 'POST',
+            path: '/v1/generations',
+            body: { model, input, ...(webhookUrl === undefined ? {} : { webhook_url: webhookUrl }) },
+            ...(wait === undefined ? {} : { wait }),
+            idempotencyKey,
+        }),
+        get: (id, { wait } = {}) => this.#send({ method: 'GET', path: `/v1/generations/${encodeURIComponent(id)}`, ...(wait === undefined ? {} : { wait }) }),
+        wait: async (id, { timeoutMs = RUN_TIMEOUT_MS } = {}) => {
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                const left = Math.ceil((deadline - Date.now()) / 1000);
+                const generation = await this.generations.get(id, { wait: Math.max(1, Math.min(LONGEST_WAIT_S, left)) });
+                if (isFinished(generation))
+                    return generation;
+                if (left <= 0)
+                    throw new Error(`${id} did not finish within ${timeoutMs} ms; it is still ${generation.status}`);
+            }
+        },
+        run: async (model, input, { timeoutMs, ...options } = {}) => {
+            const created = await this.generations.create(model, input, { ...options, wait: LONGEST_WAIT_S });
+            const generation = isFinished(created) ? created : await this.generations.wait(created.id, timeoutMs === undefined ? {} : { timeoutMs });
+            if (generation.status !== 'succeeded')
+                throw new GenerationFailed(generation);
+            return generation;
+        },
+        cancel: (id) => this.#send({ method: 'POST', path: `/v1/generations/${encodeURIComponent(id)}/cancel` }),
+        list: (params = {}) => this.#list('/v1/generations', params),
+    };
+    models = {
+        list: (params = {}) => this.#list('/v1/models', params),
+        get: (id) => this.#send({ method: 'GET', path: `/v1/models/${encodeURIComponent(id)}` }),
+    };
+    assets = {
+        list: (params = {}) => this.#list('/v1/assets', params),
+        get: (id) => this.#send({ method: 'GET', path: `/v1/assets/${encodeURIComponent(id)}` }),
+        import: (url, { name, idempotencyKey = crypto.randomUUID() } = {}) => this.#send({ method: 'POST', path: '/v1/assets', body: { url, ...(name === undefined ? {} : { name }) }, idempotencyKey }),
+    };
+    brand = {
+        get: () => this.#send({ method: 'GET', path: '/v1/brand' }),
+    };
+    offers = {
+        list: (params = {}) => this.#list('/v1/offers', params),
+        get: (id) => this.#send({ method: 'GET', path: `/v1/offers/${encodeURIComponent(id)}` }),
+    };
+    characters = {
+        list: (params = {}) => this.#list('/v1/characters', params),
+    };
+    voices = {
+        list: (params = {}) => this.#list('/v1/voices', params),
+    };
+    advertisers = {
+        list: (params) => this.#list('/v1/advertisers', params),
+    };
+    ads = {
+        list: (params = {}) => this.#list('/v1/ads', params),
+        get: (id) => this.#send({ method: 'GET', path: `/v1/ads/${encodeURIComponent(id)}` }),
+    };
+    webhooks = {
+        secret: async () => (await this.#send({ method: 'GET', path: '/v1/webhooks/secret' })).secret,
+    };
+    #list(path, params) {
+        return new Page((cursor) => this.#send({ method: 'GET', path, query: cursor === undefined ? params : { ...params, cursor } }));
+    }
+    async #send(request) {
+        const url = new URL(this.#baseUrl + request.path);
+        for (const [name, value] of Object.entries(request.query ?? {}))
+            if (value !== undefined)
+                url.searchParams.set(name, String(value));
+        const headers = {
+            ...this.#headers,
+            ...(request.body === undefined ? {} : { 'content-type': 'application/json' }),
+            ...(request.wait === undefined ? {} : { prefer: `wait=${request.wait}` }),
+            ...(request.idempotencyKey === undefined ? {} : { 'idempotency-key': request.idempotencyKey }),
+        };
+        const body = request.body === undefined ? null : JSON.stringify(request.body);
+        const send = this.#fetch;
+        for (let attempt = 0;; attempt++) {
+            const timeout = AbortSignal.timeout(this.#timeoutMs + (request.wait ?? 0) * 1000);
+            const answered = await send(url, { method: request.method, headers, body, signal: timeout }).catch((error) => error instanceof Error ? error : new Error(String(error)));
+            if (answered instanceof Response && answered.ok && isJson(answered))
+                return (await answered.json());
+            if (answered instanceof Response && answered.ok)
+                throw await notTheApi(answered, url.origin);
+            const retryable = answered instanceof Error || RETRYABLE.has(answered.status);
+            if (!retryable || attempt >= this.#maxRetries)
+                throw answered instanceof Error ? answered : await refusalOf(answered, url.origin);
+            await new Promise((resolve) => setTimeout(resolve, delayOf(attempt, answered instanceof Response ? answered : undefined)));
+        }
+    }
+}
+function delayOf(attempt, response) {
+    const after = Number(response?.headers.get('retry-after'));
+    if (Number.isFinite(after) && after > 0)
+        return after * 1000;
+    return Math.min(8_000, 500 * 2 ** attempt) * (0.75 + Math.random() / 2);
+}
+const isJson = (response) => response.headers.get('content-type')?.includes('json') === true;
+async function notTheApi(response, origin) {
+    await response.body?.cancel();
+    return new SandstormError(response.status, {
+        type: 'api_error',
+        code: 'not_the_api',
+        message: `${origin} answered ${response.status} with ${response.headers.get('content-type') ?? 'no content type'} instead of the API's JSON. If ${origin} is not the Sandstorm API, pass baseUrl or set SANDSTORM_API_URL.`,
+    });
+}
+async function refusalOf(response, origin) {
+    if (!isJson(response))
+        return notTheApi(response, origin);
+    return new SandstormError(response.status, (await response.json()).error);
+}
+const HEX = /^[0-9a-f]{64}$/;
+export async function verifyWebhook({ secret, body, signature, toleranceSeconds = 300, now = Date.now() }) {
+    const parts = new Map((signature ?? '').split(',').map((part) => [part.slice(0, part.indexOf('=')), part.slice(part.indexOf('=') + 1)]));
+    const timestamp = Number(parts.get('t'));
+    const given = parts.get('v1') ?? '';
+    if (!Number.isInteger(timestamp) || !HEX.test(given))
+        throw new Error('The Sandstorm-Signature header is missing or malformed.');
+    if (Math.abs(now / 1000 - timestamp) > toleranceSeconds)
+        throw new Error('The webhook is older than the tolerance; refuse it as a possible replay.');
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const bytes = Uint8Array.from(given.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16));
+    if (!(await crypto.subtle.verify('HMAC', key, bytes, encoder.encode(`${timestamp}.${body}`)))) {
+        throw new Error('The webhook signature does not match; it was not sent by Sandstorm with this secret.');
+    }
+    return JSON.parse(body);
+}