@blamejs/blamejs-shop 0.0.44

package/lib/externaldb-d1.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * @module shop.externaldbD1
+ * @title  External-DB adapter — Cloudflare D1
+ *
+ * @intro
+ *   Adapter that lets `b.externalDb` target a Cloudflare D1 database
+ *   from a Node container. D1 is HTTP-accessed (no TCP), so the
+ *   adapter wraps `fetch()` rather than a binary driver — which means
+ *   no npm runtime dependency and no vendored client bundle. Two
+ *   operating modes:
+ *
+ *   1. **service-binding** (recommended for Cloudflare Containers):
+ *      the container reaches a sibling Worker over a service binding;
+ *      the Worker holds the D1 binding and executes the query. The
+ *      adapter calls `<bridgeUrl><bridgePath>` with a shared-secret
+ *      header. Latency is sub-millisecond plus D1 itself, and no D1
+ *      API token ever lives in the container.
+ *
+ *   2. **rest-api** (for non-Cloudflare deployments that still want
+ *      to read from D1 — e.g. a development environment): hits
+ *      `https://api.cloudflare.com/client/v4/accounts/<acc>/d1/
+ *      database/<db>/query` with an API token in the Authorization
+ *      header.
+ *
+ *   The factory returns the four-field shape `b.externalDb.init`
+ *   expects: `{ dialect: "sqlite", connect, query, close }`. Plug it
+ *   in as a backend:
+ *
+ *       var b = require("./lib/vendor/blamejs");
+ *       var d1 = require("./lib/externaldb-d1").create({
+ *         mode:         "service-binding",
+ *         bridgeUrl:    process.env.D1_BRIDGE_URL,    // e.g. http://shop-worker
+ *         bridgePath:   "/_/db/query",
+ *         bridgeSecret: process.env.D1_BRIDGE_SECRET,
+ *       });
+ *       b.externalDb.init({ backends: { main: d1 } });
+ *
+ *   D1 SQL dialect is SQLite — `?1, ?2, ...` parameter placeholders,
+ *   no JSONB, no advisory locks. The adapter normalizes both modes'
+ *   result shapes into `{ rows, rowCount, lastRowId? }` so downstream
+ *   primitives don't see the wire-shape difference.
+ */
+
+var _bShop;
+function _bCrypto() {
+  if (!_bShop) _bShop = require("./index");
+  return _bShop.framework.crypto;
+}
+
+var DEFAULT_TIMEOUT_MS = 10000;
+var DEFAULT_BRIDGE_PATH = "/_/db/query";
+var MAX_RETRY = 2;
+var RETRY_BACKOFF_MS = 200;
+
+// SQLite parameter placeholders are `?1, ?2, ...`. Any `?` not
+// followed by a digit is a SQLite "auto-numbered" placeholder which
+// the D1 driver also accepts; we leave SQL untouched and pass the
+// params array through. Operators write SQL with explicit indices in
+// new code so re-ordering params in a statement update doesn't
+// silently re-map.
+function _validateOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("externaldbD1.create({ opts }) — opts must be an object");
+  }
+  var mode = opts.mode || "service-binding";
+  if (mode !== "service-binding" && mode !== "rest-api") {
+    throw new TypeError("externaldbD1.create — mode must be 'service-binding' or 'rest-api', got " + JSON.stringify(opts.mode));
+  }
+  if (mode === "service-binding") {
+    if (typeof opts.bridgeUrl !== "string" || !opts.bridgeUrl.length) {
+      throw new TypeError("externaldbD1.create — service-binding mode requires bridgeUrl");
+    }
+    if (typeof opts.bridgeSecret !== "string" || !opts.bridgeSecret.length) {
+      throw new TypeError("externaldbD1.create — service-binding mode requires bridgeSecret");
+    }
+  } else {
+    if (typeof opts.accountId !== "string" || !opts.accountId.length) {
+      throw new TypeError("externaldbD1.create — rest-api mode requires accountId");
+    }
+    if (typeof opts.databaseId !== "string" || !opts.databaseId.length) {
+      throw new TypeError("externaldbD1.create — rest-api mode requires databaseId");
+    }
+    if (typeof opts.apiToken !== "string" || !opts.apiToken.length) {
+      throw new TypeError("externaldbD1.create — rest-api mode requires apiToken");
+    }
+  }
+  if (opts.timeoutMs !== undefined && (typeof opts.timeoutMs !== "number" || !isFinite(opts.timeoutMs) || opts.timeoutMs <= 0)) {
+    throw new TypeError("externaldbD1.create — timeoutMs must be a positive number");
+  }
+  if (opts.fetch !== undefined && typeof opts.fetch !== "function") {
+    throw new TypeError("externaldbD1.create — fetch override must be a function");
+  }
+}
+
+function _isWriteSql(sql) {
+  // Classification used only to pick D1's `run` vs `all` execution
+  // mode in the Worker bridge. Strips leading whitespace + line
+  // comments + block comments before peeking at the verb.
+  var s = String(sql || "").replace(/^\s+|^\/\*[\s\S]*?\*\/|^--[^\n]*\n/g, "").trimStart();
+  var verb = (s.match(/^[A-Za-z]+/) || [""])[0].toUpperCase();
+  return verb === "INSERT" || verb === "UPDATE" || verb === "DELETE" || verb === "CREATE" || verb === "DROP" || verb === "ALTER" || verb === "REPLACE";
+}
+
+function _withTimeout(promise, ms, label) {
+  var controller = new AbortController();
+  var timer = setTimeout(function () { controller.abort(); }, ms);
+  return {
+    signal: controller.signal,
+    finish: function () {
+      clearTimeout(timer);
+      return promise;
+    },
+    timeoutErr: function () {
+      var e = new Error("externaldbD1: " + label + " timed out after " + ms + "ms");
+      e.code = "D1_TIMEOUT";
+      return e;
+    },
+  };
+}
+
+async function _retryingFetch(fetchImpl, url, init, attempts, label) {
+  var lastErr;
+  for (var i = 0; i <= attempts; i += 1) {
+    try {
+      var res = await fetchImpl(url, init);
+      // Retry only on 5xx / 429; 4xx is a permanent client error.
+      if (res.status >= 500 || res.status === 429) {
+        lastErr = _httpErr(res.status, label);
+        if (i < attempts) {
+          await _backoff(i);
+          continue;
+        }
+      }
+      return res;
+    } catch (e) {
+      lastErr = e;
+      if (i < attempts && _isTransient(e)) {
+        await _backoff(i);
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw lastErr;
+}
+
+function _isTransient(err) {
+  if (!err) return false;
+  var c = err.code || (err.cause && err.cause.code);
+  return c === "ECONNRESET" || c === "ETIMEDOUT" || c === "ENOTFOUND" || c === "EAI_AGAIN" || c === "UND_ERR_SOCKET";
+}
+
+function _backoff(attempt) {
+  // Jittered exponential — 200ms, 400ms, ... with ±25% jitter so
+  // retries from many container replicas don't synchronize.
+  var base = RETRY_BACKOFF_MS * Math.pow(2, attempt);
+  var jitter = base * (0.75 + (_bCrypto().randomInt(0, 50) / 100));
+  return new Promise(function (r) { setTimeout(r, jitter); });
+}
+
+function _httpErr(status, label) {
+  var e = new Error("externaldbD1: " + label + " failed with HTTP " + status);
+  e.code = "D1_HTTP_" + status;
+  e.status = status;
+  return e;
+}
+
+// ---- mode: service-binding -----------------------------------------------
+
+function _serviceBindingQuery(opts) {
+  var url = opts.bridgeUrl.replace(/\/+$/, "") + (opts.bridgePath || DEFAULT_BRIDGE_PATH);
+  var secret = opts.bridgeSecret;
+  var fetchImpl = opts.fetch || globalThis.fetch;
+  var timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("externaldbD1: global fetch unavailable — pass opts.fetch explicitly");
+  }
+  return async function (_client, sql, params) {
+    var mode = _isWriteSql(sql) ? "run" : "all";
+    var body = JSON.stringify({ sql: sql, params: params || [], mode: mode });
+    var tcap = _withTimeout(null, timeoutMs, "service-binding query");
+    var res;
+    try {
+      res = await _retryingFetch(fetchImpl, url, {
+        method: "POST",
+        headers: {
+          "content-type":        "application/json",
+          "x-d1-bridge-secret":  secret,
+          "accept":               "application/json",
+        },
+        body:   body,
+        signal: tcap.signal,
+      }, MAX_RETRY, "service-binding query");
+    } catch (e) {
+      if (e && e.name === "AbortError") throw tcap.timeoutErr();
+      throw e;
+    }
+    if (!res.ok) throw _httpErr(res.status, "service-binding query");
+    var json = await res.json();
+    if (!json || json.ok === false) {
+      var err = new Error("externaldbD1: query failed — " + (json && json.error || "unknown") + (json && json.message ? ": " + json.message : ""));
+      err.code = (json && json.error) || "D1_QUERY_FAILED";
+      throw err;
+    }
+    return {
+      rows:      json.rows || [],
+      rowCount:  typeof json.rowCount === "number" ? json.rowCount : (json.rows ? json.rows.length : 0),
+      lastRowId: json.lastRowId != null ? json.lastRowId : null,
+    };
+  };
+}
+
+// ---- mode: rest-api ------------------------------------------------------
+
+function _restApiQuery(opts) {
+  var url = "https://api.cloudflare.com/client/v4/accounts/" + encodeURIComponent(opts.accountId) +
+            "/d1/database/" + encodeURIComponent(opts.databaseId) + "/query";
+  var token = opts.apiToken;
+  var fetchImpl = opts.fetch || globalThis.fetch;
+  var timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("externaldbD1: global fetch unavailable — pass opts.fetch explicitly");
+  }
+  return async function (_client, sql, params) {
+    var body = JSON.stringify({ sql: sql, params: params || [] });
+    var tcap = _withTimeout(null, timeoutMs, "rest-api query");
+    var res;
+    try {
+      res = await _retryingFetch(fetchImpl, url, {
+        method: "POST",
+        headers: {
+          "authorization": "Bearer " + token,
+          "content-type":  "application/json",
+          "accept":         "application/json",
+        },
+        body:   body,
+        signal: tcap.signal,
+      }, MAX_RETRY, "rest-api query");
+    } catch (e) {
+      if (e && e.name === "AbortError") throw tcap.timeoutErr();
+      throw e;
+    }
+    if (!res.ok) throw _httpErr(res.status, "rest-api query");
+    var json = await res.json();
+    if (!json || json.success !== true) {
+      var firstErr = json && Array.isArray(json.errors) && json.errors[0];
+      var err = new Error("externaldbD1: rest-api query failed — " + (firstErr && firstErr.message || "unknown"));
+      err.code = firstErr && firstErr.code ? "D1_REST_" + firstErr.code : "D1_REST_QUERY_FAILED";
+      throw err;
+    }
+    // The /query endpoint returns `result: [{ results, meta, success }]`.
+    var first = json.result && json.result[0];
+    var rows = (first && first.results) || [];
+    return {
+      rows:      rows,
+      rowCount:  typeof (first && first.meta && first.meta.changes) === "number" ? first.meta.changes : rows.length,
+      lastRowId: (first && first.meta && first.meta.last_row_id) || null,
+    };
+  };
+}
+
+// ---- factory -------------------------------------------------------------
+
+function create(opts) {
+  _validateOpts(opts);
+  var queryFn = opts.mode === "rest-api" ? _restApiQuery(opts) : _serviceBindingQuery(opts);
+  var sentinelClient = Object.freeze({ kind: "d1-adapter-sentinel" });
+  return {
+    dialect: "sqlite",
+    connect: async function () {
+      // D1 has no per-connection state; the adapter returns a frozen
+      // sentinel so the pool layer above can still track checkouts.
+      return sentinelClient;
+    },
+    query: queryFn,
+    close: async function (_client) {
+      // Nothing to close — every query is an independent HTTP call.
+    },
+  };
+}
+
+module.exports = { create: create };

package/lib/index.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * blamejs.shop entry point.
+ *
+ * Re-exports the vendored blamejs surface plus the local primitives
+ * composed on top of it. Extend by adding new modules under `lib/`
+ * that compose blamejs primitives — never by patching
+ * `lib/vendor/blamejs/` in place.
+ *
+ *   var bShop = require("blamejs-shop");
+ *   var b     = bShop.framework;        // the vendored blamejs
+ *   var d1    = bShop.externaldbD1;     // Cloudflare D1 adapter
+ *
+ * Future primitives surface as additional fields on the exports
+ * object (e.g. `bShop.catalog`, `bShop.cart`, `bShop.checkout`, etc.).
+ */
+
+var framework;
+try {
+  framework = require("./vendor/blamejs");
+} catch (e) {
+  // The vendored tree is absent on a fresh clone. Direct the
+  // operator at the refresh script rather than crashing opaquely.
+  if (e && e.code === "MODULE_NOT_FOUND") {
+    throw new Error(
+      "blamejs is not vendored — run `bash scripts/vendor-update.sh blamejs latest` " +
+      "to populate lib/vendor/blamejs/ before requiring this module"
+    );
+  }
+  throw e;
+}
+
+module.exports = {
+  framework:    framework,
+  externaldbD1: require("./externaldb-d1"),
+  r2Bridge:     require("./r2-bridge"),
+  catalog:      require("./catalog"),
+  catalogImport: require("./catalog-import"),
+  cart:         require("./cart"),
+  pricing:      require("./pricing"),
+  tax:          require("./tax"),
+  shipping:     require("./shipping"),
+  payment:      require("./payment"),
+  order:         require("./order"),
+  subscriptions: require("./subscriptions"),
+  customers:     require("./customers"),
+  checkout:      require("./checkout"),
+  email:        require("./email"),
+  newsletter:   require("./newsletter"),
+  storefront:   require("./storefront"),
+  theme:        require("./theme"),
+  admin:        require("./admin"),
+  config:       require("./config"),
+  webhooks:        require("./webhooks"),
+  analytics:       require("./analytics"),
+  inventoryAlerts: require("./inventory-alerts"),
+};

package/lib/inventory-alerts.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * @module shop.inventoryAlerts
+ * @title  Inventory low-stock alerts
+ *
+ * @intro
+ *   When a SKU's available stock (`stock_on_hand - stock_held`) drops
+ *   below its configured threshold, the alert primitive writes an
+ *   `inventory_alerts` row and fans out the signal. The fan-out has
+ *   two channels:
+ *
+ *     1. `logger.warn` — always called. The default logger is
+ *        `b.log` with a bound `component: "inventory-alerts"` field
+ *        so the line lands in the same observability pipeline as the
+ *        rest of the application.
+ *     2. `webhooks.send("inventory.low_stock", payload)` — called
+ *        when an outbound-webhooks dep is wired into the factory.
+ *        Optional: when absent the log line is the only signal.
+ *
+ *   The primitive is paired with `catalog.inventory.setThreshold(sku,
+ *   threshold)` (which writes the per-SKU threshold) and
+ *   `catalog.inventory.checkLowStock(sku)` (a pure SELECT that
+ *   returns `{ alert, available, threshold }`). Callers that have
+ *   just mutated stock (the InventoryLock DO's decrement path, the
+ *   `inventory.release` primitive, the admin restock route) invoke
+ *   `check(sku)` to decide whether to fire.
+ *
+ *   The fire path is idempotent at the row level — every call writes
+ *   a fresh `inventory_alerts` row keyed by a v7 UUID. Operators that
+ *   want dedupe-by-day or rate-limit-per-SKU compose that on top via
+ *   the outbound-webhooks dispatcher's own retry / dedupe policies.
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+var SKU_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function _validateSku(s) {
+  if (typeof s !== "string" || !SKU_RE.test(s)) {
+    throw new TypeError("inventory-alerts: sku must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/ (alnum + . _ -, ≤ 128 chars)");
+  }
+}
+
+function _validateNonNegInt(n, label) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TypeError("inventory-alerts: " + label + " must be a non-negative integer");
+  }
+}
+
+function _validateLimit(n) {
+  if (!Number.isInteger(n) || n <= 0 || n > 1000) {
+    throw new TypeError("inventory-alerts: limit must be an integer in 1..1000");
+  }
+}
+
+function _validateOffset(n) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TypeError("inventory-alerts: offset must be a non-negative integer");
+  }
+}
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+  // Optional outbound-webhooks dep. When wired, `fire` calls
+  // `webhooks.send(event, payload)` after the alert row is written.
+  // The webhooks primitive lands in a sibling stacked release; until
+  // it merges, this dep stays optional and the log line is the only
+  // signal.
+  var webhooks = opts.webhooks || null;
+  if (webhooks && typeof webhooks.send !== "function") {
+    throw new TypeError("inventory-alerts.create: opts.webhooks must expose a send(event, payload) method");
+  }
+  // Logger — defaults to `b.log` bound with a component tag so the
+  // emitted lines are filterable in the aggregator. Tests inject a
+  // collector logger; production wires the framework logger at boot.
+  var logger;
+  if (opts.logger) {
+    if (typeof opts.logger.warn !== "function") {
+      throw new TypeError("inventory-alerts.create: opts.logger must expose a warn(msg, extras) method");
+    }
+    logger = opts.logger;
+  } else {
+    var bLog = _b().log;
+    logger = bLog.bind
+      ? bLog.bind({ component: "inventory-alerts" })
+      : bLog;
+  }
+
+  function _now() { return Date.now(); }
+
+  return {
+    // Pure pass-through to `catalog.inventory.checkLowStock(sku)` —
+    // but the alert primitive exposes its own `check` so a caller
+    // that only has the alert dep wired (e.g. the DO callback path
+    // that POSTs to the container) doesn't have to also wire catalog.
+    check: async function (sku) {
+      _validateSku(sku);
+      var r = await query(
+        "SELECT stock_on_hand, stock_held, low_stock_threshold FROM inventory WHERE sku = ?1",
+        [sku],
+      );
+      var row = r.rows[0];
+      if (!row) return { alert: false, available: null, threshold: null };
+      if (row.low_stock_threshold == null) {
+        var availableNoThreshold = row.stock_on_hand - row.stock_held;
+        return { alert: false, available: availableNoThreshold, threshold: null };
+      }
+      var available = row.stock_on_hand - row.stock_held;
+      return {
+        alert:     available < row.low_stock_threshold,
+        available: available,
+        threshold: row.low_stock_threshold,
+      };
+    },
+
+    // Fire an alert: write the row, call the optional webhooks
+    // dispatcher, and emit a log line. Returns the new alert row.
+    fire: async function (sku, available, threshold) {
+      _validateSku(sku);
+      _validateNonNegInt(available, "available");
+      _validateNonNegInt(threshold, "threshold");
+      var id = _b().uuid.v7();
+      var ts = _now();
+      await query(
+        "INSERT INTO inventory_alerts (id, sku, available_at_alert, threshold, fired_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5)",
+        [id, sku, available, threshold, ts],
+      );
+      var payload = { sku: sku, available: available, threshold: threshold, fired_at: ts };
+      // Webhooks fan-out — drop-silent at this boundary because the
+      // alert row is already persisted; a downstream delivery
+      // failure must not roll back the alert record.
+      if (webhooks) {
+        try { await webhooks.send("inventory.low_stock", payload); }
+        catch (_e) { /* drop-silent — outbound delivery failure already routed via webhooks' own retry queue */ }
+      }
+      // Log line — always emitted, regardless of webhooks state.
+      try {
+        logger.warn("inventory.low_stock", {
+          sku:       sku,
+          available: available,
+          threshold: threshold,
+        });
+      } catch (_e) { /* drop-silent — observability sink must never fail the alert path */ }
+      return { id: id, sku: sku, available_at_alert: available, threshold: threshold, fired_at: ts };
+    },
+
+    // check + fire in one call. The common caller path: a stock
+    // mutation just happened, ask "should we alert?" and fire if so.
+    // Returns the alert row when fired, `null` when below-threshold
+    // was not the case, and `null` when the SKU has no threshold
+    // configured.
+    checkAndFire: async function (sku) {
+      var result = await this.check(sku);
+      if (!result.alert) return null;
+      return await this.fire(sku, result.available, result.threshold);
+    },
+
+    // Recent alerts, ordered by fired_at DESC. `limit` defaults to
+    // 100; `offset` supports admin-UI pagination. `sku` optionally
+    // narrows to a single SKU's history.
+    list: async function (listOpts) {
+      listOpts = listOpts || {};
+      var limit  = listOpts.limit == null ? 100 : listOpts.limit;
+      var offset = listOpts.offset == null ? 0   : listOpts.offset;
+      _validateLimit(limit);
+      _validateOffset(offset);
+      var sku = listOpts.sku;
+      if (sku !== undefined && sku !== null) {
+        _validateSku(sku);
+        var r1 = await query(
+          "SELECT id, sku, available_at_alert, threshold, fired_at FROM inventory_alerts " +
+          "WHERE sku = ?1 ORDER BY fired_at DESC LIMIT ?2 OFFSET ?3",
+          [sku, limit, offset],
+        );
+        return r1.rows;
+      }
+      var r2 = await query(
+        "SELECT id, sku, available_at_alert, threshold, fired_at FROM inventory_alerts " +
+        "ORDER BY fired_at DESC LIMIT ?1 OFFSET ?2",
+        [limit, offset],
+      );
+      return r2.rows;
+    },
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/lib/newsletter.js

@@ -0,0 +1,142 @@
+/**
+ * Newsletter signups — operator-collected email broadcast list.
+ *
+ * Composes:
+ *   - `b.guardEmail` — RFC-shape validation, length cap, control-
+ *     byte refusal. The primitive itself never tries to parse the
+ *     address; it delegates the entire shape check to the guard.
+ *   - `b.crypto.namespaceHash` — dedupe key. The hash is computed
+ *     from the namespace `"newsletter-email"` + the normalised
+ *     address (lowercased + trimmed) so two signups for the same
+ *     mailbox collapse to a single row regardless of casing
+ *     variation.
+ *   - `b.uuid.v7` — row id.
+ *
+ * Surface:
+ *   - `signup({ email, source })` — INSERT-OR-IGNORE; returns
+ *     `{ id, status: "new" | "dedup", email_normalized }`.
+ *   - `byEmailHash(hash)` — operator lookup.
+ *   - `count()` — total non-unsubscribed signups (for the live
+ *     newsletter-band stat the home page renders).
+ *
+ * Storage:
+ *   - `newsletter_signups` (migration `0010_newsletter_signups.sql`).
+ *
+ * @primitive newsletter
+ * @related   b.guardEmail, b.crypto.namespaceHash
+ */
+
+"use strict";
+
+var EMAIL_NAMESPACE = "newsletter-email";
+var MAX_SOURCE_LEN  = 64;
+var SOURCE_RE       = /^[a-z0-9][a-z0-9._-]{0,62}[a-z0-9]$/;
+
+// Lazy framework handle — matches the pattern used by the rest of
+// the shop primitives; avoids the `require` cycle that would arise
+// from importing `./index` at module-eval time.
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+function _normalizeEmail(s) {
+  if (typeof s !== "string") {
+    throw new TypeError("newsletter: email must be a string");
+  }
+  var trimmed = s.trim();
+  // Defer the shape check to `b.guardEmail`. The guard refuses
+  // control bytes, empty input, oversized input, and RFC-shape
+  // violations; we just hand it through with the trim already
+  // applied so the canonical form lands in storage.
+  var checked = _b().guardEmail(trimmed, { profile: "strict" });
+  return checked.toLowerCase();
+}
+
+function _normalizeSource(s) {
+  if (s == null || s === "") return "storefront-footer";
+  if (typeof s !== "string") {
+    throw new TypeError("newsletter: source must be a string");
+  }
+  var clean = s.toLowerCase().trim();
+  if (clean.length > MAX_SOURCE_LEN) {
+    throw new TypeError("newsletter: source must be <= " + MAX_SOURCE_LEN + " chars");
+  }
+  if (!SOURCE_RE.test(clean)) {
+    throw new TypeError("newsletter: source must match /[a-z0-9][a-z0-9._-]*[a-z0-9]/");
+  }
+  return clean;
+}
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+
+  return {
+    EMAIL_NAMESPACE: EMAIL_NAMESPACE,
+
+    signup: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("newsletter.signup: input object required");
+      }
+      var emailNormalized = _normalizeEmail(input.email);
+      var source          = _normalizeSource(input.source);
+      var emailHash       = _b().crypto.namespaceHash(EMAIL_NAMESPACE, emailNormalized);
+      var now             = Date.now();
+
+      // Idempotent insert — re-running with the same address is a
+      // no-op on the storage side, but the operator's caller might
+      // want to distinguish "this address just joined" from "we
+      // already had this address" for response copy. The SELECT
+      // after the INSERT-OR-IGNORE tells us which one happened.
+      var id = _b().uuid.v7();
+      await query(
+        "INSERT OR IGNORE INTO newsletter_signups " +
+        "(id, email_hash, email_normalized, source, created_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5)",
+        [id, emailHash, emailNormalized, source, now],
+      );
+      var existing = (await query(
+        "SELECT id, created_at FROM newsletter_signups WHERE email_hash = ?1 LIMIT 1",
+        [emailHash],
+      )).rows[0];
+      var status = existing && existing.id === id ? "new" : "dedup";
+      return {
+        id:               existing ? existing.id : id,
+        status:           status,
+        email_normalized: emailNormalized,
+      };
+    },
+
+    byEmailHash: async function (emailHash) {
+      if (typeof emailHash !== "string" || !emailHash.length) {
+        throw new TypeError("newsletter.byEmailHash: emailHash required");
+      }
+      var r = await query(
+        "SELECT id, email_normalized, source, created_at, unsubscribed_at " +
+        "FROM newsletter_signups WHERE email_hash = ?1 LIMIT 1",
+        [emailHash],
+      );
+      return r.rows[0] || null;
+    },
+
+    // Total active signups — drives the optional live stat the
+    // operator can surface in the newsletter band. Excludes rows
+    // where `unsubscribed_at` is non-NULL.
+    count: async function () {
+      var r = await query(
+        "SELECT COUNT(*) AS n FROM newsletter_signups WHERE unsubscribed_at IS NULL",
+        [],
+      );
+      return Number((r.rows[0] || {}).n || 0);
+    },
+  };
+}
+
+module.exports = {
+  create: create,
+};