@blamejs/blamejs-shop 0.1.20 → 0.1.22

package/lib/checkout.js

@@ -106,6 +106,93 @@ function create(deps) {
   // customers.hashEmail keying the customers table) and stored on the
   // order so a later verified-email sign-in can claim the guest order.
   var customers     = deps.customers || null;
+  // Optional gift-card credit. `giftcards` owns the bearer credential
+  // (lookup + the atomic balance decrement); `giftCardLedger` writes
+  // the audit row. Gift-card redemption at checkout disables when
+  // either is absent — the rest of the flow is unchanged.
+  var giftcards     = deps.giftcards || null;
+  var giftCardLedger = deps.giftCardLedger || null;
+
+  // Validate a gift-card code against a priced quote: the card exists,
+  // is active, not expired, and matches the order currency. Returns
+  // the credit to apply (capped at the grand total so an order total
+  // can never go negative) plus the resolved card row. Throws a
+  // structured (non-TypeError) error on a code the customer typed that
+  // can't be applied so callers surface a clean message; returns null
+  // when no code was supplied or gift-card redemption isn't wired.
+  async function _resolveGiftCard(code, quote) {
+    if (code == null || code === "") return null;
+    if (!giftcards) {
+      var unwired = new Error("checkout: gift-card redemption is not configured");
+      unwired.code = "GIFTCARD_NOT_CONFIGURED";
+      throw unwired;
+    }
+    // _lookup throws TypeError on a malformed code (wrong length /
+    // out-of-alphabet). Treat that as a generic "not recognized" so
+    // the storefront never distinguishes "doesn't exist" from
+    // "malformed" — both are the same dead end to a customer.
+    var card;
+    try {
+      card = await giftcards.lookup(code);
+    } catch (e) {
+      if (e instanceof TypeError) card = null;
+      else throw e;
+    }
+    if (!card) {
+      var miss = new Error("checkout: gift card not recognized");
+      miss.code = "GIFTCARD_NOT_FOUND";
+      throw miss;
+    }
+    if (card.status !== "active") {
+      var inactive = new Error("checkout: gift card is " + card.status);
+      inactive.code = "GIFTCARD_NOT_ACTIVE";
+      throw inactive;
+    }
+    if (card.expires_at != null && card.expires_at <= Date.now()) {
+      var expired = new Error("checkout: gift card is expired");
+      expired.code = "GIFTCARD_EXPIRED";
+      throw expired;
+    }
+    if (card.currency !== quote.currency) {
+      var mismatch = new Error("checkout: gift card currency " + card.currency +
+                               " does not match order currency " + quote.currency);
+      mismatch.code = "GIFTCARD_CURRENCY_MISMATCH";
+      throw mismatch;
+    }
+    // Credit is the lesser of the card balance and the grand total —
+    // a card worth more than the order leaves the remainder on the
+    // card; a card worth less reduces the amount due, never below 0.
+    var grand = quote.totals.grand_total_minor;
+    var applied = card.balance_minor < grand ? card.balance_minor : grand;
+    // `code_plain` is the bearer code the redeem decrement re-hashes;
+    // it lives only in this in-memory resolution, never persisted.
+    return { card: card, code_plain: code, applied_minor: applied, balance_minor: card.balance_minor };
+  }
+
+  // Burn the resolved credit against the created order. The
+  // `giftcards.redeem` decrement is the authoritative double-spend
+  // guard — its `balance_minor >= ?` SQL predicate refuses a second
+  // spend that would overdraw, and a re-quote of the same card on a
+  // new order only ever debits the remaining balance. The ledger
+  // debit rides alongside as the operator-facing audit row, keyed on
+  // the order id. Called once per order, immediately after the order
+  // row exists, so a card is never burned for an order that failed to
+  // create.
+  async function _redeemGiftCard(resolved, orderId) {
+    var redemption = await giftcards.redeem({
+      code:         resolved.code_plain,
+      order_id:     orderId,
+      amount_minor: resolved.applied_minor,
+    });
+    if (giftCardLedger) {
+      await giftCardLedger.debit({
+        gift_card_id: resolved.card.id,
+        order_id:     orderId,
+        amount_minor: resolved.applied_minor,
+      });
+    }
+    return redemption;
+  }
 
   // Compose a quote from a cart + ship-to + (optional) selected
   // shipping service. Pure read — no DB writes.
@@ -200,9 +287,63 @@ function create(deps) {
         throw new TypeError("checkout.confirm: grand_total_minor must be > 0 (zero-total orders use a separate freebie flow)");
       }
 
-      // Create the PaymentIntent (idempotent via header).
+      // Resolve an optional gift-card credit BEFORE any charge so a
+      // bad code fails the checkout without touching Stripe. The
+      // credit reduces the amount due; the order still records the
+      // full grand total it owed.
+      var gc = await _resolveGiftCard(input.gift_card_code, quote);
+      var amountDue = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+
+      var orderLines = quote.lines.map(function (l) {
+        return {
+          variant_id:        l.variant_id,
+          sku:               l.sku,
+          qty:               l.qty,
+          unit_amount_minor: l.unit_amount_minor,
+          unit_currency:     l.unit_currency,
+        };
+      });
+      var cartRow = await cart.get(quote.cart_id);
+      // Hash of the buyer email (same key as the customers table) so a
+      // later verified-email sign-in can claim this guest order.
+      var emailHash = customers ? customers.hashEmail(email) : null;
+
+      // Zero amount due — the gift card fully covers the order. No
+      // PaymentIntent (Stripe refuses a zero-amount intent); create
+      // the order, burn the card against it, and advance it straight
+      // to paid via the FSM.
+      if (amountDue === 0) {
+        var paidOrder = await order.createFromCart({
+          cart_id:            quote.cart_id,
+          session_id:         cartRow.session_id,
+          customer_id:        cartRow.customer_id || null,
+          currency:           quote.currency,
+          subtotal_minor:    quote.totals.subtotal_minor,
+          discount_minor:    quote.totals.discount_minor,
+          tax_minor:         quote.totals.tax_minor,
+          shipping_minor:    quote.totals.shipping_minor,
+          grand_total_minor: quote.totals.grand_total_minor,
+          payment_intent_id: null,
+          ship_to:           input.ship_to,
+          customer_email_hash: emailHash,
+          lines:             orderLines,
+        });
+        await _redeemGiftCard(gc, paidOrder.id);
+        await cart.setStatus(quote.cart_id, "converted");
+        var settled = await order.transition(paidOrder.id, "mark_paid", {
+          reason: "gift_card:full",
+        });
+        return {
+          order: settled,
+          payment_intent: null,
+          gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 },
+        };
+      }
+
+      // Create the PaymentIntent for the amount DUE after the credit
+      // (idempotent via header).
       var pi = await payment.createPaymentIntent({
-        amount_minor:  quote.totals.grand_total_minor,
+        amount_minor:  amountDue,
         currency:      quote.currency.toLowerCase(),
         receipt_email: email,
         description:   "blamejs.shop order — cart " + quote.cart_id,
@@ -212,11 +353,11 @@ function create(deps) {
           subtotal_minor: String(quote.totals.subtotal_minor),
           tax_minor:      String(quote.totals.tax_minor),
           shipping_minor: String(quote.totals.shipping_minor),
+          gift_card_applied_minor: String(gc ? gc.applied_minor : 0),
         },
       }, idempotencyKey);
 
       // Create the local order in `pending` state with the PI linked.
-      var cartRow = await cart.get(quote.cart_id);
       var createdOrder = await order.createFromCart({
         cart_id:            quote.cart_id,
         session_id:         cartRow.session_id,
@@ -229,20 +370,15 @@ function create(deps) {
         grand_total_minor: quote.totals.grand_total_minor,
         payment_intent_id: pi.id,
         ship_to:           input.ship_to,
-        // Hash of the buyer email (same key as the customers table) so a
-        // later verified-email sign-in can claim this guest order.
-        customer_email_hash: customers ? customers.hashEmail(email) : null,
-        lines:             quote.lines.map(function (l) {
-          return {
-            variant_id:        l.variant_id,
-            sku:               l.sku,
-            qty:               l.qty,
-            unit_amount_minor: l.unit_amount_minor,
-            unit_currency:     l.unit_currency,
-          };
-        }),
+        customer_email_hash: emailHash,
+        lines:             orderLines,
       });
 
+      // Burn the gift-card credit against the created order. Runs
+      // after the order row exists so a failed order never burns the
+      // card; the redeem decrement is the double-spend guard.
+      if (gc) await _redeemGiftCard(gc, createdOrder.id);
+
       // Mark the cart converted so a refresh of the storefront
       // doesn't accidentally re-quote the same cart.
       await cart.setStatus(quote.cart_id, "converted");
@@ -254,6 +390,7 @@ function create(deps) {
           client_secret: pi.client_secret,
           status:        pi.status,
         },
+        gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null,
       };
     },
 
@@ -347,14 +484,48 @@ function create(deps) {
       if (quote.totals.grand_total_minor <= 0) {
         throw new TypeError("checkout.createPaypalOrder: grand_total_minor must be > 0");
       }
+      // Resolve an optional gift-card credit before opening the PayPal
+      // order so a bad code fails without a remote round-trip.
+      var gc = await _resolveGiftCard(input.gift_card_code, quote);
+      var amountDue = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+      var cartRow = await cart.get(quote.cart_id);
+      var emailHash = customers ? customers.hashEmail(email) : null;
+      var ppLines = quote.lines.map(function (l) {
+        return { variant_id: l.variant_id, sku: l.sku, qty: l.qty, unit_amount_minor: l.unit_amount_minor, unit_currency: l.unit_currency };
+      });
+
+      // Gift card fully covers the order — no PayPal order (PayPal
+      // refuses a zero-amount order). Create + burn + mark paid, same
+      // as the Stripe full-coverage path.
+      if (amountDue === 0) {
+        var paidOrder = await order.createFromCart({
+          cart_id:             quote.cart_id,
+          session_id:          cartRow.session_id,
+          customer_id:         cartRow.customer_id || null,
+          currency:            quote.currency,
+          subtotal_minor:      quote.totals.subtotal_minor,
+          discount_minor:      quote.totals.discount_minor,
+          tax_minor:           quote.totals.tax_minor,
+          shipping_minor:      quote.totals.shipping_minor,
+          grand_total_minor:   quote.totals.grand_total_minor,
+          payment_intent_id:   null,
+          ship_to:             input.ship_to,
+          customer_email_hash: emailHash,
+          lines:               ppLines,
+        });
+        await _redeemGiftCard(gc, paidOrder.id);
+        await cart.setStatus(quote.cart_id, "converted");
+        var settled = await order.transition(paidOrder.id, "mark_paid", { reason: "gift_card:full" });
+        return { order: settled, paypal_order_id: null, status: "PAID_BY_GIFT_CARD", gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 } };
+      }
+
       var ppOrder = await paypal.createOrder({
-        amount_minor: quote.totals.grand_total_minor,
+        amount_minor: amountDue,
         currency:     quote.currency.toUpperCase(),
         order_id:     quote.cart_id,
         return_url:   input.return_url || undefined,
         cancel_url:   input.cancel_url || undefined,
       }, idempotencyKey);
-      var cartRow = await cart.get(quote.cart_id);
       var createdOrder = await order.createFromCart({
         cart_id:             quote.cart_id,
         session_id:          cartRow.session_id,
@@ -367,13 +538,12 @@ function create(deps) {
         grand_total_minor:   quote.totals.grand_total_minor,
         payment_intent_id:   ppOrder.id,   // the PayPal order id (opaque); links the webhook + capture
         ship_to:             input.ship_to,
-        customer_email_hash: customers ? customers.hashEmail(email) : null,
-        lines:               quote.lines.map(function (l) {
-          return { variant_id: l.variant_id, sku: l.sku, qty: l.qty, unit_amount_minor: l.unit_amount_minor, unit_currency: l.unit_currency };
-        }),
+        customer_email_hash: emailHash,
+        lines:               ppLines,
       });
+      if (gc) await _redeemGiftCard(gc, createdOrder.id);
       await cart.setStatus(quote.cart_id, "converted");
-      return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status };
+      return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status, gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null };
     },
 
     // Capture an approved PayPal order, then advance the local order to paid.

package/lib/collections.js

@@ -56,7 +56,7 @@
  *     - `defineSmart({ slug, title, description?, rules,
  *                      sort_strategy })`
  *     - `get(slug)`
- *     - `list({ active_only? })`
+ *     - `list({ active_only? | archived_only? })`
  *     - `update(slug, patch)` — title / description / hero_image_url
  *       / sort_strategy / rules (smart only).
  *     - `archive(slug)` — soft delete via archived_at column.
@@ -491,10 +491,11 @@ function create(opts) {
 
   async function list(input) {
     input = input || {};
-    var activeOnly = input.active_only === true;
     var sql;
-    if (activeOnly) {
+    if (input.active_only === true) {
       sql = "SELECT * FROM collections WHERE archived_at IS NULL ORDER BY updated_at DESC, slug DESC";
+    } else if (input.archived_only === true) {
+      sql = "SELECT * FROM collections WHERE archived_at IS NOT NULL ORDER BY updated_at DESC, slug DESC";
     } else {
       sql = "SELECT * FROM collections ORDER BY updated_at DESC, slug DESC";
     }

package/lib/customers.js

@@ -45,6 +45,13 @@ var MAX_CRED_FIELD_BYTES  = 4096;
 var TRANSPORTS_RE = /^[a-z]+(?:,[a-z]+)*$/;
 var CONTROL_BYTE_RE = /[\x00-\x1f\x7f]/;
 
+// Pagination cursor for the operator-facing `list` — newest first by
+// (created_at, id), HMAC-tagged via b.pagination so an operator can't
+// hand-craft one to skip rows. Same orderKey-mismatch refusal the order
+// primitive uses for its customer-scoped history.
+var CUSTOMERS_ORDER_KEY = ["created_at:desc", "id:desc"];
+var MAX_LIST_LIMIT = 100;
+
 // ---- validators ---------------------------------------------------------
 
 function _uuid(s, label) {
@@ -143,6 +150,18 @@ function create(opts) {
   if (!query) {
     query = function (sql, params) { return b.externalDb.query(sql, params); };
   }
+  // Pagination cursors for `list` are HMAC-tagged via b.pagination so an
+  // operator can't hand-craft one to skip past a row or replay across
+  // deployments. The secret defaults to a dev-only placeholder so the
+  // primitive boots in tests; the deployment supplies a derived value
+  // (typically b.crypto.namespaceHash("customers-cursor", D1_BRIDGE_SECRET)).
+  if (typeof opts.cursorSecret !== "string" || !opts.cursorSecret.length) {
+    if (process.env.NODE_ENV === "production") {
+      throw new Error("customers.create: opts.cursorSecret is required in production");
+    }
+    opts.cursorSecret = "customers-cursor-secret-dev-only";
+  }
+  var cursorSecret = opts.cursorSecret;
 
   function _hashEmail(email) {
     return b.crypto.namespaceHash(EMAIL_NAMESPACE, email);
@@ -206,6 +225,89 @@ function create(opts) {
       return r.rows[0] || null;
     },
 
+    // Operator-facing paginated list of customers, newest first by
+    // (created_at, id). Tuple cursor (created_at, id) ordered DESC —
+    // mirrors order.listForCustomer's HMAC-tagged cursor shape (same
+    // b.pagination tag, same orderKey mismatch-on-tamper refusal). The
+    // raw email is never stored, so rows carry only the displayable
+    // columns (id, email_hash, display_name, created_at, updated_at).
+    // Returns { rows, next_cursor }.
+    list: async function (listOpts) {
+      listOpts = listOpts || {};
+      var limit = listOpts.limit == null ? 50 : listOpts.limit;
+      if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIST_LIMIT) {
+        throw new TypeError("customers.list: limit must be 1..." + MAX_LIST_LIMIT);
+      }
+      var cursorVals = null;
+      if (listOpts.cursor != null) {
+        if (typeof listOpts.cursor !== "string") {
+          throw new TypeError("customers.list: cursor must be an opaque string or null");
+        }
+        try {
+          var state = b.pagination.decodeCursor(listOpts.cursor, cursorSecret);
+          if (JSON.stringify(state.orderKey) !== JSON.stringify(CUSTOMERS_ORDER_KEY)) {
+            throw new TypeError("customers.list: cursor orderKey mismatch");
+          }
+          cursorVals = state.vals;
+        } catch (e) {
+          if (e instanceof TypeError) throw e;
+          throw new TypeError("customers.list: cursor — " + (e && e.message || "malformed"));
+        }
+      }
+      var sql, params;
+      if (cursorVals) {
+        sql = "SELECT id, email_hash, display_name, created_at, updated_at FROM customers " +
+              "WHERE (created_at < ?1 OR (created_at = ?1 AND id < ?2)) " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?3";
+        params = [cursorVals[0], cursorVals[1], limit];
+      } else {
+        sql = "SELECT id, email_hash, display_name, created_at, updated_at FROM customers " +
+              "ORDER BY created_at DESC, id DESC LIMIT ?1";
+        params = [limit];
+      }
+      var rows = (await query(sql, params)).rows;
+      var last = rows[rows.length - 1];
+      var next = null;
+      if (last && rows.length === limit) {
+        next = b.pagination.encodeCursor({
+          orderKey: CUSTOMERS_ORDER_KEY,
+          vals:     [last.created_at, last.id],
+          forward:  true,
+        }, cursorSecret);
+      }
+      return { rows: rows, next_cursor: next };
+    },
+
+    // Per-customer sign-in method counts WITHOUT an N+1: two bounded
+    // `IN (...)` aggregates over the passkey + oauth tables, returning
+    // { passkeys: {customer_id: count}, oauth: {customer_id: [provider,...]} }.
+    // Callers pass the (already-paginated) page's customer ids; an empty
+    // list short-circuits to empty maps so the SQL never sees `IN ()`.
+    signInMethodsByCustomer: async function (customerIds) {
+      if (!Array.isArray(customerIds)) {
+        throw new TypeError("customers.signInMethodsByCustomer: customerIds must be an array");
+      }
+      var passkeys = {}, oauth = {};
+      if (customerIds.length === 0) return { passkeys: passkeys, oauth: oauth };
+      var placeholders = customerIds.map(function (_id, i) { return "?" + (i + 1); }).join(", ");
+      var pk = (await query(
+        "SELECT customer_id, COUNT(*) AS n FROM customer_passkeys " +
+        "WHERE customer_id IN (" + placeholders + ") GROUP BY customer_id",
+        customerIds,
+      )).rows;
+      for (var i = 0; i < pk.length; i += 1) passkeys[pk[i].customer_id] = Number(pk[i].n);
+      var oa = (await query(
+        "SELECT customer_id, provider FROM customer_oauth_identities " +
+        "WHERE customer_id IN (" + placeholders + ") ORDER BY provider ASC",
+        customerIds,
+      )).rows;
+      for (var j = 0; j < oa.length; j += 1) {
+        if (!oauth[oa[j].customer_id]) oauth[oa[j].customer_id] = [];
+        oauth[oa[j].customer_id].push(oa[j].provider);
+      }
+      return { passkeys: passkeys, oauth: oauth };
+    },
+
     // ---- federated (OAuth / OIDC) sign-in -------------------------------
 
     // The customer linked to an external (provider, subject) identity, or

package/lib/giftcards.js

@@ -379,6 +379,46 @@ function create(opts) {
       return after.rows[0] || null;
     },
 
+    // Operator-facing list of issued cards — drives the admin
+    // gift-card ledger console. Never returns the code hash or the
+    // recipient hash (operators identify a card by its `code_hint` +
+    // issued date, not the bearer credential). Newest first. The
+    // optional `status` filter narrows to one lifecycle state; the
+    // `limit` caps the page (defaults to 100, max 500). This is a
+    // read-only projection — no balance math, just the snapshot
+    // columns the card row already carries.
+    list: async function (opts4) {
+      opts4 = opts4 || {};
+      var limit = opts4.limit == null ? 100 : opts4.limit;
+      if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 500) {
+        throw new TypeError("giftcards.list: limit must be an integer in [1, 500]");
+      }
+      var sql = "SELECT id, code_hint, currency, issued_minor, balance_minor, status, " +
+                "expires_at, created_at, updated_at FROM giftcards";
+      var params = [];
+      if (opts4.status != null) {
+        _status(opts4.status);
+        sql += " WHERE status = ?1";
+        params.push(opts4.status);
+      }
+      sql += " ORDER BY created_at DESC LIMIT ?" + (params.length + 1);
+      params.push(limit);
+      var r = await query(sql, params);
+      return r.rows;
+    },
+
+    // Fetch a single card by id for the admin detail view — same
+    // projection as `list` (no hash). Returns null on no match.
+    getById: async function (id) {
+      _uuid(id, "giftcard id");
+      var r = await query(
+        "SELECT id, code_hint, currency, issued_minor, balance_minor, status, " +
+        "expires_at, created_at, updated_at FROM giftcards WHERE id = ?1",
+        [id],
+      );
+      return r.rows.length ? r.rows[0] : null;
+    },
+
     listForCustomer: async function (customerId, opts3) {
       _uuid(customerId, "customer_id");
       opts3 = opts3 || {};

package/lib/order.js

@@ -472,6 +472,28 @@ function create(opts) {
       )).rows;
       return rows.length > 0;
     },
+
+    // Order count per customer for a bounded set of customer ids, in ONE
+    // grouped query — the operator console renders an order-count column
+    // across a page of customers without an N+1. Returns a
+    // { customer_id: count } map; customers with zero orders are simply
+    // absent (the caller defaults to 0). An empty input short-circuits so
+    // the SQL never sees `IN ()`.
+    countsByCustomer: async function (customerIds) {
+      if (!Array.isArray(customerIds)) {
+        throw new TypeError("order.countsByCustomer: customerIds must be an array");
+      }
+      var out = {};
+      if (customerIds.length === 0) return out;
+      var placeholders = customerIds.map(function (_id, i) { return "?" + (i + 1); }).join(", ");
+      var rows = (await query(
+        "SELECT customer_id, COUNT(*) AS n FROM orders " +
+        "WHERE customer_id IN (" + placeholders + ") GROUP BY customer_id",
+        customerIds,
+      )).rows;
+      for (var i = 0; i < rows.length; i += 1) out[rows[i].customer_id] = Number(rows[i].n);
+      return out;
+    },
   };
 }