@aglyn/aglyn 1.14.0 → 1.15.1

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 (94) 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 +6 -3
  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 +6 -6
  11. package/src/lib/app-utils/docs-help.generated.js +14 -1
  12. package/src/lib/app-utils/docs-help.generated.js.map +1 -1
  13. package/src/lib/app-utils/docs-index.generated.js +20 -20
  14. package/src/lib/app-utils/docs-index.generated.js.map +1 -1
  15. package/src/lib/app-utils/entity-picker-context.d.ts +6 -0
  16. package/src/lib/app-utils/entity-picker-context.js.map +1 -1
  17. package/src/lib/app-utils/host-status.js +1 -1
  18. package/src/lib/app-utils/host-status.js.map +1 -1
  19. package/src/lib/app-utils/org-role-grants.js +1 -1
  20. package/src/lib/app-utils/org-role-grants.js.map +1 -1
  21. package/src/lib/app-utils/page-header-record-context.d.ts +15 -0
  22. package/src/lib/app-utils/page-header-record-context.js +13 -4
  23. package/src/lib/app-utils/page-header-record-context.js.map +1 -1
  24. package/src/lib/app-utils/plan-entitlements.d.ts +125 -46
  25. package/src/lib/app-utils/plan-entitlements.js +118 -49
  26. package/src/lib/app-utils/plan-entitlements.js.map +1 -1
  27. package/src/lib/app-utils/plugin-bundle-checks.d.ts +14 -2
  28. package/src/lib/app-utils/plugin-bundle-checks.js +82 -7
  29. package/src/lib/app-utils/plugin-bundle-checks.js.map +1 -1
  30. package/src/lib/app-utils/plugin-connection-editor.d.ts +48 -0
  31. package/src/lib/app-utils/plugin-connection-editor.js +46 -0
  32. package/src/lib/app-utils/plugin-connection-editor.js.map +1 -0
  33. package/src/lib/app-utils/plugin-connection-record.d.ts +42 -0
  34. package/src/lib/app-utils/plugin-connection-record.js +48 -0
  35. package/src/lib/app-utils/plugin-connection-record.js.map +1 -0
  36. package/src/lib/app-utils/plugin-connection-records-context.d.ts +23 -0
  37. package/src/lib/app-utils/plugin-connection-records-context.js +29 -0
  38. package/src/lib/app-utils/plugin-connection-records-context.js.map +1 -0
  39. package/src/lib/app-utils/plugin-connection-records.d.ts +42 -0
  40. package/src/lib/app-utils/plugin-connection-records.js +56 -0
  41. package/src/lib/app-utils/plugin-connection-records.js.map +1 -0
  42. package/src/lib/app-utils/plugin-connections.d.ts +320 -0
  43. package/src/lib/app-utils/plugin-connections.js +895 -0
  44. package/src/lib/app-utils/plugin-connections.js.map +1 -0
  45. package/src/lib/app-utils/plugin-elements.d.ts +104 -0
  46. package/src/lib/app-utils/plugin-elements.js +128 -0
  47. package/src/lib/app-utils/plugin-elements.js.map +1 -0
  48. package/src/lib/app-utils/plugin-manifest.d.ts +20 -75
  49. package/src/lib/app-utils/plugin-manifest.js +65 -100
  50. package/src/lib/app-utils/plugin-manifest.js.map +1 -1
  51. package/src/lib/app-utils/realm-elements-context.d.ts +16 -0
  52. package/src/lib/app-utils/realm-elements-context.js +16 -0
  53. package/src/lib/app-utils/realm-elements-context.js.map +1 -1
  54. package/src/lib/app-utils/realm-host-surface.generated.js +1 -0
  55. package/src/lib/app-utils/realm-host-surface.generated.js.map +1 -1
  56. package/src/lib/app-utils/release-flags.d.ts +1 -1
  57. package/src/lib/app-utils/release-flags.js +35 -0
  58. package/src/lib/app-utils/release-flags.js.map +1 -1
  59. package/src/lib/app-utils/server.d.ts +1 -0
  60. package/src/lib/app-utils/server.js +2 -0
  61. package/src/lib/app-utils/server.js.map +1 -1
  62. package/src/lib/app-utils/site-context.d.ts +9 -0
  63. package/src/lib/app-utils/site-context.js.map +1 -1
  64. package/src/lib/app-utils/site-starter.d.ts +6 -0
  65. package/src/lib/app-utils/site-starter.js +15 -0
  66. package/src/lib/app-utils/site-starter.js.map +1 -1
  67. package/src/lib/plugin-manager/feature-plugins.d.ts +25 -0
  68. package/src/lib/plugin-manager/feature-plugins.js +10 -0
  69. package/src/lib/plugin-manager/feature-plugins.js.map +1 -1
  70. package/src/lib/plugin-manager/first-party-plugins.generated.js +12 -0
  71. package/src/lib/plugin-manager/first-party-plugins.generated.js.map +1 -1
  72. package/src/lib/plugin-manager/index.d.ts +1 -0
  73. package/src/lib/plugin-manager/index.js +1 -0
  74. package/src/lib/plugin-manager/index.js.map +1 -1
  75. package/src/lib/plugin-manager/plugin-artifact-inventory.d.ts +5 -0
  76. package/src/lib/plugin-manager/plugin-artifact-inventory.js.map +1 -1
  77. package/src/lib/plugin-manager/plugin-record-lists.d.ts +18 -0
  78. package/src/lib/plugin-manager/plugin-record-lists.js +13 -0
  79. package/src/lib/plugin-manager/plugin-record-lists.js.map +1 -1
  80. package/src/lib/plugin-manager/plugin-site-csp.d.ts +36 -0
  81. package/src/lib/plugin-manager/plugin-site-csp.js +50 -1
  82. package/src/lib/plugin-manager/plugin-site-csp.js.map +1 -1
  83. package/src/lib/plugin-manager/realm-host-aglyn.generated.js +61 -59
  84. package/src/lib/plugin-manager/realm-host-aglyn.generated.js.map +1 -1
  85. package/src/lib/plugin-manager/site-page-enricher-services.d.ts +35 -0
  86. package/src/lib/plugin-manager/site-page-enricher-services.js +35 -0
  87. package/src/lib/plugin-manager/site-page-enricher-services.js.map +1 -0
  88. package/src/lib/plugin-manager/site-page-hooks.js +16 -3
  89. package/src/lib/plugin-manager/site-page-hooks.js.map +1 -1
  90. package/src/lib/plugin-manager/video-embed-provider.d.ts +28 -0
  91. package/src/lib/plugin-manager/video-embed-provider.js +21 -0
  92. package/src/lib/plugin-manager/video-embed-provider.js.map +1 -1
  93. package/src/lib/plugin-manager/video-embed-providers.generated.js +3 -1
  94. package/src/lib/plugin-manager/video-embed-providers.generated.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,25 +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 path pins
1912
- * `payment_method_types`, 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.
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.
1926
1922
  */
1927
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;
1928
1970
  /**
1929
1971
  * The Stripe Connect `application_fee_amount` for ONE storefront sale
1930
1972
  * (AGL-2152) — the platform's advertised take PLUS Stripe's processing cost,
@@ -1949,8 +1991,9 @@ export declare function saleProcessingCostCents(chargeCents: number): number;
1949
1991
  * Clamped to `chargeCents` because Stripe rejects an application fee larger
1950
1992
  * than the charge. That clamp can only bind below ~32¢, under Stripe's own 50¢
1951
1993
  * charge minimum, so it never trims a real order's fee.
1994
+
1952
1995
  */
1953
- export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', feeBaseCents: number, chargeCents?: number): number;
1996
+ export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling> | null | undefined, productType: 'physical' | 'digital' | 'service', feeBaseCents: number, chargeCents?: number, options?: SaleProcessingOptions): number;
1954
1997
  /**
1955
1998
  * Stripe's processing cost on a RECURRING charge of `amountCents`, as the
1956
1999
  * percent a Subscription's `application_fee_percent` can carry (AGL-2655).
@@ -1964,8 +2007,8 @@ export declare function resolveTransactionFeeCents(org: Partial<AglynOrgBilling>
1964
2007
  * percent = rate + fixed ÷ amount
1965
2008
  *
1966
2009
  * which is why a smaller recurring price carries a HIGHER percent: the 30¢
1967
- * is a bigger share of it. At 6% + 30¢ a $10 price carries 9%, $25 carries
1968
- * 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%.
1969
2012
  *
1970
2013
  * Computed in hundredths of a percent on integers and rounded UP to the next
1971
2014
  * hundredth. Up, for the reason the one-time helper rounds its percentage
@@ -1997,7 +2040,13 @@ export declare function saleProcessingPassThroughPercent(amountCents: number): n
1997
2040
  * not always `8.34` in floating point), and capped at 100, Stripe's ceiling
1998
2041
  * for the parameter — the recurring twin of the clamp to the charge.
1999
2042
  */
2000
- 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;
2001
2050
  /**
2002
2051
  * Platform take rate % for a MARKETPLACE listing sale (AGL-1543), priced
2003
2052
  * off the SELLER org. Resolved through `resolveOrgEntitlements` — so a
@@ -2034,35 +2083,65 @@ export declare function bindingMarketplaceFeePct(): number;
2034
2083
  * they exist only as inputs to a platform take and to figures a seller reads;
2035
2084
  * changing one never changes a price list.
2036
2085
  *
2037
- * THE BNPL RATE IS THE ONE THAT BINDS, and it is not hypothetical: the live
2038
- * default payment method configuration has `klarna` and `affirm` enabled
2039
- * alongside `card`, `cashapp`, `link`, `amazon_pay` and `apple_pay`, and no
2040
- * checkout session pins `payment_method_types`, so a buyer may pay by either.
2041
- * A cost computed from the cheapest method would be wrong exactly when it
2042
- * mattered.
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`).
2043
2093
  */
2044
2094
  export declare const CARD_PROCESSING_PERCENT = 2.9;
2045
- /** 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. */
2046
2096
  export declare const BNPL_PROCESSING_PERCENT = 6;
2047
- /** Stripe's per-transaction fixed component, in cents. */
2097
+ /** Stripe's per-transaction fixed component on a card, in cents. */
2048
2098
  export declare const PROCESSING_FIXED_CENTS = 30;
2049
2099
  /**
2050
- * The processing rate a storefront or booking destination charge is priced
2051
- * against (AGL-2152), and the one identifier to repoint if those sessions'
2052
- * payment method set changes.
2053
- *
2054
- * Deliberately its OWN name rather than a direct use of the binding rate,
2055
- * while being defined as it: every seller shares Stripe's published rates and
2056
- * today shares the platform's payment method configuration, but each surface
2057
- * is a separate product decision. A future choice to pin
2058
- * `payment_method_types` on storefront sessions to the card family — and so
2059
- * to recover at `CARD_PROCESSING_PERCENT` — must not silently lower the
2060
- * marketplace listing floor, which is derived from the binding rate for a
2061
- * different flow.
2062
- */
2063
- export declare const SALE_PROCESSING_PERCENT = 6;
2064
- /** 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¢. */
2065
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;
2066
2145
  /**
2067
2146
  * The cheapest plan whose BASE features include `feature`, in ladder order —
2068
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,23 +3208,17 @@ 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 path pins
3212
- * `payment_method_types`, 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.
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.
3226
3222
  */ // `SALE_PROCESSING_PERCENT` and `SALE_PROCESSING_FIXED_CENTS` are declared
3227
3223
  // beside the processing constants they are defined from, further down this
3228
3224
  // file — a `const` cannot be read before its declaration is evaluated, and
@@ -3231,6 +3227,40 @@ export function saleProcessingCostCents(chargeCents) {
3231
3227
  if (!Number.isFinite(chargeCents) || chargeCents <= 0) return 0;
3232
3228
  return Math.ceil(chargeCents * SALE_PROCESSING_PERCENT / 100) + SALE_PROCESSING_FIXED_CENTS;
3233
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)));
3263
+ }
3234
3264
  /**
3235
3265
  * The Stripe Connect `application_fee_amount` for ONE storefront sale
3236
3266
  * (AGL-2152) — the platform's advertised take PLUS Stripe's processing cost,
@@ -3255,7 +3285,8 @@ export function saleProcessingCostCents(chargeCents) {
3255
3285
  * Clamped to `chargeCents` because Stripe rejects an application fee larger
3256
3286
  * than the charge. That clamp can only bind below ~32¢, under Stripe's own 50¢
3257
3287
  * charge minimum, so it never trims a real order's fee.
3258
- */ export function resolveTransactionFeeCents(org, productType, feeBaseCents, chargeCents = feeBaseCents) {
3288
+
3289
+ */ export function resolveTransactionFeeCents(org, productType, feeBaseCents, chargeCents = feeBaseCents, options = {}) {
3259
3290
  const charge = Number.isFinite(chargeCents) && chargeCents > 0 ? Math.round(chargeCents) : 0;
3260
3291
  if (charge <= 0) return 0;
3261
3292
  const base = Number.isFinite(feeBaseCents) && feeBaseCents > 0 ? Math.round(feeBaseCents) : 0;
@@ -3263,7 +3294,7 @@ export function saleProcessingCostCents(chargeCents) {
3263
3294
  // The `Math.max(1, …)` every door already applied: a rate above zero on
3264
3295
  // goods the shopper pays for is a fee however small it rounds to.
3265
3296
  const take = pct > 0 && base > 0 ? Math.max(1, Math.round(base * pct / 100)) : 0;
3266
- return Math.min(charge, take + saleProcessingCostCents(charge));
3297
+ return saleApplicationFeeCents(take, charge, options);
3267
3298
  }
3268
3299
  /**
3269
3300
  * Stripe's processing cost on a RECURRING charge of `amountCents`, as the
@@ -3278,8 +3309,8 @@ export function saleProcessingCostCents(chargeCents) {
3278
3309
  * percent = rate + fixed ÷ amount
3279
3310
  *
3280
3311
  * which is why a smaller recurring price carries a HIGHER percent: the 30¢
3281
- * is a bigger share of it. At 6% + 30¢ a $10 price carries 9%, $25 carries
3282
- * 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%.
3283
3314
  *
3284
3315
  * Computed in hundredths of a percent on integers and rounded UP to the next
3285
3316
  * hundredth. Up, for the reason the one-time helper rounds its percentage
@@ -3294,7 +3325,7 @@ export function saleProcessingCostCents(chargeCents) {
3294
3325
  const amount = Number.isFinite(amountCents) && amountCents > 0 ? Math.round(amountCents) : 0;
3295
3326
  if (amount <= 0) return 0;
3296
3327
  const rateHundredths = Math.round(SALE_PROCESSING_PERCENT * 100);
3297
- // 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
3298
3329
  // it hundredths of one.
3299
3330
  const fixedHundredths = SALE_PROCESSING_FIXED_CENTS * 10000 / amount;
3300
3331
  return Math.min(100, Math.ceil(rateHundredths + fixedHundredths) / 100);
@@ -3317,12 +3348,25 @@ export function saleProcessingCostCents(chargeCents) {
3317
3348
  * Composed in hundredths so two decimals stay two decimals (`2 + 6.34` is
3318
3349
  * not always `8.34` in floating point), and capped at 100, Stripe's ceiling
3319
3350
  * for the parameter — the recurring twin of the clamp to the charge.
3320
- */ export function resolveSubscriptionFeePercent(org, productType, amountCents) {
3351
+ */ export function resolveSubscriptionFeePercent(org, productType, amountCents, options = {}) {
3321
3352
  const amount = Number.isFinite(amountCents) && amountCents > 0 ? Math.round(amountCents) : 0;
3322
3353
  if (amount <= 0) return 0;
3323
3354
  const take = resolveTransactionFeePct(org, productType);
3355
+ if (options.direct) return Math.min(100, Math.round(take * 100) / 100);
3324
3356
  const passThrough = saleProcessingPassThroughPercent(amount);
3325
- 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);
3326
3370
  }
3327
3371
  /**
3328
3372
  * Platform take rate % for a MARKETPLACE listing sale (AGL-1543), priced
@@ -3381,30 +3425,55 @@ export function saleProcessingCostCents(chargeCents) {
3381
3425
  * they exist only as inputs to a platform take and to figures a seller reads;
3382
3426
  * changing one never changes a price list.
3383
3427
  *
3384
- * THE BNPL RATE IS THE ONE THAT BINDS, and it is not hypothetical: the live
3385
- * default payment method configuration has `klarna` and `affirm` enabled
3386
- * alongside `card`, `cashapp`, `link`, `amazon_pay` and `apple_pay`, and no
3387
- * checkout session pins `payment_method_types`, so a buyer may pay by either.
3388
- * A cost computed from the cheapest method would be wrong exactly when it
3389
- * mattered.
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`).
3390
3435
  */ export const CARD_PROCESSING_PERCENT = 2.9;
3391
- /** Klarna/Affirm, roughly. See the note above — this is the binding one. */ export const BNPL_PROCESSING_PERCENT = 6;
3392
- /** Stripe's per-transaction fixed component, in cents. */ export const PROCESSING_FIXED_CENTS = 30;
3393
- /**
3394
- * The processing rate a storefront or booking destination charge is priced
3395
- * against (AGL-2152), and the one identifier to repoint if those sessions'
3396
- * payment method set changes.
3397
- *
3398
- * Deliberately its OWN name rather than a direct use of the binding rate,
3399
- * while being defined as it: every seller shares Stripe's published rates and
3400
- * today shares the platform's payment method configuration, but each surface
3401
- * is a separate product decision. A future choice to pin
3402
- * `payment_method_types` on storefront sessions to the card family — and so
3403
- * to recover at `CARD_PROCESSING_PERCENT` — must not silently lower the
3404
- * marketplace listing floor, which is derived from the binding rate for a
3405
- * different flow.
3406
- */ export const SALE_PROCESSING_PERCENT = BNPL_PROCESSING_PERCENT;
3407
- /** 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;
3408
3477
  /**
3409
3478
  * The cheapest plan whose BASE features include `feature`, in ladder order —
3410
3479
  * the answer to "which plan do I need for this?", which is the one thing an