@fantastic.dev/better-stripe 0.58.0 → 0.60.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 +12 -0
- package/README.md +3 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +888 -62
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +428 -15
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +856 -30
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +444 -31
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/index.d.ts +4 -0
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/paymentSource/resolver.d.ts +12 -1
- package/dist/client/paymentSource/resolver.d.ts.map +1 -1
- package/dist/client/paymentSource/resolver.fixtures.d.ts +220 -0
- package/dist/client/paymentSource/resolver.fixtures.d.ts.map +1 -0
- package/dist/client/paymentSource/resolver.fixtures.js +189 -0
- package/dist/client/paymentSource/resolver.fixtures.js.map +1 -0
- package/dist/client/paymentSource/resolver.js +28 -3
- package/dist/client/paymentSource/resolver.js.map +1 -1
- package/dist/client/settlement/execution.d.ts +25 -0
- package/dist/client/settlement/execution.d.ts.map +1 -1
- package/dist/client/settlement/execution.js +2 -0
- package/dist/client/settlement/execution.js.map +1 -1
- package/dist/client/usage/allowanceClient.d.ts +1 -1
- package/dist/client/usage/catalogPrices.d.ts +1 -1
- package/dist/client/usage/catalogPrices.d.ts.map +1 -1
- package/dist/client/usage/catalogPrices.js +4 -4
- package/dist/client/usage/catalogPrices.js.map +1 -1
- package/dist/client/usage/client.d.ts +2 -2
- package/dist/client/usage/client.d.ts.map +1 -1
- package/dist/client/usage/client.js +2 -2
- package/dist/client/usage/client.js.map +1 -1
- package/dist/client/usage/correctionClient.d.ts +33 -0
- package/dist/client/usage/correctionClient.d.ts.map +1 -0
- package/dist/client/usage/correctionClient.js +27 -0
- package/dist/client/usage/correctionClient.js.map +1 -0
- package/dist/client/usage/correctionEligibility.d.ts +4 -0
- package/dist/client/usage/correctionEligibility.d.ts.map +1 -0
- package/dist/client/usage/correctionEligibility.js +7 -0
- package/dist/client/usage/correctionEligibility.js.map +1 -0
- package/dist/client/usage/correctionInvoice.d.ts +9 -0
- package/dist/client/usage/correctionInvoice.d.ts.map +1 -0
- package/dist/client/usage/correctionInvoice.js +218 -0
- package/dist/client/usage/correctionInvoice.js.map +1 -0
- package/dist/client/usage/correctionInvoiceProof.d.ts +29 -0
- package/dist/client/usage/correctionInvoiceProof.d.ts.map +1 -0
- package/dist/client/usage/correctionInvoiceProof.js +41 -0
- package/dist/client/usage/correctionInvoiceProof.js.map +1 -0
- package/dist/client/usage/correctionProofs.d.ts +36 -0
- package/dist/client/usage/correctionProofs.d.ts.map +1 -0
- package/dist/client/usage/correctionProofs.js +41 -0
- package/dist/client/usage/correctionProofs.js.map +1 -0
- package/dist/client/usage/correctionProvider.d.ts +6 -0
- package/dist/client/usage/correctionProvider.d.ts.map +1 -0
- package/dist/client/usage/correctionProvider.js +243 -0
- package/dist/client/usage/correctionProvider.js.map +1 -0
- package/dist/client/usage/correctionRead.d.ts +27 -0
- package/dist/client/usage/correctionRead.d.ts.map +1 -0
- package/dist/client/usage/correctionRead.js +36 -0
- package/dist/client/usage/correctionRead.js.map +1 -0
- package/dist/client/usage/correctionTerms.d.ts +64 -0
- package/dist/client/usage/correctionTerms.d.ts.map +1 -0
- package/dist/client/usage/correctionTerms.js +65 -0
- package/dist/client/usage/correctionTerms.js.map +1 -0
- package/dist/client/usage/correctionTransport.fixtures.d.ts +37 -0
- package/dist/client/usage/correctionTransport.fixtures.d.ts.map +1 -0
- package/dist/client/usage/correctionTransport.fixtures.js +322 -0
- package/dist/client/usage/correctionTransport.fixtures.js.map +1 -0
- package/dist/client/usage/creditClient.d.ts +1 -1
- package/dist/client/usage/creditRevenue.d.ts +22 -0
- package/dist/client/usage/creditRevenue.d.ts.map +1 -0
- package/dist/client/usage/creditRevenue.js +118 -0
- package/dist/client/usage/creditRevenue.js.map +1 -0
- package/dist/client/usage/creditSettlement.d.ts +29 -0
- package/dist/client/usage/creditSettlement.d.ts.map +1 -0
- package/dist/client/usage/creditSettlement.fixtures.d.ts +215 -0
- package/dist/client/usage/creditSettlement.fixtures.d.ts.map +1 -0
- package/dist/client/usage/creditSettlement.fixtures.js +59 -0
- package/dist/client/usage/creditSettlement.fixtures.js.map +1 -0
- package/dist/client/usage/creditSettlement.js +70 -0
- package/dist/client/usage/creditSettlement.js.map +1 -0
- package/dist/client/usage/creditTransport.fixtures.d.ts +7 -1
- package/dist/client/usage/creditTransport.fixtures.d.ts.map +1 -1
- package/dist/client/usage/creditTransport.fixtures.js +25 -4
- package/dist/client/usage/creditTransport.fixtures.js.map +1 -1
- package/dist/client/usage/index.d.ts +6 -0
- package/dist/client/usage/index.d.ts.map +1 -1
- package/dist/client/usage/invoiceSale.d.ts +22 -0
- package/dist/client/usage/invoiceSale.d.ts.map +1 -0
- package/dist/client/usage/invoiceSale.fixtures.d.ts +285 -0
- package/dist/client/usage/invoiceSale.fixtures.d.ts.map +1 -0
- package/dist/client/usage/invoiceSale.fixtures.js +104 -0
- package/dist/client/usage/invoiceSale.fixtures.js.map +1 -0
- package/dist/client/usage/invoiceSale.js +117 -0
- package/dist/client/usage/invoiceSale.js.map +1 -0
- package/dist/client/usage/observationClient.d.ts +20 -0
- package/dist/client/usage/observationClient.d.ts.map +1 -1
- package/dist/client/usage/observationClient.js +20 -6
- package/dist/client/usage/observationClient.js.map +1 -1
- package/dist/client/usage/records.d.ts +1 -1
- package/dist/client/usage/records.d.ts.map +1 -1
- package/dist/client/usage/records.js.map +1 -1
- package/dist/client/usage/settlement.d.ts +32 -0
- package/dist/client/usage/settlement.d.ts.map +1 -0
- package/dist/client/usage/settlement.js +60 -0
- package/dist/client/usage/settlement.js.map +1 -0
- package/dist/client/usage/settlementClient.d.ts +51 -0
- package/dist/client/usage/settlementClient.d.ts.map +1 -0
- package/dist/client/usage/settlementClient.js +35 -0
- package/dist/client/usage/settlementClient.js.map +1 -0
- package/dist/client/usage/summary.d.ts +3 -0
- package/dist/client/usage/summary.d.ts.map +1 -1
- package/dist/client/usage/summary.js +9 -4
- package/dist/client/usage/summary.js.map +1 -1
- package/dist/client/usageExports.d.ts +2 -0
- package/dist/client/usageExports.d.ts.map +1 -1
- package/dist/component/_generated/api.d.ts +12 -0
- package/dist/component/_generated/api.d.ts.map +1 -1
- package/dist/component/_generated/api.js.map +1 -1
- package/dist/component/_generated/component.d.ts +380 -14
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/accountClosure/mutations.d.ts.map +1 -1
- package/dist/component/accountClosure/mutations.js +13 -0
- package/dist/component/accountClosure/mutations.js.map +1 -1
- package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
- package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
- package/dist/component/earnings/triggers.d.ts +368 -32
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -1
- package/dist/component/financialObservations/settlementHelpers.js +2 -0
- package/dist/component/financialObservations/settlementHelpers.js.map +1 -1
- package/dist/component/recoveryWorkflow/helpers.d.ts +25 -0
- package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
- package/dist/component/recoveryWorkflow/mutations.d.ts +25 -0
- package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
- package/dist/component/recoveryWorkflow/queries.d.ts +50 -0
- package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
- package/dist/component/recoveryWorkflow/schema.d.ts +566 -10
- package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
- package/dist/component/schema.d.ts +428 -15
- package/dist/component/schema.js +4 -0
- package/dist/component/schema.js.map +1 -1
- package/dist/component/settlement/mutations.d.ts +50 -0
- package/dist/component/settlement/mutations.d.ts.map +1 -1
- package/dist/component/settlement/mutations.js +8 -1
- package/dist/component/settlement/mutations.js.map +1 -1
- package/dist/component/settlement/queries.d.ts +25 -0
- package/dist/component/settlement/queries.d.ts.map +1 -1
- package/dist/component/settlement/schema.d.ts +128 -1
- package/dist/component/settlement/schema.d.ts.map +1 -1
- package/dist/component/settlement/schema.js +22 -0
- package/dist/component/settlement/schema.js.map +1 -1
- package/dist/component/usage/queries.d.ts +2 -2
- package/dist/component/usage/schema.d.ts +18 -13
- package/dist/component/usage/schema.d.ts.map +1 -1
- package/dist/component/usage/schema.js +2 -1
- package/dist/component/usage/schema.js.map +1 -1
- package/dist/component/usageAllowance/queries.d.ts +1 -1
- package/dist/component/usageAllowance/queries.d.ts.map +1 -1
- package/dist/component/usageAllowance/queries.js +10 -1
- package/dist/component/usageAllowance/queries.js.map +1 -1
- package/dist/component/usageAllowance/schema.d.ts +5 -5
- package/dist/component/usageAllowance/schema.d.ts.map +1 -1
- package/dist/component/usageAllowance/schema.js +1 -1
- package/dist/component/usageAllowance/schema.js.map +1 -1
- package/dist/component/usageCorrections/accounting.d.ts +5 -0
- package/dist/component/usageCorrections/accounting.d.ts.map +1 -0
- package/dist/component/usageCorrections/accounting.js +55 -0
- package/dist/component/usageCorrections/accounting.js.map +1 -0
- package/dist/component/usageCorrections/cancellation.d.ts +6 -0
- package/dist/component/usageCorrections/cancellation.d.ts.map +1 -0
- package/dist/component/usageCorrections/cancellation.js +29 -0
- package/dist/component/usageCorrections/cancellation.js.map +1 -0
- package/dist/component/usageCorrections/helpers.d.ts +60 -0
- package/dist/component/usageCorrections/helpers.d.ts.map +1 -0
- package/dist/component/usageCorrections/helpers.js +52 -0
- package/dist/component/usageCorrections/helpers.js.map +1 -0
- package/dist/component/usageCorrections/invoice.d.ts +38 -0
- package/dist/component/usageCorrections/invoice.d.ts.map +1 -0
- package/dist/component/usageCorrections/invoice.js +82 -0
- package/dist/component/usageCorrections/invoice.js.map +1 -0
- package/dist/component/usageCorrections/mutations.d.ts +121 -0
- package/dist/component/usageCorrections/mutations.d.ts.map +1 -0
- package/dist/component/usageCorrections/mutations.js +256 -0
- package/dist/component/usageCorrections/mutations.js.map +1 -0
- package/dist/component/usageCorrections/queries.d.ts +115 -0
- package/dist/component/usageCorrections/queries.d.ts.map +1 -0
- package/dist/component/usageCorrections/queries.js +84 -0
- package/dist/component/usageCorrections/queries.js.map +1 -0
- package/dist/component/usageCorrections/schema.d.ts +248 -0
- package/dist/component/usageCorrections/schema.d.ts.map +1 -0
- package/dist/component/usageCorrections/schema.js +74 -0
- package/dist/component/usageCorrections/schema.js.map +1 -0
- package/dist/component/usageCredits/queries.d.ts +1 -1
- package/dist/component/usageCredits/queries.d.ts.map +1 -1
- package/dist/component/usageCredits/queries.js +6 -0
- package/dist/component/usageCredits/queries.js.map +1 -1
- package/dist/component/usageCredits/schema.d.ts +5 -5
- package/dist/component/usageCredits/schema.d.ts.map +1 -1
- package/dist/component/usageCredits/schema.js +1 -1
- package/dist/component/usageCredits/schema.js.map +1 -1
- package/dist/component/usageDelivery/fields.d.ts +2 -2
- package/dist/component/usageDelivery/fields.d.ts.map +1 -1
- package/dist/component/usageDelivery/fields.js +1 -1
- package/dist/component/usageDelivery/fields.js.map +1 -1
- package/dist/component/usageDelivery/helpers.d.ts +7 -6
- package/dist/component/usageDelivery/helpers.d.ts.map +1 -1
- package/dist/component/usageDelivery/mutations.d.ts +6 -6
- package/dist/component/usageDelivery/mutations.d.ts.map +1 -1
- package/dist/component/usageDelivery/mutations.js +9 -1
- package/dist/component/usageDelivery/mutations.js.map +1 -1
- package/dist/component/usageDelivery/queries.d.ts +8 -6
- package/dist/component/usageDelivery/queries.d.ts.map +1 -1
- package/dist/component/usageDelivery/schema.d.ts +4 -4
- package/dist/component/usageDelivery/steps.d.ts +2 -2
- package/dist/component/usageDelivery/steps.js +1 -1
- package/dist/component/usageDelivery/steps.js.map +1 -1
- package/dist/component/usageObservations/queries.d.ts.map +1 -1
- package/dist/component/usageObservations/queries.js +4 -2
- package/dist/component/usageObservations/queries.js.map +1 -1
- package/dist/component/usageSubscriptions/retirement.d.ts.map +1 -1
- package/dist/component/usageSubscriptions/retirement.js +24 -2
- package/dist/component/usageSubscriptions/retirement.js.map +1 -1
- package/docs/README.md +4 -0
- package/docs/settlement.md +4 -0
- package/docs/usage-corrections.md +249 -0
- package/docs/usage-limits.md +1 -1
- package/docs/usage-settlement.md +162 -0
- package/package.json +3 -1
- package/src/client/index.ts +9 -0
- package/src/client/paymentSource/resolver.fixtures.ts +216 -0
- package/src/client/paymentSource/resolver.test.ts +11 -207
- package/src/client/paymentSource/resolver.ts +54 -2
- package/src/client/settlement/execution.ts +24 -0
- package/src/client/usage/catalogPrices.ts +4 -2
- package/src/client/usage/client.ts +2 -2
- package/src/client/usage/correctionClient.test.ts +153 -0
- package/src/client/usage/correctionClient.ts +62 -0
- package/src/client/usage/correctionCredits.test.ts +156 -0
- package/src/client/usage/correctionEligibility.ts +14 -0
- package/src/client/usage/correctionInvoice.test.ts +127 -0
- package/src/client/usage/correctionInvoice.ts +269 -0
- package/src/client/usage/correctionInvoiceProof.ts +40 -0
- package/src/client/usage/correctionProofs.ts +40 -0
- package/src/client/usage/correctionProvider.ts +326 -0
- package/src/client/usage/correctionRead.ts +73 -0
- package/src/client/usage/correctionRecovery.test.ts +113 -0
- package/src/client/usage/correctionTerms.ts +98 -0
- package/src/client/usage/correctionTransport.fixtures.ts +372 -0
- package/src/client/usage/creditRevenue.test.ts +105 -0
- package/src/client/usage/creditRevenue.ts +163 -0
- package/src/client/usage/creditSettlement.fixtures.ts +70 -0
- package/src/client/usage/creditSettlement.test.ts +66 -0
- package/src/client/usage/creditSettlement.ts +94 -0
- package/src/client/usage/creditSettlementRecovery.test.ts +173 -0
- package/src/client/usage/creditTransport.fixtures.ts +29 -4
- package/src/client/usage/index.ts +20 -0
- package/src/client/usage/invoiceSale.fixtures.ts +103 -0
- package/src/client/usage/invoiceSale.test.ts +184 -0
- package/src/client/usage/invoiceSale.ts +155 -0
- package/src/client/usage/observationClient.ts +20 -6
- package/src/client/usage/records.ts +7 -1
- package/src/client/usage/settlement.test.ts +179 -0
- package/src/client/usage/settlement.ts +81 -0
- package/src/client/usage/settlementClient.ts +84 -0
- package/src/client/usage/summary.ts +12 -4
- package/src/client/usageExports.ts +11 -0
- package/src/component/_generated/api.ts +12 -0
- package/src/component/_generated/component.ts +440 -2
- package/src/component/accountClosure/mutations.ts +17 -0
- package/src/component/financialObservations/settlementHelpers.ts +2 -0
- package/src/component/schema.ts +8 -0
- package/src/component/settlement/mutations.ts +10 -1
- package/src/component/settlement/schema.ts +26 -0
- package/src/component/settlement/settlement-claims.test.ts +54 -0
- package/src/component/usage/schema.ts +2 -0
- package/src/component/usageAllowance/queries.ts +8 -1
- package/src/component/usageAllowance/schema.ts +1 -0
- package/src/component/usageCorrections/accounting.ts +79 -0
- package/src/component/usageCorrections/cancellation.ts +32 -0
- package/src/component/usageCorrections/corrections.test.ts +389 -0
- package/src/component/usageCorrections/helpers.ts +57 -0
- package/src/component/usageCorrections/invoice.ts +103 -0
- package/src/component/usageCorrections/mutations.ts +278 -0
- package/src/component/usageCorrections/queries.ts +94 -0
- package/src/component/usageCorrections/schema.ts +90 -0
- package/src/component/usageCredits/queries.ts +4 -0
- package/src/component/usageCredits/schema.ts +1 -0
- package/src/component/usageDelivery/fields.ts +1 -0
- package/src/component/usageDelivery/mutations.ts +8 -3
- package/src/component/usageDelivery/steps.ts +1 -1
- package/src/component/usageObservations/queries.ts +5 -2
- package/src/component/usageSubscriptions/retirement.ts +31 -2
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# Usage corrections and invoice adjustments
|
|
2
|
+
|
|
3
|
+
Correct the original activity through `stripe.usage.requestCorrection`. The package
|
|
4
|
+
retains the immutable event, original subscription/price terms, acceptance receipt,
|
|
5
|
+
delivery history, native outcome and quantity-accounting provenance. Corrections
|
|
6
|
+
never create another cash collection, transfer or commission.
|
|
7
|
+
|
|
8
|
+
Authenticate the operator and authorize the exact original activity on the server.
|
|
9
|
+
Resolve the payer and realm from trusted ownership records. Derive `actor` from the
|
|
10
|
+
signed-in operator, and use an opaque actor ID and a reason without private customer
|
|
11
|
+
information. A browser must not supply another payer, native proof or provider key.
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
const result = await stripe.usage.requestCorrection(
|
|
15
|
+
ctx,
|
|
16
|
+
{
|
|
17
|
+
scope: original.scope,
|
|
18
|
+
eventId: originalReceipt.eventId,
|
|
19
|
+
correctionId: operatorCommand.id,
|
|
20
|
+
actor: authorizedOperator.id,
|
|
21
|
+
reason: "duplicate_activity",
|
|
22
|
+
operation: "cancel",
|
|
23
|
+
},
|
|
24
|
+
{ stripeSecretKey: process.env.STRIPE_SECRET_KEY },
|
|
25
|
+
);
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Run native operations in an action or durable host worker. The same Stripe sandbox
|
|
29
|
+
and server-side key used by the rest of BetterStripe is sufficient. No Metronome
|
|
30
|
+
account or credential is required. Provider keys and raw provider error bodies do
|
|
31
|
+
not enter component history or workflow state.
|
|
32
|
+
|
|
33
|
+
A correction ID is immutable within its realm, payer, meter and mode. Retries keep
|
|
34
|
+
its original actor, reason, event and quantity. Changed requests conflict. Only one
|
|
35
|
+
full event-cancellation operation can claim an event. The original business source
|
|
36
|
+
identity stays retained, including after cancellation or a new subscription.
|
|
37
|
+
|
|
38
|
+
## Full event cancellation
|
|
39
|
+
|
|
40
|
+
For an event that has never started delivery, pay-as-you-go and included-usage
|
|
41
|
+
cancellation completes in the same component transaction as its terminal delivery
|
|
42
|
+
state and quantity restoration. Prepaid first verifies the original successful
|
|
43
|
+
payment, native grant and available backing. It restores only the event's original
|
|
44
|
+
grant allocations, without minting another grant or refunding cash.
|
|
45
|
+
|
|
46
|
+
The original `record` receipt remains unchanged. Read `getDelivery` for its current
|
|
47
|
+
`canceled` state. Canceled delivery cannot start or resume. Summaries retain raw
|
|
48
|
+
`acceptedQuantity`, and expose `canceledQuantity`, `effectiveQuantity` and
|
|
49
|
+
`effectiveScaledQuantity`. Included consumption and cost estimates use effective
|
|
50
|
+
quantity. The event and its original native receipt remain available for audit.
|
|
51
|
+
|
|
52
|
+
For provider-accepted events, BetterStripe sends a native Meter Event Adjustment
|
|
53
|
+
using the retained event name and native identifier. It checks the original realm,
|
|
54
|
+
Accounts v2 payer, mapped Customer, exact meter, subscription item, price and period.
|
|
55
|
+
The package uses a conservative 23-hour window after Stripe's original receipt,
|
|
56
|
+
within Stripe's 24-hour cancellation window. It also closes this path before the
|
|
57
|
+
managed billing period closes.
|
|
58
|
+
|
|
59
|
+
The native v1 adjustment response has no adjustment ID. `nativeAdjustmentId` is
|
|
60
|
+
therefore `null`; the stable correction operation key and original native event
|
|
61
|
+
identifier are retained instead. The package does not invent an adjustment ID,
|
|
62
|
+
retrieval endpoint or completion webhook.
|
|
63
|
+
|
|
64
|
+
A native `pending` response becomes `provider_accepted`, with
|
|
65
|
+
`nativeStatus: "pending"` and `restoredQuantity: "0"`. It does not prove that usage
|
|
66
|
+
was removed from billing. Repeating the command returns that recorded pending
|
|
67
|
+
outcome. A summary or invoice preview is not proof that this individual event was
|
|
68
|
+
canceled. An unresolved pending result needs explicit operator investigation.
|
|
69
|
+
|
|
70
|
+
A native `complete` response can restore units once only after invoice checks
|
|
71
|
+
before and after the request establish that billing remains open and no applicable
|
|
72
|
+
finalized usage invoice was found. Prepaid additionally rechecks payment/grant
|
|
73
|
+
backing after cancellation. If an invoice finalized during cancellation, the
|
|
74
|
+
result retains native completion but becomes `invoice_adjustment_required`, with
|
|
75
|
+
no restored units. Incomplete invoice history stays held.
|
|
76
|
+
|
|
77
|
+
Included allowance restoration updates the original period counter and keeps all
|
|
78
|
+
policy revisions and reservations. It does not grant units in a later period.
|
|
79
|
+
Prepaid restoration retains the original purchase, currency, version, rate,
|
|
80
|
+
allocation and expiry. Refunded, disputed, frozen, expired or unavailable backing
|
|
81
|
+
cannot become spendable through a correction. Use
|
|
82
|
+
[credit reconciliation and recovery](./usage-credits.md) for those cases.
|
|
83
|
+
|
|
84
|
+
## Unknown outcomes and recovery
|
|
85
|
+
|
|
86
|
+
A full correction holds further event delivery while it is unresolved. An
|
|
87
|
+
in-flight or unknown original send cannot be treated as unsent. Let the original
|
|
88
|
+
durable delivery workflow recover its receipt; do not fabricate provider success.
|
|
89
|
+
|
|
90
|
+
Native correction writes use one stable idempotency key. A lost response becomes
|
|
91
|
+
`held` with `provider_outcome_unknown`, and never restores quantity. Retrying the
|
|
92
|
+
same command uses that key and request. Concurrent attempts have a 15-minute lease;
|
|
93
|
+
a crashed attempt retains its identity and can retry after the lease. Receipt
|
|
94
|
+
storage failure can recover through the same retained operation rather than a
|
|
95
|
+
new cancellation command.
|
|
96
|
+
|
|
97
|
+
The package stops native retries 23 hours after the first correction attempt or
|
|
98
|
+
when the original receipt's cancellation window or billing period closes. A provably
|
|
99
|
+
unsent prepaid event can still complete local cancellation later after fresh
|
|
100
|
+
payment/grant verification; no native cancellation write is needed. The package
|
|
101
|
+
returns held or invoice-adjustment-required evidence for operator resolution.
|
|
102
|
+
Do not retry old commands under new IDs, delete an outbox entry or alter the
|
|
103
|
+
original occurrence time to bypass these bounds.
|
|
104
|
+
|
|
105
|
+
Confirmed full cancellation can resolve that event's validation error for
|
|
106
|
+
retirement while preserving every error record. The retirement audit checks at
|
|
107
|
+
most 100 retained validation errors and stays held if the evidence exceeds that
|
|
108
|
+
bound or any error lacks proven cancellation.
|
|
109
|
+
|
|
110
|
+
Pending native corrections and required financial adjustments block managed
|
|
111
|
+
subscription retirement and account closure. New correction work cannot start
|
|
112
|
+
after account closure has begun. Reads retain historical evidence.
|
|
113
|
+
|
|
114
|
+
## Partial quantities and finalized invoices
|
|
115
|
+
|
|
116
|
+
Native Meter Event Adjustments cancel a whole event. Passing an optional
|
|
117
|
+
`quantity` smaller than the original quantity returns `unsupported` with
|
|
118
|
+
`partial_event_requires_replacement_or_invoice_adjustment`. It neither changes the
|
|
119
|
+
original event nor restores units or stops valid delivery. Zero quantities and
|
|
120
|
+
amounts larger than the original are rejected. Do not send negative meter events
|
|
121
|
+
or change an immutable event's payload to simulate a partial correction.
|
|
122
|
+
|
|
123
|
+
A partial replacement is a separately authorized business operation, not an
|
|
124
|
+
implicit refund or new source identity. BetterStripe does not automatically compose
|
|
125
|
+
full cancellation and replacement across asynchronous native outcomes. Use an
|
|
126
|
+
explicit operator workflow and preserve both references if that composition is
|
|
127
|
+
needed. Never grant units while the original cancellation remains pending.
|
|
128
|
+
|
|
129
|
+
An expired cancellation window, a closed period or a finalized usage invoice
|
|
130
|
+
requires an invoice adjustment. A meter cancellation cannot establish that a
|
|
131
|
+
finalized invoice was reduced or that cash was refunded. Use the native Stripe
|
|
132
|
+
credit-note workflow and the existing authorized BetterStripe refund workflow.
|
|
133
|
+
Link an existing refund to the credit note when appropriate. Do not issue a second
|
|
134
|
+
refund merely because a credit note or usage correction is recorded.
|
|
135
|
+
|
|
136
|
+
`observeInvoiceCorrection` verifies and adopts an already issued native credit
|
|
137
|
+
note. It performs provider reads and records evidence. It does not create a credit
|
|
138
|
+
note, refund, customer-balance wallet or new financial settlement.
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
const observed = await stripe.usage.observeInvoiceCorrection(
|
|
142
|
+
ctx,
|
|
143
|
+
{
|
|
144
|
+
scope: original.scope,
|
|
145
|
+
eventId: originalReceipt.eventId,
|
|
146
|
+
correctionId: operatorCommand.id,
|
|
147
|
+
invoiceId: "in_original",
|
|
148
|
+
creditNoteId: "cn_original_adjustment",
|
|
149
|
+
amount: 4, // Exact positive minor currency units authorized by the operator.
|
|
150
|
+
},
|
|
151
|
+
{ stripeSecretKey: process.env.STRIPE_SECRET_KEY },
|
|
152
|
+
);
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
This supports partial or full monetary adjustment against one original, unprorated
|
|
156
|
+
native usage invoice line in the original period and currency. The supplied amount
|
|
157
|
+
must exactly match the credit note. The native invoice, credit-note customer,
|
|
158
|
+
subscription item, price and line identities must agree. A credit note or refund
|
|
159
|
+
can be claimed by only one correction operation in the native realm and mode.
|
|
160
|
+
Changed adoption terms conflict.
|
|
161
|
+
|
|
162
|
+
For a post-payment adjustment, the reader verifies the original paid InvoicePayment,
|
|
163
|
+
PaymentIntent, captured Charge and succeeded linked Refund, with exact safe integer
|
|
164
|
+
amounts and matching currency/payer. A paid invoice alone is not proof of new cash.
|
|
165
|
+
Pre-payment invoice credits have no cash refund. They can even move an invoice to
|
|
166
|
+
`paid` by reducing its amount due to zero; that does not create payment proceeds.
|
|
167
|
+
A verified pre-payment credit-note void is recorded as a reversal with no cash or
|
|
168
|
+
unit restoration. Earlier issued evidence remains in history.
|
|
169
|
+
|
|
170
|
+
The observer returns a correction view when verified, or `{ status: "held", reason }`
|
|
171
|
+
when native evidence is unavailable or unsupported. Handle that union explicitly.
|
|
172
|
+
A verified view exposes `invoiceAdjustment` with the original amount, currency,
|
|
173
|
+
invoice line and any original payment/charge/refund references. `cashCollection`
|
|
174
|
+
always remains `"none"`.
|
|
175
|
+
|
|
176
|
+
A financial adjustment returns `resolution: "invoice_credit"`, retains valid usage
|
|
177
|
+
and its consumed units, and reports `restoredQuantity: "0"`. It cannot silently
|
|
178
|
+
cancel an event or restore credits. Existing seller/affiliate refund, dispute,
|
|
179
|
+
processing-cost and recovery protocols remain authoritative.
|
|
180
|
+
|
|
181
|
+
The bounded v1 observer holds incomplete pages, custom/multiple credit-note lines,
|
|
182
|
+
prorations, taxes/discount combinations, customer-balance or out-of-band adjustments,
|
|
183
|
+
pending refunds, foreign sources and unverified payment mappings. It reads at most
|
|
184
|
+
100 invoices in cancellation preflight and requires complete embedded invoice/note
|
|
185
|
+
lines. It does not turn a partial page into a successful adjustment.
|
|
186
|
+
|
|
187
|
+
Prepaid invoice-credit adoption returns `held` with
|
|
188
|
+
`prepaid_credit_reconciliation_required`. Billing credit-grant application,
|
|
189
|
+
reinstatement, purchase refunds and local quantity restoration are different
|
|
190
|
+
operations. Use the original credit purchase's reconciliation/refund APIs and
|
|
191
|
+
native credit eligibility rules. A credit note, refund or reinstated native balance
|
|
192
|
+
must never independently mint local spendable units.
|
|
193
|
+
|
|
194
|
+
## Scoped history and reconciliation
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
const correction = await stripe.usage.getCorrection(ctx, {
|
|
198
|
+
scope: original.scope,
|
|
199
|
+
eventId: originalReceipt.eventId,
|
|
200
|
+
correctionId: operatorCommand.id,
|
|
201
|
+
});
|
|
202
|
+
const page = await stripe.usage.readCorrectionHistory(ctx, {
|
|
203
|
+
scope: original.scope,
|
|
204
|
+
eventId: originalReceipt.eventId,
|
|
205
|
+
limit: 25,
|
|
206
|
+
cursor: null,
|
|
207
|
+
});
|
|
208
|
+
const periodHistory = await stripe.usage.readCorrectionPeriodHistory(ctx, {
|
|
209
|
+
scope: original.scope,
|
|
210
|
+
period: original.subscription.period,
|
|
211
|
+
limit: 25,
|
|
212
|
+
cursor: null,
|
|
213
|
+
});
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Readers enforce the exact scope and page limits of 1–100. Each history record
|
|
217
|
+
retains original event/subscription snapshots, request identity, actor/reason and
|
|
218
|
+
sanitized native/accounting evidence. The package also decodes `record`,
|
|
219
|
+
`subscription`, `evidence` and `recordedAt` for typed consumers. Follow the returned
|
|
220
|
+
cursor until `isDone`.
|
|
221
|
+
`coverage: "not_recorded"` means no correction evidence was recorded on that page;
|
|
222
|
+
it is not proof that no external or legacy correction ever happened. Undated
|
|
223
|
+
legacy period records set `legacyHistoryMissing`.
|
|
224
|
+
|
|
225
|
+
`getReconciliation` exposes recorded correction history when evidence exists,
|
|
226
|
+
including its cursor and completeness. Without evidence it preserves typed
|
|
227
|
+
unsupported availability. Confirmed quantity cancellation is included in local
|
|
228
|
+
allowance and credit/invoice reconciliation; an unproven canceled projection is
|
|
229
|
+
held rather than counted as a zero charge. Financial adjustments remain separate
|
|
230
|
+
from quantity totals.
|
|
231
|
+
|
|
232
|
+
A correction view is a retained observation, with `observedAt`; it does not poll
|
|
233
|
+
Stripe automatically. Re-observe native invoice adjustments when their state
|
|
234
|
+
changes. Loading, stale, held and partial histories must remain visible in host UI.
|
|
235
|
+
|
|
236
|
+
History is retained with limits of 100 operations per event and 1000 history rows
|
|
237
|
+
per operation. Quota exhaustion fails the accounting transaction atomically.
|
|
238
|
+
Do not delete evidence to make room or release unknown liabilities during rollback.
|
|
239
|
+
Use existing delivery holds while investigating and resume only work whose native
|
|
240
|
+
and original financial outcome is known.
|
|
241
|
+
|
|
242
|
+
Native references: [Meter Event Adjustment API](https://docs.stripe.com/api/billing/meter-event-adjustment/create),
|
|
243
|
+
[credit notes](https://docs.stripe.com/invoicing/dashboard/credit-notes), and
|
|
244
|
+
[retrieving a credit note](https://docs.stripe.com/api/credit_notes/retrieve).
|
|
245
|
+
|
|
246
|
+
A delivery explicitly rejected by the provider with no acceptance receipt can
|
|
247
|
+
also be canceled locally. The original rejection and correction history remain
|
|
248
|
+
available. Paid credits require fresh verification of their original backing
|
|
249
|
+
before restoration. Unknown or in-flight delivery never qualifies for this path.
|
package/docs/usage-limits.md
CHANGED
|
@@ -128,7 +128,7 @@ Committed usage cannot be released. Delivery rejection, uncertainty, delayed
|
|
|
128
128
|
native aggregates or an unpaid invoice do not restore allowance. Corrections
|
|
129
129
|
retain the original event and terms and require an auditable correction outcome;
|
|
130
130
|
never decrement counters based on an invoice preview or an optimistic UI action.
|
|
131
|
-
|
|
131
|
+
See the [auditable correction workflow](./usage-corrections.md).
|
|
132
132
|
|
|
133
133
|
## Edit access policy without resetting consumption
|
|
134
134
|
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# Native usage revenue and settlement
|
|
2
|
+
|
|
3
|
+
Usage, allowance estimates and prepaid consumption are quantity accounting.
|
|
4
|
+
Settle only a verified original cash payment. These methods reuse BetterStripe's
|
|
5
|
+
existing allocation, transfer, refund/dispute, processing-cost and affiliate
|
|
6
|
+
recovery contracts. They require the existing Stripe credentials; no Metronome
|
|
7
|
+
account is needed.
|
|
8
|
+
|
|
9
|
+
## Authorize the original sale
|
|
10
|
+
|
|
11
|
+
Authenticate the caller on your server. Resolve the complete Stripe realm, mode,
|
|
12
|
+
Accounts v2 payer, mapped Customer, original meter, subscription item, price and
|
|
13
|
+
billing period from your trusted records. Authorize the native product's seller,
|
|
14
|
+
affiliate and fee settings before applying them. Browser input, current
|
|
15
|
+
subscription prices and Stripe metadata do not establish ownership.
|
|
16
|
+
|
|
17
|
+
Pass runtime credentials only to the provider options. The package pins the
|
|
18
|
+
original binding's API version, uses a 15-second HTTP timeout and disables SDK
|
|
19
|
+
network retries. It sends no connected-account header: the configured key must
|
|
20
|
+
own the requested realm. Use the ordinary direct billing read when you only need
|
|
21
|
+
revenue evidence. Creating recipient transfers additionally requires a supported
|
|
22
|
+
Stripe Connect separate-charges-and-transfers configuration.
|
|
23
|
+
|
|
24
|
+
## Pay as you go and included overages
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
const original = {
|
|
28
|
+
scope, // Server-authorized realm, payer, meter and mode
|
|
29
|
+
binding, // Immutable plan, API version and native price/customer binding
|
|
30
|
+
subscription, // Original subscription/item/price and monthly period
|
|
31
|
+
period: subscription.period,
|
|
32
|
+
invoiceId,
|
|
33
|
+
paymentIntentId,
|
|
34
|
+
gross, // Expected paid amount in integer minor currency units
|
|
35
|
+
};
|
|
36
|
+
const provider = { stripeSecretKey: process.env.STRIPE_SECRET_KEY };
|
|
37
|
+
const source = await stripe.usage.getInvoiceSale(ctx, original, provider);
|
|
38
|
+
if (source.status !== "ready") return source;
|
|
39
|
+
// Authorize source.value.stripeProductId and all recipient policy on the server.
|
|
40
|
+
return stripe.usage.settleInvoice(
|
|
41
|
+
ctx,
|
|
42
|
+
{
|
|
43
|
+
...original,
|
|
44
|
+
policy: {
|
|
45
|
+
creatorAccountId: authorizedSellerAccount,
|
|
46
|
+
feeBasisPoints: authorizedFeeBasisPoints,
|
|
47
|
+
affiliate: authorizedAffiliate, // Omit when no affiliate applies
|
|
48
|
+
commissionTerm: "one_time", // Or "forever"; default is forever
|
|
49
|
+
collaborators: authorizedCollaborators,
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
provider,
|
|
53
|
+
);
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`getInvoiceSale` is read-only. It verifies the realm/mode, payer mapping, native
|
|
57
|
+
sum meter, immutable native price and original finalized invoice line. Complete
|
|
58
|
+
bidirectional InvoicePayment history must link exactly one full PaymentIntent
|
|
59
|
+
payment to the invoice. The original Charge and BalanceTransaction must reconcile
|
|
60
|
+
gross, actual processing fee, currency and net. The returned source retains the
|
|
61
|
+
original product/price, meter, subscription/item, period and InvoicePayment ID;
|
|
62
|
+
it never substitutes the current subscription's price. Exact native decimal
|
|
63
|
+
quantities are checked without converting them to JavaScript floating point.
|
|
64
|
+
An archived original price remains valid for historical settlement.
|
|
65
|
+
|
|
66
|
+
`settleInvoice` repeats those reads, selects commission eligibility, allocates
|
|
67
|
+
with the existing fee-first helper and executes through the existing transfer
|
|
68
|
+
ledger. The inclusive selling fee has actual processing cost as its floor.
|
|
69
|
+
Original native provenance becomes part of the immutable settlement identity.
|
|
70
|
+
Retries retain the original allocation even after fee changes. A native transfer
|
|
71
|
+
whose persistence failed is recovered before another transfer can be created.
|
|
72
|
+
|
|
73
|
+
A zero initial invoice creates no commission decision. `one_time` uses the first
|
|
74
|
+
paid nonzero invoice from complete native history; delayed webhook delivery does
|
|
75
|
+
not turn a later renewal into a second first payment. `forever` applies per paid
|
|
76
|
+
invoice. Refunds and disputes do not reset eligibility.
|
|
77
|
+
|
|
78
|
+
An unpaid draft/open invoice returns `not_ready/provider_pending`. Missing fees
|
|
79
|
+
remain `not_ready/fee_pending`. Zero paid invoices and refunded/disputed sources
|
|
80
|
+
are not payable. Incomplete or ambiguous funding, credit-funded/partial/multiple
|
|
81
|
+
payments, multiple priced invoice lines, proration, mismatched original periods,
|
|
82
|
+
converted settlement currencies and automatic destination/on-behalf-of charges
|
|
83
|
+
are held through explicit non-ready outcomes. The method does not guess a
|
|
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 original priced line. Treat these
|
|
87
|
+
limits as unsupported settlement combinations, not as zero proceeds.
|
|
88
|
+
|
|
89
|
+
## Prepaid issuer-service revenue
|
|
90
|
+
|
|
91
|
+
Native Stripe billing credits are for the issuing business's own products and
|
|
92
|
+
services. Stripe prohibits using them as third-party payments or stored-value
|
|
93
|
+
wallets. See [Stripe's approved and prohibited uses](https://docs.stripe.com/billing/subscriptions/usage-based/billing-credits).
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
const revenue = await stripe.usage.getCreditPurchaseRevenue(
|
|
97
|
+
ctx,
|
|
98
|
+
originalPurchase,
|
|
99
|
+
provider,
|
|
100
|
+
);
|
|
101
|
+
if (revenue.status !== "ready") return revenue;
|
|
102
|
+
return stripe.usage.settleCreditPurchase(
|
|
103
|
+
ctx,
|
|
104
|
+
{
|
|
105
|
+
...originalPurchase,
|
|
106
|
+
policy: {
|
|
107
|
+
affiliate: authorizedIssuerServiceAffiliate,
|
|
108
|
+
feeBasisPoints: authorizedFeeBasisPoints,
|
|
109
|
+
},
|
|
110
|
+
},
|
|
111
|
+
provider,
|
|
112
|
+
);
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`originalPurchase` is the original `UsageCreditPurchaseOptions`, including
|
|
116
|
+
`ownership: "issuer"`, quantity and immutable price. A verified paid purchase and
|
|
117
|
+
retained grant must already exist. The reader rechecks original purchase
|
|
118
|
+
identity, native payer/realm, payment success, refund/dispute eligibility and the
|
|
119
|
+
actual processing cost. It returns the original PaymentIntent, Charge, grant,
|
|
120
|
+
product/price and purchase ID. It performs no financial writes.
|
|
121
|
+
|
|
122
|
+
`settleCreditPurchase` keeps the issuer's remaining revenue on its own platform
|
|
123
|
+
balance after actual processing costs and any server-authorized affiliate share.
|
|
124
|
+
It creates no seller or reseller transfer. Affiliate policy applies to this
|
|
125
|
+
original paid purchase/top-up, with exact original-charge replay protection.
|
|
126
|
+
A prepaid purchase is a one-time sale rather than an invoice subscription award;
|
|
127
|
+
the host decides whether an affiliate applies to each top-up. Consumption,
|
|
128
|
+
reservation, cancellation, credit expiry and invoice credit application never
|
|
129
|
+
create a second cash sale or affiliate award. An extra seller/collaborator policy
|
|
130
|
+
or non-issuer ownership returns `rejected/unsupported_source`.
|
|
131
|
+
|
|
132
|
+
A pending payment/grant is not revenue available for settlement. A missing
|
|
133
|
+
processing fee is not zero. Refunded/disputed purchase proceeds cannot initiate a
|
|
134
|
+
new settlement. A ready revenue read is not accounting advice about revenue
|
|
135
|
+
recognition or a promise that a native credit may fund another business.
|
|
136
|
+
|
|
137
|
+
## Recovery and operation boundaries
|
|
138
|
+
|
|
139
|
+
Continue to use the existing refund/dispute webhooks and [affiliate recovery](affiliate-clawbacks.md).
|
|
140
|
+
Both invoice and prepaid purchase settlements retain the original charge and
|
|
141
|
+
recipient legs in the same component ledger. Partial refunds accumulate against
|
|
142
|
+
those original legs; disputes and won-dispute reinstatement use the existing
|
|
143
|
+
recovery reservations. Never calculate clawbacks from current rates or issue a
|
|
144
|
+
second commission to compensate for a usage correction.
|
|
145
|
+
|
|
146
|
+
Before refunding a prepaid purchase, follow [paid-credit recovery](usage-credits.md):
|
|
147
|
+
reconcile consumption and disable refundable unspent native credit before using
|
|
148
|
+
the original cash-refund API. A usage correction can restore proven quantity
|
|
149
|
+
without creating cash. A finalized invoice adjustment uses the [correction and
|
|
150
|
+
verified credit-note/refund workflow](usage-corrections.md); it does not erase
|
|
151
|
+
valid usage or reopen affiliate eligibility.
|
|
152
|
+
|
|
153
|
+
Keep original bindings, settlement claims, transfers, grants and recovery history
|
|
154
|
+
while any operation can be retried or reversed. Unsupported account combinations
|
|
155
|
+
require operator resolution. There is no automatic production migration, live
|
|
156
|
+
billing activation, marketplace credit redemption or package publication.
|
|
157
|
+
|
|
158
|
+
The co-located SDK transport and Convex transaction tests cover original invoice
|
|
159
|
+
provenance, fractional quantity, included tiers, zero-first-invoice commission,
|
|
160
|
+
transfer-success/persistence-failure, replay, prepaid purchase consumption and
|
|
161
|
+
refund guards. These tests are not a new native financial sandbox execution;
|
|
162
|
+
project-wide native acceptance is recorded separately.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fantastic.dev/better-stripe",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.60.0",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -108,6 +108,8 @@
|
|
|
108
108
|
"docs/usage-subscriptions.md",
|
|
109
109
|
"docs/usage-credits.md",
|
|
110
110
|
"docs/usage-limits.md",
|
|
111
|
+
"docs/usage-corrections.md",
|
|
112
|
+
"docs/usage-settlement.md",
|
|
111
113
|
"docs/evidence/native-metering"
|
|
112
114
|
],
|
|
113
115
|
"scripts": {
|
package/src/client/index.ts
CHANGED
|
@@ -1811,3 +1811,12 @@ export type {
|
|
|
1811
1811
|
} from "./billing/subscription-payment-method.js";
|
|
1812
1812
|
|
|
1813
1813
|
export * from "./usageExports.js";
|
|
1814
|
+
|
|
1815
|
+
export type {
|
|
1816
|
+
UsageInvoiceSaleOptions,
|
|
1817
|
+
VerifiedUsageInvoiceSale,
|
|
1818
|
+
} from "./usage/invoiceSale.js";
|
|
1819
|
+
export type { UsageInvoiceSettlementOptions } from "./usage/settlement.js";
|
|
1820
|
+
export type { UsageCreditRevenue } from "./usage/creditRevenue.js";
|
|
1821
|
+
|
|
1822
|
+
export type { UsageCreditSettlementOptions } from "./usage/creditSettlement.js";
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
import type Stripe from "stripe";
|
|
2
|
+
import { componentsGeneric } from "convex/server";
|
|
3
|
+
import { BetterStripe } from "../index.js";
|
|
4
|
+
import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
|
|
5
|
+
|
|
6
|
+
export interface SourceHttpClient extends Stripe.HttpClient {}
|
|
7
|
+
export function fixture() {
|
|
8
|
+
const key = `sk_test_source_${crypto.randomUUID()}`;
|
|
9
|
+
const apiVersion = "2026-09-30.preview";
|
|
10
|
+
const client = new BetterStripe(
|
|
11
|
+
componentsGeneric().betterStripe as unknown as Component,
|
|
12
|
+
{
|
|
13
|
+
STRIPE_SECRET_KEY: key,
|
|
14
|
+
stripeApiVersion: apiVersion,
|
|
15
|
+
},
|
|
16
|
+
);
|
|
17
|
+
const transaction = {
|
|
18
|
+
id: "txn_source",
|
|
19
|
+
object: "balance_transaction",
|
|
20
|
+
source: "ch_source",
|
|
21
|
+
amount: 1000,
|
|
22
|
+
fee: 50,
|
|
23
|
+
net: 950,
|
|
24
|
+
currency: "usd",
|
|
25
|
+
};
|
|
26
|
+
const payment = {
|
|
27
|
+
id: "pi_source",
|
|
28
|
+
object: "payment_intent",
|
|
29
|
+
status: "succeeded",
|
|
30
|
+
amount: 1000,
|
|
31
|
+
amount_received: 1000,
|
|
32
|
+
currency: "usd",
|
|
33
|
+
customer_account: "acct_customer",
|
|
34
|
+
livemode: false,
|
|
35
|
+
metadata: { stripePriceId: "price_untrusted" },
|
|
36
|
+
latest_charge: {
|
|
37
|
+
id: "ch_source",
|
|
38
|
+
object: "charge",
|
|
39
|
+
payment_intent: "pi_source",
|
|
40
|
+
amount: 1000,
|
|
41
|
+
amount_captured: 1000,
|
|
42
|
+
currency: "usd",
|
|
43
|
+
paid: true,
|
|
44
|
+
captured: true,
|
|
45
|
+
status: "succeeded",
|
|
46
|
+
amount_refunded: 0,
|
|
47
|
+
disputed: false,
|
|
48
|
+
livemode: false,
|
|
49
|
+
balance_transaction: transaction,
|
|
50
|
+
},
|
|
51
|
+
};
|
|
52
|
+
const invoice = {
|
|
53
|
+
id: "in_source",
|
|
54
|
+
object: "invoice",
|
|
55
|
+
status: "paid",
|
|
56
|
+
currency: "usd",
|
|
57
|
+
amount_paid: 1000,
|
|
58
|
+
amount_due: 1000,
|
|
59
|
+
amount_remaining: 0,
|
|
60
|
+
total: 1000,
|
|
61
|
+
amount_overpaid: 0,
|
|
62
|
+
starting_balance: 0,
|
|
63
|
+
ending_balance: 0,
|
|
64
|
+
customer_account: "acct_customer",
|
|
65
|
+
livemode: false,
|
|
66
|
+
parent: {
|
|
67
|
+
type: "subscription_details",
|
|
68
|
+
subscription_details: { subscription: "sub_source" },
|
|
69
|
+
},
|
|
70
|
+
};
|
|
71
|
+
const funding = {
|
|
72
|
+
id: "inpay_source",
|
|
73
|
+
object: "invoice_payment",
|
|
74
|
+
invoice: "in_source",
|
|
75
|
+
status: "paid",
|
|
76
|
+
currency: "usd",
|
|
77
|
+
amount_paid: 1000,
|
|
78
|
+
amount_requested: 1000,
|
|
79
|
+
livemode: false,
|
|
80
|
+
payment: { type: "payment_intent", payment_intent: "pi_source" },
|
|
81
|
+
};
|
|
82
|
+
const line = {
|
|
83
|
+
id: "il_source",
|
|
84
|
+
object: "line_item",
|
|
85
|
+
invoice: "in_source",
|
|
86
|
+
currency: "usd",
|
|
87
|
+
amount: 1000,
|
|
88
|
+
quantity: 1,
|
|
89
|
+
livemode: false,
|
|
90
|
+
parent: {
|
|
91
|
+
type: "subscription_item_details",
|
|
92
|
+
subscription_item_details: {
|
|
93
|
+
subscription: "sub_source",
|
|
94
|
+
subscription_item: "si_source",
|
|
95
|
+
proration: false,
|
|
96
|
+
},
|
|
97
|
+
},
|
|
98
|
+
pricing: {
|
|
99
|
+
type: "price_details",
|
|
100
|
+
price_details: { price: "price_original", product: "prod_original" },
|
|
101
|
+
unit_amount_decimal: "1000",
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
const subscription = {
|
|
105
|
+
id: "sub_source",
|
|
106
|
+
object: "subscription",
|
|
107
|
+
customer_account: "acct_customer",
|
|
108
|
+
livemode: false,
|
|
109
|
+
metadata: { sellerId: "untrusted" },
|
|
110
|
+
items: {
|
|
111
|
+
data: [{ price: { id: "price_current", product: "prod_current" } }],
|
|
112
|
+
},
|
|
113
|
+
};
|
|
114
|
+
const history = { inverse: [funding], funding: [funding], lines: [line] };
|
|
115
|
+
const pages = new Map<string, { data: unknown[]; has_more: boolean }>();
|
|
116
|
+
const requests: {
|
|
117
|
+
path: string;
|
|
118
|
+
method: string;
|
|
119
|
+
version: string;
|
|
120
|
+
account: string;
|
|
121
|
+
}[] = [];
|
|
122
|
+
const sdk = getStripeClient(key, apiVersion);
|
|
123
|
+
const extra = new Map<string, unknown>();
|
|
124
|
+
(
|
|
125
|
+
sdk as unknown as { _setApiField: (name: string, value: unknown) => void }
|
|
126
|
+
)._setApiField("httpClient", {
|
|
127
|
+
getClientName: () => "verified-source-contract",
|
|
128
|
+
makeRequest: async (
|
|
129
|
+
...[, , path, method, headers, body]: Parameters<
|
|
130
|
+
ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
|
|
131
|
+
>
|
|
132
|
+
) => {
|
|
133
|
+
requests.push({
|
|
134
|
+
path,
|
|
135
|
+
method,
|
|
136
|
+
version: String(headers["Stripe-Version"]),
|
|
137
|
+
account: String(headers["Stripe-Account"]),
|
|
138
|
+
});
|
|
139
|
+
const url = new URL(path, "https://stripe.test");
|
|
140
|
+
const phase = url.pathname.endsWith("/lines")
|
|
141
|
+
? "lines"
|
|
142
|
+
: url.searchParams.has("invoice")
|
|
143
|
+
? "funding"
|
|
144
|
+
: "inverse";
|
|
145
|
+
const override = pages.get(
|
|
146
|
+
phase + ":" + (url.searchParams.get("starting_after") ?? ""),
|
|
147
|
+
);
|
|
148
|
+
const handler = extra.get(url.pathname);
|
|
149
|
+
const data =
|
|
150
|
+
(typeof handler === "function" ? handler(method, body) : handler) ??
|
|
151
|
+
(url.pathname === "/v1/payment_intents/pi_source"
|
|
152
|
+
? payment
|
|
153
|
+
: url.pathname === "/v1/invoices/in_source"
|
|
154
|
+
? invoice
|
|
155
|
+
: url.pathname === "/v1/subscriptions/sub_source"
|
|
156
|
+
? subscription
|
|
157
|
+
: {
|
|
158
|
+
object: "list",
|
|
159
|
+
url: url.pathname,
|
|
160
|
+
has_more: override?.has_more ?? false,
|
|
161
|
+
data:
|
|
162
|
+
override?.data ??
|
|
163
|
+
(phase === "lines"
|
|
164
|
+
? history.lines
|
|
165
|
+
: phase === "funding"
|
|
166
|
+
? history.funding
|
|
167
|
+
: history.inverse),
|
|
168
|
+
});
|
|
169
|
+
return {
|
|
170
|
+
getStatusCode: () => 200,
|
|
171
|
+
getHeaders: () => ({}),
|
|
172
|
+
getRawResponse: () => ({}),
|
|
173
|
+
toJSON: async () => JSON.parse(JSON.stringify(data)),
|
|
174
|
+
toStream: () => {
|
|
175
|
+
throw new Error("Unexpected stream");
|
|
176
|
+
},
|
|
177
|
+
};
|
|
178
|
+
},
|
|
179
|
+
});
|
|
180
|
+
const options = {
|
|
181
|
+
paymentIntentId: "pi_source",
|
|
182
|
+
customerAccountId: "acct_customer",
|
|
183
|
+
stripeAccountId: "acct_connected",
|
|
184
|
+
gross: 1000,
|
|
185
|
+
currency: "usd",
|
|
186
|
+
};
|
|
187
|
+
const resolve = (
|
|
188
|
+
overrides: Partial<typeof options> & {
|
|
189
|
+
maxHistoryPages?: number;
|
|
190
|
+
maxHistoryItems?: number;
|
|
191
|
+
} = {},
|
|
192
|
+
) => {
|
|
193
|
+
return client.getVerifiedPaymentSource({} as RunCtx, {
|
|
194
|
+
...options,
|
|
195
|
+
...overrides,
|
|
196
|
+
});
|
|
197
|
+
};
|
|
198
|
+
return {
|
|
199
|
+
resolve,
|
|
200
|
+
sdk,
|
|
201
|
+
httpClient: (
|
|
202
|
+
sdk as unknown as { getApiField(name: string): SourceHttpClient }
|
|
203
|
+
).getApiField("httpClient"),
|
|
204
|
+
extra,
|
|
205
|
+
client,
|
|
206
|
+
options,
|
|
207
|
+
payment,
|
|
208
|
+
invoice,
|
|
209
|
+
funding,
|
|
210
|
+
line,
|
|
211
|
+
subscription,
|
|
212
|
+
history,
|
|
213
|
+
requests,
|
|
214
|
+
pages,
|
|
215
|
+
};
|
|
216
|
+
}
|