web-comments 0.0.1 → 0.1.0

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/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/index.d.ts

@@ -0,0 +1,71 @@
+import type { Comment, Identity, Thread } from "../shared/types";
+import { type AuthPlugin } from "./auth";
+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 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;
+    /** 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<{
+        Bindings: Env;
+        Variables: Vars;
+    }, import("hono/types").BlankSchema, string, string>;
+    /** Answers requests under basePath; 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. */
+    matches(request: Request): boolean;
+};

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

@@ -0,0 +1,59 @@
+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 and all its comments. */
+    deleteThread(site: string, id: string): Promise<void>;
+    /** Remembers who has been here (for @mentions); optional. */
+    saveUser?(who: Identity, seenAt: string): Promise<void>;
+}
+/** 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"> {
+    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,108 @@
+/** 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[];
+}
+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;