@fantastic.dev/better-stripe 0.61.0 → 0.63.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 (87) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +6 -2
  3. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +32 -32
  4. package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
  5. package/dist/client/paymentSource/resolver.d.ts +1 -0
  6. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  7. package/dist/client/paymentSource/resolver.js +11 -2
  8. package/dist/client/paymentSource/resolver.js.map +1 -1
  9. package/dist/client/paymentSource/zeroTierLines.d.ts +4 -0
  10. package/dist/client/paymentSource/zeroTierLines.d.ts.map +1 -0
  11. package/dist/client/paymentSource/zeroTierLines.js +35 -0
  12. package/dist/client/paymentSource/zeroTierLines.js.map +1 -0
  13. package/dist/client/usage/configuration.d.ts +13 -0
  14. package/dist/client/usage/configuration.d.ts.map +1 -0
  15. package/dist/client/usage/configuration.js +2 -0
  16. package/dist/client/usage/configuration.js.map +1 -0
  17. package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
  18. package/dist/client/usage/deliveryProvider.js +16 -0
  19. package/dist/client/usage/deliveryProvider.js.map +1 -1
  20. package/dist/client/usage/index.d.ts +2 -0
  21. package/dist/client/usage/index.d.ts.map +1 -1
  22. package/dist/client/usage/invoiceSale.d.ts.map +1 -1
  23. package/dist/client/usage/invoiceSale.js +15 -2
  24. package/dist/client/usage/invoiceSale.js.map +1 -1
  25. package/dist/client/usage/observationClient.d.ts +2 -2
  26. package/dist/client/usage/observationClient.d.ts.map +1 -1
  27. package/dist/client/usage/views.d.ts +24 -0
  28. package/dist/client/usage/views.d.ts.map +1 -0
  29. package/dist/client/usage/views.js +2 -0
  30. package/dist/client/usage/views.js.map +1 -0
  31. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  32. package/dist/component/payoutRelease/queries.d.ts +2 -2
  33. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  34. package/dist/react/index.d.ts +5 -0
  35. package/dist/react/index.d.ts.map +1 -1
  36. package/dist/react/index.js +3 -0
  37. package/dist/react/index.js.map +1 -1
  38. package/dist/react/workflows/Usage.types.d.ts +2 -23
  39. package/dist/react/workflows/Usage.types.d.ts.map +1 -1
  40. package/dist/react/workflows/Usage.types.js.map +1 -1
  41. package/dist/react/workflows/UsageConfiguration.d.ts +4 -0
  42. package/dist/react/workflows/UsageConfiguration.d.ts.map +1 -0
  43. package/dist/react/workflows/UsageConfiguration.js +19 -0
  44. package/dist/react/workflows/UsageConfiguration.js.map +1 -0
  45. package/dist/react/workflows/UsageConfiguration.types.d.ts +57 -0
  46. package/dist/react/workflows/UsageConfiguration.types.d.ts.map +1 -0
  47. package/dist/react/workflows/UsageConfiguration.types.js +2 -0
  48. package/dist/react/workflows/UsageConfiguration.types.js.map +1 -0
  49. package/dist/react/workflows/UsagePriceRow.d.ts +26 -0
  50. package/dist/react/workflows/UsagePriceRow.d.ts.map +1 -0
  51. package/dist/react/workflows/UsagePriceRow.js +40 -0
  52. package/dist/react/workflows/UsagePriceRow.js.map +1 -0
  53. package/dist/react/workflows/usage-configuration-validation.d.ts +4 -0
  54. package/dist/react/workflows/usage-configuration-validation.d.ts.map +1 -0
  55. package/dist/react/workflows/usage-configuration-validation.js +116 -0
  56. package/dist/react/workflows/usage-configuration-validation.js.map +1 -0
  57. package/dist/react/workflows/useUsageConfiguration.d.ts +4 -0
  58. package/dist/react/workflows/useUsageConfiguration.d.ts.map +1 -0
  59. package/dist/react/workflows/useUsageConfiguration.js +84 -0
  60. package/dist/react/workflows/useUsageConfiguration.js.map +1 -0
  61. package/docs/README.md +4 -0
  62. package/docs/react-api.md +2 -0
  63. package/docs/usage-configuration.md +154 -0
  64. package/docs/usage-delivery.md +4 -0
  65. package/docs/usage-example.md +246 -0
  66. package/docs/usage-react.md +4 -0
  67. package/docs/usage-settlement.md +8 -3
  68. package/package.json +4 -2
  69. package/src/client/paymentSource/resolver.ts +14 -2
  70. package/src/client/paymentSource/zeroTierLines.ts +42 -0
  71. package/src/client/usage/configuration.ts +9 -0
  72. package/src/client/usage/deliveryProvider.test.ts +77 -37
  73. package/src/client/usage/deliveryProvider.ts +19 -0
  74. package/src/client/usage/index.ts +4 -0
  75. package/src/client/usage/invoiceSale.test.ts +68 -0
  76. package/src/client/usage/invoiceSale.ts +20 -2
  77. package/src/client/usage/views.ts +23 -0
  78. package/src/react/index.ts +16 -0
  79. package/src/react/workflows/Usage.types.ts +5 -29
  80. package/src/react/workflows/UsageConfiguration.test.tsx +393 -0
  81. package/src/react/workflows/UsageConfiguration.tsx +135 -0
  82. package/src/react/workflows/UsageConfiguration.types.ts +59 -0
  83. package/src/react/workflows/UsagePriceRow.test.tsx +140 -0
  84. package/src/react/workflows/UsagePriceRow.tsx +109 -0
  85. package/src/react/workflows/usage-configuration-validation.test.ts +107 -0
  86. package/src/react/workflows/usage-configuration-validation.ts +152 -0
  87. package/src/react/workflows/useUsageConfiguration.ts +99 -0
@@ -15,6 +15,12 @@ function setup(
15
15
  status = 200,
16
16
  errorCode = "parameter_invalid_integer",
17
17
  nativeOverrides: Record<string, unknown> = {},
18
+ clock?: {
19
+ id: string;
20
+ frozen_time: number;
21
+ status: string;
22
+ livemode: boolean;
23
+ },
18
24
  ) {
19
25
  const now = Math.floor(Date.now() / 1000);
20
26
  const record = prepareUsageRecord({
@@ -74,49 +80,54 @@ function setup(
74
80
  body = new URLSearchParams(String(init?.body ?? ""));
75
81
  requests.push({ path, body, headers: new Headers(init?.headers) });
76
82
  const value =
77
- path === "/v1/account"
78
- ? { id: "acct_platform" }
79
- : path === "/v1/balance"
80
- ? { livemode: false }
81
- : path === "/v1/billing/meters/mtr_calls"
82
- ? {
83
- id: "mtr_calls",
84
- livemode: false,
85
- status: "active",
86
- event_name: "calls",
87
- default_aggregation: { formula: "sum" },
88
- customer_mapping: {
89
- type: "by_id",
90
- event_payload_key: "stripe_customer_id",
91
- },
92
- value_settings: { event_payload_key: "value" },
93
- event_time_window: null,
94
- }
95
- : path === "/v1/subscriptions/sub_calls"
83
+ path === "/v1/test_helpers/test_clocks/clock_fixture"
84
+ ? clock
85
+ : path === "/v1/account"
86
+ ? { id: "acct_platform" }
87
+ : path === "/v1/balance"
88
+ ? { livemode: false }
89
+ : path === "/v1/billing/meters/mtr_calls"
96
90
  ? {
97
- id: "sub_calls",
91
+ id: "mtr_calls",
98
92
  livemode: false,
99
- customer: "cus_buyer",
100
- customer_account: "acct_buyer",
101
- ...nativeOverrides,
93
+ status: "active",
94
+ event_name: "calls",
95
+ default_aggregation: { formula: "sum" },
96
+ customer_mapping: {
97
+ type: "by_id",
98
+ event_payload_key: "stripe_customer_id",
99
+ },
100
+ value_settings: { event_payload_key: "value" },
101
+ event_time_window: null,
102
102
  }
103
- : status === 200
103
+ : path === "/v1/subscriptions/sub_calls"
104
104
  ? {
105
- object: "billing.meter_event",
106
- identifier: body.get("identifier"),
107
- event_name: "calls",
105
+ id: "sub_calls",
108
106
  livemode: false,
109
- timestamp: now,
110
- created: now,
111
- payload: { stripe_customer_id: "cus_buyer", value: "120" },
107
+ customer: "cus_buyer",
108
+ customer_account: "acct_buyer",
109
+ ...nativeOverrides,
112
110
  }
113
- : {
114
- error: {
115
- type: status === 429 ? "rate_limit_error" : "api_error",
116
- message: "private provider detail",
117
- code: errorCode,
118
- },
119
- };
111
+ : status === 200
112
+ ? {
113
+ object: "billing.meter_event",
114
+ identifier: body.get("identifier"),
115
+ event_name: "calls",
116
+ livemode: false,
117
+ timestamp: now,
118
+ created: now,
119
+ payload: {
120
+ stripe_customer_id: "cus_buyer",
121
+ value: "120",
122
+ },
123
+ }
124
+ : {
125
+ error: {
126
+ type: status === 429 ? "rate_limit_error" : "api_error",
127
+ message: "private provider detail",
128
+ code: errorCode,
129
+ },
130
+ };
120
131
  if (path === "/v1/billing/meter_events" && status === 0)
121
132
  throw new Error("Lost accepted response");
122
133
  return new Response(JSON.stringify(value), {
@@ -274,3 +285,32 @@ it("withholds a managed send when native manual invoicing drifts to automatic ch
274
285
  false,
275
286
  );
276
287
  });
288
+
289
+ it.each([
290
+ [-301, "ready", false, "rejected"],
291
+ [-300, "ready", false, "accepted"],
292
+ [-60, "advancing", false, "unavailable"],
293
+ [-60, "ready", true, "unavailable"],
294
+ [35 * 86400 + 1, "ready", false, "rejected"],
295
+ ] as const)(
296
+ "checks native test-clock eligibility offset=%s state=%s mode=%s before sending",
297
+ async (offset, status, livemode, expected) => {
298
+ const now = Math.floor(Date.now() / 1000);
299
+ const f = setup(
300
+ 200,
301
+ "parameter_invalid_integer",
302
+ { test_clock: "clock_fixture" },
303
+ { id: "clock_fixture", frozen_time: now + offset, status, livemode },
304
+ );
305
+ const result = await deliverUsageProvider(
306
+ componentsGeneric().betterStripe as unknown as Component,
307
+ f.ctx,
308
+ f.request,
309
+ { stripeSecretKey: "sk_test_usage", httpClient: f.httpClient },
310
+ );
311
+ expect(result.outcome.status).toBe(expected);
312
+ expect(
313
+ f.requests.filter((row) => row.path === "/v1/billing/meter_events"),
314
+ ).toHaveLength(expected === "accepted" ? 1 : 0);
315
+ },
316
+ );
@@ -105,6 +105,25 @@ export async function deliverUsageProvider(
105
105
  eventName: record.binding.eventName,
106
106
  displayName: meter.display_name,
107
107
  });
108
+ // Test-clock customers use their frozen time for native meter validation.
109
+ const clockId =
110
+ typeof subscription.test_clock === "string"
111
+ ? subscription.test_clock
112
+ : subscription.test_clock?.id;
113
+ if (!args.scope.livemode && clockId) {
114
+ const clock = await stripe.testHelpers.testClocks.retrieve(clockId);
115
+ if (
116
+ clock.id !== clockId ||
117
+ clock.livemode !== false ||
118
+ clock.status !== "ready" ||
119
+ !Number.isSafeInteger(clock.frozen_time) ||
120
+ clock.frozen_time < 0
121
+ )
122
+ return done({ status: "unavailable" });
123
+ const offset = BigInt(record.occurredAt) - BigInt(clock.frozen_time);
124
+ if (offset > 300n || offset < -35n * 86400n)
125
+ return done({ status: "rejected" });
126
+ }
108
127
  await verifyCreditDelivery(stripe, component, ctx, saved.event, record);
109
128
  const current = await read();
110
129
  if (
@@ -111,3 +111,7 @@ export type { UsageCreditSettlementOptions } from "./creditSettlement.js";
111
111
 
112
112
  export type { UsageEventView } from "./client.js";
113
113
  export type { UsageCreditReconciliation } from "./creditObservation.js";
114
+
115
+ export type { UsageConfigurationValue } from "./configuration.js";
116
+
117
+ export type { UsageViewScope, UsageBillingSnapshot } from "./views.js";
@@ -182,3 +182,71 @@ it("exposes the scoped reader through stripe.usage with runtime-only credentials
182
182
  ),
183
183
  ).toBe(true);
184
184
  });
185
+
186
+ it("verifies native graduated invoices with a zero included tier and paid overage line", async () => {
187
+ const f = fixture();
188
+ const plan = {
189
+ ...f.input.binding.plan,
190
+ model: "included_overage" as const,
191
+ includedQuantity: "10",
192
+ reset: "billing_period" as const,
193
+ };
194
+ Object.assign(f.price, {
195
+ billing_scheme: "tiered",
196
+ tiers_mode: "graduated",
197
+ unit_amount_decimal: null,
198
+ tiers: [
199
+ { up_to: 10, unit_amount_decimal: "0", flat_amount: null },
200
+ { up_to: null, unit_amount_decimal: "2", flat_amount: null },
201
+ ],
202
+ });
203
+ const included = {
204
+ ...structuredClone(f.line),
205
+ period: { ...f.input.period },
206
+ };
207
+ Object.assign(included, {
208
+ id: "il_included",
209
+ amount: 0,
210
+ quantity_decimal: "10",
211
+ });
212
+ Object.assign(f.invoice, {
213
+ lines: { data: [included, f.line], has_more: false },
214
+ });
215
+ f.extra.set("/v1/invoices/in_source/lines", {
216
+ object: "list",
217
+ data: [included, f.line],
218
+ has_more: false,
219
+ });
220
+ const input = { ...f.input, binding: { ...f.input.binding, plan } };
221
+ expect(await getUsageInvoiceSale(f.sdk, input)).toMatchObject({
222
+ status: "ready",
223
+ value: { model: "included_overage", gross: 1000, processingFee: 50 },
224
+ });
225
+ for (const mutation of [
226
+ "foreign_item",
227
+ "foreign_price",
228
+ "period",
229
+ "proration",
230
+ "extra_paid",
231
+ "duplicate_id",
232
+ ]) {
233
+ const altered = structuredClone(included);
234
+ if (mutation === "foreign_item")
235
+ altered.parent.subscription_item_details.subscription_item = "si_foreign";
236
+ if (mutation === "foreign_price")
237
+ altered.pricing.price_details.price = "price_foreign";
238
+ if (mutation === "period") altered.period.start++;
239
+ if (mutation === "proration")
240
+ altered.parent.subscription_item_details.proration = true;
241
+ if (mutation === "extra_paid") altered.amount = 1;
242
+ if (mutation === "duplicate_id") altered.id = f.line.id;
243
+ f.extra.set("/v1/invoices/in_source/lines", {
244
+ object: "list",
245
+ data: [altered, f.line],
246
+ has_more: false,
247
+ });
248
+ expect((await getUsageInvoiceSale(f.sdk, input)).status, mutation).not.toBe(
249
+ "ready",
250
+ );
251
+ }
252
+ });
@@ -60,11 +60,26 @@ export async function getUsageInvoiceSale(
60
60
  reason: "payment_not_payable",
61
61
  retryable: false,
62
62
  };
63
- const line = value.lines[0];
63
+ const paidLines = value.lines.filter((row) => BigInt(row.amount) > 0n);
64
+ const line = paidLines[0];
65
+ const zeroLines = value.lines.filter((row) => row.amount === "0");
64
66
  if (
65
67
  !value.linesComplete ||
66
68
  value.meterAmount.status !== "available" ||
67
- value.lines.length !== 1 ||
69
+ paidLines.length !== 1 ||
70
+ (value.lines.length !== 1 &&
71
+ !(
72
+ opts.binding.plan.model === "included_overage" &&
73
+ value.lines.length === 2 &&
74
+ zeroLines.length === 1
75
+ )) ||
76
+ value.lines.some(
77
+ (row) =>
78
+ row.proration ||
79
+ row.creditAppliedAmount !== "0" ||
80
+ row.nativePeriod.start !== opts.subscription.period.start ||
81
+ row.nativePeriod.end !== opts.subscription.period.end,
82
+ ) ||
68
83
  !line ||
69
84
  line.proration ||
70
85
  line.creditAppliedAmount !== "0" ||
@@ -115,6 +130,9 @@ export async function getUsageInvoiceSale(
115
130
  customerId: opts.binding.stripeCustomerId,
116
131
  invoiceLine: {
117
132
  id: line.lineId,
133
+ ...(zeroLines.length
134
+ ? { zeroAmountLineIds: zeroLines.map((row) => row.lineId) }
135
+ : {}),
118
136
  subscriptionItemId: opts.subscription.subscriptionItemId,
119
137
  period: opts.subscription.period,
120
138
  },
@@ -0,0 +1,23 @@
1
+ import type { UsageAvailability, UsagePeriod } from "./boundaries.js";
2
+ import type { UsageLocalSummary } from "./summary.js";
3
+ import type { UsageAggregateObservation } from "./observationTypes.js";
4
+ import type { UsageAllowanceStatus } from "./allowanceTerms.js";
5
+ import type { UsageCreditBalance, UsageCreditPurchase } from "./creditTerms.js";
6
+ import type { UsageCreditReconciliation } from "./creditObservation.js";
7
+ /** Cache identity only. The authenticated host must resolve and authorize original native bindings. */
8
+ export type UsageViewScope = {
9
+ identityKey: string;
10
+ accountKey: string;
11
+ /** Include original plan/price version in this opaque host meter key. */
12
+ meterKey: string;
13
+ period: UsagePeriod;
14
+ currency: string;
15
+ };
16
+ export type UsageBillingSnapshot = {
17
+ summary: UsageAvailability<UsageLocalSummary>;
18
+ provider?: UsageAggregateObservation;
19
+ allowance?: UsageAvailability<UsageAllowanceStatus | null>;
20
+ credits?: UsageAvailability<UsageCreditBalance>;
21
+ purchase?: UsageCreditPurchase | null;
22
+ creditApplication?: UsageAvailability<UsageCreditReconciliation>;
23
+ };
@@ -326,3 +326,19 @@ export type {
326
326
  UsageHistoryProps,
327
327
  UsageHistoryPage,
328
328
  } from "./workflows/UsageHistory.js";
329
+
330
+ export { UsageConfiguration } from "./workflows/UsageConfiguration.js";
331
+ export { useUsageConfiguration } from "./workflows/useUsageConfiguration.js";
332
+ export type {
333
+ UsageConfigurationProps,
334
+ UsageConfigurationScope,
335
+ UsageConfigurationValue,
336
+ UsageConfigurationFields,
337
+ UsageConfigurationState,
338
+ UsageMeterChoice,
339
+ } from "./workflows/UsageConfiguration.types.js";
340
+ export { UsagePriceRow } from "./workflows/UsagePriceRow.js";
341
+ export type {
342
+ UsagePriceRowProps,
343
+ UsageCatalogPrice,
344
+ } from "./workflows/UsagePriceRow.js";
@@ -1,32 +1,8 @@
1
- import type {
2
- UsageAvailability,
3
- UsagePeriod,
4
- } from "../../client/usage/boundaries.js";
5
- import type { UsageLocalSummary } from "../../client/usage/summary.js";
6
- import type { UsageAggregateObservation } from "../../client/usage/observationTypes.js";
7
- import type { UsageAllowanceStatus } from "../../client/usage/allowanceTerms.js";
8
- import type {
9
- UsageCreditBalance,
10
- UsageCreditPurchase,
11
- } from "../../client/usage/creditTerms.js";
12
- import type { UsageCreditReconciliation } from "../../client/usage/creditObservation.js";
13
- /** Cache identity only. The authenticated host must resolve and authorize original native bindings. */
14
- export type UsageViewScope = {
15
- identityKey: string;
16
- accountKey: string;
17
- /** Include original plan/price version in this opaque host meter key. */
18
- meterKey: string;
19
- period: UsagePeriod;
20
- currency: string;
21
- };
22
- export type UsageBillingSnapshot = {
23
- summary: UsageAvailability<UsageLocalSummary>;
24
- provider?: UsageAggregateObservation;
25
- allowance?: UsageAvailability<UsageAllowanceStatus | null>;
26
- credits?: UsageAvailability<UsageCreditBalance>;
27
- purchase?: UsageCreditPurchase | null;
28
- creditApplication?: UsageAvailability<UsageCreditReconciliation>;
29
- };
1
+ import type { UsageViewScope } from "../../client/usage/views.js";
2
+ export type {
3
+ UsageViewScope,
4
+ UsageBillingSnapshot,
5
+ } from "../../client/usage/views.js";
30
6
  export function usageViewKey(scope: UsageViewScope) {
31
7
  return JSON.stringify([
32
8
  scope.identityKey,