@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,300 @@
1
+ import { scopeValidator } from "../usage/schema.js";
2
+ import { scopeKey } from "../usage/helpers.js";
3
+ import { account, purchase } from "./helpers.js";
4
+ import { creditAllocations } from "./reservations.js";
5
+ import type { Id } from "../_generated/dataModel.js";
6
+ import { subscriptionSnapshot } from "../usage/helpers.js";
7
+ import type { PreparedUsageRecord } from "../../client/usage/records.js";
8
+ import { canonicalFingerprint } from "../operationEvidence/canonical.js";
9
+ import { intentDoc } from "../usageSubscriptions/schema.js";
10
+ import { activeEnrollment } from "./helpers.js";
11
+ import {
12
+ paginationOptsValidator,
13
+ paginationResultValidator,
14
+ } from "convex/server";
15
+ import { paginator } from "convex-helpers/server/pagination";
16
+ import { v } from "convex/values";
17
+ import { query } from "../_generated/server.js";
18
+ import schema from "../schema.js";
19
+ import { purchaseDoc, grantDoc, historyDoc } from "./schema.js";
20
+ import { accountTerms, boundedJson, grants } from "./helpers.js";
21
+ import type {
22
+ UsageCreditBinding,
23
+ UsageCreditBalance,
24
+ } from "../../client/usage/creditTerms.js";
25
+ import { decimalFromScaled } from "../../client/usage/summary.js";
26
+ export const getPurchase = query({
27
+ args: { bindingJson: v.string(), purchaseId: v.string() },
28
+ returns: v.union(purchaseDoc, v.null()),
29
+ handler: async (ctx, args) => {
30
+ if (!args.purchaseId || args.purchaseId.length > 100)
31
+ throw new Error("Invalid credit purchase identity");
32
+ const original = await accountTerms(
33
+ boundedJson(args.bindingJson) as UsageCreditBinding,
34
+ );
35
+ const key = await canonicalFingerprint([original.key, args.purchaseId]);
36
+ return ctx.db
37
+ .query("usageCreditPurchases")
38
+ .withIndex("by_key", (q) => q.eq("key", key))
39
+ .unique();
40
+ },
41
+ });
42
+ export const getByKey = query({
43
+ args: { key: v.string() },
44
+ returns: v.union(purchaseDoc, v.null()),
45
+ handler: (ctx, args) =>
46
+ ctx.db
47
+ .query("usageCreditPurchases")
48
+ .withIndex("by_key", (q) => q.eq("key", args.key))
49
+ .unique(),
50
+ });
51
+ export const balance = query({
52
+ args: { bindingJson: v.string() },
53
+ returns: v.object({
54
+ availableQuantity: v.string(),
55
+ reservedQuantity: v.string(),
56
+ consumedQuantity: v.string(),
57
+ expiredQuantity: v.string(),
58
+ frozenQuantity: v.string(),
59
+ precision: v.number(),
60
+ currency: v.string(),
61
+ unit: v.string(),
62
+ status: v.union(v.literal("available"), v.literal("held")),
63
+ cashCollection: v.literal("none"),
64
+ }),
65
+ handler: async (ctx, args): Promise<UsageCreditBalance> => {
66
+ const original = await accountTerms(
67
+ boundedJson(args.bindingJson) as UsageCreditBinding,
68
+ );
69
+ const ledger = await ctx.db
70
+ .query("usageCreditAccounts")
71
+ .withIndex("by_key", (q) => q.eq("key", original.key))
72
+ .unique();
73
+ const rows = ledger ? await grants(ctx, original.key) : [];
74
+ let available = 0n,
75
+ reserved = 0n,
76
+ consumed = 0n,
77
+ expired = 0n,
78
+ frozen = 0n;
79
+ for (const row of rows) {
80
+ reserved += BigInt(row.reserved);
81
+ consumed += BigInt(row.consumed);
82
+ if (row.nativeExpired) expired += BigInt(row.available);
83
+ else if (row.frozen) frozen += BigInt(row.available);
84
+ else if (row.expiresAt !== null && row.expiresAt <= Date.now() / 1000)
85
+ expired += BigInt(row.available);
86
+ else if (row.effectiveAt <= Date.now() / 1000)
87
+ available += BigInt(row.available);
88
+ }
89
+ const plan = original.binding.binding.plan,
90
+ precision = plan.unit.precision;
91
+ const held = !!ledger?.frozenReason || !!ledger?.closed;
92
+ return {
93
+ availableQuantity: decimalFromScaled(held ? 0n : available, precision),
94
+ reservedQuantity: decimalFromScaled(reserved, precision),
95
+ consumedQuantity: decimalFromScaled(consumed, precision),
96
+ expiredQuantity: decimalFromScaled(expired, precision),
97
+ frozenQuantity: decimalFromScaled(
98
+ frozen + (held ? available : 0n),
99
+ precision,
100
+ ),
101
+ precision,
102
+ currency: plan.rate.currency,
103
+ unit: plan.unit.name,
104
+ status: held ? "held" : "available",
105
+ cashCollection: "none",
106
+ };
107
+ },
108
+ });
109
+ export const readGrants = query({
110
+ args: { bindingJson: v.string(), paginationOpts: paginationOptsValidator },
111
+ returns: paginationResultValidator(grantDoc),
112
+ handler: async (ctx, args) => {
113
+ const original = await accountTerms(
114
+ boundedJson(args.bindingJson) as UsageCreditBinding,
115
+ );
116
+ if (args.paginationOpts.numItems < 1 || args.paginationOpts.numItems > 100)
117
+ throw new Error("Credit page limit must be 1–100");
118
+ return paginator(ctx.db, schema)
119
+ .query("usageCreditGrants")
120
+ .withIndex("by_account", (q) => q.eq("accountKey", original.key))
121
+ .paginate({
122
+ ...args.paginationOpts,
123
+ maximumRowsRead: 200,
124
+ maximumBytesRead: 1000000,
125
+ });
126
+ },
127
+ });
128
+ export const readHistory = query({
129
+ args: { bindingJson: v.string(), paginationOpts: paginationOptsValidator },
130
+ returns: paginationResultValidator(historyDoc),
131
+ handler: async (ctx, args) => {
132
+ const original = await accountTerms(
133
+ boundedJson(args.bindingJson) as UsageCreditBinding,
134
+ );
135
+ if (args.paginationOpts.numItems < 1 || args.paginationOpts.numItems > 100)
136
+ throw new Error("Credit page limit must be 1–100");
137
+ return paginator(ctx.db, schema)
138
+ .query("usageCreditHistory")
139
+ .withIndex("by_account", (q) => q.eq("accountKey", original.key))
140
+ .paginate({
141
+ ...args.paginationOpts,
142
+ maximumRowsRead: 200,
143
+ maximumBytesRead: 1000000,
144
+ });
145
+ },
146
+ });
147
+
148
+ export const context = query({
149
+ args: { bindingJson: v.string() },
150
+ returns: intentDoc,
151
+ handler: async (ctx, args) => {
152
+ const original = await accountTerms(
153
+ boundedJson(args.bindingJson) as UsageCreditBinding,
154
+ );
155
+ return (await activeEnrollment(ctx, original.binding)).intent;
156
+ },
157
+ });
158
+
159
+ export const invoiceUsage = query({
160
+ args: {
161
+ bindingJson: v.string(),
162
+ subscriptionId: v.string(),
163
+ subscriptionItemId: v.string(),
164
+ start: v.number(),
165
+ end: v.number(),
166
+ },
167
+ returns: v.object({
168
+ complete: v.boolean(),
169
+ valid: v.boolean(),
170
+ scaledQuantity: v.string(),
171
+ }),
172
+ handler: async (ctx, args) => {
173
+ const original = await accountTerms(
174
+ boundedJson(args.bindingJson) as UsageCreditBinding,
175
+ );
176
+ if (
177
+ !Number.isSafeInteger(args.start) ||
178
+ !Number.isSafeInteger(args.end) ||
179
+ args.start >= args.end
180
+ )
181
+ throw new Error("Invalid credit invoice period");
182
+ const rows = await ctx.db
183
+ .query("usageEvents")
184
+ .withIndex("by_scope_subscription_time", (q) =>
185
+ q
186
+ .eq("scopeKey", original.scopeKey)
187
+ .eq("subscriptionId", args.subscriptionId)
188
+ .gte("occurredAt", args.start)
189
+ .lt("occurredAt", args.end),
190
+ )
191
+ .take(501);
192
+ let quantity = 0n,
193
+ valid = true;
194
+ for (const row of rows.slice(0, 500)) {
195
+ const event = JSON.parse(row.recordJson) as PreparedUsageRecord;
196
+ const subscription = subscriptionSnapshot(row.subscriptionJson);
197
+ const binding = await accountTerms(event);
198
+ if (
199
+ binding.key !== original.key ||
200
+ subscription.subscriptionItemId !== args.subscriptionItemId ||
201
+ subscription.period.start !== args.start ||
202
+ subscription.period.end !== args.end
203
+ )
204
+ valid = false;
205
+ const outbox = await ctx.db
206
+ .query("usageOutbox")
207
+ .withIndex("by_event", (q) => q.eq("eventId", row._id))
208
+ .unique();
209
+ const error = await ctx.db
210
+ .query("usageDeliveryErrors")
211
+ .withIndex("by_event", (q) => q.eq("eventId", row._id))
212
+ .first();
213
+ if (outbox?.state !== "provider_accepted" || error) valid = false;
214
+ quantity += BigInt(event.scaledQuantity);
215
+ }
216
+ return {
217
+ complete: rows.length <= 500,
218
+ valid,
219
+ scaledQuantity: quantity.toString(),
220
+ };
221
+ },
222
+ });
223
+
224
+ export const deliveryBacking = query({
225
+ args: { scope: scopeValidator, eventId: v.id("usageEvents") },
226
+ returns: v.object({
227
+ held: v.boolean(),
228
+ purchases: v.array(purchaseDoc),
229
+ grants: v.array(grantDoc),
230
+ }),
231
+ handler: async (ctx, args) => {
232
+ const event = await ctx.db.get("usageEvents", args.eventId);
233
+ if (
234
+ !event ||
235
+ event.scopeKey !== scopeKey(args.scope) ||
236
+ !event.reservationId
237
+ )
238
+ throw new Error("Credit delivery source unavailable");
239
+ const reservation = await ctx.db.get(
240
+ "usageReservations",
241
+ event.reservationId,
242
+ );
243
+ if (
244
+ !reservation ||
245
+ reservation.accountingKind !== "prepaid" ||
246
+ reservation.state !== "committed" ||
247
+ reservation.eventId !== event._id
248
+ )
249
+ throw new Error("Committed credit backing required");
250
+ const original = await accountTerms(
251
+ JSON.parse(event.recordJson) as PreparedUsageRecord,
252
+ );
253
+ const ledger = await account(ctx, original.key);
254
+ const allocations = creditAllocations.parse(
255
+ JSON.parse(reservation.allocationsJson!),
256
+ );
257
+ const selected = [],
258
+ purchases = [];
259
+ for (const allocation of allocations) {
260
+ const grant = await ctx.db.get(
261
+ "usageCreditGrants",
262
+ allocation.grantId as Id<"usageCreditGrants">,
263
+ );
264
+ if (!grant || grant.accountKey !== original.key)
265
+ throw new Error("Credit allocation scope mismatch");
266
+ selected.push(grant);
267
+ purchases.push(await purchase(ctx, grant.purchaseKey));
268
+ }
269
+ return {
270
+ held:
271
+ ledger.closed ||
272
+ !!ledger.frozenReason ||
273
+ selected.some((g) => g.frozen),
274
+ grants: selected,
275
+ purchases,
276
+ };
277
+ },
278
+ });
279
+
280
+ export const capacity = query({
281
+ args: { bindingJson: v.string() },
282
+ returns: v.number(),
283
+ handler: async (ctx, args) => {
284
+ const { binding } = await accountTerms(
285
+ boundedJson(args.bindingJson) as UsageCreditBinding,
286
+ );
287
+ const key = JSON.stringify([
288
+ binding.scope.stripeAccountId,
289
+ binding.scope.livemode,
290
+ binding.binding.stripeCustomerId,
291
+ ]);
292
+ const rows = await ctx.db
293
+ .query("usageCreditPurchases")
294
+ .withIndex("by_customer_capacity", (q) =>
295
+ q.eq("nativeCustomerKey", key).eq("capacityReserved", true),
296
+ )
297
+ .take(101);
298
+ return rows.length;
299
+ },
300
+ });
@@ -0,0 +1,214 @@
1
+ import { z } from "zod";
2
+ import { convexToJson, type Value } from "convex/values";
3
+ import type { MutationCtx } from "../_generated/server.js";
4
+ import type { Doc, Id } from "../_generated/dataModel.js";
5
+ import { prepareUsageRecord } from "../../client/usage/records.js";
6
+ import { creditCost } from "../../client/usage/creditTerms.js";
7
+ import { scopeKey, subscriptionSnapshot } from "../usage/helpers.js";
8
+ import {
9
+ accountTerms,
10
+ account,
11
+ grants,
12
+ activeEnrollment,
13
+ history,
14
+ boundedJson,
15
+ } from "./helpers.js";
16
+ export const creditAllocations = z
17
+ .array(
18
+ z.strictObject({
19
+ grantId: z.string().min(1).max(100),
20
+ quantity: z.string().regex(/^[1-9]\d{0,17}$/),
21
+ }),
22
+ )
23
+ .min(1)
24
+ .max(10);
25
+ const canonical = (value: Value) => JSON.stringify(convexToJson(value));
26
+ export async function reserve(
27
+ ctx: MutationCtx,
28
+ inputJson: string,
29
+ subscriptionJson: string,
30
+ ) {
31
+ const event = prepareUsageRecord(boundedJson(inputJson));
32
+ const subscription = subscriptionSnapshot(subscriptionJson);
33
+ const original = await accountTerms(event),
34
+ key = original.scopeKey;
35
+ creditCost(event.binding.plan, event.scaledQuantity);
36
+ const input = canonical(event),
37
+ sub = canonical(subscription);
38
+ const prior = await ctx.db
39
+ .query("usageReservations")
40
+ .withIndex("by_scope_source", (q) =>
41
+ q.eq("scopeKey", key).eq("sourceEventId", event.sourceEventId),
42
+ )
43
+ .unique();
44
+ if (prior) {
45
+ if (
46
+ prior.accountingKind !== "prepaid" ||
47
+ prior.inputJson !== input ||
48
+ prior.subscriptionJson !== sub
49
+ )
50
+ throw new Error("Credit reservation replay conflict");
51
+ return { reservationId: prior._id, state: prior.state };
52
+ }
53
+ const ledger = await account(ctx, original.key);
54
+ if (ledger.closed || ledger.frozenReason)
55
+ throw new Error("Credit account requires reconciliation");
56
+ const { view, item } = await activeEnrollment(ctx, original.binding);
57
+ const now = Math.floor(Date.now() / 1000);
58
+ if (
59
+ subscription.subscriptionId !== view.subscriptionId ||
60
+ subscription.subscriptionItemId !== item.id ||
61
+ subscription.stripePriceId !== item.stripePriceId ||
62
+ subscription.period.start !== item.period.start ||
63
+ subscription.period.end !== item.period.end ||
64
+ event.occurredAt < subscription.period.start ||
65
+ event.occurredAt >= subscription.period.end ||
66
+ event.occurredAt < now - 35 * 86400 ||
67
+ event.occurredAt > now + 300
68
+ )
69
+ throw new Error("Credit reservation subscription period mismatch");
70
+ const rows = (await grants(ctx, ledger.key)).filter(
71
+ (g) =>
72
+ !g.frozen &&
73
+ g.effectiveAt <= now &&
74
+ (g.expiresAt === null ||
75
+ g.expiresAt > subscription.period.end + 72 * 3600),
76
+ );
77
+ rows.sort(
78
+ (a, b) =>
79
+ (a.expiresAt ?? Number.MAX_SAFE_INTEGER) -
80
+ (b.expiresAt ?? Number.MAX_SAFE_INTEGER) ||
81
+ a.effectiveAt - b.effectiveAt ||
82
+ a.nativeCreated - b.nativeCreated ||
83
+ a.creditGrantId.localeCompare(b.creditGrantId),
84
+ );
85
+ let remaining = BigInt(event.scaledQuantity);
86
+ const selected: z.infer<typeof creditAllocations> = [];
87
+ for (const grant of rows) {
88
+ const quantity =
89
+ BigInt(grant.available) < remaining ? BigInt(grant.available) : remaining;
90
+ if (quantity === 0n) continue;
91
+ if (selected.length === 10) break;
92
+ creditCost(event.binding.plan, quantity.toString());
93
+ selected.push({ grantId: grant._id, quantity: quantity.toString() });
94
+ await ctx.db.patch("usageCreditGrants", grant._id, {
95
+ available: (BigInt(grant.available) - quantity).toString(),
96
+ reserved: (BigInt(grant.reserved) + quantity).toString(),
97
+ });
98
+ remaining -= quantity;
99
+ if (remaining === 0n) break;
100
+ }
101
+ if (remaining > 0n)
102
+ throw new Error("Insufficient prepaid credits within bounded allocation");
103
+ const id = await ctx.db.insert("usageReservations", {
104
+ scopeKey: key,
105
+ sourceEventId: event.sourceEventId,
106
+ planJson: JSON.stringify(event.binding.plan),
107
+ scaledQuantity: event.scaledQuantity,
108
+ state: "reserved",
109
+ accountingKind: "prepaid",
110
+ accountKey: ledger.key,
111
+ inputJson: input,
112
+ subscriptionJson: sub,
113
+ allocationsJson: JSON.stringify(selected),
114
+ });
115
+ await history(ctx, ledger.key, "reservation", id, {
116
+ input: event,
117
+ subscription,
118
+ allocations: selected,
119
+ });
120
+ return { reservationId: id, state: "reserved" as const };
121
+ }
122
+ export async function commit(
123
+ ctx: MutationCtx,
124
+ reservation: Doc<"usageReservations">,
125
+ input: Value,
126
+ subscription: Value,
127
+ eventId: Id<"usageEvents">,
128
+ ) {
129
+ if (
130
+ reservation.accountingKind !== "prepaid" ||
131
+ !reservation.accountKey ||
132
+ reservation.inputJson !== canonical(input) ||
133
+ reservation.subscriptionJson !== canonical(subscription)
134
+ )
135
+ throw new Error("Prepaid reservation provenance mismatch");
136
+ const ledger = await account(ctx, reservation.accountKey);
137
+ if (ledger.closed || ledger.frozenReason)
138
+ throw new Error("Credit account requires reconciliation");
139
+ const selected = creditAllocations.parse(
140
+ JSON.parse(reservation.allocationsJson!),
141
+ );
142
+ for (const item of selected) {
143
+ const grant = await ctx.db.get(
144
+ "usageCreditGrants",
145
+ item.grantId as Id<"usageCreditGrants">,
146
+ );
147
+ if (
148
+ !grant ||
149
+ grant.accountKey !== ledger.key ||
150
+ grant.frozen ||
151
+ BigInt(grant.reserved) < BigInt(item.quantity)
152
+ )
153
+ throw new Error("Credit reservation backing unavailable");
154
+ await ctx.db.patch("usageCreditGrants", grant._id, {
155
+ reserved: (BigInt(grant.reserved) - BigInt(item.quantity)).toString(),
156
+ consumed: (BigInt(grant.consumed) + BigInt(item.quantity)).toString(),
157
+ });
158
+ }
159
+ await history(ctx, ledger.key, "commit", reservation._id, {
160
+ eventId,
161
+ sourceEventId: reservation.sourceEventId,
162
+ allocations: selected,
163
+ cashCollection: "none",
164
+ });
165
+ }
166
+ export async function release(
167
+ ctx: MutationCtx,
168
+ scope: Parameters<typeof scopeKey>[0],
169
+ reservationId: Id<"usageReservations">,
170
+ reason: string,
171
+ ) {
172
+ if (!["work_failed", "abandoned_before_work"].includes(reason))
173
+ throw new Error("Explicit uncommitted work recovery reason required");
174
+ const row = await ctx.db.get("usageReservations", reservationId);
175
+ if (
176
+ !row ||
177
+ row.scopeKey !== scopeKey(scope) ||
178
+ row.accountingKind !== "prepaid" ||
179
+ !row.accountKey
180
+ )
181
+ throw new Error("Credit reservation unavailable");
182
+ if (row.state === "committed" || row.eventId)
183
+ throw new Error("Committed usage requires an auditable correction");
184
+ if (row.state === "released") {
185
+ if (row.releaseReason !== reason)
186
+ throw new Error("Credit release replay conflict");
187
+ return;
188
+ }
189
+ const selected = creditAllocations.parse(JSON.parse(row.allocationsJson!));
190
+ for (const item of selected) {
191
+ const grant = await ctx.db.get(
192
+ "usageCreditGrants",
193
+ item.grantId as Id<"usageCreditGrants">,
194
+ );
195
+ if (
196
+ !grant ||
197
+ grant.accountKey !== row.accountKey ||
198
+ BigInt(grant.reserved) < BigInt(item.quantity)
199
+ )
200
+ throw new Error("Credit reservation invariant violated");
201
+ await ctx.db.patch("usageCreditGrants", grant._id, {
202
+ reserved: (BigInt(grant.reserved) - BigInt(item.quantity)).toString(),
203
+ available: (BigInt(grant.available) + BigInt(item.quantity)).toString(),
204
+ });
205
+ }
206
+ await ctx.db.patch("usageReservations", row._id, {
207
+ state: "released",
208
+ releaseReason: reason,
209
+ });
210
+ await history(ctx, row.accountKey, "release", row._id, {
211
+ reason,
212
+ allocations: selected,
213
+ });
214
+ }
@@ -0,0 +1,106 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ export const accountFields = {
4
+ key: v.string(),
5
+ scopeKey: v.string(),
6
+ bindingJson: v.string(),
7
+ stripeAccountId: v.string(),
8
+ customerAccount: v.string(),
9
+ closed: v.boolean(),
10
+ purchaseCount: v.number(),
11
+ historyCount: v.number(),
12
+ frozenReason: v.optional(v.string()),
13
+ };
14
+ export const accountsTable = defineTable(accountFields)
15
+ .index("by_key", ["key"])
16
+ .index("by_realm_closed", ["stripeAccountId", "closed"])
17
+ .index("by_payer_closed", ["customerAccount", "closed"]);
18
+ export const purchaseFields = {
19
+ key: v.string(),
20
+ accountKey: v.string(),
21
+ nativeCustomerKey: v.string(),
22
+ capacityReserved: v.boolean(),
23
+ paymentAttemptedAt: v.optional(v.number()),
24
+ termsJson: v.string(),
25
+ firstAttemptAt: v.number(),
26
+ state: v.union(
27
+ v.literal("pending"),
28
+ v.literal("ready"),
29
+ v.literal("frozen"),
30
+ v.literal("canceled"),
31
+ ),
32
+ paymentIntentId: v.optional(v.string()),
33
+ paymentKey: v.optional(v.string()),
34
+ paymentProofJson: v.optional(v.string()),
35
+ refundedAmount: v.optional(v.number()),
36
+ grantFirstAttemptAt: v.optional(v.number()),
37
+ creditGrantId: v.optional(v.string()),
38
+ };
39
+ export const purchaseDoc = v.object({
40
+ _id: v.id("usageCreditPurchases"),
41
+ _creationTime: v.number(),
42
+ ...purchaseFields,
43
+ });
44
+ export const purchasesTable = defineTable(purchaseFields)
45
+ .index("by_key", ["key"])
46
+ .index("by_payment", ["paymentKey"])
47
+ .index("by_customer_capacity", ["nativeCustomerKey", "capacityReserved"])
48
+ .index("by_account", ["accountKey"]);
49
+ export const grantFields = {
50
+ purchaseKey: v.string(),
51
+ accountKey: v.string(),
52
+ creditGrantId: v.string(),
53
+ nativeCustomerKey: v.string(),
54
+ nativeUnused: v.boolean(),
55
+ nativeCreated: v.number(),
56
+ paymentIntentId: v.string(),
57
+ chargeId: v.string(),
58
+ proofJson: v.string(),
59
+ available: v.string(),
60
+ reserved: v.string(),
61
+ consumed: v.string(),
62
+ effectiveAt: v.number(),
63
+ expiresAt: v.union(v.number(), v.null()),
64
+ frozen: v.boolean(),
65
+ nativeExpired: v.optional(v.boolean()),
66
+ nativeObservationJson: v.optional(v.string()),
67
+ observedAt: v.optional(v.number()),
68
+ };
69
+ export const grantDoc = v.object({
70
+ _id: v.id("usageCreditGrants"),
71
+ _creationTime: v.number(),
72
+ ...grantFields,
73
+ });
74
+ export const grantsTable = defineTable(grantFields)
75
+ .index("by_purchase", ["purchaseKey"])
76
+ .index("by_native", ["creditGrantId"])
77
+ .index("by_customer_unused", ["nativeCustomerKey", "nativeUnused"])
78
+ .index("by_account", ["accountKey"]);
79
+ export const historyFields = {
80
+ accountKey: v.string(),
81
+ purchaseKey: v.optional(v.string()),
82
+ kind: v.union(
83
+ v.literal("purchase"),
84
+ v.literal("payment"),
85
+ v.literal("grant"),
86
+ v.literal("reservation"),
87
+ v.literal("commit"),
88
+ v.literal("release"),
89
+ v.literal("observation"),
90
+ v.literal("recovery"),
91
+ v.literal("closure"),
92
+ ),
93
+ sourceKey: v.string(),
94
+ fingerprint: v.string(),
95
+ evidenceJson: v.string(),
96
+ at: v.number(),
97
+ };
98
+ export const historyDoc = v.object({
99
+ _id: v.id("usageCreditHistory"),
100
+ _creationTime: v.number(),
101
+ ...historyFields,
102
+ });
103
+ export const historyTable = defineTable(historyFields)
104
+ .index("by_fingerprint", ["fingerprint"])
105
+ .index("by_account", ["accountKey"])
106
+ .index("by_purchase", ["accountKey", "purchaseKey"]);