@zoowork-ai/sdk 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to `@zoowork-ai/sdk` (formerly `@zooclaw-agents/sdk`). Dates are the
 day the behaviour was verified, not the day it was written.
 
+## 0.14.0 — 2026-10-29
+
+- Live smoke and thinking tests now default to the platform default model (the catalog row whose
+  `default_for` includes `model`) instead of the first catalog row, which sorts alphabetically.
+  They fall back to the first eligible row when no default is marked. `--model` still overrides.
+- Ship `dist/AGENTS.md`, a short guide for coding assistants working in a project that installs this
+  package. The public docs describe the newest release; the guide tells an assistant to check a
+  method against the installed `*.d.ts` and `CHANGELOG.md`, and to tell the user when the docs rely
+  on something the installed version lacks instead of upgrading or working around it silently. In
+  an eval of projects pinned to 0.10.2, such a guide took Codex from 0/9 to 8/9 on reporting the
+  gap and kept Claude Code at 9/9 (zoowork-sdk-skills#40).
+- Add `getBalance()` for `GET /service/v1/balance`. It returns the Organization balance shared by
+  all Projects as a USD decimal string (`available_amount`), the same amount the Platform Billing
+  page shows. Any Platform key in the Organization can read it; Work service tokens receive
+  `service_api.not_found`.
+- Require Node.js 22 or later (`engines.node` is now `>=22`). Node.js 20 reached end of life on
+  2026-04-30 and was not patched by the 2026-10-21 Node.js security release. The SDK does not use
+  any Node.js 22-only API, so Node.js 20 may still run it, but that line is no longer tested or
+  supported. CI now tests Node.js 22, 24 and 26.
+
 ## 0.13.0 — 2026-10-23
 
 - Make the deprecated engine-only event lane visible in the types (#58). `listEvents`,

package/README.md

@@ -2,7 +2,10 @@
 
 TypeScript SDK for the [ZooWork Managed Agents](https://zoowork.ai/docs/) API. Developer Preview.
 
-Zero runtime dependencies — it uses the platform `fetch`, which you can override for edge runtimes and tests. ESM only, Node 20+.
+Zero runtime dependencies — it uses the platform `fetch`, which you can override for edge runtimes and tests. ESM only. Requires Node.js 22 or later; use the latest security release of your Node.js line.
+
+Coding assistants: the installed package includes `dist/AGENTS.md`, which explains how to check
+the docs against the installed version.
 
 ```bash
 npm install @zoowork-ai/sdk
@@ -446,6 +449,7 @@ These helpers require an SDK release that includes them. Check the installed dec
 
 ```ts
 const usage = await zc.getUsage({ range: '7d', view: 'both' })
+const balance = await zc.getBalance() // { object: 'balance', available_amount: '11.34', currency: 'usd' }
 const endpoint = await zc.createAgentWebhook(agentId, {
   url: 'https://receiver.example/webhook', event_types: ['run.finished'],
 }, 'register-hook-v1')
@@ -460,7 +464,9 @@ The workspace Files methods (`getWorkspaceFile`, `writeWorkspaceFile`,
 Send a file to an Agent with `uploadFile`, and retrieve results by asking the Agent to publish
 Artifacts and downloading those through the Artifact API. The database viewer is not a
 supported production workflow. The Agent can use `agent_db` and return query results in its
-reply. Method presence is not production availability. Usage stays within the current key scope. Page helpers retain `next_cursor` and `has_more`; replay cursors
+reply. Method presence is not production availability. Usage stays within the current key scope.
+`getBalance` returns the Organization balance shared by all Projects, in USD, to any Platform
+key in the Organization. Page helpers retain `next_cursor` and `has_more`; replay cursors
 verbatim. `getApproval` and `getCustomToolCall` read terminal as well as pending actions.
 
 Agent webhook methods include get/update/delete, `rotateAgentWebhookSecret`, `testAgentWebhook`,

package/dist/AGENTS.md

@@ -0,0 +1,18 @@
+# @zoowork-ai/sdk: notes for coding assistants
+
+This file ships inside the installed `@zoowork-ai/sdk` package. The installed version is in
+`../package.json`.
+
+The docs at https://zoowork.ai/docs describe the newest SDK release, which can be newer than the
+copy installed in this project. Before you use a method, field, or option from the docs:
+
+- Check that it exists in the `*.d.ts` files next to this one. They are the source of truth for
+  what the installed version supports.
+- `../CHANGELOG.md` lists what each release up to the installed one added. Later releases are
+  listed at https://raw.githubusercontent.com/SerendipityOneInc/zoowork-sdk-typescript/main/CHANGELOG.md.
+- If the docs rely on something the installed version lacks, tell the user which release adds it
+  and ask before upgrading. Do not upgrade the SDK without asking. If you work around the gap
+  instead, for example with a deprecated method or an untyped value, say so.
+
+Server behavior (errors, event streams, schedules, limits) does not depend on the SDK version.
+Follow the live docs for it: https://zoowork.ai/docs/llms.txt

package/dist/developer-api.d.ts

@@ -68,6 +68,13 @@ export interface UsageResult extends ApiObject {
     groups?: ApiObject[];
     records?: ApiObject[];
 }
+/** The Organization's shared balance, as shown on the Platform Billing page. */
+export interface BalanceResult extends ApiObject {
+    object: 'balance';
+    /** Decimal USD string with two places, e.g. `"11.34"`, after current-period usage. */
+    available_amount: string;
+    currency: 'usd';
+}
 export interface RunOutputArtifact extends ApiObject {
     artifact_id: string | null;
     name: string;
@@ -182,6 +189,8 @@ export interface DeveloperApi {
         offset?: number;
     }): Promise<AgentDatabaseRows>;
     getUsage(opts?: UsageOptions): Promise<UsageResult>;
+    /** Read the Organization balance shared by every Project. Requires a Platform key. */
+    getBalance(): Promise<BalanceResult>;
     getRunOutput(agentId: string, sessionId: string, runId: string, opts?: CursorOptions): Promise<RunOutput>;
     getApproval(agentId: string, approvalId: string): Promise<ApprovalRecord>;
     getCustomToolCall(agentId: string, callId: string): Promise<CustomToolCallRecord>;

package/dist/developer-api.js

@@ -21,6 +21,7 @@ export function createDeveloperApi(json, bytes, selectors) {
         getAgentDatabase: (id) => json(`${agent(id)}/database`),
         getAgentDatabaseRows: (id, table, opts = {}) => json(`${agent(id)}/database/tables/${segment(table)}/rows${query({ limit: opts.limit, offset: opts.offset })}`),
         getUsage: (opts = {}) => json(`/usage${query({ range: opts.range, timezone: opts.timezone, group_by: opts.groupBy, view: opts.view, session_id: opts.sessionId, api_key_id: opts.apiKeyId, root_session_id: opts.rootSessionId, attribution: opts.attribution, page: opts.page, per_page: opts.perPage, as_of: opts.asOf, snapshot: opts.snapshot, cursor: opts.cursor })}`),
+        getBalance: () => json('/balance'),
         getRunOutput: (id, sid, rid, opts = {}) => json(`${agent(id)}/sessions/${segment(sid)}/runs/${segment(rid)}/output${query({ cursor: opts.cursor, limit: opts.limit })}`),
         getApproval: (id, aid) => json(`${agent(id)}/approvals/${segment(aid)}`),
         getCustomToolCall: (id, cid) => json(`${agent(id)}/custom_tool_calls/${segment(cid)}`),

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { createZooworkClient, DEFAULT_BASE_URL, ZooworkError, type ZooworkClient
 export { SESSION_EVENT_TYPES, type SessionEventType, PUBLIC_INPUT_EVENT_TYPES, type PublicInputEventType, normalizeEvent, isRunFinished, runOutcome, messageText, assistantText, thinkingText, customToolUse, type CustomToolUse, toolCall, type ToolCall, } from './events.js';
 export { parseSSE, type SSEMessage } from './sse.js';
 export { WEBHOOK_EVENT_TYPES, WEBHOOK_SCHEDULE_CONFIG_EVENT_TYPES, type WebhookEventType, isKnownWebhookEventType, knownWebhookEvent, verifyWebhookSignature, unwrapWebhook, signWebhook, ZooworkWebhookError, type WebhookErrorCode, WEBHOOK_ID_HEADER, WEBHOOK_TIMESTAMP_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SECRET_ENV, WEBHOOK_TOLERANCE_SECONDS, WEBHOOK_DEFAULT_MAX_BODY_BYTES, type WebhookEvent, type WebhookEventFor, type KnownWebhookEvent, type WebhookEventData, type WebhookEventDataByType, type WebhookEventAttribution, type WebhookScheduleRunRef, type WebhookWaitingOnRef, type WebhookRunEventData, type WebhookRunStartedData, type WebhookRunFinishedData, type WebhookRunYieldedData, type WebhookApprovalEventData, type WebhookApprovalRequestedData, type WebhookApprovalResolvedData, type WebhookCustomToolEventData, type WebhookCustomToolRequestedData, type WebhookCustomToolResolvedData, type WebhookOutcomeEvaluatedData, type WebhookSessionCreatedData, type WebhookSessionArchivedData, type WebhookSessionDeletedData, type WebhookScheduleFireData, type WebhookScheduleDispatchedData, type WebhookScheduleDispatchFailedData, type WebhookScheduleSkippedData, type WebhookScheduleFinishedData, type WebhookScheduleConfigData, type WebhookTestData, type WebhookHeaders, type WebhookHeaderSource, type WebhookSignatureHeaders, type VerifyWebhookInput, type VerifiedWebhook, type SignWebhookInput, } from './webhooks.js';
-export type { ApiObject, CursorOptions, ActionListOptions, ApprovalPage, CustomToolCallPage, WorkspaceFileEntry, WorkspaceFile, AgentDatabase, AgentDatabaseRows, UsageOptions, UsageResult, RunOutputArtifact, RunOutputItem, RunOutput, AgentWebhookInput, AgentWebhookEndpoint, AgentWebhookPage, AgentWebhookCreated, AgentWebhookSecretRotation, WebhookDeliveryOptions, WebhookDeliveryPage, WebhookTestReceipt, WebhookRedeliveryReceipt, WebhookBatchRedeliveryReceipt, WebhookBatchRedeliveryInput, DeveloperApi, } from './developer-api.js';
+export type { ApiObject, CursorOptions, ActionListOptions, ApprovalPage, CustomToolCallPage, WorkspaceFileEntry, WorkspaceFile, AgentDatabase, AgentDatabaseRows, UsageOptions, UsageResult, BalanceResult, RunOutputArtifact, RunOutputItem, RunOutput, AgentWebhookInput, AgentWebhookEndpoint, AgentWebhookPage, AgentWebhookCreated, AgentWebhookSecretRotation, WebhookDeliveryOptions, WebhookDeliveryPage, WebhookTestReceipt, WebhookRedeliveryReceipt, WebhookBatchRedeliveryReceipt, WebhookBatchRedeliveryInput, DeveloperApi, } from './developer-api.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoowork-ai/sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "TypeScript SDK for the ZooWork Managed Agents API (Developer Preview)",
   "keywords": [
     "zoowork",
@@ -33,14 +33,14 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync('agent-guide/AGENTS.md', 'dist/AGENTS.md')\"",
     "typecheck": "tsc --noEmit",
     "test": "tsc --noEmit && vitest run",
     "test:watch": "vitest",