@fantastic.dev/better-stripe 0.70.0 → 0.72.0

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 (112) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +524 -50
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +246 -9
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +524 -50
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +246 -9
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/paymentSource/resolver.d.ts +6 -1
  12. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  13. package/dist/client/paymentSource/resolver.js +49 -41
  14. package/dist/client/paymentSource/resolver.js.map +1 -1
  15. package/dist/client/processingCostReconciliation/provider.d.ts.map +1 -1
  16. package/dist/client/processingCostReconciliation/provider.js +14 -2
  17. package/dist/client/processingCostReconciliation/provider.js.map +1 -1
  18. package/dist/client/readContracts.d.ts +1 -0
  19. package/dist/client/readContracts.d.ts.map +1 -1
  20. package/dist/client/readContracts.js.map +1 -1
  21. package/dist/client/settlement/authorization.fixture.d.ts +26 -0
  22. package/dist/client/settlement/authorization.fixture.d.ts.map +1 -1
  23. package/dist/client/settlement/execution.d.ts +2 -0
  24. package/dist/client/settlement/execution.d.ts.map +1 -1
  25. package/dist/client/settlement/execution.js.map +1 -1
  26. package/dist/client/usage/index.d.ts +1 -0
  27. package/dist/client/usage/index.d.ts.map +1 -1
  28. package/dist/client/usage/invoiceSale.d.ts +8 -0
  29. package/dist/client/usage/invoiceSale.d.ts.map +1 -1
  30. package/dist/client/usage/invoiceSale.js +3 -0
  31. package/dist/client/usage/invoiceSale.js.map +1 -1
  32. package/dist/client/usage/mixedInvoice.fixtures.d.ts +315 -0
  33. package/dist/client/usage/mixedInvoice.fixtures.d.ts.map +1 -0
  34. package/dist/client/usage/mixedInvoice.fixtures.js +55 -0
  35. package/dist/client/usage/mixedInvoice.fixtures.js.map +1 -0
  36. package/dist/client/usage/mixedInvoiceSale.d.ts +6 -0
  37. package/dist/client/usage/mixedInvoiceSale.d.ts.map +1 -0
  38. package/dist/client/usage/mixedInvoiceSale.js +160 -0
  39. package/dist/client/usage/mixedInvoiceSale.js.map +1 -0
  40. package/dist/client/usage/observationClient.d.ts +2 -2
  41. package/dist/client/usage/observationClient.d.ts.map +1 -1
  42. package/dist/client/usage/retainedInvoiceSource.d.ts +20 -0
  43. package/dist/client/usage/retainedInvoiceSource.d.ts.map +1 -0
  44. package/dist/client/usage/retainedInvoiceSource.js +92 -0
  45. package/dist/client/usage/retainedInvoiceSource.js.map +1 -0
  46. package/dist/client/usage/settlement.d.ts +5 -0
  47. package/dist/client/usage/settlement.d.ts.map +1 -1
  48. package/dist/client/usage/settlement.js +28 -9
  49. package/dist/client/usage/settlement.js.map +1 -1
  50. package/dist/component/_generated/component.d.ts +66 -0
  51. package/dist/component/_generated/component.d.ts.map +1 -1
  52. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  53. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  54. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  55. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  56. package/dist/component/earnings/triggers.d.ts +84 -6
  57. package/dist/component/earnings/triggers.d.ts.map +1 -1
  58. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  59. package/dist/component/products/queries.d.ts +1 -0
  60. package/dist/component/products/queries.d.ts.map +1 -1
  61. package/dist/component/products/queries.js +14 -8
  62. package/dist/component/products/queries.js.map +1 -1
  63. package/dist/component/recoveryWorkflow/helpers.d.ts +13 -0
  64. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
  65. package/dist/component/recoveryWorkflow/mutations.d.ts +13 -0
  66. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
  67. package/dist/component/recoveryWorkflow/queries.d.ts +26 -0
  68. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
  69. package/dist/component/recoveryWorkflow/schema.d.ts +464 -16
  70. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
  71. package/dist/component/schema.d.ts +246 -9
  72. package/dist/component/settlement/mutations.d.ts +26 -0
  73. package/dist/component/settlement/mutations.d.ts.map +1 -1
  74. package/dist/component/settlement/queries.d.ts +13 -0
  75. package/dist/component/settlement/queries.d.ts.map +1 -1
  76. package/dist/component/settlement/schema.d.ts +122 -3
  77. package/dist/component/settlement/schema.d.ts.map +1 -1
  78. package/dist/component/settlement/schema.js +2 -0
  79. package/dist/component/settlement/schema.js.map +1 -1
  80. package/dist/component/usage/allowance.fixtures.d.ts +262 -25
  81. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  82. package/dist/component/usageCredits/accounting.fixtures.d.ts +246 -9
  83. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  84. package/dist/shared/usageInvoiceLines.d.ts +32 -0
  85. package/dist/shared/usageInvoiceLines.d.ts.map +1 -0
  86. package/dist/shared/usageInvoiceLines.js +13 -0
  87. package/dist/shared/usageInvoiceLines.js.map +1 -0
  88. package/docs/evidence/native-metering/mixed-settlement-2026-10-20.json +284 -0
  89. package/docs/metering-setup.md +3 -2
  90. package/docs/read-contracts.md +9 -2
  91. package/docs/usage-example.md +24 -5
  92. package/docs/usage-settlement.md +74 -8
  93. package/docs/usage-verification.md +22 -2
  94. package/package.json +1 -1
  95. package/src/client/paymentSource/resolver.ts +80 -59
  96. package/src/client/processingCostReconciliation/provider.ts +20 -2
  97. package/src/client/readContracts.ts +1 -0
  98. package/src/client/readPagination.test.ts +21 -0
  99. package/src/client/settlement/execution.ts +2 -0
  100. package/src/client/usage/index.ts +2 -0
  101. package/src/client/usage/invoiceSale.ts +10 -0
  102. package/src/client/usage/mixedInvoice.fixtures.ts +54 -0
  103. package/src/client/usage/mixedInvoiceSale.test.ts +92 -0
  104. package/src/client/usage/mixedInvoiceSale.ts +196 -0
  105. package/src/client/usage/mixedSettlement.test.ts +187 -0
  106. package/src/client/usage/retainedInvoiceSource.ts +118 -0
  107. package/src/client/usage/settlement.ts +47 -9
  108. package/src/component/_generated/component.ts +51 -0
  109. package/src/component/products/provider-price-pagination.test.ts +174 -0
  110. package/src/component/products/queries.ts +24 -10
  111. package/src/component/settlement/schema.ts +2 -0
  112. package/src/shared/usageInvoiceLines.ts +14 -0
@@ -0,0 +1,284 @@
1
+ {
2
+ "kind": "native-mixed-invoice-settlement",
3
+ "date": "2026-10-20",
4
+ "ticket": "BTS-287",
5
+ "livemode": false,
6
+ "apiVersion": "2026-09-30.endive",
7
+ "method": "Compiled BetterStripe SDK against native Stripe test APIs; isolated Accounts v2 payer/test clock for initial and renewal cash; original product example invoice replay through billing hook and durable settlement workflow. No shared customer clock advancement.",
8
+ "fixture": {
9
+ "runId": "bts287-native-v1",
10
+ "clockId": "clock_1USSD76JR7kThJogiWhQYpXY",
11
+ "sellerAccountId": "acct_1UQ78o7xOsB2U2nM",
12
+ "productId": "prod_VTP1DX2R2js6f5",
13
+ "invoiceId": "in_1USSDC6JR7kThJog3yQnJQdG",
14
+ "input": {
15
+ "scope": {
16
+ "stripeAccountId": "acct_1TEQzE6JR7kThJog",
17
+ "customerAccount": "acct_1USSD78k9tFVeKFN",
18
+ "meterId": "mtr_test_61VbqAVIxs9O0sFgt416JR7kThJogO5w",
19
+ "livemode": false
20
+ },
21
+ "binding": {
22
+ "stripeCustomerId": "cus_VTP1D5rkZMxZHc",
23
+ "stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
24
+ "eventName": "bts287_native_v1",
25
+ "apiVersion": "2026-09-30.endive",
26
+ "plan": {
27
+ "key": "bts287-native-v1",
28
+ "version": "v1",
29
+ "unit": {
30
+ "name": "minute",
31
+ "precision": 0
32
+ },
33
+ "rate": {
34
+ "currency": "usd",
35
+ "unitAmountDecimal": "100"
36
+ },
37
+ "model": "included_overage",
38
+ "includedQuantity": "60",
39
+ "reset": "billing_period"
40
+ }
41
+ },
42
+ "subscription": {
43
+ "subscriptionId": "sub_1USSDC6JR7kThJogK1m7V9Q2",
44
+ "subscriptionItemId": "si_VTP1jHuM4LSQWN",
45
+ "stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
46
+ "period": {
47
+ "start": 1792461060,
48
+ "end": 1795139460
49
+ },
50
+ "interval": "month"
51
+ },
52
+ "period": {
53
+ "start": 1792461060,
54
+ "end": 1795139460
55
+ },
56
+ "fixedPrice": {
57
+ "stripePriceId": "price_1USSDA6JR7kThJoguUhyBEXl",
58
+ "subscriptionItemId": "si_VTP18QFXyYFnDo",
59
+ "unitAmount": 2000
60
+ }
61
+ }
62
+ },
63
+ "initial": {
64
+ "sourceChargeId": "ch_3USSDf6JR7kThJog0F5su3xa",
65
+ "paymentIntentId": "pi_3USSDf6JR7kThJog0Zj92PRp",
66
+ "sourceInvoiceId": "in_1USSDC6JR7kThJog3yQnJQdG",
67
+ "usageSource": {
68
+ "customerAccount": "acct_1USSD78k9tFVeKFN",
69
+ "invoiceLines": [
70
+ {
71
+ "amount": 2000,
72
+ "kind": "fixed",
73
+ "lineId": "il_1USSCe6JR7kThJogfcJks0En",
74
+ "period": {
75
+ "end": 1795139460,
76
+ "start": 1792461060
77
+ },
78
+ "quantity": "1",
79
+ "stripePriceId": "price_1USSDA6JR7kThJoguUhyBEXl",
80
+ "stripeProductId": "prod_VTP1DX2R2js6f5",
81
+ "subscriptionItemId": "si_VTP18QFXyYFnDo"
82
+ }
83
+ ],
84
+ "invoicePaymentId": "inpay_1USSDf6JR7kThJogCongDU4L",
85
+ "livemode": false,
86
+ "meterId": "mtr_test_61VbqAVIxs9O0sFgt416JR7kThJogO5w",
87
+ "model": "included_overage",
88
+ "period": {
89
+ "end": 1795139460,
90
+ "start": 1792461060
91
+ },
92
+ "stripeAccountId": "acct_1TEQzE6JR7kThJog",
93
+ "stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
94
+ "stripeProductId": "prod_VTP1DX2R2js6f5",
95
+ "subscriptionId": "sub_1USSDC6JR7kThJogK1m7V9Q2",
96
+ "subscriptionItemId": "si_VTP1jHuM4LSQWN"
97
+ },
98
+ "gross": 2000,
99
+ "currency": "usd",
100
+ "processingFee": 88,
101
+ "platformNet": 92,
102
+ "transfers": [
103
+ {
104
+ "amount": 1820,
105
+ "destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
106
+ "role": "store"
107
+ }
108
+ ],
109
+ "status": "settled",
110
+ "executedTransfers": [
111
+ {
112
+ "stripeTransferId": "tr_3USSDf6JR7kThJog0X6GYuWa",
113
+ "destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
114
+ "role": "store",
115
+ "amount": 1820
116
+ }
117
+ ]
118
+ },
119
+ "renewalInvoice": {
120
+ "id": "in_1USSEa6JR7kThJogK6C02ulM",
121
+ "status": "open",
122
+ "total": 3500,
123
+ "paid": 0,
124
+ "reason": "subscription_cycle",
125
+ "lines": [
126
+ {
127
+ "id": "il_1Udgye6JR7kThJogo8mem1ju",
128
+ "amount": 0,
129
+ "quantity": "60",
130
+ "period": {
131
+ "end": 1795139460,
132
+ "start": 1792461060
133
+ },
134
+ "price": "price_1USSDA6JR7kThJogT3xsgBd6"
135
+ },
136
+ {
137
+ "id": "il_1Udgyf6JR7kThJogGYOwmntt",
138
+ "amount": 1500,
139
+ "quantity": "15",
140
+ "period": {
141
+ "end": 1795139460,
142
+ "start": 1792461060
143
+ },
144
+ "price": "price_1USSDA6JR7kThJogT3xsgBd6"
145
+ },
146
+ {
147
+ "id": "il_1Udgyg6JR7kThJog3UoOkXqt",
148
+ "amount": 2000,
149
+ "quantity": "1",
150
+ "period": {
151
+ "end": 1797731460,
152
+ "start": 1795139460
153
+ },
154
+ "price": "price_1USSDA6JR7kThJoguUhyBEXl"
155
+ }
156
+ ]
157
+ },
158
+ "renewal": {
159
+ "sourceChargeId": "ch_3USSEg6JR7kThJog1TT4PblE",
160
+ "paymentIntentId": "pi_3USSEg6JR7kThJog1beR1tZF",
161
+ "sourceInvoiceId": "in_1USSEa6JR7kThJogK6C02ulM",
162
+ "usageSource": {
163
+ "customerAccount": "acct_1USSD78k9tFVeKFN",
164
+ "invoiceLines": [
165
+ {
166
+ "amount": 0,
167
+ "kind": "metered",
168
+ "lineId": "il_1Udgye6JR7kThJogo8mem1ju",
169
+ "period": {
170
+ "end": 1795139460,
171
+ "start": 1792461060
172
+ },
173
+ "quantity": "60",
174
+ "stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
175
+ "stripeProductId": "prod_VTP1DX2R2js6f5",
176
+ "subscriptionItemId": "si_VTP1jHuM4LSQWN"
177
+ },
178
+ {
179
+ "amount": 1500,
180
+ "kind": "metered",
181
+ "lineId": "il_1Udgyf6JR7kThJogGYOwmntt",
182
+ "period": {
183
+ "end": 1795139460,
184
+ "start": 1792461060
185
+ },
186
+ "quantity": "15",
187
+ "stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
188
+ "stripeProductId": "prod_VTP1DX2R2js6f5",
189
+ "subscriptionItemId": "si_VTP1jHuM4LSQWN"
190
+ },
191
+ {
192
+ "amount": 2000,
193
+ "kind": "fixed",
194
+ "lineId": "il_1Udgyg6JR7kThJog3UoOkXqt",
195
+ "period": {
196
+ "end": 1797731460,
197
+ "start": 1795139460
198
+ },
199
+ "quantity": "1",
200
+ "stripePriceId": "price_1USSDA6JR7kThJoguUhyBEXl",
201
+ "stripeProductId": "prod_VTP1DX2R2js6f5",
202
+ "subscriptionItemId": "si_VTP18QFXyYFnDo"
203
+ }
204
+ ],
205
+ "invoicePaymentId": "inpay_1USSEh6JR7kThJogqGqDt0l7",
206
+ "livemode": false,
207
+ "meterId": "mtr_test_61VbqAVIxs9O0sFgt416JR7kThJogO5w",
208
+ "model": "included_overage",
209
+ "period": {
210
+ "end": 1795139460,
211
+ "start": 1792461060
212
+ },
213
+ "stripeAccountId": "acct_1TEQzE6JR7kThJog",
214
+ "stripePriceId": "price_1USSDA6JR7kThJogT3xsgBd6",
215
+ "stripeProductId": "prod_VTP1DX2R2js6f5",
216
+ "subscriptionId": "sub_1USSDC6JR7kThJogK1m7V9Q2",
217
+ "subscriptionItemId": "si_VTP1jHuM4LSQWN"
218
+ },
219
+ "gross": 3500,
220
+ "currency": "usd",
221
+ "processingFee": 132,
222
+ "platformNet": 183,
223
+ "transfers": [
224
+ {
225
+ "amount": 3185,
226
+ "destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
227
+ "role": "store"
228
+ }
229
+ ],
230
+ "status": "settled",
231
+ "executedTransfers": [
232
+ {
233
+ "stripeTransferId": "tr_3USSEg6JR7kThJog11S3kprM",
234
+ "destinationAccountId": "acct_1UQ78o7xOsB2U2nM",
235
+ "role": "store",
236
+ "amount": 3185
237
+ }
238
+ ]
239
+ },
240
+ "replay": "Second native settle returned the same original tr_3USSEg6JR7kThJog11S3kprM, amount3185, with no additional transfer.",
241
+ "automaticProductExample": {
242
+ "sourceInvoiceId": "in_1USC3M6JR7kThJog1yJkx0lS",
243
+ "stripeSubscriptionId": "sub_1USC3O6JR7kThJogep66wAiF",
244
+ "chargeId": "ch_3USC3N6JR7kThJog1kfdYxoa",
245
+ "paymentIntentId": "pi_3USC3N6JR7kThJog1dIMNxz8",
246
+ "gross": 2000,
247
+ "processingFee": 88,
248
+ "sellingFee": 180,
249
+ "platformNet": 92,
250
+ "sellerNet": 1820,
251
+ "costRecoveryAmount": 0,
252
+ "status": "settled",
253
+ "sellerTransferId": "tr_3USC3N6JR7kThJog1DrgShEg",
254
+ "stripeProductId": "prod_VQz7JDdU8Tr7GZ"
255
+ },
256
+ "partialRefund": {
257
+ "id": "re_3USSEg6JR7kThJog14TYHCy7",
258
+ "amount": 700,
259
+ "status": "succeeded"
260
+ },
261
+ "refundAudit": {
262
+ "invoiceId": "in_1USSEa6JR7kThJogK6C02ulM",
263
+ "paymentIntentId": "pi_3USSEg6JR7kThJog1beR1tZF",
264
+ "chargeId": "ch_3USSEg6JR7kThJog1TT4PblE",
265
+ "refunded": 700,
266
+ "transfersComplete": true,
267
+ "transfers": [
268
+ {
269
+ "id": "tr_3USSEg6JR7kThJog11S3kprM",
270
+ "amount": 3185,
271
+ "reversed": 637,
272
+ "sourceChargeId": "ch_3USSEg6JR7kThJog1TT4PblE"
273
+ }
274
+ ],
275
+ "cost": {
276
+ "status": "ready",
277
+ "gross": 3500,
278
+ "fee": 132,
279
+ "refundAdjustment": 0,
280
+ "principalReturned": 700
281
+ }
282
+ },
283
+ "cleanup": "The isolated subscription is cancel_at_period_end=true; original financial evidence and test resources retained."
284
+ }
@@ -115,8 +115,9 @@ configure the admin's own Store analytics reports product and verify that work i
115
115
  held before a paid grant and denied after credit exhaustion.
116
116
 
117
117
  Follow [the product walkthrough](usage-example.md) for exact steps, authorization,
118
- payment verification, retained history and the mixed-invoice seller-settlement
119
- limitation. Product subscriptions use actual native billing periods and the
118
+ payment verification, retained history and automatic mixed-invoice seller
119
+ settlement. Activate the seller's paid store plan and complete Stripe recipient onboarding
120
+ before accepting new customer payments. Product subscriptions use actual native billing periods and the
120
121
  customer's original account; this flow does not advance shared test clocks.
121
122
 
122
123
  For isolated clock-driven renewal, correction and cleanup checks, use Admin →
@@ -9,14 +9,21 @@ methods remain available. Neither an array preview nor one cursor page is an
9
9
  exact financial total.
10
10
 
11
11
  Products support `accountId` and `active`. Prices support the component's
12
- `productId` and `active`; this ID differs from `stripeProductId`. Authorize the
12
+ `productId` and `active`; this ID differs from `stripeProductId`. Alternatively,
13
+ pass `stripeProductId` alone for an **unfiltered** page from the existing provider-product
14
+ index. Combining that selector with `productId` or either `active: true` or
15
+ `active: false` throws before any read. Provider pages retain inactive rows and
16
+ contradictory component-product links so hosts can validate them rather than hide
17
+ them with an active filter. They use the same page bounds, descending order,
18
+ opaque continuations, pinned end cursors and native split hints. These cached rows
19
+ do not prove provider completeness, ownership or financial eligibility. Authorize the
13
20
  parent product before exposing price reads. Payout history requires `accountId`
14
21
  and optionally accepts `status`. No filter means no restriction on that field.
15
22
  An omitted product account filter includes all accounts, including platform
16
23
  products. Host applications must derive allowed account and product scope from
17
24
  the authenticated user. A client-supplied account ID is not authorization.
18
25
 
19
- The Vite reference provides bindings in `example/convex/readContracts.ts` and
26
+ The Vite reference provides bindings in `example/convex/readContracts/queries.ts` and
20
27
  `example/src/lib/stripe-hooks.ts`. Its selectable personas are demo identities.
21
28
  Production hosts must replace them with session authorization.
22
29
 
@@ -120,11 +120,30 @@ is retained and the native invoice preview remains available; the example does
120
120
  not round a billing period and claim an exact reconciliation. Credit grants also keep their original
121
121
  price and ownership terms.
122
122
 
123
- **Automatic seller settlement for mixed fixed-fee and usage invoices is not
124
- supported by the current verifier.** Customer billing can work while seller
125
- transfers remain held. The example does not bypass the verifier, report a paid
126
- invoice as settled earnings, or allocate mixed cash using a browser estimate.
127
- Existing single-source settlement protocols remain in the separate diagnostics.
123
+ Paid product invoices route automatically through the original managed Checkout,
124
+ enrollment and seller-owned product. The example settles the initial monthly fee
125
+ and later monthly-plus-overage invoices only after verifying complete native
126
+ lines, a single full captured payment and actual processing costs. The seller's product fee policy applies to the whole mixed invoice. Product enrollments
127
+ have no referral attribution; SDK hosts can authorize affiliates explicitly. Metadata
128
+ locates the managed intent; it never chooses the seller or payout amount.
129
+
130
+ New seller Checkout sessions use the same active paid-plan and Stripe recipient
131
+ readiness checks as the ordinary storefront. Unready stores are hidden from new
132
+ buyers; original enrollments remain readable. Completed Checkout reconciliation
133
+ and existing renewals preserve original purchased terms after a store lapses. The
134
+ enrollment pins that plan as a fallback for already-purchased terms; renewals use
135
+ the current seller tier or retained purchased tier, as ordinary store sales do.
136
+ The existing settlement workflow reserves owned recovery obligations, persists
137
+ complete original line provenance, and reauthorizes the seller and cash proof
138
+ before each new transfer. `invoice.paid`, `payment_intent.succeeded` and
139
+ `charge.updated` all route through original invoice funding. Pending fees retry;
140
+ replayed events retain the same allocation and transfer IDs. Issuer-owned services
141
+ retain their proceeds without creating a seller transfer.
142
+
143
+ Foreign products/items, incomplete funding, discounts/taxes/credits, prorations,
144
+ refunded/disputed new sales and unsupported recipient configurations remain held.
145
+ See [native usage settlement](usage-settlement.md) for the SDK contract and
146
+ [verification evidence](usage-verification.md) for actual test-mode economics.
128
147
 
129
148
  ## Package APIs and UI implementations
130
149
 
@@ -82,14 +82,52 @@ payments, unrelated priced invoice lines, proration, mismatched original periods
82
82
  converted settlement currencies and automatic destination/on-behalf-of charges
83
83
  are held through explicit non-ready outcomes. The method does not guess a
84
84
  multi-product allocation or take over existing destination-charge fee handling.
85
- Fixed-plus-metered invoices remain readable with the ordinary invoice APIs, but
86
- this automatic settlement method requires one paid original meter line. Native
87
- included-overage invoices can also contain one zero-priced included-tier line.
88
- Both lines must retain the same original price, product, subscription item,
89
- period, currency and mode, with no credit adjustments. The complete independent
90
- line-item read must match both original IDs. Additional paid lines, duplicate IDs
91
- and foreign zero-priced siblings remain unsupported. Treat unsupported settlement
92
- combinations as unavailable evidence rather than zero proceeds.
85
+ For a mixed invoice, provide the original monthly item explicitly:
86
+
87
+ ```ts
88
+ const mixedOriginal = {
89
+ ...original,
90
+ fixedPrice: {
91
+ stripePriceId: originalMonthlyPriceId,
92
+ subscriptionItemId: originalMonthlyItemId,
93
+ unitAmount: 2000, // USD 20; quantity must be one
94
+ },
95
+ };
96
+ const source = await stripe.usage.getInvoiceSale(ctx, mixedOriginal, provider);
97
+ // Pass mixedOriginal to settleInvoice with the same server-authorized policy.
98
+ ```
99
+
100
+ This supports one original product with one licensed monthly item and one metered
101
+ item. The initial invoice may contain only the monthly fee. Renewals may contain
102
+ that fee plus a metered line, or a zero included tier and a paid overage tier.
103
+ Every native line must match the pinned product, price and subscription item;
104
+ complete bounded pagination is mandatory. A USD 20 base plus USD 15 overage is
105
+ one USD 35 cash sale with one actual processing fee and one conserved allocation.
106
+ Fixed fees are billed in advance and usage in arrears, so each original native
107
+ line period is retained separately. No minute rounding or current-price lookup
108
+ is used to reconstruct historical periods. `invoiceLines` retains every line's
109
+ identity, amount, exact quantity and period in the immutable charge allocation.
110
+
111
+ Additional products/items, discounts, taxes, credits, negative adjustments,
112
+ prorations, partial or multiple funding, and automatic destination charges remain
113
+ held. Single-meter settlement without `fixedPrice` keeps its existing stricter
114
+ period and line rules. A ready read proves proceeds; it does not authorize a
115
+ recipient by itself.
116
+
117
+ Use `authorize` on `settleInvoice` to recheck original ownership and sealed
118
+ allocation after reads and immediately before each new transfer. Throw to hold a
119
+ changed seller or liability policy. For host-owned recovery workflows, the
120
+ optional `allocation` accepts the same conserved allocation as `settleSale`,
121
+ including `policyContext` and `adjustmentAmount`. The host owns commission
122
+ selection for that resolved allocation. Retain the complete `usageSource` when
123
+ passing it to a durable recovery workflow; do not reconstruct it from metadata.
124
+ Mixed-invoice processing-cost reconciliation checks the sealed original lines and
125
+ InvoicePayment again, so refunds/disputes cannot substitute a new funding receipt.
126
+ Mixed invoices with pre-payment or post-payment credit notes are held for both
127
+ new transfers and retained-source cost reconciliation, including credit notes
128
+ that issue customer-balance or out-of-band credit without refunding the charge.
129
+ Credit-note-backed refunds require separate native credit-note-to-refund proof;
130
+ this flow supports ordinary cash refunds and disputes without credit notes.
93
131
 
94
132
  ## Prepaid issuer-service revenue
95
133
 
@@ -165,3 +203,31 @@ provenance, fractional quantity, included tiers, zero-first-invoice commission,
165
203
  transfer-success/persistence-failure, replay, prepaid purchase consumption and
166
204
  refund guards. These tests are not a new native financial sandbox execution;
167
205
  project-wide native acceptance is recorded separately.
206
+
207
+ ## Verify mixed billing in development
208
+
209
+ Use the example's existing Stripe test key and a test seller with active transfer
210
+ capability. Run commands from `example/` against the intended development
211
+ Convex deployment. The internal `meteredProducts/mixedProof` fixture rejects live
212
+ keys and creates its own clock and Accounts v2 payer. Do not advance the shared
213
+ example customer's clock.
214
+
215
+ 1. Call `meteredProducts/mixedProof:prepare` with a unique `runId` starting with
216
+ `mixed-proof-`, a minute-aligned UNIX `start` timestamp, and the test
217
+ `sellerAccountId`. Retain its returned JSON as `fixtureJson` for later calls.
218
+ 2. Call `meteredProducts/mixedProof:run` with `fixtureJson` and `phase: "usage"`
219
+ to record 75 minutes, then `phase: "pay"` to pay the initial USD 20 invoice
220
+ with the fixture's synthetic test payment method. `phase: "settle"` verifies
221
+ actual processing costs and creates the original seller transfer.
222
+ 3. Call `phase: "advance"` once. Inspect with `phase: "inspect"` until the
223
+ clock is ready and the renewal contains USD 20 base plus USD 15 overage.
224
+ Pass that original renewal `invoiceId` to `pay`, then `settle` twice.
225
+ Both settlement results must retain the same transfer ID.
226
+ 4. `phase: "refund"` issues a USD 7 test refund on the selected invoice.
227
+ `phase: "audit"` reads complete native transfers and processing costs.
228
+ Verify proportional reversal against the original allocation, then call
229
+ `phase: "cancel"` to stop future renewals. Retain financial evidence.
230
+
231
+ These internal fixtures are developer verification tools. The product UI uses
232
+ original Checkout enrollments, with seller/customer authorization in the host.
233
+ The fixture does not substitute for testing the application's authentication.
@@ -88,8 +88,8 @@ comes from the product example, separately from the isolated protocol fixtures a
88
88
 
89
89
  These are test-mode observations, not finalized renewal or seller-settlement
90
90
  proof. Exact native meter summaries reject partial-minute subscription boundaries.
91
- The draft invoices remain estimates. Mixed fixed-fee and usage settlement stays
92
- held. The earlier unsupported automatic-collection prepaid test enrollment was
91
+ The draft invoices remain estimates. That run preceded mixed-invoice settlement
92
+ support; the later mixed-invoice proof below verifies original paid cash and transfers. The earlier unsupported automatic-collection prepaid test enrollment was
93
93
  retained and its renewal canceled; corrected enrollments use `send_invoice`.
94
94
 
95
95
  The product regression suite covers store enablement, ownership, immutable
@@ -146,3 +146,23 @@ worker/DB failures, retained quota limits and API-version refusals use determini
146
146
  SDK/component tests. No load or sustained throughput certification is claimed.
147
147
  These checks authorize neither live billing nor automatic production migration,
148
148
  publication or replay of unknown historical provider writes.
149
+
150
+ ## Mixed monthly fee and usage settlement
151
+
152
+ The isolated 2026-10-20 native Stripe test uses a separate Accounts v2 payer and
153
+ minute-aligned test clock. It leaves the product example customer's clock intact.
154
+ [Retained native evidence](evidence/native-metering/mixed-settlement-2026-10-20.json)
155
+ records the original complete line periods, funding, actual fees and transfer IDs.
156
+
157
+ | Original invoice | Paid | Actual processing | Platform net | Seller transfer |
158
+ | ----------------------------------------------------------- | --------: | ----------------: | -----------: | --------------: |
159
+ | Initial monthly fee | USD 20.00 | USD 0.88 | USD 0.92 | USD 18.20 |
160
+ | Renewal: next monthly fee + 15 prior-period overage minutes | USD 35.00 | USD 1.32 | USD 1.83 | USD 31.85 |
161
+
162
+ The renewal contains three native lines: 60 included minutes at zero, 15 extra
163
+ minutes at USD 1, and the next USD 20 monthly fee. Replaying settlement returned
164
+ the same transfer ID. A native USD 7 partial refund reversed USD 6.37 of
165
+ the USD 31.85 seller transfer. The actual product example's initial USD 20 invoice
166
+ also settled through the billing hook and durable recovery workflow. SDK regressions also cover complete pagination, foreign
167
+ lines, taxes/credits/prorations, reauthorization, lost transfer receipts, sealed
168
+ funding identity and refund/dispute cost observations.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.70.0",
3
+ "version": "0.72.0",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -50,8 +50,13 @@ export async function resolveVerifiedPaymentSource(
50
50
  stripe: Stripe,
51
51
  input: VerifiedPaymentSourceOptions,
52
52
  eligibility?: {
53
- requirePayable: true;
53
+ requirePayable: boolean;
54
54
  customerId: string;
55
+ /** Internal native-line verifier; never exposed as browser input. */
56
+ verifyInvoiceLines?: (
57
+ invoice: Stripe.Invoice,
58
+ lines: Stripe.InvoiceLineItem[],
59
+ ) => { stripePriceId: string; stripeProductId: string } | null;
55
60
  invoiceLine?: {
56
61
  id: string;
57
62
  zeroAmountLineIds?: string[];
@@ -132,12 +137,13 @@ export async function resolveVerifiedPaymentSource(
132
137
  );
133
138
  const customerAccountId = payment.customer_account!;
134
139
  if (eligibility) {
135
- requireSource(
136
- charge.amount_refunded === 0 &&
137
- charge.disputed === false &&
138
- charge.refunded === false,
139
- reject("payment_not_payable"),
140
- );
140
+ if (eligibility.requirePayable)
141
+ requireSource(
142
+ charge.amount_refunded === 0 &&
143
+ charge.disputed === false &&
144
+ charge.refunded === false,
145
+ reject("payment_not_payable"),
146
+ );
141
147
  requireSource(
142
148
  objectId(payment.customer) === eligibility.customerId &&
143
149
  objectId(charge.customer) === eligibility.customerId,
@@ -326,63 +332,78 @@ export async function resolveVerifiedPaymentSource(
326
332
  ),
327
333
  );
328
334
  if (lines.status !== "complete") return lines;
329
- const zeroIds = eligibility?.invoiceLine?.zeroAmountLineIds ?? [];
330
- const line = zeroIds.length
331
- ? lines.data.find((row) => row.id === eligibility!.invoiceLine!.id)
332
- : lines.data[0];
333
- requireSource(
334
- line &&
335
- (zeroIds.length
336
- ? zeroTierLinesMatch(lines.data, line, zeroIds)
337
- : lines.data.length === 1),
338
- reject("unsupported_source"),
339
- );
340
- if (!line) return reject("unsupported_source");
341
- requireSource(
342
- line.object === "line_item" &&
343
- line.invoice === invoice.id &&
344
- line.livemode === payment.livemode,
345
- identity(),
335
+ const verifiedLines = eligibility?.verifyInvoiceLines?.(
336
+ invoice,
337
+ lines.data,
346
338
  );
347
- requireSource(line.currency === opts.currency, reject("currency_mismatch"));
348
- requireSource(
349
- integer(line.amount) &&
350
- line.amount > 0 &&
351
- (line.quantity_decimal != null
352
- ? /^\d{1,30}(\.\d{1,12})?$/.test(line.quantity_decimal.toString()) &&
353
- /[1-9]/.test(line.quantity_decimal.toString())
354
- : Number.isSafeInteger(line.quantity) && line.quantity! > 0),
355
- reject("unsupported_source"),
356
- );
357
- const parent = line.parent;
358
- if (eligibility?.invoiceLine) {
359
- const expected = eligibility.invoiceLine;
339
+ if (eligibility?.verifyInvoiceLines)
340
+ requireSource(verifiedLines, reject("unsupported_source"));
341
+ let priceId = verifiedLines?.stripePriceId;
342
+ let productId = verifiedLines?.stripeProductId;
343
+ if (!verifiedLines) {
344
+ const zeroIds = eligibility?.invoiceLine?.zeroAmountLineIds ?? [];
345
+ const line = zeroIds.length
346
+ ? lines.data.find((row) => row.id === eligibility!.invoiceLine!.id)
347
+ : lines.data[0];
360
348
  requireSource(
361
- line.id === expected.id &&
362
- line.parent?.subscription_item_details?.subscription_item ===
363
- expected.subscriptionItemId &&
364
- line.period.start === expected.period.start &&
365
- line.period.end === expected.period.end,
349
+ line &&
350
+ (zeroIds.length
351
+ ? zeroTierLinesMatch(lines.data, line, zeroIds)
352
+ : lines.data.length === 1),
353
+ reject("unsupported_source"),
354
+ );
355
+ if (!line) return reject("unsupported_source");
356
+ requireSource(
357
+ line.object === "line_item" &&
358
+ line.invoice === invoice.id &&
359
+ line.livemode === payment.livemode,
366
360
  identity(),
367
361
  );
362
+ requireSource(
363
+ line.currency === opts.currency,
364
+ reject("currency_mismatch"),
365
+ );
366
+ requireSource(
367
+ integer(line.amount) &&
368
+ line.amount > 0 &&
369
+ (line.quantity_decimal != null
370
+ ? /^\d{1,30}(\.\d{1,12})?$/.test(
371
+ line.quantity_decimal.toString(),
372
+ ) && /[1-9]/.test(line.quantity_decimal.toString())
373
+ : Number.isSafeInteger(line.quantity) && line.quantity! > 0),
374
+ reject("unsupported_source"),
375
+ );
376
+ const parent = line.parent;
377
+ if (eligibility?.invoiceLine) {
378
+ const expected = eligibility.invoiceLine;
379
+ requireSource(
380
+ line.id === expected.id &&
381
+ line.parent?.subscription_item_details?.subscription_item ===
382
+ expected.subscriptionItemId &&
383
+ line.period.start === expected.period.start &&
384
+ line.period.end === expected.period.end,
385
+ identity(),
386
+ );
387
+ }
388
+ const lineSubscription =
389
+ parent?.subscription_item_details?.subscription ??
390
+ parent?.invoice_item_details?.subscription ??
391
+ undefined;
392
+ requireSource(lineSubscription === subscriptionId, identity());
393
+ requireSource(
394
+ !parent?.subscription_item_details?.proration &&
395
+ !parent?.invoice_item_details?.proration,
396
+ reject("unsupported_source"),
397
+ );
398
+ const price = line.pricing?.price_details;
399
+ priceId = objectId(price?.price);
400
+ productId = objectId(price?.product);
401
+ requireSource(
402
+ line.pricing?.type === "price_details" && priceId && productId,
403
+ reject("unsupported_source"),
404
+ );
368
405
  }
369
- const lineSubscription =
370
- parent?.subscription_item_details?.subscription ??
371
- parent?.invoice_item_details?.subscription ??
372
- undefined;
373
- requireSource(lineSubscription === subscriptionId, identity());
374
- requireSource(
375
- !parent?.subscription_item_details?.proration &&
376
- !parent?.invoice_item_details?.proration,
377
- reject("unsupported_source"),
378
- );
379
- const price = line.pricing?.price_details;
380
- const priceId = objectId(price?.price);
381
- const productId = objectId(price?.product);
382
- requireSource(
383
- line.pricing?.type === "price_details" && priceId && productId,
384
- reject("unsupported_source"),
385
- );
406
+ requireSource(priceId && productId, reject("unsupported_source"));
386
407
  return {
387
408
  status: "ready",
388
409
  value: {