@blamejs/blamejs-shop 0.4.113 → 0.4.114

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.114 (2026-06-26) — **A mid-cycle subscription downgrade now issues the proration credit the customer is owed instead of dropping it.** When a subscription plan changed mid-billing-period to a cheaper plan, the credit for the outgoing plan's unused time exceeded the incoming plan's partial-period charge — and that net credit was silently discarded. The proration adjustment is recorded as a single invoice whose amount is the net of charge minus credit, and a negative net (the downgrade case) was clamped to zero with no mechanism to apply the remainder, so the customer lost the money they were owed. A mid-cycle downgrade now issues that owed credit to the customer's store-credit ledger. The plan-change component takes an optional storeCredit handle for this; when a downgrade owes a credit and no handle is wired, the change is refused (an immediate change throws before any state changes) or left pending (a scheduled change is skipped and retried on a later sweep) rather than applied with the credit lost. Upgrades and same-price changes are unchanged. **Fixed:** *Mid-cycle plan downgrade credit is issued to store credit, not dropped* — A subscription plan change splits the proration into a charge (billed through the invoice ledger) and a credit (the unused remainder of the outgoing plan). For a downgrade the credit exceeds the charge, and the invoice — which can only carry a charge — clamped the negative net to zero, so the owed remainder was silently lost. The plan-change component now issues that remainder (proration credit minus the partial-period charge) to the customer's hash-chained store-credit ledger, correlated to the change that produced it and gated on the same atomic transition claim that prevents double application. The credit is settled as part of winning that claim: if the store-credit write fails (a transient error), the plan transition is rolled back and the change is left reclaimable so a retry settles it cleanly — the credit is never finalized as lost. The proration invoice still records the (zero) charge, so a downgrade never overcharges. · *A downgrade with no credit vehicle is refused, not applied with the credit lost* — The plan-change component accepts an optional storeCredit handle. When a downgrade owes a credit but no handle is wired, an immediate change is refused before any row is written or plan transition is applied (the call throws), and a scheduled change is left pending and retried on a later sweep once a handle is available — never transitioned with the credit dropped. Operators composing the plan-change component should wire the store-credit handle to enable mid-cycle downgrades.
+
 - v0.4.113 (2026-06-26) — **VAT-ID validation and EU reverse-charge now handle Greece's EL prefix and Switzerland's CHE prefix correctly.** Two related correctness fixes in the tax module's VAT handling. The bare VAT number returned by validateVatId was corrupted for Greek and Swiss IDs: it dropped the leading digit of a Greek number when the caller passed the ISO code "GR", and it left a stray "E" on a Swiss number — because the prefix was guessed by length instead of taken from the registry's actual prefix (Greece files its EU VAT under "EL", Switzerland under "CHE"). Separately, the intra-EU B2B reverse charge was always denied to Greek parties: the country was derived from the VAT-ID prefix ("EL") and checked against the EU member list, which is keyed by the ISO code ("GR"), with no alias normalization — so a Greek buyer or seller was treated as non-EU and charged standard VAT where EU law requires 0% with reverse charge. Both paths now canonicalize the EL/GR alias and strip the exact registry prefix. Every other country, and a genuine VAT-ID/country mismatch, behaves exactly as before. **Fixed:** *EU reverse-charge is no longer wrongly denied to Greek (EL) VAT IDs* — applyReverseCharge derives a party's country from the first characters of its VAT ID. Greek EU VAT IDs carry the prefix "EL" while Greece's ISO 3166-1 code is "GR", and the EU-membership check is keyed by ISO code — so a Greek seller, or a Greek buyer (whether the country was supplied as "GR" or "EL"), was classified as non-EU and refused the reverse charge, causing standard VAT to be invoiced on a transaction where EU law requires 0% with the buyer self-assessing. The derived prefix and the declared country are now canonicalized (EL is treated as GR) before the EU-membership and prefix-match checks. A genuine mismatch — a non-Greek VAT ID declared against a GR country, or vice versa — is still refused. · *validateVatId returns the exact bare number for Greek (EL) and Swiss (CHE) IDs* — The bare VAT number was produced by guessing the prefix length (2 vs 3 characters) rather than using the registry's actual prefix. For a Greek ID queried under the ISO code "GR" this dropped the first digit of the number; for a Swiss "CHE…" ID it left the "E" attached. The prefix is now taken from the registry — "EL" for Greece (ISO "GR"), "CHE" for Switzerland (ISO "CH"), and the two-letter ISO code for every other registry — so the returned number that prints on a reverse-charge invoice is exact. IDs whose registered number itself begins with letters (Austria's U, France's two-character lead, Spain's alphanumeric) are unaffected.
 
 - v0.4.112 (2026-06-26) — **The edge Stripe-webhook signature check now uses the framework's hardened verifier instead of a hand-rolled parse.** The Cloudflare edge worker verifies the Stripe webhook signature before forwarding a delivery to the container. That edge check previously parsed the `t=`/`v1=` signature header and compared the HMAC by hand. It now composes the framework's Stripe-signature verifier (HMAC-SHA256, the scheme Stripe publishes), which adds a bound on the signature-header size and on each `v1` hex length (so a malformed or oversized header is rejected cheaply), refuses a tolerance window below 30 seconds, matches across every `v1` signature a header carries, and compares in constant time. The container still re-verifies the same signature authoritatively, so this is a stricter front-line filter, not the only line of defense. Valid Stripe deliveries verify exactly as before; an unsigned, tampered, replayed, or oversized delivery is now refused at the edge by the same hardened code path the container uses. No configuration changes and no operator action required. **Changed:** *Edge Stripe-webhook verification composes the framework's hardened signature verifier* — The edge worker's inbound Stripe-signature pre-check no longer hand-parses the `t=`/`v1=` header and hand-compares the HMAC. It now calls the framework's Stripe verifier (HMAC-SHA256 over `<timestamp>.<body>`, the format Stripe documents), which applies a signature-header size cap, a per-`v1` hex-length cap, a minimum 30-second tolerance floor, matching across all `v1` signatures present, and a constant-time digest comparison — then forwards to the container, which re-verifies authoritatively (defense in depth). Valid deliveries are unaffected; unsigned, tampered, replayed, or oversized deliveries are refused at the edge before any container resource is touched. The framework's webhook module resolves its outbound HTTP client and delivery dispatcher only on the send path, so importing it solely to verify an inbound signature pulls no networking into the edge bundle.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.113",
+  "version": "0.4.114",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/plan-changes.js

@@ -130,6 +130,8 @@ function _now() { return Date.now(); }
 // caller's validation upstream (proposeChange) refuses those shapes
 // before they reach here, but the function stays defensive so a
 // future direct caller can't divide-by-zero through it.
+function _max0(n) { return n < 0 ? 0 : n; }
+
 function _prorate(fromAmount, toAmount, periodStart, periodEnd, effectiveAt) {
   var periodMs = periodEnd - periodStart;
   if (periodMs <= 0) {
@@ -168,6 +170,18 @@ function create(opts) {
   // a parallel surface.
   var billingHandle = opts.subscriptionBilling || null;
 
+  // `storeCredit` is the vehicle for the credit a mid-cycle DOWNGRADE
+  // leaves the customer holding: when the outgoing plan's unused
+  // remainder exceeds the incoming plan's partial-period charge, the
+  // difference is money the customer is owed. The proration invoice can
+  // only carry a charge (it clamps a negative net to zero), so without a
+  // credit vehicle that remainder would be silently dropped. When a
+  // downgrade owes a credit, it is issued to this handle's hash-chained
+  // ledger; if the handle is absent the change is refused (executeChange
+  // throws) or left pending (applyScheduledChanges) rather than applied
+  // with the credit lost.
+  var storeCreditHandle = opts.storeCredit || null;
+
   async function _getSubscription(subscriptionId) {
     // Prefer the injected handle (production composition); fall back
     // to a direct read so tests that pass a minimal handle
@@ -198,6 +212,61 @@ function create(opts) {
     return r.rows[0] || null;
   }
 
+  // A downgrade taking effect now owes the customer a credit the invoice
+  // ledger cannot carry. Refuse if there is no vehicle to pay it.
+  function _assertCreditable(creditMinor) {
+    if (creditMinor > 0 && !storeCreditHandle) {
+      throw new TypeError(
+        "planChanges: a mid-cycle downgrade owes a " + creditMinor +
+        "-minor store credit, but no storeCredit handle was provided to " +
+        "planChanges.create — wire one or schedule the change to next_billing_cycle"
+      );
+    }
+  }
+
+  // Issue the credit a won downgrade owes to the customer's store-credit
+  // ledger. The won-transition claim makes this exactly-once; the caller
+  // pairs it with a revert-on-throw so a transient write failure cannot
+  // finalize a downgrade whose credit was never paid (the credit is the
+  // customer's money — it must be retryable, not lost). _assertCreditable
+  // (executeChange) / the pre-claim skip (applyScheduledChanges) guarantee
+  // storeCreditHandle is present whenever creditMinor > 0.
+  async function _issueDowngradeCredit(o) {
+    await storeCreditHandle.credit({
+      customer_id:  o.customerId,
+      amount_minor: o.creditMinor,
+      source:       "refund",
+      // Correlates the credit row to the plan-change that produced it.
+      source_ref:   "subscription-downgrade:" + o.planChangeId,
+    });
+  }
+
+  // Record the proration charge through the invoice ledger. Drop-silent —
+  // recordInvoice is an optional dashboard record, so a failure must not
+  // crash the transition that landed; the caller observes the gap through
+  // the billing ledger query. (The owed CREDIT, by contrast, is never
+  // dropped — see _issueDowngradeCredit + the callers' revert-on-throw.)
+  async function _recordProrationInvoice(o) {
+    if (!billingHandle || typeof billingHandle.recordInvoice !== "function") return;
+    try {
+      // Plans store currency lowercase ('usd'); recordInvoice expects
+      // uppercase ISO 4217. Normalize at the boundary.
+      await billingHandle.recordInvoice({
+        subscription_id: o.subscriptionId,
+        period_start:    o.periodStart,
+        period_end:      o.periodEnd,
+        amount_minor:    o.chargeMinor,
+        currency:        String(o.currency).toUpperCase(),
+        // Deterministic idempotency key — the change applies once, so a
+        // re-run dedupes against the UNIQUE processor_invoice_id rather
+        // than writing a second proration invoice.
+        processor_invoice_id: "planchange:" + o.planChangeId,
+      });
+    } catch (_e) {
+      // Drop-silent — by design.
+    }
+  }
+
   return {
     CHANGE_KINDS:    CHANGE_KINDS.slice(),
     STATUSES:        STATUSES.slice(),
@@ -326,6 +395,12 @@ function create(opts) {
       var sub = await _getSubscription(subscriptionId);
       var id  = b.uuid.v7();
       var ts  = _now();
+      // Split the proration into the charge (billed via the invoice
+      // ledger) and the credit (owed to the customer). Exactly one is
+      // non-zero: an upgrade charges the difference, a downgrade leaves
+      // the customer in credit for the outgoing plan's unused remainder.
+      var chargeMinor = _max0(proposed.first_charge_minor - proposed.proration_credit_minor);
+      var creditMinor = _max0(proposed.proration_credit_minor - proposed.first_charge_minor);
       // Status: `executed` when the effective clock is now-or-past,
       // `pending` when the change is queued for a future clock
       // (typically next_billing_cycle but also any future
@@ -334,6 +409,13 @@ function create(opts) {
       var status      = proposed.effective_at <= ts ? "executed" : "pending";
       var executedAt  = status === "executed" ? ts : null;
 
+      // Fail closed: a downgrade taking effect now owes the customer a
+      // credit, and the store-credit ledger is the only vehicle for it.
+      // Refuse before any row is written rather than apply the transition
+      // and silently drop the credit. (A future-dated downgrade is left
+      // pending; applyScheduledChanges re-checks at execution time.)
+      if (status === "executed") _assertCreditable(creditMinor);
+
       await query(
         "INSERT INTO subscription_plan_changes " +
         "(id, subscription_id, from_plan_id, to_plan_id, change_kind, status, " +
@@ -361,39 +443,41 @@ function create(opts) {
           [newPlanId, ts, subscriptionId, sub.plan_id],
         );
         var wonTransition = Number((planUpd && planUpd.rowCount) || 0) > 0;
-        if (wonTransition && billingHandle && typeof billingHandle.recordInvoice === "function") {
-          // Queue the proration adjustment as a single invoice row.
-          // The amount is the net (first_charge - credit); negative
-          // nets clamp to zero (the credit covers the partial-period
-          // charge in full — the unused remainder becomes a future-
-          // period credit the operator surfaces through a separate
-          // ledger entry outside this primitive's surface).
-          var net = proposed.first_charge_minor - proposed.proration_credit_minor;
-          if (net < 0) net = 0;
-          try {
-            // The `subscription_plans` table stores currency
-            // lowercase (`'usd'`); `subscriptionBilling.recordInvoice`
-            // expects uppercase ISO 4217. Normalize at the boundary
-            // so callers don't have to know the casing dialect each
-            // primitive picked.
-            await billingHandle.recordInvoice({
-              subscription_id: subscriptionId,
-              period_start:    proposed.effective_at,
-              period_end:      sub.current_period_end,
-              amount_minor:    net,
-              currency:        proposed.currency.toUpperCase(),
-              // Deterministic idempotency key keyed on this change row so
-              // a re-applied change dedupes against the UNIQUE
-              // processor_invoice_id instead of double-billing.
-              processor_invoice_id: "planchange:" + id,
-            });
-          } catch (_e) {
-            // Drop-silent — by design. The billing handle is an
-            // optional composition; a recordInvoice failure must not
-            // crash executeChange (the plan transition itself
-            // landed). The caller observes the invoice gap through
-            // the billing handle's own ledger query.
+        if (wonTransition) {
+          if (creditMinor > 0) {
+            try {
+              await _issueDowngradeCredit({
+                customerId:   sub.customer_id,
+                creditMinor:  creditMinor,
+                planChangeId: id,
+              });
+            } catch (e) {
+              // Revert-on-throw: the credit is the customer's money, so a
+              // transient write failure must not finalize a downgrade it
+              // was never paid for. Roll the subscription back to the
+              // outgoing plan (guarded on the just-applied plan id so a
+              // concurrent change isn't clobbered) and void this change,
+              // then rethrow so the caller retries from a clean state.
+              await query(
+                "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
+                [sub.plan_id, _now(), subscriptionId, newPlanId],
+              );
+              await query(
+                "UPDATE subscription_plan_changes SET status = 'cancelled', cancelled_at = ?1, " +
+                "cancel_reason = ?2 WHERE id = ?3",
+                [_now(), "credit-settlement-failed", id],
+              );
+              throw e;
+            }
           }
+          await _recordProrationInvoice({
+            subscriptionId: subscriptionId,
+            chargeMinor:    chargeMinor,
+            currency:       proposed.currency,
+            periodStart:    proposed.effective_at,
+            periodEnd:      sub.current_period_end,
+            planChangeId:   id,
+          });
         }
       }
 
@@ -472,6 +556,14 @@ function create(opts) {
       var executed = [];
       for (var i = 0; i < due.rows.length; i += 1) {
         var row = due.rows[i];
+        var chargeMinor = _max0(row.first_charge_minor - row.proration_credit_minor);
+        var creditMinor = _max0(row.proration_credit_minor - row.first_charge_minor);
+        // Fail closed: a due downgrade owes the customer a credit. If no
+        // store-credit vehicle is wired, leave the row PENDING (skip
+        // before claiming) so it applies on a later sweep once the handle
+        // exists — never transition it and drop the credit.
+        if (creditMinor > 0 && !storeCreditHandle) continue;
+
         // Atomic claim: flip pending -> executed gated on the status.
         // Two overlapping scheduler runs (cron overrun, retry, two
         // workers) both SELECT the same due row; WITHOUT this guard both
@@ -491,31 +583,42 @@ function create(opts) {
           "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3",
           [row.to_plan_id, now, row.subscription_id],
         );
-        if (billingHandle && typeof billingHandle.recordInvoice === "function") {
-          var net = row.first_charge_minor - row.proration_credit_minor;
-          if (net < 0) net = 0;
-          var subRow = await _getSubscription(row.subscription_id);
-          var periodEnd = subRow && subRow.current_period_end != null
-            ? subRow.current_period_end : row.effective_at;
+        var subRow = await _getSubscription(row.subscription_id);
+        var periodEnd = subRow && subRow.current_period_end != null
+          ? subRow.current_period_end : row.effective_at;
+        if (creditMinor > 0) {
           try {
-            // Same casing-normalization the synchronous executeChange
-            // path runs — plans store currency lowercase, billing
-            // expects uppercase.
-            await billingHandle.recordInvoice({
-              subscription_id: row.subscription_id,
-              period_start:    row.effective_at,
-              period_end:      periodEnd,
-              amount_minor:    net,
-              currency:        String(row.currency).toUpperCase(),
-              // Deterministic idempotency key — this change applies once,
-              // so a re-run dedupes against the UNIQUE processor_invoice_id
-              // rather than writing a second proration invoice.
-              processor_invoice_id: "planchange:" + row.id,
+            await _issueDowngradeCredit({
+              customerId:   subRow ? subRow.customer_id : null,
+              creditMinor:  creditMinor,
+              planChangeId: row.id,
             });
           } catch (_e) {
-            // Drop-silent — see executeChange.
+            // Revert-on-throw, then carry on with the batch: the credit is
+            // the customer's money, so a transient write failure must not
+            // finalize this downgrade. Roll the plan back and return the row
+            // to 'pending' (guarded on the just-applied state) so a later
+            // sweep retries it cleanly; one bad row must not abort the run.
+            await query(
+              "UPDATE subscriptions SET plan_id = ?1, updated_at = ?2 WHERE id = ?3 AND plan_id = ?4",
+              [row.from_plan_id, now, row.subscription_id, row.to_plan_id],
+            );
+            await query(
+              "UPDATE subscription_plan_changes SET status = 'pending', executed_at = NULL " +
+              "WHERE id = ?1 AND status = 'executed'",
+              [row.id],
+            );
+            continue;
           }
         }
+        await _recordProrationInvoice({
+          subscriptionId: row.subscription_id,
+          chargeMinor:    chargeMinor,
+          currency:       row.currency,
+          periodStart:    row.effective_at,
+          periodEnd:      periodEnd,
+          planChangeId:   row.id,
+        });
         executed.push(await _getById(row.id));
       }
       return executed;

package/package.json

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