@blamejs/blamejs-shop 0.0.53 → 0.0.56

package/CHANGELOG.md

@@ -8,6 +8,12 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- 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.
+
+- v0.0.55 (2026-05-22) — **Eleven new primitives: order tracking, returns, loyalty, referrals, notifications, addresses, tax exemptions, email suppressions, multi-currency display, search suggestions, cart abandonment.** Eleven primitives land in one release, each composed on the vendored blamejs surface (`b.crypto.namespaceHash`, `b.guardEmail`, `b.guardUuid`, `b.uuid.v7`, `b.pagination`, `b.safeSql`, `b.money`). Order tracking + shipments now drive carrier deep-links (UPS / FedEx / USPS / DHL / Royal Mail / Canada Post / Australia Post). Returns ship a full RMA FSM (pending → approved → received → refunded). Loyalty awards points + tier bands. Referrals issue two-sided rewards. Notifications queue with retry + preferences. Saved addresses give customers a per-account book with default-shipping/billing uniqueness. Tax exemption certificates carry an approve/reject/revoke pipeline + a region-aware `isExempt` check. Email suppressions gate outbound mail per scope (transactional / marketing / all). Multi-currency display caches FX rates as integer basis-points with a staleness flag. Search suggestions blend operator-featured rows with popular queries. Cart abandonment scans idle carts and emits per-detection rows for downstream reminder fan-out. **Added:** *`orderTracking` primitive — shipments + per-event log + carrier deep-links* — `bShop.orderTracking.create({ query?, cursorSecret? })` returns `{ createShipment, addEvent, getShipment, listForOrder, byTrackingNumber, carrierTrackingUrl, statusFromCarrier, latestStatus }`. Shipment status flows `label_created → in_transit → out_for_delivery → delivered`, with `exception` + `returned` terminal branches. `carrierTrackingUrl(carrier, tracking_number)` returns the carrier deep-link from a built-in URL template table for UPS / FedEx / USPS / DHL / Royal Mail / Canada Post / Australia Post; unknown carriers return `null` rather than guessing. `addEvent` appends a `shipment_events` row with the carrier-reported status string + raw timestamp + free-form description. Migration `0021_shipments.sql` (shipments + shipment_events tables, indexes on (order_id, created_at), (tracking_number), (status, created_at)). · *`returns` primitive — RMA workflow with per-line reason codes* — `bShop.returns.create({ query?, cursorSecret? })` returns `{ open, approve, reject, markReceived, refund, get, listForCustomer, listForOrder, byStatus }`. The RMA FSM is `pending → approved → received → refunded` with a `rejected` terminal branch from `pending`. Each line carries a reason code from the operator-config'd enum (default: `defective`, `wrong_item`, `wrong_size`, `changed_mind`, `damaged_in_transit`, `not_as_described`, `arrived_late`, `other`) + an optional 280-char note. `refund` writes the refund amount in minor units + the operator's payment-processor refund id. Migration `0023_returns.sql` (returns + return_lines tables, FK CASCADE, indexes on (customer_id, created_at desc), (order_id), (status, created_at desc)). · *`loyalty` primitive — tier bands + point ledger with earn / redeem / expire* — `bShop.loyalty.create({ query?, cursorSecret? })` returns `{ award, redeem, expire, balance, tierForCustomer, history, customersInTier, recomputeTier }`. Default tiers are `bronze (0)`, `silver (250)`, `gold (1000)`, `platinum (5000)` with operator-overridable thresholds. Point ledger is append-only (`earn` / `redeem` / `expire` / `adjust` row types) so totals are always derivable + audit-replayable. `expire` walks rows whose `expires_at <= now` and emits an offsetting `expire` row equal to the unconsumed remainder. Migration `0022_loyalty.sql` (loyalty_ledger + customer_loyalty_summary cached-aggregate tables, indexes on (customer_id, occurred_at desc), (expires_at) where expires_at IS NOT NULL). · *`referrals` primitive — two-sided reward with single-use codes* — `bShop.referrals.create({ query?, cursorSecret? })` returns `{ issueCode, redeem, getCode, listForReferrer, statusForCode, expireScan, statsForReferrer }`. `issueCode` mints a per-referrer code (8-char crockford-base32) and stores it lowercase-normalised; one referrer can hold N codes. `redeem(code, referee_customer_id)` is single-use, refuses self-referral, refuses re-redemption, and emits both the referrer reward row + the referee reward row in one transaction. Reward shape is operator-config'd (`{ kind: 'percent_off' | 'amount_off' | 'points', value }`). Migration `0025_referrals.sql` (referral_codes + referral_redemptions tables, UNIQUE(referee_customer_id) so a customer can only be referred once, indexes on (referrer_customer_id), (status, created_at desc)). · *`notifications` primitive — queue with retry + per-customer channel preferences* — `bShop.notifications.create({ query?, cursorSecret? })` returns `{ enqueue, dispatch, markDelivered, markFailed, setPreference, getPreferences, listForCustomer, listPending }`. Channels: `email`, `sms`, `webhook`. A `notifications_preferences` row stores per-(customer_id, channel, category) opt-in state — `enqueue` consults the matrix and refuses with `{ skipped: true, reason: 'opted-out' }` when the matching row is opt-out. `dispatch` reads `next_retry_at <= now` rows in `pending` and walks the operator-supplied dispatcher callback. Failure schedules an exponential-backoff retry on `[60s, 5m, 30m, 4h]` before terminal `failed`. Migration `0024_notifications.sql` (notifications + notifications_preferences tables, indexes on (status, next_retry_at), (customer_id, created_at desc), (status, created_at desc)). · *`addresses` primitive — per-customer address book with default flags* — `bShop.addresses.create({ query? })` returns `{ add, update, get, listForCustomer, defaultShipping, defaultBilling, archive, unarchive, setDefaultShipping, setDefaultBilling, matchByContent }`. Default-flag uniqueness is enforced write-side — promoting an address to default clears the flag on its sibling rows in the same transaction. Archive drops both default flags so a stale archived row can't accidentally remain default. `matchByContent` collapses casing + whitespace on the address fields so dedup catches near-duplicates at submit time. Migration `0026_customer_addresses.sql` (id, customer_id, full_name, line1/line2, city, region, postal_code, country (ISO-3166-1 alpha-2), phone, is_default_shipping, is_default_billing, archived_at, created_at, updated_at). · *`taxExempt` primitive — exemption certificates with approve / reject / revoke pipeline* — `bShop.taxExempt.create({ query? })` returns `{ submit, approve, reject, revoke, expireScan, get, activeForCustomer, listPendingReview, isExempt }`. Cert numbers persist plaintext for operator display + dedup-hashed via `b.crypto.namespaceHash('tax-cert-number', uppercase(trim(...)))`. Submit is idempotent on `(customer_id, jurisdiction, hash)` — re-submitting an approved cert returns the existing row's status. `isExempt(customer_id, jurisdiction)` honours region-aware ancestry — an `US` certificate covers `US-CA` subdivision lookups. Read-path filters `expires_at <= now` so a slow `expireScan` scheduler can't honor a stale row at checkout. Migration `0027_tax_exempt_certs.sql` (certs + the FSM status column, indexes on (customer_id, status, expires_at), (status, submitted_at), (jurisdiction, status)). · *`emailSuppressions` primitive — bounce / complaint / unsubscribe / opt-out gate* — `bShop.emailSuppressions.create({ query?, cursorSecret? })` returns `{ add, isSuppressed, remove, byHash, list, cleanupExpired, stats }`. Suppression types: `bounce` (hard / soft), `complaint`, `unsubscribe`, `operator_manual`, `rate_limit_block`. Default scope is operator-friendly per type — bounce/complaint suppress `transactional`, unsubscribe suppresses `marketing`, operator-manual + rate-limit suppress `all`. `isSuppressed(email, scope)` honours scope hierarchy — an `all` row blocks every requested scope. Email never persists raw; only the lowercased + trimmed form + the `namespaceHash('email-suppression', ...)` digest. Migration `0028_email_suppressions.sql` (id, email_hash UNIQUE, email_normalised, type, scope, reason, occurrences, expires_at, created_at, updated_at). · *`currencyDisplay` primitive — FX rate cache + safe conversion + locale-aware format* — `bShop.currencyDisplay.create({ query? })` returns `{ setRate, getRate, convert, format, convertAndFormat, cleanupExpired, bulkSetRates }`. Rates encode as integer basis-points (`rate * 10000`) so storage stays integer-clean. Conversion composes `b.money.convert` — rounding is half-to-even via the framework's BigInt path, so zero-decimal targets (JPY, KRW) work without per-currency casing. Stale rows surface `{ stale: true, converted_minor: null }` instead of returning an out-of-date number — the storefront falls back to native currency. `bulkSetRates` validates every row before writing any (pre-flight, since D1 has no client transactions). Migration `0029_fx_rates.sql` (id, base_currency + quote_currency UNIQUE pair, rate_bps, source, fetched_at, expires_at). · *`searchSuggestions` primitive — operator-featured rows + popular-query log + product matches* — `bShop.searchSuggestions.create({ query?, catalog })` returns `{ recordQuery, suggest, addFeatured, updateFeatured, deleteFeatured, popularQueries, cleanupOldQueries }`. `suggest(prefix)` returns a three-array shape (`featured`, `popular`, `products`) so the storefront renders sectioned dropdowns without re-querying. Featured rows carry an FSM (`active` / `paused` / `expired`) + a `(starts_at, expires_at)` window so an operator can time a promotion. `link_url` on featured rows refuses `javascript:` / `data:` / `vbscript:` schemes. Session ids on `recordQuery` are hashed via `namespaceHash('search-suggestions-session', ...)` before write — the popular-query log never holds a recoverable identifier. Migrations `0030_search_suggestions.sql` (featured_search_suggestions + search_query_log tables, indexes on (active + window), (query_normalised, recorded_at desc), (priority desc)). · *`cartAbandonment` primitive — scheduled scanner over idle carts + reminder fan-out feed* — `bShop.cartAbandonment.create({ query?, cursorSecret? })` returns `{ scan, markReminderSent, markReminderSkipped, markReminderFailed, recentDetections, statsForRun, cleanupOld }`. Each `scan` writes a `cart_abandonment_runs` row + N `cart_abandonment_detections` rows for carts whose last update falls in the idle window. Idempotent — a cart already detected within the current idle window skips via a `last detection > idleCutoff` guard + a `UNIQUE(cart_id, detected_at)` collision catch. Session ids are namespace-hashed (`cart-abandonment-session`) before write. Reminder skip reasons route to `skipped-suppressed` (consult `emailSuppressions`) vs `skipped-no-email` (anonymous cart). Migration `0031_cart_abandonment_runs.sql` (detections + runs tables, indexes on (status, detected_at desc), (cart_id), (run_id)).
+
+- v0.0.54 (2026-05-22) — **Reviews, wishlist, inventory-receive, webhooks DLQ, payment idempotency, newsletter unsubscribe, email templates, VAT/GST, midnight theme, analytics events.** Ten new or extended primitives land together. `reviews`, `wishlist`, and `inventoryReceive` are brand-new with their own migrations and surface APIs. `webhooks` gains a dead-letter queue + exponential-backoff retry + sliding-window rate-limit + signed-incoming verification. `payment` gains idempotency-key tracking so a re-issued Stripe call replays the stored response instead of double-charging. `newsletter` gains an unsubscribe token flow + resubscribe path. `email` gains three new transactional templates (wishlist-discount, abandoned-cart, review-request). `tax` gains VAT/GST extraction, reverse-charge for EU B2B, and format-only VAT-ID validation for 29 country codes. `analytics` gains an event-stream surface with hashed identifiers + top-N aggregations + funnel math. `themes/midnight` ships as an alternate dark-mode theme that inherits the default theme's component CSS and overrides only the design tokens. **Added:** *`reviews` primitive — moderated customer reviews per product* — `bShop.reviews.create({ query?, cursorSecret? })` returns `{ submit, get, publish, reject, listForProduct, summaryForProduct, byCustomer, hashCustomerId, hashCustomerEmail }`. Email is stored hash-only via `b.crypto.namespaceHash` namespace `"reviews-customer"`; raw addresses never persist. Either `customer_id` or `customer_email` is required at submit; the hash collapses casing for dedup. Status pipeline: `pending → published → rejected`. `summaryForProduct` returns count + average + distribution histogram. Migration `0011_reviews.sql` (id, product_id, customer_id, customer_id_hash, rating CHECK 1..5, title cap 120, body cap 4000, verified_purchase, status CHECK enum, created_at, updated_at) with indexes on (product, status, created_at desc), (customer_hash, created_at), and (product, rating). · *`wishlist` primitive — saved-for-later with operator analytics* — `bShop.wishlist.create({ query?, cursorSecret? })` returns `{ add, remove, listForCustomer, isWishlisted, countForProduct, popularProducts }`. Idempotent dedup via `UNIQUE (customer_id, product_id, COALESCE(variant_id, ''))`. `popularProducts` returns the top-N most-wishlisted products for operator merchandising. HMAC-tagged pagination cursor on `created_at` desc + `id` desc. Migration `0012_wishlist.sql` (id, customer_id, product_id, variant_id nullable, notes cap 280, created_at). 38 layer-1 check assertions covering add/dedup, scoped remove, pagination, tamper-refused cursor, distinct-customer count. · *`inventoryReceive` primitive — bulk stock receipts with audit trail* — `bShop.inventoryReceive.create({ query?, catalog, cursorSecret? })` returns `{ draft, apply, reverse, get, byReference, list }`. Operators draft a `pending` receipt with N lines in one transaction, then `apply` walks each line + calls `catalog.inventory.restock(sku, qty)` — atomic, so a single restock failure aborts the whole apply and leaves the receipt pending for retry. `reverse` rolls back an applied receipt by issuing the inverse stock adjustment. Idempotent re-apply on `applied` status is a no-op. Migration `0018_inventory_receipts.sql` (receipts + receipt_lines tables, FK CASCADE, indexes on received_at + status + receipt_id + sku). · *`webhooks` — dead-letter queue + exponential backoff + sliding-window rate-limit + signed incoming verification* — Failed deliveries now retry on a `[60s, 5m, 30m, 4h, 24h]` exponential schedule. After 5 failures, the row moves to `webhook_dlq` for operator investigation; `replayFromDlq(dlq_id)` re-queues with `attempts=0`. Per-endpoint `rate_limit_per_minute` (default 60) is enforced via a sliding-window count over the deliveries table. New `verifyIncoming(payload, signature_header, secret, tolerance_seconds?)` matches the Stripe `t=<unix>,v1=<hmac>` shape via `b.webhook.verify`; `signOutgoing(payload, secret, ts?)` is the companion emitter so the framework can both produce and verify the standard signature shape. Migration `0017_webhook_dlq.sql` adds the DLQ table + the next_retry_at + last_attempted_at columns on deliveries. · *`payment` — idempotency-key tracking on mutating Stripe calls* — `createPaymentIntent`, `refund`, and the `subscriptions.*` mutating methods now accept an `idempotency_key` parameter. When the primitive is created with a `query` opt, the same key + canonicalised body hash returns the stored response without re-calling Stripe; the same key with a *different* body throws `TypeError("payment: idempotency_key collision (different inputs)")` — silently returning would let an attacker replay a different amount. Migration `0015_payment_idempotency.sql` stores (idempotency_key PK, operation, request_hash, response_status, response_body, expires_at) with a 24-hour TTL matching Stripe's. `cleanupExpired()` purges expired rows on operator schedule. · *`newsletter` — single-use unsubscribe token + resubscribe flow* — `issueUnsubscribeToken(signup_id)` mints a 24-byte base64url plaintext bearer (32 chars), stores only the `namespaceHash("newsletter-unsubscribe", plaintext)` with a one-year expiry; the plaintext is returned once, never re-issuable. `consumeUnsubscribeToken(plaintext)` is the single-use redeem — structured-result return distinguishes `not-found`, `already-consumed`, `expired`, `ok`. Uses `b.crypto.timingSafeEqual` to equalize hit-vs-miss CPU work. `resubscribe({ email })` clears `unsubscribed_at` for a previously-opted-out signup. Migration `0014_newsletter_unsubscribe_tokens.sql` (token_hash PK, signup_id, created_at, consumed_at, expires_at). · *`email` — three new transactional templates* — `sendWishlistDiscount({ customer_email, product_title, product_url, old_price, new_price, discount_pct, expires_at? })` — price-drop alert with the orange CTA back to the product. `sendAbandonedCartReminder({ customer_email, customer_name?, cart_url, lines, total, notes? })` — loops cart lines through the strict renderer once per row so every cell stays HTML-escaped. `sendReviewRequest({ customer_email, customer_name?, order_id, products, review_base_url })` — per-product review links built as `review_base_url + "/" + slug + "/review"`. All three emit both html + text via `b.mail.compose`, validate addresses via `b.guardEmail`, and refuse unknown / unused placeholders at the strict renderer. · *`tax` — VAT / GST extraction + reverse charge + VAT-ID format validation* — `calculateInclusive({ amount_minor, rate_bps, currency })` extracts VAT from a gross price; `calculateExclusive` adds VAT to a net price; both use banker's rounding to even and guarantee `net + tax === gross`. `applyReverseCharge({ ctx, seller_vat_id?, buyer_vat_id?, buyer_country })` returns `rate_bps: 0` when both VAT IDs format-validate, both countries are EU, and the buyer VAT-ID country matches. `validateVatId(vat_id, country_code)` regex-checks against 29 country formats (EU-27 + GB + CH, with GR aliasing to EL). `format({ rate_bps, locale?, reverse_charge? })` renders via `Intl.NumberFormat` with optional reverse-charge annotation. Operators wire VIES live-validation out of band — the primitive's JSDoc documents the boundary. · *`analytics` — event-stream surface with hashed identifiers + top-N + funnel* — `recordEvent({ event_type, session_id?, customer_id?, product_id?, search_q?, page_url?, user_agent_class?, payload?, occurred_at? })` hashes `session_id` and `customer_id` via `b.crypto.namespaceHash` before write — raw identifiers never persist. Refuses raw email or IP shapes on every string field. `topSearchTerms`, `topViewedProducts`, `funnel`, `sessionFlow(session_id, …)`, `dropAfter(ts)` cover the operator surfaces. Migration `0019_analytics_events.sql` (id, event_type CHECK enum, session_id_hash NOT NULL, customer_id_hash, payload_json bounded 4 KiB, product_id, search_q, page_url, user_agent_class CHECK enum, occurred_at) + 4 indexes covering (event_type, time), (session, time), (product, event_type, time), and (search_q, time). · *`themes/midnight` — alternate dark-mode theme via design-token override* — 2.59 KiB stylesheet at `themes/midnight/assets/css/main.css` that `@import`s the default theme's component CSS, then overrides ~26 design tokens (palette flipped, shadow alpha deepened, accent warmed to `#ff8a3a` for dark contrast). Two per-surface fixes for `.site-header` and `.site-footer` which hard-code colours outside the token system. Operators activate by setting `SHOP_THEME=midnight` in wrangler vars. The midnight theme demonstrates the inheritance pattern for operators authoring their own theme.
+
 - v0.0.53 (2026-05-22) — **Docs refresh, sample catalog tripled, designed empty-cart card, worker hardening.** Four surfaces refresh in one release. `SECURITY.md` + `CONTRIBUTING.md` + `docs/deploy-cloudflare.md` cover the scoped package name + custom domain + the full 0001-0010 migration table. The sample catalog grows from 4 products to 12 (Operator Hoodie, Vault Stick, Signing Cable, Build Pass, Audit Log Kit, Self-Hosted Plan, Operator Mug, Sticker Pack — each with its own brand-coloured SVG hero). The empty-cart row gains a designed `cart-empty` card with the brand 🛒 icon, eyebrow + title + lede + dual CTAs (`Browse products` primary, `Find a specific product` ghost linking the header search). The Worker gets a `/robots.txt` edge fallback (so crawlers get a clean answer even during container cold-start), the warming-up page picks up `noindex`/`canonical`/`aria-live`/refresh tuned to `Sec-Fetch-Mode`, and a new `/_/version` probe surfaces deploy state. **Added:** *Sample catalog grows from 4 to 12 products with brand-coloured SVG heroes* — `scripts/sample-product-images/{operator-hoodie,vault-stick,signing-cable,build-pass,audit-log-kit,self-hosted-plan,operator-mug,sticker-pack}.svg` ship as the next round of reference imagery. Apparel SVGs use dark-ink gradients with accent-orange illustrations; hardware uses navy-to-blue gradients with grey/black device silhouettes + accent-orange chip highlights; digital uses purple-to-navy with credential-artifact motifs carrying a visible PQC / ML-DSA seal; bundles use deep-orange or green with stacked-object compositions. All 800×800 viewBox, system font stack, monospace SKU at bottom-right. `scripts/seed-sample-products.sql` + `scripts/seed-sample-product-media.sql` extend with the matching catalog + media rows (UUIDv7 ids continue the existing numbering 0005-000c). · *Designed empty-cart card* — `renderCart` emits a `.cart-empty` section instead of a bare `<td colspan>` row when there are no lines. The card carries the brand emoji in a dashed-border circle, `Cart` eyebrow, `Your cart is empty` headline, a lede that explains how the cart holds the add-time price, and dual CTAs — `Browse products →` (primary, → `/`) + `Find a specific product` (ghost, anchors `#site-search-q` for header-search focus without inline JS). Populated cart gains a `Shop / Cart` breadcrumb above the section head, matching the PDP's pattern. · *Worker `/robots.txt` edge fallback* — Even during container cold-start, the Worker now serves a minimal `User-agent: *\nAllow: /\nSitemap: https://blamejs.shop/sitemap.xml\n` directly at the edge with a 1h cache. Crawlers never see the warming page for robots probes. R2-uploaded `/assets/robots.txt` overrides still win for operators with a custom policy. · *Worker `/_/version` deploy probe* — Operator-friendly diagnostic endpoint returning `{ worker, container_image, time }`. No auth required (pure read-only probe); use it to verify a deploy reached the edge before sending traffic. · *`CONTRIBUTING.md`* — 210 lines covering: dev environment setup (clone → vendor-update → smoke), the release workflow (release-notes JSON → CHANGELOG rebuild → branch → PR → admin merge → tag → publish), code conventions (CommonJS, `var`, zero npm runtime deps, compose `b.*` primitives, vendored tree read-only, security defaults non-opt-in, PQC-first), how to run + write tests (smoke + layer-0/1/2, `waitUntil` over `setTimeout`), the explicit list of artifacts each publish produces, and a pointer to `SECURITY.md` for vuln reporting. **Changed:** *Warming-up page — `noindex`, canonical, ARIA-live, refresh tuned to navigation mode* — The cold-start fallback page picks up `<meta name="robots" content="noindex, nofollow">` + a canonical link so crawlers don't index the placeholder. The auto-refresh interval shifts based on `Sec-Fetch-Mode` — 5 seconds for `navigate` requests (real visitor in a browser tab), 8 seconds for non-navigation fetches (XHR/fetch/Stripe.js probes that shouldn't spam the container). A new `aria-live="polite"` region announces the warming state to screen readers. · *`SECURITY.md` — Stripe webhook clause updated to match shipped code* — The container's defense-in-depth verification clause used a placeholder phrase from before `lib/payment.js` shipped. Now describes the actual `b.webhook.verify` call (alg `hmac-sha256-stripe`) running inside `lib/payment.js` before any FSM transition. Every other audit point matched the workflow output as-is — SLSA L3 provenance, Sigstore-keyless SBOM signatures, SHA-256 + SHA3-512 digests, ML-DSA-65 PQC sidecar. · *`docs/deploy-cloudflare.md` — custom-domain section + 0001-0010 migration table + demo-seed step* — Adds a `Wire a custom domain` section (zone-add → Worker custom-domain bind → `wrangler.toml` route alternative → TLS verify). Replaces the bare-paragraph migration mention with the explicit 0001-0010 table (calling out the intentional `0007` gap from the abandoned discounts work). Adds a `Seed demo content` section that runs both seed SQL files via `wrangler d1 execute --remote`. Switches the existing migration-apply step to `--remote` for clarity.
 
 - v0.0.52 (2026-05-22) — **Live deploy moves to the custom domain — README + wrangler config point at https://blamejs.shop.** The reference deploy now serves at `https://blamejs.shop` instead of the `*.workers.dev` subdomain. README header now reads 'Homepage: **https://blamejs.shop**' and the admin-API curl example uses a placeholder `your-shop.example.com` host since operators replace it with their own. `wrangler.toml#D1_BRIDGE_URL` switches to `https://blamejs.shop` so the container's externalDb adapter calls back through the canonical origin. **Changed:** *README header — 'Homepage' instead of 'Live demo', custom domain* — `Homepage: **https://blamejs.shop**` replaces the previous `Live demo: **https://blamejs-shop.coocoo.workers.dev/**`. Operators evaluating the framework now see the canonical address. The admin-API curl example in the operator quick-start drops the placeholder `<your-worker>.workers.dev` host in favour of a `your-shop.example.com` placeholder with a comment pointing at the reference deploy. · *`wrangler.toml#D1_BRIDGE_URL` → `https://blamejs.shop`* — The container's externalDb D1 adapter posts SQL to `<D1_BRIDGE_URL><D1_BRIDGE_PATH>` (the Worker's service-binding bridge endpoint). Updating the base URL routes those internal calls through the custom domain. Cloudflare resolves custom domains to the same Worker that serves `*.workers.dev`, so the bridge keeps working with no router change.

package/lib/addresses.js

@@ -0,0 +1,430 @@
+"use strict";
+/**
+ * @module shop.addresses
+ * @title  Customer addresses primitive — saved shipping/billing book
+ *
+ * @intro
+ *   Persistent address book attached to a customer account. One row
+ *   per saved address; the customer (via the storefront) or the
+ *   operator (via admin) curates the list. The primitive owns the
+ *   `customer_addresses` table introduced in migration
+ *   `0026_customer_addresses.sql`.
+ *
+ *   Composition:
+ *     var addresses = bShop.addresses.create({ query: q });
+ *     var row = await addresses.add({
+ *       customer_id:    customer.id,
+ *       recipient_name: "Jane Doe",
+ *       street_line1:   "123 Main St",
+ *       city:           "Springfield",
+ *       postal_code:    "97001",
+ *       country:        "US",
+ *       is_default_shipping: true,
+ *     });
+ *     var ship = await addresses.defaultShipping(customer.id);
+ *
+ *   Default-flag uniqueness is enforced at write time inside `.add`,
+ *   `.update`, `.setDefaultShipping`, and `.setDefaultBilling`. Each
+ *   call clears the matching flag on the customer's other
+ *   (non-archived) rows before promoting the named row, so the
+ *   "is there a default shipping address?" question always resolves
+ *   to zero or one row without a partial UNIQUE index.
+ *
+ *   `country` is ISO 3166-1 alpha-2 — two uppercase letters. The
+ *   primitive enforces the character class with `/^[A-Z]{2}$/`;
+ *   strict country-list membership (e.g. excluding retired codes or
+ *   restricted-jurisdiction subdivisions) is operator policy and
+ *   layers on top.
+ *
+ *   `phone` is optional E.164-ish — leading `+` is permitted, the
+ *   first digit must be non-zero, and the digit run is 2-15 long.
+ *   Storage is plaintext so the operator can display the number back
+ *   to staff during outbound contact.
+ *
+ *   `is_archived` is the soft-delete flag. Archived rows are excluded
+ *   from `listForCustomer` / `defaultShipping` / `defaultBilling` /
+ *   `matchByContent` by default — passing `include_archived: true`
+ *   to `listForCustomer` opts them back in for an admin audit.
+ *   Archived rows can be promoted back via `.unarchive`.
+ *
+ * @related  customers, checkout
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+var MAX_LABEL_LEN          = 64;
+var MAX_RECIPIENT_NAME_LEN = 128;
+var MAX_COMPANY_LEN        = 128;
+var MAX_STREET_LEN         = 256;
+var MAX_CITY_LEN           = 128;
+var MAX_REGION_LEN         = 128;
+var MAX_POSTAL_LEN         = 32;
+var MAX_PHONE_LEN          = 32;
+
+var COUNTRY_RE      = /^[A-Z]{2}$/;
+var PHONE_RE        = /^\+?[1-9]\d{1,14}$/;
+var CONTROL_BYTE_RE = /[\x00-\x1f\x7f]/;
+
+// ---- validators ---------------------------------------------------------
+
+function _uuid(s, label) {
+  try { return _b().guardUuid.sanitize(s, { profile: "strict" }); }
+  catch (e) { throw new TypeError("addresses: " + label + " — " + (e && e.message || "invalid UUID")); }
+}
+
+function _str(value, label, max, opts) {
+  opts = opts || {};
+  var required = opts.required !== false;
+  if (value == null) {
+    if (required) throw new TypeError("addresses: " + label + " is required");
+    return "";
+  }
+  if (typeof value !== "string") {
+    throw new TypeError("addresses: " + label + " must be a string");
+  }
+  var trimmed = value.trim();
+  if (required && !trimmed.length) {
+    throw new TypeError("addresses: " + label + " must be a non-empty string");
+  }
+  if (trimmed.length > max) {
+    throw new TypeError("addresses: " + label + " must be <= " + max + " characters");
+  }
+  if (CONTROL_BYTE_RE.test(trimmed)) {
+    throw new TypeError("addresses: " + label + " contains control bytes");
+  }
+  return trimmed;
+}
+
+function _country(value) {
+  if (typeof value !== "string" || !COUNTRY_RE.test(value)) {
+    throw new TypeError("addresses: country must be ISO 3166-1 alpha-2 (two uppercase letters)");
+  }
+  return value;
+}
+
+function _phone(value) {
+  if (value == null || value === "") return "";
+  if (typeof value !== "string") {
+    throw new TypeError("addresses: phone must be a string");
+  }
+  var trimmed = value.trim();
+  if (!trimmed.length) return "";
+  if (trimmed.length > MAX_PHONE_LEN) {
+    throw new TypeError("addresses: phone must be <= " + MAX_PHONE_LEN + " characters");
+  }
+  if (!PHONE_RE.test(trimmed)) {
+    throw new TypeError("addresses: phone must match E.164-ish shape (^\\+?[1-9]\\d{1,14}$)");
+  }
+  return trimmed;
+}
+
+function _bool(value, label) {
+  if (value == null) return 0;
+  if (value === true || value === 1)  return 1;
+  if (value === false || value === 0) return 0;
+  throw new TypeError("addresses: " + label + " must be a boolean");
+}
+
+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); };
+  }
+
+  // Clear the named default flag on every non-archived row for this
+  // customer EXCEPT the optionally-excluded id. Used before promoting
+  // a new default so the table's one-default-per-role invariant holds
+  // without a partial UNIQUE index.
+  async function _clearDefault(customerId, column, exceptId) {
+    var sql =
+      "UPDATE customer_addresses SET " + column + " = 0, updated_at = ?1 " +
+      "WHERE customer_id = ?2 AND " + column + " = 1 AND is_archived = 0";
+    var params = [_now(), customerId];
+    if (exceptId) {
+      sql += " AND id != ?3";
+      params.push(exceptId);
+    }
+    await query(sql, params);
+  }
+
+  async function _getRow(id) {
+    var r = await query("SELECT * FROM customer_addresses WHERE id = ?1", [id]);
+    return r.rows[0] || null;
+  }
+
+  return {
+    add: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("addresses.add: input object required");
+      }
+      var customerId    = _uuid(input.customer_id, "customer_id");
+      var label         = _str(input.label,         "label",         MAX_LABEL_LEN,          { required: false });
+      var recipientName = _str(input.recipient_name, "recipient_name", MAX_RECIPIENT_NAME_LEN);
+      var company       = _str(input.company,       "company",       MAX_COMPANY_LEN,        { required: false });
+      var streetLine1   = _str(input.street_line1,  "street_line1",  MAX_STREET_LEN);
+      var streetLine2   = _str(input.street_line2,  "street_line2",  MAX_STREET_LEN,         { required: false });
+      var city          = _str(input.city,          "city",          MAX_CITY_LEN);
+      var region        = _str(input.region,        "region",        MAX_REGION_LEN,         { required: false });
+      var postalCode    = _str(input.postal_code,   "postal_code",   MAX_POSTAL_LEN);
+      var country       = _country(input.country);
+      var phone         = _phone(input.phone);
+      var defShipping   = _bool(input.is_default_shipping, "is_default_shipping");
+      var defBilling    = _bool(input.is_default_billing,  "is_default_billing");
+
+      var id = _b().uuid.v7();
+      var ts = _now();
+
+      // Clear sibling defaults FIRST so the promotion lands cleanly.
+      if (defShipping) await _clearDefault(customerId, "is_default_shipping", null);
+      if (defBilling)  await _clearDefault(customerId, "is_default_billing",  null);
+
+      await query(
+        "INSERT INTO customer_addresses (" +
+        "  id, customer_id, label, recipient_name, company," +
+        "  street_line1, street_line2, city, region, postal_code, country, phone," +
+        "  is_default_shipping, is_default_billing, is_archived," +
+        "  created_at, updated_at" +
+        ") VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, 0, ?15, ?15)",
+        [
+          id, customerId, label, recipientName, company,
+          streetLine1, streetLine2, city, region, postalCode, country, phone,
+          defShipping, defBilling, ts,
+        ],
+      );
+      return await _getRow(id);
+    },
+
+    update: async function (addressId, patch) {
+      _uuid(addressId, "address_id");
+      if (!patch || typeof patch !== "object") {
+        throw new TypeError("addresses.update: patch object required");
+      }
+      var existing = await _getRow(addressId);
+      if (!existing) {
+        throw new TypeError("addresses.update: address " + addressId + " not found");
+      }
+
+      // Build the column list from whichever keys are actually
+      // present in the patch. Each branch validates the new value
+      // against the same rules `.add` applies. Keys absent from the
+      // patch are left untouched.
+      var sets = [];
+      var params = [];
+      function _push(col, val) {
+        params.push(val);
+        sets.push(col + " = ?" + params.length);
+      }
+
+      if (Object.prototype.hasOwnProperty.call(patch, "label")) {
+        _push("label", _str(patch.label, "label", MAX_LABEL_LEN, { required: false }));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "recipient_name")) {
+        _push("recipient_name", _str(patch.recipient_name, "recipient_name", MAX_RECIPIENT_NAME_LEN));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "company")) {
+        _push("company", _str(patch.company, "company", MAX_COMPANY_LEN, { required: false }));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "street_line1")) {
+        _push("street_line1", _str(patch.street_line1, "street_line1", MAX_STREET_LEN));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "street_line2")) {
+        _push("street_line2", _str(patch.street_line2, "street_line2", MAX_STREET_LEN, { required: false }));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "city")) {
+        _push("city", _str(patch.city, "city", MAX_CITY_LEN));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "region")) {
+        _push("region", _str(patch.region, "region", MAX_REGION_LEN, { required: false }));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "postal_code")) {
+        _push("postal_code", _str(patch.postal_code, "postal_code", MAX_POSTAL_LEN));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "country")) {
+        _push("country", _country(patch.country));
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "phone")) {
+        _push("phone", _phone(patch.phone));
+      }
+
+      var promoteShipping = false;
+      var promoteBilling  = false;
+      if (Object.prototype.hasOwnProperty.call(patch, "is_default_shipping")) {
+        var ds = _bool(patch.is_default_shipping, "is_default_shipping");
+        _push("is_default_shipping", ds);
+        promoteShipping = ds === 1;
+      }
+      if (Object.prototype.hasOwnProperty.call(patch, "is_default_billing")) {
+        var db = _bool(patch.is_default_billing, "is_default_billing");
+        _push("is_default_billing", db);
+        promoteBilling = db === 1;
+      }
+
+      if (!sets.length) return existing;
+
+      // Clear sibling defaults BEFORE the row's own update so we
+      // don't accidentally clear the freshly-promoted row.
+      if (promoteShipping) await _clearDefault(existing.customer_id, "is_default_shipping", addressId);
+      if (promoteBilling)  await _clearDefault(existing.customer_id, "is_default_billing",  addressId);
+
+      _push("updated_at", _now());
+      params.push(addressId);
+      await query(
+        "UPDATE customer_addresses SET " + sets.join(", ") + " WHERE id = ?" + params.length,
+        params,
+      );
+      return await _getRow(addressId);
+    },
+
+    get: async function (addressId) {
+      _uuid(addressId, "address_id");
+      return await _getRow(addressId);
+    },
+
+    // Default ordering: default-shipping rows first, then
+    // default-billing, then by created_at DESC. The operator-facing
+    // contract is "the customer's most recent / most-blessed
+    // addresses surface at the top of an account-page render".
+    listForCustomer: async function (customerId, listOpts) {
+      _uuid(customerId, "customer_id");
+      listOpts = listOpts || {};
+      var includeArchived = listOpts.include_archived === true;
+      var sql =
+        "SELECT * FROM customer_addresses " +
+        "WHERE customer_id = ?1" +
+        (includeArchived ? "" : " AND is_archived = 0") +
+        " ORDER BY is_default_shipping DESC, is_default_billing DESC, created_at DESC";
+      var r = await query(sql, [customerId]);
+      return r.rows;
+    },
+
+    defaultShipping: async function (customerId) {
+      _uuid(customerId, "customer_id");
+      var r = await query(
+        "SELECT * FROM customer_addresses " +
+        "WHERE customer_id = ?1 AND is_default_shipping = 1 AND is_archived = 0 " +
+        "LIMIT 1",
+        [customerId],
+      );
+      return r.rows[0] || null;
+    },
+
+    defaultBilling: async function (customerId) {
+      _uuid(customerId, "customer_id");
+      var r = await query(
+        "SELECT * FROM customer_addresses " +
+        "WHERE customer_id = ?1 AND is_default_billing = 1 AND is_archived = 0 " +
+        "LIMIT 1",
+        [customerId],
+      );
+      return r.rows[0] || null;
+    },
+
+    archive: async function (addressId) {
+      _uuid(addressId, "address_id");
+      var existing = await _getRow(addressId);
+      if (!existing) return false;
+      // Archiving the current default for a role also drops the flag
+      // — leaving an archived row as the "default" would let the
+      // listForCustomer / defaultShipping pair disagree on whether a
+      // default exists.
+      await query(
+        "UPDATE customer_addresses SET is_archived = 1, " +
+        "is_default_shipping = 0, is_default_billing = 0, updated_at = ?1 " +
+        "WHERE id = ?2",
+        [_now(), addressId],
+      );
+      return true;
+    },
+
+    unarchive: async function (addressId) {
+      _uuid(addressId, "address_id");
+      var existing = await _getRow(addressId);
+      if (!existing) return false;
+      await query(
+        "UPDATE customer_addresses SET is_archived = 0, updated_at = ?1 WHERE id = ?2",
+        [_now(), addressId],
+      );
+      return true;
+    },
+
+    setDefaultShipping: async function (addressId) {
+      _uuid(addressId, "address_id");
+      var existing = await _getRow(addressId);
+      if (!existing) {
+        throw new TypeError("addresses.setDefaultShipping: address " + addressId + " not found");
+      }
+      if (existing.is_archived === 1) {
+        throw new TypeError("addresses.setDefaultShipping: address is archived — unarchive first");
+      }
+      await _clearDefault(existing.customer_id, "is_default_shipping", addressId);
+      await query(
+        "UPDATE customer_addresses SET is_default_shipping = 1, updated_at = ?1 WHERE id = ?2",
+        [_now(), addressId],
+      );
+      return await _getRow(addressId);
+    },
+
+    setDefaultBilling: async function (addressId) {
+      _uuid(addressId, "address_id");
+      var existing = await _getRow(addressId);
+      if (!existing) {
+        throw new TypeError("addresses.setDefaultBilling: address " + addressId + " not found");
+      }
+      if (existing.is_archived === 1) {
+        throw new TypeError("addresses.setDefaultBilling: address is archived — unarchive first");
+      }
+      await _clearDefault(existing.customer_id, "is_default_billing", addressId);
+      await query(
+        "UPDATE customer_addresses SET is_default_billing = 1, updated_at = ?1 WHERE id = ?2",
+        [_now(), addressId],
+      );
+      return await _getRow(addressId);
+    },
+
+    // Operator-side dedup helper. The address book grows quickly when
+    // a customer types a slight variation of an address they already
+    // have saved (extra apartment number, different casing on city,
+    // etc.); the storefront uses this to surface "you already have an
+    // address with this postal_code + country" before the customer
+    // confirms the save. Returns every non-archived row that matches
+    // the customer + postal_code + country triple — the caller
+    // decides whether the recipient_name / street_line1 are close
+    // enough to merge.
+    matchByContent: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("addresses.matchByContent: input object required");
+      }
+      var customerId = _uuid(input.customer_id, "customer_id");
+      var postal     = _str(input.postal_code,  "postal_code", MAX_POSTAL_LEN);
+      var country    = _country(input.country);
+      var r = await query(
+        "SELECT * FROM customer_addresses " +
+        "WHERE customer_id = ?1 AND postal_code = ?2 AND country = ?3 AND is_archived = 0 " +
+        "ORDER BY created_at DESC",
+        [customerId, postal, country],
+      );
+      return r.rows;
+    },
+  };
+}
+
+module.exports = {
+  create:                  create,
+  MAX_LABEL_LEN:           MAX_LABEL_LEN,
+  MAX_RECIPIENT_NAME_LEN:  MAX_RECIPIENT_NAME_LEN,
+  MAX_COMPANY_LEN:         MAX_COMPANY_LEN,
+  MAX_STREET_LEN:          MAX_STREET_LEN,
+  MAX_CITY_LEN:            MAX_CITY_LEN,
+  MAX_REGION_LEN:          MAX_REGION_LEN,
+  MAX_POSTAL_LEN:          MAX_POSTAL_LEN,
+  MAX_PHONE_LEN:           MAX_PHONE_LEN,
+};