web-comments 0.0.1 → 1.0.0

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

@@ -0,0 +1,50 @@
+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 { 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>[];
+    /** Where comments are kept, e.g. `(env) => d1Store(env.DB)`. Any CommentsStore works. */
+    store: (env: Env) => CommentsStore;
+    /** Where screenshots are kept, e.g. `(env) => r2Assets(env.SCREENSHOTS)`. Without it, threads keep none. */
+    assets?: (env: Env) => AssetStore;
+    /** Who may use comments once identified. Everyone identified, by default. */
+    authorize?: (who: Identity, request: Request, env: Env) => boolean | Promise<boolean>;
+    /** Where the API is mounted. Default "/__comments". */
+    basePath?: string;
+    /** Keeps several sites apart in one store. Default "default". */
+    site?: (request: Request, env: Env) => string;
+    /** Origins other than the API's own that may call it with credentials. */
+    allowedOrigins?: string[];
+    /** The widget bundle (dist/widget.global.js) to serve at `{basePath}/widget.js`. */
+    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;
+}
+export declare function createComments<Env extends object = object>(options: CommentsOptions<Env>): {
+    app: Hono<{
+        Bindings: Env;
+    }, 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 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

@@ -0,0 +1,85 @@
+import type { Comment, Identity, ScreenshotKind, Thread, ThreadStatus } from "../shared/types";
+/**
+ * Where comments are kept. The service owns the rules (who may do what, ids,
+ * timestamps, what deleting the first comment means); a store only saves and
+ * loads. Implement it over anything: the built-in ones are Drizzle (SQLite/D1,
+ * Postgres, MySQL) and an in-memory store.
+ *
+ * Every lookup is scoped to a site, so one store can serve several.
+ */
+export interface CommentsStore {
+    /** Gets storage ready (e.g. creates tables). Called once before first use; optional. */
+    setup?(): Promise<void>;
+    /**
+     * Threads with their comments (oldest first). With a page: that page's
+     * threads, oldest first. Without: the site's most recent, newest first.
+     */
+    listThreads(site: string, query: {
+        page?: string;
+        limit: number;
+    }): Promise<StoredThread[]>;
+    getThread(site: string, id: string): Promise<StoredThread | null>;
+    /** Saves a new thread together with the comment that opens it. */
+    insertThread(thread: StoredThread, first: Comment): Promise<void>;
+    insertComment(site: string, comment: Comment): Promise<void>;
+    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 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 {
+    key: string;
+    contentType: string;
+    width: number;
+    height: number;
+}
+/** A thread as a store keeps it. */
+export interface StoredThread extends Omit<Thread, "screenshots" | "links"> {
+    site: string;
+    screenshots: Partial<Record<ScreenshotKind, StoredScreenshot>>;
+}
+export type ThreadChanges = Partial<Pick<StoredThread, "status" | "anchor" | "screenshots" | "updatedAt" | "resolvedAt" | "resolvedBy">>;
+export type { ThreadStatus };
+/**
+ * Where screenshots are kept. Implement it over anything that can hold bytes
+ * under a key; the built-ins are R2, S3 (and S3-compatible) and in-memory.
+ * The API serves them to people it has identified, so the bucket can stay private.
+ */
+export interface AssetStore {
+    put(key: string, body: ArrayBuffer, contentType: string): Promise<void>;
+    get(key: string): Promise<{
+        body: ReadableStream | ArrayBuffer;
+        contentType: string;
+    } | null>;
+    delete?(key: string): Promise<void>;
+}

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

@@ -0,0 +1,20 @@
+import type { Anchor, CreateThreadInput, ScreenshotKind, ThreadContext, ThreadStatus } from "../shared/types";
+export declare class InvalidInput extends Error {
+}
+export declare function commentBody(value: unknown): string;
+export declare function reply(value: unknown): string;
+export declare function anchor(value: unknown): Anchor;
+export declare function context(value: unknown): ThreadContext;
+export declare const SCREENSHOT_KINDS: readonly ScreenshotKind[];
+/** A new thread: what's said and where, plus the size of each screenshot sent with it. */
+export declare function createThread(value: unknown): CreateThreadInput & {
+    screenshots: Partial<Record<ScreenshotKind, {
+        width: number;
+        height: number;
+    }>>;
+};
+/** A thread change: resolve or reopen it, move its pin, or both. */
+export declare function threadUpdate(value: unknown): {
+    status?: ThreadStatus;
+    anchor?: Anchor;
+};

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

@@ -0,0 +1,117 @@
+/** Who is making a request, as an auth plugin reports it. */
+export interface Identity {
+    /** Stable and prefixed by its source, e.g. "access:<sub>" or "token:<name>". */
+    id: string;
+    name: string;
+    email?: string;
+    avatarUrl?: string;
+    kind: "human" | "agent";
+}
+/** The author of a comment as it was when the comment was written. */
+export interface Author {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+    kind: "human" | "agent";
+}
+/** Where a comment sits on the page. */
+export interface Anchor {
+    /** CSS selector of the element the comment was dropped on. */
+    selector: string;
+    /** Start of the element's text when the comment was made, to find it again if the selector breaks. */
+    text?: string;
+    /** Lowercase tag name of the element. */
+    tag: string;
+    /** Point inside the element's box, as fractions of its width and height (0–1). */
+    x: number;
+    y: number;
+    /** Viewport width when the comment was made, for context. */
+    viewportWidth: number;
+}
+/** What the commenter was looking at, recorded with the first comment. */
+export interface ThreadContext {
+    element: {
+        /** The element's outerHTML, cut to a few kilobytes. */
+        html: string;
+        /** Its box in the viewport when the comment was made, in CSS pixels. */
+        rect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    page: {
+        title: string;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        scroll: {
+            x: number;
+            y: number;
+        };
+        devicePixelRatio: number;
+        userAgent: string;
+    };
+}
+/** Which screenshots a thread keeps: the element, and the viewport around it. */
+export type ScreenshotKind = "element" | "page";
+export interface Screenshot {
+    /** Where the API serves it (it checks who is asking first). */
+    url: string;
+    contentType: string;
+    width: number;
+    height: number;
+}
+export type ThreadStatus = "open" | "resolved";
+export interface Comment {
+    id: string;
+    threadId: string;
+    body: string;
+    author: Author;
+    createdAt: string;
+}
+export interface Thread {
+    id: string;
+    /** The page key the widget filed it under (by default the path). */
+    page: string;
+    /** Full address the comment was made on. */
+    url: string;
+    anchor: Anchor;
+    /** Null for threads made by clients that send none. */
+    context: ThreadContext | null;
+    screenshots: Partial<Record<ScreenshotKind, Screenshot>>;
+    status: ThreadStatus;
+    author: Author;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt: string | null;
+    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: {
+        code: string;
+        message: string;
+    };
+    /** Present on 401 when an auth plugin knows where to sign in. */
+    loginUrl?: string;
+}
+export interface CreateThreadInput {
+    page: string;
+    url: string;
+    anchor: Anchor;
+    context?: ThreadContext;
+    body: string;
+}

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

@@ -0,0 +1,9 @@
+import { drizzle } from "drizzle-orm/d1";
+import type { CommentsStore } from "../server/store";
+/**
+ * Comments in a Cloudflare D1 database, creating the tables on first use:
+ * `store: (env) => d1Store(env.DB)`.
+ */
+export declare function d1Store(binding: Parameters<typeof drizzle>[0], options?: {
+    createTables?: boolean;
+}): CommentsStore;

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

@@ -0,0 +1,22 @@
+import type { CommentsStore } from "../../server/store";
+export type Dialect = "sqlite" | "pg" | "mysql";
+export interface DrizzleStoreOptions {
+    /**
+     * A Drizzle database from any driver of the dialect: `drizzle(env.DB)` for
+     * D1, `drizzle(client)` for libSQL, PGlite, Neon, postgres.js,
+     * PlanetScale, mysql2, ...
+     */
+    db: unknown;
+    dialect: Dialect;
+    /**
+     * Create the tables on first use if they're missing. Default true; turn it
+     * off when you migrate them yourself (the schemas are exported from
+     * web-comments/store/drizzle/{sqlite,pg,mysql}).
+     */
+    createTables?: boolean;
+}
+/**
+ * A CommentsStore over Drizzle, for SQLite (D1, libSQL/Turso, ...), Postgres
+ * (PlanetScale Postgres, Neon, Supabase, ...) and MySQL (PlanetScale, ...).
+ */
+export declare function drizzleStore(options: DrizzleStoreOptions): CommentsStore;