@blamejs/blamejs-shop 0.0.70 → 0.0.72

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.72 (2026-05-22) — **`loyaltyEarnRules` primitive — per-action point earning rules.** `loyaltyEarnRules` defines HOW points are earned across eight trigger events: `per_dollar_spent`, `per_purchase`, `per_review`, `per_referral_redeemed`, `birthday`, `signup_bonus`, `first_purchase`, `abandoned_cart_recovered`. Distinct from the existing `loyalty` (ledger) and `tierBenefits` (perks) primitives. **Added:** *`loyaltyEarnRules` primitive — per-action point earning rules with optional per-event caps* — `bShop.loyaltyEarnRules.create({ query?, loyalty? })` returns `{ defineRule, getRule, listRules, updateRule, archiveRule, evaluateForEvent, awardForEvent, metricsForRule, applyBatch }`. Triggers: `per_dollar_spent / per_purchase / per_review / per_referral_redeemed / birthday / signup_bonus / first_purchase / abandoned_cart_recovered`. `evaluateForEvent` returns the points calculation (multiply + floor + zero-floor); `awardForEvent` composes the injected `loyalty.earn` handle and rolls back the audit row on ledger failure. Per-event cap (`max_per_event`) clips runaway awards. `customer_status_in` allowlist filters which customer tiers a rule applies to. UNIQUE(`rule_slug`, `customer_id`, `trigger_event_ref`) dedups re-submitted events. `applyBatch` runs multiple awards atomically with partial-failure reporting. Migration `0163_loyalty_earn_rules.sql`.
+
+- v0.0.71 (2026-05-22) — **`splitShipments` — monotonic `proposed_at` so back-to-back plans sort newest-first.** Single-fix release. `splitShipments.planSplit` calls landing in the same wall-clock millisecond now get strictly-increasing `proposed_at` stamps via a process-local monotonic clock. Without the fix, `splitsForOrder(order_id)` returned the rows in nondeterministic order under burst-write conditions — CI runners hit the collision more reliably than local clocks. **Fixed:** *`splitShipments` — process-local monotonic `_now` so consecutive `planSplit` calls sort deterministically* — Two `planSplit` calls inside the same millisecond shared a `proposed_at` value, and the secondary tiebreaker (UUID v7 id) was scrambled by the intra-ms random suffix. The primitive now bumps `_now()` by 1ms when `Date.now()` returns a stale value, so `splitsForOrder` reliably returns newest-first under any insert burstiness. Same fix pattern as `orderNotes` / `productBulkOps` / `cookieConsent` / `liveChat` / `sms-dispatcher` / others — applies cleanly to any primitive where `Date.now()` precision drives sort order.
+
 - v0.0.70 (2026-05-22) — **Six new primitives: click and collect, customer surveys, email templates, knowledge base, pixel events, sitemap generator.** Six primitives ship in one release covering store pickup (`clickAndCollect`), customer feedback (`customerSurveys`), operator-editable transactional email templates (`emailTemplates`), self-serve help center (`knowledgeBase`), server-side conversion pixel tracking (`pixelEvents`), and storefront sitemap generation (`sitemapGenerator`). **Added:** *`clickAndCollect` primitive — buy-online-pickup-in-store workflow* — `bShop.clickAndCollect.create({ query?, order?, inventoryLocations?, notifications? })` returns `{ definePickupLocation, availableLocations, scheduleAtLocation, markReadyForPickup, markPickedUp, markNoShow, pickupsForLocation, customerSchedules }`. Five-state FSM: scheduled → ready → picked_up + no_show + cancelled terminals. Capacity gated on one-hour buckets; lead-time gate per location. `markReadyForPickup` enqueues a pickup-ready notification through the injected handle (drop-silent on failure so a notifications outage can't roll back the hold shelf). `markPickedUp` drives the parent order to delivered via `order.transition(id, 'mark_delivered')` (swallows fsm/illegal-transition for idempotency). Signature hashed via `namespaceHash('click-and-collect-signature', raw)`. Migration `0126_click_and_collect.sql`. · *`customerSurveys` primitive — post-purchase NPS / CSAT / CES surveys* — `bShop.customerSurveys.create({ query? })` returns `{ defineSurvey, getSurvey, archiveSurvey, issueInvitation, getInvitation, invitationsForCustomer, submitResponse, responsesForSurvey, rollup, closeInvitation, cleanupExpired }`. Kinds: nps / csat / ces / custom. Trigger events: after_delivery / after_support_close / after_refund / manual. NPS / CSAT / CES enforce primary-question shape (`max === 10 / 5 / 7` respectively). NPS rollup = `round(%promoters - %detractors)`, CSAT = top-2-box positive_pct + mean, CES = mean + agree_pct. Invitation tokens 32-byte base64url plaintext returned exactly once, stored only as SHA3-512 namespaceHash. Migration `0128_customer_surveys.sql`. · *`emailTemplates` primitive — operator-editable transactional email templates* — `bShop.emailTemplates.create({ query? })` returns `{ defineTemplate, getTemplate, listTemplates, updateTemplate, publishVersion, archiveTemplate, renderTemplate, versionsFor, validateVariables }`. Closed 11-kind enum (order_confirmation / order_shipped / order_delivered / order_refunded / password_reset / account_verification / abandoned_cart / wishlist_discount / review_request / welcome / generic). `{{var_name}}` substitution composes `b.template.escapeHtml`; `{{var_name|raw}}` slots require schema vouching at definition time. Locale fallback to `en`. Migration `0125_email_templates.sql`. · *`knowledgeBase` primitive — self-serve customer help center with search ranking* — `bShop.knowledgeBase.create({ query?, defaultLocale?, cursorSecret? })` returns `{ defineArticle, getArticle, listArticles, updateArticle, publishArticle, unpublishArticle, archiveArticle, recordView, recordVote, voteAggregateForArticle, popularArticles, searchSuggest }`. Locale fallback chain. `searchSuggest` ranks by title 3 + tag 2 + body 1 weighted score; archived + unpublished excluded. Vote dedup at the `UNIQUE(slug, session_id_hash)` index. In-process markdown subset composes `b.template.escapeHtml` + `b.safeUrl.parse` (https-only + /-rooted internal). Session ids hashed via `namespaceHash` under `kb-view-session` / `kb-vote-session`. Migration `0162_knowledge_base.sql`. · *`pixelEvents` primitive — server-side conversion-tracking pixel / event API* — `bShop.pixelEvents.create({ query? })` returns `{ registerProvider, recordEvent, dispatchTick, markDispatched, markFailed, eventsForOrder, dispatchedInPeriod, failedEvents, metricsForProvider }`. Provider enum: meta_capi / google_ec / tiktok_events / pinterest_capi / snap_capi. Event names: purchase / add_to_cart / view_content / lead / complete_registration / search. Customer email + phone SHA-256-hashed (per provider spec — NOT namespaceHash; ad platforms accept SHA-256 of the normalised value). Five-step retry back-off on transient failures. Migration `0123_pixel_events.sql`. · *`sitemapGenerator` primitive — storefront sitemap.xml + sitemap-index.xml* — `bShop.sitemapGenerator.create({ query?, catalog?, collections?, storefrontPages?, custom? })` returns `{ defineSection, sections, archiveSection, validateOriginUrl, generate, recordGeneration, lastGeneration }`. Splits at 50,000 URLs or 50 MB serialized per chunk (whichever hits first). Path percent-encoding + XML escape on every emitted `<loc>`. Per-section sources: product / collection / storefront_page / custom. `validateOriginUrl` gates via `b.safeUrl` (https-only). Migration `0130_sitemap_generator.sql`.
 
 - v0.0.69 (2026-05-22) — **Twelve new primitives + return-labels CI smoke fix.** Twelve primitives ship in one release plus a CI smoke fix that unblocks the npm publish workflow. The smoke fix bumps a too-tight 50ms `waitUntil` in `return-labels.test.js` to 5s so it survives the GitHub Actions runner's slower scheduling. New primitives cover orders (order ratings, packing slips, print queue), customers (wishlist sharing, customer activity feed, push notifications, order escalation), inventory (allocations, drop-ship forwarding, auto-replenishment), operator tooling (operator roles, clickstream events, damage photos). **Added:** *`orderRatings` primitive — per-order rating for shipping / packaging / recommend* — `bShop.orderRatings.create({ query? })` returns `{ submitRating, getRating, ratingsForCustomer, aggregateForPeriod, flagComment, responseToCustomer, topPositiveRatings, topNegativeRatings }`. Ratings 1..5 across three dimensions. UNIQUE(order_id) so one rating per order. Comment + operator response HTML-escaped on render. flagComment moderates abuse; responseToCustomer is the operator's public reply. Migration `0151_order_ratings.sql`. · *`wishlistSharing` primitive — share-a-wishlist links + group wishlists* — `bShop.wishlistSharing.create({ query?, wishlist? })` returns `{ createShareLink, revokeShareLink, viewShared, recordView, createGroupWishlist, joinGroupWishlist, leaveGroupWishlist, groupWishlistsForCustomer, listSharesForOwner, listGroupMembers }`. Tokens are 32-byte base64url plaintext returned once, hashed at rest via `namespaceHash` under per-domain namespaces. Privacy enum: public / unlisted / friends_only. Group wishlists let multiple customers co-author a list. Migration `0150_wishlist_sharing.sql`. · *`inventoryAllocations` primitive — soft-reserve holds for in-progress carts* — `bShop.inventoryAllocations.create({ query?, inventoryLocations? })` returns `{ holdForCart, releaseHold, releaseAllForCart, commitHold, extendHold, availableForSku, holdsForCart, cleanupExpiredHolds, metricsForSku }`. Holds prevent overselling during checkout. `availableForSku` returns committed - on_hold. `commitHold` composes `inventoryLocations.adjustStock` to commit the reservation as a real stock movement. TTL-bound; `cleanupExpiredHolds` walks expired rows and frees the inventory. Migration `0152_inventory_allocations.sql`. · *`dropshipForwarding` primitive — drop-ship vendor order-forwarding flow* — `bShop.dropshipForwarding.create({ query?, vendors?, orderTracking? })` returns `{ bindSkuToVendor, forwardOrder, markVendorAccepted, markVendorShipped, markVendorDelivered, markVendorFailed, markVendorReturned, getForwarding, forwardingsForOrder, pendingForwardings, metricsForVendor }`. Six-state FSM: queued / accepted / shipped / delivered / failed / returned. Composes `b.fsm` for transition validation. `forwardOrder` writes per-vendor forwarding rows. Migration `0154_dropship_forwarding.sql`. · *`damagePhotos` primitive — image attachments for damage / quality-control events* — `bShop.damagePhotos.create({ query? })` returns `{ recordPhoto, getPhoto, photosForSubject, archivePhoto, replacePhoto, metricsForKind, findDuplicatesBySha }`. Subject kinds: writeoff / return / quality_check / damaged_receipt / customer_complaint. SHA3-512 + size + content_type per upload. content_type allowlist: image/jpeg, image/png, image/webp, image/heic. `findDuplicatesBySha` returns prior uploads with the same digest (fraud detection signal). Migration `0159_damage_photos.sql`. · *`pushNotifications` primitive — APNs / FCM / Web Push outbound* — `bShop.pushNotifications.create({ query? })` returns `{ registerProvider, registerDevice, revokeDevice, recordOptIn, recordOptOut, isOptedIn, enqueueNotification, markDelivered, markFailed, dispatchTick, notificationsForCustomer, devicesForCustomer, metricsForProvider }`. Marketing channel uses opt-IN; transactional + alert use opt-OUT. Device class / provider kind compatibility enforced (ios↔apns, android↔fcm, web↔web_push, desktop↔fcm|web_push). Retry budget 5 with [1m, 5m, 30m, 2h, 12h] back-off. Migration `0148_push_notifications.sql`. · *`autoReplenish` primitive — auto-PO when reorder thresholds fire* — `bShop.autoReplenish.create({ query?, reorderThresholds?, purchaseOrders?, vendors? })` returns `{ definePolicy, tickReplenishment, getPolicy, listPolicies, archivePolicy, updatePolicy, replenishmentHistory, markPolicyTriggered }`. `tickReplenishment` finds reorder candidates via `reorderThresholds.scanAll` + groups by vendor + submits PO via `purchaseOrders.createDraft + submitToVendor`. Per-policy gates: min/max PO value, max_concurrent_open_pos cap, vendor-archived skip. Schedule: hourly / daily / weekly. Migration `0155_auto_replenish.sql`. · *`operatorRoles` primitive — staff-side RBAC* — `bShop.operatorRoles.create({ query?, operatorAuditLog? })` returns `{ defineRole, assignRoleToOperator, revokeRoleFromOperator, rolesForOperator, operatorsWithRole, hasPermission, listRoles, updateRole, archiveRole, listPermissions, permissionUsageLog, recordPermissionUse }`. 15-permission closed allow-list (orders.* / customers.* / catalog.* / inventory.write / vendors.manage / settings.write / billing.view / reports.read / users.* / support.handle). Multi-role union; expires_at honored. Migration `0157_operator_roles.sql`. · *`clickstream` primitive — server-side storefront analytics events* — `bShop.clickstream.create({ query? })` returns `{ recordPageView, recordEvent, sessionPath, topPages, topClicks, funnelAnalysis, bouncerate, dwellByPage, cleanupOlderThan }`. Tracks page views + clicks + form submits + scroll depth + dwell without third-party scripts. Event kinds: click / form_submit / form_abandon / video_play / video_complete / scroll_depth / dwell. Query strings + URL fragments stripped at write so PII in query params never reaches the table. Drop-silent on bad input. Migration `0161_clickstream.sql`. · *`customerActivity` primitive — per-customer aggregated activity timeline* — `bShop.customerActivity.create({ query?, cursorSecret?, order?, wishlist?, loyalty?, supportTickets?, reviews? })` returns `{ forCustomer, recentActivity, summarize, lastActivityAt, inactiveCustomers, purgeStaleCache }`. Aggregates events from order / wishlist / loyalty / support / reviews into one feed for the operator's customer-detail page. Missing peers skipped silently. `summarize` returns 30/90/365-day kind counts with cache hit/miss. Migration `0153_customer_activity_cache.sql`. · *`packingSlips` primitive — warehouse packing-slip rendering + print queue* — `bShop.packingSlips.create({ query?, order, giftOptions? })` returns `{ renderHtml, renderPdfPayload, recordPrint, printsForOrder, enqueueForLocation, dequeueForLocation, bulkRenderForLocation }`. Inlined Code-128 barcode SVG renderer (no external library dependency). HTML-escapes every operator + customer field. Gift options: hide_prices strips price/total columns; gift_message + recipient_name rendered inert against hostile input. Composite PK on the queue table as idempotency guard. Migration `0149_packing_slips.sql`. · *`printQueue` primitive — warehouse print job queue scheduler* — `bShop.printQueue.create({ query? })` returns `{ enqueueJob, claimJob, markComplete, markFailed, cancelJob, getJob, jobsForStation, pendingByKind, cleanupCompleted, stationActivity, dailyMetrics }`. Job kinds: packing_slip / shipping_label / invoice / packing_label / return_label / pickup_slip. `claimJob` returns next queued job (FIFO with priority tiebreak), flips `in_progress`. station_filter restricts which stations can claim a job. Retry budget on markFailed. Migration `0158_print_queue.sql`. **Fixed:** *`return-labels.test.js` — bumped a 50ms `waitUntil` timeout to 5s for CI runner scheduling* — GitHub Actions Ubuntu / macOS runners under contention sometimes need more than 50ms between `Date.now()` ticks to clear a monotonic-clock guard. The two `waitUntil` calls in `_listQueries` now use a 5000ms budget so the CI smoke gate doesn't drop the npm publish workflow. Local runs were always fast enough; only CI saw the failure.

package/lib/index.js

@@ -200,4 +200,5 @@ module.exports = {
   knowledgeBase:         require("./knowledge-base"),
   pixelEvents:           require("./pixel-events"),
   sitemapGenerator:      require("./sitemap-generator"),
+  loyaltyEarnRules:      require("./loyalty-earn-rules"),
 };

package/lib/loyalty-earn-rules.js

@@ -0,0 +1,786 @@
+"use strict";
+/**
+ * @module shop.loyaltyEarnRules
+ * @title  Loyalty earn rules — per-action point-earning configuration
+ *
+ * @intro
+ *   Distinct from `loyalty` (which records the running points balance
+ *   and the audited transaction trail) and from `tierBenefits` (which
+ *   configures perks unlocked at each tier). This primitive defines
+ *   HOW points are earned — operators publish rules keyed by an event
+ *   `trigger` and the application calls `awardForEvent` at the
+ *   appropriate lifecycle moment.
+ *
+ *   Triggers (closed enum):
+ *     - per_dollar_spent          — N points per $1 of order subtotal
+ *     - per_purchase              — flat N points per completed order
+ *     - per_review                — N points per review submitted
+ *     - per_referral_redeemed     — N points per referred friend's
+ *                                   first order completing
+ *     - birthday                  — N points on the customer's birthday
+ *     - signup_bonus              — N points on account creation
+ *     - first_purchase            — N points on the first completed order
+ *     - abandoned_cart_recovered  — N points when a recovered cart converts
+ *
+ *   Composition:
+ *
+ *     var rules = bShop.loyaltyEarnRules.create({
+ *       query:    q,
+ *       loyalty:  loy,    // optional — awardForEvent composes loy.earn
+ *     });
+ *
+ *     await rules.defineRule({
+ *       slug:                "spend-1pt-per-dollar",
+ *       trigger:             "per_dollar_spent",
+ *       points_per_unit:     1,
+ *       max_per_event:       5000,
+ *       customer_status_in:  ["active", "vip"],
+ *     });
+ *
+ *     await rules.awardForEvent({
+ *       trigger:           "per_dollar_spent",
+ *       customer_id:       customerId,
+ *       dollars_spent:     42,
+ *       trigger_event_ref: "order:" + orderId,
+ *       customer_status:   "active",
+ *     });
+ *
+ *   `evaluateForEvent` is the dry-run companion to `awardForEvent`. It
+ *   returns the same `{ points, reason }` shape but does NOT touch the
+ *   audit log or the loyalty ledger — operators preview an award at
+ *   checkout (so the customer sees "you'll earn 42 points") without
+ *   committing.
+ *
+ *   `applyBatch` runs multiple awards in a single call. Each (rule,
+ *   event) pair flows through the same validate -> evaluate -> award
+ *   path; per-pair failures are collected into a `failed[]` array
+ *   rather than failing the whole batch (operators commonly run nightly
+ *   sweeps that span thousands of events — a malformed row shouldn't
+ *   block the rest).
+ *
+ *   Per-event dedup: the (rule_slug, customer_id, trigger_event_ref)
+ *   UNIQUE on `loyalty_earn_log` collapses retried inserts onto one
+ *   row so a webhook retry doesn't double-award.
+ *
+ *   Composes:
+ *     - `b.uuid.v7`     — audit-log row ids (lexicographic + monotonic)
+ *     - `b.guardUuid`   — strict UUID gate on every customer_id
+ *     - `loyalty`       — optional; when wired, `awardForEvent` composes
+ *                         `loyalty.earn` so the points land in the
+ *                         customer's balance + the loyalty audit trail
+ *                         in one call.
+ *
+ *   Storage: `migrations-d1/0163_loyalty_earn_rules.sql` —
+ *     `loyalty_earn_rules` + `loyalty_earn_log`.
+ *
+ * @primitive loyaltyEarnRules
+ * @related   loyalty, tierBenefits, b.uuid.v7, b.guardUuid
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+// ---- constants ----------------------------------------------------------
+
+var TRIGGERS = Object.freeze([
+  "per_dollar_spent",
+  "per_purchase",
+  "per_review",
+  "per_referral_redeemed",
+  "birthday",
+  "signup_bonus",
+  "first_purchase",
+  "abandoned_cart_recovered",
+]);
+
+// Triggers that scale points by a caller-supplied unit count.
+// per_dollar_spent multiplies points_per_unit by the order's dollar
+// subtotal; every other trigger awards a flat points_per_unit.
+var UNIT_TRIGGERS = Object.freeze({
+  per_dollar_spent: "dollars_spent",
+});
+
+var SLUG_RE              = /^[a-z0-9](?:[a-z0-9-]{0,98}[a-z0-9])?$/;
+var TRIGGER_REF_RE       = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+var STATUS_RE            = /^[a-z][a-z0-9_-]{0,31}$/;
+
+var MAX_STATUS_LIST      = 16;
+var MAX_POINTS_PER_UNIT  = 1000000;       // 1M cap on a single multiplier
+var MAX_MAX_PER_EVENT    = 1000000000;    // 1B cap on a per-event ceiling
+
+var DEFAULT_LIST_LIMIT   = 50;
+var MAX_LIST_LIMIT       = 500;
+
+// ---- monotonic clock ----------------------------------------------------
+//
+// Awards land in `loyalty_earn_log` keyed by `occurred_at`. The metrics
+// rollup window scans by (rule_slug, occurred_at >= from AND <= to);
+// two awards in the same millisecond would tie on the sort key and the
+// `applyBatch` path issues many awards in a tight loop. The strict-
+// monotonic clock guarantees distinct timestamps per call so ordering
+// is deterministic without a tiebreaker column.
+
+var _lastTs = 0;
+function _now() {
+  var t = Date.now();
+  if (t <= _lastTs) { t = _lastTs + 1; }
+  _lastTs = t;
+  return t;
+}
+
+// ---- validators ---------------------------------------------------------
+
+function _slug(s, label) {
+  if (typeof s !== "string" || !SLUG_RE.test(s)) {
+    throw new TypeError("loyaltyEarnRules: " + (label || "slug") +
+                        " must be lowercase alnum + dash, no leading/trailing dash, 1..100 chars");
+  }
+  return s;
+}
+
+function _trigger(s) {
+  if (typeof s !== "string" || TRIGGERS.indexOf(s) < 0) {
+    throw new TypeError("loyaltyEarnRules: trigger must be one of " + TRIGGERS.join(", "));
+  }
+  return s;
+}
+
+function _pointsPerUnit(n) {
+  if (typeof n !== "number" || !Number.isInteger(n) || n <= 0 || n > MAX_POINTS_PER_UNIT) {
+    throw new TypeError("loyaltyEarnRules: points_per_unit must be a positive integer <= " +
+                        MAX_POINTS_PER_UNIT);
+  }
+  return n;
+}
+
+function _maxPerEvent(n) {
+  if (n == null) return null;
+  if (typeof n !== "number" || !Number.isInteger(n) || n <= 0 || n > MAX_MAX_PER_EVENT) {
+    throw new TypeError("loyaltyEarnRules: max_per_event must be a positive integer <= " +
+                        MAX_MAX_PER_EVENT + " (or omitted)");
+  }
+  return n;
+}
+
+function _customerStatusIn(arr) {
+  if (arr == null) return null;
+  if (!Array.isArray(arr)) {
+    throw new TypeError("loyaltyEarnRules: customer_status_in must be an array of status strings");
+  }
+  if (arr.length === 0) {
+    throw new TypeError("loyaltyEarnRules: customer_status_in must be non-empty when provided");
+  }
+  if (arr.length > MAX_STATUS_LIST) {
+    throw new TypeError("loyaltyEarnRules: customer_status_in must contain <= " +
+                        MAX_STATUS_LIST + " entries");
+  }
+  var seen = Object.create(null);
+  var out = [];
+  for (var i = 0; i < arr.length; i += 1) {
+    var s = arr[i];
+    if (typeof s !== "string" || !STATUS_RE.test(s)) {
+      throw new TypeError("loyaltyEarnRules: customer_status_in[" + i +
+                          "] must be lowercase alnum / underscore / dash, 1..32 chars");
+    }
+    if (seen[s]) {
+      throw new TypeError("loyaltyEarnRules: customer_status_in[" + i +
+                          "] duplicates a previous entry");
+    }
+    seen[s] = true;
+    out.push(s);
+  }
+  return out;
+}
+
+function _uuid(s, label) {
+  try { return _b().guardUuid.sanitize(s, { profile: "strict" }); }
+  catch (e) { throw new TypeError("loyaltyEarnRules: " + label + " — " + (e && e.message || "invalid UUID")); }
+}
+
+function _triggerEventRef(s) {
+  if (typeof s !== "string" || !TRIGGER_REF_RE.test(s)) {
+    throw new TypeError("loyaltyEarnRules: trigger_event_ref must match /^[A-Za-z0-9][A-Za-z0-9._:-]*$/ (1..128 chars)");
+  }
+  return s;
+}
+
+function _statusOpt(s) {
+  if (s == null) return null;
+  if (typeof s !== "string" || !STATUS_RE.test(s)) {
+    throw new TypeError("loyaltyEarnRules: customer_status must be lowercase alnum / underscore / dash, 1..32 chars");
+  }
+  return s;
+}
+
+function _epochOpt(n, label) {
+  if (n == null) return null;
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TypeError("loyaltyEarnRules: " + label + " must be a non-negative integer (ms epoch) or null");
+  }
+  return n;
+}
+
+function _limit(n) {
+  if (n == null) return DEFAULT_LIST_LIMIT;
+  if (!Number.isInteger(n) || n <= 0 || n > MAX_LIST_LIMIT) {
+    throw new TypeError("loyaltyEarnRules: limit must be an integer in [1, " + MAX_LIST_LIMIT + "]");
+  }
+  return n;
+}
+
+function _bool(v, label) {
+  if (typeof v !== "boolean") {
+    throw new TypeError("loyaltyEarnRules: " + label + " must be a boolean");
+  }
+  return v;
+}
+
+// Pure compute — given a rule row + an event context, return the
+// (points, reason) tuple WITHOUT touching storage. Exported via
+// evaluateForEvent + reused inside awardForEvent so the math is
+// single-sourced.
+function _computePoints(rule, ctx) {
+  var unitField = UNIT_TRIGGERS[rule.trigger];
+  var units = 1;
+  if (unitField != null) {
+    var raw = ctx[unitField];
+    if (typeof raw !== "number" || !isFinite(raw) || raw < 0) {
+      return { points: 0, reason: unitField + " must be a non-negative finite number for trigger " + rule.trigger };
+    }
+    units = Math.floor(raw);
+    if (units <= 0) {
+      return { points: 0, reason: unitField + " floored to zero" };
+    }
+  }
+  var raw_points = rule.points_per_unit * units;
+  if (rule.max_per_event != null && raw_points > rule.max_per_event) {
+    return {
+      points:  rule.max_per_event,
+      reason:  "capped at max_per_event=" + rule.max_per_event +
+               " (uncapped would have been " + raw_points + ")",
+      capped:  true,
+    };
+  }
+  return { points: raw_points, reason: "trigger=" + rule.trigger + " units=" + units, capped: false };
+}
+
+// ---- factory ------------------------------------------------------------
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+  // Optional loyalty handle — when wired, awardForEvent calls
+  // loyalty.earn so the points land in the customer's balance + the
+  // loyalty transaction audit trail in one go. Absent, the primitive
+  // still writes the loyalty_earn_log breadcrumb but the operator is
+  // responsible for posting to the ledger separately.
+  var loyaltyHandle = opts.loyalty || null;
+
+  // ---- internal helpers -----------------------------------------------
+
+  function _decodeRule(row) {
+    if (!row) return null;
+    var statusList = null;
+    if (row.customer_status_in_json) {
+      try { statusList = JSON.parse(row.customer_status_in_json); }
+      catch (_e) { statusList = null; }
+    }
+    return {
+      slug:                 row.slug,
+      trigger:              row.trigger,
+      points_per_unit:      Number(row.points_per_unit),
+      max_per_event:        row.max_per_event == null ? null : Number(row.max_per_event),
+      customer_status_in:   statusList,
+      active:               Number(row.active) === 1,
+      archived_at:          row.archived_at == null ? null : Number(row.archived_at),
+      created_at:           Number(row.created_at),
+      updated_at:           Number(row.updated_at),
+    };
+  }
+
+  async function _ruleRow(slug) {
+    var r = await query("SELECT * FROM loyalty_earn_rules WHERE slug = ?1", [slug]);
+    return r.rows[0] || null;
+  }
+
+  // Status gate. If the rule restricts to a status list, the event's
+  // customer_status MUST appear in the list. NULL list means no
+  // restriction. Returns null when the event passes, or a reason
+  // string when it's filtered out.
+  function _statusFilter(rule, ctx) {
+    if (rule.customer_status_in == null) return null;
+    var status = ctx.customer_status;
+    if (status == null || rule.customer_status_in.indexOf(status) < 0) {
+      return "customer_status=" + JSON.stringify(status) +
+             " not in [" + rule.customer_status_in.join(", ") + "]";
+    }
+    return null;
+  }
+
+  // ---- defineRule -----------------------------------------------------
+
+  async function defineRule(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.defineRule: input object required");
+    }
+    var slug             = _slug(input.slug, "slug");
+    var trigger          = _trigger(input.trigger);
+    var pointsPerUnit    = _pointsPerUnit(input.points_per_unit);
+    var maxPerEvent      = _maxPerEvent(input.max_per_event);
+    var customerStatusIn = _customerStatusIn(input.customer_status_in);
+    var active           = input.active == null ? true : _bool(input.active, "active");
+
+    var existing = await _ruleRow(slug);
+    var ts = _now();
+    if (existing) {
+      if (existing.archived_at != null) {
+        throw new TypeError("loyaltyEarnRules.defineRule: rule " + JSON.stringify(slug) + " is archived");
+      }
+      await query(
+        "UPDATE loyalty_earn_rules " +
+        "SET trigger = ?1, points_per_unit = ?2, max_per_event = ?3, " +
+        "customer_status_in_json = ?4, active = ?5, updated_at = ?6 " +
+        "WHERE slug = ?7",
+        [trigger, pointsPerUnit, maxPerEvent,
+         customerStatusIn == null ? null : JSON.stringify(customerStatusIn),
+         active ? 1 : 0, ts, slug],
+      );
+    } else {
+      await query(
+        "INSERT INTO loyalty_earn_rules " +
+        "(slug, trigger, points_per_unit, max_per_event, customer_status_in_json, " +
+        " active, archived_at, created_at, updated_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6, NULL, ?7, ?7)",
+        [slug, trigger, pointsPerUnit, maxPerEvent,
+         customerStatusIn == null ? null : JSON.stringify(customerStatusIn),
+         active ? 1 : 0, ts],
+      );
+    }
+    return _decodeRule(await _ruleRow(slug));
+  }
+
+  // ---- getRule / listRules --------------------------------------------
+
+  async function getRule(slug) {
+    _slug(slug, "slug");
+    return _decodeRule(await _ruleRow(slug));
+  }
+
+  async function listRules(listOpts) {
+    listOpts = listOpts || {};
+    var activeOnly = listOpts.active_only == null ? false : _bool(listOpts.active_only, "active_only");
+    var limit      = _limit(listOpts.limit);
+    var sql    = "SELECT * FROM loyalty_earn_rules";
+    var params = [];
+    var idx    = 1;
+    var where  = [];
+    if (activeOnly) {
+      where.push("active = ?" + idx); params.push(1); idx += 1;
+      where.push("archived_at IS NULL");
+    }
+    if (listOpts.trigger != null) {
+      where.push("trigger = ?" + idx); params.push(_trigger(listOpts.trigger)); idx += 1;
+    }
+    if (where.length) sql += " WHERE " + where.join(" AND ");
+    sql += " ORDER BY slug ASC LIMIT ?" + idx;
+    params.push(limit);
+    var r = await query(sql, params);
+    var out = [];
+    for (var i = 0; i < r.rows.length; i += 1) out.push(_decodeRule(r.rows[i]));
+    return out;
+  }
+
+  // ---- updateRule -----------------------------------------------------
+
+  async function updateRule(slug, patch) {
+    _slug(slug, "slug");
+    if (!patch || typeof patch !== "object") {
+      throw new TypeError("loyaltyEarnRules.updateRule: patch object required");
+    }
+    var existing = await _ruleRow(slug);
+    if (!existing) return null;
+    if (existing.archived_at != null) {
+      throw new TypeError("loyaltyEarnRules.updateRule: rule " + JSON.stringify(slug) + " is archived");
+    }
+    var decoded = _decodeRule(existing);
+
+    var nextPoints = decoded.points_per_unit;
+    if (Object.prototype.hasOwnProperty.call(patch, "points_per_unit")) {
+      nextPoints = _pointsPerUnit(patch.points_per_unit);
+    }
+    var nextMax = decoded.max_per_event;
+    if (Object.prototype.hasOwnProperty.call(patch, "max_per_event")) {
+      nextMax = _maxPerEvent(patch.max_per_event);
+    }
+    var nextStatus = decoded.customer_status_in;
+    if (Object.prototype.hasOwnProperty.call(patch, "customer_status_in")) {
+      nextStatus = _customerStatusIn(patch.customer_status_in);
+    }
+    var nextActive = decoded.active;
+    if (Object.prototype.hasOwnProperty.call(patch, "active")) {
+      nextActive = _bool(patch.active, "active");
+    }
+    // trigger is immutable on update — operators that need a different
+    // trigger archive the rule and define a new one. Otherwise the
+    // metricsForRule history straddles two semantically distinct
+    // event spaces and the rollup becomes a lie.
+    if (Object.prototype.hasOwnProperty.call(patch, "trigger") && patch.trigger !== decoded.trigger) {
+      throw new TypeError("loyaltyEarnRules.updateRule: trigger is immutable — archive + define a new rule instead");
+    }
+
+    var ts = _now();
+    await query(
+      "UPDATE loyalty_earn_rules SET points_per_unit = ?1, max_per_event = ?2, " +
+      "customer_status_in_json = ?3, active = ?4, updated_at = ?5 WHERE slug = ?6",
+      [nextPoints, nextMax,
+       nextStatus == null ? null : JSON.stringify(nextStatus),
+       nextActive ? 1 : 0, ts, slug],
+    );
+    return _decodeRule(await _ruleRow(slug));
+  }
+
+  // ---- archiveRule ----------------------------------------------------
+
+  async function archiveRule(slug) {
+    _slug(slug, "slug");
+    var ts = _now();
+    var r = await query(
+      "UPDATE loyalty_earn_rules SET archived_at = ?1, active = 0, updated_at = ?1 " +
+      "WHERE slug = ?2 AND archived_at IS NULL",
+      [ts, slug],
+    );
+    if (Number(r.rowCount || 0) === 0) {
+      var existing = await _ruleRow(slug);
+      if (!existing) return null;
+      return _decodeRule(existing);
+    }
+    return _decodeRule(await _ruleRow(slug));
+  }
+
+  // ---- evaluateForEvent (dry-run) -------------------------------------
+
+  async function evaluateForEvent(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.evaluateForEvent: input object required");
+    }
+    var trigger = _trigger(input.trigger);
+    _uuid(input.customer_id, "customer_id");
+    _statusOpt(input.customer_status);
+
+    // The slug-targeted path lets operators preview a single named
+    // rule even when several rules share the same trigger. Absent a
+    // slug, every active matching-trigger rule is evaluated; the
+    // primitive returns each rule's verdict (eligible / skipped /
+    // capped) so the operator-facing UI can render a per-rule
+    // breakdown.
+    var rules;
+    if (input.slug != null) {
+      var slug = _slug(input.slug, "slug");
+      var r = await _ruleRow(slug);
+      rules = r ? [r] : [];
+    } else {
+      var r2 = await query(
+        "SELECT * FROM loyalty_earn_rules WHERE trigger = ?1 AND active = 1 AND archived_at IS NULL " +
+        "ORDER BY slug ASC",
+        [trigger],
+      );
+      rules = r2.rows;
+    }
+
+    var verdicts = [];
+    var totalPoints = 0;
+    for (var i = 0; i < rules.length; i += 1) {
+      var rule = _decodeRule(rules[i]);
+      if (rule.trigger !== trigger) {
+        verdicts.push({ slug: rule.slug, eligible: false, points: 0,
+                        reason: "rule.trigger=" + rule.trigger + " != requested " + trigger });
+        continue;
+      }
+      if (!rule.active || rule.archived_at != null) {
+        verdicts.push({ slug: rule.slug, eligible: false, points: 0,
+                        reason: "rule is inactive or archived" });
+        continue;
+      }
+      var statusReason = _statusFilter(rule, input);
+      if (statusReason) {
+        verdicts.push({ slug: rule.slug, eligible: false, points: 0, reason: statusReason });
+        continue;
+      }
+      var calc = _computePoints(rule, input);
+      if (calc.points <= 0) {
+        verdicts.push({ slug: rule.slug, eligible: false, points: 0, reason: calc.reason });
+        continue;
+      }
+      verdicts.push({
+        slug:     rule.slug,
+        eligible: true,
+        points:   calc.points,
+        reason:   calc.reason,
+        capped:   !!calc.capped,
+      });
+      totalPoints += calc.points;
+    }
+
+    return {
+      trigger:      trigger,
+      customer_id:  input.customer_id,
+      total_points: totalPoints,
+      verdicts:     verdicts,
+    };
+  }
+
+  // ---- awardForEvent --------------------------------------------------
+
+  async function awardForEvent(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.awardForEvent: input object required");
+    }
+    var trigger          = _trigger(input.trigger);
+    var customerId       = _uuid(input.customer_id, "customer_id");
+    var triggerEventRef  = _triggerEventRef(input.trigger_event_ref);
+    _statusOpt(input.customer_status);
+
+    var rules;
+    if (input.slug != null) {
+      var slug = _slug(input.slug, "slug");
+      var r = await _ruleRow(slug);
+      rules = r ? [r] : [];
+    } else {
+      var r2 = await query(
+        "SELECT * FROM loyalty_earn_rules WHERE trigger = ?1 AND active = 1 AND archived_at IS NULL " +
+        "ORDER BY slug ASC",
+        [trigger],
+      );
+      rules = r2.rows;
+    }
+
+    var awarded   = [];
+    var skipped   = [];
+    var totalPts  = 0;
+    for (var i = 0; i < rules.length; i += 1) {
+      var rule = _decodeRule(rules[i]);
+      if (rule.trigger !== trigger) {
+        skipped.push({ slug: rule.slug, reason: "rule.trigger != requested trigger" });
+        continue;
+      }
+      if (!rule.active || rule.archived_at != null) {
+        skipped.push({ slug: rule.slug, reason: "rule is inactive or archived" });
+        continue;
+      }
+      var statusReason = _statusFilter(rule, input);
+      if (statusReason) {
+        skipped.push({ slug: rule.slug, reason: statusReason });
+        continue;
+      }
+      var calc = _computePoints(rule, input);
+      if (calc.points <= 0) {
+        skipped.push({ slug: rule.slug, reason: calc.reason });
+        continue;
+      }
+
+      // Dedup at the storage layer: the UNIQUE (rule_slug,
+      // customer_id, trigger_event_ref) collapses a retried award
+      // onto the existing row. SQLite's INSERT OR IGNORE is the
+      // cheapest portable shape — when 0 rows change we surface the
+      // dedup as a skipped reason rather than a hard error so a
+      // webhook retry produces a consistent observable result.
+      var logId = _b().uuid.v7();
+      var ts    = _now();
+      var ins = await query(
+        "INSERT OR IGNORE INTO loyalty_earn_log " +
+        "(id, rule_slug, customer_id, points_awarded, trigger_event_ref, occurred_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+        [logId, rule.slug, customerId, calc.points, triggerEventRef, ts],
+      );
+      if (Number(ins.rowCount || 0) === 0) {
+        skipped.push({
+          slug:   rule.slug,
+          reason: "duplicate trigger_event_ref — already awarded for this event",
+        });
+        continue;
+      }
+
+      // Compose loyalty.earn when wired. Source is derived from the
+      // trigger name — loyalty's source validator demands lowercase
+      // alnum + `._-`, which the trigger enum already satisfies.
+      if (loyaltyHandle && typeof loyaltyHandle.earn === "function") {
+        try {
+          await loyaltyHandle.earn({
+            customer_id: customerId,
+            points:      calc.points,
+            source:      "earn-rule." + rule.slug,
+            notes:       "trigger=" + trigger + " ref=" + triggerEventRef,
+          });
+        } catch (err) {
+          // Loyalty ledger failed AFTER the audit log wrote. Roll
+          // the audit row back so the next retry isn't dedup-skipped
+          // against a row that never made it to the ledger. The
+          // operator-facing failure carries the underlying loyalty
+          // error so debugging hits the root cause not the audit
+          // breadcrumb.
+          await query(
+            "DELETE FROM loyalty_earn_log WHERE id = ?1",
+            [logId],
+          );
+          throw err;
+        }
+      }
+
+      awarded.push({
+        log_id:             logId,
+        slug:               rule.slug,
+        points:             calc.points,
+        capped:             !!calc.capped,
+        trigger_event_ref:  triggerEventRef,
+        occurred_at:        ts,
+      });
+      totalPts += calc.points;
+    }
+
+    return {
+      trigger:      trigger,
+      customer_id:  customerId,
+      total_points: totalPts,
+      awarded:      awarded,
+      skipped:      skipped,
+    };
+  }
+
+  // ---- metricsForRule -------------------------------------------------
+
+  async function metricsForRule(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.metricsForRule: input object required");
+    }
+    var slug = _slug(input.slug, "slug");
+    var from = _epochOpt(input.from, "from");
+    var to   = _epochOpt(input.to,   "to");
+    if (from != null && to != null && from > to) {
+      throw new TypeError("loyaltyEarnRules.metricsForRule: from must be <= to");
+    }
+    var ruleRow = await _ruleRow(slug);
+    if (!ruleRow) return null;
+
+    var sql = "SELECT COUNT(*) AS award_count, COUNT(DISTINCT customer_id) AS unique_customers, " +
+              "COALESCE(SUM(points_awarded), 0) AS total_points, " +
+              "MIN(occurred_at) AS first_award, MAX(occurred_at) AS last_award " +
+              "FROM loyalty_earn_log WHERE rule_slug = ?1";
+    var params = [slug];
+    var idx = 2;
+    if (from != null) { sql += " AND occurred_at >= ?" + idx; params.push(from); idx += 1; }
+    if (to   != null) { sql += " AND occurred_at <= ?" + idx; params.push(to);   idx += 1; }
+
+    var r = await query(sql, params);
+    var row = r.rows[0] || { award_count: 0, unique_customers: 0, total_points: 0,
+                              first_award: null, last_award: null };
+    return {
+      slug:              slug,
+      trigger:           ruleRow.trigger,
+      from:              from,
+      to:                to,
+      award_count:       Number(row.award_count || 0),
+      unique_customers:  Number(row.unique_customers || 0),
+      total_points:      Number(row.total_points || 0),
+      first_award:       row.first_award == null ? null : Number(row.first_award),
+      last_award:        row.last_award  == null ? null : Number(row.last_award),
+    };
+  }
+
+  // ---- applyBatch -----------------------------------------------------
+
+  async function applyBatch(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.applyBatch: input object required");
+    }
+    if (!Array.isArray(input.events) || input.events.length === 0) {
+      throw new TypeError("loyaltyEarnRules.applyBatch: events must be a non-empty array");
+    }
+    if (input.events.length > 10000) {
+      throw new TypeError("loyaltyEarnRules.applyBatch: events.length must be <= 10000");
+    }
+    // `rules` is an optional advisory hint — when supplied, the batch
+    // restricts to those rule slugs by passing through the per-event
+    // `slug` field. The primary path uses the per-event `slug` (when
+    // present) or `trigger` (when absent).
+    var ruleFilter = null;
+    if (input.rules != null) {
+      if (!Array.isArray(input.rules)) {
+        throw new TypeError("loyaltyEarnRules.applyBatch: rules must be an array of slugs when provided");
+      }
+      ruleFilter = Object.create(null);
+      for (var ri = 0; ri < input.rules.length; ri += 1) {
+        ruleFilter[_slug(input.rules[ri], "rules[" + ri + "]")] = true;
+      }
+    }
+
+    var awarded = [];
+    var skipped = [];
+    var failed  = [];
+    var totalPts = 0;
+
+    for (var i = 0; i < input.events.length; i += 1) {
+      var ev = input.events[i];
+      if (!ev || typeof ev !== "object") {
+        failed.push({ index: i, reason: "event must be an object" });
+        continue;
+      }
+      if (ruleFilter != null && ev.slug != null && !ruleFilter[ev.slug]) {
+        skipped.push({ index: i, slug: ev.slug, reason: "slug not in rules filter" });
+        continue;
+      }
+      try {
+        var result = await awardForEvent(ev);
+        for (var a = 0; a < result.awarded.length; a += 1) {
+          awarded.push({ index: i, award: result.awarded[a] });
+          totalPts += result.awarded[a].points;
+        }
+        for (var s = 0; s < result.skipped.length; s += 1) {
+          skipped.push({ index: i, slug: result.skipped[s].slug, reason: result.skipped[s].reason });
+        }
+      } catch (err) {
+        failed.push({ index: i, reason: err && err.message ? err.message : String(err) });
+      }
+    }
+
+    return {
+      total_events:  input.events.length,
+      total_points:  totalPts,
+      awarded:       awarded,
+      skipped:       skipped,
+      failed:        failed,
+    };
+  }
+
+  return {
+    TRIGGERS:               TRIGGERS.slice(),
+    UNIT_TRIGGERS:          Object.assign({}, UNIT_TRIGGERS),
+    MAX_POINTS_PER_UNIT:    MAX_POINTS_PER_UNIT,
+    MAX_MAX_PER_EVENT:      MAX_MAX_PER_EVENT,
+    MAX_STATUS_LIST:        MAX_STATUS_LIST,
+
+    defineRule:        defineRule,
+    getRule:           getRule,
+    listRules:         listRules,
+    updateRule:        updateRule,
+    archiveRule:       archiveRule,
+    evaluateForEvent:  evaluateForEvent,
+    awardForEvent:     awardForEvent,
+    metricsForRule:    metricsForRule,
+    applyBatch:        applyBatch,
+  };
+}
+
+module.exports = {
+  create:                create,
+  TRIGGERS:              TRIGGERS,
+  UNIT_TRIGGERS:         UNIT_TRIGGERS,
+  MAX_POINTS_PER_UNIT:   MAX_POINTS_PER_UNIT,
+  MAX_MAX_PER_EVENT:     MAX_MAX_PER_EVENT,
+  MAX_STATUS_LIST:       MAX_STATUS_LIST,
+};

package/lib/split-shipments.js

@@ -143,7 +143,13 @@ function _shortText(s, label, max) {
   return s;
 }
 
-function _now() { return Date.now(); }
+var _lastTs = 0;
+function _now() {
+  var t = Date.now();
+  if (t <= _lastTs) { t = _lastTs + 1; }
+  _lastTs = t;
+  return t;
+}
 
 // ---- factory ------------------------------------------------------------
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.0.70",
+  "version": "0.0.72",
   "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": {