web-comments 0.0.1 → 1.0.0

package/dist/react.js

@@ -0,0 +1,19 @@
+// src/react.ts
+import { useEffect, useRef } from "react";
+import { mountComments } from "web-comments";
+function Comments(props) {
+  const latest = useRef(props);
+  latest.current = props;
+  useEffect(() => {
+    const handle = mountComments({
+      ...latest.current,
+      page: () => latest.current.page?.() ?? location.pathname,
+      headers: async () => await latest.current.headers?.() ?? {}
+    });
+    return () => handle.unmount();
+  }, []);
+  return null;
+}
+export {
+  Comments
+};

package/dist/server.js

@@ -0,0 +1,11 @@
+import {
+  CommentsError,
+  createComments,
+  newId
+} from "./chunks/chunk-RRSB326L.js";
+import "./chunks/chunk-WSFCRVEQ.js";
+export {
+  CommentsError,
+  createComments,
+  newId
+};

package/dist/store/d1.js

@@ -0,0 +1,16 @@
+import {
+  drizzleStore
+} from "../chunks/chunk-T4WN3STA.js";
+import "../chunks/chunk-7K7K7M5O.js";
+import "../chunks/chunk-WY5E2C47.js";
+import "../chunks/chunk-644PTNSO.js";
+import "../chunks/chunk-WSFCRVEQ.js";
+
+// src/store/d1.ts
+import { drizzle } from "drizzle-orm/d1";
+function d1Store(binding, options = {}) {
+  return drizzleStore({ db: drizzle(binding), dialect: "sqlite", ...options });
+}
+export {
+  d1Store
+};

package/dist/store/drizzle/mysql.js

@@ -0,0 +1,17 @@
+import {
+  comments,
+  createTablesSql,
+  links,
+  threads,
+  users,
+  values
+} from "../../chunks/chunk-WY5E2C47.js";
+import "../../chunks/chunk-WSFCRVEQ.js";
+export {
+  comments,
+  createTablesSql,
+  links,
+  threads,
+  users,
+  values
+};

package/dist/store/drizzle/pg.js

@@ -0,0 +1,17 @@
+import {
+  comments,
+  createTablesSql,
+  links,
+  threads,
+  users,
+  values
+} from "../../chunks/chunk-7K7K7M5O.js";
+import "../../chunks/chunk-WSFCRVEQ.js";
+export {
+  comments,
+  createTablesSql,
+  links,
+  threads,
+  users,
+  values
+};

package/dist/store/drizzle/sqlite.js

@@ -0,0 +1,17 @@
+import {
+  comments,
+  createTablesSql,
+  links,
+  threads,
+  users,
+  values
+} from "../../chunks/chunk-644PTNSO.js";
+import "../../chunks/chunk-WSFCRVEQ.js";
+export {
+  comments,
+  createTablesSql,
+  links,
+  threads,
+  users,
+  values
+};

package/dist/store/drizzle.js

@@ -0,0 +1,10 @@
+import {
+  drizzleStore
+} from "../chunks/chunk-T4WN3STA.js";
+import "../chunks/chunk-7K7K7M5O.js";
+import "../chunks/chunk-WY5E2C47.js";
+import "../chunks/chunk-644PTNSO.js";
+import "../chunks/chunk-WSFCRVEQ.js";
+export {
+  drizzleStore
+};

package/dist/store/memory.js

@@ -0,0 +1,109 @@
+import "../chunks/chunk-WSFCRVEQ.js";
+
+// src/store/memory.ts
+function memoryStore() {
+  const threads = /* @__PURE__ */ new Map();
+  const comments = /* @__PURE__ */ new Map();
+  const links = /* @__PURE__ */ new Map();
+  const values = /* @__PURE__ */ new Map();
+  const linkKey = (site, connector, externalId) => JSON.stringify([site, connector, externalId]);
+  function withComments(thread) {
+    const own = [...comments.values()].filter((c) => c.threadId === thread.id).sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+    return structuredClone({ ...thread, comments: own });
+  }
+  function find(site, id) {
+    const thread = threads.get(id);
+    return thread && thread.site === site ? thread : void 0;
+  }
+  return {
+    async listThreads(site, { page, limit }) {
+      const list = [...threads.values()].filter(
+        (t) => t.site === site && (page === void 0 || t.page === page)
+      );
+      list.sort(
+        (a, b) => page === void 0 ? b.createdAt.localeCompare(a.createdAt) : a.createdAt.localeCompare(b.createdAt)
+      );
+      return list.slice(0, limit).map(withComments);
+    },
+    async getThread(site, id) {
+      const thread = find(site, id);
+      return thread ? withComments(thread) : null;
+    },
+    async insertThread(thread, first) {
+      const { comments: _, ...rest } = structuredClone(thread);
+      threads.set(thread.id, rest);
+      comments.set(first.id, structuredClone(first));
+    },
+    async insertComment(site, comment) {
+      if (find(site, comment.threadId)) comments.set(comment.id, structuredClone(comment));
+    },
+    async updateThread(site, id, changes) {
+      const thread = find(site, id);
+      if (thread) Object.assign(thread, structuredClone(changes));
+    },
+    async getComment(site, id) {
+      const comment = comments.get(id);
+      return comment && find(site, comment.threadId) ? structuredClone(comment) : null;
+    },
+    async deleteComment(site, id) {
+      const comment = comments.get(id);
+      if (comment && find(site, comment.threadId)) comments.delete(id);
+    },
+    async deleteThread(site, id) {
+      if (!find(site, id)) return;
+      threads.delete(id);
+      for (const [key, comment] of comments) if (comment.threadId === id) comments.delete(key);
+      for (const [key, link] of links) {
+        if (link.site === site && link.threadId === id) links.delete(key);
+      }
+    },
+    async saveLink(site, link) {
+      links.set(linkKey(site, link.connector, link.externalId), { ...structuredClone(link), site });
+    },
+    async findLink(site, connector, externalId) {
+      const link = links.get(linkKey(site, connector, externalId));
+      if (!link) return null;
+      const { site: _, ...rest } = link;
+      return structuredClone(rest);
+    },
+    async listLinks(site, threadIds) {
+      const wanted = new Set(threadIds);
+      return [...links.values()].filter((link) => link.site === site && wanted.has(link.threadId)).map(({ site: _, ...rest }) => structuredClone(rest));
+    },
+    async getValue(name) {
+      const entry = values.get(name);
+      if (!entry) return null;
+      if (entry.expiresAt !== null && entry.expiresAt <= (/* @__PURE__ */ new Date()).toISOString()) {
+        values.delete(name);
+        return null;
+      }
+      return entry.value;
+    },
+    async setValue(name, value, expiresAt) {
+      values.set(name, { value, expiresAt });
+    },
+    async deleteValue(name) {
+      values.delete(name);
+    }
+  };
+}
+function memoryAssets() {
+  const blobs = /* @__PURE__ */ new Map();
+  return {
+    async put(key, body, contentType) {
+      blobs.set(key, { body: body.slice(0), contentType });
+    },
+    async get(key) {
+      const blob = blobs.get(key);
+      return blob ? { body: blob.body.slice(0), contentType: blob.contentType } : null;
+    },
+    async delete(key) {
+      blobs.delete(key);
+    },
+    size: () => blobs.size
+  };
+}
+export {
+  memoryAssets,
+  memoryStore
+};

package/dist/store/r2.js

@@ -0,0 +1,25 @@
+import "../chunks/chunk-WSFCRVEQ.js";
+
+// src/store/r2.ts
+function r2Assets(bucket, options = {}) {
+  const prefix = options.prefix ?? "";
+  return {
+    async put(key, body, contentType) {
+      await bucket.put(prefix + key, body, { httpMetadata: { contentType } });
+    },
+    async get(key) {
+      const object = await bucket.get(prefix + key);
+      if (!object) return null;
+      return {
+        body: object.body,
+        contentType: object.httpMetadata?.contentType ?? "application/octet-stream"
+      };
+    },
+    async delete(key) {
+      await bucket.delete(prefix + key);
+    }
+  };
+}
+export {
+  r2Assets
+};

package/dist/store/s3.js

@@ -0,0 +1,43 @@
+import "../chunks/chunk-WSFCRVEQ.js";
+
+// src/store/s3.ts
+import { AwsClient } from "aws4fetch";
+function s3Assets(options) {
+  const client = new AwsClient({
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    region: options.region ?? "auto",
+    service: "s3"
+  });
+  const base = `${options.endpoint.replace(/\/+$/, "")}/${encodeURIComponent(options.bucket)}/`;
+  const urlFor = (key) => base + `${options.prefix ?? ""}${key}`.split("/").map(encodeURIComponent).join("/");
+  return {
+    async put(key, body, contentType) {
+      const response = await client.fetch(urlFor(key), {
+        method: "PUT",
+        body,
+        headers: { "content-type": contentType }
+      });
+      if (!response.ok) throw new Error(`S3 PUT ${key} answered ${response.status}`);
+    },
+    async get(key) {
+      const response = await client.fetch(urlFor(key));
+      if (response.status === 404) return null;
+      if (!response.ok || !response.body)
+        throw new Error(`S3 GET ${key} answered ${response.status}`);
+      return {
+        body: response.body,
+        contentType: response.headers.get("content-type") ?? "application/octet-stream"
+      };
+    },
+    async delete(key) {
+      const response = await client.fetch(urlFor(key), { method: "DELETE" });
+      if (!response.ok && response.status !== 404) {
+        throw new Error(`S3 DELETE ${key} answered ${response.status}`);
+      }
+    }
+  };
+}
+export {
+  s3Assets
+};

package/dist/types/auth/bearer-token.d.ts

@@ -0,0 +1,13 @@
+import type { AuthPlugin, Identity } from "../server/auth";
+export interface BearerTokenEntry {
+    /** At least 24 characters. Generate one with `openssl rand -base64 32`. */
+    token: string;
+    name: string;
+    kind?: Identity["kind"];
+    email?: string;
+}
+/**
+ * Identifies callers by `Authorization: Bearer <token>`: agents, MCP clients,
+ * scripts. Tokens usually live in a secret, so they may come from env.
+ */
+export declare function bearerToken<Env = unknown>(tokens: BearerTokenEntry[] | ((env: Env) => BearerTokenEntry[])): AuthPlugin<Env>;

package/dist/types/auth/cloudflare-access.d.ts

@@ -0,0 +1,33 @@
+import { type JWTVerifyGetKey } from "jose";
+import type { AuthPlugin, Identity } from "../server/auth";
+export interface CloudflareAccessOptions {
+    /** Your Zero Trust team domain, e.g. "acme.cloudflareaccess.com". */
+    teamDomain: string;
+    /** The Access application's Audience (AUD) tag. Several, if one Worker sits behind more than one app. */
+    audience: string | string[];
+    /**
+     * Service tokens that may call the API, keyed by their Client ID. Access
+     * lets them through as tokens, not people; this names them and marks them
+     * as agents unless told otherwise.
+     */
+    serviceTokens?: Record<string, {
+        name: string;
+        kind?: Identity["kind"];
+    }>;
+    /**
+     * Ask Access for the person's display name (one request per person per
+     * hour). Without it the name comes from the email address.
+     */
+    fetchIdentity?: boolean;
+    /** Replaces the team's published signing keys. For tests. */
+    keys?: JWTVerifyGetKey;
+}
+/**
+ * Identifies people (and service tokens) that Cloudflare Access let through.
+ * Access puts a signed JWT on every request it forwards; this checks the
+ * signature, issuer and audience before trusting it. Options may come from
+ * env, as Worker configuration usually does.
+ */
+export declare function cloudflareAccess<Env = unknown>(options: CloudflareAccessOptions | ((env: Env) => CloudflareAccessOptions)): AuthPlugin<Env>;
+/** "ada.lovelace@example.com" → "Ada Lovelace" */
+export declare function nameFromEmail(email: string): string;

package/dist/types/auth/dev-user.d.ts

@@ -0,0 +1,6 @@
+import type { AuthPlugin, Identity } from "../server/auth";
+/**
+ * Treats every request as one fixed person. For local development only:
+ * anyone who can reach the API becomes that person.
+ */
+export declare function devUser(identity?: Partial<Identity>): AuthPlugin;

package/dist/types/auth/session-endpoint.d.ts

@@ -0,0 +1,25 @@
+import type { AuthPlugin, Identity } from "../server/auth";
+export interface SessionEndpointOptions<Env> {
+    /**
+     * Your app's "who is signed in?" endpoint. It gets the request's
+     * credentials (see `forward`) and answers with the person, or 401.
+     */
+    url: string | URL | ((request: Request, env: Env) => string | URL);
+    /** Request headers passed along to it. Default: cookie and authorization. */
+    forward?: string[];
+    /** Turns its JSON answer into an Identity. Return null to turn the person away. */
+    identity: (body: unknown, request: Request) => Identity | null | Promise<Identity | null>;
+    /** How long an answer is reused for the same credentials, in ms. Default 30 000; 0 turns it off. */
+    cacheFor?: number;
+    /** Where to send people who aren't signed in. */
+    loginUrl?: (request: Request) => string | undefined;
+}
+/**
+ * Identifies people by asking an endpoint your app already has, with the
+ * request's own cookies or token: any sign-in system that can say who is
+ * signed in works, without web-comments knowing how it signs people in.
+ *
+ * A 401, 403 or redirect means "not signed in" (the next plugin gets a go);
+ * any other failure is an error rather than a silent sign-out.
+ */
+export declare function sessionEndpoint<Env = unknown>(options: SessionEndpointOptions<Env>): AuthPlugin<Env>;

package/dist/types/connectors/linear/index.d.ts

@@ -0,0 +1,46 @@
+import type { Connector, Thread } from "../../server";
+export interface LinearOptions {
+    /**
+     * How to call Linear:
+     * - `{ apiKey }`: a personal API key (lin_api_...). Issues and comments are
+     *   that person's; who said what is written into them.
+     * - `{ accessToken }`: an OAuth token.
+     * - `{ clientId, clientSecret }`: an OAuth app with client credentials
+     *   enabled. Issues and comments are the app's, shown under each
+     *   commenter's name and picture.
+     */
+    auth: {
+        apiKey: string;
+    } | {
+        accessToken: string;
+    } | {
+        clientId: string;
+        clientSecret: string;
+    };
+    /** The team new issues go to: its key ("ENG") or id. */
+    team: string;
+    /**
+     * The signing secret of a Linear webhook (Issues and Comments) pointed at
+     * `{basePath}/linear/webhook`. With it, Linear's side comes back: comments
+     * there become replies, and finishing or reopening the issue resolves or
+     * reopens the thread.
+     */
+    webhookSecret?: string;
+    /** Labels to put on new issues, by id. */
+    labelIds?: string[];
+    /** The project new issues go into, by id. */
+    projectId?: string;
+    /** Which threads become issues. All of them, by default. */
+    filter?: (thread: Thread) => boolean;
+    /** Linear's GraphQL endpoint; for tests. */
+    apiUrl?: string;
+}
+/**
+ * Every thread becomes a Linear issue, with its screenshots, and stays in
+ * step with it: replies go both ways, and resolving one resolves the other.
+ * Options can depend on the environment; returning null leaves Linear out
+ * of that one (say, until its secrets are set).
+ *
+ *   connectors: [linear((env) => ({ auth: { apiKey: env.LINEAR_API_KEY }, team: "ENG", webhookSecret: env.LINEAR_WEBHOOK_SECRET }))]
+ */
+export declare function linear<Env = unknown>(options: LinearOptions | ((env: Env) => LinearOptions | null)): Connector<Env>;

package/dist/types/connectors/mcp/index.d.ts

@@ -0,0 +1,21 @@
+import type { Connector } from "../../server";
+export interface McpOptions {
+    /** What the server calls itself, to MCP clients and on the approval page. Default "web-comments". */
+    name?: string;
+    /** How long an access token lasts, in seconds. Default an hour. */
+    accessTokenTtl?: number;
+    /** How long a refresh token lasts unused, in seconds. Default 30 days. */
+    refreshTokenTtl?: number;
+}
+/**
+ * An MCP server for comments, at `{basePath}/mcp`: agents list threads, read
+ * one with its screenshots and the element it's on, reply, and resolve or
+ * reopen it. MCP clients sign in with OAuth: the person approving one is
+ * whoever the API already recognises in their browser, and the agent then
+ * acts as them. Requests the auth plugins recognise directly (a
+ * `bearerToken`, an Access service token) are let in too.
+ *
+ *   connectors: [mcp()]
+ *   claude mcp add --transport http comments https://app.example.com/__comments/mcp
+ */
+export declare function mcp<Env = unknown>(options?: McpOptions): Connector<Env>;

package/dist/types/connectors/mcp/oauth.d.ts

@@ -0,0 +1,50 @@
+import type { ConnectorRequestContext, ConnectorStorage, Identity } from "../../server";
+export declare const SCOPE = "comments";
+export interface OAuthOptions {
+    /** What people approving a client are told they're signing in to. */
+    name: string;
+    accessTokenTtl: number;
+    refreshTokenTtl: number;
+}
+/** What a token stands for. */
+export interface Grant {
+    identity: Identity;
+    clientId: string;
+    clientName: string;
+    site: string;
+    resource: string;
+    scope: string;
+}
+/** Where everything is, for one request's origin. */
+export declare function endpoints(base: string): {
+    resource: string;
+    issuer: string;
+    authorize: string;
+    token: string;
+    register: string;
+    revoke: string;
+    jwks: string;
+    resourceMetadata: string;
+};
+export declare const CORS: {
+    "access-control-allow-origin": string;
+    "access-control-allow-methods": string;
+    "access-control-allow-headers": string;
+    "access-control-expose-headers": string;
+    "access-control-max-age": string;
+};
+/** RFC 9728: which authorization server guards the MCP endpoint. */
+export declare function protectedResourceMetadata(base: string): Response;
+/**
+ * RFC 8414, also served as OpenID discovery, which is the one place under
+ * the API's own path a client looks. This server issues no ID tokens; the
+ * JWKS and ID token fields are there because OIDC discovery parsers require
+ * them.
+ */
+export declare function authorizationServerMetadata(base: string, oidc: boolean): Response;
+export declare function jwks(): Response;
+/** The grant behind an access token, or null if it isn't a live one. */
+export declare function grantOf(storage: ConnectorStorage, token: string): Promise<Grant | null>;
+export declare function looksLikeOurToken(token: string): boolean;
+/** Answers the OAuth paths under the connector's base; null for anything else. */
+export declare function handleOAuth(request: Request, path: string, context: ConnectorRequestContext, options: OAuthOptions): Promise<Response | null>;

package/dist/types/connectors/mcp/pages.d.ts

@@ -0,0 +1,14 @@
+import type { Identity } from "../../server";
+export declare function consentPage(input: {
+    product: string;
+    host: string;
+    app: string;
+    appHost: string;
+    who: Identity;
+    action: string;
+    consentId: string;
+}): string;
+export declare function messagePage(product: string, title: string, message: string, link?: {
+    label: string;
+    href: string;
+}): string;

package/dist/types/react.d.ts

@@ -0,0 +1,8 @@
+import { type MountOptions } from "web-comments";
+export type { CommentsHandle, MountOptions } from "web-comments";
+/**
+ * Mounts the comments toolbar while rendered. Renders nothing itself.
+ * `page` and `headers` may change between renders; the other options are
+ * read once, when it mounts.
+ */
+export declare function Comments(props: MountOptions): null;

package/dist/types/server/auth.d.ts

@@ -0,0 +1,16 @@
+import type { Identity } from "../shared/types";
+export type { Identity };
+/**
+ * Answers "who is this?" for a request. Return null when the request isn't
+ * yours to judge (no header, no cookie), so the next plugin can try.
+ * Throw only for real failures; a bad credential should also return null.
+ */
+export interface AuthPlugin<Env = unknown> {
+    name: string;
+    authenticate(request: Request, env: Env): Promise<Identity | null>;
+    /** Where to send someone no plugin recognised. */
+    loginUrl?(request: Request): string | undefined;
+}
+/** Runs the plugins in order and returns the first identity any of them reports. */
+export declare function identify<Env>(plugins: readonly AuthPlugin<Env>[], request: Request, env: Env): Promise<Identity | null>;
+export declare function loginUrlFor<Env>(plugins: readonly AuthPlugin<Env>[], request: Request): string | undefined;

package/dist/types/server/connector.d.ts

@@ -0,0 +1,102 @@
+import type { Comment, Identity, ScreenshotKind, Thread, ThreadStatus } from "../shared/types";
+import type { CommentsEvent } from "./events";
+import type { ThreadLink } from "./store";
+/**
+ * Takes comments somewhere else, or lets something else in: a Linear issue
+ * per thread, an MCP server for agents, a Slack channel, ... Connectors see
+ * every change as it happens, can answer requests of their own under
+ * `{basePath}/{name}`, and act on comments by the same rules as the API.
+ *
+ * Built in: `web-comments/connectors/linear` and `web-comments/connectors/mcp`.
+ */
+export interface Connector<Env = unknown> {
+    /** Lowercase, unique: it names the connector's routes, links and stored state. */
+    name: string;
+    /**
+     * After every change, once the response has gone out. Changes this
+     * connector made itself (through `as()`) aren't sent back to it.
+     */
+    onEvent?(event: CommentsEvent, context: ConnectorContext<Env>): void | Promise<void>;
+    /**
+     * Requests under `{basePath}/{name}` (and `rootPaths`). Nobody is signed in
+     * for them: check the caller yourself (a webhook's signature, a token), or
+     * ask `context.identify()` for the visitor the API itself would see.
+     */
+    fetch?(request: Request, context: ConnectorRequestContext<Env>): Response | Promise<Response>;
+    /**
+     * Paths at the root of the origin this connector answers too, such as
+     * OAuth's `/.well-known/...` documents. They only arrive if the host
+     * sends them (see `matches()`).
+     */
+    rootPaths?(basePath: string): string[];
+}
+export interface ConnectorContext<Env = unknown> {
+    env: Env;
+    site: string;
+    /** Where the API is mounted, e.g. "/__comments". */
+    basePath: string;
+    /**
+     * Acts on comments as someone, by the API's rules (only authors delete
+     * their comments, and so on). Changes are announced like the API's own,
+     * with this connector as their `source`.
+     */
+    as(actor: Identity): CommentsActions;
+    /** Links between threads and what this connector keeps elsewhere. */
+    links: {
+        find(externalId: string): Promise<ThreadLink | null>;
+        forThread(threadId: string): Promise<ThreadLink[]>;
+        save(link: {
+            externalId: string;
+            threadId: string;
+            commentId?: string | null;
+            url?: string | null;
+            title?: string | null;
+        }): Promise<void>;
+    };
+    /** State of this connector's own, by key (kept apart from other connectors'). */
+    storage: ConnectorStorage;
+    /** A thread's screenshot, straight from the asset store. */
+    screenshot(thread: Thread, kind: ScreenshotKind): Promise<{
+        body: ArrayBuffer;
+        contentType: string;
+    } | null>;
+    /** The page the thread is on, with the thread open. */
+    threadUrl(thread: Thread): string;
+    /** Keeps the request alive for work that finishes after the response. */
+    waitUntil(work: Promise<unknown>): void;
+}
+export interface ConnectorRequestContext<Env = unknown> extends ConnectorContext<Env> {
+    /** This connector's own address: `{origin}{basePath}/{name}`. */
+    url: string;
+    /**
+     * Who a request is from by the API's own sign-in (its auth plugins and
+     * `authorize`), or null: e.g. the person approving an OAuth client.
+     */
+    identify(request: Request): Promise<Identity | null>;
+    /** Where the auth plugins send someone to sign in, if they know. */
+    loginUrl(request: Request): string | undefined;
+}
+export interface ConnectorStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** What a connector may do with comments, as whoever it acts for. */
+export interface CommentsActions {
+    /** Threads on one page (oldest first), or the site's most recent (newest first). */
+    listThreads(query?: {
+        page?: string;
+        status?: ThreadStatus;
+        limit?: number;
+    }): Promise<Thread[]>;
+    getThread(id: string): Promise<Thread | null>;
+    reply(threadId: string, body: string): Promise<{
+        thread: Thread;
+        comment: Comment;
+    }>;
+    setStatus(threadId: string, status: ThreadStatus): Promise<Thread>;
+    /** Deleting the comment that opens a thread deletes the thread. */
+    deleteComment(commentId: string): Promise<void>;
+}