@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
@@ -0,0 +1,233 @@
1
+ import type { Doc } from "../../component/_generated/dataModel.js";
2
+ import type { UsageDeliveryRef } from "./deliveryClient.js";
3
+ import { observeUsageInvoice } from "./invoiceObservation.js";
4
+ import Stripe from "stripe";
5
+ import type { RunCtx } from "../helpers.js";
6
+ import { runMutationOrThrow } from "../helpers.js";
7
+ import { componentRef } from "../webhooks/helpers.js";
8
+ import type { StripeApiVersion } from "../stripe-types.js";
9
+ import { UsageDeliveryClient } from "./deliveryClient.js";
10
+ import type { UsageDeliveryProviderOptions } from "./deliveryProvider.js";
11
+ import { observeProviderUsage } from "./providerObservation.js";
12
+ import {
13
+ observationOptions,
14
+ observationKeyOptions,
15
+ type UsageObservationOptions,
16
+ type UsageAggregateObservation,
17
+ } from "./observationTypes.js";
18
+ import type { UsageLocalSummary } from "./summary.js";
19
+ import type { UsageScope } from "./records.js";
20
+ import { scopeSchema } from "./records.js";
21
+ import { validateUsagePageRequest, type UsagePeriod } from "./boundaries.js";
22
+ import { compareUsageObservations } from "./reconciliation.js";
23
+ export type UsageReconciliationOptions = UsageObservationOptions & {
24
+ maxRecords?: number;
25
+ maxAgeSeconds?: number;
26
+ };
27
+ /** Host authorizes the exact scope and original binding before every call. */
28
+ export class UsageObservationClient extends UsageDeliveryClient {
29
+ async getSummary(
30
+ ctx: RunCtx,
31
+ input: { scope: UsageScope; period: UsagePeriod; maxRecords?: number },
32
+ ): Promise<UsageLocalSummary> {
33
+ const scope = scopeSchema.parse(input.scope),
34
+ { period } = validateUsagePageRequest({
35
+ period: input.period,
36
+ limit: 1,
37
+ cursor: null,
38
+ });
39
+ const json = await ctx.runQuery(
40
+ componentRef(this.component, "usageObservations/queries/summary"),
41
+ { scope, period, maxRecords: input.maxRecords ?? 100 },
42
+ );
43
+ return JSON.parse(json) as UsageLocalSummary;
44
+ }
45
+ async getProviderUsage(
46
+ ctx: RunCtx,
47
+ input: UsageReconciliationOptions,
48
+ ): Promise<UsageAggregateObservation> {
49
+ const opts = observationOptions(input),
50
+ { maxAgeSeconds } = observationKeyOptions.parse({
51
+ maxAgeSeconds: input.maxAgeSeconds,
52
+ });
53
+ const json = await ctx.runQuery(
54
+ componentRef(this.component, "usageObservations/queries/cached"),
55
+ { sourceJson: JSON.stringify(opts) },
56
+ );
57
+ if (json === null)
58
+ return {
59
+ status: "unavailable",
60
+ reason: "provider_not_observed",
61
+ retryable: true,
62
+ };
63
+ const result = JSON.parse(json) as UsageAggregateObservation;
64
+ if (result.status === "available")
65
+ return {
66
+ ...result,
67
+ value: {
68
+ ...result.value,
69
+ stale:
70
+ Math.floor(Date.now() / 1000) - result.observedAt > maxAgeSeconds,
71
+ },
72
+ };
73
+ return result;
74
+ }
75
+ async observeProviderUsage(
76
+ ctx: RunCtx,
77
+ input: UsageObservationOptions,
78
+ options: UsageDeliveryProviderOptions,
79
+ ): Promise<UsageAggregateObservation> {
80
+ const opts = observationOptions(input),
81
+ startedAt = Date.now();
82
+ const observation = options.stripeSecretKey
83
+ ? await observeProviderUsage(
84
+ new Stripe(options.stripeSecretKey, {
85
+ apiVersion: opts.binding.apiVersion as StripeApiVersion,
86
+ maxNetworkRetries: 0,
87
+ timeout: 15000,
88
+ ...(options.httpClient ? { httpClient: options.httpClient } : {}),
89
+ }),
90
+ opts,
91
+ )
92
+ : {
93
+ status: "unavailable" as const,
94
+ reason: "provider_unavailable",
95
+ retryable: true,
96
+ };
97
+ await runMutationOrThrow(
98
+ ctx,
99
+ componentRef(this.component, "usageObservations/mutations/save"),
100
+ {
101
+ sourceJson: JSON.stringify(opts),
102
+ observationJson: JSON.stringify(observation),
103
+ startedAt,
104
+ },
105
+ );
106
+ return observation;
107
+ }
108
+ async readDeliveryHistory(
109
+ ctx: RunCtx,
110
+ input: UsageDeliveryRef & { limit: number; cursor: string | null },
111
+ ) {
112
+ const page = validateUsagePageRequest({
113
+ period: { start: 0, end: 1 },
114
+ limit: input.limit,
115
+ cursor: input.cursor,
116
+ });
117
+ const result = (await ctx.runQuery(
118
+ componentRef(this.component, "usageObservations/queries/deliveryHistory"),
119
+ {
120
+ scope: scopeSchema.parse(input.scope),
121
+ eventId: input.eventId,
122
+ paginationOpts: { numItems: page.limit, cursor: page.cursor },
123
+ },
124
+ )) as {
125
+ page: Doc<"usageDeliveryHistory">[];
126
+ isDone: boolean;
127
+ continueCursor: string;
128
+ legacyHistoryMissing: boolean;
129
+ };
130
+ return {
131
+ records: result.page.map(
132
+ ({ sequence, attempt, phase, recordedAt, created }) => ({
133
+ sequence,
134
+ attempt,
135
+ phase,
136
+ recordedAt,
137
+ created: created ?? null,
138
+ }),
139
+ ),
140
+ isDone: result.isDone,
141
+ cursor: result.isDone ? null : result.continueCursor,
142
+ legacyHistoryMissing: result.legacyHistoryMissing,
143
+ };
144
+ }
145
+ async readValidationHistory(
146
+ ctx: RunCtx,
147
+ input: UsageDeliveryRef & { limit: number; cursor: string | null },
148
+ ) {
149
+ const page = validateUsagePageRequest({
150
+ period: { start: 0, end: 1 },
151
+ limit: input.limit,
152
+ cursor: input.cursor,
153
+ });
154
+ const result = (await ctx.runQuery(
155
+ componentRef(
156
+ this.component,
157
+ "usageObservations/queries/validationHistory",
158
+ ),
159
+ {
160
+ scope: scopeSchema.parse(input.scope),
161
+ eventId: input.eventId,
162
+ paginationOpts: { numItems: page.limit, cursor: page.cursor },
163
+ },
164
+ )) as {
165
+ page: Doc<"usageDeliveryErrors">[];
166
+ isDone: boolean;
167
+ continueCursor: string;
168
+ };
169
+ return {
170
+ records: result.page.map(({ providerEventId, code, observedAt }) => ({
171
+ providerEventId,
172
+ code,
173
+ observedAt,
174
+ })),
175
+ isDone: result.isDone,
176
+ cursor: result.isDone ? null : result.continueCursor,
177
+ };
178
+ }
179
+ async readInvoiceUsage(
180
+ _ctx: RunCtx,
181
+ input: UsageObservationOptions & { invoiceId?: string },
182
+ options: UsageDeliveryProviderOptions,
183
+ ) {
184
+ const opts = observationOptions(input);
185
+ if (!options.stripeSecretKey)
186
+ return {
187
+ status: "unavailable" as const,
188
+ reason: "provider_unavailable",
189
+ retryable: true,
190
+ };
191
+ const stripe = new Stripe(options.stripeSecretKey, {
192
+ apiVersion: opts.binding.apiVersion as StripeApiVersion,
193
+ maxNetworkRetries: 0,
194
+ timeout: 15000,
195
+ ...(options.httpClient ? { httpClient: options.httpClient } : {}),
196
+ });
197
+ return observeUsageInvoice(stripe, opts, input.invoiceId);
198
+ }
199
+ async getReconciliation(ctx: RunCtx, input: UsageReconciliationOptions) {
200
+ const opts = observationOptions(input);
201
+ const [local, aggregate] = await Promise.all([
202
+ this.getSummary(ctx, {
203
+ scope: opts.scope,
204
+ period: opts.period,
205
+ maxRecords: input.maxRecords,
206
+ }),
207
+ this.getProviderUsage(ctx, input),
208
+ ]);
209
+ return {
210
+ local,
211
+ aggregate,
212
+ comparison: compareUsageObservations(local, aggregate, opts.binding),
213
+ invoice: {
214
+ status: "unavailable" as const,
215
+ reason: "invoice_not_observed",
216
+ retryable: true,
217
+ },
218
+ correctionHistory: {
219
+ status: "unsupported" as const,
220
+ reason: "corrections_not_configured",
221
+ retryable: false,
222
+ },
223
+ };
224
+ }
225
+ async reconcile(
226
+ ctx: RunCtx,
227
+ input: UsageReconciliationOptions,
228
+ options: UsageDeliveryProviderOptions,
229
+ ) {
230
+ await this.observeProviderUsage(ctx, input, options);
231
+ return this.getReconciliation(ctx, input);
232
+ }
233
+ }
@@ -0,0 +1,101 @@
1
+ import type Stripe from "stripe";
2
+ import { z } from "zod";
3
+ import {
4
+ prepareUsageRecord,
5
+ type PreparedUsageRecord,
6
+ type UsageScope,
7
+ } from "./records.js";
8
+ import {
9
+ validateUsagePageRequest,
10
+ type UsageAvailability,
11
+ type UsagePeriod,
12
+ type UsageSubscriptionBinding,
13
+ } from "./boundaries.js";
14
+ import { subscriptionSnapshot } from "../../component/usage/helpers.js";
15
+ import { verifyRealm, verifyMeter } from "./catalogTypes.js";
16
+ export type UsageObservationOptions = {
17
+ scope: UsageScope;
18
+ binding: PreparedUsageRecord["binding"];
19
+ subscription: UsageSubscriptionBinding;
20
+ period: UsagePeriod;
21
+ limit?: number;
22
+ cursor?: string | null;
23
+ };
24
+ export type UsageAggregateValue = {
25
+ period: UsagePeriod;
26
+ quantity: string;
27
+ scaledQuantity: string;
28
+ complete: boolean;
29
+ nextCursor: string | null;
30
+ aggregationLagPossible: true;
31
+ stale: boolean;
32
+ entries: Array<{
33
+ id: string;
34
+ start: number;
35
+ end: number;
36
+ scaledQuantity: string;
37
+ }>;
38
+ };
39
+ export type UsageAggregateObservation = UsageAvailability<UsageAggregateValue>;
40
+ export function observationOptions(input: UsageObservationOptions) {
41
+ const page = validateUsagePageRequest({
42
+ period: input.period,
43
+ limit: input.limit ?? 100,
44
+ cursor: input.cursor ?? null,
45
+ });
46
+ const { scope, binding } = prepareUsageRecord({
47
+ scope: input.scope,
48
+ binding: input.binding,
49
+ sourceEventId: "observation",
50
+ quantity: "0",
51
+ occurredAt: page.period.start,
52
+ });
53
+ const subscription = subscriptionSnapshot(JSON.stringify(input.subscription));
54
+ if (subscription.stripePriceId !== binding.stripePriceId)
55
+ throw new Error("Usage observation price binding mismatch");
56
+ return {
57
+ scope,
58
+ binding,
59
+ subscription,
60
+ period: page.period,
61
+ limit: page.limit,
62
+ cursor: page.cursor,
63
+ };
64
+ }
65
+ export async function verifyObservationSource(
66
+ stripe: Stripe,
67
+ opts: ReturnType<typeof observationOptions>,
68
+ ): Promise<boolean> {
69
+ await verifyRealm(stripe, {
70
+ stripeAccountId: opts.scope.stripeAccountId,
71
+ livemode: opts.scope.livemode,
72
+ });
73
+ const [meter, subscription] = await Promise.all([
74
+ stripe.billing.meters.retrieve(opts.scope.meterId),
75
+ stripe.subscriptions.retrieve(opts.subscription.subscriptionId),
76
+ ]);
77
+ if (
78
+ meter.id !== opts.scope.meterId ||
79
+ subscription.id !== opts.subscription.subscriptionId ||
80
+ subscription.livemode !== opts.scope.livemode ||
81
+ subscription.customer_account !== opts.scope.customerAccount ||
82
+ (typeof subscription.customer === "string"
83
+ ? subscription.customer
84
+ : subscription.customer?.id) !== opts.binding.stripeCustomerId
85
+ )
86
+ return false;
87
+ verifyMeter(
88
+ meter,
89
+ {
90
+ scope: opts.scope,
91
+ plan: opts.binding.plan,
92
+ eventName: opts.binding.eventName,
93
+ displayName: meter.display_name,
94
+ },
95
+ false,
96
+ );
97
+ return true;
98
+ }
99
+ export const observationKeyOptions = z.strictObject({
100
+ maxAgeSeconds: z.number().int().min(1).max(86400).default(60),
101
+ });
@@ -0,0 +1,207 @@
1
+ import { componentsGeneric, type FunctionReference } from "convex/server";
2
+ import { BetterStripe } from "../index.js";
3
+ import { initConvexTest } from "../setup.test.js";
4
+ import { schema, modules } from "../../test.js";
5
+ import type { Component, RunCtx } from "../helpers.js";
6
+ import Stripe from "stripe";
7
+ import { expect, it, vi } from "vitest";
8
+ import { STRIPE_API_VERSION } from "../constants.js";
9
+ import { prepareUsageRecord } from "./records.js";
10
+ import { observeProviderUsage } from "./providerObservation.js";
11
+ const scope = {
12
+ stripeAccountId: "acct_platform",
13
+ customerAccount: "acct_buyer",
14
+ meterId: "mtr_calls",
15
+ livemode: false,
16
+ };
17
+ const period = { start: 600, end: 1200 };
18
+ const binding = prepareUsageRecord({
19
+ scope,
20
+ binding: {
21
+ stripeCustomerId: "cus_buyer",
22
+ stripePriceId: "price_calls",
23
+ eventName: "calls",
24
+ plan: {
25
+ key: "calls",
26
+ version: "v1",
27
+ model: "pay_as_you_go",
28
+ unit: { name: "call", precision: 2 },
29
+ rate: { currency: "usd", unitAmountDecimal: "2" },
30
+ },
31
+ },
32
+ sourceEventId: "validation",
33
+ quantity: "0",
34
+ occurredAt: 600,
35
+ }).binding;
36
+ const options = {
37
+ scope,
38
+ binding,
39
+ subscription: {
40
+ subscriptionId: "sub_calls",
41
+ subscriptionItemId: "si_calls",
42
+ stripePriceId: "price_calls",
43
+ period,
44
+ interval: "month" as const,
45
+ },
46
+ period,
47
+ limit: 100,
48
+ cursor: null,
49
+ };
50
+ function setup(value = 125, hasMore = false, empty = false) {
51
+ const requests: Array<URL> = [];
52
+ const httpClient = Stripe.createFetchHttpClient(async (input) => {
53
+ const url = new URL(String(input));
54
+ requests.push(url);
55
+ const result =
56
+ url.pathname === "/v1/account"
57
+ ? { id: "acct_platform" }
58
+ : url.pathname === "/v1/balance"
59
+ ? { livemode: false }
60
+ : url.pathname === "/v1/billing/meters/mtr_calls"
61
+ ? {
62
+ id: "mtr_calls",
63
+ livemode: false,
64
+ status: "active",
65
+ event_name: "calls",
66
+ default_aggregation: { formula: "sum" },
67
+ customer_mapping: {
68
+ type: "by_id",
69
+ event_payload_key: "stripe_customer_id",
70
+ },
71
+ value_settings: { event_payload_key: "value" },
72
+ event_time_window: null,
73
+ }
74
+ : url.pathname === "/v1/subscriptions/sub_calls"
75
+ ? {
76
+ id: "sub_calls",
77
+ livemode: false,
78
+ customer: "cus_buyer",
79
+ customer_account: "acct_buyer",
80
+ }
81
+ : {
82
+ object: "list",
83
+ data: empty
84
+ ? []
85
+ : [
86
+ {
87
+ id: "mtrusg_one",
88
+ object: "billing.meter_event_summary",
89
+ meter: "mtr_calls",
90
+ livemode: false,
91
+ start_time: 600,
92
+ end_time: 1200,
93
+ aggregated_value: value,
94
+ },
95
+ ],
96
+ has_more: hasMore,
97
+ };
98
+ return new Response(JSON.stringify(result), {
99
+ status: 200,
100
+ headers: { "content-type": "application/json" },
101
+ });
102
+ });
103
+ const stripe = new Stripe("sk_test_observe", {
104
+ apiVersion: STRIPE_API_VERSION,
105
+ maxNetworkRetries: 0,
106
+ httpClient,
107
+ });
108
+ return { stripe, requests, httpClient };
109
+ }
110
+ it("reads exact native quantities and preserves the original customer/period", async () => {
111
+ const f = setup();
112
+ expect(await observeProviderUsage(f.stripe, options)).toMatchObject({
113
+ status: "available",
114
+ value: {
115
+ quantity: "1.25",
116
+ scaledQuantity: "125",
117
+ complete: true,
118
+ aggregationLagPossible: true,
119
+ period,
120
+ },
121
+ });
122
+ const request = f.requests.find((r) =>
123
+ r.pathname.endsWith("event_summaries"),
124
+ )!;
125
+ expect(request.searchParams.get("customer")).toBe("cus_buyer");
126
+ expect(request.searchParams.get("start_time")).toBe("600");
127
+ expect(request.searchParams.get("end_time")).toBe("1200");
128
+ });
129
+ it("reports absent aggregation instead of zero and preserves incomplete pagination", async () => {
130
+ expect(
131
+ await observeProviderUsage(setup(0, false, true).stripe, options),
132
+ ).toMatchObject({ status: "unavailable", reason: "aggregation_pending" });
133
+ expect(
134
+ await observeProviderUsage(setup(0, true).stripe, options),
135
+ ).toMatchObject({
136
+ status: "available",
137
+ value: { quantity: "0", complete: false, nextCursor: "mtrusg_one" },
138
+ });
139
+ });
140
+ it("rejects unaligned windows and unsafe provider numbers without rounding", async () => {
141
+ const f = setup();
142
+ expect(
143
+ await observeProviderUsage(f.stripe, {
144
+ ...options,
145
+ period: { start: 601, end: 1200 },
146
+ }),
147
+ ).toMatchObject({
148
+ status: "unsupported",
149
+ reason: "minute_alignment_required",
150
+ });
151
+ expect(f.requests).toHaveLength(0);
152
+ expect(
153
+ await observeProviderUsage(
154
+ setup(Number.MAX_SAFE_INTEGER + 1).stripe,
155
+ options,
156
+ ),
157
+ ).toMatchObject({
158
+ status: "unavailable",
159
+ reason: "provider_precision_unsupported",
160
+ });
161
+ });
162
+
163
+ it("caches through the public facade without resending usage and exposes stale data", async () => {
164
+ const t = initConvexTest();
165
+ t.registerComponent("betterStripe", schema, modules);
166
+ const client = new BetterStripe(
167
+ componentsGeneric().betterStripe as unknown as Component,
168
+ );
169
+ const ctx = {
170
+ runQuery: (
171
+ ref: FunctionReference<"query">,
172
+ args: Record<string, unknown>,
173
+ ) => t.query(ref, args),
174
+ runMutation: (
175
+ ref: FunctionReference<"mutation">,
176
+ args: Record<string, unknown>,
177
+ ) => t.mutation(ref, args),
178
+ } as RunCtx;
179
+ const f = setup();
180
+ expect(await client.usage.getProviderUsage(ctx, options)).toMatchObject({
181
+ status: "unavailable",
182
+ reason: "provider_not_observed",
183
+ });
184
+ const result = await client.usage.reconcile(ctx, options, {
185
+ stripeSecretKey: "sk_test_observe",
186
+ httpClient: f.httpClient,
187
+ });
188
+ expect(result).toMatchObject({
189
+ local: { complete: true, eventCount: 0 },
190
+ aggregate: { status: "available", value: { quantity: "1.25" } },
191
+ comparison: { status: "mismatch" },
192
+ invoice: { status: "unavailable" },
193
+ });
194
+ expect(
195
+ f.requests.every((url) => !url.pathname.endsWith("meter_events")),
196
+ ).toBe(true);
197
+ const now = Date.now(),
198
+ clock = vi.spyOn(Date, "now").mockReturnValue(now + 61000);
199
+ try {
200
+ expect(await client.usage.getReconciliation(ctx, options)).toMatchObject({
201
+ aggregate: { status: "available", value: { stale: true } },
202
+ comparison: { status: "unavailable", reason: "aggregate_stale" },
203
+ });
204
+ } finally {
205
+ clock.mockRestore();
206
+ }
207
+ });
@@ -0,0 +1,124 @@
1
+ import type Stripe from "stripe";
2
+ import { UsageCatalogError } from "./catalogTypes.js";
3
+ import { decimalFromScaled } from "./summary.js";
4
+ import {
5
+ observationOptions,
6
+ verifyObservationSource,
7
+ type UsageObservationOptions,
8
+ type UsageAggregateObservation,
9
+ } from "./observationTypes.js";
10
+ export async function observeProviderUsage(
11
+ stripe: Stripe,
12
+ input: UsageObservationOptions,
13
+ ): Promise<UsageAggregateObservation> {
14
+ const opts = observationOptions(input),
15
+ observedAt = Math.floor(Date.now() / 1000);
16
+ const unavailable = (reason: string): UsageAggregateObservation => ({
17
+ status: "unavailable",
18
+ reason,
19
+ retryable: true,
20
+ });
21
+ if (opts.period.start % 60 || opts.period.end % 60)
22
+ return {
23
+ status: "unsupported",
24
+ reason: "minute_alignment_required",
25
+ retryable: false,
26
+ };
27
+ try {
28
+ if (!(await verifyObservationSource(stripe, opts)))
29
+ return {
30
+ status: "unsupported",
31
+ reason: "provider_binding_mismatch",
32
+ retryable: false,
33
+ };
34
+ const result = await stripe.billing.meters.listEventSummaries(
35
+ opts.scope.meterId,
36
+ {
37
+ customer: opts.binding.stripeCustomerId,
38
+ start_time: opts.period.start,
39
+ end_time: opts.period.end,
40
+ limit: opts.limit,
41
+ starting_after: opts.cursor ?? undefined,
42
+ },
43
+ );
44
+ if (!result.data.length)
45
+ return unavailable(
46
+ result.has_more ? "provider_history_incomplete" : "aggregation_pending",
47
+ );
48
+ if (result.data.length > opts.limit)
49
+ return unavailable("provider_history_incomplete");
50
+ const seen = new Set<string>();
51
+ let scaled = 0n;
52
+ const intervals: Array<{ start: number; end: number }> = [],
53
+ entries: Array<{
54
+ id: string;
55
+ start: number;
56
+ end: number;
57
+ scaledQuantity: string;
58
+ }> = [];
59
+ for (const summary of result.data) {
60
+ if (
61
+ summary.object !== "billing.meter_event_summary" ||
62
+ summary.meter !== opts.scope.meterId ||
63
+ summary.livemode !== opts.scope.livemode ||
64
+ !summary.id ||
65
+ summary.id.length > 2048 ||
66
+ seen.has(summary.id) ||
67
+ !Number.isSafeInteger(summary.start_time) ||
68
+ !Number.isSafeInteger(summary.end_time) ||
69
+ summary.start_time < opts.period.start ||
70
+ summary.end_time > opts.period.end ||
71
+ summary.end_time <= summary.start_time ||
72
+ intervals.some(
73
+ (w) => summary.start_time < w.end && summary.end_time > w.start,
74
+ )
75
+ )
76
+ return unavailable("provider_history_incomplete");
77
+ if (
78
+ !Number.isSafeInteger(summary.aggregated_value) ||
79
+ summary.aggregated_value < 0
80
+ )
81
+ return unavailable("provider_precision_unsupported");
82
+ seen.add(summary.id);
83
+ intervals.push({ start: summary.start_time, end: summary.end_time });
84
+ const value = BigInt(summary.aggregated_value);
85
+ scaled += value;
86
+ entries.push({
87
+ id: summary.id,
88
+ start: summary.start_time,
89
+ end: summary.end_time,
90
+ scaledQuantity: value.toString(),
91
+ });
92
+ }
93
+ const covered =
94
+ intervals.reduce((sum, w) => sum + w.end - w.start, 0) ===
95
+ opts.period.end - opts.period.start;
96
+ return {
97
+ status: "available",
98
+ observedAt,
99
+ value: {
100
+ period: opts.period,
101
+ quantity: decimalFromScaled(scaled, opts.binding.plan.unit.precision),
102
+ scaledQuantity: scaled.toString(),
103
+ complete: !result.has_more && opts.cursor === null && covered,
104
+ nextCursor: result.has_more
105
+ ? result.data[result.data.length - 1].id
106
+ : null,
107
+ aggregationLagPossible: true,
108
+ stale: false,
109
+ entries,
110
+ },
111
+ };
112
+ } catch (error) {
113
+ if (
114
+ error instanceof UsageCatalogError &&
115
+ error.code === "unsupported_scope"
116
+ )
117
+ return {
118
+ status: "unsupported",
119
+ reason: "unsupported_scope",
120
+ retryable: false,
121
+ };
122
+ return unavailable("provider_unavailable");
123
+ }
124
+ }