@sandstormapp/sdk 0.0.0-stage → 0.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,170 @@
-# Temporary Holding Version
+# @sandstormapp/sdk
 
-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.
+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`.
+
+```bash
+yarn add @sandstormapp/sdk
+```
+
+```ts
+import { Sandstorm } from '@sandstormapp/sdk'
+
+const sandstorm = new Sandstorm({ apiKey: process.env.SANDSTORM_API_KEY })
+
+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"}'
+```
+
+## 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.
+
+```ts
+new Sandstorm({ apiKey, brand: '2f7fa2e7-c931-47b2-a66a-f1393233f2b3' })
+```
+
+`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.
+
+## Calling a tool
+
+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:
+
+```ts
+const started = await sandstorm.tools.search_assets({ types: ['image'], limit: 10 })
+// { task_id: '…', status: 'running' }
+```
+
+```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}'
+```
+
+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)
+```
+
+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:
+
+```ts
+await sandstorm.tools.revoke_asset_share({ slug: 'summer-drop', confirm: true })
+```
+
+```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}'
+```
+
+The catalogue itself, every tool this key can call with its schema, hints and whether it asks first:
+
+```ts
+const { tools } = await sandstorm.catalogue()
+```
+
+```bash
+curl https://agent.sandstormapp.com/v1/tools -H "Authorization: Bearer $SANDSTORM_API_KEY"
+```
+
+## Following a task
+
+```ts
+const task = await sandstorm.tasks.get(taskId)
+```
+
+```bash
+curl https://agent.sandstormapp.com/v1/tasks/$TASK_ID -H "Authorization: Bearer $SANDSTORM_API_KEY"
+```
+
+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:
+
+```ts
+const finished = await sandstorm.tasks.wait(taskId)
+if (finished.status === 'failed') console.error(finished.error)
+```
+
+The twenty most recent calls of this key on its brand, newest first, without their results:
+
+```ts
+const { tasks } = await sandstorm.tasks.list()
+```
+
+```bash
+curl https://agent.sandstormapp.com/v1/tasks -H "Authorization: Bearer $SANDSTORM_API_KEY"
+```
+
+Stopping one that still runs; whatever it saved before it stopped stays in the library:
+
+```ts
+await sandstorm.tasks.stop(taskId)
+```
+
+```bash
+curl -X POST https://agent.sandstormapp.com/v1/tasks/$TASK_ID/stop -H "Authorization: Bearer $SANDSTORM_API_KEY"
+```
+
+## Refusals
+
+A response the API refuses throws a `SandstormError` with the HTTP `status`, the API's `code` and its message:
+
+```ts
+import { SandstormError } from '@sandstormapp/sdk'
+
+try {
+  await sandstorm.tools.archive_offer({ offer: 'offer:1a2b3c4d' })
+} catch (error) {
+  if (error instanceof SandstormError && error.code === 'forbidden') console.log(error.message)
+}
+```
+
+| 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.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+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'>;
+};
+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 interface Tasks {
+    list(): Promise<TaskList>;
+    get(taskId: string): Promise<Task | Started>;
+    stop(taskId: string): Promise<Stopped>;
+    wait(taskId: string): Promise<Finished>;
+}
+export interface Options {
+    readonly apiKey: string;
+    readonly brand?: string;
+    readonly baseUrl?: string;
+}
+export declare class SandstormError extends Error {
+    readonly name = "SandstormError";
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(status: number, code: string | undefined, message: string);
+}
+export declare class Sandstorm {
+    #private;
+    readonly tools: Tools;
+    readonly tasks: Tasks;
+    constructor({ apiKey, brand, baseUrl }: Options);
+    catalogue(): Promise<Catalogue>;
+}

package/dist/index.js

@@ -0,0 +1,69 @@
+import { toolNames } from "./openapi.js";
+export { toolNames };
+export class SandstormError extends Error {
+    name = 'SandstormError';
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+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;
+    }
+}
+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 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(toolNames.map((name) => [name, (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));
+                }
+            },
+        };
+    }
+    catalogue() {
+        return this.#send('GET', '/v1/tools');
+    }
+    #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();
+    }
+}