@beeos-ai/bma-sdk 1.0.1 → 2.0.0

package/README.md

@@ -2,151 +2,84 @@
 
 [![npm](https://img.shields.io/npm/v/@beeos-ai/bma-sdk.svg)](https://www.npmjs.com/package/@beeos-ai/bma-sdk)
 
-TypeScript client for the BMA REST API, generated from
-[`contracts/bma/rest.openapi.yaml`](../contracts/bma/rest.openapi.yaml) and the
-resource map [`contracts/bma/sdk.resources.yaml`](../contracts/bma/sdk.resources.yaml),
-plus the BMA extensions to the Anthropic Managed Agents API.
+TypeScript client for BMA, version 2.0 (ADR 0025): **the official
+[`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) 1.6.0
+plus the BMA extensions**. `BmaClient` extends the official `Anthropic` client,
+so every Claude Managed Agents resource under `client.beta` (agents,
+environments, sessions, events, files, skills, vaults, memory stores, …) is the
+official one with its signatures; the BMA extensions (`machines`,
+`machinePools` and `.grants`, `desktopSessions` and `.tickets`,
+`terminalSessions` and `.tickets`, `organization.projects`) are generated from
+[`contracts/bma/v2/extensions.openapi.yaml`](../contracts/bma/v2/extensions.openapi.yaml)
+and use the same client: base URL, authentication, retries, timeouts, `fetch`,
+middleware and error classes. Server side only: the API key is a tenant
+credential (hand end users a ticket, never the key).
 
 | | |
 | --- | --- |
-| Version | 1.0.0 (tag `v1.0.0`), see [CHANGELOG](../CHANGELOG.md); upgrading from 0.4: [MIGRATION](../MIGRATION.md) |
-| Contract | BMA REST snapshot recorded in [`contracts/bma/lock.json`](../contracts/bma/lock.json) |
+| Version | 2.0.0, see [CHANGELOG](../CHANGELOG.md); from 1.x: [MIGRATION](../MIGRATION.md#typescript-1x--20) |
+| Official core | `@anthropic-ai/sdk` 1.6.0 (exact pin) |
 | Node.js | 20 or newer; ESM |
 
 ```ts
-import { BmaClient } from "@beeos-ai/bma-sdk";
+import { BmaClient, errorCode, sessionExtensions } from "@beeos-ai/bma-sdk";
 
-const bma = new BmaClient({
-  token: process.env.BMA_TOKEN!,
-  baseUrl: process.env.BMA_BASE_URL!, // origin, e.g. https://api.staging.bma.beeos.ai
-  orgId: "org_...",                    // defaults: also read from BMA_ORG_ID / BMA_PROJECT_ID
-  projectId: "prj_...",
-});
+// apiKey: BMA_API_KEY, baseURL: BMA_BASE_URL (default https://api.bma.beeos.ai),
+// project: BMA_PROJECT_ID. ANTHROPIC_* is never read.
+const client = new BmaClient({ apiKey: process.env.BMA_API_KEY, baseURL: process.env.BMA_BASE_URL });
 
-const { session } = await bma.agents.sessions.create(agentId, { idempotency_key: "task-1" });
-await bma.agents.inputs.create(
-  agentId,
-  { session_id: session.id, content_blocks: [{ type: "text", text: "Plan my week." }] },
-  { idempotencyKey: "input-1" },
-);
+const session = await client.beta.sessions.create({
+  agent: agentId,
+  environment_id: environmentId,
+  bma_model_override: { model: "deepseek-flash" }, // typed BMA field
+});
+console.log(sessionExtensions(session).modelOverride);
 
-for await (const ev of bma.agents.events.stream(agentId, { session_id: session.id, stream_deltas: true })) {
-  switch (ev.event) {
-    case "model_output":       console.log(ev.sequence, ev.data.content_blocks); break;
-    case "tool_call_update":   console.log(ev.data.tool_call_id, ev.data.state); break;
-    case "model_output_delta": console.log(ev.data); break;
-  }
+// Open the stream first, then send. A dropped stream resumes with Last-Event-ID
+// and returns every event once.
+const stream = await client.beta.sessions.events.stream(session.id);
+await client.beta.sessions.events.send(session.id, {
+  events: [{ type: "user.message", content: [{ type: "text", text: "Start the task." }] }],
+});
+for await (const event of stream) {
+  if (event.type === "session.status_idle") break;
 }
-```
-
-Set `baseUrl` to the origin of your BMA deployment (for example
-`https://api.staging.bma.beeos.ai`; the default `https://api.bma.beeos.ai` does
-not resolve yet). The client adds `/api/v1`; a value already ending in
-`/api/v1` is accepted. `token` and `baseUrl` default to
-`BMA_TOKEN` and `BMA_BASE_URL`, `orgId` and `projectId` to `BMA_ORG_ID` and
-`BMA_PROJECT_ID`.
-
-## Methods
-
-Every contract operation is a method on a resource: path IDs are positional
-arguments, `params` is the operation's query, header and body fields in one
-object (wire names, snake_case), and `options` is the per-request
-`{ timeout, maxRetries, signal, idempotencyKey, headers }`. Params and results
-are the contract types; every schema is exported by name (`AgentSession`,
-`ToolCall`, ...).
-
-- **Scope.** `orgId` / `projectId` fill the organization and project of every
-  method; pass `org_id` / `project_id` in params to override one call.
-- **Lists.** Every list whose response is `{ data, next_<param> }` returns a
-  `PagePromise`: `await` gives the first page (`page.data`,
-  `page.hasNextPage()`, `page.getNextPage()`), and
-  `for await (const agent of bma.agents.list())` walks every item. Besides
-  `cursor` lists this covers `agents.events.list` (forward by
-  `after_sequence`, backward when you pass `before_sequence`),
-  `agents.sessions.list` (`before_id`), `agentSessions.list` (`after_id`),
-  `agents.turns.list`, `agents.turns.events.list` and `files.list` (`page`).
-- **Event stream.** `agents.events.stream()` yields frames discriminated by
-  `event`; durable frames carry `id` and `sequence`. Like EventSource, it
-  reconnects with `Last-Event-ID` set to the last durable frame when the
-  connection drops, when the server ends the response (a deployment), or on
-  an `error` frame with code `service_unavailable`; a frame cut off at the end
-  is discarded. It never ends on its own: it throws once `maxRetries`
-  reconnects in a row received no data (a heartbeat counts as data), and any
-  other error frame throws `EventStreamError`.
-- **Files.** Uploads take the bytes as `body` (`Blob`, `ArrayBuffer`, typed
-  array or string); downloads (`files.download`, `agents.artifacts.download`,
-  ...) return the `Response`. `agents.artifacts.downloadVerified(artifact, { maxBytes })`
-  verifies the size and sha256 digest.
-
-## Errors, retries, timeouts
-
-Errors are `BmaApiError` subclasses named after the status, as in the
-Anthropic SDK: `BadRequestError` (400), `AuthenticationError` (401),
-`PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409),
-`ContentTooLargeError` (413), `UnprocessableEntityError` (422),
-`RateLimitError` (429), `InternalServerError` (5xx), `ServiceUnavailableError`
-(503), plus `APIConnectionError`, `APIConnectionTimeoutError` and
-`APIUserAbortError`. `error.code` is the contract's `ErrorCode`.
-
-Each call retries twice by default (`maxRetries`) with exponential backoff,
-honouring `retry-after-ms` / `retry-after`. Reads and operations that accept
-an `Idempotency-Key` retry 408, 429, 5xx and connection errors; the SDK sends
-a generated key (`bma-sdk-retry-<uuid>`) unless you pass `idempotencyKey`, and
-reuses it across the retries. Other writes retry only 429, 503 and requests
-that never reached the server. 409 is never retried. The timeout is 60 s per
-attempt (`timeout`), measured until the response headers arrive; `0`
-disables it. Uploads (binary and multipart bodies) get only a per-call
-`timeout`, so a large file is never cut off by the client default (Node's
-fetch still bounds connecting and waiting for headers). The `signal` also
-aborts reading the response body. Every error the SDK throws is a
-`BmaError`.
 
-## Custom tools
+// Extensions
+for await (const machine of client.beta.machines.list({ limit: 20 })) console.log(machine.id);
+const term = await client.beta.terminalSessions.create({ machine_id: machineId }); // sends an Idempotency-Key
+const ticket = await client.beta.terminalSessions.tickets.create(term.id, {}); // single use; give it to the end user
 
-A custom tool call waits in `ready` until a consumer submits its result.
-`defineTool` takes any [Standard Schema](https://standardschema.dev) (zod 4.2+,
-valibot, arktype) and `agents.toolCalls.runner` runs the matching calls of an
-agent and its subagents:
-
-```ts
-import { z } from "zod";
-import { ToolError, defineTool } from "@beeos-ai/bma-sdk";
-
-const weather = defineTool({
-  name: "get_weather",
-  description: "Current weather",
-  inputSchema: z.object({ city: z.string() }),
-  run: async ({ city }) => {
-    if (!city) throw new ToolError("city is empty"); // submitted as a failed result
-    return `Sunny in ${city}`;                       // string or result content blocks
-  },
-});
-// weather.definition is the agent config entry for tools.get_weather.
-
-const runner = bma.agents.toolCalls.runner(agentId, { session_id: session.id, tools: [weather] });
-// ... later
-await runner.stop();
+try {
+  await client.beta.machines.retrieve("mch_x");
+} catch (err) {
+  console.log(errorCode(err)); // BMA's error.code, e.g. "machine_not_found"
+}
 ```
 
-The runner reconnects its event stream without limit by default (backoff up
-to 8 s; `max_reconnects` bounds it), lists ready calls again after each
-reconnect, treats a 409 on submit (another consumer answered first) as
-handled, and `done()` rejects with the error that stopped it; it never ends
-silently.
-
-## BMA extensions to the Anthropic facade
-
-Use the official Anthropic SDK for `/v1/agents`, `/v1/environments`,
-`/v1/sessions` and events. The routes BMA adds live in a separate entry point:
-
-```ts
-import { FacadeExtensionsClient, bmaSequence } from "@beeos-ai/bma-sdk/facade-extensions";
-
-const ext = new FacadeExtensionsClient({ baseUrl: "https://host", apiKey: key, projectId: "prj_..." });
-const ticket = await ext.sessions.desktop.stream(sessionId, { desktop_session_id, origin: location.origin });
-await ext.sessions.files.upload(sessionId, { file: new File([bytes], "report.pdf") });
-const page = await ext.sessions.files.list(sessionId, { limit: 100 });
+- **Extension fields.** `sessionExtensions`, `agentExtensions`,
+  `environmentExtensions` and `eventExtensions` read `bma_*` response fields as
+  typed values; `sessions.create/update`, `agents.create/update` and
+  `environments.create/update` accept `bma_model_override`, `bma_harness` and
+  `bma_desktop` as typed params (`bma_model_override: null` revokes).
+- **Project.** `new BmaClient({ project })` sets `x-bma-project-id`;
+  `client.withOptions({ project })` copies the client into another project.
+- **Idempotency.** Extension creates send a random `Idempotency-Key` once per
+  call, so automatic retries resend it; pass `{ headers: { "Idempotency-Key": key } }`
+  to choose it. CMA creates get none unless you pass one.
+- **Types.** The extension request and response types are exported by name
+  (`Machine`, `MachineCreateParams`, …); the whole schema set is
+  `components["schemas"]`.
+- Credential features of the official client (profiles, `authToken`,
+  federation) are disabled: authentication is the BMA API key.
+
+## Development
+
+```bash
+npm ci
+npm run build   # tsc
+npm test        # unit tests against a local server; BMA_INTEGRATION=1 adds the staging test
 ```
 
-The executor protocol (executor, harness and agent ends) is the separate
-package [`@beeos-ai/bma-executor-sdk`](https://github.com/beeos-ai/bma-executor-sdk/tree/main/typescript).
+`src/generated/` is written by `tools/generate.sh` (openapi-typescript for the
+types, `tools/sdkgen/ts2gen.py` for the services); never edit it by hand.

package/dist/beta.d.ts

@@ -0,0 +1,55 @@
+import { APIPromise } from '@anthropic-ai/sdk/core/api-promise';
+import { type RequestOptions } from './internal.js';
+import { Stream } from '@anthropic-ai/sdk/core/streaming';
+import { Beta } from '@anthropic-ai/sdk/resources/beta/beta';
+import { Agents, type AgentCreateParams, type AgentUpdateParams } from '@anthropic-ai/sdk/resources/beta/agents/agents';
+import { Environments, type EnvironmentCreateParams, type EnvironmentUpdateParams } from '@anthropic-ai/sdk/resources/beta/environments/environments';
+import { Events, type EventStreamParams } from '@anthropic-ai/sdk/resources/beta/sessions/events';
+import { Sessions, type SessionCreateParams, type SessionUpdateParams } from '@anthropic-ai/sdk/resources/beta/sessions/sessions';
+import { Organization } from '@anthropic-ai/sdk/resources/beta/organization/organization';
+import type { AgentExtParams, EnvironmentExtParams, SessionCreateExt, SessionUpdateExt } from './extensions.js';
+import { OrganizationProjects, type ExtensionServices } from './generated/extensions-resources.js';
+type StreamEvent = Awaited<ReturnType<Events['stream']>> extends Stream<infer T> ? T : never;
+/** client.beta.sessions.events: the official resource whose `stream` resumes a dropped connection. */
+export declare class BmaEvents extends Events {
+    /**
+     * Stream Events. Same signature and frames as the official method. When the
+     * connection drops or the server ends the stream, it reconnects with
+     * `Last-Event-ID` set to the `bma_sequence` before the one of the last frame
+     * and returns every event once. The official, non-resuming stream is
+     * `Events.prototype.stream.call(client.beta.sessions.events, ...)`.
+     */
+    stream(sessionID: string, params?: EventStreamParams | undefined, options?: RequestOptions): APIPromise<Stream<StreamEvent>>;
+}
+/** client.beta.sessions: the official resource with the typed bma_* request fields and the resuming events stream. */
+export declare class BmaSessions extends Sessions {
+    events: BmaEvents;
+    create(params: SessionCreateParams & SessionCreateExt, options?: RequestOptions): APIPromise<Beta.Sessions.BetaManagedAgentsSession>;
+    update(sessionID: string, params: SessionUpdateParams & SessionUpdateExt, options?: RequestOptions): APIPromise<Beta.Sessions.BetaManagedAgentsSession>;
+}
+/** client.beta.agents: the official resource with the typed bma_harness request field. */
+export declare class BmaAgents extends Agents {
+    create(params: AgentCreateParams & AgentExtParams, options?: RequestOptions): APIPromise<Beta.Agents.BetaManagedAgentsAgent>;
+    update(agentID: string, params: AgentUpdateParams & AgentExtParams, options?: RequestOptions): APIPromise<Beta.Agents.BetaManagedAgentsAgent>;
+}
+/** client.beta.environments: the official resource with the typed bma_desktop request field. */
+export declare class BmaEnvironments extends Environments {
+    create(params: EnvironmentCreateParams & EnvironmentExtParams, options?: RequestOptions): APIPromise<Beta.Environments.BetaEnvironment>;
+    update(environmentID: string, params: EnvironmentUpdateParams & EnvironmentExtParams, options?: RequestOptions): APIPromise<Beta.Environments.BetaEnvironment>;
+}
+/** client.beta.organization: the official resource plus `projects`. */
+export declare class BmaOrganization extends Organization {
+    projects: OrganizationProjects;
+}
+/** client.beta: the official Beta resources plus the BMA extensions. */
+export declare class BmaBeta extends Beta implements ExtensionServices {
+    agents: BmaAgents;
+    environments: BmaEnvironments;
+    sessions: BmaSessions;
+    organization: BmaOrganization;
+    machines: import("./generated/extensions-resources.js").Machines;
+    machinePools: import("./generated/extensions-resources.js").MachinePools;
+    desktopSessions: import("./generated/extensions-resources.js").DesktopSessions;
+    terminalSessions: import("./generated/extensions-resources.js").TerminalSessions;
+}
+export {};

package/dist/beta.js

@@ -0,0 +1,69 @@
+import { mergeHeaders } from './internal.js';
+import { Beta } from '@anthropic-ai/sdk/resources/beta/beta';
+import { Agents } from '@anthropic-ai/sdk/resources/beta/agents/agents';
+import { Environments, } from '@anthropic-ai/sdk/resources/beta/environments/environments';
+import { Events } from '@anthropic-ai/sdk/resources/beta/sessions/events';
+import { Sessions, } from '@anthropic-ai/sdk/resources/beta/sessions/sessions';
+import { Organization } from '@anthropic-ai/sdk/resources/beta/organization/organization';
+import { OrganizationProjects, newExtensionServices } from './generated/extensions-resources.js';
+import { resumable } from './resume.js';
+/** client.beta.sessions.events: the official resource whose `stream` resumes a dropped connection. */
+export class BmaEvents extends Events {
+    /**
+     * Stream Events. Same signature and frames as the official method. When the
+     * connection drops or the server ends the stream, it reconnects with
+     * `Last-Event-ID` set to the `bma_sequence` before the one of the last frame
+     * and returns every event once. The official, non-resuming stream is
+     * `Events.prototype.stream.call(client.beta.sessions.events, ...)`.
+     */
+    stream(sessionID, params = {}, options) {
+        const open = (lastEventID) => super.stream(sessionID, params, lastEventID ?
+            { ...options, headers: mergeHeaders([options?.headers, { 'Last-Event-ID': lastEventID }]) }
+            : options);
+        return super.stream(sessionID, params, options)._thenUnwrap((first) => resumable(first, open, this._client, options?.signal));
+    }
+}
+/** client.beta.sessions: the official resource with the typed bma_* request fields and the resuming events stream. */
+export class BmaSessions extends Sessions {
+    events = new BmaEvents(this._client);
+    create(params, options) {
+        return super.create(params, options);
+    }
+    update(sessionID, params, options) {
+        return super.update(sessionID, params, options);
+    }
+}
+/** client.beta.agents: the official resource with the typed bma_harness request field. */
+export class BmaAgents extends Agents {
+    create(params, options) {
+        return super.create(params, options);
+    }
+    update(agentID, params, options) {
+        return super.update(agentID, params, options);
+    }
+}
+/** client.beta.environments: the official resource with the typed bma_desktop request field. */
+export class BmaEnvironments extends Environments {
+    create(params, options) {
+        return super.create(params, options);
+    }
+    update(environmentID, params, options) {
+        return super.update(environmentID, params, options);
+    }
+}
+/** client.beta.organization: the official resource plus `projects`. */
+export class BmaOrganization extends Organization {
+    projects = new OrganizationProjects(this._client);
+}
+/** client.beta: the official Beta resources plus the BMA extensions. */
+export class BmaBeta extends Beta {
+    agents = new BmaAgents(this._client);
+    environments = new BmaEnvironments(this._client);
+    sessions = new BmaSessions(this._client);
+    organization = new BmaOrganization(this._client);
+    machines = newExtensionServices(this._client).machines;
+    machinePools = newExtensionServices(this._client).machinePools;
+    desktopSessions = newExtensionServices(this._client).desktopSessions;
+    terminalSessions = newExtensionServices(this._client).terminalSessions;
+}
+//# sourceMappingURL=beta.js.map

package/dist/beta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beta.js","sourceRoot":"","sources":["../src/beta.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import { Anthropic, type ClientOptions } from '@anthropic-ai/sdk';
+import { BmaBeta } from './beta.js';
+/** The hosted BMA origin (the paths carry /v1). */
+export declare const DEFAULT_BASE_URL = "https://api.bma.beeos.ai";
+export interface BmaClientOptions extends Omit<ClientOptions, 'apiKey' | 'authToken' | 'credentials' | 'config' | 'profile' | 'baseURL' | 'webhookKey'> {
+    /** The BMA API key (a tenant credential, server side only). Defaults to process.env.BMA_API_KEY. */
+    apiKey?: string | null | undefined;
+    /** The deployment origin, e.g. https://api.staging.bma.beeos.ai. Defaults to process.env.BMA_BASE_URL, else DEFAULT_BASE_URL. */
+    baseURL?: string | null | undefined;
+    /** The project scope, sent as x-bma-project-id; required when the key can see more than one project. Defaults to process.env.BMA_PROJECT_ID. */
+    project?: string | null | undefined;
+}
+/**
+ * The BMA client: the official Anthropic client with the BMA defaults, whose
+ * `beta` adds the BMA extensions. It never reads the ANTHROPIC_API_KEY,
+ * ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL or credential-profile configuration
+ * of the official client: the key defaults to BMA_API_KEY, the origin to
+ * BMA_BASE_URL and the project to BMA_PROJECT_ID.
+ *
+ * Only use it on a server: the API key is a tenant credential. End-user
+ * clients get single-use tickets instead.
+ */
+export declare class BmaClient extends Anthropic {
+    beta: BmaBeta;
+    constructor({ apiKey, baseURL, project, defaultHeaders, ...rest }?: BmaClientOptions);
+    /** A copy with other options; `project` replaces the project scope. */
+    withOptions(options: Partial<ClientOptions> & {
+        project?: string | null;
+    }): this;
+    /** Never resolve the official credential chain (profiles, federation, files). */
+    protected _shouldResolveDefaultCredentials(): boolean;
+}

package/dist/client.js

@@ -0,0 +1,50 @@
+import { Anthropic } from '@anthropic-ai/sdk';
+import { BmaBeta } from './beta.js';
+import { SDK_VERSION } from './version.js';
+/** The hosted BMA origin (the paths carry /v1). */
+export const DEFAULT_BASE_URL = 'https://api.bma.beeos.ai';
+function env(name) {
+    const value = typeof process !== 'undefined' ? process.env?.[name]?.trim() : undefined;
+    return value || undefined;
+}
+/**
+ * The BMA client: the official Anthropic client with the BMA defaults, whose
+ * `beta` adds the BMA extensions. It never reads the ANTHROPIC_API_KEY,
+ * ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL or credential-profile configuration
+ * of the official client: the key defaults to BMA_API_KEY, the origin to
+ * BMA_BASE_URL and the project to BMA_PROJECT_ID.
+ *
+ * Only use it on a server: the API key is a tenant credential. End-user
+ * clients get single-use tickets instead.
+ */
+export class BmaClient extends Anthropic {
+    beta = new BmaBeta(this);
+    constructor({ apiKey, baseURL, project, defaultHeaders, ...rest } = {}) {
+        const key = apiKey || env('BMA_API_KEY');
+        if (!key) {
+            throw new TypeError('BmaClient: set the apiKey option or the BMA_API_KEY environment variable');
+        }
+        const scope = project || undefined;
+        super({
+            ...rest,
+            apiKey: key,
+            authToken: null,
+            baseURL: baseURL || env('BMA_BASE_URL') || DEFAULT_BASE_URL,
+            defaultHeaders: {
+                'X-BMA-SDK': `bma-sdk-ts/${SDK_VERSION}`,
+                ...(env('BMA_PROJECT_ID') ? { 'x-bma-project-id': env('BMA_PROJECT_ID') } : {}),
+                ...defaultHeaders,
+                ...(scope ? { 'x-bma-project-id': scope } : {}),
+            },
+        });
+    }
+    /** A copy with other options; `project` replaces the project scope. */
+    withOptions(options) {
+        return super.withOptions(options);
+    }
+    /** Never resolve the official credential chain (profiles, federation, files). */
+    _shouldResolveDefaultCredentials() {
+        return false;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAY3D,SAAS,GAAG,CAAC,IAAY;IACvB,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACvF,OAAO,KAAK,IAAI,SAAS,CAAC;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,SAAU,SAAQ,SAAS;IAC7B,IAAI,GAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,KAAuB,EAAE;QACtF,MAAM,GAAG,GAAG,MAAM,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,SAAS,CAAC,0EAA0E,CAAC,CAAC;QAClG,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,IAAI,SAAS,CAAC;QACnC,KAAK,CAAC;YACJ,GAAG,IAAI;YACP,MAAM,EAAE,GAAG;YACX,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,OAAO,IAAI,GAAG,CAAC,cAAc,CAAC,IAAI,gBAAgB;YAC3D,cAAc,EAAE;gBACd,WAAW,EAAE,cAAc,WAAW,EAAE;gBACxC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,GAAG,CAAC,gBAAgB,CAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChF,GAAG,cAAc;gBACjB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD;SACF,CAAC,CAAC;IACL,CAAC;IAED,uEAAuE;IAC9D,WAAW,CAAC,OAA6D;QAChF,OAAO,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,iFAAiF;IAC9D,gCAAgC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/errors.d.ts

@@ -1,77 +1,8 @@
-import type { components } from "./generated/rest.js";
-/** Contract error codes; unknown future codes still type-check as strings. */
-export type ErrorCode = components["schemas"]["ErrorCode"] | (string & {});
-type AgentConfigErrorIssue = components["schemas"]["AgentConfigErrorIssue"];
-/** Base class of every error thrown by the SDK. */
-export declare class BmaError extends Error {
-    constructor(message: string, options?: {
-        cause?: unknown;
-    });
-}
-/** An error response from the API, or a request that never got one. */
-export declare class BmaApiError<TStatus extends number | undefined = number | undefined> extends BmaError {
-    /** HTTP status; undefined for connection errors and stream error frames. */
-    readonly status: TStatus;
-    readonly headers: Headers | undefined;
-    /** Stable error code from the response body. */
-    readonly code: ErrorCode | undefined;
-    /** Parsed response body, if any. */
-    readonly error: unknown;
-    /** Field-level problems for agent config validation errors. */
-    readonly issues: AgentConfigErrorIssue[] | undefined;
-    /** Current file digest for file_content_conflict / expected_digest_required. */
-    readonly currentDigest: string | undefined;
-    /** Facade extensions only: the Anthropic-style `error.type`. */
-    readonly type: string | undefined;
-    constructor(status: TStatus, body: unknown, message: string | undefined, headers: Headers | undefined, options?: {
-        cause?: unknown;
-    });
-    /** @internal */
-    static generate(status: number, body: unknown, headers: Headers): BmaApiError;
-}
-export declare class APIConnectionError extends BmaApiError<undefined> {
-    constructor({ message, cause }?: {
-        message?: string;
-        cause?: unknown;
-    });
-}
-export declare class APIConnectionTimeoutError extends APIConnectionError {
-    constructor({ message }?: {
-        message?: string;
-    });
-}
-export declare class APIUserAbortError extends BmaApiError<undefined> {
-    constructor({ message }?: {
-        message?: string;
-    });
-}
 /**
- * An `error` frame on an event stream. The stream ends after it; frames with
- * code `service_unavailable` are retried by the SDK before this is thrown.
+ * BMA's reason for an API error (`error.code` of the Anthropic error envelope,
+ * e.g. "idempotency_key_reused"), or undefined when `error` is not an API
+ * error or has no code. Branch on it rather than on the message. (The
+ * official `errorCode` property is `error.details.error_code`, which BMA does
+ * not set.)
  */
-export declare class EventStreamError extends BmaApiError<undefined> {
-    constructor(body: unknown);
-}
-export declare class BadRequestError extends BmaApiError<400> {
-}
-export declare class AuthenticationError extends BmaApiError<401> {
-}
-export declare class PermissionDeniedError extends BmaApiError<403> {
-}
-export declare class NotFoundError extends BmaApiError<404> {
-}
-export declare class RequestTimeoutError extends BmaApiError<408> {
-}
-export declare class ConflictError extends BmaApiError<409> {
-}
-export declare class ContentTooLargeError extends BmaApiError<413> {
-}
-export declare class UnprocessableEntityError extends BmaApiError<422> {
-}
-export declare class RateLimitError extends BmaApiError<429> {
-}
-export declare class InternalServerError extends BmaApiError<number> {
-}
-export declare class ServiceUnavailableError extends InternalServerError {
-}
-export {};
+export declare function errorCode(error: unknown): string | undefined;

package/dist/errors.js

@@ -1,109 +1,15 @@
-/** Base class of every error thrown by the SDK. */
-export class BmaError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = new.target.name;
-    }
-}
-/** An error response from the API, or a request that never got one. */
-export class BmaApiError extends BmaError {
-    /** HTTP status; undefined for connection errors and stream error frames. */
-    status;
-    headers;
-    /** Stable error code from the response body. */
-    code;
-    /** Parsed response body, if any. */
-    error;
-    /** Field-level problems for agent config validation errors. */
-    issues;
-    /** Current file digest for file_content_conflict / expected_digest_required. */
-    currentDigest;
-    /** Facade extensions only: the Anthropic-style `error.type`. */
-    type;
-    constructor(status, body, message, headers, options) {
-        const wire = (typeof body === "object" && body !== null ? body : {});
-        // Native API: {error: string, code}. Facade: {type: "error", error: {type, message, code}}.
-        const nested = typeof wire.error === "object" && wire.error !== null ? wire.error : undefined;
-        const code = str(nested ? nested.code : wire.code);
-        const type = nested ? str(nested.type) : undefined;
-        const detail = str(nested ? nested.message : wire.error) ?? message;
-        super(status === undefined
-            ? (message ?? detail ?? "bma: request failed")
-            : `bma: ${status} ${code ?? type ?? "unknown"}: ${detail ?? `HTTP ${status}`}`, options);
-        this.status = status;
-        this.headers = headers;
-        this.code = code;
-        this.type = type;
-        this.error = body;
-        this.issues = Array.isArray(wire.issues) ? wire.issues : undefined;
-        this.currentDigest = str(wire.current_digest);
-    }
-    /** @internal */
-    static generate(status, body, headers) {
-        const cls = STATUS_CLASSES.get(status) ?? (status >= 500 ? InternalServerError : BmaApiError);
-        return new cls(status, body, undefined, headers);
-    }
-}
-function str(value) {
-    return typeof value === "string" && value !== "" ? value : undefined;
-}
-export class APIConnectionError extends BmaApiError {
-    constructor({ message, cause } = {}) {
-        super(undefined, undefined, message ?? "bma: connection error", undefined, { cause });
-    }
-}
-export class APIConnectionTimeoutError extends APIConnectionError {
-    constructor({ message } = {}) {
-        super({ message: message ?? "bma: request timed out" });
-    }
-}
-export class APIUserAbortError extends BmaApiError {
-    constructor({ message } = {}) {
-        super(undefined, undefined, message ?? "bma: request was aborted", undefined);
-    }
-}
+import { APIError } from '@anthropic-ai/sdk';
 /**
- * An `error` frame on an event stream. The stream ends after it; frames with
- * code `service_unavailable` are retried by the SDK before this is thrown.
+ * BMA's reason for an API error (`error.code` of the Anthropic error envelope,
+ * e.g. "idempotency_key_reused"), or undefined when `error` is not an API
+ * error or has no code. Branch on it rather than on the message. (The
+ * official `errorCode` property is `error.details.error_code`, which BMA does
+ * not set.)
  */
-export class EventStreamError extends BmaApiError {
-    constructor(body) {
-        const wire = (body ?? {});
-        super(undefined, body, `bma: event stream error ${String(wire.code ?? "unknown")}: ${String(wire.error ?? "")}`, undefined);
-    }
-}
-export class BadRequestError extends BmaApiError {
-}
-export class AuthenticationError extends BmaApiError {
-}
-export class PermissionDeniedError extends BmaApiError {
-}
-export class NotFoundError extends BmaApiError {
-}
-export class RequestTimeoutError extends BmaApiError {
-}
-export class ConflictError extends BmaApiError {
-}
-export class ContentTooLargeError extends BmaApiError {
-}
-export class UnprocessableEntityError extends BmaApiError {
-}
-export class RateLimitError extends BmaApiError {
-}
-export class InternalServerError extends BmaApiError {
-}
-export class ServiceUnavailableError extends InternalServerError {
+export function errorCode(error) {
+    if (!(error instanceof APIError))
+        return undefined;
+    const code = error.error?.error?.code;
+    return typeof code === 'string' ? code : undefined;
 }
-const STATUS_CLASSES = new Map([
-    [400, BadRequestError],
-    [401, AuthenticationError],
-    [403, PermissionDeniedError],
-    [404, NotFoundError],
-    [408, RequestTimeoutError],
-    [409, ConflictError],
-    [413, ContentTooLargeError],
-    [422, UnprocessableEntityError],
-    [429, RateLimitError],
-    [503, ServiceUnavailableError],
-]);
 //# sourceMappingURL=errors.js.map