@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,150 @@
1
+ import { expect, it } from "vitest";
2
+ import { normalizeCreditState } from "./creditObservation.js";
3
+ const grant = {
4
+ creditGrantId: "credgr_test",
5
+ paymentIntentId: "pi_test",
6
+ consumed: "6",
7
+ reserved: "0",
8
+ available: "4",
9
+ };
10
+ const terms = {
11
+ scope: {
12
+ stripeAccountId: "acct_platform",
13
+ customerAccount: "acct_buyer",
14
+ meterId: "mtr_calls",
15
+ livemode: false,
16
+ },
17
+ binding: {
18
+ apiVersion: "2026-09-30.endive" as const,
19
+ stripeCustomerId: "cus_buyer",
20
+ stripePriceId: "price_calls",
21
+ eventName: "calls",
22
+ plan: {
23
+ key: "calls",
24
+ version: "v1",
25
+ model: "prepaid" as const,
26
+ unit: { name: "call", precision: 0 },
27
+ rate: { currency: "usd", unitAmountDecimal: "2" },
28
+ insufficientBalance: "reject" as const,
29
+ },
30
+ },
31
+ purchaseId: "topup1",
32
+ quantity: "10",
33
+ scaledQuantity: "10",
34
+ amount: 20,
35
+ ownership: "issuer" as const,
36
+ rollover: "retain_original_terms" as const,
37
+ };
38
+ it("keeps pending native consumption separate from funded units and does not mint on invoice void", () => {
39
+ const initial = normalizeCreditState(
40
+ terms,
41
+ grant,
42
+ {
43
+ ledgerAmount: 20,
44
+ availableAmount: 20,
45
+ granted: 20,
46
+ applied: 0,
47
+ expired: 0,
48
+ voided: 0,
49
+ reinstated: 0,
50
+ },
51
+ true,
52
+ );
53
+ expect(initial).toMatchObject({
54
+ backing: "sufficient",
55
+ pendingFinalizationAmount: 12,
56
+ cashCollection: "none",
57
+ });
58
+ const applied = normalizeCreditState(
59
+ terms,
60
+ grant,
61
+ {
62
+ ledgerAmount: 8,
63
+ availableAmount: 8,
64
+ granted: 20,
65
+ applied: 12,
66
+ expired: 0,
67
+ voided: 0,
68
+ reinstated: 0,
69
+ },
70
+ true,
71
+ );
72
+ expect(applied).toMatchObject({
73
+ backing: "sufficient",
74
+ pendingFinalizationAmount: 0,
75
+ });
76
+ const restored = normalizeCreditState(
77
+ terms,
78
+ grant,
79
+ {
80
+ ledgerAmount: 20,
81
+ availableAmount: 20,
82
+ granted: 20,
83
+ applied: 12,
84
+ expired: 0,
85
+ voided: 0,
86
+ reinstated: 12,
87
+ },
88
+ true,
89
+ );
90
+ expect(restored).toMatchObject({
91
+ backing: "held",
92
+ reason: "invoice_void_requires_correction",
93
+ });
94
+ });
95
+ it("holds unexpected native consumption, incomplete invoice proof and insufficient backing", () => {
96
+ expect(
97
+ normalizeCreditState(
98
+ terms,
99
+ grant,
100
+ {
101
+ ledgerAmount: 0,
102
+ availableAmount: 0,
103
+ granted: 20,
104
+ applied: 20,
105
+ expired: 0,
106
+ voided: 0,
107
+ reinstated: 0,
108
+ },
109
+ true,
110
+ ).backing,
111
+ ).toBe("held");
112
+ expect(
113
+ normalizeCreditState(
114
+ terms,
115
+ grant,
116
+ {
117
+ ledgerAmount: 8,
118
+ availableAmount: 8,
119
+ granted: 20,
120
+ applied: 12,
121
+ expired: 0,
122
+ voided: 0,
123
+ reinstated: 0,
124
+ },
125
+ false,
126
+ ).backing,
127
+ ).toBe("held");
128
+ });
129
+
130
+ it("holds ledger credit that native available balance has already reserved for unrecorded transactions", () => {
131
+ expect(
132
+ normalizeCreditState(
133
+ terms,
134
+ grant,
135
+ {
136
+ ledgerAmount: 20,
137
+ availableAmount: 0,
138
+ granted: 20,
139
+ applied: 0,
140
+ expired: 0,
141
+ voided: 0,
142
+ reinstated: 0,
143
+ },
144
+ true,
145
+ ),
146
+ ).toMatchObject({
147
+ backing: "held",
148
+ reason: "native_credit_pending_application",
149
+ });
150
+ });
@@ -0,0 +1,82 @@
1
+ import { creditCost, type UsageCreditPurchaseTerms } from "./creditTerms.js";
2
+ export type UsageCreditNativeAmounts = {
3
+ ledgerAmount: number;
4
+ availableAmount: number;
5
+ granted: number;
6
+ applied: number;
7
+ expired: number;
8
+ voided: number;
9
+ reinstated: number;
10
+ };
11
+ export type UsageCreditReconciliation = UsageCreditNativeAmounts & {
12
+ backing: "sufficient" | "held";
13
+ reason: string | null;
14
+ pendingFinalizationAmount: number;
15
+ cashCollection: "none";
16
+ invoicePaymentEvidence: "not_resolved";
17
+ };
18
+ export function normalizeCreditState(
19
+ terms: UsageCreditPurchaseTerms,
20
+ grant: { consumed: string; reserved: string; available: string },
21
+ native: UsageCreditNativeAmounts,
22
+ invoicesVerified: boolean,
23
+ ): UsageCreditReconciliation {
24
+ const cost = (quantity: string) =>
25
+ BigInt(quantity) === 0n ? 0 : creditCost(terms.binding.plan, quantity);
26
+ const consumed = cost(grant.consumed),
27
+ reserved = cost(grant.reserved),
28
+ available = cost(grant.available);
29
+ let reason: string | null = null;
30
+ if (
31
+ [
32
+ native.ledgerAmount,
33
+ native.availableAmount,
34
+ native.granted,
35
+ native.applied,
36
+ native.expired,
37
+ native.voided,
38
+ native.reinstated,
39
+ ].some((n) => !Number.isSafeInteger(n) || n < 0)
40
+ )
41
+ reason = "unsafe_native_amount";
42
+ else if (native.reinstated > 0) reason = "invoice_void_requires_correction";
43
+ else if (
44
+ native.granted !== terms.amount ||
45
+ native.ledgerAmount !==
46
+ native.granted -
47
+ native.applied -
48
+ native.expired -
49
+ native.voided +
50
+ native.reinstated ||
51
+ native.availableAmount > native.ledgerAmount
52
+ )
53
+ reason = "native_ledger_mismatch";
54
+ else if (native.availableAmount < native.ledgerAmount)
55
+ reason = "native_credit_pending_application";
56
+ else if (!invoicesVerified) reason = "invoice_provenance_unavailable";
57
+ else if (native.applied > consumed) reason = "unexpected_native_consumption";
58
+ else if (
59
+ native.ledgerAmount < available + reserved + consumed - native.applied &&
60
+ native.expired + native.voided === 0
61
+ )
62
+ reason = "insufficient_native_backing";
63
+ else if (
64
+ (native.expired > 0 || native.voided > 0) &&
65
+ reserved + consumed - native.applied > 0
66
+ )
67
+ reason = "expired_pending_consumption";
68
+ return {
69
+ ledgerAmount: native.ledgerAmount,
70
+ availableAmount: native.availableAmount,
71
+ granted: native.granted,
72
+ applied: native.applied,
73
+ expired: native.expired,
74
+ voided: native.voided,
75
+ reinstated: native.reinstated,
76
+ backing: reason ? "held" : "sufficient",
77
+ reason,
78
+ pendingFinalizationAmount: Math.max(0, consumed - native.applied),
79
+ cashCollection: "none",
80
+ invoicePaymentEvidence: "not_resolved",
81
+ };
82
+ }
@@ -0,0 +1,61 @@
1
+ import { z } from "zod";
2
+ const id = (prefix: string) =>
3
+ z
4
+ .string()
5
+ .regex(new RegExp("^" + prefix + "_[a-zA-Z0-9_]+$"))
6
+ .max(200);
7
+ export const paymentCreditProof = z.strictObject({
8
+ paymentIntentId: id("pi"),
9
+ chargeId: id("ch"),
10
+ amount: z.number().int().min(1).max(99999999),
11
+ currency: z.string().regex(/^[a-z]{3}$/),
12
+ customerAccount: id("acct"),
13
+ livemode: z.boolean(),
14
+ });
15
+ export const grantCreditProof = paymentCreditProof.extend({
16
+ creditGrantId: id("credgr"),
17
+ stripePriceId: id("price"),
18
+ createdAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
19
+ effectiveAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
20
+ expiresAt: z
21
+ .number()
22
+ .int()
23
+ .positive()
24
+ .max(Number.MAX_SAFE_INTEGER)
25
+ .nullable(),
26
+ });
27
+
28
+ export const creditNativeObservation = z.strictObject({
29
+ creditGrantId: id("credgr"),
30
+ paymentIntentId: id("pi"),
31
+ currency: z.string().regex(/^[a-z]{3}$/),
32
+ ledgerAmount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
33
+ availableAmount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
34
+ granted: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
35
+ applied: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
36
+ expired: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
37
+ voided: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
38
+ reinstated: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
39
+ invoicesVerified: z.boolean(),
40
+ complete: z.boolean(),
41
+ transactions: z
42
+ .array(
43
+ z.strictObject({
44
+ id: z
45
+ .string()
46
+ .regex(/^cbtxn_[a-zA-Z0-9_]+$/)
47
+ .max(200),
48
+ kind: z.enum([
49
+ "credits_granted",
50
+ "credits_applied",
51
+ "credits_expired",
52
+ "credits_voided",
53
+ "credits_application_invoice_voided",
54
+ ]),
55
+ amount: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
56
+ invoiceId: id("in").nullable(),
57
+ invoiceLineId: z.string().max(200).nullable(),
58
+ }),
59
+ )
60
+ .max(100),
61
+ });
@@ -0,0 +1,202 @@
1
+ import { creditFixture } from "./creditTransport.fixtures.js";
2
+ import { cancelCreditPurchase } from "./creditLifecycle.js";
3
+ import { componentRef } from "../webhooks/helpers.js";
4
+ import { afterEach, expect, it, vi } from "vitest";
5
+ import {
6
+ ensureCreditPurchase,
7
+ observeCreditPurchase,
8
+ } from "./creditProvider.js";
9
+ import type { RunCtx } from "../helpers.js";
10
+ afterEach(() => vi.useRealTimers());
11
+ it("creates an idempotent native purchase, waits for verified payment and issues one price-scoped paid grant", async () => {
12
+ const f = creditFixture();
13
+ await f.ready();
14
+ const first = await f.t.action((ctx) =>
15
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
16
+ );
17
+ expect(first.purchase.state).toBe("pending");
18
+ expect(first.clientSecret).toContain("_secret_");
19
+ expect(
20
+ f.calls.some(
21
+ (c) => c.path.includes("credit_grants") && c.method === "POST",
22
+ ),
23
+ ).toBe(false);
24
+ f.state.paid = true;
25
+ const paid = await f.t.action((ctx) =>
26
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
27
+ );
28
+ expect(paid).toMatchObject({
29
+ state: "ready",
30
+ creditGrantId: "credgr_topup1",
31
+ });
32
+ await f.t.action((ctx) =>
33
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
34
+ );
35
+ expect(
36
+ f.calls.filter(
37
+ (c) => c.path === "/v1/payment_intents" && c.method === "POST",
38
+ ),
39
+ ).toHaveLength(1);
40
+ const grants = f.calls.filter(
41
+ (c) => c.path === "/v1/billing/credit_grants" && c.method === "POST",
42
+ );
43
+ expect(grants).toHaveLength(1);
44
+ expect(grants[0].body.get("category")).toBe("paid");
45
+ expect(grants[0].body.get("applicability_config[scope][prices][0][id]")).toBe(
46
+ "price_calls",
47
+ );
48
+ expect(grants[0].body.get("amount[monetary][value]")).toBe("20");
49
+ });
50
+ it("preserves the grant intent after a private failure and refuses a foreign payment", async () => {
51
+ const f = creditFixture();
52
+ await f.ready();
53
+ await f.t.action((ctx) =>
54
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
55
+ );
56
+ f.state.paid = true;
57
+ f.state.failGrant = true;
58
+ await expect(
59
+ f.t.action((ctx) =>
60
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
61
+ ),
62
+ ).rejects.toThrow("Native usage credits unavailable");
63
+ f.state.failGrant = false;
64
+ f.state.wrongPayer = true;
65
+ await expect(
66
+ f.t.action((ctx) =>
67
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
68
+ ),
69
+ ).rejects.toThrow(/scope|identity/i);
70
+ f.state.wrongPayer = false;
71
+ expect(
72
+ await f.t.action((ctx) =>
73
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
74
+ ),
75
+ ).toMatchObject({ state: "ready" });
76
+ });
77
+
78
+ it("starts a separate grant retry window when an original payment succeeds after a day", async () => {
79
+ const f = creditFixture();
80
+ await f.ready();
81
+ await f.t.action((ctx) =>
82
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
83
+ );
84
+ f.state.paid = true;
85
+ vi.setSystemTime(700000 + 24 * 3600 * 1000);
86
+ expect(
87
+ await f.t.action((ctx) =>
88
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
89
+ ),
90
+ ).toMatchObject({ state: "ready" });
91
+ });
92
+
93
+ it("freezes previously purchased units on verified refund evidence without granting them again", async () => {
94
+ const f = creditFixture();
95
+ await f.ready();
96
+ await f.t.action((ctx) =>
97
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
98
+ );
99
+ f.state.paid = true;
100
+ await f.t.action((ctx) =>
101
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
102
+ );
103
+ f.state.refunded = true;
104
+ await expect(
105
+ f.t.action((ctx) =>
106
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
107
+ ),
108
+ ).rejects.toThrow(/recovery/i);
109
+ const row = await f.t.action((ctx) =>
110
+ ctx.runQuery(
111
+ componentRef(f.component, "usageCredits/queries/getPurchase"),
112
+ {
113
+ bindingJson: JSON.stringify({
114
+ scope: f.purchase.scope,
115
+ binding: f.purchase.binding,
116
+ }),
117
+ purchaseId: "topup1",
118
+ },
119
+ ),
120
+ );
121
+ expect(row.state).toBe("frozen");
122
+ });
123
+
124
+ it("adopts a native grant after a database failure without creating another grant", async () => {
125
+ const f = creditFixture();
126
+ await f.ready();
127
+ await f.t.action((ctx) =>
128
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
129
+ );
130
+ f.state.paid = true;
131
+ let failed = false;
132
+ await expect(
133
+ f.t.action((ctx) =>
134
+ observeCreditPurchase(
135
+ f.stripe,
136
+ f.component,
137
+ {
138
+ ...ctx,
139
+ runMutation: async (reference, args) => {
140
+ if (
141
+ String(
142
+ (reference as unknown as Record<symbol, string>)[
143
+ Symbol.for("toReferencePath")
144
+ ],
145
+ ).endsWith("/usageCredits/mutations/pinGrant") &&
146
+ !failed
147
+ ) {
148
+ failed = true;
149
+ throw new Error("simulated database failure");
150
+ }
151
+ return ctx.runMutation(reference, args);
152
+ },
153
+ } as RunCtx,
154
+ f.purchase,
155
+ ),
156
+ ),
157
+ ).rejects.toThrow();
158
+ expect(f.state.grant).toBeDefined();
159
+ expect(
160
+ await f.t.action((ctx) =>
161
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
162
+ ),
163
+ ).toMatchObject({ state: "ready" });
164
+ expect(
165
+ f.calls.filter(
166
+ (c) => c.path === "/v1/billing/credit_grants" && c.method === "POST",
167
+ ),
168
+ ).toHaveLength(1);
169
+ });
170
+
171
+ it("cancels an unpaid original purchase and never recreates its payment intent", async () => {
172
+ const f = creditFixture();
173
+ await f.ready();
174
+ await f.t.action((ctx) =>
175
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
176
+ );
177
+ expect(
178
+ await f.t.action((ctx) =>
179
+ cancelCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
180
+ ),
181
+ ).toMatchObject({ state: "canceled" });
182
+ expect(
183
+ await f.t.action((ctx) =>
184
+ cancelCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
185
+ ),
186
+ ).toMatchObject({ state: "canceled" });
187
+ expect(
188
+ await f.t.action((ctx) =>
189
+ ctx.runQuery(componentRef(f.component, "usageCredits/queries/capacity"), {
190
+ bindingJson: JSON.stringify({
191
+ scope: f.purchase.scope,
192
+ binding: f.purchase.binding,
193
+ }),
194
+ }),
195
+ ),
196
+ ).toBe(0);
197
+ expect(
198
+ f.calls.filter(
199
+ (c) => c.path === "/v1/payment_intents" && c.method === "POST",
200
+ ),
201
+ ).toHaveLength(1);
202
+ });