@caltra/backend-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# Caltra backend 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.
+Define tools in your TypeScript backend and serve them to Caltra through an outbound authenticated WebSocket. Handler code and application data remain on your backend. The public client is `CaltraBackendClient`.
+
+## Install
+
+Requires Node.js 24 or newer. This package is ESM.
+
+```sh
+mkdir caltra-backend && cd caltra-backend
+npm init -y
+npm pkg set type=module
+npm install @caltra/backend-sdk zod
+npm install --save-dev typescript tsx @types/node
+cp node_modules/@caltra/backend-sdk/examples/quickstart.ts quickstart.ts
+```
+
+In Caltra, open **Backends → Add backend**. Restrict its workspace availability, then save the backend ID and one-time credential. All replicas share those credentials.
+
+Create `backend.config.json` using your backend ID and credential:
+
+```json
+{
+  "url": "wss://api.caltra.dev/backends/v1/connect",
+  "backendId": "REPLACE_WITH_BACKEND_UUID",
+  "credential": "REPLACE_WITH_BACKEND_CREDENTIAL",
+  "label": "example-replica-1"
+}
+```
+
+Keep the credential in your secret manager, restrict permissions on the configuration file, and exclude it from source control. The executable [quickstart](examples/quickstart.ts) validates this configuration before connecting. It defines a harmless `diagnostics.echo` tool returning a message, trusted workspace ID, and replica label.
+
+```sh
+chmod 600 backend.config.json
+npx tsc --noEmit --strict --target ES2022 --module NodeNext --moduleResolution NodeNext quickstart.ts
+# Publish once when deploying new definitions.
+npx tsx quickstart.ts publish backend.config.json
+# Start each replica separately; Ctrl-C closes its connection.
+npx tsx quickstart.ts serve backend.config.json
+```
+
+In **Backends → Tools**, call `diagnostics.echo` with `{"message":"hello"}` in an allowed workspace. Expect the same message, that workspace's ID, and `example-replica-1`. For a hosted agent, grant the tool to its execution principal under **Access**, then ask the agent to discover and call it. Revoke the grant to deny subsequent calls, including an already discovered action ID.
+
+## API
+
+```ts
+import { BackendTool, CaltraBackendClient, type ToolContext } from "@caltra/backend-sdk";
+```
+
+- `BackendTool` takes a name, description, Zod input/output schemas, and `handler(context, inputs)`. Use JSON-Schema-compatible Zod schemas. Input and output validation happens locally and on Caltra.
+- `new CaltraBackendClient({ url, backendId, credential, label, tools, maxConcurrency? })` creates a client. Default concurrency is 1; supported values are 1–100.
+- `publish()` explicitly publishes definitions and returns `{ id, version, hash }`. It opens and closes its own connection. Identical current definitions reuse the version.
+- `connect()` registers one replica against matching, already-published definitions. It returns `{ instanceId, manifest, heartbeatMs }` and starts transport heartbeats.
+- `waitForDisconnect()` waits for that serving connection to close. The SDK does not reconnect automatically.
+- `close()` closes the serving connection and waits for disconnect.
+
+The URL must use `wss://`; `ws://` is allowed only for loopback development. Credentials belong in authentication headers, never the URL. A proxy must support WebSocket upgrades and long-lived connections.
+
+`ToolContext` carries trusted organization, workspace, environment, principal, invocation ID and deadline. Hosted calls also include principal, session, turn and agent IDs. Tool inputs cannot replace these fields. Enforce your application's business permissions using the trusted context.
+
+Caltra routes each call to one available matching-manifest replica and rechecks current access at dispatch. There is no cancellation API or automatic execution retry. A timeout/disconnect can leave the outcome unknown; your handler may continue. Deduplicate business writes using your own operation key before retrying. A newer manifest can temporarily make older replicas unavailable; publish deliberately and start matching replicas.
+
+See the [backend tools documentation](https://caltra.dev/docs/backend-tools) for grants, version rollout, context, limits and wire protocol. The `/protocol` and `/peer` exports support protocol integrations; ordinary applications need only the package root.

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { type ManifestVersion, type Registration } from "./protocol.js";
+import type { ToolRegistration } from "./tool.js";
+/** Publishes definitions explicitly and serves one replica on an outbound, authenticated socket. */
+export declare class CaltraBackendClient {
+    private readonly options;
+    private peer?;
+    private registration?;
+    private heartbeat?;
+    private readonly calls;
+    private readonly seen;
+    private closed;
+    private readonly manifest;
+    constructor(options: {
+        url: string;
+        backendId: string;
+        credential: string;
+        tools: ToolRegistration[];
+        label: string;
+        maxConcurrency?: number;
+    });
+    publish(): Promise<ManifestVersion>;
+    connect(): Promise<Registration>;
+    waitForDisconnect(): Promise<void>;
+    close(): Promise<void>;
+    private open;
+    private scheduleHeartbeat;
+    private invoke;
+}

package/dist/client.js

@@ -0,0 +1,105 @@
+import { WebSocket } from "ws";
+import { JSONRPCErrorException } from "json-rpc-2.0";
+import { z } from "zod";
+import { BackendProtocol, CallSchema, ManifestVersionSchema, RegistrationSchema } from "./protocol.js";
+import { BackendRpcPeer } from "./peer.js";
+/** Publishes definitions explicitly and serves one replica on an outbound, authenticated socket. */
+export class CaltraBackendClient {
+    options;
+    peer;
+    registration;
+    heartbeat;
+    calls = new Set();
+    seen = new Set();
+    closed = Promise.resolve();
+    manifest;
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.url);
+        if (url.protocol !== "wss:" && !(url.protocol === "ws:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+            throw new Error("Use wss:// (ws:// is allowed only on loopback).");
+        if (url.username || url.password || url.search || url.hash)
+            throw new Error("Connection URL must not contain credentials, query parameters or fragments.");
+        z.string().uuid().parse(options.backendId);
+        this.manifest = options.tools.map(tool => tool.manifest);
+        BackendProtocol.hash(this.manifest);
+    }
+    async publish() {
+        const peer = await this.open();
+        try {
+            return ManifestVersionSchema.parse(await peer.request("manifests/publish", { tools: this.manifest }));
+        }
+        finally {
+            peer.close();
+        }
+    }
+    async connect() {
+        if (this.peer)
+            throw new Error("This client is already connected.");
+        const peer = await this.open();
+        this.peer = peer;
+        this.closed = new Promise(resolve => peer.socket.once("close", () => {
+            if (this.peer === peer) {
+                this.peer = undefined;
+                this.registration = undefined;
+            }
+            clearTimeout(this.heartbeat);
+            resolve();
+        }));
+        peer.method("tools/call", params => this.invoke(params));
+        try {
+            this.registration = RegistrationSchema.parse(await peer.request("instances/register", {
+                protocolVersion: 1, manifestHash: BackendProtocol.hash(this.manifest), label: this.options.label, maxConcurrency: this.options.maxConcurrency ?? 1,
+            }));
+            this.scheduleHeartbeat(peer);
+            return this.registration;
+        }
+        catch (error) {
+            peer.close();
+            throw error;
+        }
+    }
+    waitForDisconnect() { return this.closed; }
+    async close() { clearTimeout(this.heartbeat); this.peer?.close(); await this.closed; }
+    async open() {
+        const socket = new WebSocket(this.options.url, { headers: { authorization: `Bearer ${this.options.credential}`, "x-caltra-backend-id": this.options.backendId }, maxPayload: BackendProtocol.maxBytes, handshakeTimeout: 10000, followRedirects: false });
+        const peer = new BackendRpcPeer(socket);
+        await new Promise((resolve, reject) => { socket.once("open", resolve); socket.once("error", () => reject(new Error("Backend connection failed; check URL and credential."))); });
+        return peer;
+    }
+    scheduleHeartbeat(peer) {
+        // This timer observes a live transport; PostgreSQL lease expiry remains authoritative after a crash.
+        this.heartbeat = setTimeout(() => {
+            void peer.request("instances/heartbeat", {}, 5000).then(() => {
+                if (this.peer === peer && peer.socket.readyState === WebSocket.OPEN)
+                    this.scheduleHeartbeat(peer);
+            }).catch(() => peer.close());
+        }, this.registration.heartbeatMs);
+    }
+    async invoke(params) {
+        const call = CallSchema.parse(params);
+        if (!this.registration || call.manifestVersion !== this.registration.manifest.version)
+            throw new JSONRPCErrorException("Manifest mismatch.", -32001);
+        const tool = this.options.tools.find(tool => tool.manifest.name === call.name);
+        if (!tool)
+            throw new JSONRPCErrorException("Tool not found.", -32601);
+        if (this.seen.has(call.invocationId))
+            throw new JSONRPCErrorException("Duplicate invocation.", -32002);
+        if (this.calls.size >= (this.options.maxConcurrency ?? 1))
+            throw new JSONRPCErrorException("Instance is busy.", -32003);
+        const remaining = Date.parse(call.deadline) - Date.now();
+        if (remaining <= 0)
+            throw new JSONRPCErrorException("Deadline expired.", -32004);
+        this.seen.add(call.invocationId);
+        if (this.seen.size > 10000)
+            this.seen.delete(this.seen.values().next().value);
+        this.calls.add(call.invocationId);
+        // A disconnected or timed-out call can still be running; retain its capacity until the handler finishes.
+        try {
+            return await tool.invoke({ ...call.context, invocationId: call.invocationId, deadline: new Date(call.deadline) }, call.inputs);
+        }
+        finally {
+            this.calls.delete(call.invocationId);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { CaltraBackendClient } from "./client.js";
+export { BackendTool } from "./tool.js";
+export type { ToolRegistration } from "./tool.js";
+export type { ToolContext, ManifestVersion, Registration } from "./protocol.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CaltraBackendClient } from "./client.js";
+export { BackendTool } from "./tool.js";

package/dist/peer.d.ts

@@ -0,0 +1,14 @@
+import { WebSocket } from "ws";
+/** Binds the JSON-RPC library to bounded text frames and rejects pending requests on disconnect. */
+export declare class BackendRpcPeer {
+    readonly socket: WebSocket;
+    private readonly server;
+    private readonly client;
+    private readonly peer;
+    private inFlight;
+    constructor(socket: WebSocket);
+    method(name: string, handler: (params: unknown) => Promise<unknown>): void;
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    close(): void;
+    private send;
+}

package/dist/peer.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { JSONRPCClient, JSONRPCServer, JSONRPCServerAndClient, JSONRPCErrorException, createJSONRPCErrorResponse } from "json-rpc-2.0";
+import { WebSocket } from "ws";
+import { BackendProtocol } from "./protocol.js";
+/** Binds the JSON-RPC library to bounded text frames and rejects pending requests on disconnect. */
+export class BackendRpcPeer {
+    socket;
+    server = new JSONRPCServer({ errorListener: () => undefined });
+    client;
+    peer;
+    inFlight = 0;
+    constructor(socket) {
+        this.socket = socket;
+        this.client = new JSONRPCClient(async (request) => this.send(request), () => randomUUID());
+        this.peer = new JSONRPCServerAndClient(this.server, this.client, { errorListener: () => undefined });
+        socket.on("message", (data, binary) => {
+            if (binary || Buffer.byteLength(data.toString()) > BackendProtocol.maxBytes || this.inFlight >= 128) {
+                socket.close(1008, "Invalid frame or too many requests");
+                return;
+            }
+            let payload;
+            try {
+                payload = JSON.parse(data.toString());
+            }
+            catch {
+                void this.send(createJSONRPCErrorResponse(null, -32700, "Parse error")).catch(() => socket.terminate());
+                return;
+            }
+            if (Array.isArray(payload)) {
+                void this.send(createJSONRPCErrorResponse(null, -32600, "Batch requests are not supported.")).catch(() => socket.terminate());
+                return;
+            }
+            this.inFlight++;
+            void this.peer.receiveAndSend(payload).catch(() => socket.close(1008, "Invalid RPC message")).finally(() => this.inFlight--);
+        });
+        socket.on("error", () => this.client.rejectAllPendingRequests("Backend disconnected; invocation outcome may be unknown."));
+        socket.on("close", () => this.client.rejectAllPendingRequests("Backend disconnected; invocation outcome may be unknown."));
+    }
+    method(name, handler) {
+        this.server.addMethod(name, async (params) => {
+            try {
+                return await handler(params);
+            }
+            catch (error) {
+                if (error instanceof JSONRPCErrorException)
+                    throw error;
+                if (error instanceof z.ZodError)
+                    throw new JSONRPCErrorException("Invalid parameters or tool data.", -32602);
+                throw new JSONRPCErrorException("Request could not be completed.", -32000);
+            }
+        });
+    }
+    async request(method, params, timeoutMs = BackendProtocol.callTimeoutMs) {
+        return this.client.timeout(timeoutMs, id => createJSONRPCErrorResponse(id, -32015, "Backend RPC timed out; invocation outcome may be unknown. Do not automatically retry.")).request(method, params);
+    }
+    close() { this.socket.close(1000, "Closed"); }
+    async send(value) {
+        const data = JSON.stringify(value);
+        if (this.socket.readyState !== WebSocket.OPEN)
+            throw new Error("Backend connection is closed.");
+        if (Buffer.byteLength(data) > BackendProtocol.maxBytes || this.socket.bufferedAmount > BackendProtocol.maxBytes)
+            throw new Error("RPC payload or buffered data exceeds limit.");
+        await new Promise((resolve, reject) => this.socket.send(data, error => error ? reject(error) : resolve()));
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+export declare const ToolManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const ManifestSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>>;
+export declare const ManifestVersionSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+    hash: z.ZodString;
+}, z.core.$strip>;
+export declare const RegisterSchema: z.ZodObject<{
+    protocolVersion: z.ZodLiteral<1>;
+    manifestHash: z.ZodString;
+    label: z.ZodString;
+    maxConcurrency: z.ZodNumber;
+}, z.core.$strict>;
+export declare const RegistrationSchema: z.ZodObject<{
+    instanceId: z.ZodString;
+    manifest: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodNumber;
+        hash: z.ZodString;
+    }, z.core.$strip>;
+    heartbeatMs: z.ZodNumber;
+}, z.core.$strip>;
+export declare const CallContextSchema: z.ZodUnion<readonly [z.ZodObject<{
+    organizationId: z.ZodString;
+    workspaceId: z.ZodString;
+    environmentId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodLiteral<"platform_user">;
+        id: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    organizationId: z.ZodString;
+    workspaceId: z.ZodString;
+    environmentId: z.ZodString;
+    principalId: z.ZodString;
+    principal: z.ZodObject<{
+        kind: z.ZodEnum<{
+            tenant_user: "tenant_user";
+            agent_identity: "agent_identity";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    sessionId: z.ZodString;
+    turnId: z.ZodString;
+    agentIdentityId: z.ZodNullable<z.ZodString>;
+    agentId: z.ZodString;
+}, z.core.$strict>]>;
+export declare const CallSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    manifestVersion: z.ZodNumber;
+    name: z.ZodString;
+    inputs: z.ZodUnknown;
+    context: z.ZodUnion<readonly [z.ZodObject<{
+        organizationId: z.ZodString;
+        workspaceId: z.ZodString;
+        environmentId: z.ZodString;
+        principal: z.ZodObject<{
+            kind: z.ZodLiteral<"platform_user">;
+            id: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        organizationId: z.ZodString;
+        workspaceId: z.ZodString;
+        environmentId: z.ZodString;
+        principalId: z.ZodString;
+        principal: z.ZodObject<{
+            kind: z.ZodEnum<{
+                tenant_user: "tenant_user";
+                agent_identity: "agent_identity";
+                system: "system";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        sessionId: z.ZodString;
+        turnId: z.ZodString;
+        agentIdentityId: z.ZodNullable<z.ZodString>;
+        agentId: z.ZodString;
+    }, z.core.$strict>]>;
+    deadline: z.ZodString;
+}, z.core.$strict>;
+export type ToolManifest = z.infer<typeof ToolManifestSchema>;
+export type ManifestVersion = z.infer<typeof ManifestVersionSchema>;
+export type Registration = z.infer<typeof RegistrationSchema>;
+export type ToolCall = z.infer<typeof CallSchema>;
+export type ToolContext = z.infer<typeof CallContextSchema> & {
+    invocationId: string;
+    deadline: Date;
+};
+/** Defines the version-one wire contract and a stable digest independent of JSON object key order. */
+export declare class BackendProtocol {
+    static readonly path = "/backends/v1/connect";
+    static readonly maxBytes: number;
+    static readonly heartbeatMs = 10000;
+    static readonly leaseMs = 35000;
+    static readonly callTimeoutMs = 15000;
+    static hash(tools: ToolManifest[]): string;
+    private static canonical;
+}

package/dist/protocol.js

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const ToolManifestSchema = z.object({
+    name: z.string().min(1).max(128).regex(/^[A-Za-z0-9_.-]+$/u),
+    description: z.string().max(10000),
+    inputSchema: z.record(z.string(), z.unknown()),
+    outputSchema: z.record(z.string(), z.unknown()),
+}).strict();
+export const ManifestSchema = z.array(ToolManifestSchema).max(100).superRefine((tools, context) => {
+    if (new Set(tools.map(tool => tool.name)).size !== tools.length)
+        context.addIssue({ code: "custom", message: "Duplicate tool names." });
+});
+export const ManifestVersionSchema = z.object({ id: z.string().uuid(), version: z.number().int().positive(), hash: z.string().length(64) });
+export const RegisterSchema = z.object({ protocolVersion: z.literal(1), manifestHash: z.string().length(64), label: z.string().min(1).max(100).regex(/\S/u), maxConcurrency: z.number().int().min(1).max(100) }).strict();
+export const RegistrationSchema = z.object({ instanceId: z.string().uuid(), manifest: ManifestVersionSchema, heartbeatMs: z.number().int().positive() });
+const ContextScope = z.object({
+    organizationId: z.string().uuid(), workspaceId: z.string().uuid(), environmentId: z.string().uuid(),
+});
+export const CallContextSchema = z.union([z.object({
+        organizationId: z.string().uuid(), workspaceId: z.string().uuid(), environmentId: z.string().uuid(),
+        principal: z.object({ kind: z.literal("platform_user"), id: z.string().uuid() }).strict(),
+    }).strict(), ContextScope.extend({
+        principalId: z.string().uuid(), principal: z.object({ kind: z.enum(["tenant_user", "agent_identity", "system"]), id: z.string().uuid() }).strict(),
+        sessionId: z.string().uuid(), turnId: z.string().uuid(), agentIdentityId: z.string().uuid().nullable(), agentId: z.string().uuid(),
+    }).strict()]);
+export const CallSchema = z.object({
+    invocationId: z.string().uuid(), manifestVersion: z.number().int().positive(), name: z.string(),
+    inputs: z.unknown(), context: CallContextSchema, deadline: z.string().datetime(),
+}).strict();
+/** Defines the version-one wire contract and a stable digest independent of JSON object key order. */
+export class BackendProtocol {
+    static path = "/backends/v1/connect";
+    static maxBytes = 1024 * 1024;
+    static heartbeatMs = 10000;
+    static leaseMs = 35000;
+    static callTimeoutMs = 15000;
+    static hash(tools) {
+        return createHash("sha256").update(JSON.stringify(this.canonical([...ManifestSchema.parse(tools)].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)))).digest("hex");
+    }
+    static canonical(value) {
+        if (Array.isArray(value))
+            return value.map(item => this.canonical(item));
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, this.canonical(item)]));
+        return value;
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { ToolContext, ToolManifest } from "./protocol.js";
+export type ToolRegistration = {
+    manifest: ToolManifest;
+    invoke(context: ToolContext, inputs: unknown): Promise<unknown>;
+};
+/** Keeps executable code local while exporting the same schemas used to validate each invocation. */
+export declare class BackendTool<I extends z.ZodType, O extends z.ZodType> implements ToolRegistration {
+    private readonly definition;
+    readonly manifest: ToolManifest;
+    constructor(definition: {
+        name: string;
+        description: string;
+        input: I;
+        output: O;
+        handler(context: ToolContext, inputs: z.output<I>): Promise<z.input<O>>;
+    });
+    invoke(context: ToolContext, inputs: unknown): Promise<unknown>;
+}

package/dist/tool.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** Keeps executable code local while exporting the same schemas used to validate each invocation. */
+export class BackendTool {
+    definition;
+    manifest;
+    constructor(definition) {
+        this.definition = definition;
+        this.manifest = { name: definition.name, description: definition.description,
+            inputSchema: z.toJSONSchema(definition.input, { io: "input" }), outputSchema: z.toJSONSchema(definition.output, { io: "output" }) };
+    }
+    async invoke(context, inputs) {
+        const parsed = this.definition.input.parse(inputs);
+        return this.definition.output.parse(await this.definition.handler(context, parsed));
+    }
+}

package/examples/quickstart.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { BackendTool, CaltraBackendClient } from "@caltra/backend-sdk";
+import { z } from "zod";
+
+/** Loads validated deployment configuration and serves a harmless tool without accessing application data. */
+class BackendQuickstart {
+  async run(command: string, configPath: string): Promise<void> {
+    if (command !== "publish" && command !== "serve") throw new Error("Use publish or serve, followed by a config file path.");
+    const config = z.object({
+      url: z.url(), backendId: z.uuid(), credential: z.string().min(1), label: z.string().min(1),
+    }).strict().parse(JSON.parse(readFileSync(configPath, "utf8")));
+    const backend = new CaltraBackendClient({
+      ...config,
+      tools: [new BackendTool({
+        name: "diagnostics.echo",
+        description: "Echo a test message with the trusted workspace and serving replica.",
+        input: z.object({ message: z.string().min(1) }).strict(),
+        output: z.object({ message: z.string(), workspaceId: z.uuid(), handledBy: z.string() }).strict(),
+        handler: async (context, inputs) => ({ message: inputs.message, workspaceId: context.workspaceId, handledBy: config.label }),
+      })],
+    });
+    if (command === "publish") {
+      process.stdout.write(`${JSON.stringify(await backend.publish())}\n`);
+      return;
+    }
+    process.once("SIGINT", () => { void backend.close(); });
+    process.once("SIGTERM", () => { void backend.close(); });
+    try {
+      process.stdout.write(`${JSON.stringify(await backend.connect())}\n`);
+      await backend.waitForDisconnect();
+    } finally { await backend.close(); }
+  }
+}
+
+await new BackendQuickstart().run(process.argv[2] ?? "", process.argv[3] ?? "backend.config.json");

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@caltra/backend-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./peer": {
+      "types": "./dist/peer.d.ts",
+      "import": "./dist/peer.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "json-rpc-2.0": "1.8.1",
+    "ws": "8.22.0",
+    "zod": "^4.4.3",
+    "@types/ws": "8.18.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  },
+  "description": "TypeScript backend tools for Caltra over outbound authenticated WebSockets",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "examples/quickstart.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caltra-dev/caltra.git",
+    "directory": "packages/backend-sdk"
+  },
+  "homepage": "https://caltra.dev/docs/backend-tools",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}