@fantastic.dev/better-stripe 0.61.0 → 0.62.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 (39) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +3 -1
  3. package/dist/react/index.d.ts +5 -0
  4. package/dist/react/index.d.ts.map +1 -1
  5. package/dist/react/index.js +3 -0
  6. package/dist/react/index.js.map +1 -1
  7. package/dist/react/workflows/UsageConfiguration.d.ts +4 -0
  8. package/dist/react/workflows/UsageConfiguration.d.ts.map +1 -0
  9. package/dist/react/workflows/UsageConfiguration.js +19 -0
  10. package/dist/react/workflows/UsageConfiguration.js.map +1 -0
  11. package/dist/react/workflows/UsageConfiguration.types.d.ts +65 -0
  12. package/dist/react/workflows/UsageConfiguration.types.d.ts.map +1 -0
  13. package/dist/react/workflows/UsageConfiguration.types.js +2 -0
  14. package/dist/react/workflows/UsageConfiguration.types.js.map +1 -0
  15. package/dist/react/workflows/UsagePriceRow.d.ts +26 -0
  16. package/dist/react/workflows/UsagePriceRow.d.ts.map +1 -0
  17. package/dist/react/workflows/UsagePriceRow.js +40 -0
  18. package/dist/react/workflows/UsagePriceRow.js.map +1 -0
  19. package/dist/react/workflows/usage-configuration-validation.d.ts +4 -0
  20. package/dist/react/workflows/usage-configuration-validation.d.ts.map +1 -0
  21. package/dist/react/workflows/usage-configuration-validation.js +116 -0
  22. package/dist/react/workflows/usage-configuration-validation.js.map +1 -0
  23. package/dist/react/workflows/useUsageConfiguration.d.ts +4 -0
  24. package/dist/react/workflows/useUsageConfiguration.d.ts.map +1 -0
  25. package/dist/react/workflows/useUsageConfiguration.js +84 -0
  26. package/dist/react/workflows/useUsageConfiguration.js.map +1 -0
  27. package/docs/README.md +2 -0
  28. package/docs/react-api.md +2 -0
  29. package/docs/usage-configuration.md +150 -0
  30. package/package.json +3 -2
  31. package/src/react/index.ts +16 -0
  32. package/src/react/workflows/UsageConfiguration.test.tsx +393 -0
  33. package/src/react/workflows/UsageConfiguration.tsx +135 -0
  34. package/src/react/workflows/UsageConfiguration.types.ts +67 -0
  35. package/src/react/workflows/UsagePriceRow.test.tsx +140 -0
  36. package/src/react/workflows/UsagePriceRow.tsx +109 -0
  37. package/src/react/workflows/usage-configuration-validation.test.ts +107 -0
  38. package/src/react/workflows/usage-configuration-validation.ts +152 -0
  39. package/src/react/workflows/useUsageConfiguration.ts +99 -0
@@ -0,0 +1,150 @@
1
+ # Configure native usage billing in React
2
+
3
+ `UsageConfiguration`, `useUsageConfiguration` and `UsagePriceRow` are reusable,
4
+ unstyled package UI. Both component-backed Convex actions and authenticated HTTP
5
+ adapters use the same contract. No Metronome account or credentials are required.
6
+ Read [native catalog provisioning](usage-catalog.md), [usage views](usage-react.md)
7
+ and [authorization boundaries](usage-security.md) before wiring the adapter.
8
+
9
+ ```tsx
10
+ import {
11
+ UsageConfiguration,
12
+ type UsageConfigurationValue,
13
+ } from "@fantastic.dev/better-stripe/react";
14
+
15
+ const initial: UsageConfigurationValue = {
16
+ plan: {
17
+ key: "api-calls",
18
+ version: "v1",
19
+ model: "pay_as_you_go",
20
+ unit: { name: "call", precision: 0 },
21
+ rate: { currency: "usd", unitAmountDecimal: "2" },
22
+ },
23
+ eventName: "api_calls_v1",
24
+ displayName: "API calls",
25
+ };
26
+
27
+ <UsageConfiguration
28
+ scope={authorizedConfigurationScope}
29
+ initial={initial}
30
+ meters={authorizedManagedMeters}
31
+ onSave={saveAuthorizedConfiguration}
32
+ />;
33
+ ```
34
+
35
+ `scope` contains opaque `identityKey`, `accountKey` and `productKey`, a display
36
+ `ownershipLabel`, `role: "admin" | "seller"`, `canConfigure` and
37
+ `capability: "issuer_native" | "unsupported"`. Derive these on the host from the
38
+ signed-in actor and verified issuer account. They control browser state and
39
+ presentation. They do not authorize a server operation. Include actor changes in
40
+ `identityKey`, even if two actors share an account.
41
+
42
+ The form has no owner selector, provider secret input or browser Stripe callback.
43
+ The native APIs currently operate in the configured key's issuer realm, without
44
+ connected-account headers. Seller adapters must authorize the seller's product
45
+ within that supported realm; a role label does not enable arbitrary Connect
46
+ billing. A host must return unsupported for an ineligible provider/account setup.
47
+ These are BetterStripe components, not Stripe embedded catalog components.
48
+
49
+ ## Supported settings
50
+
51
+ The billing model selects the relevant fields:
52
+
53
+ - **Pay as you go:** exact price per whole unit, currency, billable unit and
54
+ quantity precision from 0 through 6.
55
+ - **Included monthly units plus overages:** the same rate as an overage rate,
56
+ positive included units, and a reset at the original monthly billing period.
57
+ Native pricing uses a graduated free first tier followed by an infinite paid
58
+ tier. This does not add a monthly subscription fee or authorize work.
59
+ - **Prepaid paid credits:** a paid credit package quantity, manual top-up and
60
+ reject-on-insufficient-credit policy. The package must have positive whole minor currency backing within the native
61
+ payment bound and supported charge increments. Each later reservation must
62
+ also have exact whole-minor backing. Fractional rates are supported when work
63
+ uses suitable batches; fractional-minor consumption is rejected without rounding. Original terms
64
+ remain attached to credits. Automatic top-up and a monetary wallet are not
65
+ supported. Credit purchases fund only the issuer's own services.
66
+
67
+ Rates shown in the form are **major currency units per whole billable unit**.
68
+ The submitted `plan.rate.unitAmountDecimal` is an exact string in **minor currency
69
+ units per whole billable unit**. For example, `0.00125 USD` becomes `"0.125"` minor
70
+ units. Precision 2 gives Stripe a scaled-unit rate of `"0.00125"` minor units.
71
+ The form uses the existing plan, quantity, native rate and credit cost validators.
72
+ It rejects excessive precision and bounds rather than rounding. Provider account,
73
+ minimum payment, currency and payment-method eligibility still require server
74
+ validation and native observations.
75
+
76
+ Monthly interval and sum aggregation are the current supported configuration.
77
+ Other intervals, count/last aggregation, general tiers and transformed quantities
78
+ need an explicit supported server adapter. The form does not imply support by
79
+ accepting those settings.
80
+
81
+ ## Immutable meter selection and versions
82
+
83
+ `meters` is an authorized subset/page of managed meters. Each entry contains `id`,
84
+ `active` and its original `configuration`. Do not pass arbitrary native meters
85
+ without first verifying/adopting them through the package. Do not describe a
86
+ partial page as complete inventory. Hosts can page or search their managed catalog
87
+ and replace the supplied subset.
88
+
89
+ Selecting an active meter loads its immutable original terms and disables edits.
90
+ Inactive meters cannot be selected. Choose **Create new meter version** to edit
91
+ new terms. The server must require a new plan version, event name and price lookup
92
+ key for changed terms. Saving does not migrate, cancel or reprice existing
93
+ subscriptions. Those keep their original price until an explicit authorized host
94
+ operation changes them.
95
+
96
+ `onSave` receives `{ plan, eventName, displayName, meterId?, creditPackage? }`.
97
+ For prepaid, `creditPackage` is `{ quantity, topUp: "manual" }`. It is configuration
98
+ only. Saving does not create a payment, grant credits or authorize consumption.
99
+ The host must:
100
+
101
+ 1. Authenticate the actor and authorize admin/seller access to the product.
102
+ 2. Resolve the Stripe realm, mode, product and permitted immutable plan identity
103
+ on the server. Ignore client attempts to choose financial ownership.
104
+ 3. Revalidate the plan and selected original meter. Call `ensureUsageMeter` or
105
+ verify/adopt the selected meter, then `ensureUsagePrice` with a stable lookup
106
+ key. Persist the validated package policy in the host's authorized product
107
+ configuration, not a second usage ledger.
108
+ 4. For later purchases, use the package's [credit workflow](usage-credits.md),
109
+ deriving `ownership: "issuer"` and `rollover: "retain_original_terms"` on the
110
+ server. Verify payment before granting spending capacity.
111
+ 5. Return only sanitized results. An uncertain create outcome must be reconciled
112
+ using the original keys. Do not invent new identities to retry.
113
+
114
+ The package catalog persists intents and verifies immutable provider terms. A
115
+ browser duplicate-submit lock is only a UI convenience. Host authorization and
116
+ package idempotency remain mandatory after reloads or across tabs.
117
+
118
+ ## State, styling and recovery
119
+
120
+ Inputs and save controls disable during submission. Validation errors identify
121
+ unsupported values. Provider errors use a sanitized retry/reconciliation message;
122
+ raw provider messages are not shown by the default UI. A successful save shows a
123
+ version confirmation. Changing scope, authoritative initial terms or meter choices
124
+ resets edits and discards delayed results. A read-only or unsupported host cannot
125
+ submit through the hook either.
126
+
127
+ Use `className`, `[data-better-stripe="usage-configuration"]`, ordinary semantic
128
+ HTML and associated labels to style the default form. A `children(state)` render
129
+ prop, or `useUsageConfiguration(props)`, exposes `fields`, `setField`, `meterId`,
130
+ `selectMeter`, `immutable`, `disabled`, `isPending`, `save`, `error` and `message`.
131
+ Keep immutable/disabled controls and error/status announcements accessible when
132
+ customizing. The hook retains the same validation and submission lifecycle.
133
+
134
+ `UsagePriceRow` accepts a discriminated `value`:
135
+
136
+ - `{ kind: "fixed", price }` reuses `PriceCard` formatting. Pass observed usage,
137
+ billing-scheme and transformation metadata when available. Metered, tiered,
138
+ transformed, missing amounts or unsupported charge units cannot masquerade as
139
+ fixed zero prices.
140
+ - `{ kind: "metered", price }` uses the managed `UsagePriceBinding` returned by
141
+ `getUsagePrice`. It displays the original plan version, exact whole-unit rate,
142
+ model, monthly interval, aggregation, precision and active state. Included
143
+ tiers and prepaid credit backing have separate explanations.
144
+ - `{ kind: "unsupported", reason: "tiered" | "transformed" | "other" }` labels
145
+ other observed terms explicitly. It never infers a free price from a null
146
+ amount.
147
+
148
+ Use `productName`, `className` or `children(value)` for the catalog row. It is
149
+ read-only. The form, catalog row and usage views share package contracts; the
150
+ example should compose them rather than implementing another pricing engine.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.61.0",
3
+ "version": "0.62.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -112,7 +112,8 @@
112
112
  "docs/usage-settlement.md",
113
113
  "docs/usage-security.md",
114
114
  "docs/usage-react.md",
115
- "docs/evidence/native-metering"
115
+ "docs/evidence/native-metering",
116
+ "docs/usage-configuration.md"
116
117
  ],
117
118
  "scripts": {
118
119
  "build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
@@ -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";
@@ -0,0 +1,393 @@
1
+ // @vitest-environment jsdom
2
+ import {
3
+ act,
4
+ cleanup,
5
+ fireEvent,
6
+ render,
7
+ screen,
8
+ waitFor,
9
+ } from "@testing-library/react";
10
+ import { afterEach, expect, it, vi } from "vitest";
11
+ import * as ui from "../index.js";
12
+ afterEach(cleanup);
13
+ const scope = {
14
+ identityKey: "admin-a",
15
+ accountKey: "issuer-a",
16
+ productKey: "calls",
17
+ role: "admin" as const,
18
+ ownershipLabel: "Issuer A",
19
+ canConfigure: true,
20
+ capability: "issuer_native" as const,
21
+ };
22
+ const initial = {
23
+ plan: {
24
+ key: "calls",
25
+ version: "v2",
26
+ model: "pay_as_you_go" as const,
27
+ unit: { name: "call", precision: 0 },
28
+ rate: { currency: "usd", unitAmountDecimal: "2" },
29
+ },
30
+ eventName: "calls_v2",
31
+ displayName: "API calls",
32
+ };
33
+ function field(name: string, value: string) {
34
+ fireEvent.change(screen.getByLabelText(name), { target: { value } });
35
+ }
36
+ function save() {
37
+ fireEvent.submit(screen.getByRole("form", { name: "Usage configuration" }));
38
+ }
39
+ it("saves exact supported native terms, creates a version and never submits host ownership", async () => {
40
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
41
+ const onSave = vi.fn().mockResolvedValue(undefined);
42
+ render(
43
+ <ui.UsageConfiguration
44
+ scope={scope}
45
+ initial={initial}
46
+ meters={[]}
47
+ onSave={onSave}
48
+ />,
49
+ );
50
+ expect(
51
+ screen.getByText(/Existing subscriptions keep their original prices/),
52
+ ).toBeTruthy();
53
+ field("Price per whole unit (USD)", "0.00125");
54
+ field("Quantity precision", "2");
55
+ save();
56
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
57
+ expect(onSave.mock.calls[0][0]).toEqual({
58
+ ...initial,
59
+ plan: {
60
+ ...initial.plan,
61
+ unit: { name: "call", precision: 2 },
62
+ rate: { currency: "usd", unitAmountDecimal: "0.125" },
63
+ },
64
+ });
65
+ expect(screen.getByRole("status").textContent).toMatch(/version saved/i);
66
+ });
67
+ it("validates included units against precision and native tier bounds, and resets per billing period", async () => {
68
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
69
+ const onSave = vi.fn().mockResolvedValue(undefined);
70
+ render(
71
+ <ui.UsageConfiguration
72
+ scope={scope}
73
+ initial={initial}
74
+ meters={[]}
75
+ onSave={onSave}
76
+ />,
77
+ );
78
+ field("Billing model", "included_overage");
79
+ field("Included units per billing period", "0");
80
+ save();
81
+ await waitFor(() =>
82
+ expect(screen.getByRole("alert").textContent).toMatch(/included/i),
83
+ );
84
+ expect(onSave).not.toHaveBeenCalled();
85
+ field("Included units per billing period", "9007199254740992");
86
+ save();
87
+ await waitFor(() => expect(screen.getByRole("alert")).toBeTruthy());
88
+ expect(onSave).not.toHaveBeenCalled();
89
+ field("Included units per billing period", "100");
90
+ save();
91
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
92
+ expect(onSave.mock.calls[0][0].plan).toMatchObject({
93
+ model: "included_overage",
94
+ includedQuantity: "100",
95
+ reset: "billing_period",
96
+ });
97
+ expect(screen.getByText(/Graduated pricing:/)).toBeTruthy();
98
+ });
99
+ it("configures paid credit packages, rejecting fractional backing and retaining issuer terms with manual top-up", async () => {
100
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
101
+ const onSave = vi.fn().mockResolvedValue(undefined);
102
+ render(
103
+ <ui.UsageConfiguration
104
+ scope={scope}
105
+ initial={initial}
106
+ meters={[]}
107
+ onSave={onSave}
108
+ />,
109
+ );
110
+ field("Billing model", "prepaid");
111
+ field("Credit package quantity", "3");
112
+ field("Price per whole unit (USD)", "0.001");
113
+ save();
114
+ await waitFor(() =>
115
+ expect(screen.getByRole("alert").textContent).toMatch(/whole minor/i),
116
+ );
117
+ expect(onSave).not.toHaveBeenCalled();
118
+ field("Price per whole unit (USD)", "0.02");
119
+ save();
120
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
121
+ expect(onSave.mock.calls[0][0]).toMatchObject({
122
+ plan: { model: "prepaid", insufficientBalance: "reject" },
123
+ creditPackage: { quantity: "3", topUp: "manual" },
124
+ });
125
+ expect(
126
+ screen.getByText(/Reject work when credits are insufficient/),
127
+ ).toBeTruthy();
128
+ expect(screen.queryByLabelText(/owner/i)).toBeNull();
129
+ });
130
+ it("selects immutable authorized meters, disables incompatible meters and preserves their original version", async () => {
131
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
132
+ const onSave = vi.fn().mockResolvedValue(undefined);
133
+ render(
134
+ <ui.UsageConfiguration
135
+ scope={{ ...scope, role: "seller" }}
136
+ initial={initial}
137
+ meters={[
138
+ {
139
+ id: "mtr_old",
140
+ active: true,
141
+ configuration: {
142
+ ...initial,
143
+ plan: { ...initial.plan, version: "v1" },
144
+ eventName: "calls_v1",
145
+ },
146
+ },
147
+ { id: "mtr_off", active: false, configuration: initial },
148
+ ]}
149
+ onSave={onSave}
150
+ />,
151
+ );
152
+ field("Meter", "mtr_old");
153
+ expect(
154
+ (screen.getByLabelText("Plan version") as HTMLInputElement).disabled,
155
+ ).toBe(true);
156
+ expect(
157
+ (screen.getByLabelText("Price per whole unit (USD)") as HTMLInputElement)
158
+ .value,
159
+ ).toBe("0.02");
160
+ save();
161
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
162
+ expect(onSave.mock.calls[0][0]).toMatchObject({
163
+ meterId: "mtr_old",
164
+ plan: { version: "v1" },
165
+ eventName: "calls_v1",
166
+ });
167
+ expect(
168
+ screen.getByRole("option", { name: /inactive/i }).getAttribute("disabled"),
169
+ ).not.toBeNull();
170
+ });
171
+ it("locks duplicate submissions, sanitizes provider errors and allows a same-terms retry", async () => {
172
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
173
+ let reject!: (error: Error) => void;
174
+ const onSave = vi
175
+ .fn()
176
+ .mockImplementationOnce(
177
+ () =>
178
+ new Promise((_, r) => {
179
+ reject = r;
180
+ }),
181
+ )
182
+ .mockResolvedValue(undefined);
183
+ render(
184
+ <ui.UsageConfiguration
185
+ scope={scope}
186
+ initial={initial}
187
+ meters={[]}
188
+ onSave={onSave}
189
+ />,
190
+ );
191
+ save();
192
+ save();
193
+ expect(onSave).toHaveBeenCalledTimes(1);
194
+ expect(
195
+ (screen.getByLabelText("Plan version") as HTMLInputElement).matches(
196
+ ":disabled",
197
+ ),
198
+ ).toBe(true);
199
+ await act(async () => reject(new Error("secret provider tenant-a")));
200
+ expect(screen.getByRole("alert").textContent).toBe(
201
+ "Configuration could not be saved. Retry the same terms or ask an administrator to reconcile the operation.",
202
+ );
203
+ save();
204
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(2));
205
+ });
206
+ it.each([
207
+ "identityKey",
208
+ "accountKey",
209
+ "productKey",
210
+ "role",
211
+ "ownershipLabel",
212
+ "canConfigure",
213
+ "capability",
214
+ ])("discards pending results and edits on %s scope change", async (key) => {
215
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
216
+ let resolve!: () => void;
217
+ const onSave = vi.fn().mockImplementation(
218
+ () =>
219
+ new Promise<void>((r) => {
220
+ resolve = r;
221
+ }),
222
+ );
223
+ const { rerender } = render(
224
+ <ui.UsageConfiguration
225
+ scope={scope}
226
+ initial={initial}
227
+ meters={[]}
228
+ onSave={onSave}
229
+ />,
230
+ );
231
+ field("Plan version", "private-edit");
232
+ save();
233
+ const next = {
234
+ ...scope,
235
+ [key]:
236
+ key === "canConfigure"
237
+ ? false
238
+ : key === "role"
239
+ ? "seller"
240
+ : key === "capability"
241
+ ? "unsupported"
242
+ : "scope-b",
243
+ } as typeof scope;
244
+ rerender(
245
+ <ui.UsageConfiguration
246
+ scope={next}
247
+ initial={initial}
248
+ meters={[]}
249
+ onSave={onSave}
250
+ />,
251
+ );
252
+ await act(async () => resolve());
253
+ expect(screen.queryByText(/version saved/i)).toBeNull();
254
+ const version = screen.queryByLabelText(
255
+ "Plan version",
256
+ ) as HTMLInputElement | null;
257
+ if (version) expect(version.value).toBe("v2");
258
+ });
259
+ it("leaves unavailable capability and read-only hosts unable to submit", () => {
260
+ expect(ui.UsageConfiguration).toBeTypeOf("function");
261
+ const onSave = vi.fn();
262
+ const { rerender } = render(
263
+ <ui.UsageConfiguration
264
+ scope={{ ...scope, capability: "unsupported" }}
265
+ initial={initial}
266
+ meters={[]}
267
+ onSave={onSave}
268
+ />,
269
+ );
270
+ expect(screen.getByText(/configuration unavailable/i)).toBeTruthy();
271
+ expect(screen.queryByRole("button", { name: /save/i })).toBeNull();
272
+ rerender(
273
+ <ui.UsageConfiguration
274
+ scope={{ ...scope, canConfigure: false }}
275
+ initial={initial}
276
+ meters={[]}
277
+ onSave={onSave}
278
+ />,
279
+ );
280
+ save();
281
+ expect(onSave).not.toHaveBeenCalled();
282
+ });
283
+ it("shares configuration payloads between component and serialized HTTP host adapters", async () => {
284
+ const componentSave = vi.fn().mockResolvedValue(undefined);
285
+ const apiSave = vi
286
+ .fn()
287
+ .mockImplementation(async (value) => JSON.parse(JSON.stringify(value)));
288
+ const { unmount } = render(
289
+ <ui.UsageConfiguration
290
+ scope={scope}
291
+ initial={initial}
292
+ meters={[]}
293
+ onSave={componentSave}
294
+ />,
295
+ );
296
+ field("Billing model", "included_overage");
297
+ field("Included units per billing period", "42");
298
+ save();
299
+ await waitFor(() => expect(componentSave).toHaveBeenCalledTimes(1));
300
+ unmount();
301
+ render(
302
+ <ui.UsageConfiguration
303
+ scope={scope}
304
+ initial={JSON.parse(JSON.stringify(initial))}
305
+ meters={[]}
306
+ onSave={apiSave}
307
+ />,
308
+ );
309
+ field("Billing model", "included_overage");
310
+ field("Included units per billing period", "42");
311
+ save();
312
+ await waitFor(() => expect(apiSave).toHaveBeenCalledTimes(1));
313
+ expect(apiSave.mock.calls[0][0]).toEqual(componentSave.mock.calls[0][0]);
314
+ });
315
+ it("exposes styling and render props without adding a second configuration engine", async () => {
316
+ const onSave = vi.fn().mockResolvedValue(undefined);
317
+ render(
318
+ <ui.UsageConfiguration
319
+ scope={scope}
320
+ initial={initial}
321
+ meters={[]}
322
+ onSave={onSave}
323
+ >
324
+ {(state) => (
325
+ <button
326
+ onClick={() => {
327
+ state.setField("version", "v3");
328
+ }}
329
+ >
330
+ Edit version {state.fields.version}
331
+ <span
332
+ onClick={(event) => {
333
+ event.stopPropagation();
334
+ void state.save();
335
+ }}
336
+ >
337
+ Submit
338
+ </span>
339
+ </button>
340
+ )}
341
+ </ui.UsageConfiguration>,
342
+ );
343
+ fireEvent.click(screen.getByRole("button"));
344
+ expect(screen.getByRole("button").textContent).toContain("v3");
345
+ fireEvent.click(screen.getByText("Submit"));
346
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
347
+ expect(onSave.mock.calls[0][0].plan.version).toBe("v3");
348
+ });
349
+ it.each(["pay_as_you_go", "included_overage", "prepaid"] as const)(
350
+ "preserves the exact original %s snapshot including lexical decimals",
351
+ async (model) => {
352
+ const onSave = vi.fn().mockResolvedValue(undefined);
353
+ const common = {
354
+ ...initial.plan,
355
+ version: "original",
356
+ unit: { name: "call", precision: 2 },
357
+ rate: { currency: "usd", unitAmountDecimal: "2.00" },
358
+ };
359
+ const plan: ui.UsageConfigurationValue["plan"] =
360
+ model === "included_overage"
361
+ ? {
362
+ ...common,
363
+ model,
364
+ includedQuantity: "100.00",
365
+ reset: "billing_period",
366
+ }
367
+ : model === "prepaid"
368
+ ? { ...common, model, insufficientBalance: "reject" }
369
+ : { ...common, model };
370
+ const original: ui.UsageConfigurationValue = {
371
+ ...initial,
372
+ plan,
373
+ ...(model === "prepaid"
374
+ ? { creditPackage: { quantity: "100.00", topUp: "manual" } }
375
+ : {}),
376
+ };
377
+ render(
378
+ <ui.UsageConfiguration
379
+ scope={scope}
380
+ initial={initial}
381
+ meters={[{ id: "mtr_original", active: true, configuration: original }]}
382
+ onSave={onSave}
383
+ />,
384
+ );
385
+ field("Meter", "mtr_original");
386
+ save();
387
+ await waitFor(() => expect(onSave).toHaveBeenCalledTimes(1));
388
+ expect(onSave.mock.calls[0][0]).toEqual({
389
+ ...original,
390
+ meterId: "mtr_original",
391
+ });
392
+ },
393
+ );