@sandstormapp/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @sandstormapp/sdk
 
-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`.
+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
@@ -36,27 +36,43 @@ 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 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:
+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.search_assets({ types: ['image'], limit: 10 })
+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/search_assets \
+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 '{"types":["image"],"limit":10}'
+  -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.search_assets({ types: ['image'], limit: 10 }, { wait: 30 })
+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.result)
+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:
@@ -71,7 +87,7 @@ curl -X POST https://agent.sandstormapp.com/v1/tools/revoke_asset_share \
   -d '{"slug":"summer-drop","confirm":true}'
 ```
 
-The catalogue itself, every tool this key can call with its schema, hints and whether it asks first:
+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()
@@ -136,12 +152,14 @@ try {
 
 | status | code | when |
 | --- | --- | --- |
-| 400 | `bad_request` | the body does not match the tool's schema; the message names the mismatch |
+| 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.

package/dist/index.d.ts

@@ -1,13 +1,17 @@
-import { toolNames, type components, type paths } from './openapi.ts';
-export { toolNames };
+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 = (typeof toolNames)[number];
-export type ToolInput<Name extends ToolName> = paths[`/v1/tools/${Name}`]['post']['requestBody']['content']['application/json'];
+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'];
@@ -18,8 +22,9 @@ 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]: ToolCall<Name>;
+    readonly [Name in ToolName]: Method<Name> extends 'get' ? ToolRead<Name> : ToolCall<Name>;
 };
 export interface Tasks {
     list(): Promise<TaskList>;

package/dist/index.js

@@ -1,5 +1,5 @@
-import { toolNames } from "./openapi.js";
-export { toolNames };
+import { toolMethods } from "./openapi.js";
+export { toolMethods };
 export class SandstormError extends Error {
     name = 'SandstormError';
     status;
@@ -38,7 +38,12 @@ export class Sandstorm {
     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.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}`),
@@ -56,6 +61,16 @@ export class Sandstorm {
     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));