agentic-comments 0.4.0 → 0.5.0

package/README.md

@@ -243,6 +243,34 @@ curl -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
   http://127.0.0.1:8787/api/v1/docs/d1/threads
 ```
 
+## HTTP client
+
+`agentic-comments/client` is a typed client for the Worker routes. It uses only `fetch`, so it runs in browsers,
+Workers, and Node.
+
+```ts
+import { createClient, CommentsApiError } from "agentic-comments/client";
+
+const comments = createClient({ baseUrl: "https://comments.example.com", token });
+await comments.createDocument({ id: "d1", text: "The quick brown fox" });
+const thread = await comments.addThread("d1", { anchor: { type: "text", quote: "fox" }, body: "Which fox?" });
+await comments.reply("d1", thread.id, { body: "This one." });
+try {
+  await comments.accept("d1", "missing");
+} catch (error) {
+  if (error instanceof CommentsApiError) console.error(error.code, error.status);
+}
+```
+
+- The methods match the routes: `me`, `createDocument`, `getDocument`, `listThreads`, `getThread`, `addThread`, `reply`,
+  `resolve`, `reopen`, `relocate`, `listSuggestions`, `suggest`, `accept`, `reject`. Each takes an optional `{ signal }`.
+- `baseUrl` is the Worker URL, `http` or `https`, with no query, hash, or credentials.
+- The client never sends an author. The Worker stamps one from the token.
+- A failed call throws `CommentsApiError`. `code` is the API error code, or `UNKNOWN` when the reply is not an API
+  error. `status` is the HTTP status. A `200` reply with the wrong shape also fails as `UNKNOWN`.
+- The client never follows a redirect and never retries. A write that you abort after the client sends it can still apply:
+  read the thread before you try again.
+
 ## Live demo
 
 A demo Worker runs at <https://agentic-comments-demo.hello-fd1.workers.dev>. It is a staging site. Check it with

package/dist/{chunk-R4LH36VG.js → chunk-ABXAPWXD.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   CommentsService
 } from "./chunk-NQWRFKJ6.js";

package/dist/{chunk-DRACF66Y.js → chunk-WQHJNHAR.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.4.0" : readPackageVersion();
+var VERSION = true ? "0.5.0" : readPackageVersion();
 
 export {
   VERSION

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
 } from "./chunk-HXXJNFEO.js";
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   CommentsService,
   TEXT_ROOT
@@ -155,7 +155,7 @@ async function runCli(argv, io) {
       return 0;
     }
     if (p.command === "mcp") {
-      const { startMcp } = await import("./mcp-ACC4QIEM.js");
+      const { startMcp } = await import("./mcp-JMEXA2RI.js");
       await startMcp(store, operatorActor(p.flags["--as"] ?? io.env.AGENTIC_COMMENTS_AS, io.env.AGENTIC_COMMENTS_SCOPES));
       return 0;
     }

package/dist/client.d.ts

@@ -0,0 +1,72 @@
+import { L as ListFilter, A as AnchorSpec } from './service-hpWbnSmc.js';
+import { C as CommentsErrorCode } from './errors-CNgWMVQT.js';
+import { PrincipalKind } from 'agentic-identity';
+export { PrincipalKind } from 'agentic-identity';
+import { T as Thread, N as NewReply, M as Message, S as Suggestion } from './suggestions-CvJwo6r4.js';
+import 'yjs';
+
+/** Codes the comment rules return, plus the ones the Worker and its auth return. */
+type ApiErrorCode = CommentsErrorCode | "UNAUTHENTICATED" | "NOT_FOUND" | "INTERNAL" | "UNKNOWN";
+/** Thrown for every reply that is not a success. `code` is the API error code and `status` is the HTTP status. */
+declare class CommentsApiError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    constructor(code: ApiErrorCode, status: number, message: string);
+}
+interface ClientOptions {
+    /** The Worker origin, for example https://comments.example.com. The client adds /api/v1. */
+    baseUrl: string;
+    /** A bearer credential that the Worker's auth accepts. */
+    token: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Every method takes an optional signal. An aborted call rejects with the signal reason, not a
+ * CommentsApiError. A write that was aborted after it was sent may still have applied: read the
+ * thread before you try again.
+ */
+interface CallOptions {
+    signal?: AbortSignal;
+}
+interface Me {
+    kind: PrincipalKind;
+    name: string;
+    scopes: string[];
+}
+type ThreadFilter = ListFilter;
+type SuggestionListFilter = Pick<ListFilter, "status" | "anchorState">;
+interface CommentsClient {
+    me(options?: CallOptions): Promise<Me>;
+    createDocument(input: {
+        id: string;
+        text?: string;
+    }, options?: CallOptions): Promise<{
+        id: string;
+    }>;
+    getDocument(docId: string, options?: CallOptions): Promise<{
+        id: string;
+        text: string;
+    }>;
+    listThreads(docId: string, filter?: ThreadFilter, options?: CallOptions): Promise<Thread[]>;
+    getThread(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    addThread(docId: string, input: {
+        anchor: AnchorSpec;
+        body: string;
+        mentions?: string[];
+    }, options?: CallOptions): Promise<Thread>;
+    reply(docId: string, threadId: string, input: NewReply, options?: CallOptions): Promise<Message>;
+    resolve(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    reopen(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    relocate(docId: string, threadId: string, options?: CallOptions): Promise<Thread>;
+    listSuggestions(docId: string, filter?: SuggestionListFilter, options?: CallOptions): Promise<Suggestion[]>;
+    suggest(docId: string, input: {
+        anchor: AnchorSpec;
+        change: unknown;
+        summary?: string;
+    }, options?: CallOptions): Promise<Suggestion>;
+    accept(docId: string, suggestionId: string, options?: CallOptions): Promise<Suggestion>;
+    reject(docId: string, suggestionId: string, options?: CallOptions): Promise<Suggestion>;
+}
+declare function createClient(options: ClientOptions): CommentsClient;
+
+export { AnchorSpec, type ApiErrorCode, type CallOptions, type ClientOptions, CommentsApiError, type CommentsClient, CommentsErrorCode, ListFilter, type Me, Message, NewReply, Suggestion, type SuggestionListFilter, Thread, type ThreadFilter, createClient };

package/dist/client.js

@@ -0,0 +1,135 @@
+// src/client.ts
+var CODES = {
+  INVALID_AUTHOR: true,
+  INVALID_INPUT: true,
+  INVALID_ANCHOR: true,
+  NO_THREAD: true,
+  THREAD_RESOLVED: true,
+  CORRUPT: true,
+  NO_SUGGESTION: true,
+  FORBIDDEN: true,
+  ALREADY_DECIDED: true,
+  APPLY_FAILED: true,
+  RELOCATE_FAILED: true,
+  STORE_MISSING: true,
+  STORE_EXISTS: true,
+  STORE_CORRUPT: true,
+  STORE_LOCKED: true,
+  STORE_FULL: true,
+  NO_DOCUMENT: true,
+  DOCUMENT_EXISTS: true,
+  CONFLICT: true,
+  MISCONFIGURED: true,
+  USAGE: true,
+  UNAUTHENTICATED: true,
+  NOT_FOUND: true,
+  INTERNAL: true,
+  UNKNOWN: true
+};
+var isKnownCode = (v) => typeof v === "string" && Object.hasOwn(CODES, v);
+var CommentsApiError = class extends Error {
+  code;
+  status;
+  constructor(code, status, message) {
+    super(message);
+    this.name = "CommentsApiError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var KINDS = { human: true, agent_of_human: true, agent_of_agent: true, agent: true, user_token: true };
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isString = (v) => typeof v === "string";
+var SHAPES = {
+  me: (v) => isObject(v) && (typeof v.kind === "string" && Object.hasOwn(KINDS, v.kind)) && isString(v.name) && Array.isArray(v.scopes),
+  created: (v) => isObject(v) && isString(v.id),
+  document: (v) => isObject(v) && isString(v.id) && isString(v.text),
+  thread: (v) => isObject(v) && isString(v.id) && isObject(v.anchor) && (v.status === "open" || v.status === "resolved") && Array.isArray(v.messages),
+  threads: (v) => Array.isArray(v) && v.every(SHAPES.thread),
+  message: (v) => isObject(v) && isString(v.id) && isString(v.body) && isObject(v.author),
+  suggestion: (v) => isObject(v) && isString(v.id) && isObject(v.anchor) && isString(v.status) && isObject(v.author),
+  suggestions: (v) => Array.isArray(v) && v.every(SHAPES.suggestion)
+};
+function createClient(options) {
+  if (typeof options.baseUrl !== "string" || options.baseUrl === "") throw new TypeError("createClient needs a baseUrl");
+  if (typeof options.token !== "string" || options.token === "") throw new TypeError("createClient needs a token");
+  let origin;
+  try {
+    origin = new URL(options.baseUrl);
+  } catch {
+    throw new TypeError("baseUrl must be an absolute URL");
+  }
+  if (origin.protocol !== "https:" && origin.protocol !== "http:") throw new TypeError("baseUrl must be an http or https URL");
+  if (origin.search !== "" || origin.hash !== "" || origin.username !== "" || origin.password !== "") {
+    throw new TypeError("baseUrl must have no query, hash, or credentials");
+  }
+  const root = `${origin.origin}${origin.pathname.replace(/\/+$/, "")}/api/v1`;
+  const token = options.token;
+  const send = (input, init) => {
+    const run = options.fetch ?? globalThis.fetch;
+    return run(input, init);
+  };
+  const seg = (value) => {
+    if (typeof value !== "string" || /^(?:\.|%2e){0,2}$/i.test(value)) throw new TypeError("an id must be a non-empty string that is not . or ..");
+    return encodeURIComponent(value);
+  };
+  const query = (filter) => {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(filter ?? {})) if (value !== void 0) params.set(key, String(value));
+    const text = params.toString();
+    return text === "" ? "" : `?${text}`;
+  };
+  async function call(method, path, body, callOptions, shape) {
+    const headers = { authorization: `Bearer ${token}` };
+    if (body !== void 0) headers["content-type"] = "application/json";
+    const response = await send(`${root}${path}`, {
+      method,
+      headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body),
+      signal: callOptions?.signal,
+      // Never follow a redirect: it would send a write to another host.
+      redirect: "manual"
+    });
+    const text = await response.text();
+    let parsed;
+    try {
+      parsed = text === "" ? void 0 : JSON.parse(text);
+    } catch {
+      parsed = void 0;
+    }
+    if (!response.ok) {
+      const error = parsed?.error;
+      const code = isKnownCode(error?.code) ? error.code : "UNKNOWN";
+      const message = typeof error?.message === "string" ? error.message : `HTTP ${response.status}`;
+      throw new CommentsApiError(code, response.status, message);
+    }
+    if (!SHAPES[shape](parsed)) throw new CommentsApiError("UNKNOWN", response.status, `the reply is not a ${shape}`);
+    return parsed;
+  }
+  const doc = (id) => `/docs/${seg(id)}`;
+  const thread = (id, threadId) => `${doc(id)}/threads/${seg(threadId)}`;
+  const suggestion = (id, suggestionId) => `${doc(id)}/suggestions/${seg(suggestionId)}`;
+  const methods = {
+    me: (o) => call("GET", "/me", void 0, o, "me"),
+    createDocument: (input, o) => call("POST", "/docs", input, o, "created"),
+    getDocument: (id, o) => call("GET", doc(id), void 0, o, "document"),
+    listThreads: (id, filter, o) => call("GET", `${doc(id)}/threads${query(filter)}`, void 0, o, "threads"),
+    getThread: (id, threadId, o) => call("GET", thread(id, threadId), void 0, o, "thread"),
+    addThread: (id, input, o) => call("POST", `${doc(id)}/threads`, input, o, "thread"),
+    reply: (id, threadId, input, o) => call("POST", `${thread(id, threadId)}/replies`, input, o, "message"),
+    resolve: (id, threadId, o) => call("POST", `${thread(id, threadId)}/resolve`, void 0, o, "thread"),
+    reopen: (id, threadId, o) => call("POST", `${thread(id, threadId)}/reopen`, void 0, o, "thread"),
+    relocate: (id, threadId, o) => call("POST", `${thread(id, threadId)}/relocate`, void 0, o, "thread"),
+    listSuggestions: (id, filter, o) => call("GET", `${doc(id)}/suggestions${query(filter)}`, void 0, o, "suggestions"),
+    suggest: (id, input, o) => call("POST", `${doc(id)}/suggestions`, input, o, "suggestion"),
+    accept: (id, suggestionId, o) => call("POST", `${suggestion(id, suggestionId)}/accept`, void 0, o, "suggestion"),
+    reject: (id, suggestionId, o) => call("POST", `${suggestion(id, suggestionId)}/reject`, void 0, o, "suggestion")
+  };
+  return Object.fromEntries(
+    Object.entries(methods).map(([name, method]) => [name, async (...args) => method(...args)])
+  );
+}
+export {
+  CommentsApiError,
+  createClient
+};

package/dist/errors-CNgWMVQT.d.ts

@@ -0,0 +1,7 @@
+type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
+declare class CommentsError extends Error {
+    readonly code: CommentsErrorCode;
+    constructor(code: CommentsErrorCode, message: string);
+}
+
+export { type CommentsErrorCode as C, CommentsError as a };

package/dist/index.d.ts

@@ -1,16 +1,11 @@
-import { a as Author, C as Comments, b as Suggestions } from './suggestions-oj8fd-nG.js';
-export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, S as Suggestion, p as SuggestionFilter, q as SuggestionHost, r as TextAnchor, T as Thread, s as ThreadFilter, t as authorLabel, u as stamp, v as textAnchor, w as textOf } from './suggestions-oj8fd-nG.js';
+import { a as Author, C as Comments, b as Suggestions } from './suggestions-CvJwo6r4.js';
+export { c as ACCEPT_SCOPE, A as Actor, d as Anchor, e as AnchorKind, f as AnchorState, g as ApplyContext, h as CanvasAnchor, i as CellAnchor, j as CommentsOptions, M as Message, N as NewReply, k as NewSuggestion, l as NewThread, R as RelativePositionJson, m as RevertContext, n as SlideAnchor, o as StampInput, S as Suggestion, p as SuggestionFilter, q as SuggestionHost, r as TextAnchor, T as Thread, s as ThreadFilter, t as authorLabel, u as stamp, v as textAnchor, w as textOf } from './suggestions-CvJwo6r4.js';
+export { a as CommentsError, C as CommentsErrorCode } from './errors-CNgWMVQT.js';
 export { PRINCIPAL_KINDS, PrincipalKind } from 'agentic-identity';
 import 'yjs';
 
 declare const VERSION: string;
 
-type CommentsErrorCode = "INVALID_AUTHOR" | "INVALID_INPUT" | "INVALID_ANCHOR" | "NO_THREAD" | "THREAD_RESOLVED" | "CORRUPT" | "NO_SUGGESTION" | "FORBIDDEN" | "ALREADY_DECIDED" | "APPLY_FAILED" | "RELOCATE_FAILED" | "STORE_MISSING" | "STORE_EXISTS" | "STORE_CORRUPT" | "STORE_LOCKED" | "STORE_FULL" | "NO_DOCUMENT" | "DOCUMENT_EXISTS" | "CONFLICT" | "MISCONFIGURED" | "USAGE";
-declare class CommentsError extends Error {
-    readonly code: CommentsErrorCode;
-    constructor(code: CommentsErrorCode, message: string);
-}
-
 type CommentEventType = "thread.created" | "message.added" | "mention" | "thread.resolved" | "thread.reopened" | "suggestion.created" | "suggestion.accepted" | "suggestion.rejected";
 /**
  * One change, in terms a notifier can route. It holds ids and never the text of a comment, a suggestion, or
@@ -103,4 +98,4 @@ declare class Notifications {
     private decided;
 }
 
-export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, CommentsError, type CommentsErrorCode, Notifications, type NotificationsOptions, Suggestions, VERSION };
+export { Author, type CommentEvent, type CommentEventType, type CommentListener, Comments, Notifications, type NotificationsOptions, Suggestions, VERSION };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-WQHJNHAR.js";
 import {
   ACCEPT_SCOPE,
   Actor,

package/dist/local.d.ts

@@ -1,6 +1,6 @@
 import * as Y from 'yjs';
-export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-Dxw9TVxY.js';
-import { q as SuggestionHost, A as Actor } from './suggestions-oj8fd-nG.js';
+export { A as AnchorSpec, C as CommentsService, L as ListFilter } from './service-hpWbnSmc.js';
+import { q as SuggestionHost, A as Actor } from './suggestions-CvJwo6r4.js';
 import 'agentic-identity';
 
 /** The most bytes a saved document holds. A save over this is refused, so a file never grows past what a load accepts. */

package/dist/{mcp-ACC4QIEM.js → mcp-JMEXA2RI.js}

@@ -1,8 +1,8 @@
 import {
   createMcpServer,
   startMcp
-} from "./chunk-R4LH36VG.js";
-import "./chunk-DRACF66Y.js";
+} from "./chunk-ABXAPWXD.js";
+import "./chunk-WQHJNHAR.js";
 import "./chunk-NQWRFKJ6.js";
 import "./chunk-BSNBDKR2.js";
 export {

package/dist/mcp-bin.js

@@ -6,10 +6,10 @@ import {
 } from "./chunk-HXXJNFEO.js";
 import {
   startMcp
-} from "./chunk-R4LH36VG.js";
+} from "./chunk-ABXAPWXD.js";
 import {
   VERSION
-} from "./chunk-DRACF66Y.js";
+} from "./chunk-WQHJNHAR.js";
 import "./chunk-NQWRFKJ6.js";
 import "./chunk-BSNBDKR2.js";
 

package/dist/{service-Dxw9TVxY.d.ts → service-hpWbnSmc.d.ts}

@@ -1,5 +1,5 @@
 import * as Y from 'yjs';
-import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-oj8fd-nG.js';
+import { A as Actor, T as Thread, M as Message, S as Suggestion } from './suggestions-CvJwo6r4.js';
 
 /** Where a comment or suggestion points, in terms a person or agent can write down. */
 type AnchorSpec = {

package/dist/worker.d.ts

@@ -1,8 +1,8 @@
 import { Hono } from 'hono';
 import { Auth, Store, PrincipalContext, Region } from 'agentic-identity';
 import { D1Like } from 'agentic-identity/cloudflare';
-import { A as Actor } from './suggestions-oj8fd-nG.js';
-import { C as CommentsService } from './service-Dxw9TVxY.js';
+import { A as Actor } from './suggestions-CvJwo6r4.js';
+import { C as CommentsService } from './service-hpWbnSmc.js';
 import 'yjs';
 
 interface WorkerEnv {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-comments",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Comment threads and suggestions anchored to any content, from people and agents.",
   "keywords": [
     "comments",
@@ -48,6 +48,10 @@
       "types": "./dist/anchoring.d.ts",
       "import": "./dist/anchoring.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./local": {
       "types": "./dist/local.d.ts",
       "import": "./dist/local.js"

package/dist/{suggestions-oj8fd-nG.d.ts → suggestions-CvJwo6r4.d.ts}

@@ -1,6 +1,35 @@
 import * as Y from 'yjs';
 import { PrincipalKind } from 'agentic-identity';
 
+/** What a thread keeps about who wrote a message. Scopes never reach storage. */
+interface Author {
+    kind: PrincipalKind;
+    name: string;
+}
+interface StampInput {
+    kind: PrincipalKind;
+    name: string;
+    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
+    scopes?: string[];
+}
+/**
+ * The only author a write accepts. The host makes one from the principal it authenticated, and an
+ * operation never reads an author from its input. An object that `stamp()` did not make is refused,
+ * and a stamped one cannot change.
+ */
+declare class Actor implements Author {
+    readonly kind: PrincipalKind;
+    readonly name: string;
+    readonly scopes: readonly string[];
+    private constructor();
+    static of(input: StampInput): Actor;
+    static is(value: unknown): value is Actor;
+}
+/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
+declare const stamp: (input: StampInput) => Actor;
+/** The label a UI shows. Agent work stays marked as machine-made. */
+declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
+
 /** A Yjs relative position as JSON. It names an item, not an index, so it follows its text. */
 interface RelativePositionJson {
     type?: {
@@ -66,35 +95,6 @@ declare function textOf(type: Y.Text | Y.XmlText): string;
 /** Pin a range of a Yjs text. Later edits by any replica do not move the anchor off its text. */
 declare function textAnchor(type: Y.Text | Y.XmlText, from: number, to: number): TextAnchor;
 
-/** What a thread keeps about who wrote a message. Scopes never reach storage. */
-interface Author {
-    kind: PrincipalKind;
-    name: string;
-}
-interface StampInput {
-    kind: PrincipalKind;
-    name: string;
-    /** Rights the host granted this principal, such as `comments:accept`. Used to decide, never stored. */
-    scopes?: string[];
-}
-/**
- * The only author a write accepts. The host makes one from the principal it authenticated, and an
- * operation never reads an author from its input. An object that `stamp()` did not make is refused,
- * and a stamped one cannot change.
- */
-declare class Actor implements Author {
-    readonly kind: PrincipalKind;
-    readonly name: string;
-    readonly scopes: readonly string[];
-    private constructor();
-    static of(input: StampInput): Actor;
-    static is(value: unknown): value is Actor;
-}
-/** Make the author for one authenticated principal. Throws when the kind or name is missing or wrong. */
-declare const stamp: (input: StampInput) => Actor;
-/** The label a UI shows. Agent work stays marked as machine-made. */
-declare function authorLabel(author: Author): "person" | "person via agent" | "agent";
-
 interface Message {
     id: string;
     at: string;