@rool-dev/sdk 2.0.0-dev.4adc2c2 → 2.0.0-dev.69ff8af

package/README.md

@@ -1,6 +1,18 @@
-# Rool SDK
+<p align="center" class="sdk-brand">
+  <a href="https://rool.dev">
+    <img class="sdk-brand-logo" src="./assets/rool-logo.svg" alt="Rool logo" width="44" height="44">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./assets/rool-wordmark-dark.svg">
+      <img class="sdk-brand-wordmark" src="./assets/rool-wordmark.svg" alt="Rool" width="128">
+    </picture>
+  </a>
+</p>
 
-TypeScript SDK for Rool Machines.
+<h1 align="center" class="sdk-title">TypeScript SDK</h1>
+
+The official TypeScript SDK for building apps and automations with [Rool Machines](https://rool.dev).
+
+A Rool Machine is a persistent cloud VM with snapshots, files, and embedded AI agents. The SDK provides one typed interface for authentication, machine management, file access, agent conversations, and live updates.
 
 ## Installation
 
@@ -8,144 +20,18 @@ TypeScript SDK for Rool Machines.
 npm install @rool-dev/sdk
 ```
 
-## User and session API
-
-```typescript
-import { RoolClient } from "@rool-dev/sdk";
-
-const client = new RoolClient({
-  getTokens: () => ({
-    accessToken: currentAccessToken,
-    roolToken: currentRoolToken,
-  }),
-});
-
-const session = await client.getSession();
-const account = await client.getAccount();
-const profile = await client.getProfile();
-const userAppData = await client.getUserAppData();
-const greeting = await client.getGreeting("en");
-
-await client.replaceProfile({
-  name: "Ada",
-  marketingOptIn: true,
-});
-await client.setUserAppData("theme", "dark");
-await client.deleteUserAppData("theme");
-await client.deleteAccount();
-```
-
-`UserAppData` is an opaque cross-device JSON object. App data is changed one key at a time so unrelated settings cannot overwrite each other.
-
-## Account events
-
-```typescript
-const unsubscribe = client.events.subscribe(async (event) => {
-  if (event.type === "session") {
-    renderSession(event.session);
-  } else if (event.type === "account_changed") {
-    renderAccount(await client.getAccount());
-  } else if (event.type === "profile_changed") {
-    renderProfile(await client.getProfile());
-  } else if (event.type === "user_app_data_changed") {
-    renderUserAppData(await client.getUserAppData());
-  } else if (event.type === "machines_changed") {
-    renderMachines(await client.listMachines());
-  } else if (event.type === "machine_members_changed") {
-    renderMembers(
-      event.machineId,
-      await client.machine(event.machineId).members.list(),
-    );
-  }
-});
-
-unsubscribe();
-```
-
-Account events tell the client when something changed. Fetch the relevant route to get the latest data. The SDK starts with `/v2/session`, then long-polls for changes using its account sync token. Empty polls and network retries do not produce events or refresh the session. If a token expires, the SDK fetches a new session and sends another `session` event.
-
-`getTokens` may return tokens synchronously or asynchronously. The SDK sends the access token as `Authorization: Bearer …` and the Rool token as `X-Rool-Token`. Bearer-only integrations can use `getAccessToken` instead. Use `apiUrl` to target a non-production server and `fetch` to provide a custom transport.
-
-## Authentication
-
-Auth clients own login, credential storage, and refresh. `RoolClient` only asks one for tokens and tells it when authentication is invalidated.
-
-### Browser authentication
-
-```typescript
-import { BrowserAuth, RoolClient } from "@rool-dev/sdk";
-
-const auth = new BrowserAuth();
-const client = new RoolClient({
-  getTokens: auth.getTokens,
-  onAuthInvalidated: auth.logout,
-});
-
-auth.onAuthStateChanged(renderSignedInState);
-if (!(await auth.initialize())) {
-  await auth.login("My App");
-}
-```
-
-`initialize()` processes an auth callback in the URL. Tokens are stored in endpoint-scoped browser storage and refreshed when requested.
-
-### Native authentication
-
-`NativeAuth` uses system-browser PKCE for Google and Apple while also supporting password and magic-link sign-in.
-
-```typescript
-import { App } from "@capacitor/app";
-import { Browser } from "@capacitor/browser";
-import { NativeAuth, RoolClient } from "@rool-dev/sdk";
-
-const auth = new NativeAuth({
-  redirectUri: "roolandroidauth://auth/callback",
-  defaultProvider: "google",
-  openExternal: (url) => Browser.open({ url }),
-});
-const client = new RoolClient({
-  getTokens: auth.getTokens,
-  onAuthInvalidated: auth.logout,
-});
-
-App.addListener("appUrlOpen", async ({ url }) => {
-  await Browser.close();
-  await auth.handleRedirect(url);
-});
-
-if (!(await auth.initialize())) await auth.login("My App");
-```
-
-The redirect URI must exactly match the app setup and auth server allowlist. Pass `{ provider: "apple" }` to `login()` or `signup()` to override the default provider.
-
-```typescript
-const result = await auth.signInWithPassword(email, password);
-if (result.status === "verify_required") showCheckYourEmailMessage();
-
-await auth.requestMagicLink(email);
-await auth.verify(verifyToken);
-```
-
-On native, an HTTPS magic link only returns to the app when Universal Links or App Links are configured for that domain.
-
-### Password and account methods
+## Connect from Node.js
 
-Browser and native auth clients also provide:
-
-- `setPassword(password)`
-- `requestEmailChange(newEmail)`
-- `verify(token)`
-- `logout()`
-- `isAuthenticated()`
-
-### Node.js authentication
+`NodeAuth` opens the user's browser for login, stores their credentials locally, and refreshes them when needed.
 
 ```typescript
 import { RoolClient } from "@rool-dev/sdk";
 import { NodeAuth } from "@rool-dev/sdk/node";
 
 const auth = new NodeAuth();
-if (!(await auth.initialize())) await auth.login("My CLI");
+if (!(await auth.initialize())) {
+  await auth.login("My app");
+}
 
 const client = new RoolClient({
   getTokens: auth.getTokens,
@@ -153,502 +39,88 @@ const client = new RoolClient({
 });
 ```
 
-`NodeAuth` opens the system browser for login and stores endpoint-scoped credentials under `~/.config/rool/`. It refreshes the access and Rool tokens when requested. Pass `apiUrl` to select another deployed environment; the corresponding auth URL is derived from it. When the API uses a loopback URL, pass `authUrl` explicitly.
+The package also includes:
 
-Use `profile` or `credentialsPath` when an application needs multiple independent accounts:
-
-```typescript
-const auth = new NodeAuth({
-  apiUrl: "https://api.example.com",
-  profile: "automation",
-});
-```
+- `BrowserAuth` for web apps using browser redirects and browser storage.
+- `NativeAuth` for mobile apps that open sign-in in the system browser and return through a deep link. It also supports passwords and magic links.
 
-API errors are thrown as `RoolProblem` with the server's stable `code`, HTTP `status`, `title`, and `detail`.
+## Put a machine to work
 
-## Machine API
+This example creates a machine, gives an agent a job, uploads a receipt, and asks the agent to file it. The file API writes to the machine's WebDAV storage, so the agent and the app see the same files.
 
 ```typescript
-const created = await client.createMachine({ name: "Research" });
-const machine = client.machine(created.id);
-
-const details = await machine.get();
-await machine.settings.replace({ name: "Field research" });
-const copy = await machine.duplicate({ name: "Research copy" });
-const response = await machine.fetchUrl("https://example.com/data.json");
-await client.machine(copy.id).delete();
-```
-
-`client.machine(id)` returns a stable machine handle that owns machine-scoped APIs and synchronization state. Creation, listing, sessions, duplication, and `machine.get()` all return the same point-in-time `MachineSummary`; bind its ID to a handle before performing machine operations. Summaries include the machine's inbound email address, lifecycle `state`, and an opaque `meta` JSON object. `fetchUrl()` returns the upstream `Response`, including non-success statuses.
-
-## Machine checkpoints
-
-```typescript
-const history = await machine.checkpoints.list();
-const checkpoint = history.checkpoints.at(-1);
-if (checkpoint) {
-  await machine.checkpoints.restore(checkpoint.id);
-}
-```
-
-The checkpoint collection contains the currently restorable timeline and the `baseCheckpointId` underlying the live filesystem. The live filesystem can contain newer uncheckpointed changes. Restoring a checkpoint preserves those changes as a new checkpoint and causes a watched machine file tree to reconcile completely. Moving backward does not discard later checkpoints, but modifying the filesystem from that earlier position replaces the later timeline.
-
-## Machine files
-
-```typescript
-const files = machine.files;
-const path = "/rool-drive/documents/report.pdf";
-
-const storage = await files.getStorageUsage();
-console.log(storage.usedBytes, storage.availableBytes);
-await files.createDirectory("/rool-drive/documents");
-const written = await files.write(path, reportBlob, {
-  contentType: "application/pdf",
-  ifNoneMatch: "*",
-  onUploadProgress: ({ transferredBytes, totalBytes }) => {
-    if (totalBytes) renderUploadProgress(transferredBytes / totalBytes);
-  },
-});
-const info = await files.stat(path);
-const documents = await files.list("/rool-drive/documents");
-const response = await files.read(path, {
-  range: { start: 0, end: 1023 },
-  ifMatch: info.etag,
-});
-const hydrated = await files.readMultiple([
-  "/space/.meta.json",
-  "/rool-drive/documents/notes.json",
-]);
-await files.copy(path, "/rool-drive/documents/report-backup.pdf", {
-  overwrite: false,
-  ifMatch: written.etag,
-});
-await files.move(path, "/rool-drive/documents/final-report.pdf");
-const deleted = await files.deleteMultiple([
-  "/rool-drive/documents/final-report.pdf",
-  { path: "/rool-drive/documents/notes.json", ifMatch: '"notes-etag"' },
-]);
-for (const result of deleted) {
-  if (!result.ok)
-    console.error(`Failed to delete ${result.path}`, result.error);
-}
-```
-
-Paths are absolute machine paths under `/space` or `/rool-drive`. `list()` without a path enumerates those storage roots; pass `{ recursive: true }` to enumerate a complete subtree. File and directory metadata has a discriminating `kind` field. Reads return the native `Response` so callers can stream the body. `readMultiple()` hydrates ordered small files in one request and returns an `ok` result with binary-safe bytes and validators, or a per-file HTTP failure. A batch accepts at most 128 paths, 2 MiB per successful file, and 16 MiB across successful files. Writes accept any `BodyInit`, including `Blob` and `ReadableStream`, and return the same complete file metadata as `stat()` and `list()`. `onUploadProgress` reports transferred bytes and includes the total size when it is known; successful completion is confirmed by the `write()` promise. Copy and move operations overwrite by default; pass `{ overwrite: false }` for create-only behavior.
-
-`deleteMultiple()` sends independent DAV requests with at most eight in flight. It accepts plain paths and targets carrying their own HTTP preconditions, and returns one ordered success or failure result per target. The requests are not atomic. A directory target recursively deletes its contents, so callers should omit redundant descendants; duplicate and overlapping targets otherwise remain independent and can race.
-
-Every file and directory has protected `access` metadata. `currentUser` says whether the requesting user can read or write it. `readableBy` and `writableBy` describe its filesystem audiences as `resource-owner`, `machine-admins`, `machine-editors`, and `machine-members`. For a file, write means changing its contents. For a directory, write means adding, removing, or renaming entries. Members without read access to a directory do not receive that directory through listing, direct lookup, or synchronization.
+import { readFile } from "node:fs/promises";
 
-`getStorageUsage()` reports the used and writable bytes on the machine's complete live persistent filesystem, including public files and private runtime or system state. It excludes checkpoint history and the ephemeral operating-system overlay.
-
-Watch the files when an application needs a live machine file tree:
-
-```typescript
-await files.watch();
+const created = await client.createMachine({ name: "Receipts" });
+const machine = client.machine(created.id);
 
-const unsubscribe = files.tree.subscribe(({ reset, changed, deleted }) => {
-  renderFileChanges({ reset, changed, deleted });
+const agent = await machine.agents.create("receipt-filer", {
+  system:
+    "File receipt attachments under /rool-drive/receipts. " +
+    "Choose useful subfolders based on the receipt's contents.",
 });
-
-const cached = files.tree.get("/rool-drive/documents/final-report.pdf");
-const etag = files.tree.etag("/rool-drive/documents/final-report.pdf");
-const allDocuments = files.tree.list("/rool-drive/documents", {
-  recursive: true,
+const conversation = await agent.createConversation({
+  name: "Receipt inbox",
+  visibility: "private",
 });
 
-unsubscribe();
-files.unwatch();
-```
-
-`files.watch()` performs a complete `sync-collection`, then keeps the machine's file metadata and ETag cache current with long-poll incremental reports. DAV writes and guest-program changes enter the same tree. An invalid or expired sync token causes an atomic complete reconciliation and a change event with `reset: true`. Transient sync errors are retried and available as `files.watchError`; `files.unwatch()` aborts the active long poll.
-
-## Rool Object Collections
-
-Objects are JSON stored under `/space`. Collections are directories with a `.schema.json` definition and objects are schema-checked JSON files.
-
-```typescript
-await machine.files.watch();
-
-const task = await machine.collections.create("task", {
-  fields: [
-    { name: "title", type: { kind: "string" } },
-    { name: "done", type: { kind: "boolean" } },
-  ],
+const receiptPath = "/rool-drive/receipts/unsorted/receipt.pdf";
+await machine.files.write(receiptPath, await readFile("./receipt.pdf"), {
+  contentType: "application/pdf",
+  createParents: true,
 });
 
-const first = await machine.objects.create("/space/task/first.json", {
-  title: "First task",
-  done: false,
+await conversation.prompt("File this receipt.", {
+  attachments: [receiptPath],
 });
-const objectPaths = machine.objects.list({ collection: "task" });
-const object = await machine.objects.get(first.path);
-const [sameObject, missing] = await machine.objects.getMultiple([
-  first.path,
-  "/space/task/missing.json",
-]);
-
-await machine.objects.patch(first.path, { done: true });
-await machine.objects.move(first.path, "/space/task/renamed.json");
-const [removal] = await machine.objects.removeMultiple([
-  "/space/task/renamed.json",
-]);
-if (!removal) throw new Error("Object removal returned no result");
-if (!removal.ok) throw removal.error;
-await machine.collections.remove(task.name);
-```
-
-`machine.objects.list()` returns object paths from the synchronized file tree without reading their bodies. `get()` reads one object and `getMultiple()` preserves the input positions and returns `undefined` for missing objects. Every call reads the current bodies from DAV, with multiple reads using bounded `read-multiple` batches. Collection schemas are read in the same way and schema replacement follows the guest's lazy-migration rule: existing objects are checked again only when edited.
-
-Creates are create-only. Metadata, schema, and object replacements plus object patches, moves, and removals use ETags and report status `412` when state changed concurrently. `removeMultiple()` uses a separate conditional DAV request for each object and returns ordered per-object results. Removing a collection recursively deletes its contents. Object moves do not overwrite by default; pass `{ overwrite: true }` explicitly. Patch values of `null` or `undefined` remove fields.
-
-The semantic APIs use the machine's shared file tree and sync loop. They do not create separate synchronization state. Body reads and mutations also work without `machine.files.watch()` by reading current DAV state directly; `objects.list()` reflects the shared file tree, so watch the machine's files before enumerating paths.
-
-## Agents
-
-Agents and conversations use stable JSON routes; their private machine files are not part of the SDK. Prompting does not require `machine.files.watch()`.
-
-```typescript
-const defaultAgent = await machine.agents.get("rool");
-if (!defaultAgent) throw new Error("Rool agent is unavailable");
-
-const conversation = defaultAgent.conversation("research-chat");
-await conversation.prompt("Explain the result.", { effort: "reasoning" });
-
-renderSettled(await conversation.listTurns());
-clearUnsettled();
 await conversation.follow({
-  onEvent: (event) => {
-    if (event.type !== "output.delta") return;
-    if (event.content.type === "text") {
-      renderUnsettledText(event.content.text);
-    } else if (event.content.type === "tool_call") {
-      showRunningTool(event.content.id, event.content.name);
-    } else if (event.content.type === "tool_result") {
-      showToolResult(event.content.id, event.content.content);
+  onEvent(event) {
+    if (event.type === "output.delta" && event.content.type === "text") {
+      process.stdout.write(event.content.text);
     }
   },
 });
-renderSettled(await conversation.listTurns());
 ```
 
-`prompt()` starts the conversation's current run and resolves once the server accepts it. The agent runs as a detached job. A conversation can only have one current run; call `cancel()` and wait for `follow()` to finish before prompting again. The `readOnly` option is accepted for compatibility with legacy prompting but currently has no effect.
-
-`follow()` performs one `GET` of the conversation's current run. It receives the complete unsettled part of the conversation and then continues with new events until that response ends. Tool calls and their results arrive as `output.delta` events with matching IDs. A tool result contains nested content parts and an optional `error` flag. `follow()` returns `false` when there is no current run. A client can always render the conversation from its durable turns plus the events from its latest `follow()` call.
-
-A `conversation_changed` account event tells clients to fetch the durable turns and follow the current run again. Aborting `follow()` only stops watching. Call `cancel()` to stop the detached job.
+Prompting is asynchronous: `prompt()` returns when Rool accepts the work, while the agent keeps running on the machine. An app can follow the current run, leave, and reconnect later. UI clients can instead watch a conversation and receive a current view as its saved turns and live output change.
 
-Prompt attachments are existing `/space` or `/rool-drive` paths. Pass a durable user turn's `id` as `replaceTurnId` to replace that message and everything after it. This supports edits and rerolls, including the first message. A replacement gets a new user turn ID; use that ID to edit it again.
+## Give agents data your app understands
 
-Pass a JSON Schema as `responseSchema` to request structured output. Tools are skipped for that run. The successful assistant turn contains one JSON content part; the value is JSON directly, not a JSON string.
+A machine can hold records as well as documents. A collection defines the fields in each record, and Rool rejects writes that do not match. For example, an app can keep an index alongside the receipt files:
 
 ```typescript
-await conversation.prompt("Return the number of records.", {
-  responseSchema: {
-    type: "object",
-    properties: { count: { type: "integer" } },
-    required: ["count"],
-    additionalProperties: false,
-  },
+await machine.collections.create("receipts", {
+  fields: [
+    { name: "vendor", type: { kind: "string" } },
+    { name: "amount", type: { kind: "number" } },
+    { name: "currency", type: { kind: "string" } },
+    { name: "document", type: { kind: "string" } },
+  ],
 });
-await conversation.follow();
 
-const turns = await conversation.listTurns();
-const part = turns.at(-1)?.body.content[0];
-if (part?.type !== "json") throw new Error("No structured result");
-console.log(part.value); // { count: ... }
-```
-
-Custom agent definitions currently contain one plain system prompt. The server owns the executable agent implementation.
-
-```typescript
-const researcher = await machine.agents.create("researcher", {
-  system: "Investigate carefully and distinguish facts from uncertainty.",
+await machine.objects.create("/space/receipts/cafe.json", {
+  vendor: "Cafe",
+  amount: 12,
+  currency: "EUR",
+  document: receiptPath,
 });
-const customConversation = await researcher.createConversation({
-  name: "Climate report",
-  visibility: "private",
-});
-await customConversation.prompt("Investigate this claim.");
 ```
 
-Agents expose `replace()` and `delete()`. Conversations expose metadata replacement, listing, durable turn reads, rename, and deletion. Listed and fetched conversation metadata includes server-managed ISO 8601 `createdAt` and `updatedAt` timestamps plus `isRunning`, which can drive a running indicator without opening every run stream. Visibility defaults to private. The built-in `rool` agent cannot be replaced or deleted.
+The record is also a normal JSON file at `/space/receipts/cafe.json`. The app can work with it through `machine.objects`, while agents and programs inside the machine can use normal file tools. Changes from either side enter the same watched file tree.
 
-## Members and invites
+Collections can power task lists, catalogues, contact records, or a memory view with links between people, projects, and notes. The app gets predictable fields for its UI without hiding the data from the agent.
 
-```typescript
-const invite = await machine.invites.create({
-  role: "editor",
-  maxUses: 1,
-});
-const token = invite.url.split("/").at(-1)!;
+## What the SDK handles
 
-await client.getInvitePreview(token);
-await client.redeemInvite(token);
+- **Machines:** create, configure, duplicate, checkpoint, share, and delete persistent VMs.
+- **Files:** upload, stream, move, and watch files under `/space` and `/rool-drive`.
+- **Agents:** define agents, keep conversation history, attach machine files, stream runs, and request structured output.
+- **Live state:** learn when account data changes, keep a file tree current, and stream conversation updates.
+- **Shared app data:** define records that apps, agents, and programs inside the machine can all read and edit.
 
-const members = await machine.members.list();
-console.log(members[1].name ?? members[1].email);
-await machine.members.replaceRole(members[1].userId, { role: "viewer" });
-await machine.members.remove(members[1].userId);
-await machine.invites.revoke(invite.id);
-```
-
-Invite URLs contain a secret token and are returned only when an invite is created. Invites can optionally be bound to an email address. Role replacement never creates membership or transfers ownership.
-
-## Gifts
-
-A gift carries something of value in a short code. Users receive gifts from Rool and give the codes away themselves. Claiming a gift is single-use, and claiming your own gift is allowed.
-
-```typescript
-const { gifts } = await client.listGifts();
-for (const gift of gifts) {
-  console.log(gift.code, gift.url, gift.description, gift.claimedAt);
-}
-
-const preview = await client.previewGift(code); // no auth required
-console.log(
-  `${preview.holderName ?? "Someone"} gave you ${preview.description}`,
-);
-
-const { gift } = await client.claimGift(code);
-if (gift.kind === "credits") console.log(`+${gift.credits} credits`);
-```
-
-Codes are case-insensitive and the dash is optional. Prefer the server-rendered `description` for display. Narrow `gift.kind` when using the structured payload because new gift kinds may be added.
-
-A holder can add a note, archive a gift, or replace an unclaimed gift's code. These actions do not change what the gift grants. Archiving only hides it from the holder's normal view.
-
-```typescript
-await client.updateGift(giftId, { note: "sent to Peter" });
-await client.updateGift(giftId, { archived: true });
-await client.updateGift(giftId, { note: null });
-const updated = await client.rotateGiftCode(giftId);
-```
-
-Gift failures are `RoolProblem` errors. `gift_invalid` means the code or gift is unavailable to the caller. `gift_claimed` means it was already claimed.
-
-## API problems
-
-Each problem `type` links to its entry below.
-
-<a id="problem-authentication_required"></a>
-
-### `authentication_required`
-
-**Documentation placeholder.**
-
-<a id="problem-invalid_authentication"></a>
-
-### `invalid_authentication`
-
-**Documentation placeholder.**
-
-<a id="problem-email_unverified"></a>
-
-### `email_unverified`
-
-**Documentation placeholder.**
-
-<a id="problem-account_suspended"></a>
-
-### `account_suspended`
-
-**Documentation placeholder.**
-
-<a id="problem-invalid_profile"></a>
-
-### `invalid_profile`
-
-**Documentation placeholder.**
-
-<a id="problem-invalid_user_app_data"></a>
-
-### `invalid_user_app_data`
-
-**Documentation placeholder.**
-
-<a id="problem-invalid_json"></a>
-
-### `invalid_json`
-
-**Documentation placeholder.**
-
-<a id="problem-payload_too_large"></a>
-
-### `payload_too_large`
-
-**Documentation placeholder.**
-
-<a id="problem-user_app_data_too_large"></a>
-
-### `user_app_data_too_large`
-
-**Documentation placeholder.**
-
-<a id="problem-not_found"></a>
-
-### `not_found`
-
-**Documentation placeholder.**
-
-<a id="problem-checkpoint_not_found"></a>
-
-### `checkpoint_not_found`
-
-**Documentation placeholder.**
-
-<a id="problem-sync_token_required"></a>
-
-### `sync_token_required`
-
-The account event route requires the sync token returned by `/v2/session`.
-
-<a id="problem-invalid_sync_token"></a>
-
-### `invalid_sync_token`
-
-The account event history no longer contains everything after this token. Fetch `/v2/session` and continue with its new token.
-
-<a id="problem-invalid_wait_preference"></a>
-
-### `invalid_wait_preference`
-
-The account event wait must be an integer from 0 through 50 seconds.
-
-<a id="problem-internal_error"></a>
-
-### `internal_error`
-
-**Documentation placeholder.**
+Long-running work belongs to the machine rather than the client connection. File changes made by the app, a user, or an agent enter the same synchronized file tree, while account events tell the app when to fetch fresh account or machine data.
 
-<a id="problem-server_misconfigured"></a>
-
-### `server_misconfigured`
-
-**Documentation placeholder.**
-
-<a id="problem-current_run_exists"></a>
-
-### `current_run_exists`
-
-The conversation is already running. Cancel or follow that run before prompting again. This also applies to prompts with `replaceTurnId`.
-
-<a id="problem-replace_turn_not_found"></a>
-
-### `replace_turn_not_found`
-
-The user turn supplied as `replaceTurnId` is no longer in the conversation. Fetch the turns again before retrying the edit.
-
-<a id="problem-invalid_member_role"></a>
-
-### `invalid_member_role`
-
-**Documentation placeholder.**
-
-<a id="problem-role_not_replaceable"></a>
-
-### `role_not_replaceable`
-
-**Documentation placeholder.**
-
-<a id="problem-membership_not_removable"></a>
-
-### `membership_not_removable`
-
-**Documentation placeholder.**
-
-<a id="problem-invalid_invite"></a>
-
-### `invalid_invite`
-
-**Documentation placeholder.**
-
-<a id="problem-invite_invalid"></a>
-
-### `invite_invalid`
-
-**Documentation placeholder.**
-
-<a id="problem-invite_expired"></a>
-
-### `invite_expired`
-
-**Documentation placeholder.**
-
-<a id="problem-invite_revoked"></a>
-
-### `invite_revoked`
-
-**Documentation placeholder.**
-
-<a id="problem-invite_exhausted"></a>
-
-### `invite_exhausted`
-
-**Documentation placeholder.**
-
-<a id="problem-invite_email_mismatch"></a>
-
-### `invite_email_mismatch`
-
-**Documentation placeholder.**
-
-<a id="problem-gift_invalid"></a>
-
-### `gift_invalid`
-
-The code is not valid, or the requested gift does not belong to the current user.
-
-<a id="problem-gift_claimed"></a>
-
-### `gift_claimed`
-
-The gift has already been claimed. A claimed gift cannot be claimed again or given a new code.
-
-<a id="problem-invalid_input"></a>
-
-### `invalid_input`
-
-The gift update is empty or contains an invalid note or archived value.
-
-## Development
-
-```bash
-pnpm build
-pnpm typecheck
-```
-
-The user-route smoke test must target a dedicated non-production account. It replaces profile and app data, then schedules and cancels account deletion. The member-route smoke test requires a second non-production account to exercise invite redemption and membership changes. The local gift fixture accounts are deleted after the gift smoke test.
-
-Copy `.env.example` to the ignored `.env` file and configure the local endpoints and expected primary account ID.
-
-| Variable                        | Purpose                                                                |
-| ------------------------------- | ---------------------------------------------------------------------- |
-| `ROOL_TEST_API_URL`             | API origin. HTTPS is required except for loopback development servers. |
-| `ROOL_TEST_AUTH_URL`            | Auth endpoint override required for a loopback API.                    |
-| `ROOL_TEST_ROUTER_URL`          | Local machine-router origin.                                           |
-| `ROOL_TEST_USER_ID`             | Expected primary account ID, preventing mutation of the wrong account. |
-| `ROOL_TEST_GIFT_HOLDER_EMAIL`   | Local fixture account that holds a gift.                               |
-| `ROOL_TEST_GIFT_CLAIMANT_EMAIL` | Local fixture account that claims the gift.                            |
-| `ROOL_TEST_INTERNAL_SECRET`     | Local rool-server secret used to create and remove fixtures.           |
-
-Log the `sdk-v2-primary` and `sdk-v2-member` Node profiles into two dedicated accounts:
-
-```bash
-node --env-file=.env --import tsx test/integration/v2/login.ts
-```
-
-Then run the complete v2 smoke-test suite:
-
-```bash
-pnpm test:v2
-```
-
-To run one smoke test manually, invoke its script directly, for example:
-
-```bash
-node --env-file=.env --import tsx test/integration/v2/machine-routes.test.ts
-```
+The package exports its public TypeScript types, so editor autocomplete shows the detailed options and results. See [docs.rool.dev](https://docs.rool.dev/sdk/) for the published documentation.
 
 ## License