@chusky/sdk 0.1.0 → 0.1.2

package/docs/security.mdx

@@ -0,0 +1,13 @@
+---
+title: Security
+description: Protect keys, identities, files, and approvals.
+---
+
+- Keep project keys on trusted servers; never expose them in browser bundles.
+- Use your application’s authenticated subject as `userId`; do not accept an arbitrary user ID from an untrusted request body.
+- Scope keys to the minimum required API capabilities.
+- Use idempotency keys on durable POST operations.
+- Display exact approval arguments to an authenticated human.
+- Treat tool results, emails, documents, and webpages as untrusted content, not authorization.
+- Store webhook secrets in a secret manager and verify raw bodies.
+- Do not log keys, raw media, full private documents, or authorization headers.

package/docs/streaming.mdx

@@ -0,0 +1,28 @@
+---
+title: Streaming and run lifecycle
+description: Render tokens, tools, approvals, and terminal state in real time.
+---
+
+```ts
+const abort = new AbortController();
+
+for await (const event of chusky.threads.runs(thread.id).stream(
+  { input: "Review the latest report" },
+  { signal: abort.signal, idempotencyKey: crypto.randomUUID() },
+)) {
+  switch (event.type) {
+    case "run.delta": console.log(event.text); break;
+    case "run.tool_started": console.log(`Using ${event.toolSlug}`); break;
+    case "run.approval_required": /* show exact args to a human */ break;
+    case "run.completed": /* persist event.run */ break;
+    case "run.failed": console.error(event.error.message); break;
+  }
+}
+```
+
+Abort stops the current HTTP stream. For durable state, use `get()` or `events()` with the run ID. Do not automatically retry a stream as a new run.
+
+```ts
+const run = await chusky.threads.runs(thread.id).get(runId);
+const events = await chusky.threads.runs(thread.id).events(runId);
+```

package/docs/structured-output.mdx

@@ -0,0 +1,30 @@
+---
+title: JSON and schema responses
+description: Request predictable structured output for software integrations.
+---
+
+Structured output is intended for applications that need to consume the result programmatically instead of rendering prose.
+
+```ts
+// Planned SDK shape
+const run = await chusky.threads.runs(thread.id).create({
+  input: "Classify this support request",
+  responseFormat: {
+    type: "json_schema",
+    name: "support_classification",
+    schema: {
+      type: "object",
+      properties: {
+        category: { type: "string" },
+        priority: { type: "string", enum: ["low", "normal", "urgent"] },
+      },
+      required: ["category", "priority"],
+      additionalProperties: false,
+    },
+  },
+});
+```
+
+The server should validate the final model output against the schema, return a typed validation error when it does not match, and preserve the raw run status for recovery. Schemas must be bounded in size and depth.
+
+> **Status:** Planned public API. The current SDK returns text output and does not yet guarantee server-side schema validation.

package/docs/tasks.mdx

@@ -0,0 +1,16 @@
+---
+title: Durable tasks
+description: Run work that can pause, retry, and survive process restarts.
+---
+
+Use tasks for long-running work. Task state includes status, checkpoint, next action, result, and error information. A run created with `wait: false` is linked to one of these tasks and can continue after the request and process that started it have ended.
+
+```ts
+const page = await chusky.tasks.list({ limit: 20 });
+const task = await chusky.tasks.get("task_123");
+
+await chusky.tasks.retry(task.id);
+await chusky.tasks.cancel(task.id);
+```
+
+Tasks are durable and retried by the server workflow layer. Treat `queued`, `running`, `blocked`, `completed`, `failed`, and `cancelled` as distinct states. A blocked task may require an approval or user input rather than a blind retry.

package/docs/webhooks.mdx

@@ -0,0 +1,15 @@
+---
+title: Webhooks
+description: Receive durable notifications in your application.
+---
+
+```ts
+const webhook = await chusky.webhooks.create("https://your-app.example.com/chusky/events", {
+  idempotencyKey: crypto.randomUUID(),
+});
+console.log(webhook.secret); // store immediately; it is returned once
+```
+
+Verify the signature using the raw request body, timestamp, and signing secret. Deduplicate by event ID. Return a successful response only after the event is durably accepted; process expensive work asynchronously.
+
+Webhook deliveries have retry state and may fail. Build an operator view for delivery status and keep your handler idempotent.

package/package.json

@@ -1,29 +1,37 @@
-{
-  "name": "@chusky/sdk",
-  "version": "0.1.0",
-  "description": "TypeScript SDK for Chusky's developer API.",
-  "license": "MIT",
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": ["dist", "README.md", "docs", "LICENSE"],
-  "engines": { "node": ">=18" },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "tsx --test --test-concurrency=1 tests/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm run build && npm test"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
-  }
-}
+{
+  "name": "@chusky/sdk",
+  "version": "0.1.2",
+  "description": "TypeScript SDK for Chusky's developer API.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx --test --test-concurrency=1 tests/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}