@beeos-ai/bma-sdk 1.0.1 → 2.1.0

package/README.md

@@ -2,151 +2,92 @@
 
 [![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.1.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
-
-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
-  },
+// Or send first: sendAndStream opens the stream at the cursor read before the
+// send (bma_resume_cursor), so frames an executor wrote before the stream
+// opened are not lost. `replayed` is true when the server gave no cursor and
+// the stream starts at Last-Event-ID 0 (pick your turn by bma_input_id).
+const { sent, stream: turn } = await client.beta.sessions.events.sendAndStream(session.id, {
+  events: [{ type: "user.message", content: [{ type: "text", text: "Next step." }] }],
 });
-// 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();
-```
 
-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.
+// 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
 
-## 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";
+try {
+  await client.beta.machines.retrieve("mch_x");
+} catch (err) {
+  console.log(errorCode(err)); // BMA's error.code, e.g. "machine_not_found"
+}
+```
 
-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,79 @@
+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 EventSendParams, 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;
+/** The result of `sendAndStream`. */
+export interface SentStream {
+    /** The send response. */
+    sent: Awaited<ReturnType<Events['send']>>;
+    /** Starts at the cursor read before the send: its first frames are the sent `user.message` and its turn. */
+    stream: Stream<StreamEvent>;
+    /** True when the server gave no `bma_resume_cursor` for a `user.message`: the stream replays from `Last-Event-ID: 0`. */
+    replayed: boolean;
+}
+/** 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>>;
+    /**
+     * Send events, then open the resuming stream at the cursor the send
+     * returned (`bma_resume_cursor`: the session's last sequence before the
+     * send), so a frame an executor wrote before the stream opened is not lost.
+     * The official pattern, a stream opened before the send, needs no cursor;
+     * this one is for a caller that sends first. Without a cursor for a
+     * `user.message` the stream starts at `Last-Event-ID: 0` and `replayed` is
+     * true: it replays the session from its first event, so it can carry events
+     * that precede the send; pick this one's turn by `bma_input_id`. A send
+     * with no `user.message` streams from the server's default position (new
+     * events only). A send error rejects with no stream; an error opening the
+     * stream rejects too, after the message was accepted.
+     */
+    sendAndStream(sessionID: string, body: EventSendParams, params?: EventStreamParams | undefined, options?: RequestOptions): Promise<SentStream>;
+    private openStream;
+}
+/** 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,107 @@
+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';
+function withLastEventID(options, lastEventID) {
+    return lastEventID === undefined ? options : ({ ...options, headers: mergeHeaders([options?.headers, { 'Last-Event-ID': lastEventID }]) });
+}
+/** The Last-Event-ID for a stream opened after a send: the smallest `bma_resume_cursor` of the response's
+ * `user.message` events; 0 and `replayed` when one has none; undefined without a `user.message`. */
+function resumeCursor(sent) {
+    let after;
+    for (const event of (sent.data ?? [])) {
+        if (event.type !== 'user.message')
+            continue;
+        if (typeof event.bma_resume_cursor !== 'number')
+            return { after: 0, replayed: true };
+        after = after === undefined ? event.bma_resume_cursor : Math.min(after, event.bma_resume_cursor);
+    }
+    return { after, replayed: false };
+}
+/** 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) {
+        return this.openStream(sessionID, params, options);
+    }
+    /**
+     * Send events, then open the resuming stream at the cursor the send
+     * returned (`bma_resume_cursor`: the session's last sequence before the
+     * send), so a frame an executor wrote before the stream opened is not lost.
+     * The official pattern, a stream opened before the send, needs no cursor;
+     * this one is for a caller that sends first. Without a cursor for a
+     * `user.message` the stream starts at `Last-Event-ID: 0` and `replayed` is
+     * true: it replays the session from its first event, so it can carry events
+     * that precede the send; pick this one's turn by `bma_input_id`. A send
+     * with no `user.message` streams from the server's default position (new
+     * events only). A send error rejects with no stream; an error opening the
+     * stream rejects too, after the message was accepted.
+     */
+    async sendAndStream(sessionID, body, params = {}, options) {
+        const sent = await this.send(sessionID, body, options);
+        const { after, replayed } = resumeCursor(sent);
+        const stream = await this.openStream(sessionID, params, options, after);
+        return { sent, stream, replayed };
+    }
+    openStream(sessionID, params, options, after) {
+        const open = (lastEventID) => super.stream(sessionID, params, withLastEventID(options, lastEventID));
+        return super
+            .stream(sessionID, params, withLastEventID(options, after === undefined ? undefined : String(after)))
+            ._thenUnwrap((first) => resumable(first, open, this._client, options?.signal, after));
+    }
+}
+/** 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;