@sandstormapp/sdk 0.0.0-stage → 0.2.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,188 @@
-# 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. A tool that only reads answers its JSON at once; every other tool starts a task the client follows. 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.
+
+## Reading
+
+A tool that only reads, such as `search_assets`, `read_offer` or `get_brand_identity`, is a `GET` with its arguments as query parameters, a list as its name repeated, and answers the tool's own JSON at once; the method takes the same arguments as an object:
+
+```ts
+const { assets } = await sandstorm.tools.search_assets({ types: ['image'], limit: 10 })
+const identity = await sandstorm.tools.get_brand_identity()
+```
+
+```bash
+curl 'https://agent.sandstormapp.com/v1/tools/search_assets?types=image&limit=10' \
+  -H "Authorization: Bearer $SANDSTORM_API_KEY"
+```
+
+A read the tool refuses, such as a ref it cannot find, throws with status 422 and the tool's reason.
+
+## Calling a tool
+
+Every other 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.generate_image_nano_banana_pro({ prompt, asset_name: 'Sunlit Mug' })
+// { task_id: '…', status: 'running' }
+```
+
+```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' \
+  -d '{"prompt":"…","asset_name":"Sunlit Mug"}'
+```
+
+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.generate_image_nano_banana_pro({ prompt, asset_name: 'Sunlit Mug' }, { wait: 30 })
+if (answer.status === 'running') console.log('still running', answer.task_id)
+else console.log(answer.files)
+```
+
+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; `readOnlyHint` marks the tools that read, and `toolMethods`, exported beside the client, says which method each tool takes:
+
+```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 query or 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 |
+| 405 | `method_not_allowed` | a read was posted, or a task tool was read; the message names the method that works |
+| 409 | `task_not_running` | the task to stop has already ended |
+| 422 | `tool_failed` | a read the tool refused, with the tool's reason |
+| 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,52 @@
+import { toolMethods, type components, type paths } from './openapi.ts';
+export { toolMethods };
+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 = keyof typeof toolMethods;
+type Method<Name extends ToolName> = (typeof toolMethods)[Name];
+type Operation<Name extends ToolName> = NonNullable<paths[`/v1/tools/${Name}`][Method<Name>]>;
+type Query<Name extends ToolName> = Operation<Name>['parameters']['query'];
+export type ToolInput<Name extends ToolName> = Method<Name> extends 'get' ? NonNullable<Query<Name>> : NonNullable<Operation<Name>['requestBody']>['content']['application/json'];
+export type ReadResult<Name extends ToolName> = Operation<Name>['responses'][200]['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 ToolRead<Name extends ToolName> = undefined extends Query<Name> ? (query?: ToolInput<Name>) => Promise<ReadResult<Name>> : (query: ToolInput<Name>) => Promise<ReadResult<Name>>;
+export type Tools = {
+    readonly [Name in ToolName]: Method<Name> extends 'get' ? ToolRead<Name> : 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,84 @@
+import { toolMethods } from "./openapi.js";
+export { toolMethods };
+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(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));
+                }
+            },
+        };
+    }
+    catalogue() {
+        return this.#send('GET', '/v1/tools');
+    }
+    #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));
+        }
+        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();
+    }
+}