@fantastic.dev/better-stripe 0.54.0 → 0.56.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 (282) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +3 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +264 -8
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +132 -4
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +264 -8
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +132 -4
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +9 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/index.js +1 -0
  14. package/dist/client/index.js.map +1 -1
  15. package/dist/client/usage/catalogPrices.d.ts +2 -0
  16. package/dist/client/usage/catalogPrices.d.ts.map +1 -1
  17. package/dist/client/usage/catalogPrices.js +15 -0
  18. package/dist/client/usage/catalogPrices.js.map +1 -1
  19. package/dist/client/usage/client.d.ts +2 -2
  20. package/dist/client/usage/client.d.ts.map +1 -1
  21. package/dist/client/usage/client.js +2 -2
  22. package/dist/client/usage/client.js.map +1 -1
  23. package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
  24. package/dist/client/usage/deliveryProvider.js +26 -1
  25. package/dist/client/usage/deliveryProvider.js.map +1 -1
  26. package/dist/client/usage/index.d.ts +9 -0
  27. package/dist/client/usage/index.d.ts.map +1 -1
  28. package/dist/client/usage/index.js +1 -0
  29. package/dist/client/usage/index.js.map +1 -1
  30. package/dist/client/usage/invoiceObservation.d.ts +38 -0
  31. package/dist/client/usage/invoiceObservation.d.ts.map +1 -0
  32. package/dist/client/usage/invoiceObservation.js +157 -0
  33. package/dist/client/usage/invoiceObservation.js.map +1 -0
  34. package/dist/client/usage/observationClient.d.ts +83 -0
  35. package/dist/client/usage/observationClient.d.ts.map +1 -0
  36. package/dist/client/usage/observationClient.js +157 -0
  37. package/dist/client/usage/observationClient.js.map +1 -0
  38. package/dist/client/usage/observationTypes.d.ts +63 -0
  39. package/dist/client/usage/observationTypes.d.ts.map +1 -0
  40. package/dist/client/usage/observationTypes.js +59 -0
  41. package/dist/client/usage/observationTypes.js.map +1 -0
  42. package/dist/client/usage/providerObservation.d.ts +4 -0
  43. package/dist/client/usage/providerObservation.d.ts.map +1 -0
  44. package/dist/client/usage/providerObservation.js +96 -0
  45. package/dist/client/usage/providerObservation.js.map +1 -0
  46. package/dist/client/usage/reconciliation.d.ts +12 -0
  47. package/dist/client/usage/reconciliation.d.ts.map +1 -0
  48. package/dist/client/usage/reconciliation.js +48 -0
  49. package/dist/client/usage/reconciliation.js.map +1 -0
  50. package/dist/client/usage/subscription.fixtures.d.ts +118 -0
  51. package/dist/client/usage/subscription.fixtures.d.ts.map +1 -0
  52. package/dist/client/usage/subscription.fixtures.js +84 -0
  53. package/dist/client/usage/subscription.fixtures.js.map +1 -0
  54. package/dist/client/usage/subscriptionAbandonment.d.ts +8 -0
  55. package/dist/client/usage/subscriptionAbandonment.d.ts.map +1 -0
  56. package/dist/client/usage/subscriptionAbandonment.js +82 -0
  57. package/dist/client/usage/subscriptionAbandonment.js.map +1 -0
  58. package/dist/client/usage/subscriptionCancellation.d.ts +9 -0
  59. package/dist/client/usage/subscriptionCancellation.d.ts.map +1 -0
  60. package/dist/client/usage/subscriptionCancellation.js +39 -0
  61. package/dist/client/usage/subscriptionCancellation.js.map +1 -0
  62. package/dist/client/usage/subscriptionCheckout.d.ts +52 -0
  63. package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -0
  64. package/dist/client/usage/subscriptionCheckout.js +94 -0
  65. package/dist/client/usage/subscriptionCheckout.js.map +1 -0
  66. package/dist/client/usage/subscriptionClient.d.ts +267 -0
  67. package/dist/client/usage/subscriptionClient.d.ts.map +1 -0
  68. package/dist/client/usage/subscriptionClient.js +93 -0
  69. package/dist/client/usage/subscriptionClient.js.map +1 -0
  70. package/dist/client/usage/subscriptionErrors.d.ts +5 -0
  71. package/dist/client/usage/subscriptionErrors.d.ts.map +1 -0
  72. package/dist/client/usage/subscriptionErrors.js +9 -0
  73. package/dist/client/usage/subscriptionErrors.js.map +1 -0
  74. package/dist/client/usage/subscriptionInvoiceSchema.d.ts +203 -0
  75. package/dist/client/usage/subscriptionInvoiceSchema.d.ts.map +1 -0
  76. package/dist/client/usage/subscriptionInvoiceSchema.js +108 -0
  77. package/dist/client/usage/subscriptionInvoiceSchema.js.map +1 -0
  78. package/dist/client/usage/subscriptionLifecycle.d.ts +80 -0
  79. package/dist/client/usage/subscriptionLifecycle.d.ts.map +1 -0
  80. package/dist/client/usage/subscriptionLifecycle.js +87 -0
  81. package/dist/client/usage/subscriptionLifecycle.js.map +1 -0
  82. package/dist/client/usage/subscriptionProvider.d.ts +111 -0
  83. package/dist/client/usage/subscriptionProvider.d.ts.map +1 -0
  84. package/dist/client/usage/subscriptionProvider.js +147 -0
  85. package/dist/client/usage/subscriptionProvider.js.map +1 -0
  86. package/dist/client/usage/subscriptionTerms.d.ts +161 -0
  87. package/dist/client/usage/subscriptionTerms.d.ts.map +1 -0
  88. package/dist/client/usage/subscriptionTerms.js +242 -0
  89. package/dist/client/usage/subscriptionTerms.js.map +1 -0
  90. package/dist/client/usage/subscriptionTransport.fixtures.d.ts +25 -0
  91. package/dist/client/usage/subscriptionTransport.fixtures.d.ts.map +1 -0
  92. package/dist/client/usage/subscriptionTransport.fixtures.js +203 -0
  93. package/dist/client/usage/subscriptionTransport.fixtures.js.map +1 -0
  94. package/dist/client/usage/summary.d.ts +50 -0
  95. package/dist/client/usage/summary.d.ts.map +1 -0
  96. package/dist/client/usage/summary.js +110 -0
  97. package/dist/client/usage/summary.js.map +1 -0
  98. package/dist/client/webhooks/processors.d.ts.map +1 -1
  99. package/dist/client/webhooks/processors.js +2 -0
  100. package/dist/client/webhooks/processors.js.map +1 -1
  101. package/dist/client/webhooks/usageSubscriptions.d.ts +5 -0
  102. package/dist/client/webhooks/usageSubscriptions.d.ts.map +1 -0
  103. package/dist/client/webhooks/usageSubscriptions.js +54 -0
  104. package/dist/client/webhooks/usageSubscriptions.js.map +1 -0
  105. package/dist/component/_generated/api.d.ts +22 -0
  106. package/dist/component/_generated/api.d.ts.map +1 -1
  107. package/dist/component/_generated/api.js.map +1 -1
  108. package/dist/component/_generated/component.d.ts +255 -5
  109. package/dist/component/_generated/component.d.ts.map +1 -1
  110. package/dist/component/accountClosure/mutations.d.ts.map +1 -1
  111. package/dist/component/accountClosure/mutations.js +10 -0
  112. package/dist/component/accountClosure/mutations.js.map +1 -1
  113. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  114. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  115. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  116. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  117. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  118. package/dist/component/earnings/triggers.d.ts +296 -22
  119. package/dist/component/earnings/triggers.d.ts.map +1 -1
  120. package/dist/component/payoutRelease/queries.d.ts +2 -2
  121. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  122. package/dist/component/refundHistory/queries.d.ts +1 -1
  123. package/dist/component/schema.d.ts +132 -4
  124. package/dist/component/schema.js +8 -0
  125. package/dist/component/schema.js.map +1 -1
  126. package/dist/component/usage/mutations.d.ts.map +1 -1
  127. package/dist/component/usage/mutations.js +5 -0
  128. package/dist/component/usage/mutations.js.map +1 -1
  129. package/dist/component/usage/queries.d.ts +2 -0
  130. package/dist/component/usage/queries.d.ts.map +1 -1
  131. package/dist/component/usage/schema.d.ts +21 -9
  132. package/dist/component/usage/schema.d.ts.map +1 -1
  133. package/dist/component/usage/schema.js +5 -1
  134. package/dist/component/usage/schema.js.map +1 -1
  135. package/dist/component/usageDelivery/fields.d.ts +4 -2
  136. package/dist/component/usageDelivery/fields.d.ts.map +1 -1
  137. package/dist/component/usageDelivery/fields.js +3 -1
  138. package/dist/component/usageDelivery/fields.js.map +1 -1
  139. package/dist/component/usageDelivery/helpers.d.ts +5 -3
  140. package/dist/component/usageDelivery/helpers.d.ts.map +1 -1
  141. package/dist/component/usageDelivery/mutations.d.ts +3 -3
  142. package/dist/component/usageDelivery/mutations.d.ts.map +1 -1
  143. package/dist/component/usageDelivery/mutations.js +8 -1
  144. package/dist/component/usageDelivery/mutations.js.map +1 -1
  145. package/dist/component/usageDelivery/queries.d.ts +19 -3
  146. package/dist/component/usageDelivery/queries.d.ts.map +1 -1
  147. package/dist/component/usageDelivery/queries.js +20 -3
  148. package/dist/component/usageDelivery/queries.js.map +1 -1
  149. package/dist/component/usageDelivery/schema.d.ts +2 -2
  150. package/dist/component/usageDelivery/steps.d.ts +1 -1
  151. package/dist/component/usageDelivery/steps.d.ts.map +1 -1
  152. package/dist/component/usageDelivery/steps.js +20 -2
  153. package/dist/component/usageDelivery/steps.js.map +1 -1
  154. package/dist/component/usageObservations/helpers.d.ts +38 -0
  155. package/dist/component/usageObservations/helpers.d.ts.map +1 -0
  156. package/dist/component/usageObservations/helpers.js +80 -0
  157. package/dist/component/usageObservations/helpers.js.map +1 -0
  158. package/dist/component/usageObservations/history.d.ts +6 -0
  159. package/dist/component/usageObservations/history.d.ts.map +1 -0
  160. package/dist/component/usageObservations/history.js +29 -0
  161. package/dist/component/usageObservations/history.js.map +1 -0
  162. package/dist/component/usageObservations/mutations.d.ts +6 -0
  163. package/dist/component/usageObservations/mutations.d.ts.map +1 -0
  164. package/dist/component/usageObservations/mutations.js +39 -0
  165. package/dist/component/usageObservations/mutations.js.map +1 -0
  166. package/dist/component/usageObservations/queries.d.ts +78 -0
  167. package/dist/component/usageObservations/queries.d.ts.map +1 -0
  168. package/dist/component/usageObservations/queries.js +131 -0
  169. package/dist/component/usageObservations/queries.js.map +1 -0
  170. package/dist/component/usageObservations/schema.d.ts +72 -0
  171. package/dist/component/usageObservations/schema.d.ts.map +1 -0
  172. package/dist/component/usageObservations/schema.js +29 -0
  173. package/dist/component/usageObservations/schema.js.map +1 -0
  174. package/dist/component/usageSubscriptions/abandonment.d.ts +4 -0
  175. package/dist/component/usageSubscriptions/abandonment.d.ts.map +1 -0
  176. package/dist/component/usageSubscriptions/abandonment.js +59 -0
  177. package/dist/component/usageSubscriptions/abandonment.js.map +1 -0
  178. package/dist/component/usageSubscriptions/acceptance.d.ts +11 -0
  179. package/dist/component/usageSubscriptions/acceptance.d.ts.map +1 -0
  180. package/dist/component/usageSubscriptions/acceptance.js +38 -0
  181. package/dist/component/usageSubscriptions/acceptance.js.map +1 -0
  182. package/dist/component/usageSubscriptions/helpers.d.ts +39 -0
  183. package/dist/component/usageSubscriptions/helpers.d.ts.map +1 -0
  184. package/dist/component/usageSubscriptions/helpers.js +28 -0
  185. package/dist/component/usageSubscriptions/helpers.js.map +1 -0
  186. package/dist/component/usageSubscriptions/history.d.ts +46 -0
  187. package/dist/component/usageSubscriptions/history.d.ts.map +1 -0
  188. package/dist/component/usageSubscriptions/history.js +46 -0
  189. package/dist/component/usageSubscriptions/history.js.map +1 -0
  190. package/dist/component/usageSubscriptions/mutations.d.ts +64 -0
  191. package/dist/component/usageSubscriptions/mutations.d.ts.map +1 -0
  192. package/dist/component/usageSubscriptions/mutations.js +252 -0
  193. package/dist/component/usageSubscriptions/mutations.js.map +1 -0
  194. package/dist/component/usageSubscriptions/queries.d.ts +81 -0
  195. package/dist/component/usageSubscriptions/queries.d.ts.map +1 -0
  196. package/dist/component/usageSubscriptions/queries.js +70 -0
  197. package/dist/component/usageSubscriptions/queries.js.map +1 -0
  198. package/dist/component/usageSubscriptions/retirement.d.ts +4 -0
  199. package/dist/component/usageSubscriptions/retirement.d.ts.map +1 -0
  200. package/dist/component/usageSubscriptions/retirement.js +80 -0
  201. package/dist/component/usageSubscriptions/retirement.js.map +1 -0
  202. package/dist/component/usageSubscriptions/schema.d.ts +191 -0
  203. package/dist/component/usageSubscriptions/schema.d.ts.map +1 -0
  204. package/dist/component/usageSubscriptions/schema.js +69 -0
  205. package/dist/component/usageSubscriptions/schema.js.map +1 -0
  206. package/dist/test.d.ts +6 -0
  207. package/dist/test.d.ts.map +1 -0
  208. package/dist/test.js +15 -0
  209. package/dist/test.js.map +1 -0
  210. package/docs/README.md +4 -0
  211. package/docs/evidence/native-metering/clock-finalization-run.json +129 -0
  212. package/docs/evidence/native-metering/clock-lag-run.json +111 -0
  213. package/docs/evidence/native-metering/paid-run.json +107 -0
  214. package/docs/evidence/native-metering/promotional-run.json +103 -0
  215. package/docs/metered-usage.md +14 -0
  216. package/docs/metering-setup.md +7 -1
  217. package/docs/usage-observations.md +152 -0
  218. package/docs/usage-subscriptions.md +278 -0
  219. package/package.json +5 -2
  220. package/src/client/index.ts +26 -0
  221. package/src/client/usage/catalogPrices.ts +21 -0
  222. package/src/client/usage/client.ts +2 -2
  223. package/src/client/usage/deliveryProvider.test.ts +70 -1
  224. package/src/client/usage/deliveryProvider.ts +43 -2
  225. package/src/client/usage/index.ts +27 -0
  226. package/src/client/usage/invoiceObservation.test.ts +195 -0
  227. package/src/client/usage/invoiceObservation.ts +203 -0
  228. package/src/client/usage/observationClient.ts +233 -0
  229. package/src/client/usage/observationTypes.ts +101 -0
  230. package/src/client/usage/providerObservation.test.ts +207 -0
  231. package/src/client/usage/providerObservation.ts +124 -0
  232. package/src/client/usage/reconciliation.test.ts +117 -0
  233. package/src/client/usage/reconciliation.ts +86 -0
  234. package/src/client/usage/subscription.fixtures.ts +84 -0
  235. package/src/client/usage/subscriptionAbandonment.test.ts +124 -0
  236. package/src/client/usage/subscriptionAbandonment.ts +116 -0
  237. package/src/client/usage/subscriptionCancellation.ts +90 -0
  238. package/src/client/usage/subscriptionCheckout.test.ts +31 -0
  239. package/src/client/usage/subscriptionCheckout.ts +152 -0
  240. package/src/client/usage/subscriptionClient.test.ts +316 -0
  241. package/src/client/usage/subscriptionClient.ts +204 -0
  242. package/src/client/usage/subscriptionErrors.ts +14 -0
  243. package/src/client/usage/subscriptionInvoiceSchema.ts +116 -0
  244. package/src/client/usage/subscriptionLifecycle.ts +165 -0
  245. package/src/client/usage/subscriptionProvider.test.ts +48 -0
  246. package/src/client/usage/subscriptionProvider.ts +247 -0
  247. package/src/client/usage/subscriptionTerms.test.ts +158 -0
  248. package/src/client/usage/subscriptionTerms.ts +294 -0
  249. package/src/client/usage/subscriptionTransport.fixtures.ts +241 -0
  250. package/src/client/usage/summary.test.ts +222 -0
  251. package/src/client/usage/summary.ts +188 -0
  252. package/src/client/webhooks/processors.ts +2 -0
  253. package/src/client/webhooks/usageSubscriptions.test.ts +162 -0
  254. package/src/client/webhooks/usageSubscriptions.ts +81 -0
  255. package/src/component/_generated/api.ts +22 -0
  256. package/src/component/_generated/component.ts +335 -0
  257. package/src/component/accountClosure/mutations.ts +12 -0
  258. package/src/component/schema.ts +16 -0
  259. package/src/component/usage/mutations.ts +5 -0
  260. package/src/component/usage/schema.ts +5 -1
  261. package/src/component/usageDelivery/fields.ts +3 -0
  262. package/src/component/usageDelivery/mutations.ts +26 -1
  263. package/src/component/usageDelivery/queries.ts +30 -3
  264. package/src/component/usageDelivery/steps.ts +61 -2
  265. package/src/component/usageObservations/helpers.ts +95 -0
  266. package/src/component/usageObservations/history.test.ts +87 -0
  267. package/src/component/usageObservations/history.ts +39 -0
  268. package/src/component/usageObservations/mutations.ts +39 -0
  269. package/src/component/usageObservations/queries.test.ts +162 -0
  270. package/src/component/usageObservations/queries.ts +145 -0
  271. package/src/component/usageObservations/schema.ts +40 -0
  272. package/src/component/usageSubscriptions/abandonment.ts +80 -0
  273. package/src/component/usageSubscriptions/acceptance.test.ts +122 -0
  274. package/src/component/usageSubscriptions/acceptance.ts +66 -0
  275. package/src/component/usageSubscriptions/helpers.ts +33 -0
  276. package/src/component/usageSubscriptions/history.test.ts +69 -0
  277. package/src/component/usageSubscriptions/history.ts +68 -0
  278. package/src/component/usageSubscriptions/mutations.test.ts +205 -0
  279. package/src/component/usageSubscriptions/mutations.ts +275 -0
  280. package/src/component/usageSubscriptions/queries.ts +78 -0
  281. package/src/component/usageSubscriptions/retirement.ts +105 -0
  282. package/src/component/usageSubscriptions/schema.ts +73 -0
@@ -1,3 +1,6 @@
1
+ import { managedBillingCutoff } from "../usageSubscriptions/acceptance.js";
2
+ import { subscriptionSnapshot } from "../usage/helpers.js";
3
+ import { appendDeliveryHistory } from "../usageObservations/history.js";
1
4
  import { internalMutation } from "../_generated/server.js";
2
5
  import { v } from "convex/values";
3
6
  import { refFields, request, status } from "./schema.js";
@@ -11,7 +14,7 @@ export const claim = internalMutation({
11
14
  v.object({ kind: v.literal("done") }),
12
15
  ),
13
16
  handler: async (ctx, args) => {
14
- const { outbox, record } = await read(ctx, args),
17
+ const { event, outbox, record } = await read(ctx, args),
15
18
  now = Math.floor(Date.now() / 1000);
16
19
  if (
17
20
  outbox.held ||
@@ -30,6 +33,13 @@ export const claim = internalMutation({
30
33
  state: outbox.firstSendAt === undefined ? "held" : "unknown",
31
34
  reason: "delivery_window_expired",
32
35
  });
36
+ await appendDeliveryHistory(
37
+ ctx,
38
+ args.eventId,
39
+ "window_expired",
40
+ outbox.attempts,
41
+ `window:${outbox.attempts}`,
42
+ );
33
43
  return { kind: "done" as const };
34
44
  }
35
45
  if (outbox.state === "sending") {
@@ -45,6 +55,32 @@ export const claim = internalMutation({
45
55
  state: "unknown",
46
56
  reason: "provider_outcome_unknown",
47
57
  });
58
+ await appendDeliveryHistory(
59
+ ctx,
60
+ args.eventId,
61
+ "unknown",
62
+ outbox.attempts,
63
+ `result:${outbox.attempts}:unknown`,
64
+ );
65
+ return { kind: "done" as const };
66
+ }
67
+ const cutoff = await managedBillingCutoff(
68
+ ctx,
69
+ record,
70
+ subscriptionSnapshot(event.subscriptionJson),
71
+ );
72
+ if (cutoff !== null && now >= cutoff) {
73
+ await ctx.db.patch("usageOutbox", outbox._id, {
74
+ state: "held",
75
+ reason: "billing_period_closed",
76
+ });
77
+ await appendDeliveryHistory(
78
+ ctx,
79
+ args.eventId,
80
+ "held",
81
+ outbox.attempts,
82
+ `billing-period:${outbox.attempts}`,
83
+ );
48
84
  return { kind: "done" as const };
49
85
  }
50
86
  const keys = lockKeys(record);
@@ -85,6 +121,13 @@ export const claim = internalMutation({
85
121
  leaseUntil: now + 900,
86
122
  reason: undefined,
87
123
  });
124
+ await appendDeliveryHistory(
125
+ ctx,
126
+ args.eventId,
127
+ "started",
128
+ attempt,
129
+ `started:${attempt}`,
130
+ );
88
131
  return {
89
132
  kind: "ready" as const,
90
133
  request: {
@@ -153,6 +196,14 @@ export const save = internalMutation({
153
196
  eventId: undefined,
154
197
  });
155
198
  }
199
+ await appendDeliveryHistory(
200
+ ctx,
201
+ args.eventId,
202
+ result.status,
203
+ args.attempt,
204
+ `result:${args.attempt}:${result.status}`,
205
+ result.status === "accepted" ? result.created : undefined,
206
+ );
156
207
  return statusOf((await read(ctx, args)).outbox);
157
208
  },
158
209
  });
@@ -161,11 +212,19 @@ export const exhaust = internalMutation({
161
212
  returns: v.null(),
162
213
  handler: async (ctx, args) => {
163
214
  const { outbox } = await read(ctx, args);
164
- if (outbox.state === "queued")
215
+ if (outbox.state === "queued") {
165
216
  await ctx.db.patch("usageOutbox", outbox._id, {
166
217
  state: "held",
167
218
  reason: "retry_exhausted",
168
219
  });
220
+ await appendDeliveryHistory(
221
+ ctx,
222
+ args.eventId,
223
+ "retry_exhausted",
224
+ outbox.attempts,
225
+ `exhaust:${outbox.attempts}`,
226
+ );
227
+ }
169
228
  return null;
170
229
  },
171
230
  });
@@ -0,0 +1,95 @@
1
+ import { z } from "zod";
2
+ import { canonicalFingerprint } from "../operationEvidence/canonical.js";
3
+ import {
4
+ observationOptions,
5
+ type UsageObservationOptions,
6
+ } from "../../client/usage/observationTypes.js";
7
+ import { scopeKey } from "../usage/helpers.js";
8
+ import { decimalFromScaled } from "../../client/usage/summary.js";
9
+ const integer = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
10
+ const period = z.strictObject({ start: integer, end: integer });
11
+ const scaled = z.string().regex(/^\d{1,30}$/),
12
+ quantity = z.string().regex(/^\d{1,30}(\.\d{1,6})?$/);
13
+ const value = z.strictObject({
14
+ period,
15
+ quantity,
16
+ scaledQuantity: scaled,
17
+ complete: z.boolean(),
18
+ nextCursor: z.string().max(2048).nullable(),
19
+ aggregationLagPossible: z.literal(true),
20
+ stale: z.literal(false),
21
+ entries: z
22
+ .array(
23
+ z.strictObject({
24
+ id: z.string().min(1).max(2048),
25
+ start: integer,
26
+ end: integer,
27
+ scaledQuantity: scaled,
28
+ }),
29
+ )
30
+ .max(100),
31
+ });
32
+ const availability = z.union([
33
+ z.strictObject({
34
+ status: z.literal("available"),
35
+ observedAt: integer,
36
+ value,
37
+ }),
38
+ z.strictObject({
39
+ status: z.enum(["unavailable", "unsupported"]),
40
+ reason: z.enum([
41
+ "minute_alignment_required",
42
+ "provider_binding_mismatch",
43
+ "unsupported_scope",
44
+ "aggregation_pending",
45
+ "provider_history_incomplete",
46
+ "provider_precision_unsupported",
47
+ "provider_unavailable",
48
+ ]),
49
+ retryable: z.boolean(),
50
+ }),
51
+ ]);
52
+ export async function source(json: string) {
53
+ if (new TextEncoder().encode(json).length > 8192)
54
+ throw new Error("Usage observation source exceeds limit");
55
+ const opts = observationOptions(JSON.parse(json) as UsageObservationOptions);
56
+ const sourceJson = JSON.stringify(opts);
57
+ return {
58
+ opts,
59
+ sourceJson,
60
+ scopeKey: scopeKey(opts.scope),
61
+ key: await canonicalFingerprint(opts),
62
+ };
63
+ }
64
+ export function observation(
65
+ json: string,
66
+ opts: ReturnType<typeof observationOptions>,
67
+ ) {
68
+ if (new TextEncoder().encode(json).length > 65536)
69
+ throw new Error("Invalid usage provider observation");
70
+ const parsed = availability.safeParse(JSON.parse(json));
71
+ if (!parsed.success) throw new Error("Invalid usage provider observation");
72
+ const result = parsed.data;
73
+ if (result.status === "available") {
74
+ const v = result.value;
75
+ if (
76
+ result.observedAt > Date.now() / 1000 + 300 ||
77
+ JSON.stringify(v.period) !== JSON.stringify(opts.period) ||
78
+ v.quantity !==
79
+ decimalFromScaled(
80
+ BigInt(v.scaledQuantity),
81
+ opts.binding.plan.unit.precision,
82
+ ) ||
83
+ v.entries.reduce((sum, e) => sum + BigInt(e.scaledQuantity), 0n) !==
84
+ BigInt(v.scaledQuantity) ||
85
+ v.entries.some(
86
+ (e) =>
87
+ e.start < opts.period.start ||
88
+ e.end > opts.period.end ||
89
+ e.end <= e.start,
90
+ )
91
+ )
92
+ throw new Error("Invalid usage provider observation");
93
+ }
94
+ return JSON.stringify(result);
95
+ }
@@ -0,0 +1,87 @@
1
+ import { convexTest } from "convex-test";
2
+ import { makeFunctionReference } from "convex/server";
3
+ import { expect, it } from "vitest";
4
+ import { schema, modules } from "../../test.js";
5
+ const ref = (name: string) => makeFunctionReference<"mutation">(name);
6
+ it("retains paged delivery attempts and outcomes without admitting a foreign scope", async () => {
7
+ const t = convexTest(schema, modules),
8
+ now = Math.floor(Date.now() / 1000);
9
+ const scope = {
10
+ stripeAccountId: "acct_platform",
11
+ customerAccount: "acct_buyer",
12
+ meterId: "mtr_calls",
13
+ livemode: false,
14
+ };
15
+ const receipt = await t.mutation(ref("usage/mutations:record"), {
16
+ inputJson: JSON.stringify({
17
+ scope,
18
+ binding: {
19
+ stripeCustomerId: "cus_buyer",
20
+ stripePriceId: "price_calls",
21
+ eventName: "calls",
22
+ plan: {
23
+ key: "calls",
24
+ version: "v1",
25
+ model: "pay_as_you_go",
26
+ unit: { name: "call", precision: 0 },
27
+ rate: { currency: "usd", unitAmountDecimal: "2" },
28
+ },
29
+ },
30
+ sourceEventId: "one",
31
+ quantity: "1",
32
+ occurredAt: now,
33
+ }),
34
+ subscriptionJson: JSON.stringify({
35
+ subscriptionId: "sub_calls",
36
+ subscriptionItemId: "si_calls",
37
+ stripePriceId: "price_calls",
38
+ period: { start: now - 1, end: now + 86400 },
39
+ interval: "month",
40
+ }),
41
+ });
42
+ await t.run(async (ctx) => {
43
+ const row = (await ctx.db.query("usageOutbox").first())!;
44
+ await ctx.db.patch("usageOutbox", row._id, { definitionVersion: 1 });
45
+ });
46
+ const claimed = await t.mutation(ref("usageDelivery/steps:claim"), {
47
+ scope,
48
+ eventId: receipt.eventId,
49
+ });
50
+ await t.mutation(ref("usageDelivery/steps:save"), {
51
+ ...claimed.request,
52
+ outcome: { status: "accepted", created: now },
53
+ });
54
+ const history = makeFunctionReference<"query">(
55
+ "usageObservations/queries:deliveryHistory",
56
+ );
57
+ const args = {
58
+ scope,
59
+ eventId: receipt.eventId,
60
+ paginationOpts: { cursor: null, numItems: 1 },
61
+ };
62
+ const first = await t.query(history, args);
63
+ expect(first).toMatchObject({
64
+ page: [{ phase: "started", attempt: 1, sequence: 1 }],
65
+ isDone: false,
66
+ legacyHistoryMissing: false,
67
+ });
68
+ const second = await t.query(history, {
69
+ ...args,
70
+ paginationOpts: { cursor: first.continueCursor, numItems: 1 },
71
+ });
72
+ expect(second).toMatchObject({
73
+ page: [{ phase: "accepted", attempt: 1, sequence: 2 }],
74
+ });
75
+ expect(
76
+ await t.query(history, {
77
+ ...args,
78
+ paginationOpts: { cursor: second.continueCursor, numItems: 1 },
79
+ }),
80
+ ).toMatchObject({ page: [], isDone: true });
81
+ await expect(
82
+ t.query(history, {
83
+ ...args,
84
+ scope: { ...scope, customerAccount: "acct_other" },
85
+ }),
86
+ ).rejects.toThrow();
87
+ });
@@ -0,0 +1,39 @@
1
+ import type { MutationCtx } from "../_generated/server.js";
2
+ import type { Id } from "../_generated/dataModel.js";
3
+ import type { Infer } from "convex/values";
4
+ import type { historyPhase } from "./schema.js";
5
+ export async function appendDeliveryHistory(
6
+ ctx: MutationCtx,
7
+ eventId: Id<"usageEvents">,
8
+ phase: Infer<typeof historyPhase>,
9
+ attempt: number,
10
+ identity: string,
11
+ created?: number,
12
+ ) {
13
+ const prior = await ctx.db
14
+ .query("usageDeliveryHistory")
15
+ .withIndex("by_event_identity", (q) =>
16
+ q.eq("eventId", eventId).eq("identity", identity),
17
+ )
18
+ .unique();
19
+ if (prior) return;
20
+ const outbox = await ctx.db
21
+ .query("usageOutbox")
22
+ .withIndex("by_event", (q) => q.eq("eventId", eventId))
23
+ .unique();
24
+ if (!outbox) throw new Error("Usage history event unavailable");
25
+ const sequence = (outbox.historySequence ?? 0) + 1;
26
+ if (!Number.isSafeInteger(sequence))
27
+ throw new Error("Usage history sequence exhausted");
28
+ await ctx.db.insert("usageDeliveryHistory", {
29
+ eventId,
30
+ scopeKey: outbox.scopeKey,
31
+ sequence,
32
+ attempt,
33
+ phase,
34
+ identity,
35
+ recordedAt: Math.floor(Date.now() / 1000),
36
+ ...(created !== undefined ? { created } : {}),
37
+ });
38
+ await ctx.db.patch("usageOutbox", outbox._id, { historySequence: sequence });
39
+ }
@@ -0,0 +1,39 @@
1
+ import { mutation } from "../_generated/server.js";
2
+ import { v } from "convex/values";
3
+ import { source, observation } from "./helpers.js";
4
+ export const save = mutation({
5
+ args: {
6
+ sourceJson: v.string(),
7
+ observationJson: v.string(),
8
+ startedAt: v.number(),
9
+ },
10
+ returns: v.null(),
11
+ handler: async (ctx, args) => {
12
+ if (
13
+ !Number.isSafeInteger(args.startedAt) ||
14
+ args.startedAt < 0 ||
15
+ args.startedAt > Date.now() + 300000
16
+ )
17
+ throw new Error("Invalid observation start time");
18
+ const binding = await source(args.sourceJson),
19
+ observationJson = observation(args.observationJson, binding.opts);
20
+ const prior = await ctx.db
21
+ .query("usageProviderObservations")
22
+ .withIndex("by_key", (q) => q.eq("key", binding.key))
23
+ .unique();
24
+ if (prior && prior.sourceJson !== binding.sourceJson)
25
+ throw new Error("Usage observation binding conflict");
26
+ if (prior && prior.startedAt > args.startedAt) return null;
27
+ const fields = {
28
+ key: binding.key,
29
+ scopeKey: binding.scopeKey,
30
+ sourceJson: binding.sourceJson,
31
+ observationJson,
32
+ startedAt: args.startedAt,
33
+ };
34
+ if (prior)
35
+ await ctx.db.patch("usageProviderObservations", prior._id, fields);
36
+ else await ctx.db.insert("usageProviderObservations", fields);
37
+ return null;
38
+ },
39
+ });
@@ -0,0 +1,162 @@
1
+ import { convexTest } from "convex-test";
2
+ import { makeFunctionReference } from "convex/server";
3
+ import { expect, it } from "vitest";
4
+ import { schema, modules } from "../../test.js";
5
+ const summary = makeFunctionReference<"query">(
6
+ "usageObservations/queries:summary",
7
+ ),
8
+ record = makeFunctionReference<"mutation">("usage/mutations:record");
9
+ it("bounds local summaries and never includes another scope", async () => {
10
+ const t = convexTest(schema, modules),
11
+ now = Math.floor(Date.now() / 1000),
12
+ period = { start: now - 5, end: now + 100 };
13
+ const scope = {
14
+ stripeAccountId: "acct_platform",
15
+ customerAccount: "acct_buyer",
16
+ meterId: "mtr_calls",
17
+ livemode: false,
18
+ };
19
+ for (const sourceEventId of ["a", "b"])
20
+ await t.mutation(record, {
21
+ inputJson: JSON.stringify({
22
+ scope,
23
+ binding: {
24
+ stripeCustomerId: "cus_buyer",
25
+ stripePriceId: "price_calls",
26
+ eventName: "calls",
27
+ plan: {
28
+ key: "calls",
29
+ version: "v1",
30
+ model: "pay_as_you_go",
31
+ unit: { name: "call", precision: 0 },
32
+ rate: { currency: "usd", unitAmountDecimal: "2" },
33
+ },
34
+ },
35
+ sourceEventId,
36
+ quantity: "1",
37
+ occurredAt: now,
38
+ }),
39
+ subscriptionJson: JSON.stringify({
40
+ subscriptionId: "sub_calls",
41
+ subscriptionItemId: "si_calls",
42
+ stripePriceId: "price_calls",
43
+ period,
44
+ interval: "month",
45
+ }),
46
+ });
47
+ expect(
48
+ JSON.parse(await t.query(summary, { scope, period, maxRecords: 1 })),
49
+ ).toMatchObject({
50
+ complete: false,
51
+ eventCount: 1,
52
+ groups: [
53
+ {
54
+ acceptedQuantity: "1",
55
+ estimate: { status: "unavailable", reason: "local_history_incomplete" },
56
+ },
57
+ ],
58
+ });
59
+ expect(
60
+ JSON.parse(
61
+ await t.query(summary, {
62
+ scope: { ...scope, customerAccount: "acct_other" },
63
+ period,
64
+ maxRecords: 10,
65
+ }),
66
+ ),
67
+ ).toMatchObject({ complete: true, eventCount: 0, groups: [] });
68
+ await expect(
69
+ t.query(summary, { scope, period, maxRecords: 501 }),
70
+ ).rejects.toThrow();
71
+ });
72
+
73
+ it("retains immutable scoped cache bindings and rejects stale projections and raw payloads", async () => {
74
+ const t = convexTest(schema, modules),
75
+ now = Math.floor(Date.now() / 1000),
76
+ period = { start: 600, end: 1200 };
77
+ const source = {
78
+ scope: {
79
+ stripeAccountId: "acct_platform",
80
+ customerAccount: "acct_buyer",
81
+ meterId: "mtr_calls",
82
+ livemode: false,
83
+ },
84
+ binding: {
85
+ stripeCustomerId: "cus_buyer",
86
+ stripePriceId: "price_calls",
87
+ eventName: "calls",
88
+ plan: {
89
+ key: "calls",
90
+ version: "v1",
91
+ model: "pay_as_you_go",
92
+ unit: { name: "call", precision: 0 },
93
+ rate: { currency: "usd", unitAmountDecimal: "2" },
94
+ },
95
+ },
96
+ subscription: {
97
+ subscriptionId: "sub_calls",
98
+ subscriptionItemId: "si_calls",
99
+ stripePriceId: "price_calls",
100
+ period,
101
+ interval: "month",
102
+ },
103
+ period,
104
+ limit: 100,
105
+ cursor: null,
106
+ };
107
+ const save = makeFunctionReference<"mutation">(
108
+ "usageObservations/mutations:save",
109
+ ),
110
+ cached = makeFunctionReference<"query">("usageObservations/queries:cached");
111
+ const observation = {
112
+ status: "available",
113
+ observedAt: now,
114
+ value: {
115
+ period,
116
+ quantity: "1",
117
+ scaledQuantity: "1",
118
+ complete: true,
119
+ nextCursor: null,
120
+ aggregationLagPossible: true,
121
+ stale: false,
122
+ entries: [
123
+ { id: "mtrusg_one", start: 600, end: 1200, scaledQuantity: "1" },
124
+ ],
125
+ },
126
+ };
127
+ const args = {
128
+ sourceJson: JSON.stringify(source),
129
+ observationJson: JSON.stringify(observation),
130
+ startedAt: Date.now(),
131
+ };
132
+ await t.mutation(save, args);
133
+ await t.mutation(save, {
134
+ ...args,
135
+ startedAt: args.startedAt - 1,
136
+ observationJson: JSON.stringify({
137
+ status: "unavailable",
138
+ reason: "provider_unavailable",
139
+ retryable: true,
140
+ }),
141
+ });
142
+ expect(
143
+ JSON.parse(await t.query(cached, { sourceJson: args.sourceJson })),
144
+ ).toMatchObject({ status: "available", value: { quantity: "1" } });
145
+ expect(
146
+ await t.query(cached, {
147
+ sourceJson: JSON.stringify({
148
+ ...source,
149
+ scope: { ...source.scope, customerAccount: "acct_other" },
150
+ }),
151
+ }),
152
+ ).toBeNull();
153
+ await expect(
154
+ t.mutation(save, {
155
+ ...args,
156
+ observationJson: JSON.stringify({
157
+ ...observation,
158
+ privateMetadata: "private",
159
+ }),
160
+ }),
161
+ ).rejects.toThrow("Invalid usage provider observation");
162
+ });
@@ -0,0 +1,145 @@
1
+ import {
2
+ paginationOptsValidator,
3
+ paginationResultValidator,
4
+ } from "convex/server";
5
+ import { paginator } from "convex-helpers/server/pagination";
6
+ import schema from "../schema.js";
7
+ import { refFields } from "../usageDelivery/schema.js";
8
+ import { read } from "../usageDelivery/helpers.js";
9
+ import { historyDoc } from "./schema.js";
10
+ import { errorDoc } from "../usageDelivery/fields.js";
11
+ import { source } from "./helpers.js";
12
+ import { query } from "../_generated/server.js";
13
+ import { v } from "convex/values";
14
+ import { scopeValidator } from "../usage/schema.js";
15
+ import { scopeKey, subscriptionSnapshot } from "../usage/helpers.js";
16
+ import { validateUsagePageRequest } from "../../client/usage/boundaries.js";
17
+ import { summarizeUsageRecords } from "../../client/usage/summary.js";
18
+ import type { PreparedUsageRecord } from "../../client/usage/records.js";
19
+ export const summary = query({
20
+ args: {
21
+ scope: scopeValidator,
22
+ period: v.object({ start: v.number(), end: v.number() }),
23
+ maxRecords: v.number(),
24
+ },
25
+ returns: v.string(),
26
+ handler: async (ctx, args) => {
27
+ const key = scopeKey(args.scope);
28
+ validateUsagePageRequest({ period: args.period, limit: 1, cursor: null });
29
+ if (
30
+ !Number.isInteger(args.maxRecords) ||
31
+ args.maxRecords < 1 ||
32
+ args.maxRecords > 500
33
+ )
34
+ throw new Error("Usage summary read budget must be 1–500");
35
+ const rows = await ctx.db
36
+ .query("usageEvents")
37
+ .withIndex("by_scope_time", (q) =>
38
+ q
39
+ .eq("scopeKey", key)
40
+ .gte("occurredAt", args.period.start)
41
+ .lt("occurredAt", args.period.end),
42
+ )
43
+ .take(args.maxRecords + 1);
44
+ const views = await Promise.all(
45
+ rows.slice(0, args.maxRecords).map(async (event) => {
46
+ const [outbox, error] = await Promise.all([
47
+ ctx.db
48
+ .query("usageOutbox")
49
+ .withIndex("by_event", (q) => q.eq("eventId", event._id))
50
+ .unique(),
51
+ ctx.db
52
+ .query("usageDeliveryErrors")
53
+ .withIndex("by_event", (q) => q.eq("eventId", event._id))
54
+ .first(),
55
+ ]);
56
+ if (!outbox) throw new Error("Usage outbox invariant violated");
57
+ return {
58
+ record: JSON.parse(event.recordJson) as PreparedUsageRecord,
59
+ subscription: subscriptionSnapshot(event.subscriptionJson),
60
+ delivery: outbox.state,
61
+ hasValidationError: error !== null,
62
+ };
63
+ }),
64
+ );
65
+ return JSON.stringify(
66
+ summarizeUsageRecords(views, {
67
+ period: args.period,
68
+ observedAt: Math.floor(Date.now() / 1000),
69
+ complete: rows.length <= args.maxRecords,
70
+ }),
71
+ );
72
+ },
73
+ });
74
+
75
+ export const cached = query({
76
+ args: { sourceJson: v.string() },
77
+ returns: v.union(v.string(), v.null()),
78
+ handler: async (ctx, args) => {
79
+ const binding = await source(args.sourceJson);
80
+ const row = await ctx.db
81
+ .query("usageProviderObservations")
82
+ .withIndex("by_key", (q) => q.eq("key", binding.key))
83
+ .unique();
84
+ return row &&
85
+ row.scopeKey === binding.scopeKey &&
86
+ row.sourceJson === binding.sourceJson
87
+ ? row.observationJson
88
+ : null;
89
+ },
90
+ });
91
+
92
+ function validate(numItems: number, cursor: string | null) {
93
+ validateUsagePageRequest({
94
+ period: { start: 0, end: 1 },
95
+ limit: numItems,
96
+ cursor,
97
+ });
98
+ }
99
+ const paginated = paginationResultValidator(historyDoc);
100
+ export const deliveryHistory = query({
101
+ args: { ...refFields, paginationOpts: paginationOptsValidator },
102
+ returns: v.object({ ...paginated.fields, legacyHistoryMissing: v.boolean() }),
103
+ handler: async (ctx, args) => {
104
+ const { outbox } = await read(ctx, args);
105
+ validate(args.paginationOpts.numItems, args.paginationOpts.cursor);
106
+ const [page, first] = await Promise.all([
107
+ paginator(ctx.db, schema)
108
+ .query("usageDeliveryHistory")
109
+ .withIndex("by_event_sequence", (q) => q.eq("eventId", args.eventId))
110
+ .order("asc")
111
+ .paginate({
112
+ ...args.paginationOpts,
113
+ maximumRowsRead: 200,
114
+ maximumBytesRead: 1000000,
115
+ }),
116
+ ctx.db
117
+ .query("usageDeliveryHistory")
118
+ .withIndex("by_event_identity", (q) =>
119
+ q.eq("eventId", args.eventId).eq("identity", "started:1"),
120
+ )
121
+ .unique(),
122
+ ]);
123
+ return {
124
+ ...page,
125
+ legacyHistoryMissing: outbox.attempts > 0 && first === null,
126
+ };
127
+ },
128
+ });
129
+ export const validationHistory = query({
130
+ args: { ...refFields, paginationOpts: paginationOptsValidator },
131
+ returns: paginationResultValidator(errorDoc),
132
+ handler: async (ctx, args) => {
133
+ await read(ctx, args);
134
+ validate(args.paginationOpts.numItems, args.paginationOpts.cursor);
135
+ return paginator(ctx.db, schema)
136
+ .query("usageDeliveryErrors")
137
+ .withIndex("by_event", (q) => q.eq("eventId", args.eventId))
138
+ .order("desc")
139
+ .paginate({
140
+ ...args.paginationOpts,
141
+ maximumRowsRead: 200,
142
+ maximumBytesRead: 1000000,
143
+ });
144
+ },
145
+ });