@fantastic.dev/better-stripe 0.52.0 → 0.54.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 (189) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +160 -2
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +80 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +160 -2
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +80 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +6 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/index.js +2 -0
  14. package/dist/client/index.js.map +1 -1
  15. package/dist/client/products/catalogClient.d.ts +23 -0
  16. package/dist/client/products/catalogClient.d.ts.map +1 -1
  17. package/dist/client/products/catalogClient.js +32 -0
  18. package/dist/client/products/catalogClient.js.map +1 -1
  19. package/dist/client/products/fixedPrice.d.ts +4 -0
  20. package/dist/client/products/fixedPrice.d.ts.map +1 -0
  21. package/dist/client/products/fixedPrice.js +10 -0
  22. package/dist/client/products/fixedPrice.js.map +1 -0
  23. package/dist/client/products/products.d.ts.map +1 -1
  24. package/dist/client/products/products.js +3 -0
  25. package/dist/client/products/products.js.map +1 -1
  26. package/dist/client/usage/catalog.d.ts +7 -0
  27. package/dist/client/usage/catalog.d.ts.map +1 -0
  28. package/dist/client/usage/catalog.js +55 -0
  29. package/dist/client/usage/catalog.js.map +1 -0
  30. package/dist/client/usage/catalogLifecycle.d.ts +25 -0
  31. package/dist/client/usage/catalogLifecycle.d.ts.map +1 -0
  32. package/dist/client/usage/catalogLifecycle.js +64 -0
  33. package/dist/client/usage/catalogLifecycle.js.map +1 -0
  34. package/dist/client/usage/catalogMath.d.ts +3 -0
  35. package/dist/client/usage/catalogMath.d.ts.map +1 -0
  36. package/dist/client/usage/catalogMath.js +21 -0
  37. package/dist/client/usage/catalogMath.js.map +1 -0
  38. package/dist/client/usage/catalogPrices.d.ts +5 -0
  39. package/dist/client/usage/catalogPrices.d.ts.map +1 -0
  40. package/dist/client/usage/catalogPrices.js +178 -0
  41. package/dist/client/usage/catalogPrices.js.map +1 -0
  42. package/dist/client/usage/catalogRead.d.ts +25 -0
  43. package/dist/client/usage/catalogRead.d.ts.map +1 -0
  44. package/dist/client/usage/catalogRead.js +71 -0
  45. package/dist/client/usage/catalogRead.js.map +1 -0
  46. package/dist/client/usage/catalogTypes.d.ts +97 -0
  47. package/dist/client/usage/catalogTypes.d.ts.map +1 -0
  48. package/dist/client/usage/catalogTypes.js +106 -0
  49. package/dist/client/usage/catalogTypes.js.map +1 -0
  50. package/dist/client/usage/client.d.ts +2 -2
  51. package/dist/client/usage/client.d.ts.map +1 -1
  52. package/dist/client/usage/client.js +3 -3
  53. package/dist/client/usage/client.js.map +1 -1
  54. package/dist/client/usage/deliveryClient.d.ts +64 -0
  55. package/dist/client/usage/deliveryClient.d.ts.map +1 -0
  56. package/dist/client/usage/deliveryClient.js +60 -0
  57. package/dist/client/usage/deliveryClient.js.map +1 -0
  58. package/dist/client/usage/deliveryProtocol.d.ts +130 -0
  59. package/dist/client/usage/deliveryProtocol.d.ts.map +1 -0
  60. package/dist/client/usage/deliveryProtocol.js +21 -0
  61. package/dist/client/usage/deliveryProtocol.js.map +1 -0
  62. package/dist/client/usage/deliveryProvider.d.ts +32 -0
  63. package/dist/client/usage/deliveryProvider.d.ts.map +1 -0
  64. package/dist/client/usage/deliveryProvider.js +127 -0
  65. package/dist/client/usage/deliveryProvider.js.map +1 -0
  66. package/dist/client/usage/index.d.ts +3 -0
  67. package/dist/client/usage/index.d.ts.map +1 -1
  68. package/dist/client/usage/index.js +1 -0
  69. package/dist/client/usage/index.js.map +1 -1
  70. package/dist/client/webhooks/handler.d.ts.map +1 -1
  71. package/dist/client/webhooks/handler.js +2 -1
  72. package/dist/client/webhooks/handler.js.map +1 -1
  73. package/dist/client/webhooks/meterErrors.d.ts +5 -0
  74. package/dist/client/webhooks/meterErrors.d.ts.map +1 -0
  75. package/dist/client/webhooks/meterErrors.js +98 -0
  76. package/dist/client/webhooks/meterErrors.js.map +1 -0
  77. package/dist/client/webhooks/processors.d.ts.map +1 -1
  78. package/dist/client/webhooks/processors.js +3 -0
  79. package/dist/client/webhooks/processors.js.map +1 -1
  80. package/dist/client/webhooks/v2.d.ts.map +1 -1
  81. package/dist/client/webhooks/v2.js +5 -0
  82. package/dist/client/webhooks/v2.js.map +1 -1
  83. package/dist/component/_generated/api.d.ts +18 -0
  84. package/dist/component/_generated/api.d.ts.map +1 -1
  85. package/dist/component/_generated/api.js.map +1 -1
  86. package/dist/component/_generated/component.d.ts +232 -0
  87. package/dist/component/_generated/component.d.ts.map +1 -1
  88. package/dist/component/earnings/triggers.d.ts +150 -2
  89. package/dist/component/earnings/triggers.d.ts.map +1 -1
  90. package/dist/component/payoutRelease/queries.d.ts +2 -2
  91. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  92. package/dist/component/refundHistory/queries.d.ts +1 -1
  93. package/dist/component/schema.d.ts +80 -1
  94. package/dist/component/schema.js +5 -0
  95. package/dist/component/schema.js.map +1 -1
  96. package/dist/component/usage/schema.d.ts +96 -1
  97. package/dist/component/usage/schema.d.ts.map +1 -1
  98. package/dist/component/usage/schema.js +11 -2
  99. package/dist/component/usage/schema.js.map +1 -1
  100. package/dist/component/usageCatalog/mutations.d.ts +25 -0
  101. package/dist/component/usageCatalog/mutations.d.ts.map +1 -0
  102. package/dist/component/usageCatalog/mutations.js +75 -0
  103. package/dist/component/usageCatalog/mutations.js.map +1 -0
  104. package/dist/component/usageCatalog/queries.d.ts +33 -0
  105. package/dist/component/usageCatalog/queries.d.ts.map +1 -0
  106. package/dist/component/usageCatalog/queries.js +26 -0
  107. package/dist/component/usageCatalog/queries.js.map +1 -0
  108. package/dist/component/usageCatalog/schema.d.ts +57 -0
  109. package/dist/component/usageCatalog/schema.d.ts.map +1 -0
  110. package/dist/component/usageCatalog/schema.js +22 -0
  111. package/dist/component/usageCatalog/schema.js.map +1 -0
  112. package/dist/component/usageDelivery/bridge.d.ts +25 -0
  113. package/dist/component/usageDelivery/bridge.d.ts.map +1 -0
  114. package/dist/component/usageDelivery/bridge.js +45 -0
  115. package/dist/component/usageDelivery/bridge.js.map +1 -0
  116. package/dist/component/usageDelivery/fields.d.ts +78 -0
  117. package/dist/component/usageDelivery/fields.d.ts.map +1 -0
  118. package/dist/component/usageDelivery/fields.js +38 -0
  119. package/dist/component/usageDelivery/fields.js.map +1 -0
  120. package/dist/component/usageDelivery/helpers.d.ts +83 -0
  121. package/dist/component/usageDelivery/helpers.d.ts.map +1 -0
  122. package/dist/component/usageDelivery/helpers.js +63 -0
  123. package/dist/component/usageDelivery/helpers.js.map +1 -0
  124. package/dist/component/usageDelivery/mutations.d.ts +97 -0
  125. package/dist/component/usageDelivery/mutations.d.ts.map +1 -0
  126. package/dist/component/usageDelivery/mutations.js +153 -0
  127. package/dist/component/usageDelivery/mutations.js.map +1 -0
  128. package/dist/component/usageDelivery/queries.d.ts +113 -0
  129. package/dist/component/usageDelivery/queries.d.ts.map +1 -0
  130. package/dist/component/usageDelivery/queries.js +22 -0
  131. package/dist/component/usageDelivery/queries.js.map +1 -0
  132. package/dist/component/usageDelivery/schema.d.ts +79 -0
  133. package/dist/component/usageDelivery/schema.d.ts.map +1 -0
  134. package/dist/component/usageDelivery/schema.js +30 -0
  135. package/dist/component/usageDelivery/schema.js.map +1 -0
  136. package/dist/component/usageDelivery/steps.d.ts +85 -0
  137. package/dist/component/usageDelivery/steps.d.ts.map +1 -0
  138. package/dist/component/usageDelivery/steps.js +154 -0
  139. package/dist/component/usageDelivery/steps.js.map +1 -0
  140. package/dist/component/usageDelivery/workflow.d.ts +15 -0
  141. package/dist/component/usageDelivery/workflow.d.ts.map +1 -0
  142. package/dist/component/usageDelivery/workflow.js +28 -0
  143. package/dist/component/usageDelivery/workflow.js.map +1 -0
  144. package/docs/README.md +5 -1
  145. package/docs/metering-setup.md +3 -1
  146. package/docs/usage-catalog.md +106 -0
  147. package/docs/usage-delivery.md +143 -0
  148. package/package.json +4 -2
  149. package/src/client/index.ts +23 -0
  150. package/src/client/products/catalogClient.ts +77 -0
  151. package/src/client/products/fixedPrice.test.ts +57 -0
  152. package/src/client/products/fixedPrice.ts +13 -0
  153. package/src/client/products/products.ts +2 -0
  154. package/src/client/usage/catalog.test.ts +464 -0
  155. package/src/client/usage/catalog.ts +117 -0
  156. package/src/client/usage/catalogLifecycle.ts +128 -0
  157. package/src/client/usage/catalogMath.test.ts +13 -0
  158. package/src/client/usage/catalogMath.ts +22 -0
  159. package/src/client/usage/catalogPrices.ts +251 -0
  160. package/src/client/usage/catalogRead.ts +98 -0
  161. package/src/client/usage/catalogTypes.ts +170 -0
  162. package/src/client/usage/client.ts +5 -2
  163. package/src/client/usage/deliveryClient.ts +130 -0
  164. package/src/client/usage/deliveryProtocol.ts +26 -0
  165. package/src/client/usage/deliveryProvider.test.ts +207 -0
  166. package/src/client/usage/deliveryProvider.ts +155 -0
  167. package/src/client/usage/index.ts +13 -0
  168. package/src/client/webhooks/handler.ts +2 -1
  169. package/src/client/webhooks/meterErrors.test.ts +164 -0
  170. package/src/client/webhooks/meterErrors.ts +118 -0
  171. package/src/client/webhooks/processors.ts +2 -0
  172. package/src/client/webhooks/v2.ts +5 -0
  173. package/src/component/_generated/api.ts +18 -0
  174. package/src/component/_generated/component.ts +380 -0
  175. package/src/component/schema.ts +8 -0
  176. package/src/component/usage/schema.ts +11 -2
  177. package/src/component/usageCatalog/mutations.ts +79 -0
  178. package/src/component/usageCatalog/queries.ts +32 -0
  179. package/src/component/usageCatalog/schema.ts +21 -0
  180. package/src/component/usageDelivery/bridge.ts +56 -0
  181. package/src/component/usageDelivery/concurrency.test.ts +62 -0
  182. package/src/component/usageDelivery/fields.ts +59 -0
  183. package/src/component/usageDelivery/helpers.ts +77 -0
  184. package/src/component/usageDelivery/mutations.ts +185 -0
  185. package/src/component/usageDelivery/queries.ts +25 -0
  186. package/src/component/usageDelivery/schema.ts +33 -0
  187. package/src/component/usageDelivery/steps.ts +171 -0
  188. package/src/component/usageDelivery/workflow.test.ts +402 -0
  189. package/src/component/usageDelivery/workflow.ts +36 -0
@@ -0,0 +1,128 @@
1
+ import type Stripe from "stripe";
2
+ import { z } from "zod";
3
+ import type { Component, RunCtx } from "../helpers.js";
4
+ import { componentRef } from "../webhooks/helpers.js";
5
+ import {
6
+ UsageCatalogError,
7
+ meterTerms,
8
+ meterKey,
9
+ verifyRealm,
10
+ verifyMeter,
11
+ meterObservation,
12
+ prepareCatalog,
13
+ completeCatalog,
14
+ catalogScope,
15
+ nativeCall,
16
+ type UsageCatalogScope,
17
+ type UsageMeterOptions,
18
+ } from "./catalogTypes.js";
19
+ import type { Doc } from "../../component/_generated/dataModel.js";
20
+ const meterId = z
21
+ .string()
22
+ .regex(/^mtr_[a-zA-Z0-9_]+$/)
23
+ .max(100);
24
+ export async function adoptUsageMeter(
25
+ stripe: Stripe,
26
+ component: Component,
27
+ ctx: RunCtx,
28
+ opts: UsageMeterOptions & { meterId: string },
29
+ ): Promise<Stripe.Billing.Meter> {
30
+ const terms = meterTerms(opts);
31
+ const meter = await getUsageMeterFromStripe(stripe, {
32
+ scope: terms.scope,
33
+ meterId: opts.meterId,
34
+ });
35
+ verifyMeter(meter, terms, false);
36
+ const row = await prepareCatalog(
37
+ component,
38
+ ctx,
39
+ "meter",
40
+ terms.scope,
41
+ meterKey(terms.plan),
42
+ terms,
43
+ );
44
+ await completeCatalog(component, ctx, row, meter.id, meterObservation(meter));
45
+ return meter;
46
+ }
47
+ export async function getUsageMeterFromStripe(
48
+ stripe: Stripe,
49
+ opts: { scope: UsageCatalogScope; meterId: string },
50
+ ): Promise<Stripe.Billing.Meter> {
51
+ const id = meterId.parse(opts.meterId);
52
+ await verifyRealm(stripe, opts.scope);
53
+ const meter = await nativeCall(() => stripe.billing.meters.retrieve(id));
54
+ if (meter.id !== id || meter.livemode !== opts.scope.livemode)
55
+ throw new UsageCatalogError(
56
+ "incompatible_terms",
57
+ "Native meter identity or mode mismatch",
58
+ );
59
+ return meter;
60
+ }
61
+ export async function listStripeUsageMeters(
62
+ stripe: Stripe,
63
+ opts: { scope: UsageCatalogScope; limit: number; cursor?: string },
64
+ ): Promise<{
65
+ data: Stripe.Billing.Meter[];
66
+ hasMore: boolean;
67
+ cursor: string | null;
68
+ }> {
69
+ const limit = z.number().int().min(1).max(100).parse(opts.limit);
70
+ const cursor = meterId.optional().parse(opts.cursor);
71
+ await verifyRealm(stripe, opts.scope);
72
+ const page = await nativeCall(() =>
73
+ stripe.billing.meters.list({ limit, starting_after: cursor }),
74
+ );
75
+ if (
76
+ page.data.some((meter) => meter.livemode !== opts.scope.livemode) ||
77
+ (page.has_more && !page.data.length)
78
+ )
79
+ throw new UsageCatalogError(
80
+ "ambiguous_lookup",
81
+ "Native meter page is inconsistent",
82
+ );
83
+ return {
84
+ data: page.data,
85
+ hasMore: page.has_more,
86
+ cursor: page.has_more ? page.data[page.data.length - 1].id : null,
87
+ };
88
+ }
89
+ export async function setUsageMeterActive(
90
+ stripe: Stripe,
91
+ component: Component,
92
+ ctx: RunCtx,
93
+ opts: { scope: UsageCatalogScope; meterId: string; active: boolean },
94
+ ): Promise<Stripe.Billing.Meter> {
95
+ const current = await getUsageMeterFromStripe(stripe, opts);
96
+ const row = (await ctx.runQuery(
97
+ componentRef(component, "usageCatalog/queries/getByProvider"),
98
+ {
99
+ scopeKey: JSON.stringify(catalogScope(opts.scope)),
100
+ kind: "meter",
101
+ providerId: opts.meterId,
102
+ },
103
+ )) as Doc<"usageCatalog"> | null;
104
+ if (!row)
105
+ throw new UsageCatalogError(
106
+ "incompatible_terms",
107
+ "Adopt a native meter before changing its lifecycle",
108
+ );
109
+ const terms = meterTerms(JSON.parse(row.termsJson) as UsageMeterOptions);
110
+ verifyMeter(current, terms, false);
111
+ const target = opts.active ? "active" : "inactive";
112
+ const meter =
113
+ current.status === target
114
+ ? current
115
+ : await nativeCall(() =>
116
+ opts.active
117
+ ? stripe.billing.meters.reactivate(opts.meterId)
118
+ : stripe.billing.meters.deactivate(opts.meterId),
119
+ );
120
+ verifyMeter(meter, terms, false);
121
+ if (meter.id !== opts.meterId || meter.status !== target)
122
+ throw new UsageCatalogError(
123
+ "provider_unavailable",
124
+ "Native meter lifecycle outcome is uncertain",
125
+ );
126
+ await completeCatalog(component, ctx, row, meter.id, meterObservation(meter));
127
+ return meter;
128
+ }
@@ -0,0 +1,13 @@
1
+ import { expect, it } from "vitest";
2
+ import { scaledUsageRate } from "./catalogMath.js";
3
+ it("scales native per-unit rates exactly without money floats", () => {
4
+ expect(scaledUsageRate("2", 2)).toBe("0.02");
5
+ expect(scaledUsageRate("123.4500", 3)).toBe("0.12345");
6
+ expect(scaledUsageRate("0", 6)).toBe("0");
7
+ expect(scaledUsageRate("999999999999.123456", 6)).toBe("999999.999999123456");
8
+ });
9
+ it("rejects native decimal precision loss rather than rounding", () => {
10
+ expect(() => scaledUsageRate("0.000000000001", 1)).toThrow();
11
+ expect(() => scaledUsageRate("2", 7)).toThrow();
12
+ expect(() => scaledUsageRate("-2", 0)).toThrow();
13
+ });
@@ -0,0 +1,22 @@
1
+ /** Convert minor currency units per whole unit to a native scaled-unit rate. */
2
+ export function scaledUsageRate(rate: string, precision: number): string {
3
+ if (
4
+ !Number.isInteger(precision) ||
5
+ precision < 0 ||
6
+ precision > 6 ||
7
+ !/^(0|[1-9]\d{0,11})(\.\d{1,12})?$/.test(rate)
8
+ )
9
+ throw new Error("Unsupported native usage rate");
10
+ const [whole, fraction = ""] = rate.split(".");
11
+ const places = fraction.length + precision;
12
+ const digits = (whole + fraction).padStart(places + 1, "0");
13
+ const raw = places
14
+ ? `${digits.slice(0, -places)}.${digits.slice(-places)}`
15
+ : digits;
16
+ const [integer, decimal = ""] = raw.split(".");
17
+ const normalized = decimal.replace(/0+$/, "");
18
+ if (normalized.length > 12)
19
+ throw new Error("Unsupported native usage rate precision");
20
+ const base = BigInt(integer).toString();
21
+ return normalized ? `${base}.${normalized}` : base;
22
+ }
@@ -0,0 +1,251 @@
1
+ import Stripe from "stripe";
2
+ import { z } from "zod";
3
+ import type { Component, RunCtx } from "../helpers.js";
4
+ import { componentRef } from "../webhooks/helpers.js";
5
+ import { getChargeCurrencyMetadata } from "../charge-currency.js";
6
+ import { defineUsagePlan, parseUsageQuantity } from "./contracts.js";
7
+ import { scaledUsageRate } from "./catalogMath.js";
8
+
9
+ import {
10
+ UsageCatalogError,
11
+ verifyMeter,
12
+ catalogScope,
13
+ meterKey,
14
+ meterTerms,
15
+ verifyRealm,
16
+ prepareCatalog,
17
+ completeCatalog,
18
+ operationKey,
19
+ permitCreate,
20
+ nativeCall,
21
+ type UsageMeterOptions,
22
+ type UsagePriceOptions,
23
+ } from "./catalogTypes.js";
24
+ import type { Doc } from "../../component/_generated/dataModel.js";
25
+ function incompatible(): never {
26
+ throw new UsageCatalogError(
27
+ "incompatible_terms",
28
+ "Native price has incompatible immutable terms",
29
+ );
30
+ }
31
+ function decimal(
32
+ value: Stripe.Decimal | string | null | undefined,
33
+ integer: number | null | undefined,
34
+ ) {
35
+ const text =
36
+ value?.toString() ??
37
+ (Number.isSafeInteger(integer) && integer !== null && integer !== undefined
38
+ ? String(integer)
39
+ : undefined);
40
+ if (text === undefined || !/^\d+(\.\d{1,12})?$/.test(text))
41
+ return incompatible();
42
+ const [whole, fraction = ""] = text.split(".");
43
+ const trimmed = fraction.replace(/0+$/, "");
44
+ const normalized = BigInt(whole).toString();
45
+ return trimmed ? `${normalized}.${trimmed}` : normalized;
46
+ }
47
+ function termsFor(opts: UsagePriceOptions) {
48
+ const plan = defineUsagePlan(opts.plan);
49
+ if (!getChargeCurrencyMetadata(plan.rate.currency)) return incompatible();
50
+ const terms = {
51
+ scope: catalogScope(opts.scope),
52
+ plan,
53
+ meterId: z
54
+ .string()
55
+ .regex(/^mtr_[a-zA-Z0-9_]+$/)
56
+ .max(100)
57
+ .parse(opts.meterId),
58
+ stripeProductId: z
59
+ .string()
60
+ .regex(/^prod_[a-zA-Z0-9]+$/)
61
+ .max(100)
62
+ .parse(opts.stripeProductId),
63
+ lookupKey: z.string().min(1).max(200).parse(opts.lookupKey),
64
+ };
65
+ const rate = scaledUsageRate(
66
+ plan.rate.unitAmountDecimal,
67
+ plan.unit.precision,
68
+ );
69
+ let included: number | undefined;
70
+ if (plan.model === "included_overage") {
71
+ const scaled = BigInt(
72
+ parseUsageQuantity(plan.includedQuantity, plan.unit.precision)
73
+ .scaledQuantity,
74
+ );
75
+ if (scaled < 1n || scaled > BigInt(Number.MAX_SAFE_INTEGER))
76
+ return incompatible();
77
+ included = Number(scaled);
78
+ }
79
+ return { terms, rate, included };
80
+ }
81
+ function verifyPrice(
82
+ price: Stripe.Price,
83
+ opts: UsagePriceOptions,
84
+ rate: string,
85
+ included: number | undefined,
86
+ ) {
87
+ const product =
88
+ typeof price.product === "string" ? price.product : price.product.id;
89
+ if (
90
+ !price.active ||
91
+ price.livemode !== opts.scope.livemode ||
92
+ price.lookup_key !== opts.lookupKey ||
93
+ product !== opts.stripeProductId ||
94
+ price.currency !== opts.plan.rate.currency ||
95
+ price.type !== "recurring" ||
96
+ price.recurring?.interval !== "month" ||
97
+ price.recurring.interval_count !== 1 ||
98
+ price.recurring.usage_type !== "metered" ||
99
+ price.recurring.meter !== opts.meterId ||
100
+ price.transform_quantity != null
101
+ )
102
+ return incompatible();
103
+ if (included === undefined) {
104
+ if (
105
+ price.billing_scheme !== "per_unit" ||
106
+ decimal(price.unit_amount_decimal, price.unit_amount) !== rate
107
+ )
108
+ return incompatible();
109
+ } else {
110
+ if (
111
+ price.billing_scheme !== "tiered" ||
112
+ price.tiers_mode !== "graduated" ||
113
+ price.tiers?.length !== 2
114
+ )
115
+ return incompatible();
116
+ const [free, overage] = price.tiers;
117
+ if (
118
+ free.up_to !== included ||
119
+ overage.up_to !== null ||
120
+ decimal(free.unit_amount_decimal, free.unit_amount) !== "0" ||
121
+ decimal(overage.unit_amount_decimal, overage.unit_amount) !== rate
122
+ )
123
+ return incompatible();
124
+ for (const tier of price.tiers)
125
+ if (
126
+ (tier.flat_amount != null && tier.flat_amount !== 0) ||
127
+ (tier.flat_amount_decimal != null &&
128
+ decimal(tier.flat_amount_decimal, 0) !== "0")
129
+ )
130
+ return incompatible();
131
+ }
132
+ }
133
+ export async function ensureUsagePrice(
134
+ stripe: Stripe,
135
+ component: Component,
136
+ ctx: RunCtx,
137
+ opts: UsagePriceOptions,
138
+ ): Promise<Stripe.Price> {
139
+ const { terms, rate, included } = termsFor(opts);
140
+ await verifyRealm(stripe, terms.scope);
141
+ const meterRow = (await ctx.runQuery(
142
+ componentRef(component, "usageCatalog/queries/get"),
143
+ {
144
+ scopeKey: JSON.stringify(terms.scope),
145
+ kind: "meter",
146
+ key: meterKey(terms.plan),
147
+ },
148
+ )) as Doc<"usageCatalog"> | null;
149
+ if (!meterRow || meterRow.providerId !== terms.meterId) return incompatible();
150
+ const meterOpts = meterTerms(
151
+ JSON.parse(meterRow.termsJson) as UsageMeterOptions,
152
+ );
153
+ if (JSON.stringify(meterOpts.plan) !== JSON.stringify(terms.plan))
154
+ return incompatible();
155
+ const meter = await nativeCall(() =>
156
+ stripe.billing.meters.retrieve(terms.meterId),
157
+ );
158
+ if (meter.id !== terms.meterId) return incompatible();
159
+ verifyMeter(meter, meterOpts);
160
+ const product = await nativeCall(() =>
161
+ stripe.products.retrieve(terms.stripeProductId),
162
+ );
163
+ if (
164
+ "deleted" in product ||
165
+ !product.active ||
166
+ product.id !== terms.stripeProductId
167
+ )
168
+ return incompatible();
169
+ const row = await prepareCatalog(
170
+ component,
171
+ ctx,
172
+ "price",
173
+ terms.scope,
174
+ terms.lookupKey,
175
+ terms,
176
+ );
177
+ let price: Stripe.Price | undefined;
178
+ if (row.providerId)
179
+ price = await nativeCall(() =>
180
+ stripe.prices.retrieve(row.providerId!, { expand: ["tiers"] }),
181
+ );
182
+ else {
183
+ const result = await nativeCall(() =>
184
+ stripe.prices.list({
185
+ lookup_keys: [terms.lookupKey],
186
+ limit: 2,
187
+ expand: ["data.tiers"],
188
+ }),
189
+ );
190
+ if (result.has_more || result.data.length > 1)
191
+ throw new UsageCatalogError(
192
+ "ambiguous_lookup",
193
+ "Native price lookup key is ambiguous",
194
+ );
195
+ price = result.data[0];
196
+ }
197
+ if (!price) {
198
+ permitCreate(row);
199
+ const key = await operationKey(terms, "price");
200
+ const params: Stripe.PriceCreateParams = {
201
+ product: terms.stripeProductId,
202
+ currency: terms.plan.rate.currency,
203
+ lookup_key: terms.lookupKey,
204
+ recurring: {
205
+ interval: "month",
206
+ usage_type: "metered",
207
+ meter: terms.meterId,
208
+ },
209
+ expand: ["tiers"],
210
+ ...(included === undefined
211
+ ? {
212
+ billing_scheme: "per_unit",
213
+ unit_amount_decimal: Stripe.Decimal.from(rate),
214
+ }
215
+ : {
216
+ billing_scheme: "tiered",
217
+ tiers_mode: "graduated",
218
+ tiers: [
219
+ { up_to: included, unit_amount_decimal: Stripe.Decimal.zero },
220
+ { up_to: "inf", unit_amount_decimal: Stripe.Decimal.from(rate) },
221
+ ],
222
+ }),
223
+ };
224
+ price = await nativeCall(() =>
225
+ stripe.prices.create(params, { idempotencyKey: key }),
226
+ );
227
+ }
228
+ verifyPrice(price, terms, rate, included);
229
+ if (row.providerId && row.providerId !== price.id) return incompatible();
230
+ await completeCatalog(component, ctx, row, price.id, {
231
+ type: "metered_price",
232
+ id: price.id,
233
+ productId: terms.stripeProductId,
234
+ meterId: terms.meterId,
235
+ livemode: price.livemode,
236
+ active: price.active,
237
+ currency: price.currency,
238
+ billingScheme: price.billing_scheme,
239
+ unitAmountDecimal:
240
+ price.billing_scheme === "per_unit"
241
+ ? decimal(price.unit_amount_decimal, price.unit_amount)
242
+ : null,
243
+ tiers:
244
+ price.tiers?.map((tier) => ({
245
+ upTo: tier.up_to === null ? null : String(tier.up_to),
246
+ unitAmountDecimal: decimal(tier.unit_amount_decimal, tier.unit_amount),
247
+ })) ?? [],
248
+ interval: "month",
249
+ });
250
+ return price;
251
+ }
@@ -0,0 +1,98 @@
1
+ import { z } from "zod";
2
+ import { componentRef } from "../webhooks/helpers.js";
3
+ import { catalogScope } from "./catalogTypes.js";
4
+ import { defineUsagePlan } from "./contracts.js";
5
+ import type { Doc } from "../../component/_generated/dataModel.js";
6
+ import type { Component, RunCtx } from "../helpers.js";
7
+ import type { UsageCatalogScope } from "./catalogTypes.js";
8
+ import type { UsageAvailability } from "./boundaries.js";
9
+ import type { UsagePlan } from "./contracts.js";
10
+ export type UsagePriceBinding = {
11
+ pricingMode: "metered";
12
+ stripePriceId: string;
13
+ stripeProductId: string;
14
+ meterId: string;
15
+ active: boolean;
16
+ currency: string;
17
+ billingScheme: "per_unit" | "tiered";
18
+ unitAmountDecimal: string | null;
19
+ tiers: Array<{ upTo: string | null; unitAmountDecimal: string }>;
20
+ interval: "month";
21
+ plan: UsagePlan;
22
+ };
23
+ const observation = z.strictObject({
24
+ type: z.literal("metered_price"),
25
+ id: z.string(),
26
+ productId: z.string(),
27
+ meterId: z.string(),
28
+ livemode: z.boolean(),
29
+ active: z.boolean(),
30
+ currency: z.string(),
31
+ billingScheme: z.enum(["per_unit", "tiered"]),
32
+ unitAmountDecimal: z.string().nullable(),
33
+ tiers: z.array(
34
+ z.strictObject({
35
+ upTo: z.string().nullable(),
36
+ unitAmountDecimal: z.string(),
37
+ }),
38
+ ),
39
+ interval: z.literal("month"),
40
+ });
41
+ export async function getUsagePriceBinding(
42
+ component: Component,
43
+ ctx: RunCtx,
44
+ opts: { scope: UsageCatalogScope; lookupKey: string },
45
+ ): Promise<UsageAvailability<UsagePriceBinding>> {
46
+ const scope = catalogScope(opts.scope);
47
+ const key = z.string().min(1).max(200).parse(opts.lookupKey);
48
+ const row = (await ctx.runQuery(
49
+ componentRef(component, "usageCatalog/queries/get"),
50
+ { scopeKey: JSON.stringify(scope), kind: "price", key },
51
+ )) as Doc<"usageCatalog"> | null;
52
+ if (!row)
53
+ return {
54
+ status: "unavailable",
55
+ reason: "catalog_not_found",
56
+ retryable: false,
57
+ };
58
+ if (!row.observationJson || row.observedAt === undefined)
59
+ return {
60
+ status: "unavailable",
61
+ reason: "catalog_pending",
62
+ retryable: true,
63
+ };
64
+ try {
65
+ const price = observation.parse(JSON.parse(row.observationJson));
66
+ const plan = defineUsagePlan(JSON.parse(row.termsJson).plan);
67
+ if (
68
+ price.id !== row.providerId ||
69
+ price.livemode !== scope.livemode ||
70
+ price.currency !== plan.rate.currency ||
71
+ (price.billingScheme === "per_unit" && price.unitAmountDecimal === null)
72
+ )
73
+ throw new Error("Invalid catalog observation");
74
+ return {
75
+ status: "available",
76
+ observedAt: row.observedAt,
77
+ value: {
78
+ pricingMode: "metered",
79
+ stripePriceId: price.id,
80
+ stripeProductId: price.productId,
81
+ meterId: price.meterId,
82
+ active: price.active,
83
+ currency: price.currency,
84
+ billingScheme: price.billingScheme,
85
+ unitAmountDecimal: price.unitAmountDecimal,
86
+ tiers: price.tiers,
87
+ interval: price.interval,
88
+ plan,
89
+ },
90
+ };
91
+ } catch {
92
+ return {
93
+ status: "unavailable",
94
+ reason: "invalid_catalog_observation",
95
+ retryable: false,
96
+ };
97
+ }
98
+ }
@@ -0,0 +1,170 @@
1
+ import type Stripe from "stripe";
2
+ import { z } from "zod";
3
+ import type { Component, RunCtx } from "../helpers.js";
4
+ import { runMutationOrThrow } from "../helpers.js";
5
+ import { componentRef } from "../webhooks/helpers.js";
6
+ import { defineUsagePlan, type UsagePlan } from "./contracts.js";
7
+ import type { Doc } from "../../component/_generated/dataModel.js";
8
+ export type UsageCatalogScope = { stripeAccountId: string; livemode: boolean };
9
+ export type UsageMeterOptions = {
10
+ scope: UsageCatalogScope;
11
+ plan: UsagePlan;
12
+ eventName: string;
13
+ displayName: string;
14
+ };
15
+ export type UsagePriceOptions = {
16
+ scope: UsageCatalogScope;
17
+ plan: UsagePlan;
18
+ meterId: string;
19
+ stripeProductId: string;
20
+ lookupKey: string;
21
+ };
22
+ export class UsageCatalogError extends Error {
23
+ constructor(
24
+ public readonly code:
25
+ | "unsupported_scope"
26
+ | "incompatible_terms"
27
+ | "ambiguous_lookup"
28
+ | "unknown_create_outcome"
29
+ | "provider_unavailable",
30
+ message: string,
31
+ ) {
32
+ super(message);
33
+ this.name = "UsageCatalogError";
34
+ }
35
+ }
36
+ const scopeSchema = z.strictObject({
37
+ stripeAccountId: z
38
+ .string()
39
+ .regex(/^acct_[a-zA-Z0-9]+$/)
40
+ .max(100),
41
+ livemode: z.boolean(),
42
+ });
43
+ export function catalogScope(scope: UsageCatalogScope) {
44
+ return scopeSchema.parse(scope);
45
+ }
46
+ export function meterTerms(opts: UsageMeterOptions) {
47
+ return {
48
+ scope: catalogScope(opts.scope),
49
+ plan: defineUsagePlan(opts.plan),
50
+ eventName: z
51
+ .string()
52
+ .regex(/^[\w.-]{1,100}$/)
53
+ .parse(opts.eventName),
54
+ displayName: z.string().min(1).max(100).parse(opts.displayName),
55
+ };
56
+ }
57
+ export function meterKey(plan: UsagePlan) {
58
+ return JSON.stringify([plan.key, plan.version]);
59
+ }
60
+ export async function nativeCall<T>(call: () => Promise<T>): Promise<T> {
61
+ try {
62
+ return await call();
63
+ } catch {
64
+ throw new UsageCatalogError(
65
+ "provider_unavailable",
66
+ "Native Stripe catalog is unavailable",
67
+ );
68
+ }
69
+ }
70
+ export async function verifyRealm(stripe: Stripe, scope: UsageCatalogScope) {
71
+ const parsed = catalogScope(scope);
72
+ const [account, balance] = await Promise.all([
73
+ nativeCall(() => stripe.accounts.retrieve(null)),
74
+ nativeCall(() => stripe.balance.retrieve()),
75
+ ]);
76
+ if (
77
+ account.id !== parsed.stripeAccountId ||
78
+ balance.livemode !== parsed.livemode
79
+ )
80
+ throw new UsageCatalogError(
81
+ "unsupported_scope",
82
+ "Native catalog scope must match the configured Stripe realm and mode",
83
+ );
84
+ }
85
+ export async function operationKey(terms: unknown, kind: string) {
86
+ const bytes = new TextEncoder().encode(JSON.stringify(terms));
87
+ const digest = await crypto.subtle.digest("SHA-256", bytes);
88
+ return `bs_usage_${kind}_${Array.from(new Uint8Array(digest), (n) => n.toString(16).padStart(2, "0")).join("")}`;
89
+ }
90
+ export async function prepareCatalog(
91
+ component: Component,
92
+ ctx: RunCtx,
93
+ kind: "meter" | "price",
94
+ scope: UsageCatalogScope,
95
+ key: string,
96
+ terms: unknown,
97
+ ): Promise<Doc<"usageCatalog">> {
98
+ return runMutationOrThrow(
99
+ ctx,
100
+ componentRef(component, "usageCatalog/mutations/prepare"),
101
+ {
102
+ scopeKey: JSON.stringify(catalogScope(scope)),
103
+ kind,
104
+ key,
105
+ termsJson: JSON.stringify(terms),
106
+ },
107
+ );
108
+ }
109
+ export async function completeCatalog(
110
+ component: Component,
111
+ ctx: RunCtx,
112
+ row: Doc<"usageCatalog">,
113
+ providerId: string,
114
+ observation: unknown,
115
+ ) {
116
+ return runMutationOrThrow(
117
+ ctx,
118
+ componentRef(component, "usageCatalog/mutations/complete"),
119
+ {
120
+ scopeKey: row.scopeKey,
121
+ kind: row.kind,
122
+ key: row.key,
123
+ providerId,
124
+ observationJson: JSON.stringify(observation),
125
+ },
126
+ );
127
+ }
128
+ export function permitCreate(row: Doc<"usageCatalog">) {
129
+ if (Date.now() / 1000 - row.firstAttemptAt >= 23 * 3600)
130
+ throw new UsageCatalogError(
131
+ "unknown_create_outcome",
132
+ "Native catalog create requires reconciliation after its safe retry window",
133
+ );
134
+ }
135
+
136
+ export function verifyMeter(
137
+ meter: Stripe.Billing.Meter,
138
+ opts: UsageMeterOptions,
139
+ active = true,
140
+ ) {
141
+ if (
142
+ meter.livemode !== opts.scope.livemode ||
143
+ meter.event_name !== opts.eventName ||
144
+ meter.default_aggregation.formula !== "sum" ||
145
+ meter.customer_mapping.type !== "by_id" ||
146
+ meter.customer_mapping.event_payload_key !== "stripe_customer_id" ||
147
+ meter.value_settings.event_payload_key !== "value" ||
148
+ meter.event_time_window !== null ||
149
+ !["active", "inactive"].includes(meter.status) ||
150
+ (active && meter.status !== "active")
151
+ )
152
+ throw new UsageCatalogError(
153
+ "incompatible_terms",
154
+ "Native meter has incompatible immutable terms or status",
155
+ );
156
+ }
157
+
158
+ export function meterObservation(meter: Stripe.Billing.Meter) {
159
+ return {
160
+ type: "meter",
161
+ id: meter.id,
162
+ eventName: meter.event_name,
163
+ displayName: meter.display_name,
164
+ active: meter.status === "active",
165
+ livemode: meter.livemode,
166
+ aggregation: meter.default_aggregation.formula,
167
+ customerPayloadKey: meter.customer_mapping.event_payload_key,
168
+ valuePayloadKey: meter.value_settings.event_payload_key,
169
+ };
170
+ }
@@ -1,3 +1,4 @@
1
+ import { UsageDeliveryClient } from "./deliveryClient.js";
1
2
  import type { Component, RunCtx } from "../helpers.js";
2
3
  import { runMutationOrThrow } from "../helpers.js";
3
4
  import { componentRef } from "../webhooks/helpers.js";
@@ -45,8 +46,10 @@ function decode({ event, delivery }: StoredView): UsageEventView {
45
46
  };
46
47
  }
47
48
  /** Trusted host facade. Authenticate and authorize each exact scope first. */
48
- export class UsageLedgerClient {
49
- constructor(private readonly component: Component) {}
49
+ export class UsageLedgerClient extends UsageDeliveryClient {
50
+ constructor(component: Component) {
51
+ super(component);
52
+ }
50
53
  async record(ctx: RunCtx, opts: RecordUsageOptions): Promise<UsageReceipt> {
51
54
  const event = prepareUsageRecord(opts.event);
52
55
  const input = {