@blamejs/blamejs-shop 0.0.53 → 0.0.56

package/lib/webhooks.js

@@ -53,6 +53,38 @@ var KNOWN_EVENTS = Object.freeze([
 
 var SECRET_BYTES = 32;
 
+// Exponential backoff schedule (seconds) for failed deliveries.
+//
+// Budget rationale — the receiver can be down for a full day before
+// we give up. The five-step ramp is deliberately conservative:
+//
+//   60s     → cover a transient blip (LB reload, instance restart,
+//             garbage-collection pause). Quick retry catches the
+//             99% of failures that resolve themselves in <1 minute.
+//   300s    → after the second failure assume the outage is real;
+//             back off to five minutes so we don't hammer a receiver
+//             whose maintenance window is mid-deploy.
+//   1800s   → thirty minutes — covers a typical incident-response
+//             rollback / hotfix-deploy turnaround.
+//   14400s  → four hours — covers an overnight outage where the
+//             on-call hasn't been paged yet.
+//   86400s  → one day — last attempt before DLQ. If a receiver is
+//             still down 24h after the first failure the operator
+//             needs to look at the row by hand; further retries
+//             would risk DOS'ing the receiver's recovery path.
+//
+// After the fifth failed attempt the delivery moves to webhook_dlq
+// for operator investigation — see `_moveToDlq` below.
+var BACKOFF_SCHEDULE_S = Object.freeze([60, 300, 1800, 14400, 86400]);
+var MAX_ATTEMPTS       = 5;
+
+// Window used by the per-endpoint rate-limit sliding count. One
+// minute is short enough that a wedged receiver doesn't permanently
+// brick its own delivery feed (the window naturally slides forward),
+// long enough that bursty fan-out from a single high-volume event
+// doesn't trip the throttle on a healthy endpoint.
+var RATE_WINDOW_MS = 60 * 1000;
+
 function _now() { return Date.now(); }
 
 function _validateUrl(url) {
@@ -120,10 +152,25 @@ function create(opts) {
   }
   var transport = typeof opts.transport === "function" ? opts.transport : _defaultTransport;
   var retryOpts = opts.retry || { maxAttempts: 2, baseDelayMs: 25, maxDelayMs: 250 };
+  // Operator-injectable clock — tests fast-forward through the
+  // exponential backoff schedule by passing a synthetic `now()` that
+  // jumps ahead by the scheduled interval. Production callers leave
+  // it undefined and pick up the wall clock.
+  var nowFn = (typeof opts.now === "function") ? opts.now : _now;
 
   async function _deliver(endpointRow, eventType, payloadJson) {
+    // Rate-limit gate — count deliveries created in the last 60s for
+    // this endpoint and refuse the new fan-out when the configured
+    // ceiling would be exceeded. The refusal persists a delivery row
+    // (last_error = "rate-limited", delivered_at = NULL, no
+    // next_retry_at) so the operator sees the throttle in the admin
+    // feed instead of silently dropping the event.
+    var rateOk = await _checkRateLimit(endpointRow);
+    if (!rateOk) {
+      return await _persistRateLimited(endpointRow, eventType, payloadJson);
+    }
     var deliveryId = _b().uuid.v7();
-    var createdAt  = _now();
+    var createdAt  = nowFn();
     await query(
       "INSERT INTO webhook_deliveries (id, endpoint_id, event_type, payload_json, attempts, created_at) " +
       "VALUES (?1, ?2, ?3, ?4, 0, ?5)",
@@ -132,6 +179,31 @@ function create(opts) {
     return await _attempt(deliveryId, endpointRow, eventType, payloadJson);
   }
 
+  async function _checkRateLimit(endpointRow) {
+    var limit = endpointRow.rate_limit_per_minute;
+    if (typeof limit !== "number" || !isFinite(limit) || limit <= 0) return true;
+    var windowStart = nowFn() - RATE_WINDOW_MS;
+    var r = await query(
+      "SELECT count(*) AS n FROM webhook_deliveries WHERE endpoint_id = ?1 AND created_at > ?2",
+      [endpointRow.id, windowStart],
+    );
+    var n = (r.rows[0] && (r.rows[0].n != null ? r.rows[0].n : r.rows[0]["count(*)"])) || 0;
+    return n < limit;
+  }
+
+  async function _persistRateLimited(endpointRow, eventType, payloadJson) {
+    var deliveryId = _b().uuid.v7();
+    var ts = nowFn();
+    await query(
+      "INSERT INTO webhook_deliveries " +
+      "(id, endpoint_id, event_type, payload_json, attempts, last_status, last_error, " +
+      " last_attempted_at, created_at) " +
+      "VALUES (?1, ?2, ?3, ?4, 0, NULL, ?5, ?6, ?7)",
+      [deliveryId, endpointRow.id, eventType, payloadJson, "rate-limited", ts, ts],
+    );
+    return await _getDelivery(deliveryId);
+  }
+
   async function _attempt(deliveryId, endpointRow, eventType, payloadJson) {
     var signer = _b().webhook.signer({
       algo:        "hmac-sha3-512",
@@ -157,24 +229,70 @@ function create(opts) {
       errMsg = (e && e.message) || String(e);
     }
 
-    var ts = _now();
+    var ts = nowFn();
     var delivered = (status >= 100 && status < 400);
     if (delivered) {
       await query(
-        "UPDATE webhook_deliveries SET attempts = attempts + 1, last_status = ?1, last_error = NULL, delivered_at = ?2 " +
+        "UPDATE webhook_deliveries SET attempts = attempts + 1, last_status = ?1, " +
+        "last_error = NULL, delivered_at = ?2, last_attempted_at = ?2, next_retry_at = NULL " +
         "WHERE id = ?3",
         [status, ts, deliveryId],
       );
-    } else {
-      await query(
-        "UPDATE webhook_deliveries SET attempts = attempts + 1, last_status = ?1, last_error = ?2 " +
-        "WHERE id = ?3",
-        [status || null, errMsg || ("http-" + status), deliveryId],
-      );
+      return await _getDelivery(deliveryId);
+    }
+
+    // Failure path — increment attempts, record the error, then
+    // either schedule the next retry (attempts < MAX_ATTEMPTS) or
+    // move the delivery to webhook_dlq for operator review. The
+    // backoff index uses `attempts - 1` after increment so the first
+    // failure gets BACKOFF_SCHEDULE_S[0] (60s), the second gets [1]
+    // (300s), etc.
+    var current = await _getDelivery(deliveryId);
+    var nextAttempts = ((current && current.attempts) || 0) + 1;
+    var willDlq = (nextAttempts >= MAX_ATTEMPTS);
+    var nextRetryAt = null;
+    if (!willDlq) {
+      var idx = nextAttempts - 1;
+      if (idx < BACKOFF_SCHEDULE_S.length) {
+        nextRetryAt = ts + (BACKOFF_SCHEDULE_S[idx] * 1000);
+      }
+    }
+    await query(
+      "UPDATE webhook_deliveries SET attempts = ?1, last_status = ?2, last_error = ?3, " +
+      "last_attempted_at = ?4, next_retry_at = ?5 WHERE id = ?6",
+      [nextAttempts, status || null, errMsg || ("http-" + status), ts, nextRetryAt, deliveryId],
+    );
+    if (willDlq) {
+      await _moveToDlq(deliveryId, endpointRow, eventType, payloadJson, nextAttempts,
+        status || null, errMsg || ("http-" + status), ts);
     }
     return await _getDelivery(deliveryId);
   }
 
+  async function _moveToDlq(deliveryId, endpointRow, eventType, payloadJson, attempts,
+                            lastStatus, lastError, ts) {
+    // The original delivery row stays in webhook_deliveries (with
+    // attempts === MAX_ATTEMPTS, delivered_at NULL) so the
+    // per-endpoint feed still surfaces the failure. The DLQ row
+    // carries the full payload so replayFromDlq can re-queue
+    // without consulting the original delivery.
+    var dlqId = _b().uuid.v7();
+    var firstAttemptedAt;
+    var r = await query(
+      "SELECT created_at FROM webhook_deliveries WHERE id = ?1",
+      [deliveryId],
+    );
+    firstAttemptedAt = (r.rows[0] && r.rows[0].created_at) || ts;
+    await query(
+      "INSERT INTO webhook_dlq " +
+      "(id, endpoint_id, delivery_id, event_type, payload_json, attempts, " +
+      " last_status, last_error, first_attempted_at, last_attempted_at, dropped_at) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+      [dlqId, endpointRow.id, deliveryId, eventType, payloadJson, attempts,
+       lastStatus, lastError, firstAttemptedAt, ts, ts],
+    );
+  }
+
   async function _getDelivery(id) {
     var r = await query("SELECT * FROM webhook_deliveries WHERE id = ?1", [id]);
     return r.rows[0] || null;
@@ -196,10 +314,25 @@ function create(opts) {
         var id     = _b().uuid.v7();
         var secret = _b().crypto.generateToken(SECRET_BYTES);
         var ts     = _now();
+        // rate_limit_per_minute defaults to 60 at the schema level
+        // (see migration 0017). Operators wiring a slow receiver opt
+        // into a lower ceiling on create; raising it past the default
+        // is supported but undocumented — most receivers handle 60
+        // req/min comfortably.
+        var rate = 60;
+        if (Object.prototype.hasOwnProperty.call(input, "rate_limit_per_minute")) {
+          if (typeof input.rate_limit_per_minute !== "number" ||
+              !Number.isInteger(input.rate_limit_per_minute) ||
+              input.rate_limit_per_minute <= 0) {
+            throw new TypeError("webhooks.endpoints.create: rate_limit_per_minute must be a positive integer");
+          }
+          rate = input.rate_limit_per_minute;
+        }
         await query(
-          "INSERT INTO webhook_endpoints (id, url, secret, events, active, created_at, updated_at) " +
-          "VALUES (?1, ?2, ?3, ?4, 1, ?5, ?5)",
-          [id, input.url, secret, events, ts],
+          "INSERT INTO webhook_endpoints " +
+          "(id, url, secret, events, active, rate_limit_per_minute, created_at, updated_at) " +
+          "VALUES (?1, ?2, ?3, ?4, 1, ?5, ?6, ?6)",
+          [id, input.url, secret, events, rate, ts],
         );
         return await _getEndpoint(id);
       },
@@ -222,6 +355,7 @@ function create(opts) {
         var nextUrl    = current.url;
         var nextEvents = current.events;
         var nextActive = current.active;
+        var nextRate   = current.rate_limit_per_minute;
         if (Object.prototype.hasOwnProperty.call(patch, "url")) {
           _validateUrl(patch.url);
           nextUrl = patch.url;
@@ -235,10 +369,18 @@ function create(opts) {
           }
           nextActive = (patch.active === true || patch.active === 1) ? 1 : 0;
         }
+        if (Object.prototype.hasOwnProperty.call(patch, "rate_limit_per_minute")) {
+          var rate = patch.rate_limit_per_minute;
+          if (typeof rate !== "number" || !Number.isInteger(rate) || rate <= 0) {
+            throw new TypeError("webhooks.endpoints.update: rate_limit_per_minute must be a positive integer");
+          }
+          nextRate = rate;
+        }
         var ts = _now();
         await query(
-          "UPDATE webhook_endpoints SET url = ?1, events = ?2, active = ?3, updated_at = ?4 WHERE id = ?5",
-          [nextUrl, nextEvents, nextActive, ts, id],
+          "UPDATE webhook_endpoints SET url = ?1, events = ?2, active = ?3, " +
+          "rate_limit_per_minute = ?4, updated_at = ?5 WHERE id = ?6",
+          [nextUrl, nextEvents, nextActive, nextRate, ts, id],
         );
         return await _getEndpoint(id);
       },
@@ -272,6 +414,139 @@ function create(opts) {
       },
     },
 
+    dlq: {
+      list: async function (endpointId, listOpts) {
+        _uuid(endpointId, "endpoint id");
+        var limit = (listOpts && Number.isInteger(listOpts.limit) && listOpts.limit > 0) ? listOpts.limit : 50;
+        if (limit > 500) limit = 500;
+        var r = await query(
+          "SELECT * FROM webhook_dlq WHERE endpoint_id = ?1 ORDER BY dropped_at DESC LIMIT ?2",
+          [endpointId, limit],
+        );
+        return r.rows;
+      },
+
+      get: async function (id) {
+        _uuid(id, "dlq id");
+        var r = await query("SELECT * FROM webhook_dlq WHERE id = ?1", [id]);
+        return r.rows[0] || null;
+      },
+    },
+
+    // Re-queue a DLQ row as a fresh delivery on its original
+    // endpoint. The DLQ row is removed once the new delivery row is
+    // persisted — keeping both would leave duplicate state for the
+    // admin feed to reconcile. The new delivery starts at attempts=0
+    // so the full backoff schedule applies if the receiver is still
+    // unhappy.
+    replayFromDlq: async function (dlqId) {
+      _uuid(dlqId, "dlq id");
+      var r = await query("SELECT * FROM webhook_dlq WHERE id = ?1", [dlqId]);
+      var row = r.rows[0];
+      if (!row) return null;
+      var endpoint = await _getEndpoint(row.endpoint_id);
+      if (!endpoint) return null;
+      // Delete first — if the subsequent _deliver fails we don't
+      // want a permanent ghost; the new delivery row carries the
+      // failure state forward and (on five failures) lands back in
+      // the DLQ as a fresh row.
+      await query("DELETE FROM webhook_dlq WHERE id = ?1", [dlqId]);
+      return await _deliver(endpoint, row.event_type, row.payload_json);
+    },
+
+    // Polled scheduler entry point — picks deliveries whose
+    // next_retry_at has come due and re-attempts each. Operators
+    // wire this to a cron / Durable Object alarm / queue worker.
+    // Returns the list of deliveries the call attempted.
+    //
+    // No claim/lock here — the framework's single-writer assumption
+    // for the deliveries table holds (the worker is the only writer).
+    // A multi-writer deployment composes external locking before
+    // calling processRetries.
+    processRetries: async function (procOpts) {
+      var now = (procOpts && typeof procOpts.now === "number") ? procOpts.now : nowFn();
+      var max = (procOpts && Number.isInteger(procOpts.max) && procOpts.max > 0) ? procOpts.max : 100;
+      if (max > 1000) max = 1000;
+      var r = await query(
+        "SELECT * FROM webhook_deliveries " +
+        "WHERE next_retry_at IS NOT NULL AND next_retry_at <= ?1 AND delivered_at IS NULL " +
+        "ORDER BY next_retry_at ASC LIMIT ?2",
+        [now, max],
+      );
+      var attempted = [];
+      for (var i = 0; i < r.rows.length; i += 1) {
+        var row = r.rows[i];
+        var endpoint = await _getEndpoint(row.endpoint_id);
+        if (!endpoint) continue;
+        var d = await _attempt(row.id, endpoint, row.event_type, row.payload_json);
+        attempted.push(d);
+      }
+      return attempted;
+    },
+
+    // Inbound signature verification — operators receiving webhooks
+    // from peers (or replaying their own outbound for end-to-end
+    // testing) call this to validate the Stripe-shaped header
+    // `t=<unix>,v1=<hmac-sha256(secret, ts + "." + body)>` before
+    // trusting the payload. Delegates to b.webhook.verify — the
+    // framework's Stripe-compatible verifier handles tolerance,
+    // constant-time compare, and HMAC-SHA-256 computation.
+    //
+    // `toleranceSeconds` defaults to 300 (5 min) to match the
+    // framework default; the floor is 30 s — anything shorter risks
+    // false rejects from clock skew.
+    verifyIncoming: async function (payload, signatureHeader, secret, toleranceSeconds) {
+      if (payload == null) {
+        throw new TypeError("webhooks.verifyIncoming: payload required");
+      }
+      if (typeof signatureHeader !== "string" || signatureHeader.length === 0) {
+        throw new TypeError("webhooks.verifyIncoming: signatureHeader must be a non-empty string");
+      }
+      if ((typeof secret !== "string" || secret.length === 0) && !Buffer.isBuffer(secret)) {
+        throw new TypeError("webhooks.verifyIncoming: secret must be a non-empty string or Buffer");
+      }
+      var tolMs;
+      if (toleranceSeconds === undefined) {
+        tolMs = 300 * 1000;
+      } else {
+        if (typeof toleranceSeconds !== "number" || !isFinite(toleranceSeconds) || toleranceSeconds < 30) {
+          throw new TypeError("webhooks.verifyIncoming: toleranceSeconds must be >= 30");
+        }
+        tolMs = Math.floor(toleranceSeconds * 1000);
+      }
+      return await _b().webhook.verify({
+        alg:         "hmac-sha256-stripe",
+        secret:      secret,
+        header:      signatureHeader,
+        body:        payload,
+        toleranceMs: tolMs,
+      });
+    },
+
+    // Companion to verifyIncoming — produce the Stripe-shaped
+    // `t=<unix>,v1=<hex>` header for a given payload + secret. The
+    // round-trip is what end-to-end tests + downstream emitters
+    // need; operators forwarding events to peer systems use this to
+    // sign the relay body.
+    signOutgoing: function (payload, secret, timestampSeconds) {
+      if (payload == null) {
+        throw new TypeError("webhooks.signOutgoing: payload required");
+      }
+      if ((typeof secret !== "string" || secret.length === 0) && !Buffer.isBuffer(secret)) {
+        throw new TypeError("webhooks.signOutgoing: secret must be a non-empty string or Buffer");
+      }
+      var input = {
+        alg:    "hmac-sha256-stripe",
+        secret: secret,
+        body:   payload,
+      };
+      if (timestampSeconds !== undefined) input.timestamp = timestampSeconds;
+      return _b().webhook.sign(input);
+    },
+
+    BACKOFF_SCHEDULE_S: BACKOFF_SCHEDULE_S,
+    MAX_ATTEMPTS:       MAX_ATTEMPTS,
+
     send: async function (eventType, payload) {
       if (typeof eventType !== "string" || eventType.length === 0) {
         throw new TypeError("webhooks.send: eventType must be a non-empty string");
@@ -300,6 +575,8 @@ function create(opts) {
 }
 
 module.exports = {
-  create:       create,
-  KNOWN_EVENTS: KNOWN_EVENTS,
+  create:             create,
+  KNOWN_EVENTS:       KNOWN_EVENTS,
+  BACKOFF_SCHEDULE_S: BACKOFF_SCHEDULE_S,
+  MAX_ATTEMPTS:       MAX_ATTEMPTS,
 };

package/lib/wishlist.js

@@ -0,0 +1,269 @@
+/**
+ * Wishlist — customers save products (or specific variants) for
+ * later. The storefront PDP renders an "Add to wishlist" toggle that
+ * resolves through `isWishlisted` + `add` / `remove`; the account
+ * page renders the customer's saved items via `listForCustomer`; and
+ * the "X people saved this" social-proof counter on the PDP reads
+ * `countForProduct`. The home page / category page surfaces a
+ * "Most-wishlisted" rail via `popularProducts`.
+ *
+ * Composes:
+ *   - `b.guardUuid` — every customer / product / variant id is
+ *     UUID-shape-validated at the entry point. The primitive itself
+ *     never trusts an opaque string; the guard refuses on shape and
+ *     surfaces a TypeError that the storefront translates to a 400.
+ *   - `b.crypto.namespaceHash` — not used for row identity (the row
+ *     id is a UUIDv7 from `b.uuid.v7`); reserved for forthcoming
+ *     follower / shared-wishlist features that need a deterministic
+ *     handle without leaking customer ids.
+ *   - `b.uuid.v7` — row id.
+ *   - `b.pagination.encodeCursor` / `decodeCursor` — HMAC-tagged
+ *     opaque cursor on the `(created_at DESC, id DESC)` tuple so an
+ *     operator can't hand-craft a cursor to skip past a hidden row
+ *     or replay one across deployments.
+ *
+ * Surface:
+ *   - `add({ customer_id, product_id, variant_id?, notes? })` —
+ *     INSERT OR IGNORE on the unique (customer, product, variant)
+ *     tuple; returns `{ id, status: "added" | "dedup" }`.
+ *   - `remove({ customer_id, product_id, variant_id? })` — DELETE
+ *     the matching row; returns `{ removed: boolean }`.
+ *   - `listForCustomer(customer_id, { limit?, cursor? })` —
+ *     paginated entries scoped to one customer; returns
+ *     `{ rows, nextCursor }`.
+ *   - `isWishlisted({ customer_id, product_id, variant_id? })` —
+ *     boolean lookup used by the PDP toggle.
+ *   - `countForProduct(product_id)` — how many customers wishlisted
+ *     this product (variant-collapsed — counts distinct customers).
+ *   - `popularProducts({ limit? })` — `[ { product_id, count } ]`
+ *     sorted by count desc, used for the "Most-wishlisted" rail.
+ *
+ * Storage:
+ *   - `wishlist_entries` (migration `0012_wishlist.sql`).
+ *
+ * @primitive wishlist
+ * @related   b.guardUuid, b.pagination, b.uuid
+ */
+
+"use strict";
+
+var MAX_NOTES_LEN  = 280;
+var DEFAULT_LIMIT  = 20;
+var MAX_LIMIT      = 100;
+var POPULAR_LIMIT  = 50;
+var WISHLIST_ORDER_KEY = ["created_at:desc", "id:desc"];
+
+// 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 _uuid(s, label) {
+  try { return _b().guardUuid.sanitize(s, { profile: "strict" }); }
+  catch (e) { throw new TypeError("wishlist: " + label + " — " + (e && e.message || "invalid UUID")); }
+}
+
+function _optUuid(s, label) {
+  if (s == null || s === "") return null;
+  return _uuid(s, label);
+}
+
+function _normalizeNotes(s) {
+  if (s == null) return "";
+  if (typeof s !== "string") {
+    throw new TypeError("wishlist: notes must be a string");
+  }
+  // Refuse control bytes (incl. CR/LF) so a malicious note can't
+  // smuggle header-injection-class content into operator dashboards
+  // or downstream email templates that render the note inline.
+  if (/[\x00-\x1f\x7f]/.test(s)) {
+    throw new TypeError("wishlist: notes must not contain control bytes");
+  }
+  if (s.length > MAX_NOTES_LEN) {
+    throw new TypeError("wishlist: notes must be <= " + MAX_NOTES_LEN + " chars");
+  }
+  return s;
+}
+
+function _limit(n, label) {
+  if (n == null) return DEFAULT_LIMIT;
+  if (!Number.isInteger(n) || n <= 0 || n > MAX_LIMIT) {
+    throw new TypeError("wishlist: " + label + " must be 1..." + MAX_LIMIT);
+  }
+  return n;
+}
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+  // Pagination cursors for listForCustomer are HMAC-tagged via
+  // b.pagination so an operator can't hand-craft one to skip past a
+  // hidden entry or replay across deployments. The secret defaults
+  // to a dev-only placeholder so the primitive boots in tests; the
+  // deployment is expected to supply a derived value (typically
+  // b.crypto.namespaceHash("wishlist-cursor", D1_BRIDGE_SECRET)).
+  if (typeof opts.cursorSecret !== "string" || !opts.cursorSecret.length) {
+    if (process.env.NODE_ENV === "production") {
+      throw new Error("wishlist.create: opts.cursorSecret is required in production");
+    }
+    opts.cursorSecret = "wishlist-cursor-secret-dev-only";
+  }
+  var cursorSecret = opts.cursorSecret;
+
+  return {
+    MAX_NOTES_LEN: MAX_NOTES_LEN,
+
+    add: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("wishlist.add: input object required");
+      }
+      var customerId = _uuid(input.customer_id, "customer_id");
+      var productId  = _uuid(input.product_id,  "product_id");
+      var variantId  = _optUuid(input.variant_id, "variant_id");
+      var notes      = _normalizeNotes(input.notes);
+      var now        = Date.now();
+      var id         = _b().uuid.v7();
+
+      // Idempotent insert — re-running with the same
+      // (customer, product, variant) tuple is a no-op on the storage
+      // side. The SELECT after the INSERT-OR-IGNORE tells us which
+      // one happened so the caller can distinguish "this just got
+      // added" from "we already had this entry" for UI copy.
+      await query(
+        "INSERT OR IGNORE INTO wishlist_entries " +
+        "(id, customer_id, product_id, variant_id, notes, created_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+        [id, customerId, productId, variantId, notes, now],
+      );
+      var existing = (await query(
+        "SELECT id FROM wishlist_entries " +
+        "WHERE customer_id = ?1 AND product_id = ?2 " +
+        "AND COALESCE(variant_id, '') = COALESCE(?3, '') LIMIT 1",
+        [customerId, productId, variantId],
+      )).rows[0];
+      var status = existing && existing.id === id ? "added" : "dedup";
+      return {
+        id:     existing ? existing.id : id,
+        status: status,
+      };
+    },
+
+    remove: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("wishlist.remove: input object required");
+      }
+      var customerId = _uuid(input.customer_id, "customer_id");
+      var productId  = _uuid(input.product_id,  "product_id");
+      var variantId  = _optUuid(input.variant_id, "variant_id");
+      var r = await query(
+        "DELETE FROM wishlist_entries " +
+        "WHERE customer_id = ?1 AND product_id = ?2 " +
+        "AND COALESCE(variant_id, '') = COALESCE(?3, '')",
+        [customerId, productId, variantId],
+      );
+      return { removed: Number(r.rowCount || 0) > 0 };
+    },
+
+    listForCustomer: async function (customerId, listOpts) {
+      var cid = _uuid(customerId, "customer_id");
+      listOpts = listOpts || {};
+      var limit = _limit(listOpts.limit, "limit");
+      var cursorVals = null;
+      if (listOpts.cursor != null) {
+        if (typeof listOpts.cursor !== "string") {
+          throw new TypeError("wishlist.listForCustomer: cursor must be an opaque string or null");
+        }
+        try {
+          var state = _b().pagination.decodeCursor(listOpts.cursor, cursorSecret);
+          if (JSON.stringify(state.orderKey) !== JSON.stringify(WISHLIST_ORDER_KEY)) {
+            throw new TypeError("wishlist.listForCustomer: cursor orderKey mismatch");
+          }
+          cursorVals = state.vals;
+        } catch (e) {
+          if (e instanceof TypeError) throw e;
+          throw new TypeError("wishlist.listForCustomer: cursor — " + (e && e.message || "malformed"));
+        }
+      }
+      var sql, params;
+      if (cursorVals) {
+        sql = "SELECT * FROM wishlist_entries WHERE customer_id = ?1 AND " +
+              "(created_at < ?2 OR (created_at = ?2 AND id < ?3)) " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?4";
+        params = [cid, cursorVals[0], cursorVals[1], limit];
+      } else {
+        sql = "SELECT * FROM wishlist_entries WHERE customer_id = ?1 " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?2";
+        params = [cid, limit];
+      }
+      var rows = (await query(sql, params)).rows;
+      var last = rows[rows.length - 1];
+      var nextCursor = null;
+      if (last && rows.length === limit) {
+        nextCursor = _b().pagination.encodeCursor({
+          orderKey: WISHLIST_ORDER_KEY,
+          vals:     [last.created_at, last.id],
+          forward:  true,
+        }, cursorSecret);
+      }
+      return { rows: rows, nextCursor: nextCursor };
+    },
+
+    isWishlisted: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("wishlist.isWishlisted: input object required");
+      }
+      var customerId = _uuid(input.customer_id, "customer_id");
+      var productId  = _uuid(input.product_id,  "product_id");
+      var variantId  = _optUuid(input.variant_id, "variant_id");
+      var r = await query(
+        "SELECT id FROM wishlist_entries " +
+        "WHERE customer_id = ?1 AND product_id = ?2 " +
+        "AND COALESCE(variant_id, '') = COALESCE(?3, '') LIMIT 1",
+        [customerId, productId, variantId],
+      );
+      return r.rows.length > 0;
+    },
+
+    countForProduct: async function (productId) {
+      var pid = _uuid(productId, "product_id");
+      var r = await query(
+        "SELECT COUNT(DISTINCT customer_id) AS n FROM wishlist_entries WHERE product_id = ?1",
+        [pid],
+      );
+      return Number((r.rows[0] || {}).n || 0);
+    },
+
+    popularProducts: async function (popOpts) {
+      popOpts = popOpts || {};
+      var limit = popOpts.limit == null ? POPULAR_LIMIT
+                                        : _limit(popOpts.limit, "limit");
+      var rows = (await query(
+        "SELECT product_id, COUNT(DISTINCT customer_id) AS count " +
+        "FROM wishlist_entries " +
+        "GROUP BY product_id " +
+        "ORDER BY count DESC, product_id ASC " +
+        "LIMIT ?1",
+        [limit],
+      )).rows;
+      var out = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        out.push({
+          product_id: rows[i].product_id,
+          count:      Number(rows[i].count),
+        });
+      }
+      return out;
+    },
+  };
+}
+
+module.exports = {
+  create: create,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.0.53",
+  "version": "0.0.56",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {