@anchrd/colab-sdk

The contract of Colab: TypeScript types and Zod schemas for everything that crosses between Colab's UI, its backends and outside services, and the client an outside service uses to ask a Colab installation who a person is and what they may do.

It carries no server framework and reads no environment; its only dependencies are zod and ulid. It is released together with @anchrd/colab under the same version number: use the @anchrd/colab-sdk whose version equals the @anchrd/colab your installation runs.

Install

npm install @anchrd/colab-sdk

ES modules only, with type declarations.

What it exports

• Schemas and their types, one name each, for the input and answer of every tool of Colab's API and MCP. A schema is named after its tool: access_invitation_create takes InvitationCreateInput, access_user_list takes UserListInput. The schema validates at runtime (UserListInput.parse(body)), the type of the same name describes the parsed value.
• Ids: idSchema(resource) accepts only an id of that resource (user_01J…, node_01J…), and createId(resource) makes one.
• The error shape ErrorResponse: { error: { code, message } }, with code one of not_found, invalid, conflict, unauthenticated and unavailable (errorCodes).
• The naming grammar: every capability has one three-part name, package · resource · action, and toolRoute, toolPermission and toolEvent derive its route, right and protocol event.
• createServiceClient, the client of an outside service.

The service client

A service registered under Settings › Services holds a service key. With it, the service checks the caller's token once per request and decides locally what they may call. Colab accepts only a token it issued for this service (an Operator's, or a person's for the service's OAuth resource); a Colab session and a token for Colab's own /mcp get 401:

import { createServiceClient } from "@anchrd/colab-sdk";

const colab = createServiceClient({
  url: "https://<customer>.anchrd.sh",
  serviceKey: process.env.COLAB_SERVICE_KEY,
});

// Declare the service's interfaces once; they become rights under Settings › Roles.
await colab.interfaces.set("reports", ["read", "export"]);

// Once per request, with the person's token.
const answer = await colab.authorize(token);
if (answer.ok && answer.can("reports", "export")) {
  // answer.identity names the person or machine
}

can() decides on the rules that came back, without another call. Every failure is a result with ok: false, status and error, never a thrown error, and every answer is validated against the schemas above. The client uses the standard fetch, so it runs in Workers, Node, Bun and the browser; fetch and timeoutMs can be passed in.

The service key is a secret: it travels only in the authorization header. Keep it out of logs and answers.

License

UNLICENSED.