@fantastic.dev/better-stripe 0.62.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 (56) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +4 -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/workflows/Usage.types.d.ts +2 -23
  35. package/dist/react/workflows/Usage.types.d.ts.map +1 -1
  36. package/dist/react/workflows/Usage.types.js.map +1 -1
  37. package/dist/react/workflows/UsageConfiguration.types.d.ts +3 -11
  38. package/dist/react/workflows/UsageConfiguration.types.d.ts.map +1 -1
  39. package/docs/README.md +2 -0
  40. package/docs/usage-configuration.md +4 -0
  41. package/docs/usage-delivery.md +4 -0
  42. package/docs/usage-example.md +246 -0
  43. package/docs/usage-react.md +4 -0
  44. package/docs/usage-settlement.md +8 -3
  45. package/package.json +3 -2
  46. package/src/client/paymentSource/resolver.ts +14 -2
  47. package/src/client/paymentSource/zeroTierLines.ts +42 -0
  48. package/src/client/usage/configuration.ts +9 -0
  49. package/src/client/usage/deliveryProvider.test.ts +77 -37
  50. package/src/client/usage/deliveryProvider.ts +19 -0
  51. package/src/client/usage/index.ts +4 -0
  52. package/src/client/usage/invoiceSale.test.ts +68 -0
  53. package/src/client/usage/invoiceSale.ts +20 -2
  54. package/src/client/usage/views.ts +23 -0
  55. package/src/react/workflows/Usage.types.ts +5 -29
  56. package/src/react/workflows/UsageConfiguration.types.ts +3 -11
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=views.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"views.js","sourceRoot":"","sources":["../../../src/client/usage/views.ts"],"names":[],"mappings":""}
@@ -22,6 +22,14 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
22
22
  requestKey: string;
23
23
  scopeKey: string;
24
24
  }, Promise<{
25
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
26
+ retryable: false;
27
+ status: "conflict";
28
+ } | {
29
+ reason: "policy_invalid";
30
+ retryable: false;
31
+ status: "rejected";
32
+ } | {
25
33
  operation: {
26
34
  accountId: string;
27
35
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -32,14 +40,6 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
32
40
  } | {
33
41
  enabled: boolean;
34
42
  status: "unchanged";
35
- } | {
36
- reason: "identity_changed" | "revision_changed" | "scope_busy";
37
- retryable: false;
38
- status: "conflict";
39
- } | {
40
- reason: "policy_invalid";
41
- retryable: false;
42
- status: "rejected";
43
43
  } | {
44
44
  reason: "provider_pending";
45
45
  retryable: true;
@@ -395,6 +395,14 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
395
395
  requestKey: string;
396
396
  scopeKey: string;
397
397
  }, Promise<{
398
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
399
+ retryable: false;
400
+ status: "conflict";
401
+ } | {
402
+ reason: "policy_invalid";
403
+ retryable: false;
404
+ status: "rejected";
405
+ } | {
398
406
  operation: {
399
407
  accountId: string;
400
408
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -405,14 +413,6 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
405
413
  } | {
406
414
  enabled: boolean;
407
415
  status: "unchanged";
408
- } | {
409
- reason: "identity_changed" | "revision_changed" | "scope_busy";
410
- retryable: false;
411
- status: "conflict";
412
- } | {
413
- reason: "policy_invalid";
414
- retryable: false;
415
- status: "rejected";
416
416
  } | {
417
417
  reason: "provider_pending";
418
418
  retryable: true;
@@ -163,10 +163,10 @@ export declare const snapshot: import("convex/server").RegisteredQuery<"public",
163
163
  accountId: string;
164
164
  ownerKey: string;
165
165
  }, Promise<{
166
- transfers?: undefined;
167
- claims?: undefined;
168
166
  status: "held";
169
167
  reason: "snapshot_limit";
168
+ transfers?: undefined;
169
+ claims?: undefined;
170
170
  } | {
171
171
  reason?: undefined;
172
172
  status: "ready";
@@ -1 +1 @@
1
- {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/payoutRelease/queries.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIlB,CAAC;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiBd,CAAC;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BlB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;GAQf,CAAC;AAEH,4FAA4F;AAC5F,eAAO,MAAM,QAAQ;;;;;;YAsBE,MAAM;YAAmB,gBAAgB;;;YAS3C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE1B,CAAC"}
1
+ {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/payoutRelease/queries.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIlB,CAAC;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiBd,CAAC;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BlB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;GAQf,CAAC;AAEH,4FAA4F;AAC5F,eAAO,MAAM,QAAQ;;;;YAsBE,MAAM;YAAmB,gBAAgB;;;;;YAS3C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE1B,CAAC"}
@@ -1,25 +1,4 @@
1
- import type { UsageAvailability, UsagePeriod } from "../../client/usage/boundaries.js";
2
- import type { UsageLocalSummary } from "../../client/usage/summary.js";
3
- import type { UsageAggregateObservation } from "../../client/usage/observationTypes.js";
4
- import type { UsageAllowanceStatus } from "../../client/usage/allowanceTerms.js";
5
- import type { UsageCreditBalance, UsageCreditPurchase } from "../../client/usage/creditTerms.js";
6
- import type { UsageCreditReconciliation } from "../../client/usage/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
- };
1
+ import type { UsageViewScope } from "../../client/usage/views.js";
2
+ export type { UsageViewScope, UsageBillingSnapshot, } from "../../client/usage/views.js";
24
3
  export declare function usageViewKey(scope: UsageViewScope): string;
25
4
  //# sourceMappingURL=Usage.types.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Usage.types.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/Usage.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AACzF,uGAAuG;AACvG,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AACF,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IAC9C,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,SAAS,CAAC,EAAE,iBAAiB,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAC3D,OAAO,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACtC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC,yBAAyB,CAAC,CAAC;CAClE,CAAC;AACF,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,UASjD"}
1
+ {"version":3,"file":"Usage.types.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/Usage.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,YAAY,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,UASjD"}
@@ -1 +1 @@
1
- {"version":3,"file":"Usage.types.js","sourceRoot":"","sources":["../../../src/react/workflows/Usage.types.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,KAAK,CAAC,WAAW;QACjB,KAAK,CAAC,UAAU;QAChB,KAAK,CAAC,QAAQ;QACd,KAAK,CAAC,MAAM,CAAC,KAAK;QAClB,KAAK,CAAC,MAAM,CAAC,GAAG;QAChB,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE;KAC7B,CAAC,CAAC;AACL,CAAC"}
1
+ {"version":3,"file":"Usage.types.js","sourceRoot":"","sources":["../../../src/react/workflows/Usage.types.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,KAAK,CAAC,WAAW;QACjB,KAAK,CAAC,UAAU;QAChB,KAAK,CAAC,QAAQ;QACd,KAAK,CAAC,MAAM,CAAC,KAAK;QAClB,KAAK,CAAC,MAAM,CAAC,GAAG;QAChB,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE;KAC7B,CAAC,CAAC;AACL,CAAC"}
@@ -1,5 +1,7 @@
1
1
  import type { ReactNode } from "react";
2
- import type { UsagePlan, UsageBillingModel } from "../../client/usage/contracts.js";
2
+ import type { UsageConfigurationValue } from "../../client/usage/configuration.js";
3
+ export type { UsageConfigurationValue } from "../../client/usage/configuration.js";
4
+ import type { UsageBillingModel } from "../../client/usage/contracts.js";
3
5
  /** Display/cache context from an authenticated host. Never use this as server authorization. */
4
6
  export type UsageConfigurationScope = {
5
7
  identityKey: string;
@@ -11,16 +13,6 @@ export type UsageConfigurationScope = {
11
13
  /** Host has verified the configured issuer realm and supported native catalog. */
12
14
  capability: "issuer_native" | "unsupported";
13
15
  };
14
- export type UsageConfigurationValue = {
15
- plan: UsagePlan;
16
- eventName: string;
17
- displayName: string;
18
- meterId?: string;
19
- creditPackage?: {
20
- quantity: string;
21
- topUp: "manual";
22
- };
23
- };
24
16
  export type UsageMeterChoice = {
25
17
  id: string;
26
18
  active: boolean;
@@ -1 +1 @@
1
- {"version":3,"file":"UsageConfiguration.types.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/UsageConfiguration.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AACzC,gGAAgG;AAChG,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,kFAAkF;IAClF,UAAU,EAAE,eAAe,GAAG,aAAa,CAAC;CAC7C,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,CAAC;CACvD,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,aAAa,EAAE,uBAAuB,CAAC;CACxC,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,OAAO,EAAE,uBAAuB,CAAC;IACjC,gGAAgG;IAChG,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,8FAA8F;IAC9F,MAAM,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,SAAS,CAAC;CAC1D,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,wBAAwB,CAAC;IACjC,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,wBAAwB,EACjD,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,wBAAwB,CAAC,CAAC,CAAC,KAC/B,IAAI,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9B,CAAC"}
1
+ {"version":3,"file":"UsageConfiguration.types.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/UsageConfiguration.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,YAAY,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,gGAAgG;AAChG,MAAM,MAAM,uBAAuB,GAAG;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,kFAAkF;IAClF,UAAU,EAAE,eAAe,GAAG,aAAa,CAAC;CAC7C,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,aAAa,EAAE,uBAAuB,CAAC;CACxC,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,OAAO,EAAE,uBAAuB,CAAC;IACjC,gGAAgG;IAChG,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,8FAA8F;IAC9F,MAAM,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,KAAK,SAAS,CAAC;CAC1D,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,wBAAwB,CAAC;IACjC,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,wBAAwB,EACjD,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,wBAAwB,CAAC,CAAC,CAAC,KAC/B,IAAI,CAAC;IACV,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9B,CAAC"}
package/docs/README.md CHANGED
@@ -80,3 +80,5 @@ Start with the [native Stripe setup guide](metering-setup.md), then read the
80
80
  - [Reusable metered billing UI](usage-react.md) covers all three models, render props, authenticated adapters and bounded history.
81
81
 
82
82
  - [Native usage configuration UI](usage-configuration.md) covers reusable forms, managed meter selection, price rows and authorized adapters.
83
+
84
+ - [Native metered billing example](usage-example.md), three runnable models, paid evidence and scoped cleanup.
@@ -93,6 +93,10 @@ key for changed terms. Saving does not migrate, cancel or reprice existing
93
93
  subscriptions. Those keep their original price until an explicit authorized host
94
94
  operation changes them.
95
95
 
96
+ Server adapters can import the `UsageConfigurationValue` type from
97
+ `@fantastic.dev/better-stripe/usage` without loading React types. The React entry
98
+ point continues to re-export it for UI consumers.
99
+
96
100
  `onSave` receives `{ plan, eventName, displayName, meterId?, creditPackage? }`.
97
101
  For prepaid, `creditPackage` is `{ quantity, topUp: "manual" }`. It is configuration
98
102
  only. Saving does not create a payment, grant credits or authorize consumption.
@@ -92,6 +92,10 @@ window. Automatic sends also stop 23 hours after the first send attempt. Stripe
92
92
  retains deduplication for at least 24 hours, not forever. A historical acceptance
93
93
  receipt remains valid after these windows expire, but does not authorize replay.
94
94
  The adapter never changes the original occurrence time to make an event eligible.
95
+ For a sandbox subscription attached to a test clock, delivery additionally reads
96
+ the native clock and checks its 35-day past/5-minute future window. An advancing
97
+ or unavailable clock holds delivery. A timestamp outside its native window is
98
+ rejected before sending. Production source timestamps remain unchanged.
95
99
 
96
100
  ## Status and operational controls
97
101
 
@@ -0,0 +1,246 @@
1
+ # Run all three native billing models
2
+
3
+ The example at `/demo/metered-usage` uses the public BetterStripe package against a
4
+ Stripe sandbox. It provisions a dedicated Accounts v2 customer, test clock,
5
+ product, meter, price and managed subscription per persona and model. Usage,
6
+ delivery, allowance reservations, credits, corrections and settlement live in the
7
+ component. The example stores fixture provenance and synthetic application work.
8
+
9
+ Start with [sandbox setup](metering-setup.md). Use your existing Stripe sandbox;
10
+ no Metronome account or token is needed. Run the example backend and frontend
11
+ from the `example` directory with `pnpm dev`. Keep test keys in the backend
12
+ Convex environment. Do not copy secret values into commands, screenshots, source
13
+ files or browser storage.
14
+
15
+ ## Demo security model
16
+
17
+ This repository's persona switcher is a test-only convenience, not authentication.
18
+ Choose Customer, Seller or Admin, then Metered billing. Each operation rechecks
19
+ the server's persona binding and test key. If an authenticated identity is present,
20
+ it must match the persona's stored token identifier. Visitor and affiliate
21
+ personas cannot operate the workflow. Do not expose these demo endpoints as a
22
+ production billing service.
23
+
24
+ In your app, replace the persona lookup with real authentication and server-owned
25
+ customer, product, entitlement and recipient authorization. Never trust a browser
26
+ account ID, product ID, price, rate or settlement policy. See
27
+ [authorization and recovery](usage-security.md).
28
+
29
+ Admin and seller personas can configure the unit, precision, currency, exact price,
30
+ version and model-specific terms before setup. Customers run the server-owned
31
+ defaults. Setup retries retain the original native identities and configuration.
32
+ A saved meter and subscription keep their original terms. Archive a resolved run
33
+ before configuring its replacement.
34
+
35
+ ## Pay as you go
36
+
37
+ 1. Select Pay as you go, then Set up sandbox.
38
+ 2. Run five units three times. The default price is USD 1 per call.
39
+ 3. Replay last work. Its source identity, quantity and occurrence time stay fixed;
40
+ the synthetic application work and usage acceptance happen once.
41
+ 4. Observe native usage. If delivery is queued, use Resume queued deliveries.
42
+ Stripe aggregation is asynchronous. Refresh until the aggregate is 15.
43
+ 5. Close or resume original billing period. This fences new work, checks complete
44
+ local/native equality, drains reservations and checks every correction and
45
+ purchase intent. It advances only this run's test clock.
46
+ 6. Resume after the clock is ready. The server finds the unique original cycle
47
+ invoice, verifies its meter lines, finalizes it and pays with Stripe's sandbox
48
+ card. The default invoice is USD 15.
49
+
50
+ The outcome separately shows invoice payment, original cash verification, actual
51
+ processing fees and any verified recipient transfers. A paid invoice alone does
52
+ not imply that settlement is ready.
53
+
54
+ ## Included monthly usage and overages
55
+
56
+ Select Included monthly usage. The defaults include ten calls per original
57
+ monthly period, then USD 1 per additional call. Run three five-unit jobs. The
58
+ package allowance view shows 15 consumed, ten included, five billable overage
59
+ units and the soft-limit warning at 12. The native invoice is USD 5.
60
+
61
+ Closing the period observes the next native subscription period. When that period
62
+ is active on the Convex server, its separate allowance starts at zero consumed
63
+ and ten remaining included units. The old period and history stay unchanged. A
64
+ test clock can move ahead of real time; future renewal allowance is explicitly
65
+ unavailable. Its view stays read-only until the period is active on the server and
66
+ new event times are inside the provider's real acceptance window. This demo does not forge
67
+ future work timestamps to simulate another month's consumption.
68
+
69
+ ## Paid prepaid credits
70
+
71
+ 1. Select Prepaid credits and set up its dedicated sandbox resources.
72
+ 2. Run five units before funding. Work is held and does not execute.
73
+ 3. Create credit purchase. The default original purchase is ten units for USD 10.
74
+ Pending payment grants no usable credit.
75
+ 4. Confirm sandbox card. The backend uses Stripe's test card and the package
76
+ verifies the original captured PaymentIntent, customer and paid credit grant.
77
+ 5. Run two five-unit jobs. Replay a successful job before creating another one to
78
+ demonstrate idempotency. Another five-unit job is denied after exhaustion.
79
+ 6. Observe native usage, then close and resume the period. The native credit grant
80
+ covers the consumption invoice. The demo refuses to pay any positive prepaid
81
+ invoice remainder with a second cash payment.
82
+
83
+ The USD 10 purchase is the only cash source. Credit consumption collects no new
84
+ cash. The package reconciles native credit transactions against complete invoice
85
+ history. Unavailable observations are shown explicitly, never as a zero balance.
86
+
87
+ For production, send the package purchase result's `clientSecret` only to the
88
+ properly authenticated purchaser's Stripe payment UI. Do not store or log it.
89
+ Confirming a payment in the UI is not proof of usable credits; call
90
+ `observeCreditPurchase` and wait for the verified ready grant. See
91
+ [paid credit accounting](usage-credits.md).
92
+
93
+ Prepaid is limited to the issuer's own services. A seller persona cannot redeem
94
+ credits into reseller proceeds. An authorized affiliate can be paid once from the
95
+ original purchase; usage does not produce another affiliate sale.
96
+
97
+ ## Corrections and retained failures
98
+
99
+ Before closing, Correct last accepted event cancels its original native event
100
+ through the package. Repeated correction requests keep the same correction ID.
101
+ Wait for confirmation and native reaggregation. A new application job can then
102
+ use the released capacity. For example, record 15 units, cancel the last five,
103
+ then record a different five-unit job. Effective usage is 15, and history retains
104
+ 20 originally accepted units plus the five canceled units.
105
+
106
+ Unknown delivery outcomes stay held. Resume queued deliveries schedules only
107
+ records that the package still classifies as queued; it never resends unknown
108
+ attempts. Do not replace the source event ID, change the occurrence time, create
109
+ a new run to relabel the same work or invent a provider event identifier. Resolve
110
+ the original attempt with verified native evidence using the operational runbook.
111
+ A billing or cleanup guard failure preserves all work, purchase and correction
112
+ intents for reconciliation.
113
+
114
+ The fixture timestamps _new synthetic jobs_ at its retained test clock's original
115
+ period start. This keeps native meter events and paid grants on the same logical
116
+ clock. Retrying a job never changes that timestamp. Real applications must use
117
+ the actual occurrence time of their business event. Delivery checks both real
118
+ provider limits and an attached sandbox clock before a native event write.
119
+
120
+ ## Ownership and routing
121
+
122
+ Customer and admin runs use direct issuer billing. Seller runs pin their original
123
+ server-owned seller account and, when available, an existing demo affiliate at
124
+ setup. The demo policy is a 10% inclusive platform fee and a 20% affiliate share
125
+ of the eligible remainder, with recurring commission eligibility. The package
126
+ uses actual processing fees and verifies native payment provenance, recipient
127
+ capabilities and transfer identity. Unsupported Connect configurations remain
128
+ held. Accounts v2 payer configuration is separate from merchant or recipient
129
+ configuration; a customer account is not automatically eligible to receive money.
130
+ Prepaid settlement retains issuer revenue and accepts only eligible affiliate
131
+ policy, never seller or collaborator redemption.
132
+
133
+ ## Scoped cleanup and reset
134
+
135
+ Use Archive or resume scoped cleanup after the original invoice and cash evidence
136
+ are verified. It refuses unresolved delivery, corrections, reservations, purchases,
137
+ credit backing or settlement. Unspent paid credits require verified refund or
138
+ expiry; cleanup cannot wipe them.
139
+
140
+ Cleanup requests period-end cancellation, advances only the owned test clock to
141
+ the cancellation boundary, checks the final native cycle invoice and retires the
142
+ managed enrollment. It deactivates only the owned price, meter and product. It
143
+ retains the native payer, clock, invoice/payment evidence and every component
144
+ history record. It does not clear any Convex table or another developer's data.
145
+ After successful archival, Start new sandbox run creates new isolated resources.
146
+ Admin or seller can save a new version before starting that replacement.
147
+
148
+ Empty or unresolved runs can require operator reconciliation rather than automatic
149
+ archive. In particular, unknown provider outcomes must remain visible and retained.
150
+ Never delete a clock or payer to make financial evidence disappear.
151
+
152
+ ## Model configuration snippets
153
+
154
+ Use the same versioned unit and exact minor-currency rate in each model:
155
+
156
+ ```ts
157
+ import { defineUsagePlan } from "@fantastic.dev/better-stripe/usage";
158
+ const terms = {
159
+ key: "api-calls",
160
+ version: "v1",
161
+ unit: { name: "call", precision: 0 },
162
+ rate: { currency: "usd", unitAmountDecimal: "100" },
163
+ } as const;
164
+ ```
165
+
166
+ Pay as you go bills every effective unit:
167
+
168
+ ```ts
169
+ const payAsYouGo = defineUsagePlan({ ...terms, model: "pay_as_you_go" });
170
+ ```
171
+
172
+ Included monthly usage grants ten units before overages in each original period:
173
+
174
+ ```ts
175
+ const included = defineUsagePlan({
176
+ ...terms,
177
+ model: "included_overage",
178
+ includedQuantity: "10",
179
+ reset: "billing_period",
180
+ });
181
+ ```
182
+
183
+ Prepaid consumption requires verified paid grants and rejects insufficient credit:
184
+
185
+ ```ts
186
+ const prepaid = defineUsagePlan({
187
+ ...terms,
188
+ model: "prepaid",
189
+ insufficientBalance: "reject",
190
+ });
191
+ // After server authorization and native binding setup:
192
+ const purchase = await stripe.usage.purchaseCredits(
193
+ ctx,
194
+ {
195
+ ...originalCreditBinding,
196
+ purchaseId: originalBusinessPurchaseId,
197
+ quantity: "10",
198
+ ownership: "issuer",
199
+ rollover: "retain_original_terms",
200
+ },
201
+ { stripeSecretKey },
202
+ );
203
+ // Return clientSecret only to the authorized purchaser's payment UI.
204
+ // Observe the original purchase after payment; wait for its ready grant.
205
+ ```
206
+
207
+ Use `ensureUsageMeter`, `ensureUsagePrice` and `usage.ensureSubscription` to bind
208
+ the chosen plan to the server-authorized native payer. The exact implementations
209
+ are in the example's `meteredUsage/setup.ts` and `meteredUsage/funding.ts`.
210
+
211
+ ## Package calls behind the example
212
+
213
+ Server code imports neutral types from `@fantastic.dev/better-stripe/usage`; UI
214
+ code uses `@fantastic.dev/better-stripe/react`. The example backend lives under
215
+ `example/convex/meteredUsage`. Its atomic synthetic-work mutation follows this
216
+ pattern, using server-authorized original terms:
217
+
218
+ ```ts
219
+ const reservation =
220
+ model === "prepaid"
221
+ ? await stripe.usage.reserveCredits(ctx, { event, subscription })
222
+ : await stripe.usage.reserveAllowance(ctx, { event, subscription });
223
+ // Handle denied/released reservations before doing any application work.
224
+ const receipt = await stripe.usage.record(ctx, {
225
+ event,
226
+ subscription,
227
+ reservationId: reservation.reservationId,
228
+ });
229
+ // Persist synthetic DB work and receipt in this same mutation transaction.
230
+ ```
231
+
232
+ Schedule delivery from an action after the transaction commits:
233
+
234
+ ```ts
235
+ await stripe.usage.startDelivery(ctx, {
236
+ scope: original.scope,
237
+ eventId: receipt.eventId,
238
+ provider: internal.meteredUsage.delivery.deliver,
239
+ });
240
+ ```
241
+
242
+ For external application work, use a durable idempotent work protocol with the
243
+ original business identity. A database transaction cannot make an external side
244
+ effect atomic. See [ledger](usage-ledger.md), [delivery](usage-delivery.md),
245
+ [limits](usage-limits.md), [corrections](usage-corrections.md) and
246
+ [settlement](usage-settlement.md) for the complete contracts.
@@ -180,3 +180,7 @@ Run `pnpm run check:all` and verify your host's authorization and native setup
180
180
  using the [setup guide](metering-setup.md). Package views do not replace the
181
181
  [ledger](usage-ledger.md), [allowance](usage-limits.md) or
182
182
  [paid-credit](usage-credits.md) work and recovery protocols.
183
+
184
+ Server adapters can import the `UsageViewScope` and `UsageBillingSnapshot` types
185
+ from `@fantastic.dev/better-stripe/usage` without importing React types. The React
186
+ entry point retains its existing exports.
@@ -78,13 +78,18 @@ invoice. Refunds and disputes do not reset eligibility.
78
78
  An unpaid draft/open invoice returns `not_ready/provider_pending`. Missing fees
79
79
  remain `not_ready/fee_pending`. Zero paid invoices and refunded/disputed sources
80
80
  are not payable. Incomplete or ambiguous funding, credit-funded/partial/multiple
81
- payments, multiple priced invoice lines, proration, mismatched original periods,
81
+ payments, unrelated priced invoice lines, proration, mismatched original periods,
82
82
  converted settlement currencies and automatic destination/on-behalf-of charges
83
83
  are held through explicit non-ready outcomes. The method does not guess a
84
84
  multi-product allocation or take over existing destination-charge fee handling.
85
85
  Fixed-plus-metered invoices remain readable with the ordinary invoice APIs, but
86
- this automatic settlement method requires one original priced line. Treat these
87
- limits as unsupported settlement combinations, not as zero proceeds.
86
+ this automatic settlement method requires one paid original meter line. Native
87
+ included-overage invoices can also contain one zero-priced included-tier line.
88
+ Both lines must retain the same original price, product, subscription item,
89
+ period, currency and mode, with no credit adjustments. The complete independent
90
+ line-item read must match both original IDs. Additional paid lines, duplicate IDs
91
+ and foreign zero-priced siblings remain unsupported. Treat unsupported settlement
92
+ combinations as unavailable evidence rather than zero proceeds.
88
93
 
89
94
  ## Prepaid issuer-service revenue
90
95
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.62.0",
3
+ "version": "0.63.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -113,7 +113,8 @@
113
113
  "docs/usage-security.md",
114
114
  "docs/usage-react.md",
115
115
  "docs/evidence/native-metering",
116
- "docs/usage-configuration.md"
116
+ "docs/usage-configuration.md",
117
+ "docs/usage-example.md"
117
118
  ],
118
119
  "scripts": {
119
120
  "build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",
@@ -1,3 +1,4 @@
1
+ import { zeroTierLinesMatch } from "./zeroTierLines.js";
1
2
  import type Stripe from "stripe";
2
3
  import type {
3
4
  FinancialOutcome,
@@ -53,6 +54,7 @@ export async function resolveVerifiedPaymentSource(
53
54
  customerId: string;
54
55
  invoiceLine?: {
55
56
  id: string;
57
+ zeroAmountLineIds?: string[];
56
58
  subscriptionItemId: string;
57
59
  period: { start: number; end: number };
58
60
  };
@@ -324,8 +326,18 @@ export async function resolveVerifiedPaymentSource(
324
326
  ),
325
327
  );
326
328
  if (lines.status !== "complete") return lines;
327
- requireSource(lines.data.length === 1, reject("unsupported_source"));
328
- const line = lines.data[0]!;
329
+ const zeroIds = eligibility?.invoiceLine?.zeroAmountLineIds ?? [];
330
+ const line = zeroIds.length
331
+ ? lines.data.find((row) => row.id === eligibility!.invoiceLine!.id)
332
+ : lines.data[0];
333
+ requireSource(
334
+ line &&
335
+ (zeroIds.length
336
+ ? zeroTierLinesMatch(lines.data, line, zeroIds)
337
+ : lines.data.length === 1),
338
+ reject("unsupported_source"),
339
+ );
340
+ if (!line) return reject("unsupported_source");
329
341
  requireSource(
330
342
  line.object === "line_item" &&
331
343
  line.invoice === invoice.id &&
@@ -0,0 +1,42 @@
1
+ import type Stripe from "stripe";
2
+ /** Only explicitly pinned zero-priced siblings of one paid graduated tier are eligible. */
3
+ export function zeroTierLinesMatch(
4
+ lines: Stripe.InvoiceLineItem[],
5
+ paid: Stripe.InvoiceLineItem,
6
+ ids: readonly string[],
7
+ ): boolean {
8
+ if (
9
+ ids.length !== 1 ||
10
+ lines.length !== 2 ||
11
+ new Set(lines.map((row) => row.id)).size !== 2
12
+ )
13
+ return false;
14
+ const free = lines.find((row) => row.id === ids[0]);
15
+ if (!free || free.id === paid.id) return false;
16
+ const parent = free.parent?.subscription_item_details;
17
+ const original = paid.parent?.subscription_item_details;
18
+ const price = free.pricing?.price_details;
19
+ const originalPrice = paid.pricing?.price_details;
20
+ return (
21
+ free.object === "line_item" &&
22
+ free.invoice === paid.invoice &&
23
+ free.livemode === paid.livemode &&
24
+ free.amount === 0 &&
25
+ free.currency === paid.currency &&
26
+ free.period.start === paid.period.start &&
27
+ free.period.end === paid.period.end &&
28
+ !!parent &&
29
+ !parent.proration &&
30
+ parent.subscription === original?.subscription &&
31
+ parent.subscription_item === original?.subscription_item &&
32
+ free.pricing?.type === "price_details" &&
33
+ !!price &&
34
+ price.price === originalPrice?.price &&
35
+ price.product === originalPrice?.product &&
36
+ (free.pretax_credit_amounts ?? []).length === 0 &&
37
+ (free.quantity_decimal != null
38
+ ? /^\d{1,30}(\.\d{1,12})?$/.test(free.quantity_decimal.toString()) &&
39
+ /[1-9]/.test(free.quantity_decimal.toString())
40
+ : Number.isSafeInteger(free.quantity) && free.quantity! > 0)
41
+ );
42
+ }
@@ -0,0 +1,9 @@
1
+ import type { UsagePlan } from "./contracts.js";
2
+ /** Server-safe configuration payload shared with the reusable React form. */
3
+ export type UsageConfigurationValue = {
4
+ plan: UsagePlan;
5
+ eventName: string;
6
+ displayName: string;
7
+ meterId?: string;
8
+ creditPackage?: { quantity: string; topUp: "manual" };
9
+ };