@fantastic.dev/better-stripe 0.57.0 → 0.59.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.
Files changed (230) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +3 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +356 -50
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +162 -9
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +356 -50
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +162 -9
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/usage/allowanceClient.d.ts +51 -0
  12. package/dist/client/usage/allowanceClient.d.ts.map +1 -0
  13. package/dist/client/usage/allowanceClient.js +64 -0
  14. package/dist/client/usage/allowanceClient.js.map +1 -0
  15. package/dist/client/usage/allowanceTerms.d.ts +64 -0
  16. package/dist/client/usage/allowanceTerms.d.ts.map +1 -0
  17. package/dist/client/usage/allowanceTerms.js +101 -0
  18. package/dist/client/usage/allowanceTerms.js.map +1 -0
  19. package/dist/client/usage/client.d.ts +2 -2
  20. package/dist/client/usage/client.d.ts.map +1 -1
  21. package/dist/client/usage/client.js +2 -2
  22. package/dist/client/usage/client.js.map +1 -1
  23. package/dist/client/usage/correctionClient.d.ts +33 -0
  24. package/dist/client/usage/correctionClient.d.ts.map +1 -0
  25. package/dist/client/usage/correctionClient.js +27 -0
  26. package/dist/client/usage/correctionClient.js.map +1 -0
  27. package/dist/client/usage/correctionEligibility.d.ts +4 -0
  28. package/dist/client/usage/correctionEligibility.d.ts.map +1 -0
  29. package/dist/client/usage/correctionEligibility.js +7 -0
  30. package/dist/client/usage/correctionEligibility.js.map +1 -0
  31. package/dist/client/usage/correctionInvoice.d.ts +9 -0
  32. package/dist/client/usage/correctionInvoice.d.ts.map +1 -0
  33. package/dist/client/usage/correctionInvoice.js +218 -0
  34. package/dist/client/usage/correctionInvoice.js.map +1 -0
  35. package/dist/client/usage/correctionInvoiceProof.d.ts +29 -0
  36. package/dist/client/usage/correctionInvoiceProof.d.ts.map +1 -0
  37. package/dist/client/usage/correctionInvoiceProof.js +41 -0
  38. package/dist/client/usage/correctionInvoiceProof.js.map +1 -0
  39. package/dist/client/usage/correctionProofs.d.ts +36 -0
  40. package/dist/client/usage/correctionProofs.d.ts.map +1 -0
  41. package/dist/client/usage/correctionProofs.js +41 -0
  42. package/dist/client/usage/correctionProofs.js.map +1 -0
  43. package/dist/client/usage/correctionProvider.d.ts +6 -0
  44. package/dist/client/usage/correctionProvider.d.ts.map +1 -0
  45. package/dist/client/usage/correctionProvider.js +243 -0
  46. package/dist/client/usage/correctionProvider.js.map +1 -0
  47. package/dist/client/usage/correctionRead.d.ts +27 -0
  48. package/dist/client/usage/correctionRead.d.ts.map +1 -0
  49. package/dist/client/usage/correctionRead.js +36 -0
  50. package/dist/client/usage/correctionRead.js.map +1 -0
  51. package/dist/client/usage/correctionTerms.d.ts +64 -0
  52. package/dist/client/usage/correctionTerms.d.ts.map +1 -0
  53. package/dist/client/usage/correctionTerms.js +65 -0
  54. package/dist/client/usage/correctionTerms.js.map +1 -0
  55. package/dist/client/usage/correctionTransport.fixtures.d.ts +37 -0
  56. package/dist/client/usage/correctionTransport.fixtures.d.ts.map +1 -0
  57. package/dist/client/usage/correctionTransport.fixtures.js +322 -0
  58. package/dist/client/usage/correctionTransport.fixtures.js.map +1 -0
  59. package/dist/client/usage/creditClient.d.ts +1 -1
  60. package/dist/client/usage/index.d.ts +4 -0
  61. package/dist/client/usage/index.d.ts.map +1 -1
  62. package/dist/client/usage/observationClient.d.ts +20 -0
  63. package/dist/client/usage/observationClient.d.ts.map +1 -1
  64. package/dist/client/usage/observationClient.js +20 -6
  65. package/dist/client/usage/observationClient.js.map +1 -1
  66. package/dist/client/usage/records.d.ts +1 -1
  67. package/dist/client/usage/records.d.ts.map +1 -1
  68. package/dist/client/usage/records.js.map +1 -1
  69. package/dist/client/usage/summary.d.ts +3 -0
  70. package/dist/client/usage/summary.d.ts.map +1 -1
  71. package/dist/client/usage/summary.js +9 -4
  72. package/dist/client/usage/summary.js.map +1 -1
  73. package/dist/client/usageExports.d.ts +4 -0
  74. package/dist/client/usageExports.d.ts.map +1 -1
  75. package/dist/component/_generated/api.d.ts +20 -0
  76. package/dist/component/_generated/api.d.ts.map +1 -1
  77. package/dist/component/_generated/api.js.map +1 -1
  78. package/dist/component/_generated/component.d.ts +324 -13
  79. package/dist/component/_generated/component.d.ts.map +1 -1
  80. package/dist/component/accountClosure/mutations.d.ts.map +1 -1
  81. package/dist/component/accountClosure/mutations.js +13 -0
  82. package/dist/component/accountClosure/mutations.js.map +1 -1
  83. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  84. package/dist/component/balanceFunding/mutations.d.ts +43 -43
  85. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  86. package/dist/component/earnings/triggers.d.ts +288 -10
  87. package/dist/component/earnings/triggers.d.ts.map +1 -1
  88. package/dist/component/schema.d.ts +162 -9
  89. package/dist/component/schema.js +7 -0
  90. package/dist/component/schema.js.map +1 -1
  91. package/dist/component/usage/mutations.d.ts.map +1 -1
  92. package/dist/component/usage/mutations.js +4 -0
  93. package/dist/component/usage/mutations.js.map +1 -1
  94. package/dist/component/usage/queries.d.ts +2 -2
  95. package/dist/component/usage/schema.d.ts +21 -15
  96. package/dist/component/usage/schema.d.ts.map +1 -1
  97. package/dist/component/usage/schema.js +4 -2
  98. package/dist/component/usage/schema.js.map +1 -1
  99. package/dist/component/usageAllowance/helpers.d.ts +78 -0
  100. package/dist/component/usageAllowance/helpers.d.ts.map +1 -0
  101. package/dist/component/usageAllowance/helpers.js +99 -0
  102. package/dist/component/usageAllowance/helpers.js.map +1 -0
  103. package/dist/component/usageAllowance/mutations.d.ts +37 -0
  104. package/dist/component/usageAllowance/mutations.d.ts.map +1 -0
  105. package/dist/component/usageAllowance/mutations.js +99 -0
  106. package/dist/component/usageAllowance/mutations.js.map +1 -0
  107. package/dist/component/usageAllowance/queries.d.ts +36 -0
  108. package/dist/component/usageAllowance/queries.d.ts.map +1 -0
  109. package/dist/component/usageAllowance/queries.js +122 -0
  110. package/dist/component/usageAllowance/queries.js.map +1 -0
  111. package/dist/component/usageAllowance/reservations.d.ts +25 -0
  112. package/dist/component/usageAllowance/reservations.d.ts.map +1 -0
  113. package/dist/component/usageAllowance/reservations.js +150 -0
  114. package/dist/component/usageAllowance/reservations.js.map +1 -0
  115. package/dist/component/usageAllowance/schema.d.ts +77 -0
  116. package/dist/component/usageAllowance/schema.d.ts.map +1 -0
  117. package/dist/component/usageAllowance/schema.js +32 -0
  118. package/dist/component/usageAllowance/schema.js.map +1 -0
  119. package/dist/component/usageCorrections/accounting.d.ts +5 -0
  120. package/dist/component/usageCorrections/accounting.d.ts.map +1 -0
  121. package/dist/component/usageCorrections/accounting.js +55 -0
  122. package/dist/component/usageCorrections/accounting.js.map +1 -0
  123. package/dist/component/usageCorrections/cancellation.d.ts +6 -0
  124. package/dist/component/usageCorrections/cancellation.d.ts.map +1 -0
  125. package/dist/component/usageCorrections/cancellation.js +29 -0
  126. package/dist/component/usageCorrections/cancellation.js.map +1 -0
  127. package/dist/component/usageCorrections/helpers.d.ts +60 -0
  128. package/dist/component/usageCorrections/helpers.d.ts.map +1 -0
  129. package/dist/component/usageCorrections/helpers.js +52 -0
  130. package/dist/component/usageCorrections/helpers.js.map +1 -0
  131. package/dist/component/usageCorrections/invoice.d.ts +38 -0
  132. package/dist/component/usageCorrections/invoice.d.ts.map +1 -0
  133. package/dist/component/usageCorrections/invoice.js +82 -0
  134. package/dist/component/usageCorrections/invoice.js.map +1 -0
  135. package/dist/component/usageCorrections/mutations.d.ts +121 -0
  136. package/dist/component/usageCorrections/mutations.d.ts.map +1 -0
  137. package/dist/component/usageCorrections/mutations.js +256 -0
  138. package/dist/component/usageCorrections/mutations.js.map +1 -0
  139. package/dist/component/usageCorrections/queries.d.ts +115 -0
  140. package/dist/component/usageCorrections/queries.d.ts.map +1 -0
  141. package/dist/component/usageCorrections/queries.js +84 -0
  142. package/dist/component/usageCorrections/queries.js.map +1 -0
  143. package/dist/component/usageCorrections/schema.d.ts +248 -0
  144. package/dist/component/usageCorrections/schema.d.ts.map +1 -0
  145. package/dist/component/usageCorrections/schema.js +74 -0
  146. package/dist/component/usageCorrections/schema.js.map +1 -0
  147. package/dist/component/usageCredits/queries.d.ts +1 -1
  148. package/dist/component/usageCredits/queries.d.ts.map +1 -1
  149. package/dist/component/usageCredits/queries.js +6 -0
  150. package/dist/component/usageCredits/queries.js.map +1 -1
  151. package/dist/component/usageCredits/schema.d.ts +5 -5
  152. package/dist/component/usageCredits/schema.d.ts.map +1 -1
  153. package/dist/component/usageCredits/schema.js +1 -1
  154. package/dist/component/usageCredits/schema.js.map +1 -1
  155. package/dist/component/usageDelivery/fields.d.ts +2 -2
  156. package/dist/component/usageDelivery/fields.d.ts.map +1 -1
  157. package/dist/component/usageDelivery/fields.js +1 -1
  158. package/dist/component/usageDelivery/fields.js.map +1 -1
  159. package/dist/component/usageDelivery/helpers.d.ts +7 -6
  160. package/dist/component/usageDelivery/helpers.d.ts.map +1 -1
  161. package/dist/component/usageDelivery/mutations.d.ts +6 -6
  162. package/dist/component/usageDelivery/mutations.d.ts.map +1 -1
  163. package/dist/component/usageDelivery/mutations.js +9 -1
  164. package/dist/component/usageDelivery/mutations.js.map +1 -1
  165. package/dist/component/usageDelivery/queries.d.ts +8 -6
  166. package/dist/component/usageDelivery/queries.d.ts.map +1 -1
  167. package/dist/component/usageDelivery/schema.d.ts +4 -4
  168. package/dist/component/usageDelivery/steps.d.ts +2 -2
  169. package/dist/component/usageDelivery/steps.js +1 -1
  170. package/dist/component/usageDelivery/steps.js.map +1 -1
  171. package/dist/component/usageObservations/queries.d.ts.map +1 -1
  172. package/dist/component/usageObservations/queries.js +4 -2
  173. package/dist/component/usageObservations/queries.js.map +1 -1
  174. package/dist/component/usageSubscriptions/retirement.d.ts.map +1 -1
  175. package/dist/component/usageSubscriptions/retirement.js +24 -2
  176. package/dist/component/usageSubscriptions/retirement.js.map +1 -1
  177. package/docs/README.md +4 -0
  178. package/docs/usage-corrections.md +249 -0
  179. package/docs/usage-limits.md +217 -0
  180. package/package.json +3 -1
  181. package/src/client/usage/allowanceClient.test.ts +93 -0
  182. package/src/client/usage/allowanceClient.ts +134 -0
  183. package/src/client/usage/allowanceTerms.test.ts +131 -0
  184. package/src/client/usage/allowanceTerms.ts +172 -0
  185. package/src/client/usage/client.ts +2 -2
  186. package/src/client/usage/correctionClient.test.ts +153 -0
  187. package/src/client/usage/correctionClient.ts +62 -0
  188. package/src/client/usage/correctionCredits.test.ts +156 -0
  189. package/src/client/usage/correctionEligibility.ts +14 -0
  190. package/src/client/usage/correctionInvoice.test.ts +127 -0
  191. package/src/client/usage/correctionInvoice.ts +269 -0
  192. package/src/client/usage/correctionInvoiceProof.ts +40 -0
  193. package/src/client/usage/correctionProofs.ts +40 -0
  194. package/src/client/usage/correctionProvider.ts +326 -0
  195. package/src/client/usage/correctionRead.ts +73 -0
  196. package/src/client/usage/correctionRecovery.test.ts +113 -0
  197. package/src/client/usage/correctionTerms.ts +98 -0
  198. package/src/client/usage/correctionTransport.fixtures.ts +372 -0
  199. package/src/client/usage/index.ts +19 -0
  200. package/src/client/usage/observationClient.ts +20 -6
  201. package/src/client/usage/records.ts +7 -1
  202. package/src/client/usage/summary.ts +12 -4
  203. package/src/client/usageExports.ts +19 -0
  204. package/src/component/_generated/api.ts +20 -0
  205. package/src/component/_generated/component.ts +423 -1
  206. package/src/component/accountClosure/mutations.ts +17 -0
  207. package/src/component/schema.ts +14 -0
  208. package/src/component/usage/allowance.test.ts +435 -0
  209. package/src/component/usage/mutations.ts +13 -0
  210. package/src/component/usage/schema.ts +6 -1
  211. package/src/component/usageAllowance/helpers.ts +137 -0
  212. package/src/component/usageAllowance/mutations.ts +139 -0
  213. package/src/component/usageAllowance/queries.ts +140 -0
  214. package/src/component/usageAllowance/reservations.ts +220 -0
  215. package/src/component/usageAllowance/schema.ts +37 -0
  216. package/src/component/usageCorrections/accounting.ts +79 -0
  217. package/src/component/usageCorrections/cancellation.ts +32 -0
  218. package/src/component/usageCorrections/corrections.test.ts +389 -0
  219. package/src/component/usageCorrections/helpers.ts +57 -0
  220. package/src/component/usageCorrections/invoice.ts +103 -0
  221. package/src/component/usageCorrections/mutations.ts +278 -0
  222. package/src/component/usageCorrections/queries.ts +94 -0
  223. package/src/component/usageCorrections/schema.ts +90 -0
  224. package/src/component/usageCredits/queries.ts +4 -0
  225. package/src/component/usageCredits/schema.ts +1 -0
  226. package/src/component/usageDelivery/fields.ts +1 -0
  227. package/src/component/usageDelivery/mutations.ts +8 -3
  228. package/src/component/usageDelivery/steps.ts +1 -1
  229. package/src/component/usageObservations/queries.ts +5 -2
  230. 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.
@@ -0,0 +1,217 @@
1
+ # Included usage and optional usage limits
2
+
3
+ BetterStripe supplies atomic quantity accounting for monthly included usage and
4
+ optional pay-as-you-go caps. Use native Stripe graduated prices for included
5
+ usage, provisioned by the [usage catalog](./usage-catalog.md), and enroll the
6
+ customer through [managed subscriptions](./usage-subscriptions.md). The free
7
+ first tier and original overage rate remain the billing terms. Limits control
8
+ access to work; they do not change the price or collect money.
9
+
10
+ Prepaid uses the separate [payment-backed credit APIs](./usage-credits.md).
11
+ `configureAllowance` rejects prepaid plans. No monetary wallet or extra usage
12
+ charge is created by allowance accounting.
13
+
14
+ ## Configure before accepting usage
15
+
16
+ Authenticate and authorize policy management in a host mutation. Resolve the
17
+ payer, native customer, meter and original terms on the server. Do not accept
18
+ these identities or policy edits directly from an untrusted browser.
19
+
20
+ Use a binding returned by `stripe.usage.ensureSubscription`, `observeSubscription`
21
+ or `getSubscription`. Observe the current native subscription before initializing
22
+ a renewed period. A managed subscription must be active and its period must
23
+ still be open. This works with the supported managed collection methods.
24
+
25
+ ```ts
26
+ const original = subscription.bindings[0];
27
+ await stripe.usage.configureAllowance(ctx, {
28
+ ...original,
29
+ expectedRevision: 0,
30
+ policy: {
31
+ entitled: true,
32
+ reset: "billing_period",
33
+ rollover: "none",
34
+ overage: "allow",
35
+ limit: { mode: "hard", quantity: "12000" },
36
+ },
37
+ });
38
+ ```
39
+
40
+ Configure every metered binding that needs limits. The plan supplies
41
+ `includedQuantity`, unit precision and the original decimal overage rate.
42
+ `limit.quantity` is total usage for the period, including free units, expressed as
43
+ an exact decimal string in that unit. A hard limit of 12000 with 10000 included
44
+ units permits 2000 billable overage units. `overage: "reject"` additionally caps
45
+ usage at the included quantity. The smaller hard cap wins.
46
+
47
+ `limit: { mode: "soft", quantity: "12000" }` reports a warning at the threshold
48
+ and continues accepting usage. `limit: { mode: "none" }` has no separate usage
49
+ threshold. `entitled: false` rejects new reservations. Pay-as-you-go supports
50
+ these optional total-usage thresholds with `overage: "allow"`; it has no free
51
+ included units. Prepaid insufficient-balance enforcement comes from paid grants.
52
+
53
+ This native v1 policy explicitly resets at the original monthly billing-period
54
+ boundary and has no rollover. Carrying free units or resetting on a calendar
55
+ month would disagree with the native price and is rejected. Change billing terms
56
+ at a verified future period, using the subscription lifecycle. Do not mutate an
57
+ existing period's free tier, price, currency, version or units.
58
+
59
+ Setup over existing unaccounted period usage is rejected. Reconcile that history
60
+ and enable the policy at the next verified period rather than granting a fresh
61
+ allowance over work already accepted. An overlapping period, new subscription or
62
+ changed binding cannot reset an existing counter. Once a native payer/meter or
63
+ logical scope has a policy, recording usage without a matching policy reservation
64
+ remains blocked at renewal until the next period is configured.
65
+
66
+ ## Reserve before work, then commit with the ledger
67
+
68
+ Authorize the real activity in the host. Use its stable business identity for
69
+ `sourceEventId`, original occurrence time, and exact unit quantity. Reserve the
70
+ maximum quantity the work is allowed to perform. Commit that exact quantity;
71
+ changing it requires a new, explicitly authorized operation.
72
+
73
+ ```ts
74
+ const event = {
75
+ scope: original.scope,
76
+ binding: original.binding,
77
+ sourceEventId: activity.id,
78
+ quantity: "5",
79
+ occurredAt: activity.occurredAt,
80
+ };
81
+ const reservation = await stripe.usage.reserveAllowance(ctx, {
82
+ event,
83
+ subscription: original.subscription,
84
+ });
85
+ if (reservation.state === "denied") {
86
+ return { allowed: false, reason: reservation.reason };
87
+ }
88
+ if (reservation.state === "released") {
89
+ return { allowed: false, reason: "work_previously_released" };
90
+ }
91
+ if (reservation.state === "reserved") {
92
+ // The worker must deduplicate real work using activity.id across retries.
93
+ await performIdempotentWork(activity.id);
94
+ }
95
+ const receipt = await stripe.usage.record(ctx, {
96
+ event,
97
+ subscription: original.subscription,
98
+ reservationId: reservation.reservationId,
99
+ });
100
+ ```
101
+
102
+ Reserve and record must run from a context that supports component mutations.
103
+ External work belongs in an action or durable worker. A query used to render a
104
+ button never grants permission to run work. Concurrent reservations update the
105
+ same counter transactionally, and hard-cap decisions include both consumed and
106
+ reserved units. Ledger acceptance commits the reservation, immutable event and
107
+ outbox in one transaction. A failed transaction rolls all of them back.
108
+
109
+ Exact reservation and record retries return their prior result. Changed quantity,
110
+ price, subscription, occurrence time or source identity conflicts. A committed
111
+ reservation must not run work again. A released reservation stays released.
112
+ Historical source identities remain reserved across periods and subscriptions.
113
+
114
+ A timeout or unknown worker result retains reserved capacity. Confirm work did
115
+ not happen before releasing it. There is no automatic lease expiry that could
116
+ admit a second job while the original job still runs.
117
+
118
+ ```ts
119
+ await stripe.usage.releaseAllowance(ctx, {
120
+ scope: original.scope,
121
+ reservationId: reservation.reservationId,
122
+ reason: "work_failed", // or "abandoned_before_work"
123
+ });
124
+ ```
125
+
126
+ Release retries with the same reason are idempotent. A different reason conflicts.
127
+ Committed usage cannot be released. Delivery rejection, uncertainty, delayed
128
+ native aggregates or an unpaid invoice do not restore allowance. Corrections
129
+ retain the original event and terms and require an auditable correction outcome;
130
+ never decrement counters based on an invoice preview or an optimistic UI action.
131
+ See the [auditable correction workflow](./usage-corrections.md).
132
+
133
+ ## Edit access policy without resetting consumption
134
+
135
+ Read `getAllowanceStatus` and pass its `revision` as `expectedRevision` when changing
136
+ limits or entitlement. An exact policy replay returns the current revision;
137
+ a different policy with a stale revision fails. Cap and entitlement changes keep
138
+ all consumed and reserved units. Lowering a cap below those units denies new work.
139
+ Already reserved work retains its original authorization and can commit once,
140
+ even after entitlement is disabled or the cap is lowered. To cancel that work,
141
+ stop the worker and explicitly release its uncommitted reservation.
142
+
143
+ ```ts
144
+ const status = await stripe.usage.getAllowanceStatus(ctx, original);
145
+ if (status) {
146
+ await stripe.usage.configureAllowance(ctx, {
147
+ ...original,
148
+ expectedRevision: status.revision,
149
+ policy: { ...status.policy, entitled: false },
150
+ });
151
+ }
152
+ ```
153
+
154
+ A new verified billing period gets a new counter. Historical counters and
155
+ reservations remain readable. A late reservation from a closing or old period
156
+ cannot become current-period usage. New acceptance closes 60 seconds before the
157
+ native period ends, matching the managed delivery lifecycle.
158
+
159
+ ## Read status, evidence and reconciliation
160
+
161
+ `getAllowanceStatus(ctx, original)` returns `null` for an unavailable exact binding.
162
+ Otherwise it returns revision, observation time, period, policy, consumed and
163
+ reserved quantities, free units remaining after reservations, committed billable
164
+ overage, soft-limit state and remaining hard-cap capacity. `accepting` also
165
+ checks the current stored managed enrollment and closes on retirement or expiry.
166
+ It is a display observation; only a successful atomic reservation permits work.
167
+ Refresh the managed subscription through its native observation API when provider
168
+ state changes. A cached database view cannot prove a newly changed native state.
169
+
170
+ `committedEstimate` prices only committed usage. `projectedEstimate` also includes
171
+ reservations. Both use the original rate and exact decimal minor currency units.
172
+ They exclude fixed fees, tax, discounts and payment collection. The result always
173
+ reports `cashCollection: "none"`. Do not render estimates as available money,
174
+ paid invoices or seller/affiliate earnings.
175
+
176
+ ```ts
177
+ const local = await stripe.usage.reconcileAllowance(ctx, original);
178
+ const page = await stripe.usage.readAllowanceHistory(ctx, {
179
+ ...original,
180
+ limit: 25,
181
+ cursor: null,
182
+ });
183
+ ```
184
+
185
+ The history reader pages immutable policy, reservation, commit and release evidence
186
+ for the exact binding. Limits are 1–100 rows, with a returned cursor. Evidence is
187
+ retained, with a quota of 100000 history records per period. Accounting mutations
188
+ fail atomically when that retained quota is exhausted.
189
+
190
+ `reconcileAllowance` compares the counter with immutable accepted events and open
191
+ reservations. It returns `matched` only with complete matching local evidence.
192
+ The read is bounded to 500 events and 500 open reservations; larger or conflicting
193
+ histories return `held`, never a false match. It does not repair or restore units.
194
+ Stop new work and investigate a held result through the paged ledger/history
195
+ readers. Native quantity/invoice comparison remains available through
196
+ `getReconciliation`, `getProviderUsage` and `readInvoiceUsage`; those observations do
197
+ not enforce or reset access caps. A native invoice's payment status cannot prove
198
+ new cash collection on its own.
199
+
200
+ ## Developer and agent setup checklist
201
+
202
+ 1. Use an ordinary Stripe test sandbox. No Metronome account or token is needed.
203
+ 2. Follow [sandbox setup](./metering-setup.md), then provision the native catalog
204
+ and managed subscription with the package APIs. Keep secret keys server-side.
205
+ 3. Select the included plan or an optional pay-as-you-go limit. Choose explicit
206
+ entitlement, reset, no-rollover, overage and hard/soft threshold policy.
207
+ 4. Configure each current binding before accepting usage. Observe native renewal,
208
+ then initialize the next period before running more work.
209
+ 5. Authorize activities, reserve, perform idempotent work and record the same
210
+ original event. Start the existing durable delivery workflow for its outbox.
211
+ 6. Expose scoped status/history queries and authorized policy commands. Handle
212
+ denied, released, committed and unknown work states explicitly.
213
+ 7. Test competing last-capacity requests, replay, failed work, policy revision
214
+ conflicts, renewal and stale UI. Compare accounting and native observations
215
+ without turning lag into permission to grant additional units.
216
+
217
+ Native pricing reference: [Stripe usage-based pricing models](https://docs.stripe.com/billing/subscriptions/usage-based/pricing-models).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.57.0",
3
+ "version": "0.59.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -107,6 +107,8 @@
107
107
  "docs/usage-observations.md",
108
108
  "docs/usage-subscriptions.md",
109
109
  "docs/usage-credits.md",
110
+ "docs/usage-limits.md",
111
+ "docs/usage-corrections.md",
110
112
  "docs/evidence/native-metering"
111
113
  ],
112
114
  "scripts": {
@@ -0,0 +1,93 @@
1
+ import { afterEach, expect, it, vi } from "vitest";
2
+ import { BetterStripe } from "../index.js";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import { fixture } from "./subscriptionTransport.fixtures.js";
5
+ import { request } from "./subscription.fixtures.js";
6
+ import { ensureManagedSubscription } from "./subscriptionProvider.js";
7
+ afterEach(() => vi.useRealTimers());
8
+ it("configures, reserves, reads and releases through the public component facade", async () => {
9
+ vi.useFakeTimers();
10
+ vi.setSystemTime(700000);
11
+ const f = fixture(),
12
+ client = new BetterStripe(f.component);
13
+ const view = await f.t.action((ctx) =>
14
+ ensureManagedSubscription(f.stripe, f.component, ctx as RunCtx, request),
15
+ );
16
+ const original = view.bindings[0];
17
+ const policy = {
18
+ reset: "billing_period",
19
+ rollover: "none",
20
+ entitled: true,
21
+ overage: "reject",
22
+ limit: { mode: "none" },
23
+ } as const;
24
+ expect(
25
+ await f.t.action((ctx) =>
26
+ client.usage.configureAllowance(ctx as RunCtx, {
27
+ ...original,
28
+ policy,
29
+ expectedRevision: 0,
30
+ }),
31
+ ),
32
+ ).toEqual({ revision: 1 });
33
+ const event = {
34
+ scope: original.scope,
35
+ binding: original.binding,
36
+ sourceEventId: "work1",
37
+ quantity: "6",
38
+ occurredAt: 700,
39
+ };
40
+ const reservation = await f.t.action((ctx) =>
41
+ client.usage.reserveAllowance(ctx as RunCtx, {
42
+ event,
43
+ subscription: original.subscription,
44
+ }),
45
+ );
46
+ expect(reservation.state).toBe("reserved");
47
+ expect(
48
+ await f.t.query((ctx) =>
49
+ client.usage.getAllowanceStatus(ctx as RunCtx, original),
50
+ ),
51
+ ).toMatchObject({
52
+ consumedQuantity: "0",
53
+ reservedQuantity: "6",
54
+ hardLimitRemainingQuantity: "4",
55
+ });
56
+ const denied = await f.t.action((ctx) =>
57
+ client.usage.reserveAllowance(ctx as RunCtx, {
58
+ event: { ...event, sourceEventId: "work2" },
59
+ subscription: original.subscription,
60
+ }),
61
+ );
62
+ expect(denied).toMatchObject({ state: "denied", reason: "hard_limit" });
63
+ if (reservation.state === "denied") throw new Error("Unexpected denial");
64
+ await f.t.action((ctx) =>
65
+ client.usage.releaseAllowance(ctx as RunCtx, {
66
+ scope: original.scope,
67
+ reservationId: reservation.reservationId,
68
+ reason: "work_failed",
69
+ }),
70
+ );
71
+ expect(
72
+ await f.t.query((ctx) =>
73
+ client.usage.reconcileAllowance(ctx as RunCtx, original),
74
+ ),
75
+ ).toMatchObject({ status: "matched", repaired: false });
76
+ const page = await f.t.query((ctx) =>
77
+ client.usage.readAllowanceHistory(ctx as RunCtx, {
78
+ ...original,
79
+ limit: 1,
80
+ cursor: null,
81
+ }),
82
+ );
83
+ expect(page.records).toHaveLength(1);
84
+ expect(page.cursor).not.toBeNull();
85
+ expect(
86
+ await f.t.query((ctx) =>
87
+ client.usage.getAllowanceStatus(ctx as RunCtx, {
88
+ ...original,
89
+ scope: { ...original.scope, customerAccount: "acct_other" },
90
+ }),
91
+ ),
92
+ ).toBeNull();
93
+ });