@blamejs/blamejs-shop 0.0.57 → 0.0.58

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.58 (2026-05-22) — **Five new primitives: sales reports, quantity discounts, subscription controls, gift options, support tickets.** Five primitives ship in one release. `salesReports` aggregates orders for operator dashboards with cursor-paginated detail views + opt-in memoization. `quantityDiscounts` adds automatic tier pricing (buy N for X% off) scoped per SKU / product / collection / vendor / category / global, distinct from coupon codes. `subscriptionControls` layers pause / resume / skip-next / change-quantity / change-frequency / cancel / reactivate on top of the existing `subscriptions` surface with a full audit ledger. `giftOptions` adds gift wrapping (operator-configured wrap SKUs with fees) + gift message + recipient-name + gift-receipt toggle, with HTML-escape at every rendered field. `supportTickets` is a broader customer-service surface than `orderNotes` — pre-sale questions, account problems, complaints — with threaded messages, priority FSM, SLA timer, and per-operator assignment. **Added:** *`salesReports` primitive — order aggregations for operator dashboards* — `bShop.salesReports.create({ query?, cursorSecret? })` returns `{ revenueByDay, revenueByWeek, revenueByMonth, topProducts, topCustomers, revenueByCountry, revenueByPaymentMethod, customerCohort, aov, refundRate, funnel, purgeExpired }`. Each surface accepts `{ from, to, currency? }`; top-N surfaces add `{ limit, cursor? }` for HMAC-paginated detail. Opt-in memoization (`cache: true`) writes to a `sales_report_cache` row keyed on `(report_key, params_hash)` with operator-tuned TTL; default is fresh recompute so first-load dashboards never serve stale data. `customerCohort(cohort_month)` returns per-month retention for the cohort that first ordered in `cohort_month`. `funnel({ from, to })` counts checkout-started / payment-intent-created / paid / fulfilled / refunded. Migration `0042_sales_report_cache.sql` (id, report_key, params_hash, result_json, computed_at, expires_at + indexes on (report_key, expires_at), (params_hash)). · *`quantityDiscounts` primitive — automatic tier pricing per SKU / product / collection / vendor / category / global* — `bShop.quantityDiscounts.create({ query?, catalog })` returns `{ defineTier, getTiersForLine, applyToLine, applyToCart, update, archive, unarchive, list, tierBreakdown }`. Discount kinds: `percent_off (bps)`, `amount_off_each (minor)`, `amount_off_total (minor)`, `fixed_each_price (minor)`. `applyToLine` returns `{ original_unit_minor, discounted_unit_minor, line_subtotal_minor, line_discount_minor, applied_tier_id }` after walking applicable rules ordered by scope-specificity (sku > product > collection > vendor > category > global) and picking the best one. `exclusive: true` on a tier set short-circuits stacking. `defineTier` refuses overlapping `min_quantity` values within a single tier set so the schedule is unambiguous. Per-unit math composes `b.money.fromMinorUnits(...).multiply([num, den])` for half-even rounding consistent with the framework Money class. Migration `0044_quantity_discounts.sql` (`qd_tier_sets` + `qd_tiers` tables). · *`subscriptionControls` primitive — pause / resume / skip / change-quantity / change-frequency / cancel / reactivate* — `bShop.subscriptionControls.create({ query?, subscriptions })` returns `{ pause, resume, skipNext, changeQuantity, changeFrequency, cancel, reactivate, historyForSubscription, actorReport, scanAutoResume }`. `pause({ until?, reason })` flips active → paused; an `until` value schedules auto-resume via `scanAutoResume(now)`. `skipNext({ count, reason })` bumps `next_billing_at` by N periods without changing status; `changeFrequency({ new_frequency, reason })` recomputes `next_billing_at` on the new schedule (weekly / biweekly / monthly / quarterly / semiannual / annual). `cancel({ immediate? })` defaults to end-of-period (customer keeps access through the paid period); `immediate: true` ends now. `reactivate` allows cancelled → active within a 90-day grace window; refuses past. Every state change writes a `subscription_control_events` row with `actor_type`, `actor_id`, `before_json`, `after_json`, and a 280-char operator-prose `reason` so customer service can replay the full state arc. Migration `0045_subscription_controls.sql` (new event table + ALTER TABLE additions to `subscriptions` for `paused_at` / `paused_until` / `cancelled_at` / `quantity` / `frequency` / `next_billing_at`). · *`giftOptions` primitive — gift wrapping, gift message, gift receipt* — `bShop.giftOptions.create({ query?, catalog })` returns `{ defineWrap, listWraps, getWrap, updateWrap, archiveWrap, setForOrder, getForOrder, clearForOrder, feeForOrder, renderPackingSlipLine, analytics }`. `wrap_sku` references a real catalog SKU so wrap inventory + cost flow through normal channels. `setForOrder({ order_id, wrap_sku?, gift_message?, recipient_name?, hide_prices? })` validates `gift_message` (≤ 500 chars, control-byte-free, zero-width-char-free) + `recipient_name` (≤ 120 chars) + refuses unknown / archived wrap_sku. `renderPackingSlipLine({ order_id, locale })` returns `{ message_lines, recipient_name, hide_prices }` with every operator-input field HTML-escaped via `b.template.escapeHtml` (script-in-message / img-onerror payloads are rendered inert). `analytics({ from, to })` powers the operator dashboard (gift-option order count, top wrap_skus, gift-message rate). Migration `0046_gift_options.sql` (`gift_wraps` + per-order `gift_options` rows). · *`supportTickets` primitive — threaded customer-service surface with SLA timers* — `bShop.supportTickets.create({ query?, cursorSecret? })` returns `{ open, reply, transition, assign, unassign, addTag, removeTag, get, listForCustomer, listOpenAssignedTo, listUnassigned, thread, slaCheck, metrics }`. Distinct from `orderNotes` — a ticket isn't necessarily tied to an order. Categories: `pre_sale / order_issue / shipping / billing / refund / account / complaint / feature_request / other`. Priority: `low / normal / high / urgent`. Status FSM: `new → in_progress → waiting_customer → in_progress → resolved → closed`, with `reopened` re-entering `in_progress` and `closed` reachable from any state. Operator reply auto-flips `new → in_progress`. Email always hashed via `namespaceHash('support-ticket-email', ...)` before write. `slaCheck()` returns tickets breaching SLA (urgent 1h / high 4h / normal 24h / low 72h since last operator action). `metrics({ from, to })` covers per-category counts, average first-response time, resolution rate, escalation rate. Migration `0047_support_tickets.sql` (`support_tickets` + `support_messages` + `support_status_history` tables).
+
 - v0.0.57 (2026-05-22) — **Ten new primitives: bundles, variants, multi-warehouse inventory, backorder, payment methods, order notes, fraud screening, order export, print-on-demand, save-for-later.** Ten primitives ship in one release. `bundles` registers kit-products that expand at cart resolution time. `variants` is the option-axis layer that lets a single product carry the cartesian product of color × size × style (etc.) with per-variant overrides. `inventoryLocations` splits stock across N warehouses + retail stores + drop-ship suppliers with a routing strategy. `backorder` lets out-of-stock SKUs still be ordered with an expected-ship date carried to the PDP. `paymentMethods` stores per-customer processor tokens (Stripe payment-method ids, PayPal billing-agreement ids, etc.) with strict refuses on PAN / CVV-shaped fields. `orderNotes` adds a threaded customer-service surface attached to each order with `internal` and `customer_visible` visibility. `fraudScreen` returns a `{score, decision, signals}` triage at checkout from a 13-signal heuristic. `orderExport` streams CSV / NDJSON / scheduled-export rows with CSV-injection refusal at every cell. `printOnDemand` is the supplier-agnostic POD passthrough (Printful / Printify / Gelato / Lulu / Gooten / Cloudprinter + `custom`). `saveForLater` parks a cart line on the customer's account without losing the snapshot price. **Added:** *`bundles` primitive — kit / multi-pack products that expand at cart resolution* — `bShop.bundles.create({ query?, catalog })` returns `{ defineBundle, getBundle, listBundles, expand, priceBundle, updateBundle, deleteBundle }`. Bundle SKUs reference real catalog SKUs (or nested bundle SKUs up to 2 levels). `expand({ bundle_sku, quantity })` returns the flattened component list with multipliers applied. `priceBundle` sums child priceMinor and applies an optional `bundle_discount_bps` override. Cycle detection refuses bundles that eventually point back to themselves. `deleteBundle` refuses while any active cart line references the bundle. Migration `0032_bundles.sql` (`bundles` + `bundle_components` tables with UNIQUE(bundle_sku, sku) + FK CASCADE). · *`variants` primitive — product option matrix with per-variant overrides* — `bShop.variants.create({ query?, catalog })` returns `{ defineAxis, generateMatrix, materializeMatrix, getVariant, variantsForProduct, findVariant, updateVariant, archiveVariant, unarchiveVariant, archiveAxisOption }`. Operators register axes (`color`, `size`, etc.) with positions and option labels. `generateMatrix` previews the cartesian product without writing — the operator validates before `materializeMatrix` commits. SKU shape: `<prefix>-<axis1-opt>-<axis2-opt>-...` lowercase ASCII slug. `findVariant({ product_id, axis_values: { color: 'red', size: 'L' } })` resolves a specific cell. `image_url` validates via `b.safeUrl` so `javascript:` / `data:` schemes are refused at write. Migration `0033_product_variants.sql` (`product_variant_axes` + `product_variant_axis_options` + `product_variants` tables). · *`inventoryLocations` primitive — multi-warehouse stock + order routing* — `bShop.inventoryLocations.create({ query?, catalog })` returns `{ defineLocation, listLocations, getLocation, updateLocation, deactivateLocation, setStock, adjustStock, transferStock, stockForSku, totalForSku, availableLocations, routeOrder }`. Each location has a type (`warehouse` / `retail` / `dropship`) + priority + active flag. `transferStock` is an atomic two-row write so no stock is created or lost. `routeOrder` strategies: `priority-fill` (default — walks active locations in priority order), `single-location-cheapest`, `nearest-by-postal-prefix`. Returns `{ allocation: [{ location_code, lines }], unfulfillable }`. `inventory_adjustments` ledger is append-only — every `adjustStock` writes a reason-tagged row for audit replay. Migration `0034_inventory_locations.sql`. · *`backorder` primitive — orderable when out-of-stock with expected-ship dates* — `bShop.backorder.create({ query?, catalog })` returns `{ markBackorderable, markNotBackorderable, getStatus, listBackorderable, recordBackorder, fulfillBackorder, cancelBackorder, availabilityFor, customerBackorders, pendingForSku, arrivalsThisWeek }`. `availabilityFor(sku)` returns `{ status: 'in_stock' | 'backorderable' | 'out_of_stock', expected_ship_date?, message? }` for the PDP. `recordBackorder` enforces the per-sku `max_backorder_quantity` cap (NULL = unlimited). `arrivalsThisWeek` returns backorders with `expected_ship_date <= now + 7d` for operator-facing dashboards. Migration `0035_backorder.sql` (`backorder_skus` config table + `backorder_lines` per-order rows with status FSM (pending / fulfilled / cancelled)). · *`paymentMethods` primitive — saved processor tokens with PAN / CVV refusal* — `bShop.paymentMethods.create({ query? })` returns `{ add, get, listForCustomer, setDefault, archive, markExpired, defaultForCustomer, byProcessorToken, audit }`. Add refuses any field that looks like a raw PAN (regex: 13-19 digits in a row, including hyphen / space-collapsed forms), refuses CVV-shaped fields, validates processor enum (stripe / paypal / square / braintree / authorize_net), validates last4 (exactly 4 digits), validates expiry not in the past. `setDefault` enforces write-side default-uniqueness — promoting clears sibling default in the same transaction. `markExpired` is operator-scheduler-callable and writes an audit row per archived method. `audit(payment_method_id)` returns the row's full state-change history. Migration `0036_payment_methods.sql` (`payment_methods` + `payment_method_audit` tables with partial UNIQUE index on `(customer_id) WHERE is_default = 1 AND archived_at IS NULL`). · *`orderNotes` primitive — threaded customer-service notes per order* — `bShop.orderNotes.create({ query?, cursorSecret? })` returns `{ add, get, listForOrder, thread, markRead, pin, unpin, customerVisibleForOrder, internalForOrder, resolve, reopen }`. Visibility enum: `internal` (operator-only) / `customer_visible` (rendered on the customer's order page + emailed). Body cap 8000 chars, refuses control bytes + zero-width chars + empty-after-trim. `thread` returns a tree-shaped reply graph. `pin` floats a note to the top of the listing; resolve / reopen runs an internal-thread workflow with a 280-char resolution summary. Migration `0037_order_notes.sql` (`order_notes` + `order_note_reads` tables with indexes on (order_id, visibility, created_at desc) and (order_id, pinned desc, created_at desc)). · *`fraudScreen` primitive — heuristic risk score + decision at checkout* — `bShop.fraudScreen.create({ query?, customers?, addresses?, paymentMethods?, emailSuppressions? })` returns `{ screen, recordOutcome, recordChargeback, flagEmail, unflagEmail, customerRiskHistory, recentScreenings, hashEmail }`. `screen({ order_draft })` returns `{ score: 0..100, decision: 'approve' | 'review' | 'step_up' | 'refuse', signals }`. Decision thresholds: 0-39 approve, 40-69 review, 70-89 step_up, 90+ refuse. 13 signals fire independently and stack with operator-tunable weights: velocity (>N orders/24h from same email hash), high-value-new-customer, address-mismatch, free-email-domain, disposable-email-domain, session-too-fast (< 15s), session-too-old (> 24h), ua-curl-class, large-line-count, mismatched-bin-country (operator-supplied BIN → country map), prior-chargeback (looks up chargebacks ledger by email hash), suppressed-email, manually-flagged. Emails always hashed via `namespaceHash('fraud-email', ...)` before write. Migration `0038_fraud_screenings.sql` (`fraud_screenings` + `fraud_chargebacks` + `fraud_email_flags` tables). · *`orderExport` primitive — CSV / NDJSON streaming export with CSV-injection refusal* — `bShop.orderExport.create({ query?, order, cursorSecret? })` returns `{ csvForRange, ndjsonForRange, summaryForRange, scheduleExport, cancelExport, getExport, listExports, markExportRunning, markExportComplete, markExportFailed }`. Built-in 24-column schema covering order id / status / customer hash / addresses / line counts / monetary totals / payment method / fulfillment status / refund / return / chargeback flags. RFC-4180 quoting with CRLF; cell content starting with `=`, `+`, `-`, `@` gets prefixed with `'` per OWASP guidance (signed numerics like `+15.00` are exempt). Email is hashed via `namespaceHash('order-export-email', ...)` — raw email never reaches the export. `scheduleExport` writes a queued row + the operator's worker walks the `pod_fulfillments`-style FSM (queued → running → complete | failed | cancelled). Migration `0039_scheduled_exports.sql`. · *`printOnDemand` primitive — supplier-agnostic POD passthrough* — `bShop.printOnDemand.create({ query?, catalog })` returns `{ bindSku, unbindSku, getBinding, listBindings, updateBinding, costForOrder, forwardOrder, markFulfillmentSubmitted, markFulfillmentShipped, markFulfillmentFailed, markFulfillmentCancelled, getFulfillment, fulfillmentsForOrder, pendingFulfillments }`. Supplier enum: `printful` / `printify` / `gelato` / `lulu` / `gooten` / `cloudprinter` / `custom`. The primitive stores the SKU → supplier-product binding (artwork URL + variant id + position config + colorway + operator's wholesale `cost_minor`) and the per-order pending-fulfillment row. The actual HTTP push to each supplier is the operator's worker (each has its own auth + endpoint). `costForOrder(order_lines)` returns `{ total_cost_minor, by_supplier, unbound_skus }` for margin reporting. Migration `0040_print_on_demand.sql` (`pod_bindings` + `pod_fulfillments` tables with FSM-driven status column). · *`saveForLater` primitive — park a cart line on the customer account* — `bShop.saveForLater.create({ query?, catalog, currency?, cursorSecret? })` returns `{ moveFromCart, moveToCart, add, remove, clear, listForCustomer, countForCustomer, staleCheck, repriceAll, expireOlderThan }`. Distinct from `wishlist` — `wishlist` is "I'm interested", `saveForLater` is "I was about to buy this but not now". Lines carry their original cart context (price-at-save, variant, quantity, notes) so the customer can re-add with the snapshot price or the current price (`moveToCart` `use_price` parameter). `staleCheck` flags `is_stale` (price changed), `is_unavailable` (SKU gone), `is_low_stock` (catalog quantity < quantity-saved) per row. Refuses re-add to cart when the SKU is now out-of-stock and not backorderable. `expireOlderThan(days)` is the operator-scheduler sweep. Migration `0041_save_for_later.sql` with UNIQUE(customer_id, sku, COALESCE(variant_id, '')). **Fixed:** *`orderNotes` — monotonic `created_at` so back-to-back inserts always sort newest-first* — `Date.now()` on Windows resolves at ~15ms — three notes inserted in the same millisecond shared a `created_at` value, and the secondary `id DESC` tiebreaker fell back to UUID v7's random suffix (unstable since the time prefix collapsed). The primitive now stamps `created_at` with a process-local monotonic clock that increments by 1ms when `Date.now()` returns a stale value, so the listing's `pinned DESC, created_at DESC, id DESC` ordering reliably places the most recent note first regardless of insert burstiness.
 
 - v0.0.56 (2026-05-22) — **Republish of the eleven-primitive batch to npm.** 0.0.55 source landed on `main` but the npm publish workflow ran against the prior commit and didn't reach the registry. 0.0.56 republishes the same eleven primitives (`orderTracking`, `returns`, `loyalty`, `referrals`, `notifications`, `addresses`, `taxExempt`, `emailSuppressions`, `currencyDisplay`, `searchSuggestions`, `cartAbandonment`) plus migrations `0021`-`0031` so `npm install @blamejs/blamejs-shop@0.0.56` pulls the full surface. No code changes from 0.0.55 — only the version bump + this changelog entry. **Fixed:** *Republish to npm — 0.0.55 source on `main` reached operators via `git clone` but not via `npm install`* — `npm install @blamejs/blamejs-shop@0.0.55` would resolve to a missing version. 0.0.56 ships the identical surface so operators upgrading by version number get the full eleven-primitive batch + the eleven new migrations. Tag `v0.0.55` remains on the repo; operators referring to either version see equivalent code.

package/lib/gift-options.js

@@ -0,0 +1,596 @@
+"use strict";
+/**
+ * @module shop.giftOptions
+ * @title  Gift options — per-order wrap / message / recipient / hide-prices
+ *
+ * @intro
+ *   Three independent concerns folded into one primitive because
+ *   they all live on the same packing slip and clear together when
+ *   the order is cancelled:
+ *
+ *     wrap            — operator pre-defines a catalog SKU as a
+ *                       wrap option with a wrap fee. wrap_sku is a
+ *                       real catalog SKU so inventory + cost flow
+ *                       through the normal channels.
+ *     gift_message    — short customer-authored prose (≤ 500 chars,
+ *                       control-byte + zero-width-char free)
+ *                       rendered on the packing slip.
+ *     recipient_name  — for gift-to-someone-else orders (≤ 120
+ *                       chars, same hygiene as gift_message).
+ *     hide_prices     — toggle that suppresses prices on the slip
+ *                       (the "gift receipt" pattern).
+ *
+ *   Composes:
+ *     - `b.guardUuid` — order_id is UUID-shape-validated at every
+ *       entry point; bad shape throws TypeError the calling route
+ *       handler translates to HTTP 400.
+ *     - `b.template.escapeHtml` — `renderPackingSlipLine` returns
+ *       HTML-escaped strings ready for inline insertion into the
+ *       packing-slip template.
+ *
+ *   Surface:
+ *     - `defineWrap({ wrap_sku, title, fee_minor, image_url?,
+ *                     max_per_order?, active })` — register a wrap
+ *       option. Refuses unless wrap_sku is a real catalog variant.
+ *     - `listWraps({ active_only? })` / `getWrap(wrap_sku)` /
+ *       `updateWrap(wrap_sku, patch)` / `archiveWrap(wrap_sku)`.
+ *     - `setForOrder({ order_id, wrap_sku?, gift_message?,
+ *                      recipient_name?, hide_prices? })` — UPSERT.
+ *     - `getForOrder(order_id)` / `clearForOrder(order_id)`.
+ *     - `feeForOrder(order_id)` — wrap fee_minor or 0.
+ *     - `renderPackingSlipLine({ order_id, locale })` — returns
+ *       `{ message_lines, recipient_name, hide_prices }` with
+ *       HTML-escaped strings.
+ *     - `analytics({ from, to })` — count of orders with options,
+ *       top wrap_skus, gift-message rate.
+ *
+ *   Storage:
+ *     - `gift_wraps` + `gift_options` (migration
+ *       `0046_gift_options.sql`).
+ *
+ * @primitive giftOptions
+ * @related   b.guardUuid, b.template.escapeHtml
+ */
+
+var MAX_TITLE_LEN      = 200;
+var MAX_IMAGE_URL_LEN  = 2048;
+var MAX_MESSAGE_LEN    = 500;
+var MAX_RECIPIENT_LEN  = 120;
+
+// SKU shape mirrors catalog.js — alnum + . _ -, ≤ 128 chars,
+// leading char must be alnum so a wrap_sku can never start with a
+// hyphen / dot (sidesteps shell-arg-style ambiguity in downstream
+// CSV exports + the "looks like a flag" class of operator slips).
+var SKU_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+// Refuse C0 control bytes + DEL. The gift message + recipient name
+// render onto a packing slip and (potentially) a printer queue;
+// embedded control bytes have caused header-injection-class slips
+// in adjacent ecosystems. Newlines are allowed in gift_message
+// (people write multi-line messages); the recipient name is a
+// single line and refuses LF / CR too.
+var CONTROL_BYTE_MSG_RE   = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/;
+var CONTROL_BYTE_NAME_RE  = /[\x00-\x1f\x7f]/;
+
+// Zero-width / direction-override family — mirrors the order-notes
+// primitive's catalogue: ZWSP/ZWNJ/ZWJ (U+200B-200D), LRM/RLM
+// (U+200E/U+200F), the bidi-formatting block (U+202A-U+202E), the
+// invisible-math block (U+2060-U+2064), the LRI/RLI/FSI/PDI block
+// (U+2066-U+2069), the BOM (U+FEFF), and the Arabic letter mark
+// (U+061C). Spelled with \u-escapes so ESLint's
+// no-irregular-whitespace stays happy.
+var ZERO_WIDTH_RE = new RegExp(
+  "[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u2069\\uFEFF\\u061C]"
+);
+
+var ALLOWED_WRAP_COLUMNS = Object.freeze([
+  "title", "fee_minor", "image_url", "max_per_order", "active",
+]);
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+// ---- validators ---------------------------------------------------------
+
+function _uuid(s, label) {
+  try { return _b().guardUuid.sanitize(s, { profile: "strict" }); }
+  catch (e) { throw new TypeError("giftOptions: " + label + " — " + (e && e.message || "invalid UUID")); }
+}
+
+function _sku(s, label) {
+  if (typeof s !== "string" || !SKU_RE.test(s)) {
+    throw new TypeError("giftOptions: " + label + " must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/ (alnum + . _ -, ≤ 128 chars)");
+  }
+  return s;
+}
+
+function _title(s) {
+  if (typeof s !== "string" || !s.length || s.length > MAX_TITLE_LEN) {
+    throw new TypeError("giftOptions: title must be a non-empty string ≤ " + MAX_TITLE_LEN + " chars");
+  }
+  if (CONTROL_BYTE_NAME_RE.test(s) || ZERO_WIDTH_RE.test(s)) {
+    throw new TypeError("giftOptions: title contains control / zero-width bytes");
+  }
+  return s;
+}
+
+function _feeMinor(n) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TypeError("giftOptions: fee_minor must be a non-negative integer");
+  }
+  return n;
+}
+
+function _imageUrl(s) {
+  if (s == null) return null;
+  if (typeof s !== "string" || !s.length || s.length > MAX_IMAGE_URL_LEN) {
+    throw new TypeError("giftOptions: image_url must be a non-empty string ≤ " + MAX_IMAGE_URL_LEN + " chars");
+  }
+  // Restrict to https:// or // (protocol-relative) — http:// is a
+  // mixed-content liability on a storefront served over https, and
+  // javascript: / data: must never reach an <img src> on the
+  // checkout page. The browser-side CSP catches these too; this
+  // gate is defense-in-depth at the persistence layer.
+  if (!(/^https:\/\//.test(s) || /^\/\//.test(s) || /^\//.test(s))) {
+    throw new TypeError("giftOptions: image_url must be https://, // (protocol-relative), or / (absolute path)");
+  }
+  if (CONTROL_BYTE_NAME_RE.test(s) || ZERO_WIDTH_RE.test(s)) {
+    throw new TypeError("giftOptions: image_url contains control / zero-width bytes");
+  }
+  return s;
+}
+
+function _maxPerOrder(n) {
+  if (n == null) return null;
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new TypeError("giftOptions: max_per_order must be a positive integer or null");
+  }
+  return n;
+}
+
+function _bool(v, label) {
+  if (typeof v !== "boolean") {
+    throw new TypeError("giftOptions: " + label + " must be a boolean");
+  }
+  return v ? 1 : 0;
+}
+
+function _giftMessage(s) {
+  if (s == null) return null;
+  if (typeof s !== "string") {
+    throw new TypeError("giftOptions: gift_message must be a string");
+  }
+  if (s.length > MAX_MESSAGE_LEN) {
+    throw new TypeError("giftOptions: gift_message must be ≤ " + MAX_MESSAGE_LEN + " chars");
+  }
+  if (CONTROL_BYTE_MSG_RE.test(s)) {
+    throw new TypeError("giftOptions: gift_message contains control bytes");
+  }
+  if (ZERO_WIDTH_RE.test(s)) {
+    throw new TypeError("giftOptions: gift_message contains zero-width / direction-override characters");
+  }
+  return s;
+}
+
+function _recipientName(s) {
+  if (s == null) return null;
+  if (typeof s !== "string") {
+    throw new TypeError("giftOptions: recipient_name must be a string");
+  }
+  if (s.length > MAX_RECIPIENT_LEN) {
+    throw new TypeError("giftOptions: recipient_name must be ≤ " + MAX_RECIPIENT_LEN + " chars");
+  }
+  if (CONTROL_BYTE_NAME_RE.test(s)) {
+    throw new TypeError("giftOptions: recipient_name contains control bytes (incl. CR/LF)");
+  }
+  if (ZERO_WIDTH_RE.test(s)) {
+    throw new TypeError("giftOptions: recipient_name contains zero-width / direction-override characters");
+  }
+  return s;
+}
+
+function _epochMs(n, label) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TypeError("giftOptions: " + label + " must be a non-negative integer (epoch ms)");
+  }
+  return n;
+}
+
+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); };
+  }
+  // The catalog handle is required so `defineWrap` can verify that
+  // wrap_sku resolves to a real variant before persisting. Operators
+  // who'd run without a catalog handle would silently get wraps that
+  // point at no inventory row — refuse at factory time.
+  if (!opts.catalog) {
+    throw new TypeError("giftOptions.create: opts.catalog required (composes catalog.variants.bySku for wrap_sku resolution)");
+  }
+  var catalog = opts.catalog;
+
+  // -- gift_wraps surface -------------------------------------------------
+
+  async function defineWrap(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("giftOptions.defineWrap: input object required");
+    }
+    var wrapSku       = _sku(input.wrap_sku, "wrap_sku");
+    var title         = _title(input.title);
+    var feeMinor      = _feeMinor(input.fee_minor);
+    var imageUrl      = _imageUrl(input.image_url);
+    var maxPerOrder   = _maxPerOrder(input.max_per_order);
+    var active        = _bool(input.active, "active");
+
+    // wrap_sku must resolve to a real catalog variant so inventory
+    // + cost can flow through normal channels. Look it up via the
+    // catalog handle the factory was given.
+    var variant = await catalog.variants.bySku(wrapSku);
+    if (!variant) {
+      throw new TypeError("giftOptions.defineWrap: wrap_sku " + JSON.stringify(wrapSku) + " is not a known catalog variant");
+    }
+
+    var ts = _now();
+    await query(
+      "INSERT INTO gift_wraps (wrap_sku, title, fee_minor, image_url, max_per_order, active, archived_at, created_at, updated_at) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, NULL, ?7, ?7)",
+      [wrapSku, title, feeMinor, imageUrl, maxPerOrder, active, ts],
+    );
+    return {
+      wrap_sku:      wrapSku,
+      title:         title,
+      fee_minor:     feeMinor,
+      image_url:     imageUrl,
+      max_per_order: maxPerOrder,
+      active:        Boolean(active),
+      archived_at:   null,
+      created_at:    ts,
+      updated_at:    ts,
+    };
+  }
+
+  function _hydrateWrapRow(r) {
+    if (!r) return null;
+    return {
+      wrap_sku:      r.wrap_sku,
+      title:         r.title,
+      fee_minor:     Number(r.fee_minor),
+      image_url:     r.image_url,
+      max_per_order: r.max_per_order == null ? null : Number(r.max_per_order),
+      active:        Number(r.active) === 1,
+      archived_at:   r.archived_at == null ? null : Number(r.archived_at),
+      created_at:    Number(r.created_at),
+      updated_at:    Number(r.updated_at),
+    };
+  }
+
+  async function listWraps(listOpts) {
+    listOpts = listOpts || {};
+    var activeOnly = false;
+    if (listOpts.active_only != null) {
+      if (typeof listOpts.active_only !== "boolean") {
+        throw new TypeError("giftOptions.listWraps: active_only must be a boolean");
+      }
+      activeOnly = listOpts.active_only;
+    }
+    var sql, params;
+    if (activeOnly) {
+      sql    = "SELECT * FROM gift_wraps WHERE active = 1 AND archived_at IS NULL ORDER BY created_at ASC, wrap_sku ASC";
+      params = [];
+    } else {
+      sql    = "SELECT * FROM gift_wraps ORDER BY created_at ASC, wrap_sku ASC";
+      params = [];
+    }
+    var rows = (await query(sql, params)).rows;
+    return rows.map(_hydrateWrapRow);
+  }
+
+  async function getWrap(wrapSku) {
+    _sku(wrapSku, "wrap_sku");
+    var r = (await query(
+      "SELECT * FROM gift_wraps WHERE wrap_sku = ?1 LIMIT 1",
+      [wrapSku],
+    )).rows[0];
+    return _hydrateWrapRow(r);
+  }
+
+  async function updateWrap(wrapSku, patch) {
+    _sku(wrapSku, "wrap_sku");
+    if (!patch || typeof patch !== "object") {
+      throw new TypeError("giftOptions.updateWrap: patch object required");
+    }
+    var keys = Object.keys(patch);
+    if (!keys.length) {
+      throw new TypeError("giftOptions.updateWrap: patch must include at least one column");
+    }
+    var sets   = [];
+    var params = [];
+    var idx    = 1;
+    for (var i = 0; i < keys.length; i += 1) {
+      var col = keys[i];
+      // Lock the patch surface to a known column set — composing
+      // b.safeSql.assertOneOf would be the canonical path, but the
+      // primitive's column count is tiny enough that an explicit
+      // Object.freeze list is just as defensible and keeps the
+      // detector greps for unsafe column-name concatenation green.
+      if (ALLOWED_WRAP_COLUMNS.indexOf(col) === -1) {
+        throw new TypeError("giftOptions.updateWrap: unsupported column " + JSON.stringify(col));
+      }
+      var v;
+      if (col === "title")              v = _title(patch[col]);
+      else if (col === "fee_minor")     v = _feeMinor(patch[col]);
+      else if (col === "image_url")     v = _imageUrl(patch[col]);
+      else if (col === "max_per_order") v = _maxPerOrder(patch[col]);
+      else /* active */                 v = _bool(patch[col], "active");
+      sets.push(col + " = ?" + idx);
+      params.push(v);
+      idx += 1;
+    }
+    sets.push("updated_at = ?" + idx);
+    params.push(_now());
+    idx += 1;
+    params.push(wrapSku);
+    var r = await query(
+      "UPDATE gift_wraps SET " + sets.join(", ") + " WHERE wrap_sku = ?" + idx,
+      params,
+    );
+    if (Number(r.rowCount || 0) === 0) {
+      throw new TypeError("giftOptions.updateWrap: wrap_sku " + JSON.stringify(wrapSku) + " not found");
+    }
+    return await getWrap(wrapSku);
+  }
+
+  async function archiveWrap(wrapSku) {
+    _sku(wrapSku, "wrap_sku");
+    var ts = _now();
+    var r = await query(
+      "UPDATE gift_wraps SET active = 0, archived_at = ?1, updated_at = ?1 WHERE wrap_sku = ?2",
+      [ts, wrapSku],
+    );
+    if (Number(r.rowCount || 0) === 0) {
+      throw new TypeError("giftOptions.archiveWrap: wrap_sku " + JSON.stringify(wrapSku) + " not found");
+    }
+    return await getWrap(wrapSku);
+  }
+
+  // -- gift_options surface ----------------------------------------------
+
+  function _hydrateOptionsRow(r) {
+    if (!r) return null;
+    return {
+      order_id:        r.order_id,
+      wrap_sku:        r.wrap_sku,
+      gift_message:    r.gift_message,
+      recipient_name:  r.recipient_name,
+      hide_prices:     Number(r.hide_prices) === 1,
+      set_at:          Number(r.set_at),
+      updated_at:      Number(r.updated_at),
+    };
+  }
+
+  async function setForOrder(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("giftOptions.setForOrder: input object required");
+    }
+    var orderId = _uuid(input.order_id, "order_id");
+
+    var wrapSku = null;
+    if (input.wrap_sku != null) {
+      _sku(input.wrap_sku, "wrap_sku");
+      // Refuse if the wrap_sku isn't a defined, active, non-archived
+      // wrap. Archived wraps stay reachable via getForOrder for
+      // older orders, but setForOrder can't attach a new order to a
+      // wrap the operator has retired.
+      var wrap = (await query(
+        "SELECT * FROM gift_wraps WHERE wrap_sku = ?1 LIMIT 1",
+        [input.wrap_sku],
+      )).rows[0];
+      if (!wrap) {
+        throw new TypeError("giftOptions.setForOrder: wrap_sku " + JSON.stringify(input.wrap_sku) + " is not a defined wrap");
+      }
+      if (Number(wrap.active) !== 1 || wrap.archived_at != null) {
+        throw new TypeError("giftOptions.setForOrder: wrap_sku " + JSON.stringify(input.wrap_sku) + " is archived / inactive");
+      }
+      wrapSku = input.wrap_sku;
+    }
+
+    var giftMessage   = _giftMessage(input.gift_message);
+    var recipientName = _recipientName(input.recipient_name);
+
+    var hidePrices = 0;
+    if (input.hide_prices != null) {
+      hidePrices = _bool(input.hide_prices, "hide_prices");
+    }
+
+    var ts = _now();
+    // UPSERT — one gift_options row per order. Re-running with
+    // different inputs replaces every column (the operator UI
+    // re-submits the full state each time the customer edits gift
+    // options, so a partial UPSERT would silently retain stale
+    // fields).
+    await query(
+      "INSERT INTO gift_options (order_id, wrap_sku, gift_message, recipient_name, hide_prices, set_at, updated_at) " +
+      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?6) " +
+      "ON CONFLICT (order_id) DO UPDATE SET " +
+      "  wrap_sku        = excluded.wrap_sku, " +
+      "  gift_message    = excluded.gift_message, " +
+      "  recipient_name  = excluded.recipient_name, " +
+      "  hide_prices     = excluded.hide_prices, " +
+      "  updated_at      = excluded.updated_at",
+      [orderId, wrapSku, giftMessage, recipientName, hidePrices, ts],
+    );
+    return await getForOrder(orderId);
+  }
+
+  async function getForOrder(orderId) {
+    var oid = _uuid(orderId, "order_id");
+    var r = (await query(
+      "SELECT * FROM gift_options WHERE order_id = ?1 LIMIT 1",
+      [oid],
+    )).rows[0];
+    return _hydrateOptionsRow(r);
+  }
+
+  async function clearForOrder(orderId) {
+    var oid = _uuid(orderId, "order_id");
+    var r = await query(
+      "DELETE FROM gift_options WHERE order_id = ?1",
+      [oid],
+    );
+    return { cleared: Number(r.rowCount || 0) > 0 };
+  }
+
+  async function feeForOrder(orderId) {
+    var oid = _uuid(orderId, "order_id");
+    // Single JOIN read — pulls the wrap fee in one round-trip
+    // rather than two reads (gift_options then gift_wraps).
+    var r = (await query(
+      "SELECT gw.fee_minor AS fee_minor " +
+      "FROM gift_options go " +
+      "JOIN gift_wraps gw ON gw.wrap_sku = go.wrap_sku " +
+      "WHERE go.order_id = ?1 LIMIT 1",
+      [oid],
+    )).rows[0];
+    return r ? Number(r.fee_minor) : 0;
+  }
+
+  // -- packing-slip render ------------------------------------------------
+
+  async function renderPackingSlipLine(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("giftOptions.renderPackingSlipLine: input object required");
+    }
+    var oid = _uuid(input.order_id, "order_id");
+    // Locale is captured for future per-locale renderers — today
+    // the message itself is operator-authored prose and isn't
+    // translated, but the renderer surfaces the locale so a
+    // downstream slip template can pick a language-appropriate
+    // header. Refuse anything that isn't a BCP-47-shape string.
+    var locale = input.locale;
+    if (locale == null || typeof locale !== "string" || !/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(locale)) {
+      throw new TypeError("giftOptions.renderPackingSlipLine: locale must be a BCP-47-shape string (e.g. 'en-US')");
+    }
+
+    var row = (await query(
+      "SELECT * FROM gift_options WHERE order_id = ?1 LIMIT 1",
+      [oid],
+    )).rows[0];
+    if (!row) {
+      return {
+        message_lines:  [],
+        recipient_name: null,
+        hide_prices:    false,
+      };
+    }
+
+    var escapeHtml = _b().template.escapeHtml;
+
+    // Split the message on LF (and the rare CRLF) so the packing-
+    // slip template can emit one <div> per line without parsing
+    // raw newlines downstream. Trailing empty lines are dropped to
+    // keep the slip tidy when the customer typed an extra newline
+    // at the end.
+    var messageLines = [];
+    if (row.gift_message) {
+      var raw = String(row.gift_message).replace(/\r\n/g, "\n").split("\n");
+      while (raw.length && raw[raw.length - 1] === "") raw.pop();
+      messageLines = raw.map(function (line) { return escapeHtml(line); });
+    }
+
+    return {
+      message_lines:  messageLines,
+      recipient_name: row.recipient_name ? escapeHtml(row.recipient_name) : null,
+      hide_prices:    Number(row.hide_prices) === 1,
+      locale:         locale,
+    };
+  }
+
+  // -- analytics ----------------------------------------------------------
+
+  async function analytics(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("giftOptions.analytics: input object required");
+    }
+    var from = _epochMs(input.from, "from");
+    var to   = _epochMs(input.to,   "to");
+    if (to < from) {
+      throw new TypeError("giftOptions.analytics: to must be >= from");
+    }
+
+    // Total orders with any gift option in the window — counts
+    // every row regardless of which field(s) are set.
+    var totalRow = (await query(
+      "SELECT COUNT(*) AS n FROM gift_options WHERE set_at >= ?1 AND set_at < ?2",
+      [from, to],
+    )).rows[0];
+    var totalOrders = Number((totalRow || {}).n || 0);
+
+    // Top wrap_skus — orders with a non-NULL wrap_sku grouped by
+    // the wrap. Capped at 10 because the operator dashboard
+    // doesn't need an unbounded list.
+    var topWraps = (await query(
+      "SELECT wrap_sku, COUNT(*) AS n FROM gift_options " +
+      "WHERE set_at >= ?1 AND set_at < ?2 AND wrap_sku IS NOT NULL " +
+      "GROUP BY wrap_sku ORDER BY n DESC, wrap_sku ASC LIMIT 10",
+      [from, to],
+    )).rows.map(function (r) {
+      return { wrap_sku: r.wrap_sku, count: Number(r.n) };
+    });
+
+    // Gift-message rate — fraction of gift_options rows in the
+    // window that carry a non-NULL message. Returned as a float in
+    // [0, 1] so the dashboard can render as a percentage without
+    // worrying about division-by-zero.
+    var messageRow = (await query(
+      "SELECT COUNT(*) AS n FROM gift_options " +
+      "WHERE set_at >= ?1 AND set_at < ?2 AND gift_message IS NOT NULL AND gift_message != ''",
+      [from, to],
+    )).rows[0];
+    var messageCount = Number((messageRow || {}).n || 0);
+    var messageRate  = totalOrders > 0 ? messageCount / totalOrders : 0;
+
+    return {
+      from:               from,
+      to:                 to,
+      orders_with_gift:   totalOrders,
+      top_wrap_skus:      topWraps,
+      gift_message_count: messageCount,
+      gift_message_rate:  messageRate,
+    };
+  }
+
+  return {
+    MAX_TITLE_LEN:     MAX_TITLE_LEN,
+    MAX_MESSAGE_LEN:   MAX_MESSAGE_LEN,
+    MAX_RECIPIENT_LEN: MAX_RECIPIENT_LEN,
+
+    defineWrap:             defineWrap,
+    listWraps:              listWraps,
+    getWrap:                getWrap,
+    updateWrap:             updateWrap,
+    archiveWrap:            archiveWrap,
+
+    setForOrder:            setForOrder,
+    getForOrder:            getForOrder,
+    clearForOrder:          clearForOrder,
+    feeForOrder:            feeForOrder,
+    renderPackingSlipLine:  renderPackingSlipLine,
+    analytics:              analytics,
+  };
+}
+
+module.exports = {
+  create:            create,
+  MAX_TITLE_LEN:     MAX_TITLE_LEN,
+  MAX_MESSAGE_LEN:   MAX_MESSAGE_LEN,
+  MAX_RECIPIENT_LEN: MAX_RECIPIENT_LEN,
+};

package/lib/index.js

@@ -79,4 +79,9 @@ module.exports = {
   orderExport:       require("./order-export"),
   printOnDemand:     require("./print-on-demand"),
   saveForLater:      require("./save-for-later"),
+  salesReports:        require("./sales-reports"),
+  quantityDiscounts:   require("./quantity-discounts"),
+  subscriptionControls: require("./subscription-controls"),
+  giftOptions:         require("./gift-options"),
+  supportTickets:      require("./support-tickets"),
 };