@fantastic.dev/better-stripe 0.64.0 → 0.64.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.
- package/CHANGELOG.md +6 -0
- package/README.md +3 -1
- package/docs/README.md +2 -0
- package/docs/usage-verification.md +117 -0
- package/package.json +3 -2
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.64.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.64.0...v0.64.1) (2026-10-18)
|
|
30
|
+
|
|
31
|
+
### Tests
|
|
32
|
+
|
|
33
|
+
- **usage:** verify native three-model economics and packed consumers ([#349](https://github.com/FantasticDevHQ/better-stripe/issues/349)) ([d6f801a](https://github.com/FantasticDevHQ/better-stripe/commit/d6f801ab209f55535fdea075fa5c0072f7da66cd))
|
|
34
|
+
|
|
29
35
|
## [0.64.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.63.0...v0.64.0) (2026-10-18)
|
|
30
36
|
|
|
31
37
|
### Features
|
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.64.
|
|
8
|
+
**Version**: `0.64.1` <!-- 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.
|
|
@@ -163,4 +163,6 @@ Use the [reusable metered billing UI](docs/usage-react.md) for exact usage, allo
|
|
|
163
163
|
|
|
164
164
|
Run [all three models in the native sandbox example](docs/usage-example.md), including paid invoices, renewal, correction and scoped cleanup.
|
|
165
165
|
|
|
166
|
+
The [verification matrix](docs/usage-verification.md) maps all three models to packed-consumer, native sandbox and failure-injection checks.
|
|
167
|
+
|
|
166
168
|
Use the [native usage configuration UI](docs/usage-configuration.md) for all three billing models, immutable meters and exact rates.
|
package/docs/README.md
CHANGED
|
@@ -83,3 +83,5 @@ Start with the [native Stripe setup guide](metering-setup.md), then read the
|
|
|
83
83
|
- [Native usage configuration UI](usage-configuration.md) covers reusable forms, managed meter selection, price rows and authorized adapters.
|
|
84
84
|
|
|
85
85
|
- [Native metered billing example](usage-example.md), three runnable models, paid evidence and scoped cleanup.
|
|
86
|
+
|
|
87
|
+
- [Metered usage verification](usage-verification.md), three-model acceptance, packed consumers, native proof and failure limits.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Metered usage verification
|
|
2
|
+
|
|
3
|
+
BetterStripe supports pay as you go, included monthly units with overages, and
|
|
4
|
+
paid prepaid credits. This matrix separates actual Stripe sandbox observations
|
|
5
|
+
from deterministic failure tests. It does not certify live-money eligibility or
|
|
6
|
+
production throughput.
|
|
7
|
+
|
|
8
|
+
## Reproduce the checks
|
|
9
|
+
|
|
10
|
+
From the repository root, with the pinned pnpm dependencies installed:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
pnpm run build
|
|
14
|
+
pnpm exec vitest run src/client/usage src/component/usage src/react/workflows/Usage example/convex/meteredUsage scripts/usage-contracts-packed.test.mjs scripts/usage-composition-packed.test.mjs scripts/usage-models-packed.test.mjs scripts/verify-usage-evidence.test.mjs
|
|
15
|
+
node scripts/verify-usage-evidence.mjs
|
|
16
|
+
pnpm run check:all
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The packed tests extract an actual `pnpm pack` archive into an external temporary
|
|
20
|
+
consumer. Import resolution is asserted against the extracted package. The
|
|
21
|
+
three-model test registers its actual compiled Convex component, invokes public
|
|
22
|
+
reservation and recording APIs, races competing work against the remaining units,
|
|
23
|
+
and renders the resulting balances through the packed React components. No
|
|
24
|
+
provider is called by that deterministic test. Its prepaid setup injects verified
|
|
25
|
+
fixture backing through internal component functions; native payment verification
|
|
26
|
+
is separately exercised through real SDK transports and the sandbox flows below.
|
|
27
|
+
|
|
28
|
+
## Three-model acceptance matrix
|
|
29
|
+
|
|
30
|
+
| Contract | Pay as you go | Included monthly units and overages | Paid prepaid credits |
|
|
31
|
+
| ----------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
32
|
+
| Packed public API and actual component | Immutable record and replay; configured hard cap | Reserve, consume, exact free/overage boundary and hard cap | Unpaid purchase cannot reserve; verified backing, reserve, consume and exhaustion |
|
|
33
|
+
| Competing packed work | Exactly one remaining-capacity request commits | Exactly one remaining-capacity request commits | Exactly one last-units request commits |
|
|
34
|
+
| Packed React view | Actual allowance accounting and estimate | Actual included quantity, overage and estimate | Actual available, consumed and exhausted balance |
|
|
35
|
+
| Sandbox local/native effective units | 15 / 15 | 15 / 15, including 10 free units | 10 / 10, funded by the original 10-unit purchase |
|
|
36
|
+
| Original paid native usage invoice, USD minor units | 1500 | 500, with native zero-priced included line plus overage line | 0 due and paid; 1000 rated usage covered by original native credits |
|
|
37
|
+
| Original cash source | InvoicePayment → original PaymentIntent/Charge | InvoicePayment → original PaymentIntent/Charge | Original paid purchase PaymentIntent/Charge, gross 1000 |
|
|
38
|
+
| Actual processing fee, USD minor units | 74 | 45 | 59 on the original purchase |
|
|
39
|
+
| Eligible seller / affiliate transfer, USD minor units | 1080 / 270 | 360 / 90 | No seller redemption transfer; affiliate 180 on the original purchase |
|
|
40
|
+
| Verified renewal observation | New native period retained | New native period retained; controlled-clock test proves local reset | Original paid-grant terms and consumption retained |
|
|
41
|
+
|
|
42
|
+
Each native row has both an issuer-only customer fixture and an eligible seller
|
|
43
|
+
fixture. The values above describe those specific USD sandbox cases, not universal
|
|
44
|
+
Stripe fees or rates. Settlement retries retained the original transfer IDs.
|
|
45
|
+
|
|
46
|
+
The original payment/invoice/settlement proof and UI recording are retained in
|
|
47
|
+
[the example evidence](https://github.com/FantasticDevHQ/better-stripe/tree/main/docs/evidence/usage-example). A subsequent native
|
|
48
|
+
aggregate refresh and complete retained ledger histories for all six fixtures are
|
|
49
|
+
in [the verification evidence](https://github.com/FantasticDevHQ/better-stripe/tree/main/docs/evidence/usage-verification). Financial
|
|
50
|
+
proof records when those invoices and purchases were verified; the refresh does
|
|
51
|
+
not claim a new cash observation or perform another payment or transfer.
|
|
52
|
+
|
|
53
|
+
## Failure and boundary matrix
|
|
54
|
+
|
|
55
|
+
These tests exercise the real component and real Stripe SDK transports with
|
|
56
|
+
controlled responses. Their fixtures are deterministic, not native charge or
|
|
57
|
+
network-failure recordings.
|
|
58
|
+
|
|
59
|
+
| Invariant | Executable coverage |
|
|
60
|
+
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
61
|
+
| Concurrent duplicates, changed amount/version/time, exact source identity, tenant/mode/realm isolation | `src/component/usage/ledger.test.ts`, `src/client/usage/boundaries.test.ts`, `src/component/usage/historyIsolation.test.ts` |
|
|
62
|
+
| Host authentication boundary before reusable acceptance, guessed IDs and cross-tenant cursors | `src/client/usage/boundaries.test.ts`, `src/component/usage/historyIsolation.test.ts`, `src/component/usageCredits/accounting.test.ts`, `example/convex/meteredUsage/state.test.ts` |
|
|
63
|
+
| Exact quantities beyond safe JS integers, unsupported API/definition versions, retained payload/history quotas | `src/client/usage/contracts.test.ts`, `src/client/usage/deliveryProvider.test.ts`, `src/component/usage/ledger.test.ts`, `src/component/usage/allowanceBounds.test.ts`, `src/component/usageCredits/quotas.test.ts` |
|
|
64
|
+
| Partial batches, rate limits, restarts, lost responses and provider success followed by receipt failure | `src/component/usageDelivery/workflow.test.ts`, `src/client/usage/catalog.test.ts`, `src/client/usage/correctionRecovery.test.ts`, `src/client/usage/creditProvider.test.ts` |
|
|
65
|
+
| Unknown responses beyond the retry window cannot send blindly; native clock/time-window guards | `src/component/usageDelivery/workflow.test.ts`, `src/client/usage/deliveryProvider.test.ts` |
|
|
66
|
+
| Complete summaries, lag, stale observations, scope mismatch and incomplete histories cannot become a successful zero | `src/client/usage/reconciliation.test.ts`, `src/client/usage/providerObservation.test.ts`, `src/component/usageObservations/queries.test.ts`, `src/react/workflows/Usage.test.tsx` |
|
|
67
|
+
| Included-unit reservation, concurrency, hard/soft caps, price changes, half-open periods and new-period reset | `src/component/usage/allowance.test.ts`, `src/client/usage/allowanceTerms.test.ts` |
|
|
68
|
+
| Prepaid payment gating, concurrent last-unit spending, duplicate backing, delayed grants and exhausted balance | `src/component/usageCredits/accounting.test.ts`, `src/client/usage/creditProvider.test.ts`, `scripts/usage-models-packed.test.mjs` |
|
|
69
|
+
| Original grant application, native invoice credits, reservation freshness and bounded complete backing proof | `src/client/usage/creditInvoice.test.ts`, `src/client/usage/creditObservation.test.ts`, `src/client/usage/creditProofBounds.test.ts`, `src/component/usageCredits/freshness.test.ts` |
|
|
70
|
+
| Corrections before/after billing cutoff, native pending cancellation, late credit notes and no invented refund | `src/client/usage/correctionClient.test.ts`, `src/client/usage/correctionRecovery.test.ts`, `src/client/usage/correctionInvoice.test.ts`, `src/component/usageCorrections/corrections.test.ts` |
|
|
71
|
+
| Paid original invoice, actual processing fee, one-time/forever commission and no duplicate transfers after receipt failure | `src/client/usage/invoiceSale.test.ts`, `src/client/usage/settlement.test.ts` |
|
|
72
|
+
| Prepaid refunds, disputes, won reinstatement, consumed backing, affiliate recovery and no second sale on redemption | `src/client/usage/creditSettlementRecovery.test.ts`, `src/component/usageCredits/accounting.test.ts`, `src/client/usage/creditRevenue.test.ts` |
|
|
73
|
+
| Saved success cannot bypass later cash uncertainty or unresolved settlement during cleanup | `example/convex/meteredUsage/revenue.test.ts`, `example/convex/meteredUsage/cleanupRefresh.test.ts` |
|
|
74
|
+
|
|
75
|
+
## Comparison and hold rules
|
|
76
|
+
|
|
77
|
+
Compare explicit original scope, meter, price/version, subscription item and
|
|
78
|
+
half-open billing period. Native aggregation can lag. A temporary match is an
|
|
79
|
+
observation, not invoice finality. Missing, stale, truncated or unavailable evidence
|
|
80
|
+
stays unavailable or held. The retained native proof uses zero tolerance in scaled
|
|
81
|
+
units after aggregation has settled. Exact decimal rates and scaled integer units
|
|
82
|
+
avoid rounding discrepancies; estimates remain labelled estimates. Only a complete
|
|
83
|
+
finalized original invoice determines the rated amount. A paid zero-dollar prepaid
|
|
84
|
+
invoice cannot create cash revenue.
|
|
85
|
+
|
|
86
|
+
The evidence auditor checks all six native aggregates against complete local
|
|
87
|
+
histories, original invoice lines, exact quantities and original cash/transfer
|
|
88
|
+
identities. It also checks conservation of original gross across actual processing
|
|
89
|
+
fees, retained platform proceeds and executed transfers. Corruption tests reject
|
|
90
|
+
unknown/stale/partial data, changed quantities/prices, foreign cash and duplicate
|
|
91
|
+
transfer identities. It audits retained proof; it cannot replace a fresh provider
|
|
92
|
+
reconciliation before a financial operation.
|
|
93
|
+
|
|
94
|
+
## Tested limits
|
|
95
|
+
|
|
96
|
+
The sandbox issuer and eligible seller/affiliate recipients support the recorded
|
|
97
|
+
Accounts v2 and Connect flows. A seller without transfer capability retained paid
|
|
98
|
+
cash evidence but remained held for settlement; cleanup refused to erase it.
|
|
99
|
+
Issuer-only customer billing was also exercised on the same platform issuer.
|
|
100
|
+
This does not establish a separate non-Connect customer-only preview account's
|
|
101
|
+
eligibility. Billing under connected-account headers is not supported by the
|
|
102
|
+
current usage adapters. Those cases require their own verified API/account
|
|
103
|
+
configuration. Eligibility remains tied to the original account configuration,
|
|
104
|
+
currency, API access and native capabilities.
|
|
105
|
+
|
|
106
|
+
Native test clocks advanced billing and exposed the next subscription period.
|
|
107
|
+
That future period is outside the real server's current allowance acceptance
|
|
108
|
+
window. Its allowance is explicitly `not_active_yet`, not zero or accepting. A
|
|
109
|
+
controlled-clock component test proves monthly counter reset while retaining the
|
|
110
|
+
old period. The sandbox does not establish a future-period production send before
|
|
111
|
+
its real acceptance window, or a wall-clock month of production operation.
|
|
112
|
+
|
|
113
|
+
No native live dispute was created. Refund/dispute recovery, transport ambiguity,
|
|
114
|
+
worker/DB failures, retained quota limits and API-version refusals use deterministic
|
|
115
|
+
SDK/component tests. No load or sustained throughput certification is claimed.
|
|
116
|
+
These checks authorize neither live billing nor automatic production migration,
|
|
117
|
+
publication or replay of unknown historical provider writes.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fantastic.dev/better-stripe",
|
|
3
|
-
"version": "0.64.
|
|
3
|
+
"version": "0.64.1",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -115,7 +115,8 @@
|
|
|
115
115
|
"docs/evidence/native-metering",
|
|
116
116
|
"docs/usage-configuration.md",
|
|
117
117
|
"docs/usage-example.md",
|
|
118
|
-
"docs/payout-revision-migration.md"
|
|
118
|
+
"docs/payout-revision-migration.md",
|
|
119
|
+
"docs/usage-verification.md"
|
|
119
120
|
],
|
|
120
121
|
"scripts": {
|
|
121
122
|
"build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
|