web-comments 0.1.0 → 1.0.0

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/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>;
+}

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

@@ -0,0 +1,31 @@
+import type { Comment, Identity, Thread } from "../shared/types";
+/**
+ * A change, as integrations hear about it. `source` names the connector that
+ * made it, for changes that came in through one (a reply from Linear); the
+ * API's own have none.
+ */
+export type CommentsEvent = ({
+    type: "thread.created";
+    thread: Thread;
+    actor: Identity;
+} | {
+    type: "comment.created";
+    thread: Thread;
+    comment: Comment;
+    actor: Identity;
+} | {
+    type: "thread.resolved" | "thread.reopened" | "thread.moved";
+    thread: Thread;
+    actor: Identity;
+} | {
+    type: "comment.deleted";
+    threadId: string;
+    commentId: string;
+    actor: Identity;
+} | {
+    type: "thread.deleted";
+    threadId: string;
+    actor: Identity;
+}) & {
+    source?: string;
+};

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

@@ -1,32 +1,15 @@
-import type { Comment, Identity, Thread } from "../shared/types";
+import { Hono } from "hono";
+import type { Identity } from "../shared/types";
 import { type AuthPlugin } from "./auth";
+import type { Connector } from "./connector";
+import type { CommentsEvent } from "./events";
 import type { AssetStore, CommentsStore } from "./store";
 export type * from "../shared/types";
 export type { AuthPlugin } from "./auth";
-export type { AssetStore, CommentsStore, StoredScreenshot, StoredThread, ThreadChanges, } from "./store";
-export type CommentsEvent = {
-    type: "thread.created";
-    thread: Thread;
-    actor: Identity;
-} | {
-    type: "comment.created";
-    thread: Thread;
-    comment: Comment;
-    actor: Identity;
-} | {
-    type: "thread.resolved" | "thread.reopened" | "thread.moved";
-    thread: Thread;
-    actor: Identity;
-} | {
-    type: "comment.deleted";
-    threadId: string;
-    commentId: string;
-    actor: Identity;
-} | {
-    type: "thread.deleted";
-    threadId: string;
-    actor: Identity;
-};
+export type { CommentsActions, Connector, ConnectorContext, ConnectorRequestContext, ConnectorStorage, } from "./connector";
+export type { CommentsEvent } from "./events";
+export { CommentsError, newId } from "./service";
+export type { AssetStore, CommentsStore, StoredScreenshot, StoredThread, ThreadChanges, ThreadLink, } from "./store";
 export interface CommentsOptions<Env extends object> {
     /** Tried in order; the first plugin that recognises the request wins. */
     auth: AuthPlugin<Env>[];
@@ -46,26 +29,22 @@ export interface CommentsOptions<Env extends object> {
     widgetScript?: string;
     /** Largest screenshot accepted, in bytes. Default 5 MB. */
     maxScreenshotBytes?: number;
+    /** Query parameter of thread links, as the widget's `linkParam`. Default "comment". */
+    linkParam?: string;
+    /** Integrations: Linear, MCP, or your own. See `Connector`. */
+    connectors?: Connector<Env>[];
     /** Called after every change, for integrations. Errors are logged, never returned. */
     onEvent?: (event: CommentsEvent, env: Env) => void | Promise<void>;
 }
 interface ExecutionContextLike {
     waitUntil(promise: Promise<unknown>): void;
 }
-type Vars = {
-    who: Identity;
-    site: string;
-    store: CommentsStore;
-    assets: AssetStore | null;
-};
-export declare function newId(): string;
 export declare function createComments<Env extends object = object>(options: CommentsOptions<Env>): {
-    app: import("hono/hono-base").HonoBase<{
+    app: Hono<{
         Bindings: Env;
-        Variables: Vars;
-    }, import("hono/types").BlankSchema, string, string>;
-    /** Answers requests under basePath; anything else gets a 404. */
+    }, import("hono/types").BlankSchema, "/">;
+    /** Answers requests under basePath (and connectors' root paths); anything else gets a 404. */
     fetch(request: Request, env: Env, ctx?: ExecutionContextLike): Promise<Response>;
-    /** Whether a request belongs to the comments API, to route it from a larger worker. */
+    /** Whether a request belongs here, to route it from a larger worker. */
     matches(request: Request): boolean;
 };

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

@@ -0,0 +1,53 @@
+import type { Author, Comment, Identity, ScreenshotKind, Thread, ThreadStatus } from "../shared/types";
+import type { CommentsEvent } from "./events";
+import type { AssetStore, CommentsStore } from "./store";
+import * as validate from "./validate";
+/** A failure the caller should hear about as it is (404, 403, ...). */
+export declare class CommentsError extends Error {
+    readonly status: 400 | 403 | 404 | 413 | 415 | 501;
+    readonly code: string;
+    constructor(status: 400 | 403 | 404 | 413 | 415 | 501, code: string, message: string);
+}
+/** One request's view of the comments: its site, where things are kept, and where changes go. */
+export interface Scope {
+    site: string;
+    store: CommentsStore;
+    assets: AssetStore | null;
+    announce(event: CommentsEvent): void;
+    waitUntil(work: Promise<unknown>): void;
+}
+export declare function newId(): string;
+/**
+ * Now, as ISO 8601, never the same as or earlier than the last time handed
+ * out here: comments are ordered by time, and two written in the same
+ * millisecond must still come out in the order they were made.
+ */
+export declare function now(): string;
+export declare function authorOf(who: Identity): Author;
+/**
+ * The rules, whoever asks: the HTTP API and connectors both go through here,
+ * so a reply from Linear or an agent obeys what a reply from the widget does.
+ */
+export declare function createService(options: {
+    basePath: string;
+    maxScreenshotBytes: number;
+}): {
+    list: (scope: Scope, query?: {
+        page?: string;
+        status?: ThreadStatus;
+        limit?: number;
+    }) => Promise<Thread[]>;
+    get: (scope: Scope, id: string) => Promise<Thread | null>;
+    create: (scope: Scope, actor: Identity, input: ReturnType<typeof validate.createThread>, files?: Partial<Record<ScreenshotKind, File>>) => Promise<Thread>;
+    reply: (scope: Scope, actor: Identity, threadId: string, body: string) => Promise<{
+        thread: Thread;
+        comment: Comment;
+    }>;
+    update: (scope: Scope, actor: Identity, threadId: string, change: ReturnType<typeof validate.threadUpdate>) => Promise<Thread>;
+    deleteComment: (scope: Scope, actor: Identity, commentId: string) => Promise<{
+        deleted: "thread" | "comment";
+        threadId: string;
+    }>;
+    assetKey: (scope: Scope, path: string) => string | null;
+};
+export type Service = ReturnType<typeof createService>;

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

@@ -25,10 +25,36 @@ export interface CommentsStore {
     updateThread(site: string, id: string, changes: ThreadChanges): Promise<void>;
     getComment(site: string, id: string): Promise<Comment | null>;
     deleteComment(site: string, id: string): Promise<void>;
-    /** Deletes a thread and all its comments. */
+    /** Deletes a thread with all its comments and links. */
     deleteThread(site: string, id: string): Promise<void>;
     /** Remembers who has been here (for @mentions); optional. */
     saveUser?(who: Identity, seenAt: string): Promise<void>;
+    /** Records a link between a thread (or one of its comments) and something elsewhere; replaces one with the same connector and external id. */
+    saveLink?(site: string, link: ThreadLink): Promise<void>;
+    findLink?(site: string, connector: string, externalId: string): Promise<ThreadLink | null>;
+    /** Every link of these threads. */
+    listLinks?(site: string, threadIds: string[]): Promise<ThreadLink[]>;
+    /** A connector's own state (tokens, settings), by key. Null once it has expired. */
+    getValue?(key: string): Promise<string | null>;
+    /** `expiresAt`: ISO 8601, or null to keep it. */
+    setValue?(key: string, value: string, expiresAt: string | null): Promise<void>;
+    deleteValue?(key: string): Promise<void>;
+}
+/**
+ * A thread, or one comment in it, tied to something a connector keeps
+ * elsewhere: the Linear issue a thread became, the Linear comment a reply was
+ * mirrored to. Links with a URL and no comment show on the thread.
+ */
+export interface ThreadLink {
+    connector: string;
+    /** The other system's id, unique per connector. */
+    externalId: string;
+    threadId: string;
+    commentId: string | null;
+    url: string | null;
+    /** How to show it, e.g. "ENG-123". */
+    title: string | null;
+    createdAt: string;
 }
 /** A screenshot as stored: the asset key, not a URL. */
 export interface StoredScreenshot {
@@ -38,7 +64,7 @@ export interface StoredScreenshot {
     height: number;
 }
 /** A thread as a store keeps it. */
-export interface StoredThread extends Omit<Thread, "screenshots"> {
+export interface StoredThread extends Omit<Thread, "screenshots" | "links"> {
     site: string;
     screenshots: Partial<Record<ScreenshotKind, StoredScreenshot>>;
 }

package/dist/types/shared/types.d.ts

@@ -90,6 +90,15 @@ export interface Thread {
     resolvedBy: Author | null;
     /** Oldest first. The first comment opens the thread. */
     comments: Comment[];
+    /** Where connectors took it, e.g. the Linear issue it became. */
+    links: ThreadLinkSummary[];
+}
+export interface ThreadLinkSummary {
+    /** The connector that made it, e.g. "linear". */
+    connector: string;
+    url: string;
+    /** How to show it, e.g. "ENG-123". */
+    title: string | null;
 }
 export interface ApiError {
     error: {

package/dist/types/store/drizzle/mysql.d.ts

@@ -502,5 +502,199 @@ export declare const users: import("drizzle-orm/mysql-core").MySqlTableWithColum
     dialect: 'mysql';
     isAlias: false;
 }>;
+/** Threads and comments tied to what connectors keep elsewhere (a Linear issue, ...). */
+export declare const links: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
+    name: "wc_links";
+    schema: undefined;
+    columns: {
+        site: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        connector: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        externalId: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        threadId: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        commentId: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        url: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        title: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        createdAt: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_links";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: 'mysql';
+    isAlias: false;
+}>;
+/** Connectors' own state (OAuth clients and tokens, ...), by name. */
+export declare const values: import("drizzle-orm/mysql-core").MySqlTableWithColumns<{
+    name: "wc_values";
+    schema: undefined;
+    columns: {
+        name: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_values";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        value: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_values";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        expiresAt: import("drizzle-orm/mysql-core").MySqlColumn<{
+            name: string;
+            tableName: "wc_values";
+            dataType: "string";
+            data: string;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: 'mysql';
+    isAlias: false;
+}>;
 /** The same tables as SQL, each statement safe to run again (MySQL has no CREATE INDEX IF NOT EXISTS, so indexes are inline). */
 export declare const createTablesSql: string[];