@aglyn/aglyn 1.15.0 → 1.15.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/package.json +11 -11
  2. package/src/lib/app-utils/buy-now-pay-later.d.ts +45 -0
  3. package/src/lib/app-utils/buy-now-pay-later.js +68 -0
  4. package/src/lib/app-utils/buy-now-pay-later.js.map +1 -0
  5. package/src/lib/app-utils/contexts.d.ts +1 -0
  6. package/src/lib/app-utils/contexts.js +1 -0
  7. package/src/lib/app-utils/contexts.js.map +1 -1
  8. package/src/lib/app-utils/docs-help-sections.generated.js +2 -0
  9. package/src/lib/app-utils/docs-help-sections.generated.js.map +1 -1
  10. package/src/lib/app-utils/docs-help.generated.d.ts +3 -3
  11. package/src/lib/app-utils/docs-help.generated.js +9 -0
  12. package/src/lib/app-utils/docs-help.generated.js.map +1 -1
  13. package/src/lib/app-utils/docs-index.generated.js +4 -4
  14. package/src/lib/app-utils/docs-index.generated.js.map +1 -1
  15. package/src/lib/app-utils/plan-entitlements.d.ts +127 -75
  16. package/src/lib/app-utils/plan-entitlements.js +120 -77
  17. package/src/lib/app-utils/plan-entitlements.js.map +1 -1
  18. package/src/lib/app-utils/plugin-bundle-checks.d.ts +14 -2
  19. package/src/lib/app-utils/plugin-bundle-checks.js +82 -7
  20. package/src/lib/app-utils/plugin-bundle-checks.js.map +1 -1
  21. package/src/lib/app-utils/plugin-connection-editor.d.ts +48 -0
  22. package/src/lib/app-utils/plugin-connection-editor.js +46 -0
  23. package/src/lib/app-utils/plugin-connection-editor.js.map +1 -0
  24. package/src/lib/app-utils/plugin-connection-record.d.ts +42 -0
  25. package/src/lib/app-utils/plugin-connection-record.js +48 -0
  26. package/src/lib/app-utils/plugin-connection-record.js.map +1 -0
  27. package/src/lib/app-utils/plugin-connection-records-context.d.ts +23 -0
  28. package/src/lib/app-utils/plugin-connection-records-context.js +29 -0
  29. package/src/lib/app-utils/plugin-connection-records-context.js.map +1 -0
  30. package/src/lib/app-utils/plugin-connection-records.d.ts +42 -0
  31. package/src/lib/app-utils/plugin-connection-records.js +56 -0
  32. package/src/lib/app-utils/plugin-connection-records.js.map +1 -0
  33. package/src/lib/app-utils/plugin-connections.d.ts +320 -0
  34. package/src/lib/app-utils/plugin-connections.js +895 -0
  35. package/src/lib/app-utils/plugin-connections.js.map +1 -0
  36. package/src/lib/app-utils/plugin-elements.d.ts +104 -0
  37. package/src/lib/app-utils/plugin-elements.js +128 -0
  38. package/src/lib/app-utils/plugin-elements.js.map +1 -0
  39. package/src/lib/app-utils/plugin-manifest.d.ts +20 -75
  40. package/src/lib/app-utils/plugin-manifest.js +65 -100
  41. package/src/lib/app-utils/plugin-manifest.js.map +1 -1
  42. package/src/lib/app-utils/realm-elements-context.d.ts +16 -0
  43. package/src/lib/app-utils/realm-elements-context.js +16 -0
  44. package/src/lib/app-utils/realm-elements-context.js.map +1 -1
  45. package/src/lib/app-utils/realm-host-surface.generated.js +1 -0
  46. package/src/lib/app-utils/realm-host-surface.generated.js.map +1 -1
  47. package/src/lib/app-utils/release-flags.d.ts +1 -1
  48. package/src/lib/app-utils/release-flags.js +11 -0
  49. package/src/lib/app-utils/release-flags.js.map +1 -1
  50. package/src/lib/app-utils/server.d.ts +1 -0
  51. package/src/lib/app-utils/server.js +2 -0
  52. package/src/lib/app-utils/server.js.map +1 -1
  53. package/src/lib/plugin-manager/feature-plugins.d.ts +25 -0
  54. package/src/lib/plugin-manager/feature-plugins.js +10 -0
  55. package/src/lib/plugin-manager/feature-plugins.js.map +1 -1
  56. package/src/lib/plugin-manager/first-party-plugins.generated.js +11 -0
  57. package/src/lib/plugin-manager/first-party-plugins.generated.js.map +1 -1
  58. package/src/lib/plugin-manager/index.d.ts +1 -0
  59. package/src/lib/plugin-manager/index.js +1 -0
  60. package/src/lib/plugin-manager/index.js.map +1 -1
  61. package/src/lib/plugin-manager/plugin-artifact-inventory.d.ts +5 -0
  62. package/src/lib/plugin-manager/plugin-artifact-inventory.js.map +1 -1
  63. package/src/lib/plugin-manager/plugin-site-csp.d.ts +36 -0
  64. package/src/lib/plugin-manager/plugin-site-csp.js +50 -1
  65. package/src/lib/plugin-manager/plugin-site-csp.js.map +1 -1
  66. package/src/lib/plugin-manager/realm-host-aglyn.generated.js +61 -59
  67. package/src/lib/plugin-manager/realm-host-aglyn.generated.js.map +1 -1
  68. package/src/lib/plugin-manager/site-page-enricher-services.d.ts +35 -0
  69. package/src/lib/plugin-manager/site-page-enricher-services.js +35 -0
  70. package/src/lib/plugin-manager/site-page-enricher-services.js.map +1 -0
  71. package/src/lib/plugin-manager/site-page-hooks.js +16 -3
  72. package/src/lib/plugin-manager/site-page-hooks.js.map +1 -1
@@ -1885,8 +1885,10 @@ export declare function checkHostRegisterQuota(org: Partial<AglynOrgBilling> | n
1885
1885
  export declare function resolveTransactionFeePct(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service'): number;
1886
1886
  /**
1887
1887
  * Stripe's processing cost on ONE destination-charge sale, in cents
1888
- * (AGL-2152) — a storefront order, a booking deposit — the dearest enabled
1889
- * method's percentage plus the fixed 30¢, rounded UP on the percentage so the
1888
+ * (AGL-2152) — a storefront order, a booking deposit, a quote or an invoice —
1889
+ * the card processing it passes through to the seller: the dearest method
1890
+ * the session can offer, a card, `SALE_PROCESSING_PERCENT` +
1891
+ * `SALE_PROCESSING_FIXED_CENTS` (2.9% + 30¢), rounded UP on the percentage so the
1890
1892
  * answer is never a cent short of what Stripe actually debits.
1891
1893
  *
1892
1894
  * WHO PAYS THIS. Every storefront charge is a DESTINATION charge:
@@ -1906,26 +1908,65 @@ export declare function resolveTransactionFeePct(org: Partial<AglynOrgBilling> |
1906
1908
  * fixed 30¢ is why a percentage alone can never reach break-even on small
1907
1909
  * orders, and why this returns a CENTS amount rather than a rate.
1908
1910
  *
1909
- * WHY THE DEAREST METHOD AND NOT 2.9%. The shopper picks how to pay AFTER the
1910
- * session is created, and `application_fee_amount` is a fixed number Stripe
1911
- * will not let us revise once the charge settles. No storefront or booking
1912
- * path pins `payment_method_types` or excludes buy-now-pay-later, so the platform's payment method configuration
1913
- * decides the set — and per AGL-2343 that configuration has `klarna` and
1914
- * `affirm` on beside the card family. Pricing this at the card rate would be
1915
- * wrong exactly on the orders where it cost the most, which is the same
1916
- * reasoning the marketplace listing floor applies; both are defined from the
1917
- * SAME processing constants so the two cannot drift.
1918
- *
1919
- * THE ONE-LINE LEVER. On a card-family order this over-recovers by the spread
1920
- * between the two rates. Pinning `payment_method_types` on the storefront
1921
- * sessions to the card family would make 2.9% the true binding rate, and
1922
- * `SALE_PROCESSING_PERCENT` below is then the single identifier to
1923
- * repoint. That is a product decision about which payment methods a storefront
1924
- * offers, not this one; it is recorded on AGL-2152 and in the Pricing Decision
1925
- * Log so it can be taken deliberately. Quote and invoice pay links have taken
1926
- * it: they exclude buy-now-pay-later and pass `PAY_LINK_PROCESSING_PERCENT`.
1927
- */
1928
- export declare function saleProcessingCostCents(chargeCents: number, processingPercent?: number): number;
1911
+ * WHY THE DEAREST METHOD. The shopper picks how to pay AFTER the session is
1912
+ * created, and `application_fee_amount` is a fixed number Stripe will not let
1913
+ * us revise once the charge settles, so the fee is sized for the dearest
1914
+ * method the session can offer. Until AGL-4198 that was buy-now-pay-later, at
1915
+ * 6%: the platform's payment method configuration has `klarna` and `affirm`
1916
+ * on beside the card family (AGL-2343), and no storefront or booking session
1917
+ * excluded them. Every Checkout Session a site opens now excludes them
1918
+ * (`excludeBuyNowPayLater`, `buy-now-pay-later.ts`), which makes the card
1919
+ * rate the binding one, and `SALE_PROCESSING_PERCENT` below points at it.
1920
+ * A card issued abroad adds Stripe's 1.5% international surcharge, which is
1921
+ * not recovered, as on the register.
1922
+ */
1923
+ export declare function saleProcessingCostCents(chargeCents: number): number;
1924
+ /** What a sale's session does that changes what the platform pays for it. */
1925
+ export interface SaleProcessingOptions {
1926
+ /**
1927
+ * The session runs Stripe Tax (`automatic_tax[enabled]`), which bills the
1928
+ * platform `STRIPE_TAX_PERCENT` of the transaction where it is registered.
1929
+ */
1930
+ stripeTax?: boolean;
1931
+ /**
1932
+ * A card read by a Stripe Terminal reader (`card_present`), which Stripe
1933
+ * charges the platform less for than an online card
1934
+ * (`TERMINAL_PROCESSING_PERCENT` + `TERMINAL_PROCESSING_FIXED_CENTS`).
1935
+ */
1936
+ inPerson?: boolean;
1937
+ /**
1938
+ * The sale is a DIRECT charge on the seller's own connected account, which
1939
+ * Stripe bills itself (`controller.fees.payer: account`). Stripe takes its
1940
+ * card fee from the seller and charges the platform nothing for the sale,
1941
+ * no Connect payout fee and no Stripe Tax, so Aglyn's application fee is
1942
+ * the plan's take and nothing else.
1943
+ */
1944
+ direct?: boolean;
1945
+ }
1946
+ /**
1947
+ * Everything Stripe charges the PLATFORM for one sale, in cents (AGL-4198):
1948
+ * the card (online 2.9% + 30¢, or Terminal's 2.7% + 15¢ for a reader's card),
1949
+ * the Connect payout that sends the money on (0.25% + 25¢, one payout per
1950
+ * sale, the daily-payout worst case), and Stripe Tax's 0.5% where the
1951
+ * session runs it. Each part rounded UP, so the floor is never a cent short.
1952
+ * The $2 a month per paid-out seller is not here: the seller's paid plan,
1953
+ * which selling requires, carries it.
1954
+ */
1955
+ export declare function salePlatformCostCents(chargeCents: number, options?: SaleProcessingOptions): number;
1956
+ /**
1957
+ * The `application_fee_amount` for one sale, from its take in cents
1958
+ * (AGL-2152, AGL-4198): the take plus the card pass-through
1959
+ * (`saleProcessingCostCents`, 2.9% + 30¢), and never less than everything
1960
+ * Stripe charges the platform for the sale (`salePlatformCostCents`).
1961
+ *
1962
+ * So the costs beyond the card fee — Connect's payout and Stripe Tax — come
1963
+ * out of the plan's take first. A take that covers them leaves the seller
1964
+ * paying 2.9% + 30¢ on top of it and nothing more; a take that does not (a 0%
1965
+ * plan, or a small take on a small sale) is topped up to break even, so no
1966
+ * plan runs at a loss. Clamped to the charge, because Stripe rejects an
1967
+ * application fee larger than it.
1968
+ */
1969
+ export declare function saleApplicationFeeCents(takeCents: number, chargeCents: number, options?: SaleProcessingOptions): number;
1929
1970
  /**
1930
1971
  * The Stripe Connect `application_fee_amount` for ONE storefront sale
1931
1972
  * (AGL-2152) — the platform's advertised take PLUS Stripe's processing cost,
@@ -1950,14 +1991,9 @@ export declare function saleProcessingCostCents(chargeCents: number, processingP
1950
1991
  * Clamped to `chargeCents` because Stripe rejects an application fee larger
1951
1992
  * than the charge. That clamp can only bind below ~32¢, under Stripe's own 50¢
1952
1993
  * charge minimum, so it never trims a real order's fee.
1953
- *
1954
- * `processingPercent` is the rate the processing half is priced at. It
1955
- * defaults to `SALE_PROCESSING_PERCENT`, the dearest method a storefront or
1956
- * booking session may offer. A quote's or an invoice's pay link passes
1957
- * `PAY_LINK_PROCESSING_PERCENT`, the card rate, because those sessions never
1958
- * offer buy-now-pay-later.
1994
+
1959
1995
  */
1960
- export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', feeBaseCents: number, chargeCents?: number, processingPercent?: number): number;
1996
+ export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', feeBaseCents: number, chargeCents?: number, options?: SaleProcessingOptions): number;
1961
1997
  /**
1962
1998
  * Stripe's processing cost on a RECURRING charge of `amountCents`, as the
1963
1999
  * percent a Subscription's `application_fee_percent` can carry (AGL-2655).
@@ -1971,8 +2007,8 @@ export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling>
1971
2007
  * percent = rate + fixed ÷ amount
1972
2008
  *
1973
2009
  * which is why a smaller recurring price carries a HIGHER percent: the 30¢
1974
- * is a bigger share of it. At 6% + 30¢ a $10 price carries 9%, $25 carries
1975
- * 7.2% and $100 carries 6.3%.
2010
+ * is a bigger share of it. At 2.9% + 30¢ a $10 price carries 5.9%, $25
2011
+ * carries 4.1% and $100 carries 3.2%.
1976
2012
  *
1977
2013
  * Computed in hundredths of a percent on integers and rounded UP to the next
1978
2014
  * hundredth. Up, for the reason the one-time helper rounds its percentage
@@ -2004,7 +2040,13 @@ export declare function saleProcessingPassThroughPercent(amountCents: number): n
2004
2040
  * not always `8.34` in floating point), and capped at 100, Stripe's ceiling
2005
2041
  * for the parameter — the recurring twin of the clamp to the charge.
2006
2042
  */
2007
- export declare function resolveSubscriptionFeePercent(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', amountCents: number): number;
2043
+ export declare function resolveSubscriptionFeePercent(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', amountCents: number, options?: SaleProcessingOptions): number;
2044
+ /**
2045
+ * `salePlatformCostCents` as a percent of a recurring amount, rounded UP to
2046
+ * the next hundredth: what `application_fee_percent` must reach so the
2047
+ * platform breaks even on the cycle. Capped at 100.
2048
+ */
2049
+ export declare function salePlatformCostPercent(amountCents: number, options?: SaleProcessingOptions): number;
2008
2050
  /**
2009
2051
  * Platform take rate % for a MARKETPLACE listing sale (AGL-1543), priced
2010
2052
  * off the SELLER org. Resolved through `resolveOrgEntitlements` — so a
@@ -2041,55 +2083,65 @@ export declare function bindingMarketplaceFeePct(): number;
2041
2083
  * they exist only as inputs to a platform take and to figures a seller reads;
2042
2084
  * changing one never changes a price list.
2043
2085
  *
2044
- * THE BNPL RATE IS THE ONE THAT BINDS on a storefront, a booking and a
2045
- * marketplace listing, and it is not hypothetical: the live default payment
2046
- * method configuration has `klarna` and `affirm` enabled alongside `card`,
2047
- * `cashapp`, `link`, `amazon_pay` and `apple_pay`, and those sessions do not
2048
- * exclude them, so a buyer may pay by either. A cost computed from the
2049
- * cheapest method would be wrong exactly when it mattered. A quote's or an
2050
- * invoice's pay link is the exception: it excludes every BNPL method and so
2051
- * is priced at the card rate (`PAY_LINK_PROCESSING_PERCENT`).
2086
+ * The live default payment method configuration has `klarna` and `affirm`
2087
+ * enabled alongside `card`, `cashapp`, `link`, `amazon_pay` and `apple_pay`.
2088
+ * Since AGL-4198 every Checkout Session a site opens excludes
2089
+ * buy-now-pay-later (`buy-now-pay-later.ts`), so the CARD rate binds on
2090
+ * storefront orders, bookings, quotes, invoices and subscriptions. The BNPL
2091
+ * rate is kept for the marketplace listing floor, which still prices against
2092
+ * it as a margin (see `listing-price-floor.ts`).
2052
2093
  */
2053
2094
  export declare const CARD_PROCESSING_PERCENT = 2.9;
2054
- /** Klarna/Affirm, roughly. See the note above — this is the binding one. */
2095
+ /** Klarna/Afterpay/Affirm (standard plans), roughly. No site checkout offers them since AGL-4198. */
2055
2096
  export declare const BNPL_PROCESSING_PERCENT = 6;
2056
- /** Stripe's per-transaction fixed component, in cents. */
2097
+ /** Stripe's per-transaction fixed component on a card, in cents. */
2057
2098
  export declare const PROCESSING_FIXED_CENTS = 30;
2058
2099
  /**
2059
- * The processing rate a storefront or booking destination charge is priced
2060
- * against (AGL-2152), and the one identifier to repoint if those sessions'
2061
- * payment method set changes.
2062
- *
2063
- * Deliberately its OWN name rather than a direct use of the binding rate,
2064
- * while being defined as it: every seller shares Stripe's published rates and
2065
- * today shares the platform's payment method configuration, but each surface
2066
- * is a separate product decision. A future choice to pin
2067
- * `payment_method_types` on storefront sessions to the card family — and so
2068
- * to recover at `CARD_PROCESSING_PERCENT` — must not silently lower the
2069
- * marketplace listing floor, which is derived from the binding rate for a
2070
- * different flow.
2071
- */
2072
- export declare const SALE_PROCESSING_PERCENT = 6;
2073
- /**
2074
- * The processing rate a QUOTE's or an INVOICE's pay link is priced against:
2075
- * the card rate, 2.9% + 30¢.
2076
- *
2077
- * Those sessions always exclude Klarna, Afterpay and Affirm
2078
- * (`payLinkPaymentMethodControls` in the commerce plugin), so what a buyer
2079
- * can still choose is the card family: a card, Apple Pay, Google Pay, Link,
2080
- * Cash App Pay and Amazon Pay, all 2.9% + 30¢ on Stripe's published US
2081
- * pricing, and stablecoins, at 1.5% when a seller turns them on. The card
2082
- * rate is therefore the dearest a pay link can cost, as `SALE_PROCESSING_PERCENT`
2083
- * is for a storefront. An international card adds Stripe's 1.5% surcharge,
2084
- * which this does not recover, the same as the register's card payments.
2085
- *
2086
- * Its own name for the reason `SALE_PROCESSING_PERCENT` has one: a storefront,
2087
- * a booking and the marketplace floor stay on the rate their own sessions can
2088
- * cost, and repointing this one moves pay links only.
2089
- */
2090
- export declare const PAY_LINK_PROCESSING_PERCENT = 2.9;
2091
- /** Stripe's per-transaction fixed component, in cents. Not rate-dependent. */
2100
+ * What Stripe Connect bills the PLATFORM for paying a seller out (AGL-4198).
2101
+ * Sellers are Express accounts (`commerce/server/connect.ts`), and on the
2102
+ * "you handle pricing" model Stripe charges the platform 0.25% + 25¢ on every
2103
+ * payout sent and $2 for every account that is paid out in a month
2104
+ * (stripe.com/connect/pricing, read 2026-11-06). Every sale's money leaves
2105
+ * through a payout, so the percent rides every sale. The 25¢ is per payout,
2106
+ * which with daily payouts and one sale a day is one per sale: that is the
2107
+ * figure recovered, and a seller with several sales a day over-recovers it.
2108
+ * The $2 a month is not recovered per sale; the seller's paid plan, which
2109
+ * selling requires, carries it.
2110
+ */
2111
+ export declare const CONNECT_PAYOUT_PERCENT = 0.25;
2112
+ /** Stripe Connect's fixed charge per payout sent, in cents. */
2113
+ export declare const CONNECT_PAYOUT_FIXED_CENTS = 25;
2114
+ /**
2115
+ * Stripe Tax's charge on a Checkout transaction it calculates where the
2116
+ * platform is registered: 0.5% (stripe.com/tax/pricing, read 2026-11-06).
2117
+ * The platform is the account that runs `automatic_tax` on a site's session,
2118
+ * so a sale whose session runs it carries this too (`SaleProcessingOptions`).
2119
+ */
2120
+ export declare const STRIPE_TAX_PERCENT = 0.5;
2121
+ /**
2122
+ * The processing a site sale passes through to the seller on top of the
2123
+ * plan's take (AGL-2152, AGL-4198): Stripe's card rate, 2.9% + 30¢, online
2124
+ * and on a card reader alike. Every checkout a site opens excludes
2125
+ * buy-now-pay-later, so no method a buyer can choose costs Stripe more online
2126
+ * (a card, Apple Pay, Google Pay, Link, Cash App Pay and Amazon Pay are 2.9% +
2127
+ * 30¢ on Stripe's US pricing, stablecoins 1.5%), and a reader's card costs
2128
+ * less (`TERMINAL_PROCESSING_PERCENT`).
2129
+ *
2130
+ * What the platform pays beyond it — Connect's payout and Stripe Tax — comes
2131
+ * out of the plan's take, with the fee never below the platform's whole cost
2132
+ * (`saleApplicationFeeCents`). A card issued abroad adds Stripe's 1.5%
2133
+ * surcharge, which is not recovered.
2134
+ */
2135
+ export declare const SALE_PROCESSING_PERCENT = 2.9;
2136
+ /** The fixed cents a sale passes through: the card's 30¢. */
2092
2137
  export declare const SALE_PROCESSING_FIXED_CENTS = 30;
2138
+ /**
2139
+ * Stripe Terminal's in-person card rate, US: 2.7% + 5¢, plus 10¢ for a Tap to
2140
+ * Pay authorization (stripe.com/terminal, read 2026-11-06).
2141
+ */
2142
+ export declare const TERMINAL_PROCESSING_PERCENT = 2.7;
2143
+ /** Terminal's fixed cents per in-person card payment, Tap to Pay's 10¢ included (5¢ + 10¢). */
2144
+ export declare const TERMINAL_PROCESSING_FIXED_CENTS = 15;
2093
2145
  /**
2094
2146
  * The cheapest plan whose BASE features include `feature`, in ladder order —
2095
2147
  * the answer to "which plan do I need for this?", which is the one thing an
@@ -3185,8 +3185,10 @@ function resolvePlan(org) {
3185
3185
  }
3186
3186
  /**
3187
3187
  * Stripe's processing cost on ONE destination-charge sale, in cents
3188
- * (AGL-2152) — a storefront order, a booking deposit — the dearest enabled
3189
- * method's percentage plus the fixed 30¢, rounded UP on the percentage so the
3188
+ * (AGL-2152) — a storefront order, a booking deposit, a quote or an invoice —
3189
+ * the card processing it passes through to the seller: the dearest method
3190
+ * the session can offer, a card, `SALE_PROCESSING_PERCENT` +
3191
+ * `SALE_PROCESSING_FIXED_CENTS` (2.9% + 30¢), rounded UP on the percentage so the
3190
3192
  * answer is never a cent short of what Stripe actually debits.
3191
3193
  *
3192
3194
  * WHO PAYS THIS. Every storefront charge is a DESTINATION charge:
@@ -3206,31 +3208,58 @@ function resolvePlan(org) {
3206
3208
  * fixed 30¢ is why a percentage alone can never reach break-even on small
3207
3209
  * orders, and why this returns a CENTS amount rather than a rate.
3208
3210
  *
3209
- * WHY THE DEAREST METHOD AND NOT 2.9%. The shopper picks how to pay AFTER the
3210
- * session is created, and `application_fee_amount` is a fixed number Stripe
3211
- * will not let us revise once the charge settles. No storefront or booking
3212
- * path pins `payment_method_types` or excludes buy-now-pay-later, so the platform's payment method configuration
3213
- * decides the set — and per AGL-2343 that configuration has `klarna` and
3214
- * `affirm` on beside the card family. Pricing this at the card rate would be
3215
- * wrong exactly on the orders where it cost the most, which is the same
3216
- * reasoning the marketplace listing floor applies; both are defined from the
3217
- * SAME processing constants so the two cannot drift.
3218
- *
3219
- * THE ONE-LINE LEVER. On a card-family order this over-recovers by the spread
3220
- * between the two rates. Pinning `payment_method_types` on the storefront
3221
- * sessions to the card family would make 2.9% the true binding rate, and
3222
- * `SALE_PROCESSING_PERCENT` below is then the single identifier to
3223
- * repoint. That is a product decision about which payment methods a storefront
3224
- * offers, not this one; it is recorded on AGL-2152 and in the Pricing Decision
3225
- * Log so it can be taken deliberately. Quote and invoice pay links have taken
3226
- * it: they exclude buy-now-pay-later and pass `PAY_LINK_PROCESSING_PERCENT`.
3211
+ * WHY THE DEAREST METHOD. The shopper picks how to pay AFTER the session is
3212
+ * created, and `application_fee_amount` is a fixed number Stripe will not let
3213
+ * us revise once the charge settles, so the fee is sized for the dearest
3214
+ * method the session can offer. Until AGL-4198 that was buy-now-pay-later, at
3215
+ * 6%: the platform's payment method configuration has `klarna` and `affirm`
3216
+ * on beside the card family (AGL-2343), and no storefront or booking session
3217
+ * excluded them. Every Checkout Session a site opens now excludes them
3218
+ * (`excludeBuyNowPayLater`, `buy-now-pay-later.ts`), which makes the card
3219
+ * rate the binding one, and `SALE_PROCESSING_PERCENT` below points at it.
3220
+ * A card issued abroad adds Stripe's 1.5% international surcharge, which is
3221
+ * not recovered, as on the register.
3227
3222
  */ // `SALE_PROCESSING_PERCENT` and `SALE_PROCESSING_FIXED_CENTS` are declared
3228
3223
  // beside the processing constants they are defined from, further down this
3229
3224
  // file — a `const` cannot be read before its declaration is evaluated, and
3230
3225
  // this function is only ever CALLED, never evaluated at import.
3231
- export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PROCESSING_PERCENT) {
3226
+ export function saleProcessingCostCents(chargeCents) {
3232
3227
  if (!Number.isFinite(chargeCents) || chargeCents <= 0) return 0;
3233
- return Math.ceil(chargeCents * processingPercent / 100) + SALE_PROCESSING_FIXED_CENTS;
3228
+ return Math.ceil(chargeCents * SALE_PROCESSING_PERCENT / 100) + SALE_PROCESSING_FIXED_CENTS;
3229
+ }
3230
+ /**
3231
+ * Everything Stripe charges the PLATFORM for one sale, in cents (AGL-4198):
3232
+ * the card (online 2.9% + 30¢, or Terminal's 2.7% + 15¢ for a reader's card),
3233
+ * the Connect payout that sends the money on (0.25% + 25¢, one payout per
3234
+ * sale, the daily-payout worst case), and Stripe Tax's 0.5% where the
3235
+ * session runs it. Each part rounded UP, so the floor is never a cent short.
3236
+ * The $2 a month per paid-out seller is not here: the seller's paid plan,
3237
+ * which selling requires, carries it.
3238
+ */ export function salePlatformCostCents(chargeCents, options = {}) {
3239
+ if (!Number.isFinite(chargeCents) || chargeCents <= 0) return 0;
3240
+ const card = options.inPerson ? Math.ceil(chargeCents * TERMINAL_PROCESSING_PERCENT / 100) + TERMINAL_PROCESSING_FIXED_CENTS : Math.ceil(chargeCents * CARD_PROCESSING_PERCENT / 100) + PROCESSING_FIXED_CENTS;
3241
+ const payout = Math.ceil(chargeCents * CONNECT_PAYOUT_PERCENT / 100) + CONNECT_PAYOUT_FIXED_CENTS;
3242
+ const tax = options.stripeTax ? Math.ceil(chargeCents * STRIPE_TAX_PERCENT / 100) : 0;
3243
+ return card + payout + tax;
3244
+ }
3245
+ /**
3246
+ * The `application_fee_amount` for one sale, from its take in cents
3247
+ * (AGL-2152, AGL-4198): the take plus the card pass-through
3248
+ * (`saleProcessingCostCents`, 2.9% + 30¢), and never less than everything
3249
+ * Stripe charges the platform for the sale (`salePlatformCostCents`).
3250
+ *
3251
+ * So the costs beyond the card fee — Connect's payout and Stripe Tax — come
3252
+ * out of the plan's take first. A take that covers them leaves the seller
3253
+ * paying 2.9% + 30¢ on top of it and nothing more; a take that does not (a 0%
3254
+ * plan, or a small take on a small sale) is topped up to break even, so no
3255
+ * plan runs at a loss. Clamped to the charge, because Stripe rejects an
3256
+ * application fee larger than it.
3257
+ */ export function saleApplicationFeeCents(takeCents, chargeCents, options = {}) {
3258
+ const charge = Number.isFinite(chargeCents) && chargeCents > 0 ? Math.round(chargeCents) : 0;
3259
+ if (charge <= 0) return 0;
3260
+ const take = Number.isFinite(takeCents) && takeCents > 0 ? Math.round(takeCents) : 0;
3261
+ if (options.direct) return Math.min(charge, take);
3262
+ return Math.min(charge, Math.max(take + saleProcessingCostCents(charge), salePlatformCostCents(charge, options)));
3234
3263
  }
3235
3264
  /**
3236
3265
  * The Stripe Connect `application_fee_amount` for ONE storefront sale
@@ -3256,13 +3285,8 @@ export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PR
3256
3285
  * Clamped to `chargeCents` because Stripe rejects an application fee larger
3257
3286
  * than the charge. That clamp can only bind below ~32¢, under Stripe's own 50¢
3258
3287
  * charge minimum, so it never trims a real order's fee.
3259
- *
3260
- * `processingPercent` is the rate the processing half is priced at. It
3261
- * defaults to `SALE_PROCESSING_PERCENT`, the dearest method a storefront or
3262
- * booking session may offer. A quote's or an invoice's pay link passes
3263
- * `PAY_LINK_PROCESSING_PERCENT`, the card rate, because those sessions never
3264
- * offer buy-now-pay-later.
3265
- */ export function resolveTransactionFeeCents(org, productType, feeBaseCents, chargeCents = feeBaseCents, processingPercent = SALE_PROCESSING_PERCENT) {
3288
+
3289
+ */ export function resolveTransactionFeeCents(org, productType, feeBaseCents, chargeCents = feeBaseCents, options = {}) {
3266
3290
  const charge = Number.isFinite(chargeCents) && chargeCents > 0 ? Math.round(chargeCents) : 0;
3267
3291
  if (charge <= 0) return 0;
3268
3292
  const base = Number.isFinite(feeBaseCents) && feeBaseCents > 0 ? Math.round(feeBaseCents) : 0;
@@ -3270,7 +3294,7 @@ export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PR
3270
3294
  // The `Math.max(1, …)` every door already applied: a rate above zero on
3271
3295
  // goods the shopper pays for is a fee however small it rounds to.
3272
3296
  const take = pct > 0 && base > 0 ? Math.max(1, Math.round(base * pct / 100)) : 0;
3273
- return Math.min(charge, take + saleProcessingCostCents(charge, processingPercent));
3297
+ return saleApplicationFeeCents(take, charge, options);
3274
3298
  }
3275
3299
  /**
3276
3300
  * Stripe's processing cost on a RECURRING charge of `amountCents`, as the
@@ -3285,8 +3309,8 @@ export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PR
3285
3309
  * percent = rate + fixed ÷ amount
3286
3310
  *
3287
3311
  * which is why a smaller recurring price carries a HIGHER percent: the 30¢
3288
- * is a bigger share of it. At 6% + 30¢ a $10 price carries 9%, $25 carries
3289
- * 7.2% and $100 carries 6.3%.
3312
+ * is a bigger share of it. At 2.9% + 30¢ a $10 price carries 5.9%, $25
3313
+ * carries 4.1% and $100 carries 3.2%.
3290
3314
  *
3291
3315
  * Computed in hundredths of a percent on integers and rounded UP to the next
3292
3316
  * hundredth. Up, for the reason the one-time helper rounds its percentage
@@ -3301,7 +3325,7 @@ export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PR
3301
3325
  const amount = Number.isFinite(amountCents) && amountCents > 0 ? Math.round(amountCents) : 0;
3302
3326
  if (amount <= 0) return 0;
3303
3327
  const rateHundredths = Math.round(SALE_PROCESSING_PERCENT * 100);
3304
- // 30¢ ÷ amount is a fraction; × 100 makes it a percent, × 100 again makes
3328
+ // The fixed cents ÷ amount is a fraction; × 100 makes it a percent, × 100 again makes
3305
3329
  // it hundredths of one.
3306
3330
  const fixedHundredths = SALE_PROCESSING_FIXED_CENTS * 10000 / amount;
3307
3331
  return Math.min(100, Math.ceil(rateHundredths + fixedHundredths) / 100);
@@ -3324,12 +3348,25 @@ export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PR
3324
3348
  * Composed in hundredths so two decimals stay two decimals (`2 + 6.34` is
3325
3349
  * not always `8.34` in floating point), and capped at 100, Stripe's ceiling
3326
3350
  * for the parameter — the recurring twin of the clamp to the charge.
3327
- */ export function resolveSubscriptionFeePercent(org, productType, amountCents) {
3351
+ */ export function resolveSubscriptionFeePercent(org, productType, amountCents, options = {}) {
3328
3352
  const amount = Number.isFinite(amountCents) && amountCents > 0 ? Math.round(amountCents) : 0;
3329
3353
  if (amount <= 0) return 0;
3330
3354
  const take = resolveTransactionFeePct(org, productType);
3355
+ if (options.direct) return Math.min(100, Math.round(take * 100) / 100);
3331
3356
  const passThrough = saleProcessingPassThroughPercent(amount);
3332
- return Math.min(100, (Math.round(take * 100) + Math.round(passThrough * 100)) / 100);
3357
+ // Never below everything Stripe charges the platform for the cycle, the
3358
+ // recurring twin of `saleApplicationFeeCents`'s floor (AGL-4198).
3359
+ const floorHundredths = Math.round(salePlatformCostPercent(amount, options) * 100);
3360
+ return Math.min(100, Math.max(Math.round(take * 100) + Math.round(passThrough * 100), floorHundredths) / 100);
3361
+ }
3362
+ /**
3363
+ * `salePlatformCostCents` as a percent of a recurring amount, rounded UP to
3364
+ * the next hundredth: what `application_fee_percent` must reach so the
3365
+ * platform breaks even on the cycle. Capped at 100.
3366
+ */ export function salePlatformCostPercent(amountCents, options = {}) {
3367
+ const amount = Number.isFinite(amountCents) && amountCents > 0 ? Math.round(amountCents) : 0;
3368
+ if (amount <= 0) return 0;
3369
+ return Math.min(100, Math.ceil(salePlatformCostCents(amount, options) * 10000 / amount) / 100);
3333
3370
  }
3334
3371
  /**
3335
3372
  * Platform take rate % for a MARKETPLACE listing sale (AGL-1543), priced
@@ -3388,49 +3425,55 @@ export function saleProcessingCostCents(chargeCents, processingPercent = SALE_PR
3388
3425
  * they exist only as inputs to a platform take and to figures a seller reads;
3389
3426
  * changing one never changes a price list.
3390
3427
  *
3391
- * THE BNPL RATE IS THE ONE THAT BINDS on a storefront, a booking and a
3392
- * marketplace listing, and it is not hypothetical: the live default payment
3393
- * method configuration has `klarna` and `affirm` enabled alongside `card`,
3394
- * `cashapp`, `link`, `amazon_pay` and `apple_pay`, and those sessions do not
3395
- * exclude them, so a buyer may pay by either. A cost computed from the
3396
- * cheapest method would be wrong exactly when it mattered. A quote's or an
3397
- * invoice's pay link is the exception: it excludes every BNPL method and so
3398
- * is priced at the card rate (`PAY_LINK_PROCESSING_PERCENT`).
3428
+ * The live default payment method configuration has `klarna` and `affirm`
3429
+ * enabled alongside `card`, `cashapp`, `link`, `amazon_pay` and `apple_pay`.
3430
+ * Since AGL-4198 every Checkout Session a site opens excludes
3431
+ * buy-now-pay-later (`buy-now-pay-later.ts`), so the CARD rate binds on
3432
+ * storefront orders, bookings, quotes, invoices and subscriptions. The BNPL
3433
+ * rate is kept for the marketplace listing floor, which still prices against
3434
+ * it as a margin (see `listing-price-floor.ts`).
3399
3435
  */ export const CARD_PROCESSING_PERCENT = 2.9;
3400
- /** Klarna/Affirm, roughly. See the note above — this is the binding one. */ export const BNPL_PROCESSING_PERCENT = 6;
3401
- /** Stripe's per-transaction fixed component, in cents. */ export const PROCESSING_FIXED_CENTS = 30;
3402
- /**
3403
- * The processing rate a storefront or booking destination charge is priced
3404
- * against (AGL-2152), and the one identifier to repoint if those sessions'
3405
- * payment method set changes.
3406
- *
3407
- * Deliberately its OWN name rather than a direct use of the binding rate,
3408
- * while being defined as it: every seller shares Stripe's published rates and
3409
- * today shares the platform's payment method configuration, but each surface
3410
- * is a separate product decision. A future choice to pin
3411
- * `payment_method_types` on storefront sessions to the card family — and so
3412
- * to recover at `CARD_PROCESSING_PERCENT` — must not silently lower the
3413
- * marketplace listing floor, which is derived from the binding rate for a
3414
- * different flow.
3415
- */ export const SALE_PROCESSING_PERCENT = BNPL_PROCESSING_PERCENT;
3416
- /**
3417
- * The processing rate a QUOTE's or an INVOICE's pay link is priced against:
3418
- * the card rate, 2.9% + 30¢.
3419
- *
3420
- * Those sessions always exclude Klarna, Afterpay and Affirm
3421
- * (`payLinkPaymentMethodControls` in the commerce plugin), so what a buyer
3422
- * can still choose is the card family: a card, Apple Pay, Google Pay, Link,
3423
- * Cash App Pay and Amazon Pay, all 2.9% + 30¢ on Stripe's published US
3424
- * pricing, and stablecoins, at 1.5% when a seller turns them on. The card
3425
- * rate is therefore the dearest a pay link can cost, as `SALE_PROCESSING_PERCENT`
3426
- * is for a storefront. An international card adds Stripe's 1.5% surcharge,
3427
- * which this does not recover, the same as the register's card payments.
3428
- *
3429
- * Its own name for the reason `SALE_PROCESSING_PERCENT` has one: a storefront,
3430
- * a booking and the marketplace floor stay on the rate their own sessions can
3431
- * cost, and repointing this one moves pay links only.
3432
- */ export const PAY_LINK_PROCESSING_PERCENT = CARD_PROCESSING_PERCENT;
3433
- /** Stripe's per-transaction fixed component, in cents. Not rate-dependent. */ export const SALE_PROCESSING_FIXED_CENTS = PROCESSING_FIXED_CENTS;
3436
+ /** Klarna/Afterpay/Affirm (standard plans), roughly. No site checkout offers them since AGL-4198. */ export const BNPL_PROCESSING_PERCENT = 6;
3437
+ /** Stripe's per-transaction fixed component on a card, in cents. */ export const PROCESSING_FIXED_CENTS = 30;
3438
+ /**
3439
+ * What Stripe Connect bills the PLATFORM for paying a seller out (AGL-4198).
3440
+ * Sellers are Express accounts (`commerce/server/connect.ts`), and on the
3441
+ * "you handle pricing" model Stripe charges the platform 0.25% + 25¢ on every
3442
+ * payout sent and $2 for every account that is paid out in a month
3443
+ * (stripe.com/connect/pricing, read 2026-11-06). Every sale's money leaves
3444
+ * through a payout, so the percent rides every sale. The 25¢ is per payout,
3445
+ * which with daily payouts and one sale a day is one per sale: that is the
3446
+ * figure recovered, and a seller with several sales a day over-recovers it.
3447
+ * The $2 a month is not recovered per sale; the seller's paid plan, which
3448
+ * selling requires, carries it.
3449
+ */ export const CONNECT_PAYOUT_PERCENT = 0.25;
3450
+ /** Stripe Connect's fixed charge per payout sent, in cents. */ export const CONNECT_PAYOUT_FIXED_CENTS = 25;
3451
+ /**
3452
+ * Stripe Tax's charge on a Checkout transaction it calculates where the
3453
+ * platform is registered: 0.5% (stripe.com/tax/pricing, read 2026-11-06).
3454
+ * The platform is the account that runs `automatic_tax` on a site's session,
3455
+ * so a sale whose session runs it carries this too (`SaleProcessingOptions`).
3456
+ */ export const STRIPE_TAX_PERCENT = 0.5;
3457
+ /**
3458
+ * The processing a site sale passes through to the seller on top of the
3459
+ * plan's take (AGL-2152, AGL-4198): Stripe's card rate, 2.9% + 30¢, online
3460
+ * and on a card reader alike. Every checkout a site opens excludes
3461
+ * buy-now-pay-later, so no method a buyer can choose costs Stripe more online
3462
+ * (a card, Apple Pay, Google Pay, Link, Cash App Pay and Amazon Pay are 2.9% +
3463
+ * 30¢ on Stripe's US pricing, stablecoins 1.5%), and a reader's card costs
3464
+ * less (`TERMINAL_PROCESSING_PERCENT`).
3465
+ *
3466
+ * What the platform pays beyond it — Connect's payout and Stripe Tax — comes
3467
+ * out of the plan's take, with the fee never below the platform's whole cost
3468
+ * (`saleApplicationFeeCents`). A card issued abroad adds Stripe's 1.5%
3469
+ * surcharge, which is not recovered.
3470
+ */ export const SALE_PROCESSING_PERCENT = CARD_PROCESSING_PERCENT;
3471
+ /** The fixed cents a sale passes through: the card's 30¢. */ export const SALE_PROCESSING_FIXED_CENTS = PROCESSING_FIXED_CENTS;
3472
+ /**
3473
+ * Stripe Terminal's in-person card rate, US: 2.7% + 5¢, plus 10¢ for a Tap to
3474
+ * Pay authorization (stripe.com/terminal, read 2026-11-06).
3475
+ */ export const TERMINAL_PROCESSING_PERCENT = 2.7;
3476
+ /** Terminal's fixed cents per in-person card payment, Tap to Pay's 10¢ included (5¢ + 10¢). */ export const TERMINAL_PROCESSING_FIXED_CENTS = 15;
3434
3477
  /**
3435
3478
  * The cheapest plan whose BASE features include `feature`, in ladder order —
3436
3479
  * the answer to "which plan do I need for this?", which is the one thing an