@anchrd/colab-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# @anchrd/colab-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.
+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
+
+```sh
+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
+a person's Colab token once per request and decides locally what the person may call:
+
+```ts
+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.