@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,139 @@
1
+ import { v } from "convex/values";
2
+ import { mutation } from "../_generated/server.js";
3
+ import { limitPolicy } from "../../client/usage/allowanceTerms.js";
4
+ import {
5
+ terms,
6
+ json,
7
+ policyRow,
8
+ overlapping,
9
+ active,
10
+ history,
11
+ canonical,
12
+ scopeOverlap,
13
+ } from "./helpers.js";
14
+ import {
15
+ reserve as reserveUnits,
16
+ release as releaseUnits,
17
+ } from "./reservations.js";
18
+ import { scopeValidator } from "../usage/schema.js";
19
+ export const configure = mutation({
20
+ args: {
21
+ bindingJson: v.string(),
22
+ policyJson: v.string(),
23
+ expectedRevision: v.number(),
24
+ },
25
+ returns: v.object({ revision: v.number() }),
26
+ handler: async (ctx, args) => {
27
+ const original = terms(json(args.bindingJson)),
28
+ policy = limitPolicy(json(args.policyJson), original.binding),
29
+ policyJson = canonical(policy);
30
+ if (
31
+ !Number.isSafeInteger(args.expectedRevision) ||
32
+ args.expectedRevision < 0
33
+ )
34
+ throw new Error("Invalid allowance policy revision");
35
+ await active(ctx, original.binding);
36
+ const prior =
37
+ (await overlapping(
38
+ ctx,
39
+ original.nativeKey,
40
+ original.binding.subscription.period,
41
+ )) ??
42
+ (await scopeOverlap(
43
+ ctx,
44
+ original.scopeKey,
45
+ original.binding.subscription.period,
46
+ ));
47
+ if (prior) {
48
+ if (
49
+ prior.key !== original.key ||
50
+ prior.bindingJson !== original.bindingJson
51
+ )
52
+ throw new Error("Overlapping allowance terms cannot reset usage");
53
+ if (prior.policyJson === policyJson) return { revision: prior.revision };
54
+ if (prior.revision !== args.expectedRevision)
55
+ throw new Error("Stale allowance policy revision");
56
+ await ctx.db.patch("usageAllowancePolicies", prior._id, {
57
+ policyJson,
58
+ revision: prior.revision + 1,
59
+ });
60
+ await history(ctx, prior, "policy", {
61
+ revision: prior.revision + 1,
62
+ policy,
63
+ previousPolicy: JSON.parse(prior.policyJson),
64
+ });
65
+ return { revision: prior.revision + 1 };
66
+ }
67
+ if (args.expectedRevision !== 0)
68
+ throw new Error("Stale allowance policy revision");
69
+ // Enable accounting before any accepted usage in this scope/period. Existing
70
+ // unaccounted history must be reconciled rather than silently granting units.
71
+ const existing = await ctx.db
72
+ .query("usageEvents")
73
+ .withIndex("by_scope_time", (q) =>
74
+ q
75
+ .eq("scopeKey", original.scopeKey)
76
+ .gte("occurredAt", original.binding.subscription.period.start)
77
+ .lt("occurredAt", original.binding.subscription.period.end),
78
+ )
79
+ .first();
80
+ if (existing)
81
+ throw new Error(
82
+ "Existing period usage requires reconciliation before allowance setup",
83
+ );
84
+ const id = await ctx.db.insert("usageAllowancePolicies", {
85
+ key: original.key,
86
+ nativeKey: original.nativeKey,
87
+ scopeKey: original.scopeKey,
88
+ bindingJson: original.bindingJson,
89
+ start: original.binding.subscription.period.start,
90
+ end: original.binding.subscription.period.end,
91
+ policyJson,
92
+ revision: 1,
93
+ consumed: "0",
94
+ reserved: "0",
95
+ historyCount: 0,
96
+ });
97
+ const row = await policyRow(ctx, original.key);
98
+ if (!row || row._id !== id)
99
+ throw new Error("Allowance setup invariant violated");
100
+ await history(ctx, row, "policy", { revision: 1, policy });
101
+ return { revision: 1 };
102
+ },
103
+ });
104
+ export const reserve = mutation({
105
+ args: { inputJson: v.string(), subscriptionJson: v.string() },
106
+ returns: v.union(
107
+ v.object({
108
+ state: v.literal("denied"),
109
+ reason: v.union(v.literal("not_entitled"), v.literal("hard_limit")),
110
+ revision: v.number(),
111
+ }),
112
+ v.object({
113
+ reservationId: v.id("usageReservations"),
114
+ state: v.union(
115
+ v.literal("reserved"),
116
+ v.literal("committed"),
117
+ v.literal("released"),
118
+ ),
119
+ revision: v.number(),
120
+ }),
121
+ ),
122
+ handler: (ctx, args) =>
123
+ reserveUnits(ctx, args.inputJson, args.subscriptionJson),
124
+ });
125
+ export const release = mutation({
126
+ args: {
127
+ scope: scopeValidator,
128
+ reservationId: v.id("usageReservations"),
129
+ reason: v.union(
130
+ v.literal("work_failed"),
131
+ v.literal("abandoned_before_work"),
132
+ ),
133
+ },
134
+ returns: v.null(),
135
+ handler: async (ctx, args) => {
136
+ await releaseUnits(ctx, args.scope, args.reservationId, args.reason);
137
+ return null;
138
+ },
139
+ });
@@ -0,0 +1,133 @@
1
+ import { paginationOptsValidator } from "convex/server";
2
+ import { v } from "convex/values";
3
+ import { query } from "../_generated/server.js";
4
+ import {
5
+ allowanceStatus,
6
+ limitPolicy,
7
+ } from "../../client/usage/allowanceTerms.js";
8
+ import { terms, json, policyRow, active } from "./helpers.js";
9
+ import { historyDoc } from "./schema.js";
10
+ export const status = query({
11
+ args: { bindingJson: v.string() },
12
+ returns: v.union(v.string(), v.null()),
13
+ handler: async (ctx, args) => {
14
+ const original = terms(json(args.bindingJson)),
15
+ row = await policyRow(ctx, original.key);
16
+ if (!row || row.bindingJson !== original.bindingJson) return null;
17
+ const result = allowanceStatus(
18
+ original.binding,
19
+ limitPolicy(JSON.parse(row.policyJson), original.binding),
20
+ row,
21
+ Math.floor(Date.now() / 1000),
22
+ );
23
+ try {
24
+ await active(ctx, original.binding);
25
+ } catch {
26
+ result.accepting = false;
27
+ }
28
+ return JSON.stringify(result);
29
+ },
30
+ });
31
+ export const readHistory = query({
32
+ args: { bindingJson: v.string(), paginationOpts: paginationOptsValidator },
33
+ returns: v.object({
34
+ page: v.array(historyDoc),
35
+ isDone: v.boolean(),
36
+ continueCursor: v.string(),
37
+ }),
38
+ handler: async (ctx, args) => {
39
+ const original = terms(json(args.bindingJson)),
40
+ row = await policyRow(ctx, original.key);
41
+ if (!row || row.bindingJson !== original.bindingJson)
42
+ throw new Error("Allowance policy unavailable");
43
+ if (
44
+ !Number.isInteger(args.paginationOpts.numItems) ||
45
+ args.paginationOpts.numItems < 1 ||
46
+ args.paginationOpts.numItems > 100
47
+ )
48
+ throw new Error("Invalid allowance history page");
49
+ const result = await ctx.db
50
+ .query("usageAllowanceHistory")
51
+ .withIndex("by_key", (q) => q.eq("key", row.key))
52
+ .order("desc")
53
+ .paginate({
54
+ ...args.paginationOpts,
55
+ maximumRowsRead: 200,
56
+ maximumBytesRead: 1024 * 1024,
57
+ });
58
+ return {
59
+ page: result.page,
60
+ isDone: result.isDone,
61
+ continueCursor: result.continueCursor,
62
+ };
63
+ },
64
+ });
65
+
66
+ export const reconciliation = query({
67
+ args: { bindingJson: v.string() },
68
+ returns: v.object({
69
+ status: v.union(v.literal("matched"), v.literal("held")),
70
+ reason: v.string(),
71
+ consumedScaledQuantity: v.string(),
72
+ reservedScaledQuantity: v.string(),
73
+ acceptedScaledQuantity: v.string(),
74
+ repaired: v.literal(false),
75
+ }),
76
+ handler: async (ctx, args) => {
77
+ const original = terms(json(args.bindingJson)),
78
+ row = await policyRow(ctx, original.key);
79
+ if (!row || row.bindingJson !== original.bindingJson)
80
+ throw new Error("Allowance policy unavailable");
81
+ const events = await ctx.db
82
+ .query("usageEvents")
83
+ .withIndex("by_scope_time", (q) =>
84
+ q
85
+ .eq("scopeKey", row.scopeKey)
86
+ .gte("occurredAt", row.start)
87
+ .lt("occurredAt", row.end),
88
+ )
89
+ .take(501);
90
+ const reservations = await ctx.db
91
+ .query("usageReservations")
92
+ .withIndex("by_account_state", (q) =>
93
+ q.eq("accountKey", row.key).eq("state", "reserved"),
94
+ )
95
+ .take(501);
96
+ let accepted = 0n,
97
+ reserved = 0n,
98
+ complete = events.length <= 500 && reservations.length <= 500;
99
+ for (const event of events) {
100
+ const record = JSON.parse(event.recordJson);
101
+ const reservation = event.reservationId
102
+ ? await ctx.db.get("usageReservations", event.reservationId)
103
+ : null;
104
+ if (
105
+ !reservation ||
106
+ reservation.accountKey !== row.key ||
107
+ reservation.state !== "committed" ||
108
+ reservation.eventId !== event._id ||
109
+ reservation.scaledQuantity !== record.scaledQuantity
110
+ )
111
+ complete = false;
112
+ accepted += BigInt(record.scaledQuantity);
113
+ }
114
+ for (const reservation of reservations)
115
+ reserved += BigInt(reservation.scaledQuantity);
116
+ const matches =
117
+ complete &&
118
+ accepted.toString() === row.consumed &&
119
+ reserved.toString() === row.reserved;
120
+ return {
121
+ status: matches ? ("matched" as const) : ("held" as const),
122
+ reason: matches
123
+ ? "complete_local_accounting"
124
+ : complete
125
+ ? "accounting_mismatch"
126
+ : "local_evidence_incomplete",
127
+ consumedScaledQuantity: row.consumed,
128
+ reservedScaledQuantity: row.reserved,
129
+ acceptedScaledQuantity: accepted.toString(),
130
+ repaired: false as const,
131
+ };
132
+ },
133
+ });
@@ -0,0 +1,220 @@
1
+ import type { Value } from "convex/values";
2
+ import type { MutationCtx } from "../_generated/server.js";
3
+ import type { Doc, Id } from "../_generated/dataModel.js";
4
+ import {
5
+ prepareUsageRecord,
6
+ type PreparedUsageRecord,
7
+ type UsageScope,
8
+ } from "../../client/usage/records.js";
9
+ import {
10
+ allowanceStatus,
11
+ limitPolicy,
12
+ } from "../../client/usage/allowanceTerms.js";
13
+ import { parseUsageQuantity } from "../../client/usage/contracts.js";
14
+ import { subscriptionSnapshot, scopeKey } from "../usage/helpers.js";
15
+ import {
16
+ terms,
17
+ json,
18
+ canonical,
19
+ policyRow,
20
+ active,
21
+ history,
22
+ overlapping,
23
+ scopeOverlap,
24
+ configuredScope,
25
+ } from "./helpers.js";
26
+ export async function reserve(
27
+ ctx: MutationCtx,
28
+ inputJson: string,
29
+ subscriptionJson: string,
30
+ ) {
31
+ const event = prepareUsageRecord(json(inputJson)),
32
+ subscription = subscriptionSnapshot(subscriptionJson),
33
+ original = terms({
34
+ scope: event.scope,
35
+ binding: event.binding,
36
+ subscription,
37
+ });
38
+ const input = canonical(event),
39
+ sub = canonical(subscription);
40
+ const prior = await ctx.db
41
+ .query("usageReservations")
42
+ .withIndex("by_scope_source", (q) =>
43
+ q
44
+ .eq("scopeKey", original.scopeKey)
45
+ .eq("sourceEventId", event.sourceEventId),
46
+ )
47
+ .unique();
48
+ if (prior) {
49
+ if (
50
+ prior.accountingKind !== "allowance" ||
51
+ prior.inputJson !== input ||
52
+ prior.subscriptionJson !== sub
53
+ )
54
+ throw new Error("Allowance reservation replay conflict");
55
+ return {
56
+ reservationId: prior._id,
57
+ state: prior.state,
58
+ revision: Number(prior.allocationsJson),
59
+ };
60
+ }
61
+ const accepted = await ctx.db
62
+ .query("usageEvents")
63
+ .withIndex("by_identity", (q) => q.eq("identity", event.identity))
64
+ .unique();
65
+ if (accepted) throw new Error("Accepted usage cannot be reserved again");
66
+ const row = await policyRow(ctx, original.key);
67
+ if (!row || row.bindingJson !== original.bindingJson)
68
+ throw new Error("Allowance policy unavailable");
69
+ await active(ctx, original.binding, event);
70
+ const policy = limitPolicy(JSON.parse(row.policyJson), original.binding),
71
+ status = allowanceStatus(
72
+ original.binding,
73
+ policy,
74
+ row,
75
+ Math.floor(Date.now() / 1000),
76
+ );
77
+ if (!policy.entitled)
78
+ return {
79
+ state: "denied" as const,
80
+ reason: "not_entitled" as const,
81
+ revision: row.revision,
82
+ };
83
+ if (
84
+ status.hardLimitRemainingQuantity !== null &&
85
+ BigInt(event.scaledQuantity) >
86
+ BigInt(
87
+ parseUsageQuantity(
88
+ status.hardLimitRemainingQuantity,
89
+ event.binding.plan.unit.precision,
90
+ ).scaledQuantity,
91
+ )
92
+ )
93
+ return {
94
+ state: "denied" as const,
95
+ reason: "hard_limit" as const,
96
+ revision: row.revision,
97
+ };
98
+ const reserved = BigInt(row.reserved) + BigInt(event.scaledQuantity);
99
+ if (reserved + BigInt(row.consumed) > 999999999999999999n)
100
+ throw new Error("Allowance accounting quantity bound exceeded");
101
+ const reservationId = await ctx.db.insert("usageReservations", {
102
+ scopeKey: original.scopeKey,
103
+ sourceEventId: event.sourceEventId,
104
+ planJson: JSON.stringify(event.binding.plan),
105
+ scaledQuantity: event.scaledQuantity,
106
+ state: "reserved",
107
+ accountingKind: "allowance",
108
+ accountKey: row.key,
109
+ inputJson: input,
110
+ subscriptionJson: sub,
111
+ allocationsJson: String(row.revision),
112
+ });
113
+ await ctx.db.patch("usageAllowancePolicies", row._id, {
114
+ reserved: reserved.toString(),
115
+ });
116
+ await history(ctx, row, "reservation", {
117
+ reservationId,
118
+ event,
119
+ subscription,
120
+ revision: row.revision,
121
+ });
122
+ return { reservationId, state: "reserved" as const, revision: row.revision };
123
+ }
124
+ export async function requireReservation(
125
+ ctx: MutationCtx,
126
+ event: PreparedUsageRecord,
127
+ subscription: ReturnType<typeof subscriptionSnapshot>,
128
+ reservation: Doc<"usageReservations"> | null,
129
+ ) {
130
+ if (event.binding.plan.model === "prepaid") return;
131
+ const original = terms({
132
+ scope: event.scope,
133
+ binding: event.binding,
134
+ subscription,
135
+ });
136
+ const row =
137
+ (await overlapping(ctx, original.nativeKey, subscription.period)) ??
138
+ (await scopeOverlap(ctx, original.scopeKey, subscription.period));
139
+ if (!row && (await configuredScope(ctx, original)))
140
+ throw new Error(
141
+ "New allowance period requires policy configuration and reservation",
142
+ );
143
+ if (
144
+ row &&
145
+ (row.bindingJson !== original.bindingJson ||
146
+ !reservation ||
147
+ reservation.accountingKind !== "allowance" ||
148
+ reservation.accountKey !== row.key)
149
+ )
150
+ throw new Error("Matching allowance reservation required");
151
+ }
152
+ export async function commit(
153
+ ctx: MutationCtx,
154
+ reservation: Doc<"usageReservations">,
155
+ event: Value,
156
+ subscription: Value,
157
+ eventId: Id<"usageEvents">,
158
+ ) {
159
+ if (
160
+ reservation.accountingKind !== "allowance" ||
161
+ !reservation.accountKey ||
162
+ reservation.inputJson !== canonical(event) ||
163
+ reservation.subscriptionJson !== canonical(subscription)
164
+ )
165
+ throw new Error("Allowance reservation provenance mismatch");
166
+ const row = await policyRow(ctx, reservation.accountKey);
167
+ if (!row || BigInt(row.reserved) < BigInt(reservation.scaledQuantity))
168
+ throw new Error("Allowance reservation backing unavailable");
169
+ await ctx.db.patch("usageAllowancePolicies", row._id, {
170
+ reserved: (
171
+ BigInt(row.reserved) - BigInt(reservation.scaledQuantity)
172
+ ).toString(),
173
+ consumed: (
174
+ BigInt(row.consumed) + BigInt(reservation.scaledQuantity)
175
+ ).toString(),
176
+ });
177
+ await history(ctx, row, "commit", {
178
+ reservationId: reservation._id,
179
+ eventId,
180
+ revision: Number(reservation.allocationsJson),
181
+ scaledQuantity: reservation.scaledQuantity,
182
+ });
183
+ }
184
+ export async function release(
185
+ ctx: MutationCtx,
186
+ scope: UsageScope,
187
+ reservationId: Id<"usageReservations">,
188
+ reason: string,
189
+ ) {
190
+ const row = await ctx.db.get("usageReservations", reservationId);
191
+ if (
192
+ !row ||
193
+ row.scopeKey !== scopeKey(scope) ||
194
+ row.accountingKind !== "allowance" ||
195
+ !row.accountKey
196
+ )
197
+ throw new Error("Allowance reservation unavailable");
198
+ if (row.state === "committed" || row.eventId)
199
+ throw new Error("Committed usage requires an auditable correction");
200
+ if (row.state === "released") {
201
+ if (row.releaseReason !== reason)
202
+ throw new Error("Allowance release replay conflict");
203
+ return;
204
+ }
205
+ const policy = await policyRow(ctx, row.accountKey);
206
+ if (!policy || BigInt(policy.reserved) < BigInt(row.scaledQuantity))
207
+ throw new Error("Allowance reservation invariant violated");
208
+ await ctx.db.patch("usageAllowancePolicies", policy._id, {
209
+ reserved: (BigInt(policy.reserved) - BigInt(row.scaledQuantity)).toString(),
210
+ });
211
+ await ctx.db.patch("usageReservations", row._id, {
212
+ state: "released",
213
+ releaseReason: reason,
214
+ });
215
+ await history(ctx, policy, "release", {
216
+ reservationId,
217
+ reason,
218
+ scaledQuantity: row.scaledQuantity,
219
+ });
220
+ }
@@ -0,0 +1,36 @@
1
+ import { defineTable } from "convex/server";
2
+ import { v } from "convex/values";
3
+ export const fields = {
4
+ key: v.string(),
5
+ nativeKey: v.string(),
6
+ scopeKey: v.string(),
7
+ bindingJson: v.string(),
8
+ start: v.number(),
9
+ end: v.number(),
10
+ policyJson: v.string(),
11
+ revision: v.number(),
12
+ consumed: v.string(),
13
+ reserved: v.string(),
14
+ historyCount: v.number(),
15
+ };
16
+ export const policiesTable = defineTable(fields)
17
+ .index("by_key", ["key"])
18
+ .index("by_native_start", ["nativeKey", "start"])
19
+ .index("by_scope_start", ["scopeKey", "start"]);
20
+ export const historyFields = {
21
+ key: v.string(),
22
+ kind: v.union(
23
+ v.literal("policy"),
24
+ v.literal("reservation"),
25
+ v.literal("commit"),
26
+ v.literal("release"),
27
+ ),
28
+ evidenceJson: v.string(),
29
+ at: v.number(),
30
+ };
31
+ export const historyDoc = v.object({
32
+ _id: v.id("usageAllowanceHistory"),
33
+ _creationTime: v.number(),
34
+ ...historyFields,
35
+ });
36
+ export const historyTable = defineTable(historyFields).index("by_key", ["key"]);