web-comments 0.0.1 → 0.1.0

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

@@ -0,0 +1,506 @@
+export declare const threads: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "wc_threads";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        site: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        page: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        url: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        anchor: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        context: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        screenshots: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        authorId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        authorName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        authorAvatar: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        authorKind: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        resolvedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+        resolvedBy: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_threads";
+            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;
+        }, {}>;
+    };
+    dialect: 'sqlite';
+    isAlias: false;
+}>;
+export declare const comments: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "wc_comments";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        threadId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+        body: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+        authorId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+        authorName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+        authorAvatar: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+        authorKind: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_comments";
+            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;
+        }, {}>;
+    };
+    dialect: 'sqlite';
+    isAlias: false;
+}>;
+export declare const users: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "wc_users";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_users";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        name: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_users";
+            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;
+        }, {}>;
+        email: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_users";
+            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;
+        }, {}>;
+        avatarUrl: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_users";
+            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;
+        }, {}>;
+        kind: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_users";
+            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;
+        }, {}>;
+        lastSeenAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "wc_users";
+            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;
+        }, {}>;
+    };
+    dialect: 'sqlite';
+    isAlias: false;
+}>;
+/** The same tables as SQL, each statement safe to run again. */
+export declare const createTablesSql: string[];

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

@@ -0,0 +1,10 @@
+import type { AssetStore, CommentsStore } from "../server/store";
+/**
+ * Keeps everything in memory: for tests and trying things out, and the
+ * smallest example of a CommentsStore. Gone when the process ends.
+ */
+export declare function memoryStore(): CommentsStore;
+/** Keeps screenshots in memory, for tests. */
+export declare function memoryAssets(): AssetStore & {
+    size(): number;
+};

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

@@ -0,0 +1,20 @@
+import type { AssetStore } from "../server/store";
+/** The slice of a Workers R2 binding this uses. */
+export interface R2BucketLike {
+    put(key: string, value: ArrayBuffer, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+    }): Promise<unknown>;
+    get(key: string): Promise<{
+        body: ReadableStream;
+        httpMetadata?: {
+            contentType?: string;
+        };
+    } | null>;
+    delete(key: string): Promise<void>;
+}
+/** Screenshots in a Cloudflare R2 bucket, through its Workers binding: `assets: (env) => r2Assets(env.SCREENSHOTS)`. */
+export declare function r2Assets(bucket: R2BucketLike, options?: {
+    prefix?: string;
+}): AssetStore;

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

@@ -0,0 +1,21 @@
+import type { AssetStore } from "../server/store";
+export interface S3AssetsOptions {
+    /**
+     * The S3 API endpoint, without the bucket: "https://s3.us-east-1.amazonaws.com",
+     * "https://<account>.r2.cloudflarestorage.com", a MinIO URL, ...
+     */
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Default "auto", which R2 expects; AWS needs the bucket's region. */
+    region?: string;
+    /** Put every key under this prefix, e.g. "web-comments/". */
+    prefix?: string;
+}
+/**
+ * Screenshots in any S3-compatible bucket (AWS S3, R2's S3 API, MinIO, ...),
+ * signed with SigV4 over fetch, so it runs on Workers, Node and Bun alike.
+ * Path-style addressing: {endpoint}/{bucket}/{key}.
+ */
+export declare function s3Assets(options: S3AssetsOptions): AssetStore;

package/dist/types/widget/anchor.d.ts

@@ -0,0 +1,9 @@
+import type { Anchor } from "../shared/types";
+export declare function textOf(element: Element): string;
+/** The page element under a point, looking past the widget's own layer. */
+export declare function elementAt(x: number, y: number, host: Element): Element | null;
+/** Describes where a click landed so the comment can find its element again later. */
+export declare function createAnchor(element: Element, clientX: number, clientY: number): Anchor;
+/** Finds an anchor's element on the page as it is now, or null when it's gone. */
+export declare function resolveAnchor(anchor: Anchor): Element | null;
+export declare function selectorFor(element: Element): string;

package/dist/types/widget/api.d.ts

@@ -0,0 +1,43 @@
+import type { Anchor, Identity, Thread, ThreadContext, ThreadStatus } from "../shared/types";
+import type { Shots } from "./capture";
+export interface ApiOptions {
+    endpoint: string;
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    credentials: RequestCredentials;
+}
+/** The API answered that nobody is signed in (or the gate in front of it did). */
+export declare class SignedOut extends Error {
+    readonly loginUrl?: string | undefined;
+    constructor(loginUrl?: string | undefined);
+}
+/** Signed in, but not allowed to use comments here. */
+export declare class Forbidden extends Error {
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function createApi(options: ApiOptions): {
+    /** A path the API returned (a screenshot), as a URL the browser can load: it's relative to the API's host. */
+    resolve: (path: string) => string;
+    me: () => Promise<Identity>;
+    threads: (page: string) => Promise<Thread[]>;
+    thread: (threadId: string) => Promise<Thread>;
+    /** Opens a thread, sending its screenshots along in the same request when there are any. */
+    createThread: (input: {
+        page: string;
+        url: string;
+        anchor: Anchor;
+        context?: ThreadContext;
+        body: string;
+    }, shots?: Shots) => Promise<Thread>;
+    reply: (threadId: string, body: string) => Promise<Thread>;
+    /** Moves a thread's pin to a new spot on the page. Only its author may. */
+    moveThread: (threadId: string, anchor: Anchor) => Promise<Thread>;
+    setStatus: (threadId: string, status: ThreadStatus) => Promise<Thread>;
+    deleteComment: (commentId: string) => Promise<{
+        deleted: "comment" | "thread";
+        threadId: string;
+    }>;
+};
+export type Api = ReturnType<typeof createApi>;

package/dist/types/widget/app.d.ts

@@ -0,0 +1,29 @@
+import { type Api } from "./api";
+import { type Tracker } from "./tracker";
+export interface Settings {
+    page: () => string;
+    shortcut: string | false;
+    pollInterval: number;
+    linkParam: string;
+    /** "push" moves the page over to make room for the toolbar; "overlay" draws it on top. */
+    dock: "push" | "overlay";
+}
+/** What mountComments hands back, wired up once the app is running. */
+export interface Controls {
+    open?: (threadId: string) => void;
+    setPlacing?: (placing: boolean) => void;
+}
+interface RootProps {
+    api: Api;
+    host: HTMLElement;
+    tracker: Tracker;
+    settings: Settings;
+    controls: Controls;
+    colorScheme: "light" | "dark" | undefined;
+    zIndex: number;
+}
+/** Spectrum's Provider, with overlays (menus, tooltips, dialogs) kept inside the shadow root. */
+export declare function Root({ colorScheme, zIndex, ...props }: RootProps): import("react").JSX.Element;
+type AppProps = Omit<RootProps, "colorScheme" | "zIndex">;
+export declare function App({ api, host, tracker, settings, controls }: AppProps): import("react").JSX.Element | null;
+export {};

package/dist/types/widget/capture.d.ts

@@ -0,0 +1,33 @@
+import type { ScreenshotKind, ThreadContext } from "../shared/types";
+export interface Shot {
+    blob: Blob;
+    width: number;
+    height: number;
+}
+export type Shots = Partial<Record<ScreenshotKind, Shot>>;
+/** What the commenter is looking at: the element and the page around it. */
+export declare function contextOf(element: Element): ThreadContext;
+/**
+ * Two screenshots from one render of the viewport, drawn from the DOM and
+ * leaving the widget out: the viewport as it was, and the element in its
+ * surroundings with an outline round it. None comes back when the page can't
+ * be drawn (a render that times out); a comment never waits on them for long.
+ */
+export declare function capture(element: Element, host: Element): Promise<Shots>;
+/** The part of the viewport to show for an element: it, a margin, at least a minimum size, inside the viewport. */
+export declare function cropAround(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Waits for screenshots, but never longer than `ms`: a comment goes out without them rather than late. */
+export declare function within(shots: Promise<Shots>, ms: number): Promise<Shots>;

package/dist/types/widget/format.d.ts

@@ -0,0 +1,15 @@
+export declare function colorFor(id: string): string;
+/** An image for Spectrum's Avatar: the person's picture, or their initials on a color. */
+export declare function avatarSrc(person: {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+}): string;
+/** "Ada Lovelace" → "AL", "林黛玉" → "林" */
+export declare function initials(name: string): string;
+export declare function timeAgo(iso: string, now: number): string;
+/** Splits text into plain strings and links (with where each starts), for rendering without innerHTML. */
+export declare function linkify(text: string): Array<string | {
+    href: string;
+    start: number;
+}>;