@fantastic.dev/better-stripe 0.64.0 → 0.65.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.
- package/CHANGELOG.md +16 -0
- package/README.md +3 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +32 -32
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
- package/dist/client/index.d.ts +1 -0
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/recoveryWorkflow/provider.d.ts +3 -0
- package/dist/client/recoveryWorkflow/provider.d.ts.map +1 -1
- package/dist/client/recoveryWorkflow/provider.js +1 -1
- package/dist/client/recoveryWorkflow/provider.js.map +1 -1
- package/dist/client/settlement/authorization.d.ts +19 -0
- package/dist/client/settlement/authorization.d.ts.map +1 -0
- package/dist/client/settlement/authorization.fixture.d.ts +112 -0
- package/dist/client/settlement/authorization.fixture.d.ts.map +1 -0
- package/dist/client/settlement/authorization.fixture.js +178 -0
- package/dist/client/settlement/authorization.fixture.js.map +1 -0
- package/dist/client/settlement/authorization.js +28 -0
- package/dist/client/settlement/authorization.js.map +1 -0
- package/dist/client/settlement/execution.d.ts +2 -1
- package/dist/client/settlement/execution.d.ts.map +1 -1
- package/dist/client/settlement/execution.js +8 -4
- package/dist/client/settlement/execution.js.map +1 -1
- package/dist/client/settlement/settleSale.d.ts +3 -0
- package/dist/client/settlement/settleSale.d.ts.map +1 -1
- package/dist/client/settlement/settleSale.js +5 -2
- package/dist/client/settlement/settleSale.js.map +1 -1
- package/dist/client/usage/observationClient.d.ts +2 -2
- package/dist/client/usage/observationClient.d.ts.map +1 -1
- package/dist/component/balanceFunding/mutations.d.ts +27 -27
- package/dist/component/balanceFunding/queries.d.ts +1 -1
- package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
- package/dist/component/earnings/triggers.d.ts +16 -16
- package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
- package/dist/component/usage/allowance.fixtures.d.ts +16 -16
- package/docs/README.md +2 -0
- package/docs/settlement.md +56 -0
- package/docs/usage-verification.md +117 -0
- package/package.json +3 -2
- package/src/client/index.ts +4 -0
- package/src/client/recoveryWorkflow/provider.test.ts +149 -7
- package/src/client/recoveryWorkflow/provider.ts +10 -1
- package/src/client/settlement/authorization.fixture.ts +199 -0
- package/src/client/settlement/authorization.test.ts +160 -0
- package/src/client/settlement/authorization.ts +53 -0
- package/src/client/settlement/execution.ts +11 -4
- package/src/client/settlement/settleSale.ts +16 -2
|
@@ -372,14 +372,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
372
372
|
preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
|
|
373
373
|
requestKey: string;
|
|
374
374
|
result?: {
|
|
375
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
376
|
-
retryable: false;
|
|
377
|
-
status: "conflict";
|
|
378
|
-
} | {
|
|
379
|
-
reason: "policy_invalid";
|
|
380
|
-
retryable: false;
|
|
381
|
-
status: "rejected";
|
|
382
|
-
} | {
|
|
383
375
|
operation: {
|
|
384
376
|
accountId: string;
|
|
385
377
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -390,6 +382,14 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
390
382
|
} | {
|
|
391
383
|
enabled: boolean;
|
|
392
384
|
status: "unchanged";
|
|
385
|
+
} | {
|
|
386
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
387
|
+
retryable: false;
|
|
388
|
+
status: "conflict";
|
|
389
|
+
} | {
|
|
390
|
+
reason: "policy_invalid";
|
|
391
|
+
retryable: false;
|
|
392
|
+
status: "rejected";
|
|
393
393
|
} | {
|
|
394
394
|
reason: "provider_pending";
|
|
395
395
|
retryable: true;
|
|
@@ -3216,14 +3216,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
3216
3216
|
preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
|
|
3217
3217
|
requestKey: string;
|
|
3218
3218
|
result?: {
|
|
3219
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
3220
|
-
retryable: false;
|
|
3221
|
-
status: "conflict";
|
|
3222
|
-
} | {
|
|
3223
|
-
reason: "policy_invalid";
|
|
3224
|
-
retryable: false;
|
|
3225
|
-
status: "rejected";
|
|
3226
|
-
} | {
|
|
3227
3219
|
operation: {
|
|
3228
3220
|
accountId: string;
|
|
3229
3221
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -3234,6 +3226,14 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
3234
3226
|
} | {
|
|
3235
3227
|
enabled: boolean;
|
|
3236
3228
|
status: "unchanged";
|
|
3229
|
+
} | {
|
|
3230
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
3231
|
+
retryable: false;
|
|
3232
|
+
status: "conflict";
|
|
3233
|
+
} | {
|
|
3234
|
+
reason: "policy_invalid";
|
|
3235
|
+
retryable: false;
|
|
3236
|
+
status: "rejected";
|
|
3237
3237
|
} | {
|
|
3238
3238
|
reason: "provider_pending";
|
|
3239
3239
|
retryable: true;
|
|
@@ -14,7 +14,7 @@ export declare function checkRollback(ctx: MutationCtx, op: Doc<"processingCostR
|
|
|
14
14
|
readonly bindFunding?: undefined;
|
|
15
15
|
} | {
|
|
16
16
|
reason?: undefined;
|
|
17
|
-
|
|
17
|
+
retryable?: undefined;
|
|
18
18
|
readonly status: "ready";
|
|
19
19
|
readonly bindFunding: boolean;
|
|
20
20
|
}>;
|
|
@@ -2137,14 +2137,6 @@ export declare function setupAllowance(): Promise<{
|
|
|
2137
2137
|
preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
|
|
2138
2138
|
requestKey: string;
|
|
2139
2139
|
result?: {
|
|
2140
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2141
|
-
retryable: false;
|
|
2142
|
-
status: "conflict";
|
|
2143
|
-
} | {
|
|
2144
|
-
reason: "policy_invalid";
|
|
2145
|
-
retryable: false;
|
|
2146
|
-
status: "rejected";
|
|
2147
|
-
} | {
|
|
2148
2140
|
operation: {
|
|
2149
2141
|
accountId: string;
|
|
2150
2142
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -2155,6 +2147,14 @@ export declare function setupAllowance(): Promise<{
|
|
|
2155
2147
|
} | {
|
|
2156
2148
|
enabled: boolean;
|
|
2157
2149
|
status: "unchanged";
|
|
2150
|
+
} | {
|
|
2151
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2152
|
+
retryable: false;
|
|
2153
|
+
status: "conflict";
|
|
2154
|
+
} | {
|
|
2155
|
+
reason: "policy_invalid";
|
|
2156
|
+
retryable: false;
|
|
2157
|
+
status: "rejected";
|
|
2158
2158
|
} | {
|
|
2159
2159
|
reason: "provider_pending";
|
|
2160
2160
|
retryable: true;
|
|
@@ -2165,14 +2165,6 @@ export declare function setupAllowance(): Promise<{
|
|
|
2165
2165
|
payload: import("convex/values").VString<string, "required">;
|
|
2166
2166
|
preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
|
|
2167
2167
|
result: import("convex/values").VUnion<{
|
|
2168
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2169
|
-
retryable: false;
|
|
2170
|
-
status: "conflict";
|
|
2171
|
-
} | {
|
|
2172
|
-
reason: "policy_invalid";
|
|
2173
|
-
retryable: false;
|
|
2174
|
-
status: "rejected";
|
|
2175
|
-
} | {
|
|
2176
2168
|
operation: {
|
|
2177
2169
|
accountId: string;
|
|
2178
2170
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -2183,6 +2175,14 @@ export declare function setupAllowance(): Promise<{
|
|
|
2183
2175
|
} | {
|
|
2184
2176
|
enabled: boolean;
|
|
2185
2177
|
status: "unchanged";
|
|
2178
|
+
} | {
|
|
2179
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
2180
|
+
retryable: false;
|
|
2181
|
+
status: "conflict";
|
|
2182
|
+
} | {
|
|
2183
|
+
reason: "policy_invalid";
|
|
2184
|
+
retryable: false;
|
|
2185
|
+
status: "rejected";
|
|
2186
2186
|
} | {
|
|
2187
2187
|
reason: "provider_pending";
|
|
2188
2188
|
retryable: true;
|
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.
|
package/docs/settlement.md
CHANGED
|
@@ -120,6 +120,62 @@ closed. Existing refund/dispute reversal APIs recover these original legs too.
|
|
|
120
120
|
Stripe API idempotency is an additional safeguard, not the only recovery record.
|
|
121
121
|
Do not delete financial component records while payments can be retried or reversed.
|
|
122
122
|
|
|
123
|
+
### Reauthorize before financial dispatch
|
|
124
|
+
|
|
125
|
+
`settleSale` accepts an optional **server-only** `authorize` callback. Existing
|
|
126
|
+
callers without it retain their behavior. Authenticate the actor and derive the
|
|
127
|
+
original purchase, community, charge and recipient scope on your server first;
|
|
128
|
+
then use the callback to re-read current authorization rather than trusting
|
|
129
|
+
browser account IDs or provider metadata:
|
|
130
|
+
|
|
131
|
+
```ts
|
|
132
|
+
await stripe.settleSale(ctx, {
|
|
133
|
+
...originalSettlement,
|
|
134
|
+
authorize: async (context) => {
|
|
135
|
+
// Application-owned check: current actor, original purchase/source and recipients.
|
|
136
|
+
await authorizeOriginalSale(context);
|
|
137
|
+
},
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The discriminated `SettlementAuthorizationContext` has two phases:
|
|
142
|
+
|
|
143
|
+
- `reserve`: after provider sale reads and before allocation admission. On replay,
|
|
144
|
+
the snapshot contains the prior immutable allocation when one exists.
|
|
145
|
+
- `transfer`: after provider transfer reconciliation and immediately before each
|
|
146
|
+
**new** transfer POST. It contains the actual saved source/economics and the
|
|
147
|
+
effective leg, including a reduced affiliate release after package-owned debt
|
|
148
|
+
offsets. A competing reservation cannot substitute an unexamined recipient.
|
|
149
|
+
|
|
150
|
+
Snapshots are detached from engine inputs; callback mutation cannot change the
|
|
151
|
+
claim or transfer. Throwing from a direct `settleSale` callback propagates the
|
|
152
|
+
host error and prevents that write; the SDK does not retry it. The callback does
|
|
153
|
+
not return replacement economics or establish original cash provenance.
|
|
154
|
+
|
|
155
|
+
The last check and Stripe are not a distributed transaction. A later denial can
|
|
156
|
+
leave an admitted immutable allocation or earlier successful legs in place;
|
|
157
|
+
partial success is not undone. Retrying reuses the original claim and still
|
|
158
|
+
checks each missing new leg. Already-recovered provider success can be persisted
|
|
159
|
+
without another `transfer` callback or another POST: it is reconciliation of
|
|
160
|
+
money already moved, not new financial dispatch. `onSettled` remains a
|
|
161
|
+
post-execution, replayable completion callback, not an authorization check.
|
|
162
|
+
|
|
163
|
+
The active Vite adapter uses fresh original-sale and current seller-mapping
|
|
164
|
+
queries; demo metadata is not a production authorization policy. For its actual
|
|
165
|
+
sealed recovery-group path, pass the same server-only callback in the runtime
|
|
166
|
+
options to `costRecovery.executeGroupProvider`. This path already has persisted
|
|
167
|
+
group/allocation admission and dispatch: it invokes only the final `transfer`
|
|
168
|
+
phase for each new settlement transfer, not an earlier `reserve` guarantee.
|
|
169
|
+
The existing snapshot/definition/phase checks still apply. Reconciliation-only
|
|
170
|
+
work never creates a missing transfer or invokes a new-money callback.
|
|
171
|
+
|
|
172
|
+
A recovery callback rejection uses the existing conservative `unknown` hold
|
|
173
|
+
receipt and does not automatically retry or complete the group. This is the
|
|
174
|
+
workflow's disposition of a denied dispatch, **not** an observed unknown Stripe
|
|
175
|
+
cash result or provider failure. Original group/allocation state and earlier
|
|
176
|
+
success remain retained. No callback, credential or authority flag is persisted
|
|
177
|
+
in workflow arguments; supply it inside the registered internal host action.
|
|
178
|
+
|
|
123
179
|
The Vite example exposes a [fee-first allocation preview](http://localhost:5173/demo/allocation)
|
|
124
180
|
from Admin → Testing Utilities. Its illustrative inputs use the public helper
|
|
125
181
|
and the package React `SplitBreakdown`; they do not alter store settings.
|
|
@@ -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.
|
|
3
|
+
"version": "0.65.0",
|
|
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",
|
package/src/client/index.ts
CHANGED
|
@@ -137,6 +137,10 @@ export type {
|
|
|
137
137
|
VerifiedPaymentSourceOptions,
|
|
138
138
|
} from "./paymentSource/contracts.js";
|
|
139
139
|
export type { SettleSaleOptions } from "./settlement/settleSale.js";
|
|
140
|
+
export type {
|
|
141
|
+
SettlementAuthorization,
|
|
142
|
+
SettlementAuthorizationContext,
|
|
143
|
+
} from "./settlement/authorization.js";
|
|
140
144
|
export type { SettlementResult } from "./settlement/execution.js";
|
|
141
145
|
export type {
|
|
142
146
|
CommissionTerm,
|
|
@@ -19,6 +19,7 @@ async function setup(
|
|
|
19
19
|
kind: "invoice" | "settlement" = "invoice",
|
|
20
20
|
dispatch = true,
|
|
21
21
|
releaseUncollectible = false,
|
|
22
|
+
twoLegs = false,
|
|
22
23
|
) {
|
|
23
24
|
const t = initConvexTest();
|
|
24
25
|
t.registerComponent("betterStripe", schema, modules);
|
|
@@ -58,13 +59,26 @@ async function setup(
|
|
|
58
59
|
processingFee: 30,
|
|
59
60
|
platformNet: 40,
|
|
60
61
|
adjustmentAmount: 30,
|
|
61
|
-
transfers:
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
62
|
+
transfers: twoLegs
|
|
63
|
+
? [
|
|
64
|
+
{
|
|
65
|
+
destinationAccountId: "acct_seller",
|
|
66
|
+
role: "store" as const,
|
|
67
|
+
amount: 800,
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
destinationAccountId: "acct_other",
|
|
71
|
+
role: "other" as const,
|
|
72
|
+
amount: 100,
|
|
73
|
+
},
|
|
74
|
+
]
|
|
75
|
+
: [
|
|
76
|
+
{
|
|
77
|
+
destinationAccountId: "acct_seller",
|
|
78
|
+
role: "store" as const,
|
|
79
|
+
amount: 900,
|
|
80
|
+
},
|
|
81
|
+
],
|
|
68
82
|
};
|
|
69
83
|
await client.prepareGroup(ctx, {
|
|
70
84
|
...scope,
|
|
@@ -422,3 +436,131 @@ it.each([false, true])(
|
|
|
422
436
|
);
|
|
423
437
|
},
|
|
424
438
|
);
|
|
439
|
+
|
|
440
|
+
it("holds partial authorized recovery success and never creates the denied missing leg during reconciliation", async () => {
|
|
441
|
+
const f = await setup("settlement", true, false, true);
|
|
442
|
+
let current = true;
|
|
443
|
+
const transfers: Record<string, unknown>[] = [];
|
|
444
|
+
const httpClient = Stripe.createFetchHttpClient(async (url, init) => {
|
|
445
|
+
const path = new URL(String(url)).pathname;
|
|
446
|
+
let body: unknown;
|
|
447
|
+
if (path === "/v1/transfers" && init?.method === "POST") {
|
|
448
|
+
const params = new URLSearchParams(String(init.body));
|
|
449
|
+
body = {
|
|
450
|
+
id: "tr_partial",
|
|
451
|
+
destination: params.get("destination"),
|
|
452
|
+
amount: Number(params.get("amount")),
|
|
453
|
+
currency: "usd",
|
|
454
|
+
source_transaction: "ch_source",
|
|
455
|
+
amount_reversed: 0,
|
|
456
|
+
metadata: {
|
|
457
|
+
bsRole: params.get("metadata[bsRole]"),
|
|
458
|
+
bsSourceCharge: "ch_source",
|
|
459
|
+
},
|
|
460
|
+
};
|
|
461
|
+
transfers.push(body as Record<string, unknown>);
|
|
462
|
+
current = false;
|
|
463
|
+
} else if (path === "/v1/transfers" && init?.method === "GET") {
|
|
464
|
+
body = { object: "list", data: transfers, has_more: false };
|
|
465
|
+
} else if (path === "/v1/charges/ch_source" && init?.method === "GET") {
|
|
466
|
+
body = { id: "ch_source", created: 1 };
|
|
467
|
+
} else throw new Error("Unlisted synthetic provider request");
|
|
468
|
+
return new Response(JSON.stringify(body), {
|
|
469
|
+
status: 200,
|
|
470
|
+
headers: { "content-type": "application/json" },
|
|
471
|
+
});
|
|
472
|
+
});
|
|
473
|
+
const authorize = async () => {
|
|
474
|
+
if (!current) throw new Error("Host authorization denied");
|
|
475
|
+
};
|
|
476
|
+
const result = await f.client.executeGroupProvider(f.ctx, f.request, {
|
|
477
|
+
stripeSecretKey: "sk_test_runtime_only",
|
|
478
|
+
httpClient,
|
|
479
|
+
authorize,
|
|
480
|
+
});
|
|
481
|
+
expect(result).toMatchObject({ status: "unknown" });
|
|
482
|
+
if (result.status !== "unknown") throw new Error("Expected a held dispatch");
|
|
483
|
+
expect(transfers).toHaveLength(1);
|
|
484
|
+
expect(
|
|
485
|
+
await f.t.query(nested.betterStripe.connect.queries.listTransfersByCharge, {
|
|
486
|
+
sourceChargeId: "ch_source",
|
|
487
|
+
}),
|
|
488
|
+
).toMatchObject([{ amount: 800 }]);
|
|
489
|
+
await f.t.mutation(nested.betterStripe.recoveryWorkflow.steps.saveReceipt, {
|
|
490
|
+
...scope,
|
|
491
|
+
operationId: f.request.operationId,
|
|
492
|
+
version: 1,
|
|
493
|
+
result: { status: result.status, reason: result.reason },
|
|
494
|
+
});
|
|
495
|
+
await f.dispatchReconcile();
|
|
496
|
+
expect(
|
|
497
|
+
await f.client.executeGroupProvider(
|
|
498
|
+
f.ctx,
|
|
499
|
+
{ ...f.request, phase: "reconcile" },
|
|
500
|
+
{ stripeSecretKey: "sk_test_runtime_only", httpClient, authorize },
|
|
501
|
+
),
|
|
502
|
+
).toMatchObject({ status: "unknown" });
|
|
503
|
+
expect(transfers).toHaveLength(1);
|
|
504
|
+
});
|
|
505
|
+
|
|
506
|
+
it.each([false, true])(
|
|
507
|
+
"reauthorizes an actual frozen recovery transfer after reconciliation (revoked=%s)",
|
|
508
|
+
async (revoked) => {
|
|
509
|
+
const f = await setup("settlement");
|
|
510
|
+
let current = true;
|
|
511
|
+
let creates = 0;
|
|
512
|
+
const checked: { charge: string; destination: string; amount: number }[] =
|
|
513
|
+
[];
|
|
514
|
+
const httpClient = Stripe.createFetchHttpClient(async (url, init) => {
|
|
515
|
+
const path = new URL(String(url)).pathname;
|
|
516
|
+
let body: unknown;
|
|
517
|
+
if (path === "/v1/charges/ch_source" && init?.method === "GET") {
|
|
518
|
+
body = { id: "ch_source", created: 1 };
|
|
519
|
+
} else if (path === "/v1/transfers" && init?.method === "GET") {
|
|
520
|
+
if (revoked) current = false;
|
|
521
|
+
body = { object: "list", data: [], has_more: false };
|
|
522
|
+
} else if (path === "/v1/transfers" && init?.method === "POST") {
|
|
523
|
+
creates++;
|
|
524
|
+
body = {
|
|
525
|
+
id: "tr_authorized",
|
|
526
|
+
destination: "acct_seller",
|
|
527
|
+
amount: 900,
|
|
528
|
+
currency: "usd",
|
|
529
|
+
source_transaction: "ch_source",
|
|
530
|
+
metadata: { bsRole: "store", bsSourceCharge: "ch_source" },
|
|
531
|
+
};
|
|
532
|
+
} else throw new Error("Unlisted synthetic provider request");
|
|
533
|
+
return new Response(JSON.stringify(body), {
|
|
534
|
+
status: 200,
|
|
535
|
+
headers: { "content-type": "application/json" },
|
|
536
|
+
});
|
|
537
|
+
});
|
|
538
|
+
const options = {
|
|
539
|
+
stripeSecretKey: "sk_test_runtime_only",
|
|
540
|
+
httpClient,
|
|
541
|
+
authorize: async (
|
|
542
|
+
context: import("../settlement/authorization.js").SettlementAuthorizationContext,
|
|
543
|
+
) => {
|
|
544
|
+
if (context.phase !== "transfer")
|
|
545
|
+
throw new Error("Recovery group was already admitted");
|
|
546
|
+
checked.push({
|
|
547
|
+
charge: context.settlement.sourceChargeId,
|
|
548
|
+
destination: context.transfer.destinationAccountId,
|
|
549
|
+
amount: context.transfer.amount,
|
|
550
|
+
});
|
|
551
|
+
if (!current) throw new Error("Current host authority denied");
|
|
552
|
+
},
|
|
553
|
+
};
|
|
554
|
+
expect(
|
|
555
|
+
await f.client.executeGroupProvider(f.ctx, f.request, options),
|
|
556
|
+
).toMatchObject(
|
|
557
|
+
revoked
|
|
558
|
+
? { status: "unknown", reason: "provider_outcome_unknown" }
|
|
559
|
+
: { status: "ready", outcome: "collect" },
|
|
560
|
+
);
|
|
561
|
+
expect(creates).toBe(revoked ? 0 : 1);
|
|
562
|
+
expect(checked).toEqual([
|
|
563
|
+
{ charge: "ch_source", destination: "acct_seller", amount: 900 },
|
|
564
|
+
]);
|
|
565
|
+
},
|
|
566
|
+
);
|
|
@@ -5,6 +5,7 @@ import { componentRef } from "../webhooks/helpers.js";
|
|
|
5
5
|
import { attachRecoveryInvoice } from "../costRecovery-invoices.js";
|
|
6
6
|
import type { RecoveryGroup } from "../costRecovery.js";
|
|
7
7
|
import { executeResolvedTransfers } from "../settlement/execution.js";
|
|
8
|
+
import type { SettlementAuthorization } from "../settlement/authorization.js";
|
|
8
9
|
import { reconcileRecoverySettlement } from "./settlement.js";
|
|
9
10
|
import { operationRef } from "./contracts.js";
|
|
10
11
|
import type {
|
|
@@ -18,6 +19,8 @@ export type RecoveryProviderOptions = {
|
|
|
18
19
|
httpClient?: NonNullable<
|
|
19
20
|
ConstructorParameters<typeof Stripe>[1]
|
|
20
21
|
>["httpClient"];
|
|
22
|
+
/** Runtime-only host check before each new settlement transfer; group admission already occurred. */
|
|
23
|
+
authorize?: SettlementAuthorization;
|
|
21
24
|
};
|
|
22
25
|
export async function executeRecoveryProvider(
|
|
23
26
|
component: Component,
|
|
@@ -69,7 +72,13 @@ export async function executeRecoveryProvider(
|
|
|
69
72
|
reason: "provider_outcome_unknown",
|
|
70
73
|
};
|
|
71
74
|
if (request.phase === "execute")
|
|
72
|
-
await executeResolvedTransfers(
|
|
75
|
+
await executeResolvedTransfers(
|
|
76
|
+
stripe,
|
|
77
|
+
component,
|
|
78
|
+
ctx,
|
|
79
|
+
op.allocation,
|
|
80
|
+
options.authorize,
|
|
81
|
+
);
|
|
73
82
|
else if (
|
|
74
83
|
!(await reconcileRecoverySettlement(
|
|
75
84
|
stripe,
|