@aglyn/plugins-commerce 1.0.0-beta.143

package/src/lib/model/commerce-connect-transfer.js

@@ -0,0 +1,231 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * How a storefront destination charge splits between Aglyn and the merchant —
+ * and, when Stripe Tax is on, why the split cannot be expressed as a fee
+ * (AGL-1956).
+ *
+ * ## The defect this module exists to close
+ *
+ * Every storefront checkout is a DESTINATION charge created on AGLYN's
+ * platform account: platform secret key, no `Stripe-Account` header, no
+ * `on_behalf_of`, with `payment_intent_data[transfer_data][destination]`
+ * naming the merchant's connected account. On a `mode: 'stripe'` store the
+ * session also carries `automatic_tax[enabled]`, and AGL-1904 MEASURED what
+ * that means: the tax is computed against **Aglyn's** registrations, reported
+ * as `automatic_tax.liability: { type: "self" }`, and is **Aglyn's to remit**.
+ * See `../server/storefront-tax.ts` for the two-arm experiment.
+ *
+ * The sessions then set `payment_intent_data[application_fee_amount]`. On a
+ * destination charge that form means Stripe transfers the **whole charge** to
+ * the connected account and debits the fee at the destination — measured, and
+ * recorded at `billing-webhook.ts` (the AGL-1794 note: "`transfer.amount`
+ * equals `charge.amount`"). `amount_total` INCLUDES the Stripe Tax.
+ *
+ * So on every taxed storefront sale the sales tax Aglyn owes the state was
+ * transferred to the merchant, and only the commission came back. Aglyn was
+ * left holding the liability and none of the money. This is the same trap the
+ * marketplace plugin found and closed in AGL-1544, and the fix here is the
+ * same one: **a fixed `transfer_data[amount]`, and no `application_fee_amount`
+ * at all** — because the fee form makes Stripe do the arithmetic on a total
+ * that has the tax inside it.
+ *
+ * ## Only ONE of the two knobs may do the arithmetic
+ *
+ * `application_fee_amount` says "give the merchant everything except this".
+ * `transfer_data[amount]` says "give the merchant exactly this". They are two
+ * spellings of the same split and Stripe rejects a PaymentIntent carrying
+ * both, so the emitter below is written as a single choice with no path that
+ * can emit the pair. Which one is correct depends entirely on WHICH SIDE of
+ * the split holds the unknown:
+ *
+ *   - **Merchant owes the tax** (`manual` mode, or no tax at all). The
+ *     variable part — the merchant's tax line — is the merchant's own money.
+ *     Fixing the FEE is exact: Aglyn keeps its commission and every cent of
+ *     variance stays where it belongs.
+ *   - **Aglyn owes the tax** (`stripe` mode). The variable part is now
+ *     AGLYN's money, and a fixed fee hands all of it to the merchant. Fixing
+ *     the TRANSFER is what keeps it.
+ *
+ * ## The residual, stated out loud: shopper-chosen shipping
+ *
+ * Neither knob can be exact on a Stripe Tax sale that also offers a CHOICE of
+ * shipping rates, because at session-creation time two numbers are unknown —
+ * the tax (Aglyn's) and which shipping option the shopper will pick (the
+ * merchant's) — and there is only one knob left to fix. Whichever is fixed,
+ * the other side's variance lands on the wrong party:
+ *
+ *   - Fixing the FEE misallocates the ENTIRE tax, on EVERY taxed sale,
+ *     unbounded. That is the defect above.
+ *   - Fixing the TRANSFER misallocates at most `dearest − cheapest` shipping,
+ *     and only on a store that offers more than one rate.
+ *
+ * The transfer is therefore fixed at the CHEAPEST option, never the dearest.
+ * Not a preference — the dearest is unsafe: a transfer of
+ * `goods + dearest − fee` can EXCEED a charge where the shopper picked the
+ * cheapest, and Stripe rejects a transfer larger than its charge, which would
+ * fail the payment outright rather than mis-split it. The cheapest is always
+ * payable, because the shopper's actual shipping can only be higher.
+ *
+ * The bounded remainder — a shopper who upgraded shipping on a Stripe Tax
+ * store — is money owed to the MERCHANT that Aglyn is holding. It is recorded
+ * on the session as `metadata[transferCents]` and
+ * `metadata[transferShippingCents]` so it is derivable per order rather than
+ * lost, and closing it needs a top-up transfer at
+ * `checkout.session.completed`, which is a new outbound money path and is
+ * deliberately NOT bundled with this fix. Tracked on AGL-1956.
+ *
+ * Pure and total: integer cents in, integer cents out, no clamping surprises
+ * except the documented floor at zero.
+ */ /** Which party's registrations the tax on this sale was computed against. */ import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * What the merchant is paid, in cents, when AGLYN owes the tax.
+ *
+ * `goods + cheapest shipping − fee`, floored at zero. The floor is a real
+ * case, not defensive padding: `resolveTransactionFeeCents` adds Stripe's
+ * fixed 30¢ card cost, so a sub-dollar order can carry a fee worth more than
+ * the goods. The merchant is paid nothing on such an order, which is the
+ * honest outcome — Aglyn is out of pocket on it either way — and it must
+ * never be expressed as a NEGATIVE transfer, which Stripe rejects.
+ */ export function platformLiableTransferCents(split) {
+    var _split_merchantGoodsCents, _split_shippingFloorCents, _split_feeCents;
+    const goods = Math.max(0, Math.round(Number((_split_merchantGoodsCents = split.merchantGoodsCents) != null ? _split_merchantGoodsCents : 0)));
+    const shipping = Math.max(0, Math.round(Number((_split_shippingFloorCents = split.shippingFloorCents) != null ? _split_shippingFloorCents : 0)));
+    const fee = Math.max(0, Math.round(Number((_split_feeCents = split.feeCents) != null ? _split_feeCents : 0)));
+    return Math.max(0, goods + shipping - fee);
+}
+/**
+ * Which party's registrations a subscription invoice's tax was computed
+ * against — the same `taxOwner` distinction `destinationChargeParams` makes,
+ * read off the invoice instead of off the store's settings.
+ *
+ * `automatic_tax.enabled` is THE discriminator and the tax lines are never it,
+ * for the reason `storefront-tax.ts` states at length: a MANUAL-rate
+ * subscription carries a real Stripe Tax Rate on its line (AGL-1751), so every
+ * cycle it bills arrives with a populated `total_taxes[]` that is
+ * indistinguishable from a Stripe Tax one by shape. Reading the lines would
+ * reverse the merchant's OWN tax out of their payout on every cycle — the
+ * failure that steals from the merchant rather than from the state.
+ *
+ * `liability.type === 'account'` means Stripe computed against the CONNECTED
+ * account's registrations, so the tax is theirs and stays with them. `self`,
+ * and an absent liability (older API versions omit the field, where the only
+ * account a platform-created invoice could be liable under is the platform),
+ * mean Aglyn. This mirrors `storefrontTaxRow` exactly, deliberately: the filed
+ * tax record and the reversal must not be able to disagree about who owed it.
+ */ export function subscriptionInvoiceTaxOwner(invoice) {
+    var _source_automatic_tax, _source_automatic_tax_liability, _source_automatic_tax1;
+    const source = invoice;
+    if ((source == null ? void 0 : (_source_automatic_tax = source.automatic_tax) == null ? void 0 : _source_automatic_tax.enabled) !== true) return 'merchant';
+    return (source == null ? void 0 : (_source_automatic_tax1 = source.automatic_tax) == null ? void 0 : (_source_automatic_tax_liability = _source_automatic_tax1.liability) == null ? void 0 : _source_automatic_tax_liability.type) === 'account' ? 'merchant' : 'platform';
+}
+/** See `SubscriptionTaxReversalDecision`. */ export function subscriptionInvoiceTaxReversal(invoice) {
+    const source = invoice;
+    if (subscriptionInvoiceTaxOwner(source) === 'merchant') {
+        return {
+            kind: 'skip',
+            reason: 'merchant-tax'
+        };
+    }
+    const settle = (cents)=>cents > 0 ? {
+            kind: 'reverse',
+            taxCents: cents
+        } : {
+            kind: 'skip',
+            reason: 'no-tax'
+        };
+    // `typeof === 'number'` and NOT `Number(…)`, because `Number(null)` is a
+    // finite 0 and `null` is how an absent field arrives over JSON. Treating it
+    // as a stated zero is precisely the swallow this type exists to prevent.
+    const scalar = source == null ? void 0 : source.tax;
+    if (typeof scalar === 'number' && Number.isFinite(scalar)) {
+        return settle(Math.round(scalar));
+    }
+    // `total_taxes` replaced `total_tax_amounts`, which replaced the scalar; they
+    // do not coexist, so this cannot double-count.
+    const lines = Array.isArray(source == null ? void 0 : source.total_taxes) ? source.total_taxes : Array.isArray(source == null ? void 0 : source.total_tax_amounts) ? source.total_tax_amounts : null;
+    if (lines) {
+        let sum = 0;
+        for (const line of lines){
+            var _ref;
+            const amount = Number((_ref = line == null ? void 0 : line.amount) != null ? _ref : NaN);
+            // One unreadable line poisons the sum: a partial total would reverse
+            // LESS than the state is owed and look like a successful correction.
+            if (!Number.isFinite(amount)) {
+                return {
+                    kind: 'unreadable',
+                    reason: 'a tax line on the invoice states no readable `amount`'
+                };
+            }
+            sum += amount;
+        }
+        return settle(Math.round(sum));
+    }
+    return {
+        kind: 'unreadable',
+        reason: 'the invoice enables automatic tax but states no `tax`, `total_taxes` ' + 'or `total_tax_amounts` — the Stripe API version may have moved the field'
+    };
+}
+/**
+ * The cheapest rate on a resolved shipping plan, in cents. `0` for a plan with
+ * no options, which is also the right transfer contribution for a store that
+ * charges no shipping.
+ */ export function shippingFloorCents(options = []) {
+    if (options.length === 0) return 0;
+    return options.reduce((least, option)=>{
+        var _ref;
+        return Math.min(least, Math.max(0, Math.round(Number((_ref = option == null ? void 0 : option.amountCents) != null ? _ref : 0))));
+    }, Number.POSITIVE_INFINITY);
+}
+/**
+ * The Connect keys for a storefront destination charge — the destination, and
+ * EXACTLY ONE of `application_fee_amount` / `transfer_data[amount]`.
+ *
+ * Emitted from one place so no checkout path can pick the wrong knob on its
+ * own, and so the pair can never both appear (Stripe rejects that, and the two
+ * would be contradicting each other about the same split).
+ *
+ * The `metadata[transferCents]` companion is deliberately NOT emitted here —
+ * each caller owns its own metadata block, and the value is
+ * `platformLiableTransferCents(split)`.
+ */ export function destinationChargeParams(split) {
+    var _split_feeCents;
+    const destination = {
+        'payment_intent_data[transfer_data][destination]': String(split.accountId)
+    };
+    const fee = Math.max(0, Math.round(Number((_split_feeCents = split.feeCents) != null ? _split_feeCents : 0)));
+    if (split.taxOwner === 'platform') {
+        // AGLYN OWES THE TAX, SO AGLYN MUST KEEP IT (AGL-1956). A fixed transfer
+        // is the only form that expresses that: `application_fee_amount` would
+        // make Stripe compute `amount_total − fee`, and `amount_total` has the
+        // Stripe Tax inside it. Emitted even when it is zero — a zero transfer is
+        // a real, correct answer for a sub-dollar order (see
+        // `platformLiableTransferCents`), and OMITTING the key would silently
+        // restore the full-charge transfer this whole module exists to prevent.
+        return _extends({}, destination, {
+            'payment_intent_data[transfer_data][amount]': String(platformLiableTransferCents(split))
+        });
+    }
+    // The merchant owns the tax on this sale, so the merchant may hold it: the
+    // fee form is exact here and is left byte-identical to what these paths
+    // sent before AGL-1956. Stripe rejects a zero application fee, so a fee that
+    // rounded to nothing sends no key at all.
+    return _extends({}, destination, fee > 0 ? {
+        'payment_intent_data[application_fee_amount]': String(fee)
+    } : {});
+}
+
+//# sourceMappingURL=commerce-connect-transfer.js.map

package/src/lib/model/commerce-connect-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/commerce/src/lib/model/commerce-connect-transfer.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * How a storefront destination charge splits between Aglyn and the merchant —\n * and, when Stripe Tax is on, why the split cannot be expressed as a fee\n * (AGL-1956).\n *\n * ## The defect this module exists to close\n *\n * Every storefront checkout is a DESTINATION charge created on AGLYN's\n * platform account: platform secret key, no `Stripe-Account` header, no\n * `on_behalf_of`, with `payment_intent_data[transfer_data][destination]`\n * naming the merchant's connected account. On a `mode: 'stripe'` store the\n * session also carries `automatic_tax[enabled]`, and AGL-1904 MEASURED what\n * that means: the tax is computed against **Aglyn's** registrations, reported\n * as `automatic_tax.liability: { type: \"self\" }`, and is **Aglyn's to remit**.\n * See `../server/storefront-tax.ts` for the two-arm experiment.\n *\n * The sessions then set `payment_intent_data[application_fee_amount]`. On a\n * destination charge that form means Stripe transfers the **whole charge** to\n * the connected account and debits the fee at the destination — measured, and\n * recorded at `billing-webhook.ts` (the AGL-1794 note: \"`transfer.amount`\n * equals `charge.amount`\"). `amount_total` INCLUDES the Stripe Tax.\n *\n * So on every taxed storefront sale the sales tax Aglyn owes the state was\n * transferred to the merchant, and only the commission came back. Aglyn was\n * left holding the liability and none of the money. This is the same trap the\n * marketplace plugin found and closed in AGL-1544, and the fix here is the\n * same one: **a fixed `transfer_data[amount]`, and no `application_fee_amount`\n * at all** — because the fee form makes Stripe do the arithmetic on a total\n * that has the tax inside it.\n *\n * ## Only ONE of the two knobs may do the arithmetic\n *\n * `application_fee_amount` says \"give the merchant everything except this\".\n * `transfer_data[amount]` says \"give the merchant exactly this\". They are two\n * spellings of the same split and Stripe rejects a PaymentIntent carrying\n * both, so the emitter below is written as a single choice with no path that\n * can emit the pair. Which one is correct depends entirely on WHICH SIDE of\n * the split holds the unknown:\n *\n *   - **Merchant owes the tax** (`manual` mode, or no tax at all). The\n *     variable part — the merchant's tax line — is the merchant's own money.\n *     Fixing the FEE is exact: Aglyn keeps its commission and every cent of\n *     variance stays where it belongs.\n *   - **Aglyn owes the tax** (`stripe` mode). The variable part is now\n *     AGLYN's money, and a fixed fee hands all of it to the merchant. Fixing\n *     the TRANSFER is what keeps it.\n *\n * ## The residual, stated out loud: shopper-chosen shipping\n *\n * Neither knob can be exact on a Stripe Tax sale that also offers a CHOICE of\n * shipping rates, because at session-creation time two numbers are unknown —\n * the tax (Aglyn's) and which shipping option the shopper will pick (the\n * merchant's) — and there is only one knob left to fix. Whichever is fixed,\n * the other side's variance lands on the wrong party:\n *\n *   - Fixing the FEE misallocates the ENTIRE tax, on EVERY taxed sale,\n *     unbounded. That is the defect above.\n *   - Fixing the TRANSFER misallocates at most `dearest − cheapest` shipping,\n *     and only on a store that offers more than one rate.\n *\n * The transfer is therefore fixed at the CHEAPEST option, never the dearest.\n * Not a preference — the dearest is unsafe: a transfer of\n * `goods + dearest − fee` can EXCEED a charge where the shopper picked the\n * cheapest, and Stripe rejects a transfer larger than its charge, which would\n * fail the payment outright rather than mis-split it. The cheapest is always\n * payable, because the shopper's actual shipping can only be higher.\n *\n * The bounded remainder — a shopper who upgraded shipping on a Stripe Tax\n * store — is money owed to the MERCHANT that Aglyn is holding. It is recorded\n * on the session as `metadata[transferCents]` and\n * `metadata[transferShippingCents]` so it is derivable per order rather than\n * lost, and closing it needs a top-up transfer at\n * `checkout.session.completed`, which is a new outbound money path and is\n * deliberately NOT bundled with this fix. Tracked on AGL-1956.\n *\n * Pure and total: integer cents in, integer cents out, no clamping surprises\n * except the documented floor at zero.\n */\n\n/** Which party's registrations the tax on this sale was computed against. */\nexport type StorefrontTaxOwner = 'platform' | 'merchant'\n\nexport interface DestinationChargeSplit {\n  /** The merchant's connected account id. */\n  accountId: string\n  /**\n   * Aglyn's take in cents — the advertised platform fee plus the passed-through\n   * card cost (`resolveTransactionFeeCents`). Never negative.\n   */\n  feeCents: number\n  /**\n   * `platform` when the session carries `automatic_tax[enabled]` and Stripe\n   * Tax computes against Aglyn's registrations (AGL-1904). `merchant` for a\n   * `manual` rate the merchant set and owes, and for an untaxed sale.\n   */\n  taxOwner: StorefrontTaxOwner\n  /**\n   * What Stripe will charge for the GOODS — after any coupon is priced in, and\n   * excluding shipping and every tax line. The merchant's money.\n   */\n  merchantGoodsCents: number\n  /**\n   * The CHEAPEST shipping option offered on this session, or 0 when the\n   * merchant offers none. See the module note on why this is the cheapest and\n   * not the dearest.\n   */\n  shippingFloorCents?: number\n}\n\n/**\n * What the merchant is paid, in cents, when AGLYN owes the tax.\n *\n * `goods + cheapest shipping − fee`, floored at zero. The floor is a real\n * case, not defensive padding: `resolveTransactionFeeCents` adds Stripe's\n * fixed 30¢ card cost, so a sub-dollar order can carry a fee worth more than\n * the goods. The merchant is paid nothing on such an order, which is the\n * honest outcome — Aglyn is out of pocket on it either way — and it must\n * never be expressed as a NEGATIVE transfer, which Stripe rejects.\n */\nexport function platformLiableTransferCents(\n  split: Pick<\n    DestinationChargeSplit,\n    'feeCents' | 'merchantGoodsCents' | 'shippingFloorCents'\n  >,\n): number {\n  const goods = Math.max(0, Math.round(Number(split.merchantGoodsCents ?? 0)))\n  const shipping = Math.max(0, Math.round(Number(split.shippingFloorCents ?? 0)))\n  const fee = Math.max(0, Math.round(Number(split.feeCents ?? 0)))\n  return Math.max(0, goods + shipping - fee)\n}\n\n/**\n * What a paid SUBSCRIPTION invoice says about the tax on it, and therefore\n * whether the platform has to pull that tax back out of the transfer\n * (AGL-1956).\n *\n * ## Why the recurring path needs a different instrument entirely\n *\n * Everything above is about a knob set when the charge is CREATED. A Stripe\n * Subscription has neither knob: it accepts no `transfer_data[amount]`, only\n * `application_fee_percent`. On a destination charge that means Stripe\n * transfers the WHOLE charge to the connected account and debits the fee at\n * the destination, and the charge has the Stripe Tax inside it — so the\n * merchant is handed the state's money on every taxed cycle. `checkout.ts`\n * therefore excludes subscriptions from `destinationChargeParams` and leaves\n * them on the fee form.\n *\n * AGL-2317 makes that strictly worse, not better. It refunds the part of the\n * application fee that was taken on tax and shipping BACK to the connected\n * account, which is right on its own terms (Aglyn's advertised cut is a cut of\n * sales) but means the merchant ends the cycle holding **one hundred percent**\n * of a tax Aglyn is the one registered to remit.\n *\n * ## The money is already at the merchant, so the correction is a REVERSAL\n *\n * Worth stating explicitly, because the sign is easy to get backwards and this\n * module documents a residual that runs the OTHER way. The shipping residual\n * above is a case where the transfer was FIXED too low and the merchant is\n * owed more — that one needs a top-up. This is the opposite: the fee form\n * OVER-transfers, the tax is physically sitting in the connected account's\n * balance, and the only instrument that moves it back to the platform is a\n * transfer reversal. A top-up here would pay the merchant the tax twice.\n *\n * ## Three answers, never two\n *\n * The whole point of the three-state is that **a missing tax field must not\n * read as \"no tax\"**. Stripe removed the scalar `invoice.tax` in favour of\n * `total_taxes[]`, and which spelling an endpoint receives is dashboard\n * configuration this repo cannot see. A reader that reached for one field and\n * defaulted the miss to `0` would answer \"no reversal\" on every invoice after\n * a Stripe version bump nobody here can observe — a swallowed read rendering\n * as a measured zero, with the money going the wrong way and nothing looking\n * wrong. So an invoice that claims automatic tax while stating NO tax field at\n * all is `unreadable`, and the caller is required to make noise about it.\n *\n * A `tax: 0`, or a present-but-empty `total_taxes: []`, is a real answer and\n * is `skip`. That is also what a $0 or fully-discounted invoice produces, which\n * is why the no-op costs nothing.\n *\n * Pure and total: no throw, no clamping beyond the documented floor at zero.\n */\nexport type SubscriptionTaxReversalDecision =\n  /** Aglyn owes this tax and the merchant is holding it. Pull back exactly this. */\n  | { kind: 'reverse'; taxCents: number }\n  /** Nothing to do, and nothing wrong. No network call is warranted. */\n  | { kind: 'skip'; reason: 'merchant-tax' | 'no-tax' }\n  /** The invoice claims tax it will not state. LOUD, never silent. */\n  | { kind: 'unreadable'; reason: string }\n\n/**\n * Which party's registrations a subscription invoice's tax was computed\n * against — the same `taxOwner` distinction `destinationChargeParams` makes,\n * read off the invoice instead of off the store's settings.\n *\n * `automatic_tax.enabled` is THE discriminator and the tax lines are never it,\n * for the reason `storefront-tax.ts` states at length: a MANUAL-rate\n * subscription carries a real Stripe Tax Rate on its line (AGL-1751), so every\n * cycle it bills arrives with a populated `total_taxes[]` that is\n * indistinguishable from a Stripe Tax one by shape. Reading the lines would\n * reverse the merchant's OWN tax out of their payout on every cycle — the\n * failure that steals from the merchant rather than from the state.\n *\n * `liability.type === 'account'` means Stripe computed against the CONNECTED\n * account's registrations, so the tax is theirs and stays with them. `self`,\n * and an absent liability (older API versions omit the field, where the only\n * account a platform-created invoice could be liable under is the platform),\n * mean Aglyn. This mirrors `storefrontTaxRow` exactly, deliberately: the filed\n * tax record and the reversal must not be able to disagree about who owed it.\n */\nexport function subscriptionInvoiceTaxOwner(\n  invoice: unknown,\n): StorefrontTaxOwner {\n  const source = invoice as any\n  if (source?.automatic_tax?.enabled !== true) return 'merchant'\n  return source?.automatic_tax?.liability?.type === 'account'\n    ? 'merchant'\n    : 'platform'\n}\n\n/** See `SubscriptionTaxReversalDecision`. */\nexport function subscriptionInvoiceTaxReversal(\n  invoice: unknown,\n): SubscriptionTaxReversalDecision {\n  const source = invoice as any\n  if (subscriptionInvoiceTaxOwner(source) === 'merchant') {\n    return { kind: 'skip', reason: 'merchant-tax' }\n  }\n  const settle = (cents: number): SubscriptionTaxReversalDecision =>\n    cents > 0\n      ? { kind: 'reverse', taxCents: cents }\n      : { kind: 'skip', reason: 'no-tax' }\n\n  // `typeof === 'number'` and NOT `Number(…)`, because `Number(null)` is a\n  // finite 0 and `null` is how an absent field arrives over JSON. Treating it\n  // as a stated zero is precisely the swallow this type exists to prevent.\n  const scalar = source?.tax\n  if (typeof scalar === 'number' && Number.isFinite(scalar)) {\n    return settle(Math.round(scalar))\n  }\n  // `total_taxes` replaced `total_tax_amounts`, which replaced the scalar; they\n  // do not coexist, so this cannot double-count.\n  const lines = Array.isArray(source?.total_taxes)\n    ? source.total_taxes\n    : Array.isArray(source?.total_tax_amounts)\n      ? source.total_tax_amounts\n      : null\n  if (lines) {\n    let sum = 0\n    for (const line of lines) {\n      const amount = Number((line as any)?.amount ?? NaN)\n      // One unreadable line poisons the sum: a partial total would reverse\n      // LESS than the state is owed and look like a successful correction.\n      if (!Number.isFinite(amount)) {\n        return {\n          kind: 'unreadable',\n          reason: 'a tax line on the invoice states no readable `amount`',\n        }\n      }\n      sum += amount\n    }\n    return settle(Math.round(sum))\n  }\n  return {\n    kind: 'unreadable',\n    reason:\n      'the invoice enables automatic tax but states no `tax`, `total_taxes` ' +\n      'or `total_tax_amounts` — the Stripe API version may have moved the field',\n  }\n}\n\n/**\n * The cheapest rate on a resolved shipping plan, in cents. `0` for a plan with\n * no options, which is also the right transfer contribution for a store that\n * charges no shipping.\n */\nexport function shippingFloorCents(\n  options: readonly { amountCents?: unknown }[] = [],\n): number {\n  if (options.length === 0) return 0\n  return options.reduce(\n    (least, option) =>\n      Math.min(\n        least,\n        Math.max(0, Math.round(Number(option?.amountCents ?? 0))),\n      ),\n    Number.POSITIVE_INFINITY,\n  )\n}\n\n/**\n * The Connect keys for a storefront destination charge — the destination, and\n * EXACTLY ONE of `application_fee_amount` / `transfer_data[amount]`.\n *\n * Emitted from one place so no checkout path can pick the wrong knob on its\n * own, and so the pair can never both appear (Stripe rejects that, and the two\n * would be contradicting each other about the same split).\n *\n * The `metadata[transferCents]` companion is deliberately NOT emitted here —\n * each caller owns its own metadata block, and the value is\n * `platformLiableTransferCents(split)`.\n */\nexport function destinationChargeParams(\n  split: DestinationChargeSplit,\n): Record<string, string> {\n  const destination = {\n    'payment_intent_data[transfer_data][destination]': String(split.accountId),\n  }\n  const fee = Math.max(0, Math.round(Number(split.feeCents ?? 0)))\n  if (split.taxOwner === 'platform') {\n    // AGLYN OWES THE TAX, SO AGLYN MUST KEEP IT (AGL-1956). A fixed transfer\n    // is the only form that expresses that: `application_fee_amount` would\n    // make Stripe compute `amount_total − fee`, and `amount_total` has the\n    // Stripe Tax inside it. Emitted even when it is zero — a zero transfer is\n    // a real, correct answer for a sub-dollar order (see\n    // `platformLiableTransferCents`), and OMITTING the key would silently\n    // restore the full-charge transfer this whole module exists to prevent.\n    return {\n      ...destination,\n      'payment_intent_data[transfer_data][amount]': String(\n        platformLiableTransferCents(split),\n      ),\n    }\n  }\n  // The merchant owns the tax on this sale, so the merchant may hold it: the\n  // fee form is exact here and is left byte-identical to what these paths\n  // sent before AGL-1956. Stripe rejects a zero application fee, so a fee that\n  // rounded to nothing sends no key at all.\n  return {\n    ...destination,\n    ...(fee > 0\n      ? { 'payment_intent_data[application_fee_amount]': String(fee) }\n      : {}),\n  }\n}\n"],"names":["platformLiableTransferCents","split","goods","Math","max","round","Number","merchantGoodsCents","shipping","shippingFloorCents","fee","feeCents","subscriptionInvoiceTaxOwner","invoice","source","automatic_tax","enabled","liability","type","subscriptionInvoiceTaxReversal","kind","reason","settle","cents","taxCents","scalar","tax","isFinite","lines","Array","isArray","total_taxes","total_tax_amounts","sum","line","amount","NaN","options","length","reduce","least","option","min","amountCents","POSITIVE_INFINITY","destinationChargeParams","destination","String","accountId","taxOwner"],"mappings":"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"}

package/src/lib/model/commerce-discounts.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Discounts engine v2 (AGL-305): code-based AND automatic promotions
+ * with scoping, schedules, and usage limits, superseding the AGL-96
+ * percent-only coupons (which keep working through the legacy path).
+ * One resolver serves cart, checkout, and POS. Docs live at
+ * `hosts/{hostId}/discounts`. Pure — callers own I/O and redemption
+ * increments.
+ */
+import { type PromotionHold } from './commerce-promotions';
+export type DiscountKind = 'percent' | 'fixed' | 'free_shipping';
+/** `hosts/{hostId}/discounts/{id}` doc. */
+export interface HostDiscount {
+    /** Uppercase entry code; absent = automatic (applies to every cart). */
+    code?: string;
+    /** Display name for automatic promotions ("Summer sale"). */
+    name?: string;
+    kind: DiscountKind;
+    /** percent kind: 1-100. */
+    valuePct?: number;
+    /** fixed kind: cents off the items subtotal. */
+    valueCents?: number;
+    /** Only carts at/above this subtotal qualify. */
+    minSubtotalCents?: number;
+    /** Scope: at least one cart line must be one of these products. */
+    productIds?: string[];
+    maxRedemptions?: number;
+    redemptions?: number;
+    /**
+     * In-flight claims on the remaining slots (AGL-2453), keyed by checkout
+     * attempt. Counted as redeemed by {@link applies} for as long as they stand,
+     * which is what stops N concurrent checkouts all passing a cap of one.
+     */
+    holds?: Record<string, PromotionHold>;
+    startAtMs?: number;
+    endAtMs?: number;
+    enabled?: boolean;
+}
+/** A discount proposed for a store, before anyone has switched it on (AGL-2916). */
+export interface ProposedDiscount {
+    name: string;
+    /** The code a shopper types, or `null` for a discount that applies on its own. */
+    code: string | null;
+    kind: DiscountKind;
+    valuePct: number | null;
+    valueCents: number | null;
+    minSubtotalCents: number | null;
+}
+/** A stored discount as the discounts card writes one: an automatic discount's code is `null`. */
+export type StoredDiscount = Omit<HostDiscount, 'code'> & {
+    code: string | null;
+};
+/**
+ * The document a proposed discount is created as (AGL-2916): switched OFF,
+ * with no redemptions, its code in the shape the discounts card stores, and
+ * only the value its kind reads. A person switches it on from the discounts
+ * card. `null` for a proposal no discount can be made from: a percentage
+ * outside 1 to 100, or an amount off of nothing.
+ */
+export declare function switchedOffDiscount(proposal: ProposedDiscount): StoredDiscount | null;
+export interface DiscountContext {
+    /** Entered code, if any (case-insensitive). */
+    code?: string;
+    subtotalCents: number;
+    /** Product ids present in the cart (scope checks). */
+    productIds: string[];
+    /**
+     * What each cart line is worth, for pricing a SCOPED discount.
+     *
+     * Required whenever a discount carries `productIds`, and the reason is that
+     * `subtotalCents` alone cannot price one: a scope names some of the cart, so
+     * the discount is worth some of the cart. A caller that omits these gets a
+     * refusal rather than a whole-cart discount — see `discountBenefit`.
+     */
+    lines?: readonly {
+        productId: string;
+        amountCents: number;
+    }[];
+    nowMs?: number;
+}
+export interface ResolvedDiscount {
+    discount: HostDiscount;
+    discountId: string;
+    discountCents: number;
+    freeShipping: boolean;
+    /**
+     * What this discount confers, as one value. `discountCents` and
+     * `freeShipping` are projections of it and are kept because callers read
+     * them; the benefit is what a caller should GATE on, because it is the only
+     * one of the three that can say "nothing, and here is why".
+     */
+    benefit: DiscountBenefit;
+    /** Why a specifically-entered code failed; unset when one applied. */
+    codeProblem?: string;
+}
+/**
+ * WHAT A DISCOUNT ACTUALLY CONFERS, named rather than implied.
+ *
+ * The whole point of this type is that "nothing" is a STATED outcome with a
+ * reason, not the number zero. `valueCents` used to answer a bare `number`,
+ * and every kind it did not understand — `free_shipping` included — answered
+ * `0`. The cart's apply-block gates on `discountCents > 0`, and the
+ * invalid-code 400 beside it only fires when NO discount resolved at all, so a
+ * free-shipping code took neither branch: it resolved successfully, conferred
+ * nothing, raised no error, and the shopper paid full shipping. A silent zero
+ * cannot be told from "this discount is worth nothing", which is exactly the
+ * distinction a money path has to make.
+ *
+ * So a caller cannot read a benefit without also seeing the `none` case, and a
+ * kind this build does not recognise reports itself instead of underpaying.
+ */
+export type DiscountBenefit = 
+/** Cents off the items subtotal. Always > 0 — a zero lands on `none`. */
+{
+    kind: 'amount';
+    centsOff: number;
+}
+/** The shopper pays no shipping, whichever rate they pick. */
+ | {
+    kind: 'free-shipping';
+}
+/** Resolvable, but worth nothing. The caller must refuse, never proceed. */
+ | {
+    kind: 'none';
+    reason: string;
+};
+/**
+ * The single derivation of what one discount is worth against one subtotal.
+ *
+ * Exhaustive over {@link DiscountKind} by construction: the `never` binding
+ * below fails the BUILD when a kind is added to the union and not handled
+ * here, so the next `free_shipping` cannot reach production as a silent zero.
+ * The runtime arm underneath it is not redundant — Firestore documents are not
+ * typechecked, and a `kind` written by a newer build than the one reading it
+ * arrives as an ordinary unrecognised string.
+ */
+export declare function discountBenefit(discount: HostDiscount, subtotalCents: number, lines?: readonly {
+    productId: string;
+    amountCents: number;
+}[]): DiscountBenefit;
+/**
+ * Best applicable discount: an entered code wins when valid (its
+ * failure reason is surfaced); otherwise the largest automatic
+ * promotion applies. Discounts never stack — Squarespace/Shopify
+ * baseline semantics.
+ */
+export declare function resolveDiscount(discounts: Array<HostDiscount & {
+    $id: string;
+}>, context: DiscountContext): ResolvedDiscount | null;