@chusky/sdk 0.2.0 → 0.3.1

package/examples/README.md

@@ -0,0 +1,31 @@
+# SDK examples
+
+These examples are server-side TypeScript programs. They call the real Chusky
+Developer API; they are not mocks and they do not contain credentials.
+
+## Run one
+
+From the SDK directory:
+
+```bash
+npm install
+export CHUSKY_API_KEY=chsk_...
+export CHUSKY_USER_ID=example-user
+npx tsx examples/quickstart.ts
+```
+
+PowerShell:
+
+```powershell
+$env:CHUSKY_API_KEY = "chsk_..."
+$env:CHUSKY_USER_ID = "example-user"
+npx tsx examples/quickstart.ts
+```
+
+Set `CHUSKY_BASE_URL` when using a self-hosted or staging API. Use a test
+project key and test identity. Some examples create durable state, upload a
+file, register a webhook, or display an approval; review the source before
+running them against production.
+
+The `_client.ts` helper creates the authenticated SDK client. Each example can
+also be copied into an application and inlined without depending on the helper.

package/examples/_client.ts

@@ -0,0 +1,17 @@
+import { Chusky } from "@chusky/sdk";
+
+export function createClient(): Chusky {
+  const apiKey = process.env.CHUSKY_API_KEY;
+  if (!apiKey) throw new Error("Set CHUSKY_API_KEY before running this example.");
+
+  return new Chusky({
+    apiKey,
+    baseUrl: process.env.CHUSKY_BASE_URL,
+    userId: process.env.CHUSKY_USER_ID ?? "example-user",
+  });
+}
+
+export function required<T>(value: T | undefined, name: string): T {
+  if (value === undefined) throw new Error(`Missing ${name}.`);
+  return value;
+}

package/examples/approvals.ts

@@ -0,0 +1,27 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const page = await chusky.approvals.list();
+const pending = page.data.find((approval) => approval.status === "pending");
+
+if (!pending) {
+  console.log("There are no pending approvals.");
+  process.exit(0);
+}
+
+console.log({
+  id: pending.id,
+  action: pending.toolSlug,
+  request: pending.request,
+  expiresAt: pending.expiresAt,
+});
+
+// Replace this with an authenticated human decision in your application UI.
+const humanApproved = process.env.APPROVE_CHUSKY_ACTION === "true";
+const decision = await chusky.approvals.decide(
+  pending.id,
+  humanApproved ? "approve" : "deny",
+  { idempotencyKey: `approval:${pending.id}:${humanApproved ? "approve" : "deny"}` },
+);
+
+console.log(`Approval ${pending.id}:`, decision);

package/examples/company-agent.ts

@@ -0,0 +1,36 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const templates = await chusky.agents.templates();
+const template = templates.data.find((item) => item.slug === "lead-research");
+
+if (!template) {
+  throw new Error("The lead-research template is not available for this project.");
+}
+
+const agent = await chusky.agents.create(
+  {
+    template: template.slug,
+    name: "Fintech lead scout",
+    instructions: "Return sourced, deduplicated company profiles. Draft external communication only.",
+    policy: {
+      tools: {
+        allow: ["crm.read", "web.search", "email.draft"],
+        requireApproval: ["crm.write", "email.send"],
+      },
+      budget: { duration: "30m", maxToolCalls: 80, maxCost: 8 },
+    },
+  },
+  { idempotencyKey: "create-fintech-lead-agent-v1" },
+);
+
+const { thread, run } = await chusky.runs.create(
+  {
+    agentId: agent.id,
+    input: "Find qualified fintech companies with more than 50 employees and prepare CRM-ready profiles.",
+    wait: false,
+  },
+  { idempotencyKey: "fintech-lead-research-customer-123-v1" },
+);
+
+console.log({ agentId: agent.id, threadId: thread.id, runId: run.id, status: run.status });

package/examples/context-and-departments.ts

@@ -0,0 +1,41 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const customerId = process.env.CHUSKY_USER_ID ?? "example-user";
+
+await chusky.context.save(
+  {
+    scope: "customer",
+    scopeId: customerId,
+    kind: "preference",
+    key: "renewal_window",
+    value: "Customer prefers renewal discussions in October.",
+    source: "crm",
+    confidence: 0.9,
+    sensitivity: "normal",
+  },
+  { idempotencyKey: `context-renewal-window-${customerId}` },
+);
+
+const context = await chusky.context.list({
+  scope: "customer",
+  scopeId: customerId,
+  purpose: "renewal",
+});
+
+const catalog = await chusky.departments.catalog();
+console.log("Available departments:", catalog.data.map((item) => item.slug));
+
+const packet = await chusky.departments.handoff(
+  "customer-success",
+  {
+    objective: "Prepare a renewal risk review for the account team.",
+    inputs: { customerId },
+    constraints: ["Use verified CRM facts only."],
+    evidenceRequired: ["account health source", "open risk owner"],
+    approvalBoundary: "Draft only; do not contact the customer.",
+  },
+  { idempotencyKey: `handoff-renewal-risk-${customerId}` },
+);
+
+console.log({ contextNodes: context.data.length, handoffId: packet.id, status: packet.status });

package/examples/files.ts

@@ -0,0 +1,23 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const content = "customer_id,renewal_date\n123,2026-10-01\n";
+const body = new TextEncoder().encode(content);
+
+const upload = await chusky.files.create(
+  { name: "renewals.csv", contentType: "text/csv", size: body.byteLength },
+  { idempotencyKey: "upload-renewals-csv-v1" },
+);
+
+const response = await fetch(upload.uploadUrl, {
+  method: "PUT",
+  headers: { "Content-Type": "text/csv" },
+  body,
+});
+if (!response.ok) throw new Error(`Upload failed with HTTP ${response.status}.`);
+
+const file = await chusky.files.complete(
+  upload.id,
+  { idempotencyKey: `complete-upload:${upload.id}` },
+);
+console.log({ id: file.id, name: file.name, status: file.status });

package/examples/mission.ts

@@ -0,0 +1,46 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const mission = await chusky.missions.create(
+  {
+    title: "Qualified fintech leads",
+    objective: "Find 20 fintech companies matching our ICP and prepare CRM-ready profiles.",
+    definitionOfDone: "Every lead has a source URL, qualification reason, duplicate check, and approval-ready CRM payload.",
+    verificationMode: "strict",
+    requiredEvidence: ["source URL", "qualification assertion", "deduplication check"],
+    steps: [
+      { id: "research", title: "Research companies", objective: "Collect source-backed company facts." },
+      { id: "qualify", title: "Qualify and deduplicate", objective: "Apply the ICP and remove duplicates.", dependsOn: ["research"] },
+      { id: "prepare", title: "Prepare CRM payload", objective: "Draft the bounded CRM import.", dependsOn: ["qualify"] },
+    ],
+    maxDurationSeconds: 3 * 60 * 60,
+    maxSteps: 30,
+    maxToolCalls: 100,
+    maxCost: 15,
+  },
+  { idempotencyKey: "mission-fintech-leads-customer-123-v1" },
+);
+
+console.log(`Mission ${mission.id} is ${mission.status}.`);
+
+const proof = await chusky.missions.proof(mission.id);
+console.log({
+  status: proof.status,
+  nextAction: proof.nextAction,
+  completedSteps: proof.steps.filter((step) => step.status === "completed").length,
+  evidence: proof.evidence.length,
+});
+
+// Attach evidence only after your application has actually verified it.
+if (proof.status === "completed" && proof.steps[0]?.status === "completed") {
+  await chusky.missions.evidence(mission.id, {
+    stepId: "research",
+    evidence: [{
+      id: `source-check-${Date.now()}`,
+      kind: "source",
+      summary: "Company facts were checked against the cited source URLs.",
+      verified: true,
+      verifiedBy: "system",
+    }],
+  });
+}

package/examples/quickstart.ts

@@ -0,0 +1,25 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const requestId = `quickstart-${Date.now()}`;
+
+const { thread, run } = await chusky.runs.create(
+  {
+    input: "Prepare a concise renewal brief from the available account context.",
+    wait: false,
+    budget: { duration: "5m", maxToolCalls: 20, maxCost: 1 },
+  },
+  { idempotencyKey: requestId },
+);
+
+console.log(`Started run ${run.id} in thread ${thread.id}.`);
+const completed = await chusky.runs.wait(thread.id, run.id, {
+  timeoutMs: 120_000,
+  intervalMs: 1_000,
+});
+
+if (completed.status === "failed") {
+  throw new Error(completed.error?.message ?? "Chusky run failed.");
+}
+
+console.log(completed.output ?? "The run completed without text output.");

package/examples/streaming.ts

@@ -0,0 +1,37 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const thread = await chusky.threads.create(
+  { metadata: { source: "sdk-example" } },
+  { idempotencyKey: `stream-thread-${Date.now()}` },
+);
+
+const controller = new AbortController();
+const stopAfterMs = setTimeout(() => controller.abort(), 60_000);
+
+try {
+  for await (const event of chusky.threads.runs(thread.id).stream(
+    { input: "Summarize the account's current priorities in three bullets." },
+    { signal: controller.signal },
+  )) {
+    switch (event.type) {
+      case "run.delta":
+        process.stdout.write(event.text);
+        break;
+      case "run.tool_started":
+        console.error(`\nUsing ${event.toolSlug}...`);
+        break;
+      case "run.approval_required":
+        console.error(`\nApproval required: ${event.approval.request ?? event.approval.toolSlug}`);
+        console.error(`Approval ID: ${event.approval.id}`);
+        break;
+      case "run.failed":
+        throw new Error(event.error.message);
+      case "run.completed":
+        console.error(`\nCompleted with status ${event.run.status}.`);
+        break;
+    }
+  }
+} finally {
+  clearTimeout(stopAfterMs);
+}

package/examples/webhooks.ts

@@ -0,0 +1,16 @@
+import { createClient } from "./_client.js";
+
+const chusky = createClient();
+const webhook = await chusky.webhooks.create(
+  "https://app.example.com/api/chusky/events",
+  { idempotencyKey: "register-chusky-events-v1" },
+);
+
+const deliveries = await chusky.webhooks.deliveries(webhook.id);
+console.log({
+  webhookId: webhook.id,
+  deliveryStatuses: deliveries.data.map((delivery) => delivery.status),
+});
+
+// Your receiving endpoint should verify the Chusky signature, persist the
+// delivery ID before applying the event, and return 2xx only after that write.

package/openapi.yaml

@@ -63,7 +63,7 @@ paths:
     post: { summary: Create a Telegram linking code for the account, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '200': { description: Linking code } } }
   /account/calls:
     get: { summary: List account voice calls with redacted destinations, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: OK } } }
-    post: { summary: Create an approval-gated outbound voice call request, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Pending approval } } }
+    post: { summary: Validate and start an outbound voice call, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Started call record } } }
   /meetings:
     get: { summary: List owner-scoped Recall meeting preparations, meetings, participants, and contacts, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: OK } } }
     post: { summary: Join or schedule a Recall meeting, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Meeting lifecycle record } } }
@@ -224,11 +224,69 @@ paths:
     post: { summary: Schedule a one-time reminder, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Scheduled } } }
   /reminders/{id}:
     delete: { summary: Cancel an owned reminder, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '204': { description: Cancelled } } }
+  /reminders/{id}/pause:
+    post: { summary: Pause an owned reminder, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '200': { description: Paused } } }
+  /reminders/{id}/resume:
+    post: { summary: Resume an owned reminder, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '200': { description: Resumed } } }
+  /reminders/{id}/run:
+    post: { summary: Queue an immediate reminder execution, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '202': { description: Queued } } }
   /jobs:
     get: { summary: List recurring schedules, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: OK } } }
     post: { summary: Create a recurring QStash schedule, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Scheduled } } }
   /jobs/{id}:
     delete: { summary: Cancel an owned recurring schedule, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '204': { description: Cancelled } } }
+  /jobs/{id}/pause:
+    post: { summary: Pause an owned recurring schedule, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '200': { description: Paused } } }
+  /jobs/{id}/resume:
+    post: { summary: Resume an owned recurring schedule, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '200': { description: Resumed } } }
+  /jobs/{id}/run:
+    post: { summary: Queue an immediate recurring-job execution, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '202': { description: Queued } } }
+  /jobs/{id}/occurrences:
+    get: { summary: List owner-scoped recurring-job occurrences, parameters: [{ $ref: '#/components/parameters/UserId' }, { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }], responses: { '200': { description: Occurrence history } } }
+  /missions:
+    get: { summary: List owner-scoped autonomous missions, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: Mission records } } }
+    post: { summary: Create and start a durable dependency-aware mission, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Mission started } } }
+  /missions/{missionId}:
+    get: { summary: Get an autonomous mission, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Mission record } } }
+  /missions/{missionId}/events:
+    get: { summary: List mission lifecycle events, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Mission events } } }
+    post: { summary: Resume a mission for its exact expected provider event, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '202': { description: Continuation queued } } }
+  /missions/{missionId}/events/signed:
+    post: { summary: Verify and ingest a signed provider event for a mission, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '202': { description: Continuation queued } } }
+  /missions/{missionId}/proof:
+    get: { summary: Get bounded mission proof with budget, evidence, and verification, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Mission proof } } }
+  /missions/{missionId}/evidence:
+    post: { summary: Attach verified evidence records to a mission, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Updated mission } } }
+  /missions/{missionId}/verify:
+    post: { summary: Verify a mission definition of done, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Verification result } } }
+  /missions/{missionId}/repair:
+    post: { summary: Move a mission into an explicit repair state, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Repair state } } }
+  /missions/{missionId}/pause:
+    post: { summary: Pause a mission and cancel active slices, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Paused mission } } }
+  /missions/{missionId}/resume:
+    post: { summary: Resume a paused, blocked, or failed mission, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Resumed mission } } }
+  /missions/{missionId}/replan:
+    post: { summary: Replace the unfinished portion of a mission plan while preserving completed work, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Replanned mission } } }
+  /missions/{missionId}/steps/{stepId}/complete:
+    post: { summary: Complete the currently executable mission step, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }, { name: stepId, in: path, required: true, schema: { type: string } }], responses: { '200': { description: Updated mission } } }
+  /missions/{missionId}/cancel:
+    post: { summary: Cancel a mission and its active tasks, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/MissionId' }], responses: { '200': { description: Cancelled mission } } }
+  /context:
+    get: { summary: Select owner-scoped operating context, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: Context nodes and prompt projection } } }
+    post: { summary: Save a sensitivity-aware context node, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Context node } } }
+  /departments/catalog:
+    get: { summary: List supported department operating templates, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: Department catalogue } } }
+  /departments:
+    get: { summary: List owner department spaces, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: Department spaces } } }
+    post: { summary: Provision a department space, parameters: [{ $ref: '#/components/parameters/UserId' }, { $ref: '#/components/parameters/IdempotencyKey' }], responses: { '201': { description: Department space } } }
+  /departments/{department}/handoffs:
+    post: { summary: Create a typed department work packet, parameters: [{ $ref: '#/components/parameters/UserId' }, { name: department, in: path, required: true, schema: { type: string } }], responses: { '201': { description: Handoff packet } } }
+  /outcomes:
+    get: { summary: List governed business outcome packages, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: Outcome packages } } }
+  /outcomes/{slug}:
+    get: { summary: Get one business outcome package, parameters: [{ $ref: '#/components/parameters/UserId' }, { name: slug, in: path, required: true, schema: { type: string } }], responses: { '200': { description: Outcome package } } }
+  /outcomes/{slug}/plan:
+    post: { summary: Plan a governed outcome from supplied business inputs, parameters: [{ $ref: '#/components/parameters/UserId' }, { name: slug, in: path, required: true, schema: { type: string } }], responses: { '200': { description: Outcome plan } } }
   /scratchpad:
     get: { summary: Search private scratchpad notes, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '200': { description: OK } } }
     delete: { summary: Clear private scratchpad notes, parameters: [{ $ref: '#/components/parameters/UserId' }], responses: { '204': { description: Cleared } } }
@@ -250,3 +308,4 @@ components:
   parameters:
     UserId: { name: X-Chusky-User-Id, in: header, required: true, schema: { type: string, maxLength: 200 } }
     IdempotencyKey: { name: Idempotency-Key, in: header, required: false, schema: { type: string, maxLength: 255 } }
+    MissionId: { name: missionId, in: path, required: true, schema: { type: string, pattern: '^mis_[A-Za-z0-9_-]+$' } }

package/package.json

@@ -1,6 +1,6 @@
-{
-  "name": "@chusky/sdk",
-  "version": "0.2.0",
+{
+  "name": "@chusky/sdk",
+  "version": "0.3.1",
   "description": "TypeScript SDK for Chusky's developer API.",
   "license": "MIT",
   "repository": {
@@ -14,11 +14,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "type": "module",
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -27,28 +27,29 @@
       "types": "./dist/widget.d.ts",
       "import": "./dist/widget.js"
     }
-  },
-  "files": [
-    "dist",
-    "README.md",
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "examples",
     "docs",
     "docs.json",
     "openapi.yaml",
-    "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"
-  }
-}
+    "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"
+  }
+}