@commentbox/server-worker 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solutions Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @commentbox/server-worker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[CommentBox](https://commentbox.dev) server for Cloudflare Workers + D1. Usually scaffolded for you:
+
+```bash
+npx @commentbox/cli init --origin https://your-site.com --provision
+```
+
+Manual use: `export { default } from '@commentbox/server-worker'` as your Worker entry, with a D1 binding `DB`,
+the migration in `migrations/` and the `[[rules]]` Text rule from `wrangler.toml`. MIT licensed.

package/migrations/0001_init.sql

@@ -0,0 +1,54 @@
+-- CommentBox schema (SQLite / Cloudflare D1). Applied by both servers on start or via wrangler d1 migrations apply.
+CREATE TABLE IF NOT EXISTS comments (
+  id TEXT PRIMARY KEY,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'new',
+  type TEXT NOT NULL,
+  text TEXT NOT NULL,
+  name TEXT NOT NULL DEFAULT '',
+  page_url TEXT NOT NULL,
+  pathname TEXT NOT NULL,
+  selector TEXT,
+  tag_name TEXT,
+  element_text TEXT,
+  rect TEXT,
+  scroll_y REAL NOT NULL DEFAULT 0,
+  viewport_width INTEGER NOT NULL DEFAULT 0,
+  viewport_height INTEGER NOT NULL DEFAULT 0,
+  device_pixel_ratio REAL NOT NULL DEFAULT 1,
+  user_agent TEXT NOT NULL DEFAULT '',
+  screenshot_id TEXT,
+  meta TEXT,
+  note TEXT
+);
+CREATE INDEX IF NOT EXISTS comments_created_at ON comments (created_at);
+CREATE INDEX IF NOT EXISTS comments_status ON comments (status);
+
+CREATE TABLE IF NOT EXISTS screenshots (
+  id TEXT PRIMARY KEY,
+  mime TEXT NOT NULL,
+  data TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS deliveries (
+  id TEXT PRIMARY KEY,
+  comment_id TEXT,
+  event TEXT NOT NULL,
+  url TEXT NOT NULL,
+  body TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at INTEGER NOT NULL,
+  last_status INTEGER,
+  last_error TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS deliveries_due ON deliveries (status, next_attempt_at);
+
+CREATE TABLE IF NOT EXISTS settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);

package/migrations/0002_sessions.sql

@@ -0,0 +1,15 @@
+-- 0002: session links (CommentBox mode "session"). Only the SHA-256 of a token is stored.
+CREATE TABLE IF NOT EXISTS review_sessions (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL,
+  expires_at INTEGER NOT NULL,
+  closed_at INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS session_comments (
+  comment_id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS session_comments_session ON session_comments (session_id);

package/migrations/0003_rounds.sql

@@ -0,0 +1,28 @@
+-- CommentBox 0.2: comment rounds (opt-in). Adds the rounds table and two columns on comments.
+-- Servers apply this by themselves on start (the ALTERs only when the columns are missing).
+ALTER TABLE comments ADD COLUMN round_id TEXT;
+ALTER TABLE comments ADD COLUMN screenshot_highlighted INTEGER NOT NULL DEFAULT 0;
+CREATE INDEX IF NOT EXISTS comments_round ON comments (round_id);
+CREATE TABLE IF NOT EXISTS rounds (
+  id TEXT PRIMARY KEY,
+  project TEXT NOT NULL,
+  page_url TEXT NOT NULL,
+  session TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'open',
+  comment_count INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  last_comment_at INTEGER NOT NULL,
+  closed_at TEXT,
+  close_reason TEXT
+);
+CREATE INDEX IF NOT EXISTS rounds_open ON rounds (status, project, page_url, session);
+CREATE INDEX IF NOT EXISTS rounds_idle ON rounds (status, last_comment_at);
+CREATE TABLE IF NOT EXISTS screenshot_variants (
+  screenshot_id TEXT NOT NULL,
+  variant TEXT NOT NULL,
+  mime TEXT NOT NULL,
+  data TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (screenshot_id, variant)
+);

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@commentbox/server-worker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "CommentBox server for Cloudflare Workers + D1.",
+  "keywords": [
+    "commentbox",
+    "cloudflare-workers",
+    "d1",
+    "feedback",
+    "webhook"
+  ],
+  "license": "MIT",
+  "author": "Solutions Lab (https://solutionslab.net)",
+  "homepage": "https://commentbox.dev",
+  "bugs": {
+    "url": "https://github.com/loek-solutionslab/commentbox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/loek-solutionslab/commentbox.git",
+    "directory": "packages/server-worker"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./worker": "./src/worker.ts",
+    "./migrations/0001_init.sql": "./migrations/0001_init.sql",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "migrations",
+    "src",
+    "wrangler.toml"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@commentbox/core": "0.2.1",
+    "@commentbox/widget": "0.2.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241011.0",
+    "@types/better-sqlite3": "^7.6.11",
+    "better-sqlite3": "^11.5.0",
+    "wrangler": "^3.80.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "wrangler dev",
+    "db:migrate:local": "wrangler d1 migrations apply commentbox --local"
+  }
 }

package/src/d1.ts

@@ -0,0 +1,18 @@
+import type { SqlDriver } from '@commentbox/core'
+
+/** Adapts a Cloudflare D1 binding to the core SqlDriver. */
+export function d1Driver(db: D1Database): SqlDriver {
+  return {
+    async run(sql, params = []) {
+      const res = await db.prepare(sql).bind(...params).run()
+      return { changes: res.meta.changes ?? 0 }
+    },
+    async all(sql, params = []) {
+      const res = await db.prepare(sql).bind(...params).all<Record<string, unknown>>()
+      return res.results
+    },
+    async exec(statements) {
+      await db.batch(statements.map((s) => db.prepare(s)))
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// The widget bundle is inlined (wrangler "Text" rule), so GET /widget.js works with no CDN.
+import widgetJs from '@commentbox/widget/dist/commentbox.global.js'
+
+import { createWorker } from './worker.js'
+
+export default createWorker(widgetJs)

package/src/widget.d.ts

@@ -0,0 +1,4 @@
+declare module '*.global.js' {
+  const source: string
+  export default source
+}

package/src/worker.ts

@@ -0,0 +1,72 @@
+import { applyRetention, configFromEnv, configWarnings, createHandler, createSqlStore, processDeliveries, processRounds, resolveConfig } from '@commentbox/core'
+
+import { d1Driver } from './d1.js'
+
+export type Env = {
+  DB: D1Database
+  ALLOWED_ORIGINS?: string
+  PUBLIC_URL?: string
+  PROJECT_NAME?: string
+  WIDGET_ENABLED?: string
+  RATE_LIMIT_PER_HOUR?: string
+  WEBHOOK_URL?: string
+  WEBHOOK_MAX_ATTEMPTS?: string
+  WEBHOOK_INTEGRATION?: string
+  WEBHOOK_ALLOW_INSECURE?: string
+  // Opt-in install count (off by default; DO_NOT_TRACK=1 always disables). See docs/telemetry.md.
+  COMMENTBOX_TELEMETRY?: string
+  COMMENTBOX_TELEMETRY_URL?: string
+  DO_NOT_TRACK?: string
+  // Comment rounds and the Donna integration (opt-in). See integrations/donna/README.md.
+  COMMENTBOX_ROUNDS?: string
+  COMMENTBOX_DONNA?: string
+  COMMENTBOX_ROUND_IDLE_MINUTES?: string
+  COMMENTBOX_ROUND_MAX_COMMENTS?: string
+  // Limits for public demos.
+  MAX_COMMENT_LENGTH?: string
+  MAX_SCREENSHOT_BYTES?: string
+  RETENTION_HOURS?: string
+  // Secrets (wrangler secret put …):
+  ADMIN_TOKEN?: string
+  WEBHOOK_SECRET?: string
+  WEBHOOK_BEARER_TOKEN?: string
+  // Extra header on every delivery, `Header-Name: value` (e.g. `X-Api-Key: abc`). A secret: wrangler secret put.
+  WEBHOOK_AUTH_HEADER?: string
+}
+
+/** Worker entry, without the widget import so tests can run it against a fake D1. */
+export function createWorker(widgetJs?: string) {
+  // One handler per isolate (env is stable per isolate): keeps the schema check and rate limiter warm.
+  const cache = new WeakMap<Env, { handle: ReturnType<typeof createHandler>; store: ReturnType<typeof createSqlStore>; ready: Promise<void> | null }>()
+  const get = (env: Env) => {
+    let hit = cache.get(env)
+    if (!hit) {
+      const store = createSqlStore(d1Driver(env.DB))
+      // Once per isolate, never with secret values.
+      for (const w of configWarnings(env)) console.warn(w)
+      hit = { store, handle: createHandler({ store, config: configFromEnv(env), widgetJs }), ready: null }
+      cache.set(env, hit)
+    }
+    return hit
+  }
+
+  return {
+    async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+      return get(env).handle(req, { waitUntil: (p) => ctx.waitUntil(p) })
+    },
+    /** Cron trigger (every minute): closes idle comment rounds and sends webhook retries that are due. */
+    async scheduled(_event: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+      const hit = get(env)
+      hit.ready ??= hit.store.init()
+      await hit.ready
+      const config = configFromEnv(env)
+      // Idle rounds first (they queue round.closed), then every due delivery, retries included.
+      ctx.waitUntil(
+        processRounds(hit.store, config)
+          .then(() => resolveConfig(hit.store, config))
+          .then((cfg) => processDeliveries(hit.store, cfg))
+          .then(() => applyRetention(hit.store, config)),
+      )
+    },
+  } satisfies ExportedHandler<Env>
+}

package/wrangler.toml

@@ -0,0 +1,50 @@
+# CommentBox on Cloudflare Workers + D1.
+# 1. npx wrangler d1 create commentbox           -> paste the database_id below
+# 2. npx wrangler d1 migrations apply commentbox --remote
+# 3. npx wrangler secret put ADMIN_TOKEN / WEBHOOK_SECRET   (never commit secrets)
+#    Optional secrets: WEBHOOK_BEARER_TOKEN, and WEBHOOK_AUTH_HEADER for an extra header on every delivery,
+#    format "Header-Name: value", e.g. "X-Api-Key: abc" or "Authorization: Bearer abc123" (wins over the bearer token).
+# 4. npx wrangler deploy
+# `npx @commentbox/cli init --origin https://your-site.com --provision` runs these steps for you.
+name = "commentbox"
+main = "src/index.ts"
+compatibility_date = "2024-10-01"
+# nodejs_compat: Buffer for the server-side screenshot highlighter (jpeg-js) used by comment rounds.
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+# Comma-separated origins allowed to post comments (no trailing slash).
+ALLOWED_ORIGINS = "http://localhost:3000"
+PROJECT_NAME = "my-site"
+# Hard switch; the soft switch is PUT /v1/settings {"enabled": false} (or `npx @commentbox/cli toggle off`).
+WIDGET_ENABLED = "true"
+RATE_LIMIT_PER_HOUR = "20"
+# Where every new comment is POSTed (your Grok Bot or any agent endpoint). Empty = no webhook.
+WEBHOOK_URL = ""
+WEBHOOK_MAX_ATTEMPTS = "6"
+# "grok-bot" or "webhook": what WEBHOOK_URL points at.
+WEBHOOK_INTEGRATION = "webhook"
+# Opt-in anonymous install count, OFF by default. "1" sends one ping per verified webhook registration
+# (random install id, version, integration, event kind; nothing else). DO_NOT_TRACK = "1" always wins. See docs/telemetry.md.
+COMMENTBOX_TELEMETRY = "0"
+# Comment rounds + Donna review cards (opt-in, off by default). DONNA=1 implies ROUNDS=1 and shows "Send round".
+COMMENTBOX_ROUNDS = "0"
+COMMENTBOX_DONNA = "0"
+COMMENTBOX_ROUND_IDLE_MINUTES = "15"
+# Set when the Worker runs behind a custom domain, e.g. "https://comments.example.com".
+PUBLIC_URL = ""
+
+[[d1_databases]]
+binding = "DB"
+database_name = "commentbox"
+database_id = "00000000-0000-0000-0000-000000000000"
+migrations_dir = "migrations"
+
+# Retries for failed webhook deliveries.
+[triggers]
+crons = ["* * * * *"]
+
+[[rules]]
+type = "Text"
+globs = ["**/*.global.js"]
+fallthrough = true