@fantastic.dev/better-stripe 0.60.0 → 0.61.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 (193) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +5 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +26 -6
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +13 -3
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +26 -6
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +13 -3
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/usage/creditCapacity.d.ts.map +1 -1
  12. package/dist/client/usage/creditCapacity.js +7 -1
  13. package/dist/client/usage/creditCapacity.js.map +1 -1
  14. package/dist/client/usage/creditClient.d.ts +3 -0
  15. package/dist/client/usage/creditClient.d.ts.map +1 -1
  16. package/dist/client/usage/creditDelivery.d.ts.map +1 -1
  17. package/dist/client/usage/creditDelivery.js +4 -1
  18. package/dist/client/usage/creditDelivery.js.map +1 -1
  19. package/dist/client/usage/creditLifecycle.d.ts.map +1 -1
  20. package/dist/client/usage/creditLifecycle.js +2 -1
  21. package/dist/client/usage/creditLifecycle.js.map +1 -1
  22. package/dist/client/usage/creditNative.d.ts +3 -0
  23. package/dist/client/usage/creditNative.d.ts.map +1 -1
  24. package/dist/client/usage/creditNative.js +3 -0
  25. package/dist/client/usage/creditNative.js.map +1 -1
  26. package/dist/client/usage/creditProvider.d.ts.map +1 -1
  27. package/dist/client/usage/creditProvider.js +2 -1
  28. package/dist/client/usage/creditProvider.js.map +1 -1
  29. package/dist/client/usage/creditRead.d.ts +1 -0
  30. package/dist/client/usage/creditRead.d.ts.map +1 -1
  31. package/dist/client/usage/creditReconciliation.d.ts.map +1 -1
  32. package/dist/client/usage/creditReconciliation.js +11 -3
  33. package/dist/client/usage/creditReconciliation.js.map +1 -1
  34. package/dist/client/usage/creditSettlement.fixtures.d.ts +1 -0
  35. package/dist/client/usage/creditSettlement.fixtures.d.ts.map +1 -1
  36. package/dist/client/usage/creditTransport.fixtures.d.ts +1 -0
  37. package/dist/client/usage/creditTransport.fixtures.d.ts.map +1 -1
  38. package/dist/client/usage/creditTransport.fixtures.js +2 -1
  39. package/dist/client/usage/creditTransport.fixtures.js.map +1 -1
  40. package/dist/client/usage/index.d.ts +2 -0
  41. package/dist/client/usage/index.d.ts.map +1 -1
  42. package/dist/client/usage/subscriptionCancellation.d.ts.map +1 -1
  43. package/dist/client/usage/subscriptionCancellation.js +3 -2
  44. package/dist/client/usage/subscriptionCancellation.js.map +1 -1
  45. package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -1
  46. package/dist/client/usage/subscriptionCheckout.js +3 -2
  47. package/dist/client/usage/subscriptionCheckout.js.map +1 -1
  48. package/dist/client/usage/subscriptionLifecycle.d.ts +1 -0
  49. package/dist/client/usage/subscriptionLifecycle.d.ts.map +1 -1
  50. package/dist/client/usage/subscriptionLifecycle.js +3 -2
  51. package/dist/client/usage/subscriptionLifecycle.js.map +1 -1
  52. package/dist/client/usage/subscriptionProvider.d.ts +2 -0
  53. package/dist/client/usage/subscriptionProvider.d.ts.map +1 -1
  54. package/dist/client/usage/subscriptionProvider.js +9 -2
  55. package/dist/client/usage/subscriptionProvider.js.map +1 -1
  56. package/dist/component/_generated/component.d.ts +21 -0
  57. package/dist/component/_generated/component.d.ts.map +1 -1
  58. package/dist/component/earnings/triggers.d.ts +16 -6
  59. package/dist/component/earnings/triggers.d.ts.map +1 -1
  60. package/dist/component/schema.d.ts +13 -3
  61. package/dist/component/usage/allowance.fixtures.d.ts +4212 -0
  62. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -0
  63. package/dist/component/usage/allowance.fixtures.js +67 -0
  64. package/dist/component/usage/allowance.fixtures.js.map +1 -0
  65. package/dist/component/usageCredits/accounting.fixtures.d.ts +4235 -0
  66. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -0
  67. package/dist/component/usageCredits/accounting.fixtures.js +89 -0
  68. package/dist/component/usageCredits/accounting.fixtures.js.map +1 -0
  69. package/dist/component/usageCredits/helpers.d.ts +7 -0
  70. package/dist/component/usageCredits/helpers.d.ts.map +1 -1
  71. package/dist/component/usageCredits/helpers.js +5 -0
  72. package/dist/component/usageCredits/helpers.js.map +1 -1
  73. package/dist/component/usageCredits/mutations.d.ts +6 -0
  74. package/dist/component/usageCredits/mutations.d.ts.map +1 -1
  75. package/dist/component/usageCredits/mutations.js +70 -7
  76. package/dist/component/usageCredits/mutations.js.map +1 -1
  77. package/dist/component/usageCredits/purchase.d.ts +1 -0
  78. package/dist/component/usageCredits/purchase.d.ts.map +1 -1
  79. package/dist/component/usageCredits/queries.d.ts +10 -0
  80. package/dist/component/usageCredits/queries.d.ts.map +1 -1
  81. package/dist/component/usageCredits/schema.d.ts +24 -4
  82. package/dist/component/usageCredits/schema.d.ts.map +1 -1
  83. package/dist/component/usageCredits/schema.js +4 -0
  84. package/dist/component/usageCredits/schema.js.map +1 -1
  85. package/dist/component/usageSubscriptions/history.d.ts.map +1 -1
  86. package/dist/component/usageSubscriptions/history.js +3 -1
  87. package/dist/component/usageSubscriptions/history.js.map +1 -1
  88. package/dist/component/usageSubscriptions/mutations.d.ts +5 -0
  89. package/dist/component/usageSubscriptions/mutations.d.ts.map +1 -1
  90. package/dist/component/usageSubscriptions/mutations.js +19 -0
  91. package/dist/component/usageSubscriptions/mutations.js.map +1 -1
  92. package/dist/component/usageSubscriptions/queries.d.ts +2 -0
  93. package/dist/component/usageSubscriptions/queries.d.ts.map +1 -1
  94. package/dist/component/usageSubscriptions/schema.d.ts +7 -2
  95. package/dist/component/usageSubscriptions/schema.d.ts.map +1 -1
  96. package/dist/component/usageSubscriptions/schema.js +1 -0
  97. package/dist/component/usageSubscriptions/schema.js.map +1 -1
  98. package/dist/react/index.d.ts +12 -0
  99. package/dist/react/index.d.ts.map +1 -1
  100. package/dist/react/index.js +7 -0
  101. package/dist/react/index.js.map +1 -1
  102. package/dist/react/workflows/Pagination.d.ts +1 -0
  103. package/dist/react/workflows/Pagination.d.ts.map +1 -1
  104. package/dist/react/workflows/Pagination.js +1 -0
  105. package/dist/react/workflows/Pagination.js.map +1 -1
  106. package/dist/react/workflows/Usage.fixtures.d.ts +17 -0
  107. package/dist/react/workflows/Usage.fixtures.d.ts.map +1 -0
  108. package/dist/react/workflows/Usage.fixtures.js +79 -0
  109. package/dist/react/workflows/Usage.fixtures.js.map +1 -0
  110. package/dist/react/workflows/Usage.types.d.ts +25 -0
  111. package/dist/react/workflows/Usage.types.d.ts.map +1 -0
  112. package/dist/react/workflows/Usage.types.js +11 -0
  113. package/dist/react/workflows/Usage.types.js.map +1 -0
  114. package/dist/react/workflows/UsageAllowance.d.ts +14 -0
  115. package/dist/react/workflows/UsageAllowance.d.ts.map +1 -0
  116. package/dist/react/workflows/UsageAllowance.js +21 -0
  117. package/dist/react/workflows/UsageAllowance.js.map +1 -0
  118. package/dist/react/workflows/UsageBilling.d.ts +20 -0
  119. package/dist/react/workflows/UsageBilling.d.ts.map +1 -0
  120. package/dist/react/workflows/UsageBilling.js +40 -0
  121. package/dist/react/workflows/UsageBilling.js.map +1 -0
  122. package/dist/react/workflows/UsageCredits.d.ts +14 -0
  123. package/dist/react/workflows/UsageCredits.d.ts.map +1 -0
  124. package/dist/react/workflows/UsageCredits.js +25 -0
  125. package/dist/react/workflows/UsageCredits.js.map +1 -0
  126. package/dist/react/workflows/UsageHistory.d.ts +40 -0
  127. package/dist/react/workflows/UsageHistory.d.ts.map +1 -0
  128. package/dist/react/workflows/UsageHistory.js +74 -0
  129. package/dist/react/workflows/UsageHistory.js.map +1 -0
  130. package/dist/react/workflows/UsageSummary.d.ts +19 -0
  131. package/dist/react/workflows/UsageSummary.d.ts.map +1 -0
  132. package/dist/react/workflows/UsageSummary.js +54 -0
  133. package/dist/react/workflows/UsageSummary.js.map +1 -0
  134. package/dist/react/workflows/usage-format.d.ts +11 -0
  135. package/dist/react/workflows/usage-format.d.ts.map +1 -0
  136. package/dist/react/workflows/usage-format.js +43 -0
  137. package/dist/react/workflows/usage-format.js.map +1 -0
  138. package/dist/react/workflows/usage-scope.d.ts +5 -0
  139. package/dist/react/workflows/usage-scope.d.ts.map +1 -0
  140. package/dist/react/workflows/usage-scope.js +26 -0
  141. package/dist/react/workflows/usage-scope.js.map +1 -0
  142. package/docs/README.md +4 -0
  143. package/docs/react-api.md +4 -0
  144. package/docs/usage-credits.md +6 -1
  145. package/docs/usage-react.md +182 -0
  146. package/docs/usage-security.md +130 -0
  147. package/package.json +3 -1
  148. package/src/client/usage/creditBackingIsolation.test.ts +110 -0
  149. package/src/client/usage/creditCapacity.test.ts +80 -1
  150. package/src/client/usage/creditCapacity.ts +10 -1
  151. package/src/client/usage/creditDelivery.ts +4 -0
  152. package/src/client/usage/creditLifecycle.ts +2 -0
  153. package/src/client/usage/creditNative.ts +5 -0
  154. package/src/client/usage/creditProofBounds.test.ts +187 -0
  155. package/src/client/usage/creditProvider.test.ts +74 -0
  156. package/src/client/usage/creditProvider.ts +2 -0
  157. package/src/client/usage/creditReconciliation.ts +18 -3
  158. package/src/client/usage/creditTransport.fixtures.ts +2 -1
  159. package/src/client/usage/index.ts +3 -0
  160. package/src/client/usage/subscriptionCancellation.ts +3 -2
  161. package/src/client/usage/subscriptionCheckout.ts +7 -2
  162. package/src/client/usage/subscriptionClient.test.ts +60 -1
  163. package/src/client/usage/subscriptionLifecycle.ts +3 -2
  164. package/src/client/usage/subscriptionProvider.ts +27 -3
  165. package/src/component/_generated/component.ts +40 -1
  166. package/src/component/usage/allowance.fixtures.ts +77 -0
  167. package/src/component/usage/allowance.test.ts +3 -66
  168. package/src/component/usage/allowanceBounds.test.ts +79 -0
  169. package/src/component/usage/historyIsolation.test.ts +124 -0
  170. package/src/component/usageCredits/accounting.fixtures.ts +96 -0
  171. package/src/component/usageCredits/accounting.test.ts +176 -82
  172. package/src/component/usageCredits/freshness.test.ts +33 -0
  173. package/src/component/usageCredits/helpers.ts +8 -0
  174. package/src/component/usageCredits/mutations.ts +83 -5
  175. package/src/component/usageCredits/quotas.test.ts +63 -0
  176. package/src/component/usageCredits/schema.ts +10 -0
  177. package/src/component/usageSubscriptions/history.test.ts +57 -0
  178. package/src/component/usageSubscriptions/history.ts +3 -1
  179. package/src/component/usageSubscriptions/mutations.ts +23 -0
  180. package/src/component/usageSubscriptions/schema.ts +1 -0
  181. package/src/react/index.ts +20 -0
  182. package/src/react/workflows/Pagination.tsx +2 -0
  183. package/src/react/workflows/Usage.fixtures.ts +88 -0
  184. package/src/react/workflows/Usage.test.tsx +373 -0
  185. package/src/react/workflows/Usage.types.ts +39 -0
  186. package/src/react/workflows/UsageAllowance.tsx +114 -0
  187. package/src/react/workflows/UsageBilling.tsx +90 -0
  188. package/src/react/workflows/UsageCredits.tsx +112 -0
  189. package/src/react/workflows/UsageHistory.test.tsx +206 -0
  190. package/src/react/workflows/UsageHistory.tsx +154 -0
  191. package/src/react/workflows/UsageSummary.tsx +204 -0
  192. package/src/react/workflows/usage-format.ts +48 -0
  193. package/src/react/workflows/usage-scope.ts +42 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usage-format.js","sourceRoot":"","sources":["../../../src/react/workflows/usage-format.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,5 @@
1
+ import type { UsageBillingSnapshot, UsageViewScope } from "./Usage.types.js";
2
+ import type { UsageLocalSummary } from "../../client/usage/summary.js";
3
+ export declare function usageSummaryMatches(scope: UsageViewScope, value: UsageLocalSummary): boolean;
4
+ export declare function usageSnapshotMatches(scope: UsageViewScope, value: UsageBillingSnapshot): boolean;
5
+ //# sourceMappingURL=usage-scope.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usage-scope.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/usage-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,iBAAiB,WAczB;AACD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,oBAAoB,WAoB5B"}
@@ -0,0 +1,26 @@
1
+ export function usageSummaryMatches(scope, value) {
2
+ return (value.period.start === scope.period.start &&
3
+ value.period.end === scope.period.end &&
4
+ value.groups.every((group) => group.binding.plan.rate.currency.toLowerCase() ===
5
+ scope.currency.toLowerCase() &&
6
+ (group.estimate.status !== "available" ||
7
+ group.estimate.value.currency.toLowerCase() ===
8
+ scope.currency.toLowerCase())));
9
+ }
10
+ export function usageSnapshotMatches(scope, value) {
11
+ const periodMatches = (period) => period.start === scope.period.start && period.end === scope.period.end;
12
+ const currencyMatches = (currency) => currency.toLowerCase() === scope.currency.toLowerCase();
13
+ return ((value.summary.status !== "available" ||
14
+ usageSummaryMatches(scope, value.summary.value)) &&
15
+ (value.provider?.status !== "available" ||
16
+ periodMatches(value.provider.value.period)) &&
17
+ (value.allowance?.status !== "available" ||
18
+ !value.allowance.value ||
19
+ (periodMatches(value.allowance.value.period) &&
20
+ currencyMatches(value.allowance.value.committedEstimate.currency) &&
21
+ currencyMatches(value.allowance.value.projectedEstimate.currency))) &&
22
+ (value.credits?.status !== "available" ||
23
+ currencyMatches(value.credits.value.currency)) &&
24
+ (!value.purchase || currencyMatches(value.purchase.currency)));
25
+ }
26
+ //# sourceMappingURL=usage-scope.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usage-scope.js","sourceRoot":"","sources":["../../../src/react/workflows/usage-scope.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,mBAAmB,CACjC,KAAqB,EACrB,KAAwB;IAExB,OAAO,CACL,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,CAAC,KAAK;QACzC,KAAK,CAAC,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,MAAM,CAAC,GAAG;QACrC,KAAK,CAAC,MAAM,CAAC,KAAK,CAChB,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE;YAC5C,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE;YAC9B,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,WAAW;gBACpC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE;oBACzC,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CACpC,CACF,CAAC;AACJ,CAAC;AACD,MAAM,UAAU,oBAAoB,CAClC,KAAqB,EACrB,KAA2B;IAE3B,MAAM,aAAa,GAAG,CAAC,MAAsC,EAAE,EAAE,CAC/D,MAAM,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;IACzE,MAAM,eAAe,GAAG,CAAC,QAAgB,EAAE,EAAE,CAC3C,QAAQ,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IAC1D,OAAO,CACL,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,WAAW;QACnC,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAClD,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,KAAK,WAAW;YACrC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7C,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,KAAK,WAAW;YACtC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK;YACtB,CAAC,aAAa,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;gBAC1C,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,QAAQ,CAAC;gBACjE,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvE,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,KAAK,WAAW;YACpC,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChD,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAC9D,CAAC;AACJ,CAAC"}
package/docs/README.md CHANGED
@@ -74,3 +74,7 @@ Start with the [native Stripe setup guide](metering-setup.md), then read the
74
74
  - [Usage corrections](./usage-corrections.md) covers native cancellation, quantity restoration and verified invoice adjustments.
75
75
 
76
76
  - [Native usage settlement](./usage-settlement.md) covers original paid invoices, issuer-service credit purchases and affiliate recovery.
77
+
78
+ - [Metered billing authorization](./usage-security.md) covers server ownership, work deduplication, native proof limits and retained recovery liabilities.
79
+
80
+ - [Reusable metered billing UI](usage-react.md) covers all three models, render props, authenticated adapters and bounded history.
package/docs/react-api.md CHANGED
@@ -282,3 +282,7 @@ function SellerDisputes({ stripeAccountId }: { stripeAccountId: string }) {
282
282
  );
283
283
  }
284
284
  ```
285
+
286
+ ## Metered billing
287
+
288
+ See [reusable metered billing UI](usage-react.md) for `UsageBilling`, `UsageSummary`, `UsageAllowance`, `UsageCredits`, `UsageHistory` and their hooks.
@@ -236,7 +236,9 @@ It does not silently restore units, refund twice or settle consumption as a sale
236
236
 
237
237
  Close the managed subscription through its normal usage closeout first.
238
238
  closeCreditAccount requires no pending purchases/reservations, complete native
239
- zero-balance evidence and reconciled consumption. Unspent paid credits require a
239
+ zero-balance evidence no older than 60 seconds and reconciled consumption.
240
+ An unresolved dispute or recovery freeze prevents closure even after an earlier
241
+ zero-balance proof. Unspent paid credits require a
240
242
  verified full refund unless they expired under their original configured terms.
241
243
  The general account-closure API checks open prepaid ledgers for payer and realm.
242
244
 
@@ -253,3 +255,6 @@ required. Keep secrets in the runtime environment and follow the
253
255
  demonstrates purchased native credit covering usage without a second usage
254
256
  charge. Clock advancement is not ingestion proof. Observe the meter aggregate
255
257
  before advancing, then inspect the finalized invoice.
258
+
259
+ See [metered billing authorization](usage-security.md) for host ownership checks,
260
+ work deduplication, native Customer isolation and bounded recovery evidence.
@@ -0,0 +1,182 @@
1
+ # Reusable metered billing UI
2
+
3
+ Import the metered views from `@fantastic.dev/better-stripe/react`. They use the
4
+ package's native usage observations and component accounting for all three models:
5
+ pay as you go, included monthly usage with overages, and prepaid credits.
6
+
7
+ The defaults are unstyled semantic HTML. Each view supports render props and a
8
+ `className`; stable `data-better-stripe` attributes identify its root. No Stripe
9
+ embedded metering component or browser provider credential is required.
10
+
11
+ ## One workflow, either host transport
12
+
13
+ `UsageBilling` and `useUsageBilling` accept an authenticated asynchronous loader.
14
+ The same loader contract works with a Convex query/action client or an HTTP API.
15
+ `UsageSummary`, `UsageAllowance` and `UsageCredits` also accept observations
16
+ directly, including reactive host-query results. Both routes use the same display
17
+ components and exact decimal formatting.
18
+
19
+ ```tsx
20
+ import {
21
+ UsageBilling,
22
+ type UsageBillingSnapshot,
23
+ type UsageViewScope,
24
+ } from "@fantastic.dev/better-stripe/react";
25
+
26
+ const view: UsageViewScope = {
27
+ identityKey: authenticatedSessionKey,
28
+ accountKey: authorizedTenantKey,
29
+ meterKey: originalMeterAndPriceVersionKey,
30
+ period: verifiedBillingPeriod,
31
+ currency: originalCurrency,
32
+ };
33
+
34
+ async function loadUsage(scope: UsageViewScope): Promise<UsageBillingSnapshot> {
35
+ const response = await fetch("/api/billing/usage", {
36
+ method: "POST",
37
+ credentials: "same-origin",
38
+ headers: { "content-type": "application/json" },
39
+ body: JSON.stringify({
40
+ meterKey: scope.meterKey,
41
+ period: scope.period,
42
+ currency: scope.currency,
43
+ }),
44
+ });
45
+ if (!response.ok) throw new Error("Usage read unavailable");
46
+ return response.json();
47
+ }
48
+
49
+ <UsageBilling scope={view} unit="API calls" load={loadUsage} />;
50
+ ```
51
+
52
+ The scope is a cache identity, not authorization. Update `identityKey` on logout,
53
+ login or membership changes. Include original plan/price version in `meterKey`.
54
+ Changing identity, tenant, meter/version, period or currency resets the workflow
55
+ and its history navigation. Responses from the previous scope cannot replace the
56
+ current view. Period/currency mismatches in returned snapshots fail closed.
57
+
58
+ Authenticate every host read, refresh and page. Resolve the current tenant and
59
+ original native binding on the server. Do not trust a browser-selected payer,
60
+ price, subscription, secret or scope claim. See [authorization](usage-security.md).
61
+
62
+ The host loader should assemble `UsageBillingSnapshot` from existing package APIs:
63
+
64
+ | Snapshot field | Authenticated server source |
65
+ | ------------------- | ----------------------------------------------------------------------------------------- |
66
+ | `summary` | `stripe.usage.getSummary`, wrapped as `available` with its `observedAt` |
67
+ | `provider` | `stripe.usage.getProviderUsage`, or a fresh authorized `observeProviderUsage` action |
68
+ | `allowance` | `stripe.usage.getAllowanceStatus` for an included model or a configured pay-as-you-go cap |
69
+ | `credits` | `stripe.usage.getCreditBalance` for the original prepaid binding |
70
+ | `purchase` | `stripe.usage.getCreditPurchase` for the authorized original purchase ID |
71
+ | `creditApplication` | Authorized `stripe.usage.reconcileCreditPurchase` for that same original purchase |
72
+
73
+ Wrap successful allowance/credit reads in `{ status: "available", observedAt,
74
+ value }`. Preserve `null` allowance as no configured policy. Return explicit
75
+ `unavailable` or `unsupported` observations when evidence cannot be read. Include
76
+ only fields relevant to the verified model. The UI does not initiate purchases,
77
+ configure limits, run work, reconcile funds automatically or poll Stripe.
78
+
79
+ For a reactive adapter, pass the same observations to `UsageSummary`,
80
+ `UsageAllowance` and `UsageCredits`. Treat `undefined` as loading. Clear results
81
+ when the authenticated scope changes; never pass a previous query's data as the
82
+ new scope's observation. The asynchronous workflow performs this reset itself.
83
+
84
+ ## All three models and observation states
85
+
86
+ `UsageSummary` displays the original plan/version, per-meter and subscription-item
87
+ breakdown, accepted/effective/provider-accepted quantities, nonzero delivery
88
+ states and estimated charge. It preserves exact quantity strings, including
89
+ values beyond JavaScript's safe floating-point range. `formatUsageEstimate`
90
+ converts native minor-unit decimal estimates into exact major currency decimals,
91
+ including fractional cents; unsupported amounts stay unavailable.
92
+
93
+ Loading, empty, partial, unavailable and unsupported are separate states. A
94
+ complete zero-event local summary is empty. An unavailable summary is never zero.
95
+ Native stale/partial aggregates and possible ingestion delay remain visible.
96
+ Unknown/rejected/held delivery is distinct from acceptance and aggregation.
97
+ Estimates never become finalized or paid invoice amounts in these views.
98
+
99
+ `UsageAllowance` shows consumed plus reserved progress, included and remaining
100
+ units, overage, soft warnings and hard-cap observations. Its progress bar is
101
+ normalized for presentation; its accessible value text retains exact quantities.
102
+ A display is never permission to start work. Use the server's atomic reservation
103
+ API. The period is the verified managed billing period with no rollover, not a
104
+ calendar reset performed by React.
105
+
106
+ `UsageCredits` shows available, reserved, consumed, expired and frozen quantities,
107
+ purchase pending/ready/frozen/canceled status, exhaustion and native application
108
+ proof status. A frozen grant may hold units even while the overall account is
109
+ open. Pending purchase payment does not grant units. Consumption is not another
110
+ cash collection or a withdrawable balance. Pass the original currency when
111
+ presenting an application proof without a balance or purchase observation.
112
+
113
+ Refresh is explicit. Existing observations shown during refresh or a failed
114
+ refresh are marked potentially stale. Loader errors use a sanitized message.
115
+ Host adapters must also sanitize returned observation reasons and custom history
116
+ content before sending them to a browser.
117
+
118
+ ## Bounded history
119
+
120
+ `UsageHistory<Row>` and `useUsageHistory<Row>` own cursor navigation, loading,
121
+ retry, scope reset and stale-request protection. They work with event, delivery,
122
+ allowance and credit history. The host provides a row key and presentation rather
123
+ than another pagination engine.
124
+
125
+ ```tsx
126
+ import { UsageHistory } from "@fantastic.dev/better-stripe/react";
127
+ import type { UsageEventView } from "@fantastic.dev/better-stripe/usage";
128
+
129
+ <UsageHistory<UsageEventView>
130
+ scope={view}
131
+ historyKey="accepted-events"
132
+ limit={25}
133
+ load={async (scope, page) => {
134
+ // This host endpoint authenticates this request and resolves its binding.
135
+ const result = await loadAuthorizedEventPage(scope, page);
136
+ return {
137
+ status: "available",
138
+ observedAt: result.observedAt,
139
+ value: {
140
+ records: result.events,
141
+ cursor: result.cursor,
142
+ isDone: result.isDone,
143
+ },
144
+ };
145
+ }}
146
+ getKey={(row) => row.receipt.eventId}
147
+ renderRecord={(row) => (
148
+ <p>
149
+ {row.record.sourceEventId}: {row.record.quantity}{" "}
150
+ {row.record.binding.plan.unit.name}, {row.delivery}
151
+ </p>
152
+ )}
153
+ />;
154
+ ```
155
+
156
+ Use `readCreditHistory`, `readCreditGrants`, `readAllowanceHistory` or
157
+ `readDeliveryHistory` in analogous authorized loaders. The component accepts
158
+ 1–100 rows per page and opaque cursors up to 2,048 characters. Change `historyKey`
159
+ when changing reader kind, filters or transport cache semantics. Reauthorize
160
+ every page; a cursor never grants access. Partial or empty nonterminal pages do
161
+ not mean no history. Incomplete pages never establish complete totals. Missing, empty or repeated
162
+ nonterminal cursors stop forward navigation while preserving Previous and retry.
163
+
164
+ Render props receive the same hook state: data, loading/error, refresh, page,
165
+ previous/next and completeness. Native buttons support keyboard navigation;
166
+ status/alert regions announce loading and errors. Maintain these behaviors when
167
+ replacing defaults with a design system.
168
+
169
+ ## Verification
170
+
171
+ The co-located React tests exercise large exact quantities, every billing model,
172
+ loading/empty/partial/stale/unsupported states, native lag, pending and held
173
+ credits, error sanitization, retries, cursor navigation and delayed responses
174
+ after each scope field changes. The packed consumer typechecks these public
175
+ exports. The deterministic browser fixture is
176
+ `scripts/fixtures/usage-ui.html`; it uses the package components and does not call
177
+ Stripe. Its UI captures are separate from native financial acceptance.
178
+
179
+ Run `pnpm run check:all` and verify your host's authorization and native setup
180
+ using the [setup guide](metering-setup.md). Package views do not replace the
181
+ [ledger](usage-ledger.md), [allowance](usage-limits.md) or
182
+ [paid-credit](usage-credits.md) work and recovery protocols.
@@ -0,0 +1,130 @@
1
+ # Metered billing authorization and recovery
2
+
3
+ BetterStripe's component and server facade are trusted host APIs. The component
4
+ cannot authenticate your application's end user. Authenticate and authorize each
5
+ host query, mutation and action before calling `stripe.usage`, including every
6
+ history page, reconciliation, refund preparation and resume operation. The
7
+ example's demo role selector is not production authorization.
8
+
9
+ These rules apply to pay as you go, included monthly usage with overages and
10
+ payment-backed prepaid usage. Use native Stripe meters, meter events, managed
11
+ subscriptions and price-scoped paid Credit Grants. No Metronome account or
12
+ credential is required.
13
+
14
+ ## Derive identities on the server
15
+
16
+ Resolve the actor's current tenant membership and billing role from your trusted
17
+ database. Load the authorized original binding and subscription from that tenant.
18
+ Do not accept a browser-supplied payer, seller, native Customer, Stripe account,
19
+ meter, price, provider callback, secret key, plan, currency or pricing policy as
20
+ proof of ownership. Recheck membership after an identity or tenant change.
21
+
22
+ | Boundary | Host responsibility | Component/provider checks |
23
+ | ---------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
24
+ | Record, reserve and release | Verify the original business event, work owner and immutable quantity/time | Exact scope, source identity, original terms and matching reservation; atomic ledger, outbox and accounting |
25
+ | Catalog, subscription and Checkout | Authorize billing administration and resolve every meter/fixed price | Native realm/mode, Accounts v2 payer, mapped Customer, original native price and supported collection/model |
26
+ | Usage, allowance, credit and subscription reads | Authorize the current actor on every page; a cursor is not authorization | Original scope/binding and bounded indexed pages |
27
+ | Allowance configuration | Authorize entitlement and cap edits | Original binding, verified managed period and revision comparison; retained consumed/reserved units |
28
+ | Credit purchase and observation | Authorize the original purchaser and application purchase ID | Captured original payment, amount/currency/payer/Customer, realm/mode, metadata and price-scoped paid grant |
29
+ | Correction, cancellation, refund, resume and closure | Authorize the original operation and recovery role | Original event/payment/grant identities, immutable commands and retained unresolved liabilities |
30
+ | Settlement | Authorize original issuer/seller and affiliate policy | Independently verified cash source and actual processing costs; credit consumption creates no second sale |
31
+
32
+ Provider credentials belong in server environment variables or the host's secret
33
+ store. Bind an internal provider action in trusted server code. Never accept an
34
+ arbitrary callback handle from a browser. Return a purchase client secret only to
35
+ the authenticated original purchaser. Do not persist it in documents, workflow
36
+ arguments, audit history or logs. Provider errors are sanitized; do not append raw
37
+ Stripe exceptions or HTTP payloads to a browser response.
38
+
39
+ ## Reserve work before executing it
40
+
41
+ Use `reserveCredits` for prepaid work and `reserveAllowance` for a configured
42
+ allowance. Display reads such as `getCreditBalance` and `getAllowanceStatus` do not
43
+ authorize work. Competing reservations include both consumed and reserved units.
44
+ A configured allowance cannot be bypassed through ordinary `record`.
45
+
46
+ Persist a stable business event ID and deduplicate worker execution in the host.
47
+ A replay returning `committed` or `released` is not permission to run that work
48
+ again. The external worker and the component transaction are separate. A timeout
49
+ or lost response does not prove that work failed. Retain the reservation until
50
+ the original work outcome is known. Release an uncommitted reservation only after
51
+ confirmed failure or abandonment, using the original release reason.
52
+
53
+ `record` commits the exact reservation, immutable usage event, delivery outbox and
54
+ quantity counters together. Changed prepared fields, source quantity/time,
55
+ price/version, period or reservation fail rather than rewriting the original.
56
+ Provider rejection, unknown delivery and aggregation lag do not restore capacity.
57
+ Use the [correction protocol](usage-corrections.md) for accepted activity.
58
+
59
+ A cap reduction or disabled entitlement preserves previously authorized reserved
60
+ work. That work may commit once. Stop the worker and explicitly release its
61
+ uncommitted reservation if the business operation must be cancelled. Renewal
62
+ requires a current verified native managed period; calendar dates and changed
63
+ bindings cannot reset counters or reuse historical business source IDs.
64
+
65
+ ## Native observations and callbacks
66
+
67
+ Use the package's signed webhook integration and configured signing secret.
68
+ Signature verification precedes dispatch. A signed event must still match the
69
+ original native realm/mode and managed intent or delivery identity. Callback
70
+ version and attempt checks reject stale delivery results. Browser redirects,
71
+ invoice paid labels and webhook payload claims do not replace fresh payment or
72
+ invoice provenance.
73
+
74
+ Managed subscription and credit reconciliation reserve an ordered observation
75
+ before native I/O. Concurrent calls within one millisecond receive distinct
76
+ orders. Older subscription results cannot replace the retained projection, and
77
+ the returned view follows that retained projection. Historical snapshots remain
78
+ available. Older credit observations return held; conflicting tied evidence
79
+ freezes the account until fresh reconciliation and authorized resume. Refresh
80
+ failures remain unavailable or retryable instead of inventing a zero balance.
81
+
82
+ Native credit PaymentIntent, Charge, Credit Grant and balance proofs must match
83
+ both the original Accounts v2 payer and its mapped native Customer. A matching
84
+ payer alias alone cannot authorize a foreign Customer. Delivery rechecks original
85
+ paid backing before sending prepaid usage.
86
+
87
+ ## Bounded evidence and recovery
88
+
89
+ | Evidence | Limit | At or beyond an incomplete proof |
90
+ | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
91
+ | Allowance reconciliation | 500 accepted events and 500 open reservations | One over returns held without repairing counters |
92
+ | Credit reconciliation | 100 native transactions and 10 invoice application proofs per grant | Oversized transaction proof fails; excess applications remain held |
93
+ | Native credit inventory | 1,000 listed grants and 100 unexpired balance reads | Unproven remaining inventory prevents another purchase |
94
+ | Retained purchases | 1,000 per original credit binding | New purchase fails; exact retained replay still works |
95
+ | Retained audit history | 100,000 credit entries per binding; 100,000 allowance entries per period | The next transaction rolls back rather than deleting evidence |
96
+ | History reads | At most 100 rows per requested page | Request the next page with the same authorized original scope |
97
+
98
+ Refund preparation supports wholly unused reconciled original credits and returns
99
+ a required cash-refund step. Execute the existing authorized monetary refund on
100
+ the original payment with a stable idempotency key, then reconcile again.
101
+ Preparation does not itself execute the cash refund.
102
+
103
+ Disputes, partial refunds/use, pending work, incomplete proofs and external native
104
+ changes retain liabilities. Credit account closure requires a complete zero
105
+ balance observation no older than 60 seconds and reconciled consumption. An old
106
+ zero balance cannot bypass a later dispute or unresolved recovery freeze. Unspent
107
+ credits require a verified full original refund or their original configured
108
+ expiry. The general account-closure guard retains open credit accounts. Never
109
+ clear history, mint replacement credits, or create another purchase to bypass an
110
+ unknown result.
111
+
112
+ Usage estimates, included allowances and credit quantities report
113
+ `cashCollection: none`. Credit-funded invoice applications do not collect cash
114
+ again. See [credit accounting](usage-credits.md), [allowance limits](usage-limits.md)
115
+ and [original payment settlement](usage-settlement.md) for their separate proofs.
116
+
117
+ ## Audit and verification
118
+
119
+ The co-located tests exercise the Stripe SDK transport and Convex transactions:
120
+ foreign Customer payment/grant/balance proofs, reordered concurrent native reads,
121
+ disputed consumed-credit closure, exact proof and retained-quota boundaries,
122
+ reservation races, atomic rollback, forged records, cross-scope IDs and later-page
123
+ cursor reuse. Existing webhook and lifecycle tests cover signature, native
124
+ mapping and callback-version guards. Run `pnpm run check:all` before shipping a
125
+ host integration and add tests for the host's own membership and role checks.
126
+
127
+ SDK fixtures and synthetic financial receipts are not live native financial
128
+ execution. The [native feasibility evidence](evidence/native-metering/clock-finalization-run.json)
129
+ is separately labelled. Use the [sandbox setup guide](metering-setup.md) for
130
+ credentials and native verification; never use live billing to test recovery.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.60.0",
3
+ "version": "0.61.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -110,6 +110,8 @@
110
110
  "docs/usage-limits.md",
111
111
  "docs/usage-corrections.md",
112
112
  "docs/usage-settlement.md",
113
+ "docs/usage-security.md",
114
+ "docs/usage-react.md",
113
115
  "docs/evidence/native-metering"
114
116
  ],
115
117
  "scripts": {
@@ -0,0 +1,110 @@
1
+ import { afterEach, expect, it, vi } from "vitest";
2
+ import { BetterStripe } from "../index.js";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import { componentRef } from "../webhooks/helpers.js";
5
+ import { creditFixture } from "./creditTransport.fixtures.js";
6
+ import { verifyCreditDelivery } from "./creditDelivery.js";
7
+ import type { Doc } from "../../component/_generated/dataModel.js";
8
+ import type { PreparedUsageRecord } from "./records.js";
9
+ afterEach(() => vi.useRealTimers());
10
+ it("rejects a foreign mapped Customer on native grant or summary during reconciliation and delivery", async () => {
11
+ for (const condition of ["grant", "summary"]) {
12
+ const f = creditFixture(),
13
+ client = new BetterStripe(f.component),
14
+ options = { stripeSecretKey: "sk_test_credit", httpClient: f.httpClient };
15
+ const view = await f.ready();
16
+ await f.t.action((ctx) =>
17
+ client.usage.purchaseCredits(ctx as RunCtx, f.purchase, options),
18
+ );
19
+ f.state.paid = true;
20
+ await f.t.action((ctx) =>
21
+ client.usage.observeCreditPurchase(ctx as RunCtx, f.purchase, options),
22
+ );
23
+ const event = {
24
+ scope: f.purchase.scope,
25
+ binding: f.purchase.binding,
26
+ sourceEventId: "work1",
27
+ quantity: "6",
28
+ occurredAt: 700,
29
+ },
30
+ subscription = view.bindings[0].subscription;
31
+ const reservation = await f.t.action((ctx) =>
32
+ client.usage.reserveCredits(ctx as RunCtx, { event, subscription }),
33
+ );
34
+ const receipt = await f.t.action((ctx) =>
35
+ client.usage.record(ctx as RunCtx, {
36
+ event,
37
+ subscription,
38
+ reservationId: reservation.reservationId,
39
+ }),
40
+ );
41
+ if (condition === "grant") f.state.grant!.customer = "cus_other";
42
+ else f.state.summaryCustomer = "cus_other";
43
+ await expect(
44
+ f.t.action(async (ctx) => {
45
+ const saved = (await ctx.runQuery(
46
+ componentRef(f.component, "usageDelivery/queries/snapshot"),
47
+ { scope: event.scope, eventId: receipt.eventId },
48
+ )) as { event: Doc<"usageEvents"> };
49
+ await verifyCreditDelivery(
50
+ f.stripe,
51
+ f.component,
52
+ ctx as RunCtx,
53
+ saved.event,
54
+ JSON.parse(saved.event.recordJson) as PreparedUsageRecord,
55
+ );
56
+ }),
57
+ ).rejects.toThrow(/scope|identity|reconciliation/i);
58
+ await expect(
59
+ f.t.action((ctx) =>
60
+ client.usage.reconcileCreditPurchase(
61
+ ctx as RunCtx,
62
+ f.purchase,
63
+ options,
64
+ ),
65
+ ),
66
+ ).rejects.toThrow(/identity|scope|mismatch/i);
67
+ }
68
+ });
69
+
70
+ it("rechecks the original mapped Customer immediately before native grant expiration", async () => {
71
+ let checking = false,
72
+ reads = 0,
73
+ expirations = 0;
74
+ const f = creditFixture(async (input, init) => {
75
+ const path = new URL(input).pathname;
76
+ if (path.endsWith("/expire") && init?.method === "POST") expirations++;
77
+ if (
78
+ checking &&
79
+ path === "/v1/billing/credit_grants/credgr_topup1" &&
80
+ ++reads === 2
81
+ )
82
+ return new Response(
83
+ JSON.stringify({ ...f.state.grant, customer: "cus_other" }),
84
+ { headers: { "content-type": "application/json" } },
85
+ );
86
+ });
87
+ const client = new BetterStripe(f.component),
88
+ provider = { stripeSecretKey: "sk_test_credit", httpClient: f.httpClient };
89
+ await f.ready();
90
+ await f.t.action((ctx) =>
91
+ client.usage.purchaseCredits(ctx as RunCtx, f.purchase, provider),
92
+ );
93
+ f.state.paid = true;
94
+ await f.t.action((ctx) =>
95
+ client.usage.observeCreditPurchase(ctx as RunCtx, f.purchase, provider),
96
+ );
97
+ checking = true;
98
+ await expect(
99
+ f.t.action((ctx) =>
100
+ client.usage.prepareCreditRefund(ctx as RunCtx, f.purchase, provider),
101
+ ),
102
+ ).rejects.toThrow(/identity/i);
103
+ expect(reads).toBe(2);
104
+ expect(expirations).toBe(0);
105
+ expect(
106
+ await f.t.action((ctx) =>
107
+ client.usage.getCreditBalance(ctx as RunCtx, f.purchase),
108
+ ),
109
+ ).toMatchObject({ availableQuantity: "0", frozenQuantity: "10" });
110
+ });
@@ -27,7 +27,12 @@ const terms = creditPurchaseTerms({
27
27
  ownership: "issuer",
28
28
  rollover: "retain_original_terms",
29
29
  });
30
- function fixture(ledger: number, more = false, foreign = false) {
30
+ function fixture(
31
+ ledger: number,
32
+ more = false,
33
+ foreign = false,
34
+ mapped = false,
35
+ ) {
31
36
  const methods: string[] = [];
32
37
  const stripe = new Stripe("sk_test_credit_capacity", {
33
38
  httpClient: Stripe.createFetchHttpClient(async (input, init) => {
@@ -39,6 +44,7 @@ function fixture(ledger: number, more = false, foreign = false) {
39
44
  : [
40
45
  {
41
46
  id: "credgr_existing",
47
+ customer: mapped ? "cus_other" : "cus_buyer",
42
48
  customer_account: foreign ? "acct_other" : "acct_buyer",
43
49
  livemode: false,
44
50
  expires_at: null,
@@ -48,6 +54,7 @@ function fixture(ledger: number, more = false, foreign = false) {
48
54
  has_more: more,
49
55
  }
50
56
  : {
57
+ customer: mapped ? "cus_other" : "cus_buyer",
51
58
  customer_account: "acct_buyer",
52
59
  livemode: false,
53
60
  balances: [
@@ -81,3 +88,75 @@ it("permits verified depleted grants but holds incomplete or foreign native inve
81
88
  verifyNativeCreditCapacity(fixture(0, false, true).stripe, terms, 1),
82
89
  ).rejects.toThrow(/scope/i);
83
90
  });
91
+
92
+ it("rejects foreign mapped Customer inventory even when its Accounts v2 payer matches", async () => {
93
+ await expect(
94
+ verifyNativeCreditCapacity(fixture(0, false, false, true).stripe, terms, 1),
95
+ ).rejects.toThrow(/scope|customer/i);
96
+ });
97
+
98
+ function inventory(total: number, unexpired: number, size = 100) {
99
+ let lists = 0,
100
+ balances = 0;
101
+ const stripe = new Stripe("sk_test_inventory_bounds", {
102
+ maxNetworkRetries: 0,
103
+ httpClient: Stripe.createFetchHttpClient(async (input) => {
104
+ const url = new URL(String(input));
105
+ let value: unknown;
106
+ if (url.pathname.endsWith("/credit_grants")) {
107
+ lists++;
108
+ const cursor = url.searchParams.get("starting_after");
109
+ const start = cursor
110
+ ? Number(cursor.slice(cursor.lastIndexOf("_") + 1)) + 1
111
+ : 0;
112
+ const count = Math.min(size, total - start);
113
+ value = {
114
+ data: Array.from({ length: count }, (_, offset) => ({
115
+ id: `credgr_${start + offset}`,
116
+ customer_account: "acct_buyer",
117
+ customer: "cus_buyer",
118
+ livemode: false,
119
+ voided_at: start + offset < unexpired ? null : 1,
120
+ expires_at: null,
121
+ })),
122
+ has_more: start + count < total,
123
+ };
124
+ } else {
125
+ balances++;
126
+ value = {
127
+ customer_account: "acct_buyer",
128
+ customer: "cus_buyer",
129
+ livemode: false,
130
+ balances: [{ ledger_balance: { monetary: { value: 0 } } }],
131
+ };
132
+ }
133
+ return new Response(JSON.stringify(value), {
134
+ headers: { "content-type": "application/json" },
135
+ });
136
+ }),
137
+ });
138
+ return { stripe, counts: () => ({ lists, balances }) };
139
+ }
140
+ it("accepts exact native inventory and balance-read bounds and holds one-over proofs", async () => {
141
+ const exact = inventory(1000, 0);
142
+ await verifyNativeCreditCapacity(exact.stripe, terms, 1);
143
+ expect(exact.counts()).toEqual({ lists: 10, balances: 0 });
144
+ const overflow = inventory(1001, 0);
145
+ await expect(
146
+ verifyNativeCreditCapacity(overflow.stripe, terms, 1),
147
+ ).rejects.toThrow(/incomplete/i);
148
+ expect(overflow.counts()).toEqual({ lists: 10, balances: 0 });
149
+ const balances = inventory(100, 100);
150
+ await verifyNativeCreditCapacity(balances.stripe, terms, 1);
151
+ expect(balances.counts()).toEqual({ lists: 1, balances: 100 });
152
+ const excessive = inventory(101, 101);
153
+ await expect(
154
+ verifyNativeCreditCapacity(excessive.stripe, terms, 1),
155
+ ).rejects.toThrow(/budget/i);
156
+ expect(excessive.counts()).toEqual({ lists: 2, balances: 0 });
157
+ });
158
+ it("rejects native inventory pages exceeding the requested proof size", async () => {
159
+ await expect(
160
+ verifyNativeCreditCapacity(inventory(101, 0, 101).stripe, terms, 1),
161
+ ).rejects.toThrow(/budget|page|inventory/i);
162
+ });