@fantastic.dev/better-stripe 0.72.1 → 0.72.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.
package/CHANGELOG.md CHANGED
@@ -26,6 +26,12 @@
26
26
  - Remove internal tracker references from public documentation and add a
27
27
  regression check that prevents their reintroduction.
28
28
 
29
+ ## [0.72.2](https://github.com/FantasticDevHQ/better-stripe/compare/v0.72.1...v0.72.2) (2026-10-20)
30
+
31
+ ### Tests
32
+
33
+ - verify Maya membership across both integration views ([#374](https://github.com/FantasticDevHQ/better-stripe/issues/374)) ([4faf5c7](https://github.com/FantasticDevHQ/better-stripe/commit/4faf5c76e6b274ac118004d42bbf0febe14dcbff))
34
+
29
35
  ## [0.72.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.72.0...v0.72.1) (2026-10-20)
30
36
 
31
37
  ### Bug Fixes
package/README.md CHANGED
@@ -5,7 +5,7 @@ billing, and Connect marketplaces. It provides checkout, subscriptions, webhook
5
5
  syncing, marketplace fees and splits, payouts, refunds, and disputes, with React
6
6
  hooks and headless UI components.
7
7
 
8
- **Version**: `0.72.1` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
8
+ **Version**: `0.72.2` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
9
9
 
10
10
  Connect platforms use the default GA API version. Non-Connect merchants using
11
11
  customer-only Accounts v2 need preview access and an explicit preview version.
@@ -0,0 +1,331 @@
1
+ {
2
+ "date": "2026-10-20",
3
+ "mode": "Stripe test mode only",
4
+ "applicationBaseCommit": "7bd8ce8c9e5d244549ecf4044ddcf4c33bf792ff",
5
+ "apiVersion": "2026-09-30.endive",
6
+ "resources": {
7
+ "runId": "mixed-proof-maya-flow-20261020",
8
+ "actorId": "jh7fs3waa4rb9k63v2npgk5bwh8gnq4c",
9
+ "enrollmentId": "mn782k3g8r0qmhcfn6b6tgpmr18gn8kk",
10
+ "clockId": "clock_1USU1X6JR7kThJogboSkmZ2o",
11
+ "productId": "prod_VQz7JDdU8Tr7GZ"
12
+ },
13
+ "subscriptionId": "sub_1USU2G6JR7kThJogbypHm3mp",
14
+ "scope": {
15
+ "stripeAccountId": "acct_1TEQzE6JR7kThJog",
16
+ "customerAccount": "acct_1USU1X5QGFCnyfry",
17
+ "meterId": "mtr_test_61VbZsGvUoYJdVdWP416JR7kThJogJ8i",
18
+ "livemode": false
19
+ },
20
+ "terms": {
21
+ "baseMonthly": 2000,
22
+ "currency": "usd",
23
+ "includedMinutes": "60",
24
+ "overagePerMinute": 100
25
+ },
26
+ "includedBoundary": {
27
+ "revision": 1,
28
+ "observedAt": 1792468158,
29
+ "period": {
30
+ "start": 1792468020,
31
+ "end": 1795146420
32
+ },
33
+ "accepting": true,
34
+ "policy": {
35
+ "reset": "billing_period",
36
+ "rollover": "none",
37
+ "entitled": true,
38
+ "overage": "allow",
39
+ "limit": {
40
+ "mode": "none"
41
+ }
42
+ },
43
+ "consumedQuantity": "60",
44
+ "reservedQuantity": "0",
45
+ "includedQuantity": "60",
46
+ "remainingIncludedQuantity": "0",
47
+ "billableOverageQuantity": "0",
48
+ "softLimitReached": false,
49
+ "hardLimitRemainingQuantity": null,
50
+ "committedEstimate": {
51
+ "amountDecimal": "0",
52
+ "currency": "usd"
53
+ },
54
+ "projectedEstimate": {
55
+ "amountDecimal": "0",
56
+ "currency": "usd"
57
+ },
58
+ "cashCollection": "none"
59
+ },
60
+ "overageBoundary": {
61
+ "revision": 1,
62
+ "observedAt": 1792468206,
63
+ "period": {
64
+ "start": 1792468020,
65
+ "end": 1795146420
66
+ },
67
+ "accepting": true,
68
+ "policy": {
69
+ "reset": "billing_period",
70
+ "rollover": "none",
71
+ "entitled": true,
72
+ "overage": "allow",
73
+ "limit": {
74
+ "mode": "none"
75
+ }
76
+ },
77
+ "consumedQuantity": "75",
78
+ "reservedQuantity": "0",
79
+ "includedQuantity": "60",
80
+ "remainingIncludedQuantity": "0",
81
+ "billableOverageQuantity": "15",
82
+ "softLimitReached": false,
83
+ "hardLimitRemainingQuantity": null,
84
+ "committedEstimate": {
85
+ "amountDecimal": "1500",
86
+ "currency": "usd"
87
+ },
88
+ "projectedEstimate": {
89
+ "amountDecimal": "1500",
90
+ "currency": "usd"
91
+ },
92
+ "cashCollection": "none"
93
+ },
94
+ "workReceipts": {
95
+ "included": {
96
+ "status": "accepted",
97
+ "work": "completed_once",
98
+ "receiptId": "ss761tyfh1dw6mmeggsg994pyn8gm09m"
99
+ },
100
+ "overage": {
101
+ "status": "accepted",
102
+ "work": "completed_once",
103
+ "receiptId": "ss7chs78fdr3aptjbg5mps42bh8gnk0q"
104
+ },
105
+ "overageReplay": {
106
+ "status": "accepted",
107
+ "work": "already_completed",
108
+ "receiptId": "ss7chs78fdr3aptjbg5mps42bh8gnk0q"
109
+ }
110
+ },
111
+ "nativePreviewAt75": {
112
+ "status": "available",
113
+ "observedAt": 1792468289,
114
+ "value": {
115
+ "kind": "preview",
116
+ "invoiceId": "upcoming_in_1USU5F6JR7kThJogT3yFTUsH",
117
+ "status": "draft",
118
+ "finalized": false,
119
+ "amountDue": "3500",
120
+ "amountPaid": "0",
121
+ "total": "3500",
122
+ "currency": "usd",
123
+ "linesComplete": true,
124
+ "lines": [
125
+ {
126
+ "lineId": "il_tmp_1Udimu6JR7kThJogTd7sXnnm",
127
+ "stripePriceId": "price_1USBuv6JR7kThJogV6whMAi1",
128
+ "subscriptionItemId": "si_VTQuuxBhuesMV6",
129
+ "amount": "0",
130
+ "currency": "usd",
131
+ "quantity": "60",
132
+ "providerQuantityDecimal": "60",
133
+ "unitAmountDecimal": "0",
134
+ "creditAppliedAmount": "0",
135
+ "nativePeriod": {
136
+ "start": 1792468020,
137
+ "end": 1795146420
138
+ },
139
+ "proration": false
140
+ },
141
+ {
142
+ "lineId": "il_tmp_1Udimv6JR7kThJog58V4UVOe",
143
+ "stripePriceId": "price_1USBuv6JR7kThJogV6whMAi1",
144
+ "subscriptionItemId": "si_VTQuuxBhuesMV6",
145
+ "amount": "1500",
146
+ "currency": "usd",
147
+ "quantity": "15",
148
+ "providerQuantityDecimal": "15",
149
+ "unitAmountDecimal": "100",
150
+ "creditAppliedAmount": "0",
151
+ "nativePeriod": {
152
+ "start": 1792468020,
153
+ "end": 1795146420
154
+ },
155
+ "proration": false
156
+ }
157
+ ],
158
+ "meterAmount": {
159
+ "status": "available",
160
+ "observedAt": 1792468289,
161
+ "value": {
162
+ "amount": "1500",
163
+ "currency": "usd"
164
+ }
165
+ },
166
+ "paymentEvidence": "not_resolved"
167
+ }
168
+ },
169
+ "renewalInvoices": {
170
+ "clock": "ready",
171
+ "invoices": [
172
+ {
173
+ "id": "in_1USU5e6JR7kThJogVOaODkrh",
174
+ "status": "paid",
175
+ "total": 3500,
176
+ "paid": 3500,
177
+ "reason": "subscription_cycle",
178
+ "lines": [
179
+ {
180
+ "id": "il_1Udimu6JR7kThJogADf0225h",
181
+ "amount": 0,
182
+ "quantity": "60",
183
+ "period": {
184
+ "end": 1795146420,
185
+ "start": 1792468020
186
+ },
187
+ "price": "price_1USBuv6JR7kThJogV6whMAi1"
188
+ },
189
+ {
190
+ "id": "il_1Udimv6JR7kThJogG91IEkec",
191
+ "amount": 1500,
192
+ "quantity": "15",
193
+ "period": {
194
+ "end": 1795146420,
195
+ "start": 1792468020
196
+ },
197
+ "price": "price_1USBuv6JR7kThJogV6whMAi1"
198
+ },
199
+ {
200
+ "id": "il_1Udimw6JR7kThJogbYb4RWqA",
201
+ "amount": 2000,
202
+ "quantity": "1",
203
+ "period": {
204
+ "end": 1797738420,
205
+ "start": 1795146420
206
+ },
207
+ "price": "price_1USBuv6JR7kThJogI6gSporz"
208
+ }
209
+ ]
210
+ },
211
+ {
212
+ "id": "in_1USU2E6JR7kThJoggMhgHzt4",
213
+ "status": "paid",
214
+ "total": 2000,
215
+ "paid": 2000,
216
+ "reason": "subscription_create",
217
+ "lines": [
218
+ {
219
+ "id": "il_1USU2E6JR7kThJogqATE5w4a",
220
+ "amount": 2000,
221
+ "quantity": "1",
222
+ "period": {
223
+ "end": 1795146420,
224
+ "start": 1792468020
225
+ },
226
+ "price": "price_1USBuv6JR7kThJogI6gSporz"
227
+ }
228
+ ]
229
+ }
230
+ ]
231
+ },
232
+ "initialAutomaticSettlement": {
233
+ "invoiceId": "in_1USU2E6JR7kThJoggMhgHzt4",
234
+ "paymentIntentId": "pi_3USU2F6JR7kThJog0VBncoSi",
235
+ "chargeId": "ch_3USU2F6JR7kThJog0pXlIAYP",
236
+ "refunded": 0,
237
+ "transfersComplete": true,
238
+ "transfers": [
239
+ {
240
+ "id": "tr_3USU2F6JR7kThJog0IFiOSKC",
241
+ "amount": 1820,
242
+ "destination": "acct_1UQ78o7xOsB2U2nM",
243
+ "livemode": false,
244
+ "reversed": 0,
245
+ "sourceChargeId": "ch_3USU2F6JR7kThJog0pXlIAYP"
246
+ }
247
+ ],
248
+ "cost": {
249
+ "status": "ready",
250
+ "gross": 2000,
251
+ "fee": 88,
252
+ "refundAdjustment": 0,
253
+ "principalReturned": 0
254
+ }
255
+ },
256
+ "renewalAutomaticSettlement": {
257
+ "invoiceId": "in_1USU5e6JR7kThJogVOaODkrh",
258
+ "paymentIntentId": "pi_3USU5m6JR7kThJog0PPhEj85",
259
+ "chargeId": "ch_3USU5m6JR7kThJog0ZAxUqIh",
260
+ "refunded": 0,
261
+ "transfersComplete": true,
262
+ "transfers": [
263
+ {
264
+ "id": "tr_3USU5m6JR7kThJog0X2fqpD0",
265
+ "amount": 3185,
266
+ "reversed": 0,
267
+ "sourceChargeId": "ch_3USU5m6JR7kThJog0ZAxUqIh"
268
+ }
269
+ ],
270
+ "cost": {
271
+ "status": "ready",
272
+ "gross": 3500,
273
+ "fee": 132,
274
+ "refundAdjustment": 0,
275
+ "principalReturned": 0
276
+ }
277
+ },
278
+ "renewalAfterWebhookReplay": {
279
+ "invoiceId": "in_1USU5e6JR7kThJogVOaODkrh",
280
+ "paymentIntentId": "pi_3USU5m6JR7kThJog0PPhEj85",
281
+ "chargeId": "ch_3USU5m6JR7kThJog0ZAxUqIh",
282
+ "refunded": 0,
283
+ "transfersComplete": true,
284
+ "transfers": [
285
+ {
286
+ "id": "tr_3USU5m6JR7kThJog0X2fqpD0",
287
+ "amount": 3185,
288
+ "destination": "acct_1UQ78o7xOsB2U2nM",
289
+ "livemode": false,
290
+ "reversed": 0,
291
+ "sourceChargeId": "ch_3USU5m6JR7kThJog0ZAxUqIh"
292
+ }
293
+ ],
294
+ "cost": {
295
+ "status": "ready",
296
+ "gross": 3500,
297
+ "fee": 132,
298
+ "refundAdjustment": 0,
299
+ "principalReturned": 0
300
+ }
301
+ },
302
+ "automaticProof": "Both transfers were present on native audits before manually replaying any settlement webhook. The manual settle fixture phase was never called.",
303
+ "ui": {
304
+ "persona": "Alex Customer",
305
+ "enrollmentId": "mn79p3nw2m8a9vhhynm8rb1wq98gk9f1",
306
+ "initialMinutes": 75,
307
+ "initialOverage": 15,
308
+ "initialPreviewTotal": 3500,
309
+ "viaApiAddedMinutes": 1,
310
+ "componentsAddedMinutes": 1,
311
+ "finalMinutes": 77,
312
+ "finalOverage": 17,
313
+ "finalSessionCount": 3,
314
+ "recording": "Sequenced screenshots; continuous recording unavailable through browser control.",
315
+ "finalNativePreviewTotal": 3700,
316
+ "finalNativeUsageAmount": 1700
317
+ },
318
+ "limits": [
319
+ "Draft previews and aggregation lag are estimates.",
320
+ "No future-period work was sent before the real server acceptance window.",
321
+ "No shared product archived or shared customer clock advanced.",
322
+ "No live billing, production migration or package publication."
323
+ ],
324
+ "sellerAccountId": "acct_1UQ78o7xOsB2U2nM",
325
+ "cleanup": "fixture_renewal_cancelled_history_retained",
326
+ "futurePeriodGuard": {
327
+ "status": "held",
328
+ "message": "The original billing period is not active.",
329
+ "operation": "Final fixture inspect after clock renewal; fresh native observation refuses the future period on the real server."
330
+ }
331
+ }
@@ -0,0 +1,97 @@
1
+ # Verify Maya's membership end to end
2
+
3
+ Maya's Fitness Coaching Membership costs USD 20 per month, includes 60 whole
4
+ coaching minutes, and charges USD 1 per extra minute. Both **via API** and
5
+ **BetterStripe components** use the same enrollment and authorized coaching
6
+ operation. The tabs change usage/history rendering, not the purchased product.
7
+
8
+ ## UI check
9
+
10
+ Start the [example](metering-setup.md) and open `/demo/metered-usage` as Customer.
11
+ Review Maya's original membership. Complete Checkout in Stripe test mode if it
12
+ has not already been paid, then refresh enrollment. Check both integration tabs
13
+ before and after completing coaching work. Switching tabs must retain the same
14
+ subscription and history without adding usage. Refresh usage/history after
15
+ provider delivery, then preview the next invoice.
16
+
17
+ On 2026-10-20, Alex's existing membership initially had one 75-minute session.
18
+ Both tabs showed 60 included, zero remaining and 15 overage minutes. Stripe's
19
+ native preview was USD 35, including USD 15 usage. One additional minute was
20
+ submitted with via API selected, then one with BetterStripe components selected.
21
+ Both completed once. Each view subsequently showed three sessions, 77 minutes
22
+ and 17 overage minutes. These extra test minutes remain in Alex's history.
23
+
24
+ Delivery and native aggregation are separate asynchronous steps. During this
25
+ check, Stripe first showed 60 native minutes while the local ledger had already
26
+ accepted and delivered 75. The native preview later reached USD 35. Do not
27
+ advance a renewal until the original native invoice preview includes all intended
28
+ usage. A draft preview is an estimate, not captured cash or transfer authority.
29
+ Partial-minute Checkout periods may not support an exact meter-summary read;
30
+ use the invoice preview without rounding the original period.
31
+
32
+ ## Isolated renewal using the same product
33
+
34
+ Do not advance Alex's shared clock or replace his payer. The internal developer
35
+ fixture `meteredProducts/membershipProof` creates a hidden test buyer with its own
36
+ Accounts v2 account and clock, then calls the ordinary product Checkout against
37
+ Maya's existing offer. It creates no replacement product, pricing or usage ledger.
38
+ It rejects ordinary customers as fixture buyers and future clock start times.
39
+ Only run it on the example development deployment with a Stripe test key.
40
+
41
+ Run Convex commands from `example/`. Query `meteredProducts/catalog:list` with
42
+ Maya's actor ID to find her existing offer. Use the saved `ownerId` and offer
43
+ `_id`, not a price or account supplied by a browser. Prepare with:
44
+
45
+ ```text
46
+ meteredProducts/membershipProof:prepare
47
+ { "runId": "mixed-proof-maya-<unique-name>", "start": <current Unix seconds rounded down to a minute>, "ownerId": "<Maya user ID>", "offerId": "<original offer ID>" }
48
+ ```
49
+
50
+ Save these exact arguments for retries, especially `start`. The response contains
51
+ `actorId`, `enrollmentId`, `clockId` and the original Checkout URL. Keep that URL
52
+ out of committed evidence. Open it and pay with Stripe's synthetic 4242 test card.
53
+ The return page retains the browser's existing demo persona; this hidden buyer
54
+ is exercised through the ordinary backend functions below.
55
+
56
+ Call `membershipProof:inspect` with `runId`, `actorId`, `enrollmentId`, `clockId`.
57
+ It verifies fixture ownership and clock provenance before reconciling the
58
+ completed Checkout, and returns the original fixture JSON used for native reads.
59
+ Use `meteredProducts/work:consume` with the returned buyer and enrollment:
60
+
61
+ 1. Submit `requestId: "included-60", quantity: "60"`. Read
62
+ `meteredProducts/readers:snapshot`: consumed 60, included 60, remaining zero,
63
+ overage zero. The next invoice preview must remain USD 20.
64
+ 2. Submit `requestId: "overage-15", quantity: "15"`. Retry the identical request.
65
+ The retry must report `already_completed` with the same receipt. The snapshot
66
+ must show two sessions, 75 consumed, 15 overage and USD 15 estimated usage.
67
+ 3. Wait for delivery and native aggregation. Use `readers:preview` until the
68
+ complete original preview shows USD 35 and USD 15 metered usage. Do not infer
69
+ aggregation from the delivery receipt alone.
70
+ 4. Call `meteredProducts/mixedProof:run` with the saved `fixtureJson` and
71
+ `phase: "audit"` to read the initial payment, actual fee and automatic transfer.
72
+ Then use `phase: "advance"` to advance only the validated fixture clock.
73
+ Poll `phase: "inspect"` until the clock is ready. The renewal contains 60
74
+ included minutes at zero, 15 overage minutes at USD 15, and USD 20 for the next
75
+ monthly period. Automatic collection must pay USD 35.
76
+ 5. Audit again with that original renewal `invoiceId`. The ordinary billing
77
+ webhooks must have created the seller transfer. Do not call the fixture's
78
+ manual `settle` phase when claiming automatic settlement. Replay
79
+ `billing/events/actions:process` with `type: "invoice.paid"` and that invoice
80
+ ID, then audit again. The transfer ID and transfer count must stay unchanged.
81
+ 6. Call `membershipProof:cleanup` with the four original fixture identifiers.
82
+ It expires an unpaid fixture Checkout or cancels future fixture renewal while
83
+ retaining financial history. It does not archive Maya's shared product.
84
+
85
+ The [native evidence](evidence/native-metering/maya-membership-2026-10-20.json)
86
+ records this check's original resources. Initial USD 20 split into USD 0.88 actual
87
+ processing fee, USD 0.92 platform share and USD 18.20 seller transfer. Renewal
88
+ USD 35 split into USD 1.32 fee, USD 1.83 platform share and USD 31.85 seller transfer.
89
+ These are observed test-mode fees, not a fee schedule to hardcode.
90
+
91
+ The renewal uses a future test-clock period. This check does not claim that the
92
+ real server accepts work before that future period begins. See the controlled
93
+ clock tests and [documented limits](usage-verification.md#tested-limits).
94
+ UI evidence consists of sequenced screenshots; the browser-control interface did
95
+ not expose continuous screen recording. Native receipts prove billing and
96
+ transfers separately from those screenshots. No live billing or production
97
+ migration is part of this exercise.
@@ -166,3 +166,11 @@ the USD 31.85 seller transfer. The actual product example's initial USD 20 invoi
166
166
  also settled through the billing hook and durable recovery workflow. SDK regressions also cover complete pagination, foreign
167
167
  lines, taxes/credits/prorations, reauthorization, lost transfer receipts, sealed
168
168
  funding identity and refund/dispute cost observations.
169
+
170
+ ## Maya's original product membership
171
+
172
+ The [Maya membership walkthrough](maya-membership-verification.md) repeats the
173
+ check against Maya's existing product, through ordinary Checkout, coaching work,
174
+ package delivery and automatic invoice webhooks. It verifies the exact 60-minute
175
+ boundary before adding 15 minutes, then proves the USD 35 renewal and original
176
+ seller transfer. Both UI integration views also submit and display coaching work.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.72.1",
3
+ "version": "0.72.2",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",