@fantastic.dev/better-stripe 0.59.0 → 0.60.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 +12 -0
- package/README.md +5 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +676 -50
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +322 -9
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +644 -18
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +338 -25
- 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/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.js +2 -2
- package/dist/client/usage/creditCapacity.d.ts.map +1 -1
- package/dist/client/usage/creditCapacity.js +7 -1
- package/dist/client/usage/creditCapacity.js.map +1 -1
- package/dist/client/usage/creditClient.d.ts +3 -0
- package/dist/client/usage/creditClient.d.ts.map +1 -1
- package/dist/client/usage/creditDelivery.d.ts.map +1 -1
- package/dist/client/usage/creditDelivery.js +4 -1
- package/dist/client/usage/creditDelivery.js.map +1 -1
- package/dist/client/usage/creditLifecycle.d.ts.map +1 -1
- package/dist/client/usage/creditLifecycle.js +2 -1
- package/dist/client/usage/creditLifecycle.js.map +1 -1
- package/dist/client/usage/creditNative.d.ts +3 -0
- package/dist/client/usage/creditNative.d.ts.map +1 -1
- package/dist/client/usage/creditNative.js +3 -0
- package/dist/client/usage/creditNative.js.map +1 -1
- package/dist/client/usage/creditProvider.d.ts.map +1 -1
- package/dist/client/usage/creditProvider.js +2 -1
- package/dist/client/usage/creditProvider.js.map +1 -1
- package/dist/client/usage/creditRead.d.ts +1 -0
- package/dist/client/usage/creditRead.d.ts.map +1 -1
- package/dist/client/usage/creditReconciliation.d.ts.map +1 -1
- package/dist/client/usage/creditReconciliation.js +11 -3
- package/dist/client/usage/creditReconciliation.js.map +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 +216 -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 +8 -1
- package/dist/client/usage/creditTransport.fixtures.d.ts.map +1 -1
- package/dist/client/usage/creditTransport.fixtures.js +27 -5
- package/dist/client/usage/creditTransport.fixtures.js.map +1 -1
- package/dist/client/usage/index.d.ts +4 -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 +2 -2
- package/dist/client/usage/observationClient.d.ts.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/subscriptionCancellation.d.ts.map +1 -1
- package/dist/client/usage/subscriptionCancellation.js +3 -2
- package/dist/client/usage/subscriptionCancellation.js.map +1 -1
- package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -1
- package/dist/client/usage/subscriptionCheckout.js +3 -2
- package/dist/client/usage/subscriptionCheckout.js.map +1 -1
- package/dist/client/usage/subscriptionLifecycle.d.ts +1 -0
- package/dist/client/usage/subscriptionLifecycle.d.ts.map +1 -1
- package/dist/client/usage/subscriptionLifecycle.js +3 -2
- package/dist/client/usage/subscriptionLifecycle.js.map +1 -1
- package/dist/client/usage/subscriptionProvider.d.ts +2 -0
- package/dist/client/usage/subscriptionProvider.d.ts.map +1 -1
- package/dist/client/usage/subscriptionProvider.js +9 -2
- package/dist/client/usage/subscriptionProvider.js.map +1 -1
- package/dist/component/_generated/component.d.ts +146 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
- package/dist/component/balanceFunding/mutations.d.ts +27 -27
- package/dist/component/earnings/triggers.d.ts +172 -12
- 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 +322 -9
- 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/allowance.fixtures.d.ts +4212 -0
- package/dist/component/usage/allowance.fixtures.d.ts.map +1 -0
- package/dist/component/usage/allowance.fixtures.js +67 -0
- package/dist/component/usage/allowance.fixtures.js.map +1 -0
- package/dist/component/usageCredits/accounting.fixtures.d.ts +4235 -0
- package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -0
- package/dist/component/usageCredits/accounting.fixtures.js +89 -0
- package/dist/component/usageCredits/accounting.fixtures.js.map +1 -0
- package/dist/component/usageCredits/helpers.d.ts +7 -0
- package/dist/component/usageCredits/helpers.d.ts.map +1 -1
- package/dist/component/usageCredits/helpers.js +5 -0
- package/dist/component/usageCredits/helpers.js.map +1 -1
- package/dist/component/usageCredits/mutations.d.ts +6 -0
- package/dist/component/usageCredits/mutations.d.ts.map +1 -1
- package/dist/component/usageCredits/mutations.js +70 -7
- package/dist/component/usageCredits/mutations.js.map +1 -1
- package/dist/component/usageCredits/purchase.d.ts +1 -0
- package/dist/component/usageCredits/purchase.d.ts.map +1 -1
- package/dist/component/usageCredits/queries.d.ts +10 -0
- package/dist/component/usageCredits/queries.d.ts.map +1 -1
- package/dist/component/usageCredits/schema.d.ts +24 -4
- package/dist/component/usageCredits/schema.d.ts.map +1 -1
- package/dist/component/usageCredits/schema.js +4 -0
- package/dist/component/usageCredits/schema.js.map +1 -1
- package/dist/component/usageSubscriptions/history.d.ts.map +1 -1
- package/dist/component/usageSubscriptions/history.js +3 -1
- package/dist/component/usageSubscriptions/history.js.map +1 -1
- package/dist/component/usageSubscriptions/mutations.d.ts +5 -0
- package/dist/component/usageSubscriptions/mutations.d.ts.map +1 -1
- package/dist/component/usageSubscriptions/mutations.js +19 -0
- package/dist/component/usageSubscriptions/mutations.js.map +1 -1
- package/dist/component/usageSubscriptions/queries.d.ts +2 -0
- package/dist/component/usageSubscriptions/queries.d.ts.map +1 -1
- package/dist/component/usageSubscriptions/schema.d.ts +7 -2
- package/dist/component/usageSubscriptions/schema.d.ts.map +1 -1
- package/dist/component/usageSubscriptions/schema.js +1 -0
- package/dist/component/usageSubscriptions/schema.js.map +1 -1
- package/docs/README.md +4 -0
- package/docs/settlement.md +4 -0
- package/docs/usage-credits.md +6 -1
- package/docs/usage-security.md +130 -0
- 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/creditBackingIsolation.test.ts +110 -0
- package/src/client/usage/creditCapacity.test.ts +80 -1
- package/src/client/usage/creditCapacity.ts +10 -1
- package/src/client/usage/creditDelivery.ts +4 -0
- package/src/client/usage/creditLifecycle.ts +2 -0
- package/src/client/usage/creditNative.ts +5 -0
- package/src/client/usage/creditProofBounds.test.ts +187 -0
- package/src/client/usage/creditProvider.test.ts +74 -0
- package/src/client/usage/creditProvider.ts +2 -0
- package/src/client/usage/creditReconciliation.ts +18 -3
- 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 +31 -5
- package/src/client/usage/index.ts +9 -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/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/subscriptionCancellation.ts +3 -2
- package/src/client/usage/subscriptionCheckout.ts +7 -2
- package/src/client/usage/subscriptionClient.test.ts +60 -1
- package/src/client/usage/subscriptionLifecycle.ts +3 -2
- package/src/client/usage/subscriptionProvider.ts +27 -3
- package/src/component/_generated/component.ts +150 -1
- package/src/component/financialObservations/settlementHelpers.ts +2 -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/allowance.fixtures.ts +77 -0
- package/src/component/usage/allowance.test.ts +3 -66
- package/src/component/usage/allowanceBounds.test.ts +79 -0
- package/src/component/usage/historyIsolation.test.ts +124 -0
- package/src/component/usageCredits/accounting.fixtures.ts +96 -0
- package/src/component/usageCredits/accounting.test.ts +176 -82
- package/src/component/usageCredits/freshness.test.ts +33 -0
- package/src/component/usageCredits/helpers.ts +8 -0
- package/src/component/usageCredits/mutations.ts +83 -5
- package/src/component/usageCredits/quotas.test.ts +63 -0
- package/src/component/usageCredits/schema.ts +10 -0
- package/src/component/usageSubscriptions/history.test.ts +57 -0
- package/src/component/usageSubscriptions/history.ts +3 -1
- package/src/component/usageSubscriptions/mutations.ts +23 -0
- package/src/component/usageSubscriptions/schema.ts +1 -0
|
@@ -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.1",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -109,6 +109,8 @@
|
|
|
109
109
|
"docs/usage-credits.md",
|
|
110
110
|
"docs/usage-limits.md",
|
|
111
111
|
"docs/usage-corrections.md",
|
|
112
|
+
"docs/usage-settlement.md",
|
|
113
|
+
"docs/usage-security.md",
|
|
112
114
|
"docs/evidence/native-metering"
|
|
113
115
|
],
|
|
114
116
|
"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
|
+
}
|
|
@@ -1,211 +1,6 @@
|
|
|
1
|
-
import type
|
|
2
|
-
import { componentsGeneric } from "convex/server";
|
|
1
|
+
import type { RunCtx } from "../helpers.js";
|
|
3
2
|
import { expect, it } from "vitest";
|
|
4
|
-
import {
|
|
5
|
-
import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
|
|
6
|
-
|
|
7
|
-
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
|
-
(
|
|
124
|
-
sdk as unknown as { _setApiField: (name: string, value: unknown) => void }
|
|
125
|
-
)._setApiField("httpClient", {
|
|
126
|
-
getClientName: () => "verified-source-contract",
|
|
127
|
-
makeRequest: async (
|
|
128
|
-
...[, , path, method, headers]: Parameters<
|
|
129
|
-
ReturnType<typeof Stripe.createNodeHttpClient>["makeRequest"]
|
|
130
|
-
>
|
|
131
|
-
) => {
|
|
132
|
-
requests.push({
|
|
133
|
-
path,
|
|
134
|
-
method,
|
|
135
|
-
version: String(headers["Stripe-Version"]),
|
|
136
|
-
account: String(headers["Stripe-Account"]),
|
|
137
|
-
});
|
|
138
|
-
const url = new URL(path, "https://stripe.test");
|
|
139
|
-
const phase = url.pathname.endsWith("/lines")
|
|
140
|
-
? "lines"
|
|
141
|
-
: url.searchParams.has("invoice")
|
|
142
|
-
? "funding"
|
|
143
|
-
: "inverse";
|
|
144
|
-
const override = pages.get(
|
|
145
|
-
phase + ":" + (url.searchParams.get("starting_after") ?? ""),
|
|
146
|
-
);
|
|
147
|
-
const data =
|
|
148
|
-
url.pathname === "/v1/payment_intents/pi_source"
|
|
149
|
-
? payment
|
|
150
|
-
: url.pathname === "/v1/invoices/in_source"
|
|
151
|
-
? invoice
|
|
152
|
-
: url.pathname === "/v1/subscriptions/sub_source"
|
|
153
|
-
? subscription
|
|
154
|
-
: {
|
|
155
|
-
object: "list",
|
|
156
|
-
url: url.pathname,
|
|
157
|
-
has_more: override?.has_more ?? false,
|
|
158
|
-
data:
|
|
159
|
-
override?.data ??
|
|
160
|
-
(phase === "lines"
|
|
161
|
-
? history.lines
|
|
162
|
-
: phase === "funding"
|
|
163
|
-
? history.funding
|
|
164
|
-
: history.inverse),
|
|
165
|
-
};
|
|
166
|
-
return {
|
|
167
|
-
getStatusCode: () => 200,
|
|
168
|
-
getHeaders: () => ({}),
|
|
169
|
-
getRawResponse: () => ({}),
|
|
170
|
-
toJSON: async () => data,
|
|
171
|
-
toStream: () => {
|
|
172
|
-
throw new Error("Unexpected stream");
|
|
173
|
-
},
|
|
174
|
-
};
|
|
175
|
-
},
|
|
176
|
-
});
|
|
177
|
-
const options = {
|
|
178
|
-
paymentIntentId: "pi_source",
|
|
179
|
-
customerAccountId: "acct_customer",
|
|
180
|
-
stripeAccountId: "acct_connected",
|
|
181
|
-
gross: 1000,
|
|
182
|
-
currency: "usd",
|
|
183
|
-
};
|
|
184
|
-
const resolve = (
|
|
185
|
-
overrides: Partial<typeof options> & {
|
|
186
|
-
maxHistoryPages?: number;
|
|
187
|
-
maxHistoryItems?: number;
|
|
188
|
-
} = {},
|
|
189
|
-
) => {
|
|
190
|
-
return client.getVerifiedPaymentSource({} as RunCtx, {
|
|
191
|
-
...options,
|
|
192
|
-
...overrides,
|
|
193
|
-
});
|
|
194
|
-
};
|
|
195
|
-
return {
|
|
196
|
-
resolve,
|
|
197
|
-
client,
|
|
198
|
-
options,
|
|
199
|
-
payment,
|
|
200
|
-
invoice,
|
|
201
|
-
funding,
|
|
202
|
-
line,
|
|
203
|
-
subscription,
|
|
204
|
-
history,
|
|
205
|
-
requests,
|
|
206
|
-
pages,
|
|
207
|
-
};
|
|
208
|
-
}
|
|
3
|
+
import { fixture } from "./resolver.fixtures.js";
|
|
209
4
|
|
|
210
5
|
it("resolves a complete original invoice price through the inherited SDK method, ignoring current prices and metadata", async () => {
|
|
211
6
|
const s = fixture();
|
|
@@ -580,3 +375,12 @@ it("requires original line subscription binding and refuses proration", async ()
|
|
|
580
375
|
prorated.line.parent.subscription_item_details.proration = true;
|
|
581
376
|
expect(await prorated.resolve()).toEqual(terminal("unsupported_source"));
|
|
582
377
|
});
|
|
378
|
+
|
|
379
|
+
it("retains exact fractional native invoice quantity without rejecting its original cash provenance", async () => {
|
|
380
|
+
const f = fixture();
|
|
381
|
+
Object.assign(f.line, { quantity: null, quantity_decimal: "1.125" });
|
|
382
|
+
expect(await f.resolve()).toMatchObject({
|
|
383
|
+
status: "ready",
|
|
384
|
+
value: { stripePriceId: "price_original", gross: 1000 },
|
|
385
|
+
});
|
|
386
|
+
});
|