@blamejs/blamejs-shop 0.0.44

package/lib/analytics.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * @module shop.analytics
+ * @title  Analytics — read-only aggregate queries over orders
+ *
+ * @intro
+ *   Pure data-layer module. Every method reads from the `orders` +
+ *   `order_lines` tables (written by the order primitive) and returns
+ *   a plain JSON-shaped aggregate. No mutations, no caching, no
+ *   external I/O beyond the injected `query` function.
+ *
+ *   Operator-supplied time windows are validated as epoch-millisecond
+ *   integers with `since < until` and `until - since ≤ 1 year` (the
+ *   primitive refuses to scan unbounded history in a single call —
+ *   operators paginate by stepping the window). Default window when
+ *   either bound is omitted: last 30 days from now.
+ *
+ *   Multi-currency note: every aggregate is grouped by currency so
+ *   operators with multi-currency catalogs get one row per currency
+ *   instead of an arithmetically-incoherent sum across exchange
+ *   rates. Single-currency operators see a one-row-per-currency
+ *   array of length 1.
+ *
+ *   v1 surface:
+ *
+ *     analytics.summary({ since, until })
+ *       → { total_orders, total_revenue_minor, currency, by_status: {...} }
+ *         (or array of {currency, total_orders, total_revenue_minor, by_status}
+ *          when the window spans multiple currencies)
+ *
+ *     analytics.revenueByDay({ since, until })
+ *       → [{ day, currency, revenue_minor }]   sorted by day ASC
+ *
+ *     analytics.topSKUs({ since, until, limit })
+ *       → [{ sku, units_sold, revenue_minor, currency }]
+ *         sorted by units_sold DESC
+ *
+ *     analytics.recentOrders({ limit })
+ *       → [{ id, status, grand_total_minor, currency, created_at }]
+ *         sorted by created_at DESC
+ *
+ *   Revenue counting policy: `cancelled` orders contribute zero
+ *   (excluded from the SUM). `refunded` orders SUBTRACT their
+ *   grand_total from revenue (operator preference — net revenue
+ *   reflects what reached the bank, not what was charged-then-
+ *   refunded). Every other status (pending / paid / fulfilling /
+ *   shipped / delivered) counts at face value because the operator
+ *   has either captured the funds or is committed to capturing them.
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+var ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+var DEFAULT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+// ---- validators ---------------------------------------------------------
+
+function _epochMs(n, label) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TypeError("analytics: " + label + " must be a non-negative integer (epoch ms)");
+  }
+}
+
+function _resolveWindow(opts) {
+  opts = opts || {};
+  var now = Date.now();
+  var since = opts.since == null ? (now - DEFAULT_WINDOW_MS) : opts.since;
+  var until = opts.until == null ? now                       : opts.until;
+  _epochMs(since, "since");
+  _epochMs(until, "until");
+  if (since >= until) {
+    throw new TypeError("analytics: since must be strictly less than until");
+  }
+  if ((until - since) > ONE_YEAR_MS) {
+    throw new TypeError("analytics: window (until - since) must be ≤ 1 year");
+  }
+  return { since: since, until: until };
+}
+
+function _limit(n, label, max) {
+  max = max || 100;
+  if (!Number.isInteger(n) || n < 1 || n > max) {
+    throw new TypeError("analytics: " + label + " must be an integer in [1, " + max + "]");
+  }
+}
+
+// ---- factory ------------------------------------------------------------
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+
+  // Status buckets we always surface, even when zero. Aligned with
+  // the order FSM's seven states so the operator dashboard renders a
+  // consistent row set regardless of which buckets the window
+  // touched.
+  var ALL_STATUSES = ["pending", "paid", "fulfilling", "shipped", "delivered", "refunded", "cancelled"];
+
+  return {
+    // Aggregate counts + revenue across the window, grouped by
+    // currency. Revenue policy: `cancelled` excluded entirely;
+    // `refunded` subtracts; every other status adds. Status buckets
+    // are zero-filled so the operator dashboard renders all seven
+    // columns even when the window only touched a few.
+    summary: async function (windowOpts) {
+      var w = _resolveWindow(windowOpts);
+
+      // Per-currency aggregate. Filter on `updated_at` so an order
+      // that paid+refunded in the same window contributes to the
+      // refund subtraction (status flipped on refund updates
+      // updated_at).
+      var r = await query(
+        "SELECT currency, status, COUNT(*) AS n, " +
+        "       SUM(grand_total_minor) AS gross_minor " +
+        "  FROM orders " +
+        " WHERE updated_at >= ?1 AND updated_at < ?2 " +
+        " GROUP BY currency, status",
+        [w.since, w.until],
+      );
+
+      // Fold the per-(currency, status) rows into the operator-
+      // facing shape. Use a map keyed by currency so we can return
+      // one row per currency, sorted alphabetically.
+      var byCurrency = new Map();
+      for (var i = 0; i < r.rows.length; i += 1) {
+        var row = r.rows[i];
+        var cur = row.currency;
+        if (!byCurrency.has(cur)) {
+          var byStatus = {};
+          for (var j = 0; j < ALL_STATUSES.length; j += 1) byStatus[ALL_STATUSES[j]] = 0;
+          byCurrency.set(cur, {
+            currency:            cur,
+            total_orders:        0,
+            total_revenue_minor: 0,
+            by_status:           byStatus,
+          });
+        }
+        var entry = byCurrency.get(cur);
+        var n     = Number(row.n) || 0;
+        var gross = Number(row.gross_minor) || 0;
+        entry.by_status[row.status] = n;
+        entry.total_orders += n;
+        if (row.status === "cancelled") {
+          // Excluded from revenue entirely.
+        } else if (row.status === "refunded") {
+          entry.total_revenue_minor -= gross;
+        } else {
+          entry.total_revenue_minor += gross;
+        }
+      }
+
+      var currencies = Array.from(byCurrency.keys()).sort();
+      if (currencies.length === 0) {
+        // Empty window — return a single zero row in USD so the
+        // dashboard has a shape to render. Operators can read the
+        // total_orders === 0 signal to know nothing landed.
+        var emptyByStatus = {};
+        for (var k = 0; k < ALL_STATUSES.length; k += 1) emptyByStatus[ALL_STATUSES[k]] = 0;
+        return {
+          currency:            "USD",
+          total_orders:        0,
+          total_revenue_minor: 0,
+          by_status:           emptyByStatus,
+        };
+      }
+      if (currencies.length === 1) {
+        return byCurrency.get(currencies[0]);
+      }
+      return currencies.map(function (c) { return byCurrency.get(c); });
+    },
+
+    // Revenue grouped by calendar day (UTC) within the window,
+    // grouped by currency. `cancelled` orders are filtered out;
+    // `refunded` orders contribute as a negative (subtract). Day
+    // bucket is `date(updated_at/1000, 'unixepoch')` so the bin is
+    // calendar-aligned and stable across timezones.
+    revenueByDay: async function (windowOpts) {
+      var w = _resolveWindow(windowOpts);
+      var r = await query(
+        "SELECT date(updated_at/1000, 'unixepoch') AS day, currency, " +
+        "       SUM(CASE WHEN status = 'refunded' THEN -grand_total_minor " +
+        "                ELSE grand_total_minor END) AS revenue_minor " +
+        "  FROM orders " +
+        " WHERE updated_at >= ?1 AND updated_at < ?2 " +
+        "   AND status != 'cancelled' " +
+        " GROUP BY day, currency " +
+        " ORDER BY day ASC, currency ASC",
+        [w.since, w.until],
+      );
+      return r.rows.map(function (row) {
+        return {
+          day:           row.day,
+          currency:      row.currency,
+          revenue_minor: Number(row.revenue_minor) || 0,
+        };
+      });
+    },
+
+    // Top-N SKUs by units_sold across the window. Join order_lines
+    // onto orders so we can filter by `orders.updated_at` (the line
+    // table has no own updated_at) AND exclude cancelled+refunded
+    // orders from the units count (those units never landed with
+    // the customer for revenue purposes).
+    topSKUs: async function (windowOpts) {
+      var w = _resolveWindow(windowOpts || {});
+      var limit = (windowOpts && windowOpts.limit) == null ? 10 : windowOpts.limit;
+      _limit(limit, "limit");
+      var r = await query(
+        "SELECT ol.sku AS sku, ol.unit_currency AS currency, " +
+        "       SUM(ol.qty) AS units_sold, " +
+        "       SUM(ol.line_total_minor) AS revenue_minor " +
+        "  FROM order_lines ol " +
+        "  JOIN orders o ON o.id = ol.order_id " +
+        " WHERE o.updated_at >= ?1 AND o.updated_at < ?2 " +
+        "   AND o.status NOT IN ('cancelled', 'refunded') " +
+        " GROUP BY ol.sku, ol.unit_currency " +
+        " ORDER BY units_sold DESC, ol.sku ASC " +
+        " LIMIT ?3",
+        [w.since, w.until, limit],
+      );
+      return r.rows.map(function (row) {
+        return {
+          sku:           row.sku,
+          units_sold:    Number(row.units_sold) || 0,
+          revenue_minor: Number(row.revenue_minor) || 0,
+          currency:      row.currency,
+        };
+      });
+    },
+
+    // Most-recent orders. No window — strictly most-recent-N. Used
+    // by the dashboard's "Recent activity" sidebar.
+    recentOrders: async function (recentOpts) {
+      var limit = (recentOpts && recentOpts.limit) == null ? 20 : recentOpts.limit;
+      _limit(limit, "limit");
+      var r = await query(
+        "SELECT id, status, grand_total_minor, currency, created_at " +
+        "  FROM orders " +
+        " ORDER BY created_at DESC " +
+        " LIMIT ?1",
+        [limit],
+      );
+      return r.rows.map(function (row) {
+        return {
+          id:                row.id,
+          status:            row.status,
+          grand_total_minor: Number(row.grand_total_minor) || 0,
+          currency:          row.currency,
+          created_at:        Number(row.created_at) || 0,
+        };
+      });
+    },
+  };
+}
+
+module.exports = {
+  create:            create,
+  ONE_YEAR_MS:       ONE_YEAR_MS,
+  DEFAULT_WINDOW_MS: DEFAULT_WINDOW_MS,
+};

package/lib/cart.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * @module shop.cart
+ * @title  Cart primitive — anonymous + authenticated shopping carts
+ *
+ * @intro
+ *   Persistent carts keyed by a `session_id` carried in a sealed
+ *   cookie (set by the storefront route layer). Anonymous shoppers
+ *   get a cart with `customer_id = NULL`; on customer login the
+ *   shop calls `cart.merge(anonId, customerCartId)` so the
+ *   shopper's working cart adopts the authenticated identity. The
+ *   cart row survives container restarts (D1, not session-memory).
+ *
+ *   Price snapshots: every line captures the current
+ *   `prices.current(variant, currency)` at add time and stores
+ *   `unit_amount_minor` + `unit_currency` on the line. A later
+ *   `catalog.prices.set()` doesn't silently re-price an in-flight
+ *   cart — the storefront can show "price changed" notices by
+ *   diffing the line snapshot against the current price.
+ *
+ *   Lifecycle status:
+ *     active     — the shopper's working cart (one per session_id)
+ *     abandoned  — expired or explicitly abandoned
+ *     converted  — checkout completed; immutable post-conversion
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+var CART_STATUSES   = Object.freeze(["active", "abandoned", "converted"]);
+var DEFAULT_TTL_MS  = 30 * 24 * 60 * 60 * 1000;   // 30 days
+var MAX_QTY         = 9999;
+var SESSION_ID_RE   = /^[A-Za-z0-9_-]{16,64}$/;   // shape-only; sealed-cookie origin
+var CURRENCY_RE     = /^[A-Z]{3}$/;
+
+// ---- validators ---------------------------------------------------------
+
+function _uuid(s, label) {
+  try { return _b().guardUuid.sanitize(s, { profile: "strict" }); }
+  catch (e) { throw new TypeError("cart: " + label + " — " + (e && e.message || "invalid UUID")); }
+}
+function _sessionId(s) {
+  if (typeof s !== "string" || !SESSION_ID_RE.test(s)) {
+    throw new TypeError("cart: session_id must be 16-64 chars of [A-Za-z0-9_-]");
+  }
+}
+function _currency(s) {
+  if (typeof s !== "string" || !CURRENCY_RE.test(s)) {
+    throw new TypeError("cart: currency must be a 3-letter ISO 4217 code (uppercase)");
+  }
+}
+function _qty(n) {
+  if (!Number.isInteger(n) || n <= 0 || n > MAX_QTY) {
+    throw new TypeError("cart: qty must be a positive integer ≤ " + MAX_QTY);
+  }
+}
+function _status(s) {
+  if (CART_STATUSES.indexOf(s) === -1) {
+    throw new TypeError("cart: status must be one of " + CART_STATUSES.join(", "));
+  }
+}
+
+function _now() { return Date.now(); }
+
+// ---- factory ------------------------------------------------------------
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+  // Optional catalog handle — when present, addLine looks up the
+  // current price for the variant + currency to snapshot onto the
+  // line. Callers may also pass an explicit price snapshot in
+  // `addLine(...)` for testing or for off-catalog items.
+  var catalog = opts.catalog || null;
+  var ttlMs   = opts.ttlMs   || DEFAULT_TTL_MS;
+
+  return {
+    create: async function (sessionId, input) {
+      _sessionId(sessionId);
+      input = input || {};
+      _currency(input.currency);
+      var id = _b().uuid.v7();
+      var ts = _now();
+      var expires = ts + ttlMs;
+      await query(
+        "INSERT INTO carts (id, session_id, customer_id, currency, status, created_at, updated_at, expires_at) " +
+        "VALUES (?1, ?2, NULL, ?3, 'active', ?4, ?4, ?5)",
+        [id, sessionId, input.currency, ts, expires],
+      );
+      return { id: id, session_id: sessionId, customer_id: null, currency: input.currency, status: "active", created_at: ts, updated_at: ts, expires_at: expires };
+    },
+
+    get: async function (id) {
+      _uuid(id, "cart id");
+      var r = await query("SELECT * FROM carts WHERE id = ?1", [id]);
+      return r.rows[0] || null;
+    },
+
+    bySession: async function (sessionId) {
+      _sessionId(sessionId);
+      // Active row per session is unique via the partial UNIQUE
+      // index in the migration, so LIMIT 1 is safe.
+      var r = await query(
+        "SELECT * FROM carts WHERE session_id = ?1 AND status = 'active' LIMIT 1",
+        [sessionId],
+      );
+      return r.rows[0] || null;
+    },
+
+    listLines: async function (cartId) {
+      _uuid(cartId, "cart_id");
+      var r = await query(
+        "SELECT * FROM cart_lines WHERE cart_id = ?1 ORDER BY added_at ASC",
+        [cartId],
+      );
+      return r.rows;
+    },
+
+    // Adds qty to an existing variant line if present, else inserts
+    // a new line. Price snapshot resolution order:
+    //   1. input.unit_amount_minor + input.unit_currency (explicit)
+    //   2. catalog.prices.current(variant_id, cart.currency) (implicit)
+    // If neither yields a price, the call throws.
+    addLine: async function (cartId, input) {
+      _uuid(cartId, "cart_id");
+      if (!input || typeof input !== "object") throw new TypeError("cart.addLine: input object required");
+      _uuid(input.variant_id, "variant_id");
+      _qty(input.qty);
+      // Pull the parent cart for currency + status + variant SKU.
+      var cartRow = (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
+      if (!cartRow) throw new TypeError("cart.addLine: cart " + cartId + " not found");
+      if (cartRow.status !== "active") throw new TypeError("cart.addLine: cart status is " + cartRow.status + ", cannot modify");
+      // Resolve price snapshot.
+      var unitAmount = null;
+      var unitCurrency = null;
+      if (input.unit_amount_minor != null && input.unit_currency != null) {
+        if (!Number.isInteger(input.unit_amount_minor) || input.unit_amount_minor < 0) {
+          throw new TypeError("cart.addLine: unit_amount_minor must be a non-negative integer");
+        }
+        if (typeof input.unit_currency !== "string" || !CURRENCY_RE.test(input.unit_currency)) {
+          throw new TypeError("cart.addLine: unit_currency must be a 3-letter ISO 4217 code");
+        }
+        unitAmount = input.unit_amount_minor;
+        unitCurrency = input.unit_currency;
+      } else {
+        if (!catalog) throw new Error("cart.addLine: no catalog handle and no explicit price snapshot — cannot resolve unit price");
+        var price = await catalog.prices.current(input.variant_id, cartRow.currency);
+        if (!price) throw new TypeError("cart.addLine: no current price for variant " + input.variant_id + " in " + cartRow.currency);
+        unitAmount = price.amount_minor;
+        unitCurrency = price.currency;
+      }
+      // Fetch variant SKU for the line snapshot.
+      var variantRow = (await query("SELECT sku FROM variants WHERE id = ?1", [input.variant_id])).rows[0];
+      if (!variantRow) throw new TypeError("cart.addLine: variant " + input.variant_id + " not found");
+      // Upsert: if a line for this (cart, variant) exists, bump qty.
+      var existing = (await query(
+        "SELECT * FROM cart_lines WHERE cart_id = ?1 AND variant_id = ?2 LIMIT 1",
+        [cartId, input.variant_id],
+      )).rows[0];
+      var ts = _now();
+      if (existing) {
+        var newQty = existing.qty + input.qty;
+        _qty(newQty);
+        await query(
+          "UPDATE cart_lines SET qty = ?1, updated_at = ?2 WHERE id = ?3",
+          [newQty, ts, existing.id],
+        );
+        await query("UPDATE carts SET updated_at = ?1 WHERE id = ?2", [ts, cartId]);
+        return Object.assign({}, existing, { qty: newQty, updated_at: ts });
+      }
+      var id = _b().uuid.v7();
+      await query(
+        "INSERT INTO cart_lines (id, cart_id, variant_id, sku, qty, unit_amount_minor, unit_currency, added_at, updated_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?8)",
+        [id, cartId, input.variant_id, variantRow.sku, input.qty, unitAmount, unitCurrency, ts],
+      );
+      await query("UPDATE carts SET updated_at = ?1 WHERE id = ?2", [ts, cartId]);
+      return { id: id, cart_id: cartId, variant_id: input.variant_id, sku: variantRow.sku, qty: input.qty, unit_amount_minor: unitAmount, unit_currency: unitCurrency, added_at: ts, updated_at: ts };
+    },
+
+    updateLine: async function (lineId, patch) {
+      _uuid(lineId, "line id");
+      if (!patch || typeof patch !== "object") throw new TypeError("cart.updateLine: patch object required");
+      if (patch.qty == null) throw new TypeError("cart.updateLine: qty is the only updatable field");
+      _qty(patch.qty);
+      var ts = _now();
+      var r = await query(
+        "UPDATE cart_lines SET qty = ?1, updated_at = ?2 WHERE id = ?3",
+        [patch.qty, ts, lineId],
+      );
+      if (r.rowCount === 0) return null;
+      var row = (await query("SELECT * FROM cart_lines WHERE id = ?1", [lineId])).rows[0];
+      await query("UPDATE carts SET updated_at = ?1 WHERE id = ?2", [ts, row.cart_id]);
+      return row;
+    },
+
+    removeLine: async function (lineId) {
+      _uuid(lineId, "line id");
+      var row = (await query("SELECT cart_id FROM cart_lines WHERE id = ?1", [lineId])).rows[0];
+      if (!row) return false;
+      await query("DELETE FROM cart_lines WHERE id = ?1", [lineId]);
+      await query("UPDATE carts SET updated_at = ?1 WHERE id = ?2", [_now(), row.cart_id]);
+      return true;
+    },
+
+    // Customer login flow: merge an anonymous cart's lines into the
+    // customer's existing active cart, then mark the anonymous cart
+    // abandoned. Lines that collide on variant_id sum qty. The
+    // returned cart is the surviving (customer's) cart.
+    merge: async function (fromCartId, toCartId) {
+      _uuid(fromCartId, "from cart_id");
+      _uuid(toCartId,   "to cart_id");
+      if (fromCartId === toCartId) throw new TypeError("cart.merge: fromCartId === toCartId");
+      var fromLines = (await query("SELECT * FROM cart_lines WHERE cart_id = ?1", [fromCartId])).rows;
+      var ts = _now();
+      for (var i = 0; i < fromLines.length; i += 1) {
+        var l = fromLines[i];
+        var existing = (await query(
+          "SELECT * FROM cart_lines WHERE cart_id = ?1 AND variant_id = ?2",
+          [toCartId, l.variant_id],
+        )).rows[0];
+        if (existing) {
+          var newQty = Math.min(existing.qty + l.qty, MAX_QTY);
+          await query(
+            "UPDATE cart_lines SET qty = ?1, updated_at = ?2 WHERE id = ?3",
+            [newQty, ts, existing.id],
+          );
+        } else {
+          var newId = _b().uuid.v7();
+          await query(
+            "INSERT INTO cart_lines (id, cart_id, variant_id, sku, qty, unit_amount_minor, unit_currency, added_at, updated_at) " +
+            "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?8)",
+            [newId, toCartId, l.variant_id, l.sku, l.qty, l.unit_amount_minor, l.unit_currency, ts],
+          );
+        }
+      }
+      await query("UPDATE carts SET status = 'abandoned', updated_at = ?1 WHERE id = ?2", [ts, fromCartId]);
+      await query("UPDATE carts SET updated_at = ?1 WHERE id = ?2", [ts, toCartId]);
+      return (await query("SELECT * FROM carts WHERE id = ?1", [toCartId])).rows[0];
+    },
+
+    setCustomer: async function (cartId, customerId) {
+      _uuid(cartId,    "cart_id");
+      _uuid(customerId, "customer_id");
+      var ts = _now();
+      var r = await query(
+        "UPDATE carts SET customer_id = ?1, updated_at = ?2 WHERE id = ?3",
+        [customerId, ts, cartId],
+      );
+      if (r.rowCount === 0) return null;
+      return (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
+    },
+
+    setStatus: async function (cartId, status) {
+      _uuid(cartId, "cart_id");
+      _status(status);
+      var ts = _now();
+      var r = await query(
+        "UPDATE carts SET status = ?1, updated_at = ?2 WHERE id = ?3",
+        [status, ts, cartId],
+      );
+      if (r.rowCount === 0) return null;
+      return (await query("SELECT * FROM carts WHERE id = ?1", [cartId])).rows[0];
+    },
+  };
+}
+
+module.exports = {
+  create:           create,
+  DEFAULT_TTL_MS:   DEFAULT_TTL_MS,
+  MAX_QTY:          MAX_QTY,
+  CART_STATUSES:    CART_STATUSES,
+};