agentic-documents 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0
+
+### Added
+
+- A typed client for the Worker HTTP API: `createClient({ baseUrl, token, fetch? })` from the new
+  `agentic-documents/client` subpath. It has one method per HTTP route, except the WebSocket route. It throws `DocsApiError` with the API
+  error code and the HTTP status, takes an `AbortSignal` on every call, and never retries. A 2xx reply
+  with the wrong content type or shape throws `DocsApiError` with the code `BAD_RESPONSE`. It uses only
+  `fetch`, so it runs in browsers, Workers, and Node 22. Tests run it against the real Worker under
+  `wrangler dev`.
+
+Nothing else changed since 0.3.0.
+
 ## 0.3.0
 
 ### Breaking changes

package/README.md

@@ -7,7 +7,7 @@
 
 Write documents with people and agents in real time.
 
-> Status: early, version 0.3.0. The document model, the text operations, the CLI, the MCP server,
+> Status: early, version 0.4.0. The document model, the text operations, the CLI, the MCP server,
 > the Worker API, and live editing in a room work. The web UI is not built yet.
 
 ## Install
@@ -98,6 +98,37 @@ curl "$URL/api/v1/docs/plan/export?format=html" -H "authorization: Bearer $TOKEN
   residency check off.
 - Run it locally with `npx wrangler dev`. Set `WRANGLER_SEND_METRICS=false` to turn off wrangler telemetry.
 
+## SDK
+
+`agentic-documents/client` is a typed client for the Worker HTTP API. It uses only `fetch`, so it runs in
+browsers, Workers, and Node 22. The token sets the author and the role.
+
+```ts
+import { createClient, DocsApiError } from "agentic-documents/client";
+
+const docs = createClient({ baseUrl: "https://docs.example.com", token: process.env.AGENTIC_DOCS_TOKEN! });
+await docs.create({ id: "plan", markdown: "# Plan" });
+const [section] = await docs.outline("plan");
+await docs.replace("plan", { section: section.id, content: "Ship it." });
+console.log(await docs.read("plan"));
+
+try {
+  await docs.read("missing", {}, { signal: AbortSignal.timeout(5000) });
+} catch (error) {
+  if (error instanceof DocsApiError) console.log(error.code, error.status); // NO_DOCUMENT 404
+}
+```
+
+- One method per route: `create`, `read`, `outline`, `edits`, `insert`, `replace`, `delete`, `append`,
+  `suggest`, `suggestions`, `accept`, `reject`, `comment`, `reply`, `resolve`, `reopen`, `threads`,
+  `export`, `room`, `me`, `health`, `state`, and `checkpoint`. The WebSocket route is not a method. Use
+  `LiveDoc` from `agentic-documents/live` for it.
+- Every method takes an optional `{ signal }` last. An abort rejects with what `fetch` throws.
+- An API error throws `DocsApiError` with `code` (the API error code), `status` (the HTTP status), and
+  `matches`. A reply that is not an API error has the code `HTTP_ERROR`. A 2xx reply with the wrong content type or shape has the code `BAD_RESPONSE`.
+- The client never retries. A write is not safe to send twice.
+- Pass `fetch` to use your own, for a Worker service binding or for tests.
+
 ## Features
 
 - A Yjs document that a Tiptap editor can open. It uses the y-prosemirror layout.

package/dist/client.d.ts

@@ -0,0 +1,171 @@
+import { P as PrincipalKind, S as Section, E as EditEntry } from './doc-C_8kCsl7.js';
+export { A as Anchor } from './doc-C_8kCsl7.js';
+import { D as DocErrorCode, S as Suggestion, T as Thread, E as ExportFormat } from './review-BQW2Ci2h.js';
+import 'yjs';
+
+/** The place an edit goes: a section id, or exact text. */
+type Where = {
+    section: string;
+    at?: "start" | "end";
+} | {
+    text: string;
+    occurrence?: number;
+    at?: "before" | "after";
+};
+interface Me {
+    kind: PrincipalKind;
+    name: string;
+    scopes: string[];
+    role: "editor" | "viewer";
+}
+interface Contributor {
+    name: string;
+    kind: string;
+    machine: boolean;
+}
+interface ClientOptions {
+    /** The Worker origin, for example `https://docs.example.com`. */
+    baseUrl: string;
+    /** A bearer token. It sets the author and the role. */
+    token: string;
+    /** Your own `fetch`. The default is the global one. */
+    fetch?: typeof fetch;
+}
+/** Every call takes this last. `signal` cancels the request. */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+/** The codes a call can fail with. `BAD_RESPONSE` means a 2xx reply that does not have the expected shape. */
+type DocsApiErrorCode = DocErrorCode | "UNAUTHENTICATED" | "NOT_FOUND" | "UPGRADE_REQUIRED" | "INTERNAL" | "HTTP_ERROR" | "BAD_RESPONSE";
+/** The API refused a call, or sent a reply that is not what it should be. `code` is the API error code. */
+declare class DocsApiError extends Error {
+    readonly code: DocsApiErrorCode;
+    readonly status: number;
+    readonly matches: {
+        occurrence: number;
+        context: string;
+    }[];
+    constructor(code: DocsApiErrorCode, message: string, status: number, matches?: {
+        occurrence: number;
+        context: string;
+    }[]);
+}
+/**
+ * A client for one Worker. A call that fails with an API error throws `DocsApiError`. A network
+ * failure or an abort throws what `fetch` throws. The client never retries: a write is not safe to repeat.
+ */
+declare function createClient(options: ClientOptions): {
+    /** `GET /health`. It needs no token, but the client sends it anyway. */
+    health(call?: CallOptions): Promise<{
+        ok: boolean;
+        pack: string;
+    }>;
+    /** `GET /api/v1/me`: who the token stands for. */
+    me: (call?: CallOptions) => Promise<Me>;
+    /** `POST /api/v1/docs`. */
+    create: (input: {
+        id: string;
+        markdown?: string;
+    }, call?: CallOptions) => Promise<{
+        id: string;
+    }>;
+    /** `GET /read`: the whole document, or one section, as Markdown. */
+    read(id: string, input?: {
+        section?: string;
+    }, call?: CallOptions): Promise<string>;
+    outline: (id: string, call?: CallOptions) => Promise<Section[]>;
+    edits: (id: string, call?: CallOptions) => Promise<EditEntry[]>;
+    insert: (id: string, input: Where & {
+        content: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    replace: (id: string, input: Where & {
+        content: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    delete: (id: string, input: Where, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    append: (id: string, input: {
+        content: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    suggest: (id: string, input: {
+        text: string;
+        replacement: string;
+        occurrence?: number;
+        at?: "before" | "after";
+    }, call?: CallOptions) => Promise<{
+        suggestion: string;
+    }>;
+    suggestions: (id: string, input?: {
+        status?: Suggestion["status"];
+    }, call?: CallOptions) => Promise<Suggestion[]>;
+    accept: (id: string, input: {
+        suggestion: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    reject: (id: string, input: {
+        suggestion: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    comment: (id: string, input: {
+        text: string;
+        body: string;
+        occurrence?: number;
+    }, call?: CallOptions) => Promise<{
+        thread: string;
+    }>;
+    reply: (id: string, input: {
+        thread: string;
+        body: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    resolve: (id: string, input: {
+        thread: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    reopen: (id: string, input: {
+        thread: string;
+    }, call?: CallOptions) => Promise<{
+        ok: true;
+    }>;
+    threads: (id: string, input?: {
+        status?: Thread["status"];
+    }, call?: CallOptions) => Promise<Thread[]>;
+    /** `GET /export`. `md` and `html` return text. `odt` returns the file bytes. */
+    export: {
+        (id: string, input: {
+            format: "odt";
+            remoteImages?: boolean;
+        }, call?: CallOptions): Promise<Uint8Array>;
+        (id: string, input: {
+            format: "md" | "html";
+            remoteImages?: boolean;
+        }, call?: CallOptions): Promise<string>;
+        (id: string, input: {
+            format: ExportFormat;
+            remoteImages?: boolean;
+        }, call?: CallOptions): Promise<string | Uint8Array>;
+    };
+    /** `GET /room`: who sent updates in the live room. */
+    room: (id: string, call?: CallOptions) => Promise<{
+        contributors: Contributor[];
+    }>;
+    /** `GET /state`: the stored document as a Yjs update. */
+    state(id: string, call?: CallOptions): Promise<Uint8Array>;
+    /** `POST /checkpoint`: merge a Yjs update into the stored document. */
+    checkpoint(id: string, update: Uint8Array, call?: CallOptions): Promise<{
+        ok: true;
+    }>;
+};
+type DocsClient = ReturnType<typeof createClient>;
+
+export { type CallOptions, type ClientOptions, type Contributor, DocsApiError, type DocsApiErrorCode, type DocsClient, EditEntry, ExportFormat, type Me, Section, Suggestion, Thread, type Where, createClient };

package/dist/client.js

@@ -0,0 +1,114 @@
+// src/client.ts
+var DocsApiError = class extends Error {
+  constructor(code, message, status, matches = []) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.matches = matches;
+    this.name = "DocsApiError";
+  }
+  code;
+  status;
+  matches;
+};
+var enc = encodeURIComponent;
+function createClient(options) {
+  if (!options.token) throw new TypeError("createClient needs a token");
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+  const bad = (status, why) => new DocsApiError("BAD_RESPONSE", `the server sent a reply that is not valid: ${why}`, status);
+  const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  const isMatch = (m) => isObject(m) && typeof m.occurrence === "number" && typeof m.context === "string";
+  async function send(path, init, call = {}, expect = "application/json") {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(init.query ?? {})) if (value !== void 0) params.set(key, String(value));
+    const qs = params.toString();
+    const url = `${base}${path}${qs ? `?${qs}` : ""}`;
+    const headers = { authorization: `Bearer ${options.token}` };
+    if (init.json) headers["content-type"] = "application/json";
+    const response = await doFetch(url, { method: init.method, headers, body: init.body, signal: call.signal });
+    if (response.ok) {
+      const type = (response.headers.get("content-type") ?? "").toLowerCase();
+      if (!type.startsWith(expect)) throw bad(response.status, `unexpected content type "${type}"`);
+      return response;
+    }
+    let error;
+    try {
+      const parsed = await response.json();
+      if (isObject(parsed.error)) error = parsed.error;
+    } catch {
+    }
+    throw new DocsApiError(
+      typeof error?.code === "string" ? error.code : "HTTP_ERROR",
+      typeof error?.message === "string" ? error.message : `the server answered ${response.status}`,
+      response.status,
+      Array.isArray(error?.matches) ? error.matches.filter(isMatch) : []
+    );
+  }
+  async function json(response, check, what) {
+    let value;
+    try {
+      value = await response.json();
+    } catch {
+      throw bad(response.status, "the body is not JSON");
+    }
+    if (!check(value)) throw bad(response.status, `expected ${what}`);
+    return value;
+  }
+  const doc = (id) => `/api/v1/docs/${enc(id)}`;
+  const isOk = (v) => isObject(v) && v.ok === true;
+  const isList = (v) => Array.isArray(v) && v.every(isObject);
+  const get = async (path, query, check, what, call) => await json(await send(path, { method: "GET", query }, call), check, what);
+  const post = async (path, body, check, what, call) => await json(await send(path, { method: "POST", json: true, body: JSON.stringify(body) }, call), check, what);
+  const ok = (path, body, call) => post(path, body, isOk, "{ ok: true }", call);
+  const list = (path, query, call) => get(path, query, isList, "a list", call);
+  const withKey = (path, body, key, call) => post(path, body, (v) => isObject(v) && typeof v[key] === "string", `{ ${key}: string }`, call);
+  return {
+    /** `GET /health`. It needs no token, but the client sends it anyway. */
+    async health(call) {
+      return await json(await send("/health", { method: "GET" }, call), (v) => isObject(v) && v.ok === true && typeof v.pack === "string", "{ ok, pack }");
+    },
+    /** `GET /api/v1/me`: who the token stands for. */
+    me: (call) => get("/api/v1/me", {}, (v) => isObject(v) && typeof v.kind === "string" && typeof v.name === "string" && Array.isArray(v.scopes) && (v.role === "editor" || v.role === "viewer"), "the token identity", call),
+    /** `POST /api/v1/docs`. */
+    create: (input, call) => withKey("/api/v1/docs", input, "id", call),
+    /** `GET /read`: the whole document, or one section, as Markdown. */
+    async read(id, input = {}, call) {
+      return (await send(`${doc(id)}/read`, { method: "GET", query: input }, call, "text/markdown")).text();
+    },
+    outline: (id, call) => list(`${doc(id)}/outline`, {}, call),
+    edits: (id, call) => list(`${doc(id)}/edits`, {}, call),
+    insert: (id, input, call) => ok(`${doc(id)}/insert`, input, call),
+    replace: (id, input, call) => ok(`${doc(id)}/replace`, input, call),
+    delete: (id, input, call) => ok(`${doc(id)}/delete`, input, call),
+    append: (id, input, call) => ok(`${doc(id)}/append`, input, call),
+    suggest: (id, input, call) => withKey(`${doc(id)}/suggest`, input, "suggestion", call),
+    suggestions: (id, input = {}, call) => list(`${doc(id)}/suggestions`, input, call),
+    accept: (id, input, call) => ok(`${doc(id)}/accept`, input, call),
+    reject: (id, input, call) => ok(`${doc(id)}/reject`, input, call),
+    comment: (id, input, call) => withKey(`${doc(id)}/comment`, input, "thread", call),
+    reply: (id, input, call) => ok(`${doc(id)}/reply`, input, call),
+    resolve: (id, input, call) => ok(`${doc(id)}/resolve`, input, call),
+    reopen: (id, input, call) => ok(`${doc(id)}/reopen`, input, call),
+    threads: (id, input = {}, call) => list(`${doc(id)}/threads`, input, call),
+    /** `GET /export`. `md` and `html` return text. `odt` returns the file bytes. */
+    export: (async (id, input, call) => {
+      const response = await send(`${doc(id)}/export`, { method: "GET", query: input }, call, { md: "text/markdown", html: "text/html", odt: "application/vnd.oasis.opendocument.text" }[input.format]);
+      return input.format === "odt" ? new Uint8Array(await response.arrayBuffer()) : response.text();
+    }),
+    /** `GET /room`: who sent updates in the live room. */
+    room: (id, call) => get(`${doc(id)}/room`, {}, (v) => isObject(v) && Array.isArray(v.contributors), "{ contributors }", call),
+    /** `GET /state`: the stored document as a Yjs update. */
+    async state(id, call) {
+      return new Uint8Array(await (await send(`${doc(id)}/state`, { method: "GET" }, call, "application/octet-stream")).arrayBuffer());
+    },
+    /** `POST /checkpoint`: merge a Yjs update into the stored document. */
+    async checkpoint(id, update, call) {
+      return await json(await send(`${doc(id)}/checkpoint`, { method: "POST", body: update }, call), isOk, "{ ok: true }");
+    }
+  };
+}
+export {
+  DocsApiError,
+  createClient
+};

package/dist/{service-BKkxEnaJ.d.ts → doc-C_8kCsl7.d.ts}

@@ -1,5 +1,4 @@
 import * as Y from 'yjs';
-import { Blobs, Store } from 'agentic-identity';
 
 /** A ProseMirror node in JSON form, the shape y-prosemirror reads and writes. */
 interface PmNode {
@@ -124,58 +123,4 @@ declare class AgenticDoc {
     append(markdown: string, author: Principal): void;
 }
 
-/** What the catalog keeps for each document. The author kind stays, so machine-made work stays labeled. */
-interface DocInfo {
-    createdBy: {
-        kind: PrincipalKind;
-        name: string;
-    };
-    createdAt: number;
-}
-interface DocsPorts {
-    /** Holds each document as a Yjs update. Saves are conditional on the version that was read. */
-    blobs: Blobs;
-    /** Holds the catalog: who created each document, and when. */
-    store: Store;
-}
-/** What every command needs: make a document, read it, and change it. A live room can stand behind it as well as the ports. */
-interface DocAccess {
-    create(id: string, markdown: string, author: Principal): Promise<void>;
-    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-}
-/** Loads and saves documents as Yjs updates in a Blobs port. The CLI, MCP server, and API share it. */
-declare class DocsService implements DocAccess {
-    private readonly options;
-    private readonly blobs;
-    private readonly store;
-    constructor(ports: DocsPorts, options?: DocOptions);
-    private key;
-    create(id: string, markdown: string, author: Principal): Promise<void>;
-    /** The stored document as a Yjs update. A live client seeds its room from it. */
-    state(id: string): Promise<Uint8Array>;
-    /**
-     * Merge a Yjs update from a live room into the stored document, and create the document when it
-     * has none. A merge is safe to repeat and to run in any order. The save is conditional, so two
-     * checkpoints at once both land.
-     */
-    checkpoint(id: string, update: Uint8Array, author: Principal): Promise<void>;
-    /**
-     * The encoded document, once it reads back and every stored entry has the shape the commands rely on. Yjs does not
-     * check types, so an update can put text where the editor expects blocks, or a thread with no messages, and then a
-     * command fails on every later call.
-     */
-    private checked;
-    private fits;
-    private catalog;
-    /** Who created the document and when, or null when it has no catalog entry (made before the catalog, or a failed catalog write). */
-    info(id: string): Promise<DocInfo | null>;
-    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-    /**
-     * Load, run the change, and save only if nobody saved in between. When someone did, load again and
-     * run the change again, so a check such as "is it still pending" sees the new state.
-     */
-    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
-}
-
-export { type Anchor as A, type DocAccess as D, type EditEntry as E, type Principal as P, type Section as S, type TextTarget as T, AgenticDoc as a, type AnchorTarget as b, type PmNode as c, type DocInfo as d, type DocOptions as e, type DocsPorts as f, DocsService as g, PRINCIPAL_KINDS as h, type PrincipalKind as i, type SectionTarget as j, type Target as k, blocksToMarkdown as l, markdownToBlocks as m, parseAuthor as p };
+export { type Anchor as A, type DocOptions as D, type EditEntry as E, type PrincipalKind as P, type Section as S, type Target as T, type Principal as a, type PmNode as b, AgenticDoc as c, type AnchorTarget as d, PRINCIPAL_KINDS as e, type SectionTarget as f, type TextTarget as g, blocksToMarkdown as h, markdownToBlocks as m, parseAuthor as p };

package/dist/index.d.ts

@@ -1,94 +1,15 @@
-import { P as Principal, A as Anchor, a as AgenticDoc, T as TextTarget, b as AnchorTarget, D as DocAccess, c as PmNode } from './service-BKkxEnaJ.js';
-export { d as DocInfo, e as DocOptions, f as DocsPorts, g as DocsService, E as EditEntry, h as PRINCIPAL_KINDS, i as PrincipalKind, S as Section, j as SectionTarget, k as Target, l as blocksToMarkdown, m as markdownToBlocks, p as parseAuthor } from './service-BKkxEnaJ.js';
+import { a as Principal, b as PmNode } from './doc-C_8kCsl7.js';
+export { c as AgenticDoc, A as Anchor, d as AnchorTarget, D as DocOptions, E as EditEntry, e as PRINCIPAL_KINDS, P as PrincipalKind, S as Section, f as SectionTarget, T as Target, g as TextTarget, h as blocksToMarkdown, m as markdownToBlocks, p as parseAuthor } from './doc-C_8kCsl7.js';
 import { Schema } from 'prosemirror-model';
+export { a as DocError, D as DocErrorCode, b as EXPORT_FORMATS, E as ExportFormat, c as ExportOptions, d as ExportResult, M as Message, S as Suggestion, e as Suggestions, T as Thread, f as Threads, g as exportDoc } from './review-BQW2Ci2h.js';
 import { z } from 'zod';
+import { D as DocAccess } from './service-Do2Jwb5U.js';
+export { a as DocInfo, b as DocsPorts, c as DocsService } from './service-Do2Jwb5U.js';
 import { AdapterOptions, Blobs, Store } from 'agentic-identity';
 import 'yjs';
 
-type DocErrorCode = "NO_MATCH" | "AMBIGUOUS_MATCH" | "STALE_ANCHOR" | "NO_SECTION" | "INVALID_AUTHOR" | "INVALID_INPUT" | "NO_THREAD" | "NO_SUGGESTION" | "ALREADY_DECIDED" | "FORBIDDEN" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "LOCKED" | "CONFLICT" | "MISCONFIGURED";
-declare class DocError extends Error {
-    readonly code: DocErrorCode;
-    readonly matches: {
-        occurrence: number;
-        context: string;
-    }[];
-    constructor(code: DocErrorCode, message: string, matches?: {
-        occurrence: number;
-        context: string;
-    }[]);
-}
-
 declare const schema: Schema<string, string>;
 
-interface Message {
-    id: string;
-    at: string;
-    author: Principal;
-    body: string;
-}
-interface Thread {
-    id: string;
-    anchor: Anchor;
-    status: "open" | "resolved";
-    resolvedBy?: Principal;
-    resolvedAt?: string;
-    messages: Message[];
-    /** The anchored text no longer matches what the comment was made on. */
-    stale: boolean;
-    /** The text now under the anchor, or null when it is gone. */
-    currentText: string | null;
-}
-interface Suggestion {
-    id: string;
-    kind: "insert" | "replace" | "delete";
-    at?: "before" | "after";
-    anchor: Anchor;
-    replacement: string;
-    author: Principal;
-    createdAt: string;
-    status: "pending" | "accepted" | "rejected";
-    decidedBy?: Principal;
-    decidedAt?: string;
-    stale: boolean;
-}
-/** Comment threads anchored to text. Replies and status merge across replicas. */
-declare class Threads {
-    private readonly doc;
-    constructor(doc: AgenticDoc);
-    private get map();
-    private get;
-    private message;
-    add(target: TextTarget | AnchorTarget, body: string, author: Principal): string;
-    reply(id: string, body: string, author: Principal): void;
-    private setStatus;
-    resolve(id: string, author: Principal): void;
-    reopen(id: string, author: Principal): void;
-    list(filter?: {
-        status?: Thread["status"];
-    }): Thread[];
-}
-/** Suggested edits. Nothing changes in the text until a person, or an agent with the accept scope, accepts one. */
-declare class Suggestions {
-    private readonly doc;
-    constructor(doc: AgenticDoc);
-    private get map();
-    private get;
-    private read;
-    /** An `at` on the target means insert. An empty replacement means delete. */
-    add(target: TextTarget | AnchorTarget, replacement: string, author: Principal): string;
-    private decide;
-    /**
-     * Apply the edit as the accepting author. The check and the edit share one transaction. Accepting
-     * an accepted suggestion changes nothing. A stale anchor throws and the suggestion stays pending.
-     */
-    accept(id: string, author: Principal): void;
-    /** Same right as accept. A person can withdraw their own suggestion. An agent can never decide its own. */
-    reject(id: string, author: Principal): void;
-    list(filter?: {
-        status?: Suggestion["status"];
-    }): Suggestion[];
-}
-
 /** One table drives the CLI, the MCP server, and the HTTP API, so they stay the same. */
 interface Command {
     name: string;
@@ -99,20 +20,6 @@ interface Command {
 }
 declare const commands: Command[];
 
-declare const EXPORT_FORMATS: readonly ["md", "html", "odt"];
-type ExportFormat = (typeof EXPORT_FORMATS)[number];
-interface ExportOptions {
-    /** Keep `<img>` for web and relative sources. Opening the page then asks those hosts for the image. Off by default. */
-    remoteImages?: boolean;
-}
-interface ExportResult {
-    format: ExportFormat;
-    contentType: string;
-    encoding: "utf8" | "base64";
-    data: string;
-}
-declare function exportDoc(doc: AgenticDoc, format: ExportFormat, options?: ExportOptions): ExportResult;
-
 interface FileBlobsOptions extends AdapterOptions {
     /** A lock older than this is taken over. Default 10 seconds. A save takes milliseconds. */
     lockStaleMs?: number;
@@ -142,4 +49,4 @@ declare const ODT_MIME = "application/vnd.oasis.opendocument.text";
 /** Write blocks as an OpenDocument text file (.odt): content, styles, and images as embedded files. */
 declare function exportOdt(blocks: PmNode[]): Uint8Array;
 
-export { AgenticDoc, Anchor, AnchorTarget, type Command, DocError, type DocErrorCode, EXPORT_FORMATS, type ExportFormat, type ExportOptions, type ExportResult, type FileBlobsOptions, type Message, ODT_MIME, PmNode, Principal, type Suggestion, Suggestions, TextTarget, type Thread, Threads, commands, createFileBlobs, createFileStore, exportDoc, exportOdt, schema };
+export { type Command, type FileBlobsOptions, ODT_MIME, PmNode, Principal, commands, createFileBlobs, createFileStore, exportOdt, schema };

package/dist/live-worker.d.ts

@@ -5,8 +5,9 @@ import 'hono';
 import 'agentic-identity';
 import 'agentic-identity/cloudflare';
 import 'agentic-realtime';
-import './service-BKkxEnaJ.js';
+import './doc-C_8kCsl7.js';
 import 'yjs';
+import './service-Do2Jwb5U.js';
 
 type Namespace = Parameters<typeof createDurableObjectRealtime>[0];
 interface LiveEnv extends WorkerEnv {

package/dist/live.d.ts

@@ -1,5 +1,6 @@
 import { Peer } from 'agentic-realtime/client';
-import { a as AgenticDoc, P as Principal, e as DocOptions, D as DocAccess } from './service-BKkxEnaJ.js';
+import { c as AgenticDoc, a as Principal, D as DocOptions } from './doc-C_8kCsl7.js';
+import { D as DocAccess } from './service-Do2Jwb5U.js';
 import 'yjs';
 import 'agentic-identity';
 

package/dist/review-BQW2Ci2h.d.ts

@@ -0,0 +1,99 @@
+import { c as AgenticDoc, A as Anchor, a as Principal, g as TextTarget, d as AnchorTarget } from './doc-C_8kCsl7.js';
+
+type DocErrorCode = "NO_MATCH" | "AMBIGUOUS_MATCH" | "STALE_ANCHOR" | "NO_SECTION" | "INVALID_AUTHOR" | "INVALID_INPUT" | "NO_THREAD" | "NO_SUGGESTION" | "ALREADY_DECIDED" | "FORBIDDEN" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "LOCKED" | "CONFLICT" | "MISCONFIGURED";
+declare class DocError extends Error {
+    readonly code: DocErrorCode;
+    readonly matches: {
+        occurrence: number;
+        context: string;
+    }[];
+    constructor(code: DocErrorCode, message: string, matches?: {
+        occurrence: number;
+        context: string;
+    }[]);
+}
+
+declare const EXPORT_FORMATS: readonly ["md", "html", "odt"];
+type ExportFormat = (typeof EXPORT_FORMATS)[number];
+interface ExportOptions {
+    /** Keep `<img>` for web and relative sources. Opening the page then asks those hosts for the image. Off by default. */
+    remoteImages?: boolean;
+}
+interface ExportResult {
+    format: ExportFormat;
+    contentType: string;
+    encoding: "utf8" | "base64";
+    data: string;
+}
+declare function exportDoc(doc: AgenticDoc, format: ExportFormat, options?: ExportOptions): ExportResult;
+
+interface Message {
+    id: string;
+    at: string;
+    author: Principal;
+    body: string;
+}
+interface Thread {
+    id: string;
+    anchor: Anchor;
+    status: "open" | "resolved";
+    resolvedBy?: Principal;
+    resolvedAt?: string;
+    messages: Message[];
+    /** The anchored text no longer matches what the comment was made on. */
+    stale: boolean;
+    /** The text now under the anchor, or null when it is gone. */
+    currentText: string | null;
+}
+interface Suggestion {
+    id: string;
+    kind: "insert" | "replace" | "delete";
+    at?: "before" | "after";
+    anchor: Anchor;
+    replacement: string;
+    author: Principal;
+    createdAt: string;
+    status: "pending" | "accepted" | "rejected";
+    decidedBy?: Principal;
+    decidedAt?: string;
+    stale: boolean;
+}
+/** Comment threads anchored to text. Replies and status merge across replicas. */
+declare class Threads {
+    private readonly doc;
+    constructor(doc: AgenticDoc);
+    private get map();
+    private get;
+    private message;
+    add(target: TextTarget | AnchorTarget, body: string, author: Principal): string;
+    reply(id: string, body: string, author: Principal): void;
+    private setStatus;
+    resolve(id: string, author: Principal): void;
+    reopen(id: string, author: Principal): void;
+    list(filter?: {
+        status?: Thread["status"];
+    }): Thread[];
+}
+/** Suggested edits. Nothing changes in the text until a person, or an agent with the accept scope, accepts one. */
+declare class Suggestions {
+    private readonly doc;
+    constructor(doc: AgenticDoc);
+    private get map();
+    private get;
+    private read;
+    /** An `at` on the target means insert. An empty replacement means delete. */
+    add(target: TextTarget | AnchorTarget, replacement: string, author: Principal): string;
+    private decide;
+    /**
+     * Apply the edit as the accepting author. The check and the edit share one transaction. Accepting
+     * an accepted suggestion changes nothing. A stale anchor throws and the suggestion stays pending.
+     */
+    accept(id: string, author: Principal): void;
+    /** Same right as accept. A person can withdraw their own suggestion. An agent can never decide its own. */
+    reject(id: string, author: Principal): void;
+    list(filter?: {
+        status?: Suggestion["status"];
+    }): Suggestion[];
+}
+
+export { type DocErrorCode as D, type ExportFormat as E, type Message as M, type Suggestion as S, type Thread as T, DocError as a, EXPORT_FORMATS as b, type ExportOptions as c, type ExportResult as d, Suggestions as e, Threads as f, exportDoc as g };

package/dist/service-Do2Jwb5U.d.ts

@@ -0,0 +1,58 @@
+import { a as Principal, c as AgenticDoc, P as PrincipalKind, D as DocOptions } from './doc-C_8kCsl7.js';
+import { Blobs, Store } from 'agentic-identity';
+
+/** What the catalog keeps for each document. The author kind stays, so machine-made work stays labeled. */
+interface DocInfo {
+    createdBy: {
+        kind: PrincipalKind;
+        name: string;
+    };
+    createdAt: number;
+}
+interface DocsPorts {
+    /** Holds each document as a Yjs update. Saves are conditional on the version that was read. */
+    blobs: Blobs;
+    /** Holds the catalog: who created each document, and when. */
+    store: Store;
+}
+/** What every command needs: make a document, read it, and change it. A live room can stand behind it as well as the ports. */
+interface DocAccess {
+    create(id: string, markdown: string, author: Principal): Promise<void>;
+    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+}
+/** Loads and saves documents as Yjs updates in a Blobs port. The CLI, MCP server, and API share it. */
+declare class DocsService implements DocAccess {
+    private readonly options;
+    private readonly blobs;
+    private readonly store;
+    constructor(ports: DocsPorts, options?: DocOptions);
+    private key;
+    create(id: string, markdown: string, author: Principal): Promise<void>;
+    /** The stored document as a Yjs update. A live client seeds its room from it. */
+    state(id: string): Promise<Uint8Array>;
+    /**
+     * Merge a Yjs update from a live room into the stored document, and create the document when it
+     * has none. A merge is safe to repeat and to run in any order. The save is conditional, so two
+     * checkpoints at once both land.
+     */
+    checkpoint(id: string, update: Uint8Array, author: Principal): Promise<void>;
+    /**
+     * The encoded document, once it reads back and every stored entry has the shape the commands rely on. Yjs does not
+     * check types, so an update can put text where the editor expects blocks, or a thread with no messages, and then a
+     * command fails on every later call.
+     */
+    private checked;
+    private fits;
+    private catalog;
+    /** Who created the document and when, or null when it has no catalog entry (made before the catalog, or a failed catalog write). */
+    info(id: string): Promise<DocInfo | null>;
+    read<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+    /**
+     * Load, run the change, and save only if nobody saved in between. When someone did, load again and
+     * run the change again, so a check such as "is it still pending" sees the new state.
+     */
+    write<T>(id: string, run: (doc: AgenticDoc) => T): Promise<T>;
+}
+
+export { type DocAccess as D, type DocInfo as a, type DocsPorts as b, DocsService as c };

package/dist/worker.d.ts

@@ -2,7 +2,8 @@ import { Hono } from 'hono';
 import { Region } from 'agentic-identity';
 import { D1Like, R2Like } from 'agentic-identity/cloudflare';
 import { Realtime, Role } from 'agentic-realtime';
-import { g as DocsService, P as Principal } from './service-BKkxEnaJ.js';
+import { a as Principal } from './doc-C_8kCsl7.js';
+import { c as DocsService } from './service-Do2Jwb5U.js';
 import 'yjs';
 
 interface WorkerEnv {

package/llms.txt

@@ -6,6 +6,7 @@ Keywords: documents, editor, rich-text, tiptap, yjs, collaboration, agents.
 
 - SDK: import { AgenticDoc } from "agentic-documents".
 - Read as Markdown, read an outline, edit by section id or exact text.
+- Remote client: import { createClient } from "agentic-documents/client"; createClient({ baseUrl, token, fetch? }). It has one method per HTTP route. An error is a DocsApiError with a code and a status. Every call takes { signal }. The client never retries.
 - CLI: npx agentic-documents <command> <id>. MCP: npx agentic-documents mcp --as <kind>:<name>.
 - Every edit carries an author kind and name.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-documents",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Write documents with people and agents in real time.",
   "keywords": [
     "documents",
@@ -54,6 +54,10 @@
       "types": "./dist/live.d.ts",
       "import": "./dist/live.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./live-worker": {
       "types": "./dist/live-worker.d.ts",
       "import": "./dist/live-worker.js"