@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,152 @@
1
+ import type Stripe from "stripe";
2
+ import type { Component, RunCtx } from "../helpers.js";
3
+ import { runMutationOrThrow } from "../helpers.js";
4
+ import { componentRef } from "../webhooks/helpers.js";
5
+ import {
6
+ subscriptionTerms,
7
+ type UsageSubscriptionOptions,
8
+ type UsageSubscriptionTerms,
9
+ } from "./subscriptionTerms.js";
10
+ import {
11
+ subscriptionCall,
12
+ UsageSubscriptionError,
13
+ prepareSubscription,
14
+ verifySubscriptionRealm,
15
+ verifySubscriptionPrices,
16
+ discoverSubscription,
17
+ saveSubscription,
18
+ } from "./subscriptionProvider.js";
19
+ export function managedCheckoutParams(
20
+ terms: UsageSubscriptionTerms,
21
+ key: string,
22
+ ): Stripe.Checkout.SessionCreateParams {
23
+ if (terms.collection.method !== "checkout")
24
+ throw new UsageSubscriptionError(
25
+ "incompatible_terms",
26
+ "Managed Checkout requires Checkout collection",
27
+ );
28
+ return {
29
+ mode: "subscription",
30
+ customer_account: terms.meters[0].scope.customerAccount,
31
+ success_url: terms.collection.successUrl,
32
+ cancel_url: terms.collection.cancelUrl,
33
+ line_items: [
34
+ ...terms.meters.map((m) => ({ price: m.binding.stripePriceId })),
35
+ ...terms.fixedPriceIds.map((price) => ({ price, quantity: 1 })),
36
+ ],
37
+ metadata: { bsUsageIntent: key },
38
+ subscription_data: {
39
+ billing_mode: { type: "flexible" },
40
+ metadata: { bsUsageIntent: key },
41
+ },
42
+ };
43
+ }
44
+ async function findCheckout(
45
+ stripe: Stripe,
46
+ terms: UsageSubscriptionTerms,
47
+ key: string,
48
+ ) {
49
+ let cursor: string | undefined, found: Stripe.Checkout.Session | undefined;
50
+ for (let page = 0; page < 10; page++) {
51
+ const result = await stripe.checkout.sessions.list({
52
+ customer_account: terms.meters[0].scope.customerAccount,
53
+ limit: 100,
54
+ ...(cursor ? { starting_after: cursor } : {}),
55
+ });
56
+ if (result.data.length > 100) break;
57
+ for (const session of result.data)
58
+ if (session.metadata?.bsUsageIntent === key) {
59
+ if (found)
60
+ throw new UsageSubscriptionError(
61
+ "overlapping_enrollment",
62
+ "Ambiguous native usage Checkout identity",
63
+ );
64
+ found = session;
65
+ }
66
+ if (!result.has_more) return found;
67
+ const next = result.data[result.data.length - 1]?.id;
68
+ if (!next || next === cursor) break;
69
+ cursor = next;
70
+ }
71
+ throw new UsageSubscriptionError(
72
+ "incompatible_terms",
73
+ "Native usage Checkout history is incomplete",
74
+ );
75
+ }
76
+ export async function ensureManagedCheckout(
77
+ stripe: Stripe,
78
+ component: Component,
79
+ ctx: RunCtx,
80
+ input: UsageSubscriptionOptions,
81
+ ) {
82
+ const terms = subscriptionTerms(input),
83
+ startedAt = Date.now();
84
+ const params = managedCheckoutParams(terms, "pending");
85
+ return subscriptionCall(async () => {
86
+ await verifySubscriptionRealm(stripe, terms);
87
+ const row = await prepareSubscription(component, ctx, terms, "checkout");
88
+ await discoverSubscription(stripe, terms, row.key);
89
+ let session = row.checkoutId
90
+ ? await stripe.checkout.sessions.retrieve(row.checkoutId)
91
+ : await findCheckout(stripe, terms, row.key);
92
+ if (!session) {
93
+ if (Date.now() / 1000 - row.firstAttemptAt >= 23 * 3600)
94
+ throw new UsageSubscriptionError(
95
+ "unknown_create_outcome",
96
+ "Native Checkout create requires reconciliation after safe retry window",
97
+ );
98
+ await verifySubscriptionPrices(stripe, terms);
99
+ session = await stripe.checkout.sessions.create(
100
+ { ...params, ...managedCheckoutParams(terms, row.key) },
101
+ { idempotencyKey: `bs_usage_checkout_${row.key}` },
102
+ );
103
+ }
104
+ if (
105
+ (row.checkoutId && session.id !== row.checkoutId) ||
106
+ session.customer_account !== terms.meters[0].scope.customerAccount ||
107
+ (typeof session.customer === "string"
108
+ ? session.customer
109
+ : session.customer?.id) !== terms.meters[0].binding.stripeCustomerId ||
110
+ session.livemode !== terms.meters[0].scope.livemode ||
111
+ session.mode !== "subscription" ||
112
+ session.metadata?.bsUsageIntent !== row.key ||
113
+ !["open", "complete", "expired"].includes(session.status ?? "")
114
+ )
115
+ throw new UsageSubscriptionError(
116
+ "incompatible_terms",
117
+ "Native usage Checkout binding mismatch",
118
+ );
119
+ await runMutationOrThrow(
120
+ ctx,
121
+ componentRef(component, "usageSubscriptions/mutations/linkCheckout"),
122
+ { key: row.key, checkoutId: session.id },
123
+ );
124
+ const subscriptionId =
125
+ typeof session.subscription === "string"
126
+ ? session.subscription
127
+ : session.subscription?.id;
128
+ let view = null;
129
+ if (subscriptionId) {
130
+ const native = await stripe.subscriptions.retrieve(subscriptionId);
131
+ if (native.id !== subscriptionId)
132
+ throw new UsageSubscriptionError(
133
+ "incompatible_terms",
134
+ "Native Checkout subscription identity mismatch",
135
+ );
136
+ view = await saveSubscription(
137
+ component,
138
+ ctx,
139
+ row.key,
140
+ native,
141
+ terms,
142
+ startedAt,
143
+ );
144
+ }
145
+ return {
146
+ checkoutId: session.id,
147
+ status: session.status as "open" | "complete" | "expired",
148
+ url: session.status === "open" ? session.url : null,
149
+ subscription: view,
150
+ };
151
+ });
152
+ }
@@ -0,0 +1,316 @@
1
+ import { expect, it } from "vitest";
2
+ import { BetterStripe } from "../index.js";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import { fixture } from "./subscriptionTransport.fixtures.js";
5
+ import { request, nativeSubscription } from "./subscription.fixtures.js";
6
+ const ref = {
7
+ scope: {
8
+ stripeAccountId: "acct_platform",
9
+ customerAccount: "acct_buyer",
10
+ livemode: false,
11
+ },
12
+ requestId: "signup1",
13
+ };
14
+ it("exposes managed lifecycle through the public facade and retains original invoice provenance", async () => {
15
+ const f = fixture(),
16
+ client = new BetterStripe(f.component),
17
+ options = {
18
+ stripeSecretKey: "sk_test_subscription",
19
+ httpClient: f.httpClient,
20
+ };
21
+ await f.t.action((ctx) =>
22
+ client.usage.ensureSubscription(ctx as RunCtx, request, options),
23
+ );
24
+ expect(
25
+ await f.t.query((ctx) => client.usage.getSubscription(ctx as RunCtx, ref)),
26
+ ).toMatchObject({
27
+ status: "available",
28
+ value: {
29
+ subscriptionId: "sub_calls",
30
+ items: [
31
+ { meterId: "mtr_calls", unitAmountDecimal: null },
32
+ { meterId: null, quantity: "1" },
33
+ ],
34
+ },
35
+ });
36
+ const cancel = { ...ref, operationId: "cancel1", cancelAtPeriodEnd: true };
37
+ expect(
38
+ await f.t.action((ctx) =>
39
+ client.usage.setCancelAtPeriodEnd(ctx as RunCtx, cancel, options),
40
+ ),
41
+ ).toMatchObject({ cancelAtPeriodEnd: true });
42
+ await f.t.action((ctx) =>
43
+ client.usage.setCancelAtPeriodEnd(ctx as RunCtx, cancel, options),
44
+ );
45
+ expect(
46
+ f.calls.filter(
47
+ (c) => c.path === "/v1/subscriptions/sub_calls" && c.method === "POST",
48
+ ),
49
+ ).toHaveLength(1);
50
+ await f.t.action((ctx) =>
51
+ client.usage.setCancelAtPeriodEnd(
52
+ ctx as RunCtx,
53
+ { ...ref, operationId: "reactivate2", cancelAtPeriodEnd: false },
54
+ options,
55
+ ),
56
+ );
57
+ expect(
58
+ f.calls.filter(
59
+ (c) => c.path === "/v1/subscriptions/sub_calls" && c.method === "POST",
60
+ ),
61
+ ).toHaveLength(2);
62
+ const invoice = await f.t.action((ctx) =>
63
+ client.usage.observeSubscriptionInvoice(
64
+ ctx as RunCtx,
65
+ { ...ref, invoiceId: "in_closeout" },
66
+ options,
67
+ ),
68
+ );
69
+ expect(invoice[0].observation).toMatchObject({
70
+ status: "available",
71
+ value: {
72
+ finalized: true,
73
+ total: "1010",
74
+ paymentEvidence: "not_resolved",
75
+ lines: [{ amount: "10", quantity: "15", stripePriceId: "price_calls" }],
76
+ },
77
+ });
78
+ const history = await f.t.query((ctx) =>
79
+ client.usage.readSubscriptionHistory(ctx as RunCtx, {
80
+ ...ref,
81
+ kind: "invoice",
82
+ limit: 10,
83
+ cursor: null,
84
+ }),
85
+ );
86
+ expect(history.records).toHaveLength(1);
87
+ f.state.native!.status = "canceled";
88
+ expect(
89
+ await f.t.action((ctx) =>
90
+ client.usage.retireSubscription(
91
+ ctx as RunCtx,
92
+ { ...ref, invoiceId: "in_closeout" },
93
+ options,
94
+ ),
95
+ ),
96
+ ).toMatchObject({
97
+ retired: true,
98
+ creditTreatment: "retain_original_terms",
99
+ billingReconciliation: "required",
100
+ });
101
+ expect(
102
+ (
103
+ await f.t.query((ctx) =>
104
+ client.usage.readSubscriptionHistory(ctx as RunCtx, {
105
+ ...ref,
106
+ kind: "retirement",
107
+ limit: 10,
108
+ cursor: null,
109
+ }),
110
+ )
111
+ ).records,
112
+ ).toHaveLength(1);
113
+ });
114
+ it("pins Checkout sessions without recreating expired signup", async () => {
115
+ const f = fixture(),
116
+ client = new BetterStripe(f.component),
117
+ options = {
118
+ stripeSecretKey: "sk_test_subscription",
119
+ httpClient: f.httpClient,
120
+ };
121
+ const input = {
122
+ ...request,
123
+ collection: {
124
+ method: "checkout" as const,
125
+ successUrl: "https://example.test/success",
126
+ cancelUrl: "https://example.test/cancel",
127
+ },
128
+ };
129
+ expect(
130
+ await f.t.action((ctx) =>
131
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
132
+ ),
133
+ ).toMatchObject({ status: "open", subscription: null });
134
+ await f.t.action((ctx) =>
135
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
136
+ );
137
+ expect(
138
+ f.calls.filter(
139
+ (c) => c.path === "/v1/checkout/sessions" && c.method === "POST",
140
+ ),
141
+ ).toHaveLength(1);
142
+ f.state.session!.status = "expired";
143
+ expect(
144
+ await f.t.action((ctx) =>
145
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
146
+ ),
147
+ ).toMatchObject({ status: "expired", url: null });
148
+ expect(
149
+ f.calls.filter(
150
+ (c) => c.path === "/v1/checkout/sessions" && c.method === "POST",
151
+ ),
152
+ ).toHaveLength(1);
153
+ });
154
+ it("rejects foreign scoped reads, missing credentials and absent pinned provider IDs", async () => {
155
+ const f = fixture(),
156
+ client = new BetterStripe(f.component),
157
+ options = {
158
+ stripeSecretKey: "sk_test_subscription",
159
+ httpClient: f.httpClient,
160
+ };
161
+ await expect(
162
+ f.t.action((ctx) =>
163
+ client.usage.ensureSubscription(ctx as RunCtx, request, {}),
164
+ ),
165
+ ).rejects.toThrow(/credentials/);
166
+ await f.t.action((ctx) =>
167
+ client.usage.ensureSubscription(ctx as RunCtx, request, options),
168
+ );
169
+ await expect(
170
+ f.t.query((ctx) =>
171
+ client.usage.getSubscription(ctx as RunCtx, {
172
+ ...ref,
173
+ scope: { ...ref.scope, customerAccount: "acct_foreign" },
174
+ }),
175
+ ),
176
+ ).rejects.toThrow(/scope/);
177
+ f.state.missingNative = true;
178
+ await expect(
179
+ f.t.action((ctx) =>
180
+ client.usage.observeSubscription(ctx as RunCtx, ref, options),
181
+ ),
182
+ ).rejects.toThrow("Native usage subscription unavailable");
183
+ await expect(
184
+ f.t.action((ctx) =>
185
+ client.usage.ensureSubscription(ctx as RunCtx, request, options),
186
+ ),
187
+ ).rejects.toThrow("Native usage subscription unavailable");
188
+ expect(
189
+ f.calls.filter(
190
+ (c) => c.path === "/v1/subscriptions" && c.method === "POST",
191
+ ),
192
+ ).toHaveLength(1);
193
+ });
194
+
195
+ it("adopts the completed original Checkout subscription and reports unsupported key realms", async () => {
196
+ const f = fixture(),
197
+ client = new BetterStripe(f.component),
198
+ options = {
199
+ stripeSecretKey: "sk_test_subscription",
200
+ httpClient: f.httpClient,
201
+ };
202
+ const input = {
203
+ ...request,
204
+ collection: {
205
+ method: "checkout" as const,
206
+ successUrl: "https://example.test/success",
207
+ cancelUrl: "https://example.test/cancel",
208
+ },
209
+ };
210
+ await f.t.action((ctx) =>
211
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
212
+ );
213
+ f.state.native = {
214
+ ...nativeSubscription(),
215
+ collection_method: "charge_automatically",
216
+ days_until_due: null,
217
+ metadata: f.state.session!.metadata as Record<string, string>,
218
+ };
219
+ f.state.session!.status = "complete";
220
+ f.state.session!.subscription = "sub_calls";
221
+ expect(
222
+ await f.t.action((ctx) =>
223
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
224
+ ),
225
+ ).toMatchObject({
226
+ status: "complete",
227
+ url: null,
228
+ subscription: { subscriptionId: "sub_calls" },
229
+ });
230
+ expect(
231
+ await f.t.action((ctx) =>
232
+ client.usage.observeSubscription(ctx as RunCtx, ref, options),
233
+ ),
234
+ ).toMatchObject({ subscriptionId: "sub_calls" });
235
+ expect(
236
+ f.calls.filter(
237
+ (call) => call.path === "/v1/subscriptions" && call.method === "POST",
238
+ ),
239
+ ).toHaveLength(0);
240
+ f.state.realmId = "acct_other";
241
+ await expect(
242
+ f.t.action((ctx) =>
243
+ client.usage.observeSubscription(ctx as RunCtx, ref, options),
244
+ ),
245
+ ).rejects.toMatchObject({ code: "unsupported_scope" });
246
+ });
247
+
248
+ it("rejects a retrieved Checkout subscription ID that differs from the completed session", async () => {
249
+ const f = fixture(),
250
+ client = new BetterStripe(f.component),
251
+ options = {
252
+ stripeSecretKey: "sk_test_subscription",
253
+ httpClient: f.httpClient,
254
+ };
255
+ const input = {
256
+ ...request,
257
+ collection: {
258
+ method: "checkout" as const,
259
+ successUrl: "https://example.test/success",
260
+ cancelUrl: "https://example.test/cancel",
261
+ },
262
+ };
263
+ await f.t.action((ctx) =>
264
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
265
+ );
266
+ f.state.native = {
267
+ ...nativeSubscription(),
268
+ id: "sub_other",
269
+ metadata: f.state.session!.metadata as Record<string, string>,
270
+ };
271
+ f.state.session!.status = "complete";
272
+ f.state.session!.subscription = "sub_calls";
273
+ await expect(
274
+ f.t.action((ctx) =>
275
+ client.usage.ensureCheckout(ctx as RunCtx, input, options),
276
+ ),
277
+ ).rejects.toThrow("Native Checkout subscription identity mismatch");
278
+ });
279
+
280
+ it("records terminal cancellation refusal without leaving a lock that prevents closeout", async () => {
281
+ const f = fixture(),
282
+ client = new BetterStripe(f.component),
283
+ options = {
284
+ stripeSecretKey: "sk_test_subscription",
285
+ httpClient: f.httpClient,
286
+ };
287
+ await f.t.action((ctx) =>
288
+ client.usage.ensureSubscription(ctx as RunCtx, request, options),
289
+ );
290
+ f.state.native!.status = "canceled";
291
+ f.state.native!.cancel_at_period_end = true;
292
+ const command = {
293
+ ...ref,
294
+ operationId: "late-reactivation",
295
+ cancelAtPeriodEnd: false,
296
+ };
297
+ await expect(
298
+ f.t.action((ctx) =>
299
+ client.usage.setCancelAtPeriodEnd(ctx as RunCtx, command, options),
300
+ ),
301
+ ).rejects.toThrow(/cannot be reactivated/);
302
+ await expect(
303
+ f.t.action((ctx) =>
304
+ client.usage.setCancelAtPeriodEnd(ctx as RunCtx, command, options),
305
+ ),
306
+ ).rejects.toThrow(/cannot be reactivated/);
307
+ expect(
308
+ await f.t.action((ctx) =>
309
+ client.usage.retireSubscription(
310
+ ctx as RunCtx,
311
+ { ...ref, invoiceId: "in_closeout" },
312
+ options,
313
+ ),
314
+ ),
315
+ ).toMatchObject({ retired: true });
316
+ });
@@ -0,0 +1,204 @@
1
+ import { abandonManagedSignup } from "./subscriptionAbandonment.js";
2
+ import Stripe from "stripe";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import type { StripeApiVersion } from "../stripe-types.js";
5
+ import { componentRef } from "../webhooks/helpers.js";
6
+ import { UsageObservationClient } from "./observationClient.js";
7
+ import {
8
+ ensureManagedSubscription,
9
+ UsageSubscriptionError,
10
+ } from "./subscriptionProvider.js";
11
+ import { ensureManagedCheckout } from "./subscriptionCheckout.js";
12
+ import { changeManagedCancellation } from "./subscriptionCancellation.js";
13
+ import {
14
+ getSubscriptionIntent,
15
+ refreshManagedSubscription,
16
+ observeManagedInvoice,
17
+ retireManagedSubscription,
18
+ type UsageSubscriptionRef,
19
+ } from "./subscriptionLifecycle.js";
20
+ import {
21
+ subscriptionTerms,
22
+ type UsageSubscriptionOptions,
23
+ type UsageSubscriptionView,
24
+ } from "./subscriptionTerms.js";
25
+ import type { UsageDeliveryProviderOptions } from "./deliveryProvider.js";
26
+ import type { UsageAvailability } from "./boundaries.js";
27
+ import { validateUsagePageRequest } from "./boundaries.js";
28
+ import type { Doc } from "../../component/_generated/dataModel.js";
29
+ function provider(version: string, options: UsageDeliveryProviderOptions) {
30
+ if (!options.stripeSecretKey)
31
+ throw new UsageSubscriptionError(
32
+ "provider_unavailable",
33
+ "Native usage subscription credentials unavailable",
34
+ );
35
+ return new Stripe(options.stripeSecretKey, {
36
+ apiVersion: version as StripeApiVersion,
37
+ maxNetworkRetries: 0,
38
+ timeout: 15000,
39
+ ...(options.httpClient ? { httpClient: options.httpClient } : {}),
40
+ });
41
+ }
42
+ /** Trusted host authorizes the full payer/realm and every original meter first. */
43
+ export class UsageSubscriptionClient extends UsageObservationClient {
44
+ async ensureSubscription(
45
+ ctx: RunCtx,
46
+ input: UsageSubscriptionOptions,
47
+ options: UsageDeliveryProviderOptions,
48
+ ) {
49
+ const terms = subscriptionTerms(input);
50
+ return ensureManagedSubscription(
51
+ provider(terms.meters[0].binding.apiVersion, options),
52
+ this.component,
53
+ ctx,
54
+ terms,
55
+ );
56
+ }
57
+ async ensureCheckout(
58
+ ctx: RunCtx,
59
+ input: UsageSubscriptionOptions,
60
+ options: UsageDeliveryProviderOptions,
61
+ ) {
62
+ const terms = subscriptionTerms(input);
63
+ return ensureManagedCheckout(
64
+ provider(terms.meters[0].binding.apiVersion, options),
65
+ this.component,
66
+ ctx,
67
+ terms,
68
+ );
69
+ }
70
+ async getSubscription(
71
+ ctx: RunCtx,
72
+ input: UsageSubscriptionRef,
73
+ ): Promise<UsageAvailability<UsageSubscriptionView>> {
74
+ const row = await getSubscriptionIntent(this.component, ctx, input);
75
+ return row.viewJson && row.startedAt !== undefined
76
+ ? {
77
+ status: "available",
78
+ observedAt: Math.floor(row.startedAt / 1000),
79
+ value: JSON.parse(row.viewJson) as UsageSubscriptionView,
80
+ }
81
+ : {
82
+ status: "unavailable",
83
+ reason: "subscription_not_observed",
84
+ retryable: true,
85
+ };
86
+ }
87
+ async observeSubscription(
88
+ ctx: RunCtx,
89
+ input: UsageSubscriptionRef,
90
+ options: UsageDeliveryProviderOptions,
91
+ ) {
92
+ const row = await getSubscriptionIntent(this.component, ctx, input),
93
+ terms = subscriptionTerms(JSON.parse(row.termsJson));
94
+ return refreshManagedSubscription(
95
+ provider(terms.meters[0].binding.apiVersion, options),
96
+ this.component,
97
+ ctx,
98
+ row,
99
+ );
100
+ }
101
+ async setCancelAtPeriodEnd(
102
+ ctx: RunCtx,
103
+ input: UsageSubscriptionRef & {
104
+ operationId: string;
105
+ cancelAtPeriodEnd: boolean;
106
+ },
107
+ options: UsageDeliveryProviderOptions,
108
+ ) {
109
+ const row = await getSubscriptionIntent(this.component, ctx, input),
110
+ terms = subscriptionTerms(JSON.parse(row.termsJson));
111
+ return changeManagedCancellation(
112
+ provider(terms.meters[0].binding.apiVersion, options),
113
+ this.component,
114
+ ctx,
115
+ row,
116
+ {
117
+ operationId: input.operationId,
118
+ cancelAtPeriodEnd: input.cancelAtPeriodEnd,
119
+ },
120
+ );
121
+ }
122
+ async observeSubscriptionInvoice(
123
+ ctx: RunCtx,
124
+ input: UsageSubscriptionRef & { invoiceId: string },
125
+ options: UsageDeliveryProviderOptions,
126
+ ) {
127
+ const row = await getSubscriptionIntent(this.component, ctx, input),
128
+ terms = subscriptionTerms(JSON.parse(row.termsJson));
129
+ return observeManagedInvoice(
130
+ provider(terms.meters[0].binding.apiVersion, options),
131
+ this.component,
132
+ ctx,
133
+ row,
134
+ input.invoiceId,
135
+ );
136
+ }
137
+ async retireSubscription(
138
+ ctx: RunCtx,
139
+ input: UsageSubscriptionRef & { invoiceId: string },
140
+ options: UsageDeliveryProviderOptions,
141
+ ) {
142
+ const row = await getSubscriptionIntent(this.component, ctx, input),
143
+ terms = subscriptionTerms(JSON.parse(row.termsJson));
144
+ return retireManagedSubscription(
145
+ provider(terms.meters[0].binding.apiVersion, options),
146
+ this.component,
147
+ ctx,
148
+ row,
149
+ input.invoiceId,
150
+ );
151
+ }
152
+ async abandonSignup(
153
+ ctx: RunCtx,
154
+ input: UsageSubscriptionRef,
155
+ options: UsageDeliveryProviderOptions,
156
+ ) {
157
+ const row = await getSubscriptionIntent(this.component, ctx, input),
158
+ terms = subscriptionTerms(JSON.parse(row.termsJson));
159
+ return abandonManagedSignup(
160
+ provider(terms.meters[0].binding.apiVersion, options),
161
+ this.component,
162
+ ctx,
163
+ row,
164
+ );
165
+ }
166
+ async readSubscriptionHistory(
167
+ ctx: RunCtx,
168
+ input: UsageSubscriptionRef & {
169
+ kind: "subscription" | "invoice" | "retirement";
170
+ limit: number;
171
+ cursor: string | null;
172
+ },
173
+ ) {
174
+ const page = validateUsagePageRequest({
175
+ period: { start: 0, end: 1 },
176
+ limit: input.limit,
177
+ cursor: input.cursor,
178
+ });
179
+ await getSubscriptionIntent(this.component, ctx, input);
180
+ const result = (await ctx.runQuery(
181
+ componentRef(this.component, "usageSubscriptions/queries/history"),
182
+ {
183
+ scope: input.scope,
184
+ requestId: input.requestId,
185
+ kind: input.kind,
186
+ paginationOpts: { numItems: page.limit, cursor: page.cursor },
187
+ },
188
+ )) as {
189
+ page: Doc<"usageSubscriptionHistory">[];
190
+ isDone: boolean;
191
+ continueCursor: string;
192
+ };
193
+ return {
194
+ records: result.page.map((row) => ({
195
+ kind: row.kind,
196
+ resourceId: row.resourceId,
197
+ observedAt: Math.floor(row.startedAt / 1000),
198
+ observation: JSON.parse(row.observationJson) as unknown,
199
+ })),
200
+ isDone: result.isDone,
201
+ cursor: result.isDone ? null : result.continueCursor,
202
+ };
203
+ }
204
+ }
@@ -0,0 +1,14 @@
1
+ export class UsageSubscriptionError extends Error {
2
+ constructor(
3
+ public readonly code:
4
+ | "unsupported_scope"
5
+ | "overlapping_enrollment"
6
+ | "incompatible_terms"
7
+ | "unknown_create_outcome"
8
+ | "provider_unavailable",
9
+ message: string,
10
+ ) {
11
+ super(message);
12
+ this.name = "UsageSubscriptionError";
13
+ }
14
+ }