@beeos-ai/bma-sdk 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @beeos-ai/bma-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client for the BMA REST API, generated from
+[`contracts/bma/rest.openapi.yaml`](../contracts/bma/rest.openapi.yaml), plus
+the BMA extensions to the Anthropic Managed Agents API.
+
+```ts
+import { BmaClient, unwrap } from "@beeos-ai/bma-sdk";
+
+const bma = new BmaClient({ baseUrl: "https://host/api/v1", token: process.env.BMA_TOKEN! });
+const path = { orgID: "org_...", projectID: "proj_...", agentID: "agt_..." };
+
+const { session } = unwrap(
+  await bma.rest.POST("/orgs/{orgID}/projects/{projectID}/agents/{agentID}/sessions", {
+    params: { path },
+    body: { idempotency_key: "task-1", model_override: { model: "deepseek-flash", expires_with_session: true /* ... */ } },
+  }),
+);
+await bma.rest.POST("/orgs/{orgID}/projects/{projectID}/agents/{agentID}/inputs", {
+  params: { path, query: { session_id: session.id } },
+  body: { content_blocks: [{ type: "text", text: "Start." }] },
+});
+for await (const frame of bma.streamEvents({ ...path, sessionId: session.id })) {
+  console.log(frame.event, frame.sequence);
+}
+```
+
+`bma.rest` is a fully typed [openapi-fetch](https://openapi-ts.dev/openapi-fetch/)
+client for every contract operation. `streamEvents` parses the SSE stream and
+`downloadArtifact` verifies the artifact size and sha256 digest.
+
+## 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: "proj_..." });
+const ticket = await ext.getSessionDesktopStream(sessionId, { desktopSessionId, origin: location.origin });
+await ext.uploadSessionFile(sessionId, new Blob([bytes]), "report.pdf");
+const page = await ext.listSessionFiles(sessionId, { limit: 100 });
+```
+
+It also exports the extension field types `ModelConfigOverride`
+(`agent.model.api_url/api_key/api_format`), `MCPServerBMAAuth`
+(`mcp_servers[].bma_auth`), `IDEMPOTENCY_KEY_HEADER`, and `bmaSequence(event)`
+for `bma_sequence` resume cursors.
+
+The executor protocol (executor, harness and agent ends) is the separate
+package [`@beeos-ai/bma-executor-sdk`](../executor/typescript).

package/dist/facade-extensions.d.ts

@@ -0,0 +1,71 @@
+import { type Client } from "openapi-fetch";
+import type { components, paths } from "./generated/facade-extensions.js";
+export type { paths as FacadeExtensionPaths };
+export type DesktopStream = components["schemas"]["DesktopStream"];
+export type SessionFile = components["schemas"]["SessionFile"];
+export type SessionFilePage = components["schemas"]["SessionFilePage"];
+/** BMA extension: a project file mounted into a session. */
+export type FileResource = components["schemas"]["FileResource"];
+export type FileResourcePage = components["schemas"]["FileResourcePage"];
+export type DeletedSessionResource = components["schemas"]["DeletedSessionResource"];
+/** BMA extension: one downloaded session file with its response metadata. */
+export interface SessionFileContent {
+    content: Uint8Array;
+    contentType: string | null;
+    filename: string | null;
+    digest: string | null;
+}
+/** BMA extension: session `agent.model` object with a write-only credential override. */
+export type ModelConfigOverride = components["schemas"]["ModelConfigOverride"];
+/** BMA extension: `mcp_servers[].bma_auth`. */
+export type MCPServerBMAAuth = components["schemas"]["MCPServerBMAAuth"];
+/** BMA extension header forwarded on session create and send-events. */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * Returns the BMA extension `bma_sequence` of a facade session event, or
+ * undefined for preview and synthetic events. Send it as `Last-Event-ID` to
+ * resume `GET /v1/sessions/{id}/events/stream`.
+ */
+export declare function bmaSequence(event: unknown): number | undefined;
+export interface FacadeExtensionsOptions {
+    /** BMA organization API key (sent as x-api-key). */
+    apiKey: string;
+    /** Facade origin, without /v1 (for example https://api.bma.beeos.ai). */
+    baseUrl: string;
+    /** Project to operate in (x-bma-project-id); required for multi-project keys. */
+    projectId?: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** An Anthropic-style error envelope returned by a facade extension route. */
+export declare class FacadeApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code?: string;
+    constructor(status: number, body: unknown);
+}
+/** Client for the BMA extension routes of the Anthropic-compatible facade. */
+export declare class FacadeExtensionsClient {
+    readonly raw: Client<paths>;
+    constructor(options: FacadeExtensionsOptions);
+    /** BMA extension: GET /v1/sessions/{session_id}/desktop/stream. */
+    getSessionDesktopStream(sessionId: string, options: {
+        desktopSessionId: string;
+        ttlSeconds?: number;
+        origin?: string;
+    }): Promise<DesktopStream>;
+    /** BMA extension: POST /v1/sessions/{session_id}/files (multipart, at most 8 MiB). */
+    uploadSessionFile(sessionId: string, file: Blob, filename: string): Promise<SessionFile>;
+    /** BMA extension: GET /v1/sessions/{session_id}/files. */
+    listSessionFiles(sessionId: string, options?: {
+        limit?: number;
+        page?: string;
+    }): Promise<SessionFilePage>;
+    /** BMA extension: GET /v1/sessions/{session_id}/files/{file_id}/content. */
+    downloadSessionFile(sessionId: string, fileId: string): Promise<SessionFileContent>;
+    /** BMA extension: POST /v1/sessions/{session_id}/resources. */
+    addSessionResource(sessionId: string, fileId: string, mountPath?: string): Promise<FileResource>;
+    /** BMA extension: GET /v1/sessions/{session_id}/resources. */
+    listSessionResources(sessionId: string): Promise<FileResourcePage>;
+    /** BMA extension: DELETE /v1/sessions/{session_id}/resources/{resource_id}. */
+    deleteSessionResource(sessionId: string, resourceId: string): Promise<DeletedSessionResource>;
+}

package/dist/facade-extensions.js

@@ -0,0 +1,134 @@
+// BMA extensions to the Anthropic Managed Agents API.
+//
+// The standard facade routes (/v1/agents, /v1/environments, /v1/sessions,
+// events, events/stream, /v1/files, /v1/memory_stores) are served by the
+// official Anthropic SDKs pointed at a BMA deployment. Everything in this module is a
+// BMA extension that is NOT part of the Anthropic contract. Types come from
+// src/generated/facade-extensions.ts, generated from
+// contracts/bma/facade-extensions.openapi.yaml.
+import createClient from "openapi-fetch";
+function dispositionFilename(value) {
+    if (!value)
+        return null;
+    const match = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i.exec(value);
+    return match?.[1] ? decodeURIComponent(match[1]) : null;
+}
+/** BMA extension header forwarded on session create and send-events. */
+export const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * Returns the BMA extension `bma_sequence` of a facade session event, or
+ * undefined for preview and synthetic events. Send it as `Last-Event-ID` to
+ * resume `GET /v1/sessions/{id}/events/stream`.
+ */
+export function bmaSequence(event) {
+    const value = event?.bma_sequence;
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+/** An Anthropic-style error envelope returned by a facade extension route. */
+export class FacadeApiError extends Error {
+    status;
+    type;
+    code;
+    constructor(status, body) {
+        const error = (body?.error ?? {});
+        const type = typeof error.type === "string" ? error.type : "api_error";
+        const message = typeof error.message === "string" && error.message !== "" ? error.message : `HTTP ${status}`;
+        super(`bma facade: HTTP ${status} ${type}: ${message}`);
+        this.name = "FacadeApiError";
+        this.status = status;
+        this.type = type;
+        this.code = typeof error.code === "string" ? error.code : undefined;
+    }
+}
+function check(result) {
+    if (result.response.ok)
+        return result.data;
+    throw new FacadeApiError(result.response.status, result.error);
+}
+/** Client for the BMA extension routes of the Anthropic-compatible facade. */
+export class FacadeExtensionsClient {
+    raw;
+    constructor(options) {
+        const apiKey = options.apiKey?.trim();
+        if (!apiKey)
+            throw new Error("bma facade: apiKey is required");
+        const baseUrl = options.baseUrl?.trim().replace(/\/+$/, "");
+        if (!baseUrl)
+            throw new Error("bma facade: baseUrl is required");
+        if (baseUrl.endsWith("/v1"))
+            throw new Error("bma facade: baseUrl must be the origin without /v1");
+        const headers = { "x-api-key": apiKey };
+        if (options.projectId)
+            headers["x-bma-project-id"] = options.projectId;
+        this.raw = createClient({ baseUrl, headers, fetch: options.fetch ?? globalThis.fetch });
+    }
+    /** BMA extension: GET /v1/sessions/{session_id}/desktop/stream. */
+    async getSessionDesktopStream(sessionId, options) {
+        return check(await this.raw.GET("/v1/sessions/{session_id}/desktop/stream", {
+            params: {
+                path: { session_id: sessionId },
+                query: {
+                    desktop_session_id: options.desktopSessionId,
+                    ttl_seconds: options.ttlSeconds,
+                    origin: options.origin,
+                },
+            },
+        }));
+    }
+    /** BMA extension: POST /v1/sessions/{session_id}/files (multipart, at most 8 MiB). */
+    async uploadSessionFile(sessionId, file, filename) {
+        const form = new FormData();
+        form.append("file", file, filename);
+        return check(await this.raw.POST("/v1/sessions/{session_id}/files", {
+            params: { path: { session_id: sessionId } },
+            // The generated body type is the schema object; the wire body is FormData.
+            body: form,
+            bodySerializer: (body) => body,
+        }));
+    }
+    /** BMA extension: GET /v1/sessions/{session_id}/files. */
+    async listSessionFiles(sessionId, options = {}) {
+        return check(await this.raw.GET("/v1/sessions/{session_id}/files", {
+            params: { path: { session_id: sessionId }, query: { limit: options.limit, page: options.page } },
+        }));
+    }
+    /** BMA extension: GET /v1/sessions/{session_id}/files/{file_id}/content. */
+    async downloadSessionFile(sessionId, fileId) {
+        const result = await this.raw.GET("/v1/sessions/{session_id}/files/{file_id}/content", {
+            params: { path: { session_id: sessionId, file_id: fileId } },
+            parseAs: "arrayBuffer",
+        });
+        if (!result.response.ok)
+            throw new FacadeApiError(result.response.status, result.error);
+        return {
+            content: new Uint8Array(result.data),
+            contentType: result.response.headers.get("content-type"),
+            filename: dispositionFilename(result.response.headers.get("content-disposition")),
+            digest: result.response.headers.get("x-bma-file-digest"),
+        };
+    }
+    /** BMA extension: POST /v1/sessions/{session_id}/resources. */
+    async addSessionResource(sessionId, fileId, mountPath) {
+        return check(await this.raw.POST("/v1/sessions/{session_id}/resources", {
+            params: { path: { session_id: sessionId } },
+            body: {
+                type: "file",
+                file_id: fileId,
+                ...(mountPath === undefined ? {} : { mount_path: mountPath }),
+            },
+        }));
+    }
+    /** BMA extension: GET /v1/sessions/{session_id}/resources. */
+    async listSessionResources(sessionId) {
+        return check(await this.raw.GET("/v1/sessions/{session_id}/resources", {
+            params: { path: { session_id: sessionId } },
+        }));
+    }
+    /** BMA extension: DELETE /v1/sessions/{session_id}/resources/{resource_id}. */
+    async deleteSessionResource(sessionId, resourceId) {
+        return check(await this.raw.DELETE("/v1/sessions/{session_id}/resources/{resource_id}", {
+            params: { path: { session_id: sessionId, resource_id: resourceId } },
+        }));
+    }
+}
+//# sourceMappingURL=facade-extensions.js.map

package/dist/facade-extensions.js.map

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