@fantastic.dev/better-stripe 0.56.0 → 0.58.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 (248) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/README.md +5 -1
  3. package/dist/client/billing/setup-intent-read.d.ts +12 -1
  4. package/dist/client/billing/setup-intent-read.d.ts.map +1 -1
  5. package/dist/client/billing/setup-intent-read.js +13 -8
  6. package/dist/client/billing/setup-intent-read.js.map +1 -1
  7. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +366 -2
  8. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +183 -1
  10. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  11. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +366 -2
  12. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  13. package/dist/client/connect/payoutSyncTestHelpers.d.ts +183 -1
  14. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  15. package/dist/client/index.d.ts +2 -12
  16. package/dist/client/index.d.ts.map +1 -1
  17. package/dist/client/index.js +3 -20
  18. package/dist/client/index.js.map +1 -1
  19. package/dist/client/types/triggers.d.ts +3 -1
  20. package/dist/client/types/triggers.d.ts.map +1 -1
  21. package/dist/client/usage/allowanceClient.d.ts +51 -0
  22. package/dist/client/usage/allowanceClient.d.ts.map +1 -0
  23. package/dist/client/usage/allowanceClient.js +64 -0
  24. package/dist/client/usage/allowanceClient.js.map +1 -0
  25. package/dist/client/usage/allowanceTerms.d.ts +64 -0
  26. package/dist/client/usage/allowanceTerms.d.ts.map +1 -0
  27. package/dist/client/usage/allowanceTerms.js +101 -0
  28. package/dist/client/usage/allowanceTerms.js.map +1 -0
  29. package/dist/client/usage/client.d.ts +2 -2
  30. package/dist/client/usage/client.d.ts.map +1 -1
  31. package/dist/client/usage/client.js +4 -4
  32. package/dist/client/usage/client.js.map +1 -1
  33. package/dist/client/usage/creditCapacity.d.ts +5 -0
  34. package/dist/client/usage/creditCapacity.d.ts.map +1 -0
  35. package/dist/client/usage/creditCapacity.js +47 -0
  36. package/dist/client/usage/creditCapacity.js.map +1 -0
  37. package/dist/client/usage/creditClient.d.ts +104 -0
  38. package/dist/client/usage/creditClient.d.ts.map +1 -0
  39. package/dist/client/usage/creditClient.js +111 -0
  40. package/dist/client/usage/creditClient.js.map +1 -0
  41. package/dist/client/usage/creditDelivery.d.ts +6 -0
  42. package/dist/client/usage/creditDelivery.d.ts.map +1 -0
  43. package/dist/client/usage/creditDelivery.js +71 -0
  44. package/dist/client/usage/creditDelivery.js.map +1 -0
  45. package/dist/client/usage/creditInvoice.d.ts +6 -0
  46. package/dist/client/usage/creditInvoice.d.ts.map +1 -0
  47. package/dist/client/usage/creditInvoice.js +63 -0
  48. package/dist/client/usage/creditInvoice.js.map +1 -0
  49. package/dist/client/usage/creditLifecycle.d.ts +14 -0
  50. package/dist/client/usage/creditLifecycle.d.ts.map +1 -0
  51. package/dist/client/usage/creditLifecycle.js +90 -0
  52. package/dist/client/usage/creditLifecycle.js.map +1 -0
  53. package/dist/client/usage/creditNative.d.ts +20 -0
  54. package/dist/client/usage/creditNative.d.ts.map +1 -0
  55. package/dist/client/usage/creditNative.js +100 -0
  56. package/dist/client/usage/creditNative.js.map +1 -0
  57. package/dist/client/usage/creditObservation.d.ts +23 -0
  58. package/dist/client/usage/creditObservation.d.ts.map +1 -0
  59. package/dist/client/usage/creditObservation.js +54 -0
  60. package/dist/client/usage/creditObservation.js.map +1 -0
  61. package/dist/client/usage/creditProofs.d.ts +50 -0
  62. package/dist/client/usage/creditProofs.d.ts.map +1 -0
  63. package/dist/client/usage/creditProofs.js +58 -0
  64. package/dist/client/usage/creditProofs.js.map +1 -0
  65. package/dist/client/usage/creditProvider.d.ts +11 -0
  66. package/dist/client/usage/creditProvider.d.ts.map +1 -0
  67. package/dist/client/usage/creditProvider.js +195 -0
  68. package/dist/client/usage/creditProvider.js.map +1 -0
  69. package/dist/client/usage/creditRead.d.ts +47 -0
  70. package/dist/client/usage/creditRead.d.ts.map +1 -0
  71. package/dist/client/usage/creditRead.js +18 -0
  72. package/dist/client/usage/creditRead.js.map +1 -0
  73. package/dist/client/usage/creditReconciliation.d.ts +20 -0
  74. package/dist/client/usage/creditReconciliation.d.ts.map +1 -0
  75. package/dist/client/usage/creditReconciliation.js +157 -0
  76. package/dist/client/usage/creditReconciliation.js.map +1 -0
  77. package/dist/client/usage/creditTerms.d.ts +89 -0
  78. package/dist/client/usage/creditTerms.d.ts.map +1 -0
  79. package/dist/client/usage/creditTerms.js +76 -0
  80. package/dist/client/usage/creditTerms.js.map +1 -0
  81. package/dist/client/usage/creditTransport.fixtures.d.ts +101 -0
  82. package/dist/client/usage/creditTransport.fixtures.d.ts.map +1 -0
  83. package/dist/client/usage/creditTransport.fixtures.js +271 -0
  84. package/dist/client/usage/creditTransport.fixtures.js.map +1 -0
  85. package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
  86. package/dist/client/usage/deliveryProvider.js +2 -0
  87. package/dist/client/usage/deliveryProvider.js.map +1 -1
  88. package/dist/client/usage/index.d.ts +4 -0
  89. package/dist/client/usage/index.d.ts.map +1 -1
  90. package/dist/client/usage/index.js +1 -0
  91. package/dist/client/usage/index.js.map +1 -1
  92. package/dist/client/usage/records.d.ts +2 -0
  93. package/dist/client/usage/records.d.ts.map +1 -1
  94. package/dist/client/usage/records.js +22 -0
  95. package/dist/client/usage/records.js.map +1 -1
  96. package/dist/client/usage/subscriptionTransport.fixtures.d.ts +1 -1
  97. package/dist/client/usage/subscriptionTransport.fixtures.d.ts.map +1 -1
  98. package/dist/client/usage/subscriptionTransport.fixtures.js +4 -1
  99. package/dist/client/usage/subscriptionTransport.fixtures.js.map +1 -1
  100. package/dist/client/usage/summary.js +2 -2
  101. package/dist/client/usage/summary.js.map +1 -1
  102. package/dist/client/usageExports.d.ts +16 -0
  103. package/dist/client/usageExports.d.ts.map +1 -0
  104. package/dist/client/usageExports.js +3 -0
  105. package/dist/client/usageExports.js.map +1 -0
  106. package/dist/client/webhooks/subscriptionDeleted.d.ts +5 -0
  107. package/dist/client/webhooks/subscriptionDeleted.d.ts.map +1 -0
  108. package/dist/client/webhooks/subscriptionDeleted.js +34 -0
  109. package/dist/client/webhooks/subscriptionDeleted.js.map +1 -0
  110. package/dist/component/_generated/api.d.ts +18 -0
  111. package/dist/component/_generated/api.d.ts.map +1 -1
  112. package/dist/component/_generated/api.js.map +1 -1
  113. package/dist/component/_generated/component.d.ts +360 -0
  114. package/dist/component/_generated/component.d.ts.map +1 -1
  115. package/dist/component/accountClosure/mutations.d.ts.map +1 -1
  116. package/dist/component/accountClosure/mutations.js +10 -0
  117. package/dist/component/accountClosure/mutations.js.map +1 -1
  118. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  119. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  120. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  121. package/dist/component/balanceFunding/queries.d.ts +1 -1
  122. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  123. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  124. package/dist/component/earnings/triggers.d.ts +352 -18
  125. package/dist/component/earnings/triggers.d.ts.map +1 -1
  126. package/dist/component/payoutRelease/queries.d.ts +2 -2
  127. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  128. package/dist/component/schema.d.ts +183 -1
  129. package/dist/component/schema.js +8 -0
  130. package/dist/component/schema.js.map +1 -1
  131. package/dist/component/usage/mutations.d.ts.map +1 -1
  132. package/dist/component/usage/mutations.js +7 -0
  133. package/dist/component/usage/mutations.js.map +1 -1
  134. package/dist/component/usage/schema.d.ts +15 -1
  135. package/dist/component/usage/schema.d.ts.map +1 -1
  136. package/dist/component/usage/schema.js +12 -0
  137. package/dist/component/usage/schema.js.map +1 -1
  138. package/dist/component/usageAllowance/helpers.d.ts +78 -0
  139. package/dist/component/usageAllowance/helpers.d.ts.map +1 -0
  140. package/dist/component/usageAllowance/helpers.js +99 -0
  141. package/dist/component/usageAllowance/helpers.js.map +1 -0
  142. package/dist/component/usageAllowance/mutations.d.ts +37 -0
  143. package/dist/component/usageAllowance/mutations.d.ts.map +1 -0
  144. package/dist/component/usageAllowance/mutations.js +99 -0
  145. package/dist/component/usageAllowance/mutations.js.map +1 -0
  146. package/dist/component/usageAllowance/queries.d.ts +36 -0
  147. package/dist/component/usageAllowance/queries.d.ts.map +1 -0
  148. package/dist/component/usageAllowance/queries.js +113 -0
  149. package/dist/component/usageAllowance/queries.js.map +1 -0
  150. package/dist/component/usageAllowance/reservations.d.ts +25 -0
  151. package/dist/component/usageAllowance/reservations.d.ts.map +1 -0
  152. package/dist/component/usageAllowance/reservations.js +150 -0
  153. package/dist/component/usageAllowance/reservations.js.map +1 -0
  154. package/dist/component/usageAllowance/schema.d.ts +77 -0
  155. package/dist/component/usageAllowance/schema.d.ts.map +1 -0
  156. package/dist/component/usageAllowance/schema.js +32 -0
  157. package/dist/component/usageAllowance/schema.js.map +1 -0
  158. package/dist/component/usageCredits/helpers.d.ts +205 -0
  159. package/dist/component/usageCredits/helpers.d.ts.map +1 -0
  160. package/dist/component/usageCredits/helpers.js +129 -0
  161. package/dist/component/usageCredits/helpers.js.map +1 -0
  162. package/dist/component/usageCredits/mutations.d.ts +80 -0
  163. package/dist/component/usageCredits/mutations.d.ts.map +1 -0
  164. package/dist/component/usageCredits/mutations.js +344 -0
  165. package/dist/component/usageCredits/mutations.js.map +1 -0
  166. package/dist/component/usageCredits/purchase.d.ts +23 -0
  167. package/dist/component/usageCredits/purchase.d.ts.map +1 -0
  168. package/dist/component/usageCredits/purchase.js +166 -0
  169. package/dist/component/usageCredits/purchase.js.map +1 -0
  170. package/dist/component/usageCredits/queries.d.ts +184 -0
  171. package/dist/component/usageCredits/queries.d.ts.map +1 -0
  172. package/dist/component/usageCredits/queries.js +243 -0
  173. package/dist/component/usageCredits/queries.js.map +1 -0
  174. package/dist/component/usageCredits/reservations.d.ts +16 -0
  175. package/dist/component/usageCredits/reservations.d.ts.map +1 -0
  176. package/dist/component/usageCredits/reservations.js +161 -0
  177. package/dist/component/usageCredits/reservations.js.map +1 -0
  178. package/dist/component/usageCredits/schema.d.ts +282 -0
  179. package/dist/component/usageCredits/schema.d.ts.map +1 -0
  180. package/dist/component/usageCredits/schema.js +92 -0
  181. package/dist/component/usageCredits/schema.js.map +1 -0
  182. package/docs/README.md +4 -0
  183. package/docs/setup-intent-recovery.md +7 -0
  184. package/docs/usage-credits.md +255 -0
  185. package/docs/usage-ledger.md +7 -0
  186. package/docs/usage-limits.md +217 -0
  187. package/docs/webhooks.md +15 -1
  188. package/package.json +3 -1
  189. package/src/client/billing/setup-intent-read.test.ts +40 -0
  190. package/src/client/billing/setup-intent-read.ts +23 -9
  191. package/src/client/index.ts +9 -67
  192. package/src/client/types/triggers.ts +2 -0
  193. package/src/client/usage/allowanceClient.test.ts +93 -0
  194. package/src/client/usage/allowanceClient.ts +134 -0
  195. package/src/client/usage/allowanceTerms.test.ts +131 -0
  196. package/src/client/usage/allowanceTerms.ts +172 -0
  197. package/src/client/usage/client.ts +4 -4
  198. package/src/client/usage/creditCapacity.test.ts +83 -0
  199. package/src/client/usage/creditCapacity.ts +76 -0
  200. package/src/client/usage/creditClient.test.ts +221 -0
  201. package/src/client/usage/creditClient.ts +246 -0
  202. package/src/client/usage/creditDelivery.ts +105 -0
  203. package/src/client/usage/creditInvoice.test.ts +149 -0
  204. package/src/client/usage/creditInvoice.ts +87 -0
  205. package/src/client/usage/creditLifecycle.ts +175 -0
  206. package/src/client/usage/creditNative.ts +148 -0
  207. package/src/client/usage/creditObservation.test.ts +150 -0
  208. package/src/client/usage/creditObservation.ts +82 -0
  209. package/src/client/usage/creditProofs.ts +61 -0
  210. package/src/client/usage/creditProvider.test.ts +202 -0
  211. package/src/client/usage/creditProvider.ts +304 -0
  212. package/src/client/usage/creditRead.ts +32 -0
  213. package/src/client/usage/creditReconciliation.ts +213 -0
  214. package/src/client/usage/creditTerms.test.ts +48 -0
  215. package/src/client/usage/creditTerms.ts +140 -0
  216. package/src/client/usage/creditTransport.fixtures.ts +282 -0
  217. package/src/client/usage/deliveryProvider.ts +2 -0
  218. package/src/client/usage/index.ts +16 -0
  219. package/src/client/usage/record-composition.test.ts +195 -0
  220. package/src/client/usage/records.ts +26 -0
  221. package/src/client/usage/subscriptionTransport.fixtures.ts +6 -0
  222. package/src/client/usage/summary.test.ts +1 -1
  223. package/src/client/usage/summary.ts +2 -2
  224. package/src/client/usageExports.ts +56 -0
  225. package/src/client/webhook-handlers.test.ts +0 -34
  226. package/src/client/webhooks/subscription-deleted-dispatch.test.ts +61 -0
  227. package/src/client/webhooks/subscription-deleted.integration.test.ts +313 -0
  228. package/src/client/webhooks/subscriptionDeleted.ts +56 -0
  229. package/src/component/_generated/api.ts +18 -0
  230. package/src/component/_generated/component.ts +486 -0
  231. package/src/component/accountClosure/mutations.ts +14 -0
  232. package/src/component/schema.ts +16 -0
  233. package/src/component/usage/allowance.test.ts +435 -0
  234. package/src/component/usage/ledger.test.ts +8 -15
  235. package/src/component/usage/mutations.ts +22 -0
  236. package/src/component/usage/schema.ts +14 -0
  237. package/src/component/usageAllowance/helpers.ts +137 -0
  238. package/src/component/usageAllowance/mutations.ts +139 -0
  239. package/src/component/usageAllowance/queries.ts +133 -0
  240. package/src/component/usageAllowance/reservations.ts +220 -0
  241. package/src/component/usageAllowance/schema.ts +36 -0
  242. package/src/component/usageCredits/accounting.test.ts +389 -0
  243. package/src/component/usageCredits/helpers.ts +160 -0
  244. package/src/component/usageCredits/mutations.ts +451 -0
  245. package/src/component/usageCredits/purchase.ts +219 -0
  246. package/src/component/usageCredits/queries.ts +300 -0
  247. package/src/component/usageCredits/reservations.ts +214 -0
  248. package/src/component/usageCredits/schema.ts +106 -0
@@ -0,0 +1,140 @@
1
+ import { z } from "zod";
2
+ import {
3
+ prepareUsageRecord,
4
+ type PreparedUsageRecord,
5
+ type UsageScope,
6
+ } from "./records.js";
7
+ import { parseUsageQuantity, type UsagePlan } from "./contracts.js";
8
+ export class UsageCreditError extends Error {
9
+ constructor(
10
+ readonly code:
11
+ | "unsupported_scope"
12
+ | "incompatible_terms"
13
+ | "insufficient_credits"
14
+ | "reconciliation_required"
15
+ | "unknown_create_outcome"
16
+ | "provider_unavailable",
17
+ message: string,
18
+ ) {
19
+ super(message);
20
+ this.name = "UsageCreditError";
21
+ }
22
+ }
23
+ export type UsageCreditBinding = {
24
+ scope: UsageScope;
25
+ binding: Omit<PreparedUsageRecord["binding"], "apiVersion"> & {
26
+ apiVersion?: string;
27
+ };
28
+ };
29
+ export type UsageCreditPurchaseOptions = UsageCreditBinding & {
30
+ purchaseId: string;
31
+ quantity: string;
32
+ ownership: "issuer";
33
+ rollover: "retain_original_terms";
34
+ expiresAt?: number;
35
+ };
36
+ const options = z.strictObject({
37
+ scope: z.unknown(),
38
+ binding: z.unknown(),
39
+ purchaseId: z.string().min(1).max(100),
40
+ quantity: z.string().max(25),
41
+ ownership: z.literal("issuer"),
42
+ rollover: z.literal("retain_original_terms"),
43
+ expiresAt: z
44
+ .number()
45
+ .int()
46
+ .positive()
47
+ .max(Number.MAX_SAFE_INTEGER)
48
+ .optional(),
49
+ });
50
+ /** Quantity accounting is price-specific. No monetary wallet or currency conversion. */
51
+ export function creditCost(plan: UsagePlan, scaledQuantity: string): number {
52
+ if (plan.model !== "prepaid" || !/^\d{1,18}$/.test(scaledQuantity))
53
+ throw new UsageCreditError(
54
+ "incompatible_terms",
55
+ "Original prepaid terms required",
56
+ );
57
+ const [whole, fraction = ""] = plan.rate.unitAmountDecimal.split(".");
58
+ const numerator = BigInt(whole + fraction) * BigInt(scaledQuantity);
59
+ const denominator = 10n ** BigInt(fraction.length + plan.unit.precision);
60
+ if (numerator <= 0n || numerator % denominator !== 0n)
61
+ throw new UsageCreditError(
62
+ "incompatible_terms",
63
+ "Prepaid consumption requires whole minor currency units",
64
+ );
65
+ const amount = numerator / denominator;
66
+ if (amount > 99999999n)
67
+ throw new UsageCreditError(
68
+ "incompatible_terms",
69
+ "Prepaid backing exceeds native payment bound",
70
+ );
71
+ return Number(amount);
72
+ }
73
+ export function creditBinding(input: UsageCreditBinding) {
74
+ const { scope, binding } = prepareUsageRecord({
75
+ scope: input.scope,
76
+ binding: input.binding,
77
+ sourceEventId: "credit",
78
+ quantity: "0",
79
+ occurredAt: 0,
80
+ });
81
+ if (binding.plan.model !== "prepaid")
82
+ throw new UsageCreditError("incompatible_terms", "Prepaid plan required");
83
+ return { scope, binding };
84
+ }
85
+ export function creditPurchaseTerms(input: unknown) {
86
+ if (
87
+ input &&
88
+ typeof input === "object" &&
89
+ "ownership" in input &&
90
+ input.ownership !== "issuer"
91
+ )
92
+ throw new UsageCreditError(
93
+ "unsupported_scope",
94
+ "Native credits support only the issuer's own services",
95
+ );
96
+ const parsed = options.parse(input);
97
+ const original = creditBinding(parsed as UsageCreditPurchaseOptions);
98
+ const quantity = parseUsageQuantity(
99
+ parsed.quantity,
100
+ original.binding.plan.unit.precision,
101
+ );
102
+ return {
103
+ ...parsed,
104
+ ...original,
105
+ quantity: quantity.quantity,
106
+ scaledQuantity: quantity.scaledQuantity,
107
+ amount: creditCost(original.binding.plan, quantity.scaledQuantity),
108
+ };
109
+ }
110
+ export type UsageCreditPurchaseTerms = ReturnType<typeof creditPurchaseTerms>;
111
+ export type UsageCreditBalance = {
112
+ availableQuantity: string;
113
+ reservedQuantity: string;
114
+ consumedQuantity: string;
115
+ expiredQuantity: string;
116
+ frozenQuantity: string;
117
+ precision: number;
118
+ currency: string;
119
+ unit: string;
120
+ status: "available" | "held";
121
+ cashCollection: "none";
122
+ };
123
+ export type UsageCreditPurchase = {
124
+ purchaseId: string;
125
+ state: "pending" | "ready" | "frozen" | "canceled";
126
+ paymentIntentId: string | null;
127
+ creditGrantId: string | null;
128
+ quantity: string;
129
+ amount: number;
130
+ currency: string;
131
+ };
132
+
133
+ export class UsageCreditRecoveryError extends UsageCreditError {
134
+ constructor(readonly reason: "payment_refunded" | "payment_disputed") {
135
+ super(
136
+ "reconciliation_required",
137
+ "Credit payment refund or dispute requires recovery",
138
+ );
139
+ }
140
+ }
@@ -0,0 +1,282 @@
1
+ import { vi } from "vitest";
2
+ import { fixture } from "./subscriptionTransport.fixtures.js";
3
+ import { request } from "./subscription.fixtures.js";
4
+ import { ensureManagedSubscription } from "./subscriptionProvider.js";
5
+ import type { RunCtx } from "../helpers.js";
6
+ const response = (value: unknown) =>
7
+ new Response(JSON.stringify(value), {
8
+ headers: { "content-type": "application/json" },
9
+ });
10
+ export function creditFixture() {
11
+ vi.useFakeTimers();
12
+ vi.setSystemTime(700000);
13
+ const calls: Array<{
14
+ path: string;
15
+ method: string;
16
+ body: URLSearchParams;
17
+ key: string | null;
18
+ }> = [];
19
+ const state = {
20
+ paid: false,
21
+ nativeApplied: 0,
22
+ nativeAvailable: undefined as number | undefined,
23
+ applyAtExpire: false,
24
+ nativeExpired: false,
25
+ incomplete: false,
26
+ canceled: false,
27
+ refunded: false,
28
+ failGrant: false,
29
+ wrongPayer: false,
30
+ paymentId: "pi_topup1",
31
+ grant: undefined as Record<string, unknown> | undefined,
32
+ metadata: {} as Record<string, string>,
33
+ };
34
+ const f = fixture(false, false, async (input, init) => {
35
+ const path = new URL(input).pathname,
36
+ method = init?.method ?? "GET",
37
+ body = new URLSearchParams(String(init?.body ?? ""));
38
+ if (path === "/v1/prices/price_calls")
39
+ return response({
40
+ id: "price_calls",
41
+ active: true,
42
+ livemode: false,
43
+ currency: "usd",
44
+ type: "recurring",
45
+ product: "prod_calls",
46
+ lookup_key: "calls",
47
+ billing_scheme: "per_unit",
48
+ unit_amount_decimal: "2",
49
+ transform_quantity: null,
50
+ recurring: {
51
+ interval: "month",
52
+ interval_count: 1,
53
+ usage_type: "metered",
54
+ meter: "mtr_calls",
55
+ },
56
+ });
57
+ if (path === "/v1/invoices/in_usage")
58
+ return response({
59
+ id: "in_usage",
60
+ livemode: false,
61
+ customer_account: "acct_foreign",
62
+ customer: "cus_buyer",
63
+ currency: "usd",
64
+ status: "paid",
65
+ status_transitions: { finalized_at: 1300 },
66
+ parent: { subscription_details: { subscription: "sub_calls" } },
67
+ lines: { has_more: false, data: [] },
68
+ });
69
+ if (path === "/v1/billing/credit_balance_summary")
70
+ return response({
71
+ customer: "cus_buyer",
72
+ customer_account: "acct_buyer",
73
+ livemode: false,
74
+ balances: [
75
+ {
76
+ ledger_balance: {
77
+ type: "monetary",
78
+ monetary: {
79
+ currency: "usd",
80
+ value: state.nativeExpired ? 0 : 20 - state.nativeApplied,
81
+ },
82
+ },
83
+ available_balance: {
84
+ type: "monetary",
85
+ monetary: {
86
+ currency: "usd",
87
+ value:
88
+ state.nativeAvailable ??
89
+ (state.nativeExpired ? 0 : 20 - state.nativeApplied),
90
+ },
91
+ },
92
+ },
93
+ ],
94
+ });
95
+ if (path === "/v1/billing/credit_balance_transactions")
96
+ return response({
97
+ data: [
98
+ {
99
+ id: "cbtxn_granted",
100
+ object: "billing.credit_balance_transaction",
101
+ credit_grant: "credgr_topup1",
102
+ livemode: false,
103
+ type: "credit",
104
+ credit: {
105
+ type: "credits_granted",
106
+ amount: {
107
+ type: "monetary",
108
+ monetary: { currency: "usd", value: 20 },
109
+ },
110
+ },
111
+ debit: null,
112
+ },
113
+ ...(state.nativeApplied
114
+ ? [
115
+ {
116
+ id: "cbtxn_applied",
117
+ object: "billing.credit_balance_transaction",
118
+ credit_grant: "credgr_topup1",
119
+ livemode: false,
120
+ type: "debit",
121
+ credit: null,
122
+ debit: {
123
+ type: "credits_applied",
124
+ amount: {
125
+ type: "monetary",
126
+ monetary: { currency: "usd", value: state.nativeApplied },
127
+ },
128
+ credits_applied: {
129
+ invoice: "in_usage",
130
+ invoice_line_item: "il_usage",
131
+ },
132
+ },
133
+ },
134
+ ]
135
+ : []),
136
+ ...(state.nativeExpired
137
+ ? [
138
+ {
139
+ id: "cbtxn_expired",
140
+ object: "billing.credit_balance_transaction",
141
+ credit_grant: "credgr_topup1",
142
+ livemode: false,
143
+ type: "debit",
144
+ credit: null,
145
+ debit: {
146
+ type: "credits_expired",
147
+ amount: {
148
+ type: "monetary",
149
+ monetary: {
150
+ currency: "usd",
151
+ value: 20 - state.nativeApplied,
152
+ },
153
+ },
154
+ },
155
+ },
156
+ ]
157
+ : []),
158
+ ],
159
+ has_more: state.incomplete,
160
+ });
161
+ if (path.endsWith("/expire") && method === "POST") {
162
+ if (state.applyAtExpire) state.nativeApplied = 20;
163
+ state.nativeExpired = true;
164
+ state.grant!.expires_at = 700;
165
+ return response(state.grant);
166
+ }
167
+ if (
168
+ !path.startsWith("/v1/payment_intents") &&
169
+ !path.startsWith("/v1/billing/credit_grants")
170
+ )
171
+ return undefined;
172
+ calls.push({
173
+ path,
174
+ method,
175
+ body,
176
+ key: new Headers(init?.headers).get("idempotency-key"),
177
+ });
178
+ if (path === "/v1/payment_intents" && method === "GET")
179
+ return response({
180
+ data: state.metadata.bsUsageCredit ? [payment()] : [],
181
+ has_more: false,
182
+ });
183
+ if (path === "/v1/payment_intents" && method === "POST") {
184
+ state.metadata = { bsUsageCredit: body.get("metadata[bsUsageCredit]")! };
185
+ return response(payment());
186
+ }
187
+ if (path.endsWith("/cancel")) state.canceled = true;
188
+ if (path.startsWith("/v1/payment_intents/")) return response(payment());
189
+ if (path === "/v1/billing/credit_grants" && method === "GET")
190
+ return response({
191
+ data: state.grant ? [state.grant] : [],
192
+ has_more: false,
193
+ });
194
+ if (path === "/v1/billing/credit_grants" && method === "POST") {
195
+ if (state.failGrant)
196
+ throw new Error("private grant failure sk_test_dont_log");
197
+ state.grant = {
198
+ id: "credgr_topup1",
199
+ object: "billing.credit_grant",
200
+ livemode: false,
201
+ customer_account: "acct_buyer",
202
+ customer: "cus_buyer",
203
+ category: "paid",
204
+ amount: { type: "monetary", monetary: { currency: "usd", value: 20 } },
205
+ applicability_config: { scope: { prices: [{ id: "price_calls" }] } },
206
+ metadata: { bsUsageCredit: body.get("metadata[bsUsageCredit]") },
207
+ effective_at: 700,
208
+ expires_at: null,
209
+ voided_at: null,
210
+ created: 700,
211
+ priority: 50,
212
+ };
213
+ return response(state.grant);
214
+ }
215
+ return response(state.grant);
216
+ });
217
+ function payment() {
218
+ return {
219
+ id: state.paymentId,
220
+ object: "payment_intent",
221
+ customer_account: state.wrongPayer ? "acct_other" : "acct_buyer",
222
+ customer: "cus_buyer",
223
+ livemode: false,
224
+ currency: "usd",
225
+ amount: 20,
226
+ amount_received: state.paid ? 20 : 0,
227
+ status: state.canceled
228
+ ? "canceled"
229
+ : state.paid
230
+ ? "succeeded"
231
+ : "requires_payment_method",
232
+ metadata: state.metadata,
233
+ client_secret: "pi_topup1_secret_private",
234
+ latest_charge: state.paid
235
+ ? {
236
+ id: "ch_topup1",
237
+ object: "charge",
238
+ payment_intent: state.paymentId,
239
+ paid: true,
240
+ captured: true,
241
+ status: "succeeded",
242
+ amount: 20,
243
+ amount_captured: 20,
244
+ currency: "usd",
245
+ livemode: false,
246
+ refunded: state.refunded,
247
+ amount_refunded: state.refunded ? 20 : 0,
248
+ disputed: false,
249
+ }
250
+ : null,
251
+ };
252
+ }
253
+ const meter = {
254
+ ...request.meters[0],
255
+ binding: {
256
+ ...request.meters[0].binding,
257
+ plan: {
258
+ key: "calls",
259
+ version: "v1",
260
+ model: "prepaid" as const,
261
+ unit: { name: "call", precision: 0 },
262
+ rate: { currency: "usd", unitAmountDecimal: "2" },
263
+ insufficientBalance: "reject" as const,
264
+ },
265
+ },
266
+ };
267
+ const purchase = {
268
+ ...meter,
269
+ purchaseId: "topup1",
270
+ quantity: "10",
271
+ ownership: "issuer" as const,
272
+ rollover: "retain_original_terms" as const,
273
+ };
274
+ const ready = () =>
275
+ f.t.action((ctx) =>
276
+ ensureManagedSubscription(f.stripe, f.component, ctx as RunCtx, {
277
+ ...request,
278
+ meters: [meter],
279
+ }),
280
+ );
281
+ return { ...f, calls, state, purchase, ready };
282
+ }
@@ -1,3 +1,4 @@
1
+ import { verifyCreditDelivery } from "./creditDelivery.js";
1
2
  import type { UsageSubscriptionView } from "./subscriptionTerms.js";
2
3
  import Stripe from "stripe";
3
4
  import type { StripeApiVersion } from "../stripe-types.js";
@@ -104,6 +105,7 @@ export async function deliverUsageProvider(
104
105
  eventName: record.binding.eventName,
105
106
  displayName: meter.display_name,
106
107
  });
108
+ await verifyCreditDelivery(stripe, component, ctx, saved.event, record);
107
109
  const current = await read();
108
110
  if (
109
111
  !eligible(current.outbox) ||
@@ -72,3 +72,19 @@ export type { UsageSubscriptionRef } from "./subscriptionLifecycle.js";
72
72
  export type { UsageSubscriptionInvoice } from "./subscriptionInvoiceSchema.js";
73
73
 
74
74
  export { UsageSubscriptionError } from "./subscriptionErrors.js";
75
+
76
+ export { UsageCreditError } from "./creditTerms.js";
77
+ export type {
78
+ UsageCreditBinding,
79
+ UsageCreditPurchaseOptions,
80
+ UsageCreditPurchase,
81
+ UsageCreditBalance,
82
+ } from "./creditTerms.js";
83
+
84
+ export type {
85
+ UsageAllowanceBinding,
86
+ UsageAllowanceStatus,
87
+ UsageAllowanceReconciliation,
88
+ UsageLimitPolicy,
89
+ } from "./allowanceTerms.js";
90
+ export type { UsageAllowanceReservation } from "./allowanceClient.js";
@@ -0,0 +1,195 @@
1
+ import { afterEach, expect, it, vi } from "vitest";
2
+ import { components, initConvexTest } from "../setup.test.js";
3
+ import { schema, modules } from "../../test.js";
4
+ import { BetterStripe } from "../index.js";
5
+ import {
6
+ authorizeUsageRecord,
7
+ type UsageSubscriptionBinding,
8
+ } from "./boundaries.js";
9
+ import { prepareUsageRecord } from "./records.js";
10
+
11
+ afterEach(() => vi.restoreAllMocks());
12
+
13
+ function fixture() {
14
+ const t = initConvexTest();
15
+ t.registerComponent("betterStripe", schema, modules);
16
+ const stripe = new BetterStripe(components.betterStripe);
17
+ const now = Math.floor(Date.now() / 1000);
18
+ const event = {
19
+ scope: {
20
+ stripeAccountId: "acct_platform",
21
+ customerAccount: "acct_buyer",
22
+ meterId: "mtr_calls",
23
+ livemode: false,
24
+ },
25
+ binding: {
26
+ stripeCustomerId: "cus_buyer",
27
+ stripePriceId: "price_calls",
28
+ eventName: "calls",
29
+ plan: {
30
+ key: "calls",
31
+ version: "v1",
32
+ model: "pay_as_you_go",
33
+ unit: { name: "call", precision: 2 },
34
+ rate: { currency: "usd", unitAmountDecimal: "2" },
35
+ },
36
+ },
37
+ sourceEventId: "activity_composition",
38
+ quantity: "1.20",
39
+ occurredAt: now,
40
+ };
41
+ const subscription: UsageSubscriptionBinding = {
42
+ subscriptionId: "sub_calls",
43
+ subscriptionItemId: "si_calls",
44
+ stripePriceId: "price_calls",
45
+ period: { start: now - 1, end: now + 100 },
46
+ interval: "month",
47
+ };
48
+ const record = (input: unknown) =>
49
+ t.run((ctx) => stripe.usage.record(ctx, { event: input, subscription }));
50
+ const read = () =>
51
+ t.run((ctx) =>
52
+ stripe.usage.read(ctx, {
53
+ scope: event.scope,
54
+ page: { period: subscription.period, limit: 10, cursor: null },
55
+ }),
56
+ );
57
+ const fetch = vi
58
+ .spyOn(globalThis, "fetch")
59
+ .mockRejectedValue(
60
+ new Error("Provider I/O is forbidden for ledger acceptance"),
61
+ );
62
+ return { t, stripe, event, subscription, record, read, fetch };
63
+ }
64
+
65
+ it("composes actual authorization with the registered public ledger and retains scoped replay/conflict/read behavior", async () => {
66
+ const f = fixture();
67
+ const order: string[] = [];
68
+ const receipt = await f.t.run((ctx) =>
69
+ authorizeUsageRecord(
70
+ ctx,
71
+ {
72
+ authorize: async () => {
73
+ order.push("scope");
74
+ },
75
+ authorizeActivity: async () => {
76
+ order.push("activity");
77
+ },
78
+ },
79
+ f.event,
80
+ (event) => {
81
+ order.push("record");
82
+ return f.stripe.usage.record(ctx, {
83
+ event,
84
+ subscription: f.subscription,
85
+ });
86
+ },
87
+ ),
88
+ );
89
+ expect(order).toEqual(["scope", "activity", "record"]);
90
+ expect(receipt.delivery).toBe("queued");
91
+ expect(await f.record(f.event)).toEqual(receipt);
92
+ await expect(
93
+ f.record(prepareUsageRecord({ ...f.event, quantity: "1.21" })),
94
+ ).rejects.toThrow();
95
+ expect((await f.read()).events).toMatchObject([
96
+ { record: { quantity: "1.2", scaledQuantity: "120" } },
97
+ ]);
98
+ expect((await f.read()).events).toHaveLength(1);
99
+ expect(f.fetch).not.toHaveBeenCalled();
100
+ });
101
+
102
+ it("preserves raw strict validation and authorization denial before ledger acceptance", async () => {
103
+ const f = fixture();
104
+ await expect(
105
+ f.t.run((ctx) =>
106
+ authorizeUsageRecord(
107
+ ctx,
108
+ {
109
+ authorize: async () => {
110
+ throw new Error("Denied");
111
+ },
112
+ authorizeActivity: async () => {
113
+ throw new Error("Must not reach activity");
114
+ },
115
+ },
116
+ f.event,
117
+ (event) =>
118
+ f.stripe.usage.record(ctx, { event, subscription: f.subscription }),
119
+ ),
120
+ ),
121
+ ).rejects.toThrow("Denied");
122
+ await expect(f.record({ ...f.event, unexpected: true })).rejects.toThrow();
123
+ expect((await f.read()).events).toEqual([]);
124
+ expect(f.fetch).not.toHaveBeenCalled();
125
+ });
126
+
127
+ it("requires activity approval after successful scope authorization before composing ledger acceptance", async () => {
128
+ const f = fixture();
129
+ const order: string[] = [];
130
+ await expect(
131
+ f.t.run((ctx) =>
132
+ authorizeUsageRecord(
133
+ ctx,
134
+ {
135
+ authorize: async () => {
136
+ order.push("scope");
137
+ },
138
+ authorizeActivity: async () => {
139
+ order.push("activity");
140
+ throw new Error("Activity denied");
141
+ },
142
+ },
143
+ f.event,
144
+ (event) => {
145
+ order.push("record");
146
+ return f.stripe.usage.record(ctx, {
147
+ event,
148
+ subscription: f.subscription,
149
+ });
150
+ },
151
+ ),
152
+ ),
153
+ ).rejects.toThrow("Activity denied");
154
+ expect(order).toEqual(["scope", "activity"]);
155
+ expect((await f.read()).events).toEqual([]);
156
+ expect(f.fetch).not.toHaveBeenCalled();
157
+ });
158
+
159
+ for (const change of [
160
+ "identity",
161
+ "scaledQuantity",
162
+ "schemaVersion",
163
+ "quantity",
164
+ "noncanonicalQuantity",
165
+ "plan",
166
+ "unknown",
167
+ "nestedUnknown",
168
+ "partial",
169
+ ] as const) {
170
+ it(`rejects ${change} tampering in prepared records without a ledger write`, async () => {
171
+ const f = fixture();
172
+ const prepared = prepareUsageRecord(f.event);
173
+ const input: Record<string, unknown> = structuredClone(prepared);
174
+ if (change === "identity") input.identity = "forged";
175
+ if (change === "scaledQuantity") input.scaledQuantity = "121";
176
+ if (change === "schemaVersion") input.schemaVersion = 2;
177
+ if (change === "quantity") input.quantity = "1.21";
178
+ if (change === "noncanonicalQuantity") input.quantity = "1.20";
179
+ if (change === "plan")
180
+ input.binding = {
181
+ ...prepared.binding,
182
+ plan: {
183
+ ...prepared.binding.plan,
184
+ unit: { name: "call", precision: 1 },
185
+ },
186
+ };
187
+ if (change === "unknown") input.unexpected = true;
188
+ if (change === "nestedUnknown")
189
+ input.binding = { ...prepared.binding, unexpected: true };
190
+ if (change === "partial") delete input.scaledQuantity;
191
+ await expect(f.record(input)).rejects.toThrow();
192
+ expect((await f.read()).events).toEqual([]);
193
+ expect(f.fetch).not.toHaveBeenCalled();
194
+ });
195
+ }
@@ -74,3 +74,29 @@ export function prepareUsageRecord(input: unknown): PreparedUsageRecord {
74
74
  ]),
75
75
  };
76
76
  }
77
+
78
+ const preparedRecordSchema = recordSchema.extend({
79
+ schemaVersion: z.literal(1),
80
+ identity: z.string(),
81
+ quantity: z.string(),
82
+ scaledQuantity: z.string(),
83
+ });
84
+
85
+ /** Internal facade decoder: preparation is validation, never host authorization. */
86
+ export function validateUsageRecordInput(input: unknown): PreparedUsageRecord {
87
+ const raw = recordSchema.safeParse(input);
88
+ if (raw.success) return prepareUsageRecord(raw.data);
89
+ // Validate the complete strict shape before selecting raw fields. Partial or
90
+ // unknown prepared fields cannot silently become a valid raw event.
91
+ const { schemaVersion, identity, scaledQuantity, ...record } =
92
+ preparedRecordSchema.parse(input);
93
+ const canonical = prepareUsageRecord(record);
94
+ if (
95
+ schemaVersion !== canonical.schemaVersion ||
96
+ identity !== canonical.identity ||
97
+ scaledQuantity !== canonical.scaledQuantity ||
98
+ record.quantity !== canonical.quantity
99
+ )
100
+ throw new Error("Inconsistent prepared usage record");
101
+ return canonical;
102
+ }
@@ -7,6 +7,10 @@ import { nativeSubscription } from "./subscription.fixtures.js";
7
7
  export function fixture(
8
8
  external = false,
9
9
  failCreate = false,
10
+ intercept?: (
11
+ input: string,
12
+ init?: RequestInit,
13
+ ) => Promise<Response | undefined>,
10
14
  ): {
11
15
  t: ReturnType<typeof initConvexTest>;
12
16
  component: Component;
@@ -49,6 +53,8 @@ export function fixture(
49
53
  checkoutCreates = 0;
50
54
  const httpClient: Stripe.HttpClient = Stripe.createFetchHttpClient(
51
55
  async (input, init) => {
56
+ const intercepted = await intercept?.(String(input), init);
57
+ if (intercepted) return intercepted;
52
58
  const path = new URL(String(input)).pathname,
53
59
  method = init?.method ?? "GET",
54
60
  body = new URLSearchParams(String(init?.body ?? ""));