@fuserstudio/sdk 0.0.2 → 0.0.3

package/README.md

@@ -1,13 +1,23 @@
 # @fuserstudio/sdk
 
-The TypeScript SDK for the [Fuser](https://fuser.studio) API. Each API tool is a
-method named after it: `canvas_edit` becomes `fuser.canvas.edit()`. The
-arguments and results are the same as in the REST API and the MCP server.
+The official TypeScript SDK for the [Fuser](https://fuser.studio) API.
+
+Fuser is a node canvas for AI image, video, audio and 3D work. With this SDK
+you build canvases, run them, and collect the results from code: the same
+things the Fuser app and the Fuser MCP server do. Every API tool is a method
+named after it (`canvas_edit` is `fuser.canvas.edit()`), with the same
+arguments and results as the REST API, fully typed.
+
+## Install
 
 ```bash
 npm install @fuserstudio/sdk
 ```
 
+Works on Node 20.3+, Bun, Deno and Cloudflare Workers. It has no dependencies.
+
+## Usage
+
 ```ts
 import { Fuser } from '@fuserstudio/sdk';
 
@@ -34,7 +44,104 @@ const run = await fuser.run
 console.log(run.nodes[0]?.outputs);
 ```
 
-Works on Node 20.3+, Bun, Deno and Cloudflare Workers. Keep your API key on a
-server. It acts as you, so the SDK refuses to run in a browser unless you pass `dangerouslyAllowBrowser`.
+## What's in it
+
+| Group           | Methods                              | For                                           |
+| --------------- | ------------------------------------ | --------------------------------------------- |
+| `fuser.account` | `get`                                | Credits, plan and workspaces                  |
+| `fuser.canvas`  | `list`, `get`, `edit`, `arrange`     | Reading, changing and laying out canvases     |
+| `fuser.catalog` | `search`                             | Finding node types, their inputs and prices   |
+| `fuser.run`     | `start`, `get`, `cancel`, `wait`     | Pricing and running nodes                     |
+| `fuser.media`   | `search`, `view`, `import`, `export` | Your images and videos, and ZIP downloads     |
+| `fuser.upload`  | `files`, `start`, `finish`           | Sending local files to a canvas               |
+| `fuser.tool`    | `search`, `build`                    | Tool nodes that crop, join, convert and so on |
+
+## Authentication
+
+Create an API key in Fuser and set it as `FUSER_API_KEY`, or pass it in:
+
+```ts
+const fuser = new Fuser({ apiKey: process.env.MY_FUSER_KEY });
+```
+
+A key acts as you, so keep it on a server. The SDK refuses to run in a browser
+unless you pass `dangerouslyAllowBrowser: true`.
+
+## Waiting for runs and builds
+
+`run.start()` and `tool.build()` answer straight away. Await them for that
+first answer, or add `.wait()` to get the finished result:
+
+```ts
+const quote = await fuser.run.start({ canvasId, dryRun: true }); // price only
+
+const run = await fuser.run.start({ canvasId, maxCredits: 200 }).wait();
+```
+
+`.wait()` gives up after 30 minutes for a run and 10 for a tool build; pass
+`timeoutMs` or an `AbortSignal` to change that.
+
+## Lists
+
+List methods return one page when awaited and every item when iterated:
+
+```ts
+const firstPage = await fuser.canvas.list();
+
+for await (const canvas of fuser.canvas.list()) {
+  console.log(canvas.title);
+}
+```
+
+## Uploading files
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+const [photo] = await fuser.upload.files(canvasId, [
+  {
+    fileName: 'bag.jpg',
+    data: await readFile('bag.jpg'),
+    contentType: 'image/jpeg',
+  },
+]);
+```
+
+## Errors
+
+Every failure is a `FuserError` with the `tool` that failed, the HTTP `status`,
+the API's `code` and a `requestId`. Subclasses say what went wrong:
+`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`,
+`NotFoundError`, `ConflictError`, `RateLimitError`, `InternalServerError`,
+`ConnectionError`, `TimeoutError` and `RunRefusedError`.
+
+```ts
+import { ConflictError } from '@fuserstudio/sdk';
+
+try {
+  await fuser.canvas.edit({ canvasId, expectedRevision, diff });
+} catch (error) {
+  if (error instanceof ConflictError && error.reason === 'stale_revision') {
+    // someone else changed the canvas: read it again and retry
+  }
+  throw error;
+}
+```
+
+## Retries and timeouts
+
+Requests time out after 60 seconds and are retried twice. Change both on the
+client or for one call:
+
+```ts
+const fuser = new Fuser({ timeoutMs: 20_000, maxRetries: 0 });
+
+await fuser.canvas.get({ canvasId }, { timeoutMs: 5_000 });
+```
+
+`beforeSend` and `afterSend` let you log or change each request, and `fetch`
+swaps the HTTP client.
+
+## Documentation
 
-Full guide: https://docs.fuser.studio/docs/api/sdk
+Full guide and API reference: https://docs.fuser.studio/docs/api/sdk

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fuserstudio/sdk",
-  "version": "0.0.2",
-  "description": "TypeScript SDK for the Fuser API.",
+  "version": "0.0.3",
+  "description": "Official TypeScript SDK for the Fuser API: build and run AI image, video, audio and 3D canvases from code.",
   "license": "MIT",
   "type": "module",
   "exports": {