@sandstormapp/sdk 0.2.0 → 1.1.0

package/dist/index.js

@@ -1,84 +1,194 @@
-import { toolMethods } from "./openapi.js";
-export { toolMethods };
 export class SandstormError extends Error {
     name = 'SandstormError';
     status;
+    type;
     code;
-    constructor(status, code, message) {
-        super(message);
+    param;
+    requestId;
+    constructor(status, refusal) {
+        super(refusal.message);
         this.status = status;
-        this.code = code;
+        this.type = refusal.type;
+        this.code = refusal.code;
+        this.param = refusal.param;
+        this.requestId = refusal.request_id;
     }
 }
-const BASE_URL = 'https://agent.sandstormapp.com';
-const POLL_MS = 2_000;
-const JSON_BODY = { 'content-type': 'application/json' };
-function refusalOf(text) {
-    try {
-        const body = JSON.parse(text);
-        return typeof body.error === 'string' && typeof body.code === 'string' ? { error: body.error, code: body.code } : undefined;
-    }
-    catch {
-        return undefined;
+export class GenerationFailed extends Error {
+    name = 'GenerationFailed';
+    generation;
+    constructor(generation) {
+        super(generation.error?.message ?? `${generation.id} was ${generation.status}`);
+        this.generation = generation;
     }
 }
-async function refused(response) {
-    const text = await response.text();
-    const refusal = refusalOf(text);
-    return refusal === undefined
-        ? new SandstormError(response.status, undefined, text === '' ? response.statusText : text)
-        : new SandstormError(response.status, refusal.code, refusal.error);
+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;
+        }
+    }
 }
-const finished = (task) => task.status !== 'running';
 export class Sandstorm {
-    tools;
-    tasks;
     #baseUrl;
     #headers;
-    constructor({ apiKey, brand, baseUrl = BASE_URL }) {
-        this.#baseUrl = baseUrl.replace(/\/$/, '');
-        this.#headers = { authorization: `Bearer ${apiKey}`, ...(brand === undefined ? {} : { 'x-sandstorm-brand': brand }) };
-        this.tools = Object.fromEntries(Object.entries(toolMethods).map(([name, method]) => [
-            name,
-            method === 'get'
-                ? (query) => this.#read(name, query)
-                : (input, options) => this.#call(name, input, options),
-        ]));
-        this.tasks = {
-            list: () => this.#send('GET', '/v1/tasks'),
-            get: (taskId) => this.#send('GET', `/v1/tasks/${taskId}`),
-            stop: (taskId) => this.#send('POST', `/v1/tasks/${taskId}/stop`),
-            wait: async (taskId) => {
-                for (;;) {
-                    const task = await this.tasks.get(taskId);
-                    if (finished(task))
-                        return task;
-                    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
-                }
-            },
-        };
+    #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;
     }
-    catalogue() {
-        return this.#send('GET', '/v1/tools');
+    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 } }));
     }
-    #read(name, query = {}) {
-        const search = new URLSearchParams();
-        for (const [key, value] of Object.entries(query)) {
-            for (const each of Array.isArray(value) ? value : [value])
-                if (each !== undefined)
-                    search.append(key, String(each));
+    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)));
         }
-        const asked = search.toString();
-        return this.#send('GET', `/v1/tools/${name}${asked === '' ? '' : `?${asked}`}`);
-    }
-    #call(name, input, options) {
-        const headers = options === undefined ? JSON_BODY : { ...JSON_BODY, prefer: `wait=${options.wait}` };
-        return this.#send('POST', `/v1/tools/${name}`, headers, JSON.stringify(input));
     }
-    async #send(method, path, headers = {}, body = null) {
-        const response = await fetch(this.#baseUrl + path, { method, headers: { ...this.#headers, ...headers }, body });
-        if (!response.ok)
-            throw await refused(response);
-        return response.json();
+}
+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);
 }