@fantastic.dev/better-stripe 0.62.0 → 0.64.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 (217) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +22 -2
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +550 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +275 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +550 -0
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +275 -0
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/financialOwnership.d.ts +2 -2
  12. package/dist/client/financialOwnership.d.ts.map +1 -1
  13. package/dist/client/financialOwnership.js +2 -2
  14. package/dist/client/financialOwnership.js.map +1 -1
  15. package/dist/client/paymentSource/resolver.d.ts +1 -0
  16. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  17. package/dist/client/paymentSource/resolver.js +11 -2
  18. package/dist/client/paymentSource/resolver.js.map +1 -1
  19. package/dist/client/paymentSource/zeroTierLines.d.ts +4 -0
  20. package/dist/client/paymentSource/zeroTierLines.d.ts.map +1 -0
  21. package/dist/client/paymentSource/zeroTierLines.js +35 -0
  22. package/dist/client/paymentSource/zeroTierLines.js.map +1 -0
  23. package/dist/client/payoutRevisionMigration.d.ts +37 -0
  24. package/dist/client/payoutRevisionMigration.d.ts.map +1 -0
  25. package/dist/client/payoutRevisionMigration.js +49 -0
  26. package/dist/client/payoutRevisionMigration.js.map +1 -0
  27. package/dist/client/publicTypes.d.ts +2 -0
  28. package/dist/client/publicTypes.d.ts.map +1 -1
  29. package/dist/client/reversalObservations.d.ts +62 -0
  30. package/dist/client/reversalObservations.d.ts.map +1 -0
  31. package/dist/client/reversalObservations.js +79 -0
  32. package/dist/client/reversalObservations.js.map +1 -0
  33. package/dist/client/usage/configuration.d.ts +13 -0
  34. package/dist/client/usage/configuration.d.ts.map +1 -0
  35. package/dist/client/usage/configuration.js +2 -0
  36. package/dist/client/usage/configuration.js.map +1 -0
  37. package/dist/client/usage/deliveryProvider.d.ts.map +1 -1
  38. package/dist/client/usage/deliveryProvider.js +16 -0
  39. package/dist/client/usage/deliveryProvider.js.map +1 -1
  40. package/dist/client/usage/index.d.ts +2 -0
  41. package/dist/client/usage/index.d.ts.map +1 -1
  42. package/dist/client/usage/invoiceSale.d.ts.map +1 -1
  43. package/dist/client/usage/invoiceSale.js +15 -2
  44. package/dist/client/usage/invoiceSale.js.map +1 -1
  45. package/dist/client/usage/observationClient.d.ts +2 -2
  46. package/dist/client/usage/observationClient.d.ts.map +1 -1
  47. package/dist/client/usage/views.d.ts +24 -0
  48. package/dist/client/usage/views.d.ts.map +1 -0
  49. package/dist/client/usage/views.js +2 -0
  50. package/dist/client/usage/views.js.map +1 -0
  51. package/dist/component/_generated/api.d.ts +28 -0
  52. package/dist/component/_generated/api.d.ts.map +1 -1
  53. package/dist/component/_generated/api.js.map +1 -1
  54. package/dist/component/_generated/component.d.ts +354 -0
  55. package/dist/component/_generated/component.d.ts.map +1 -1
  56. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  57. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  58. package/dist/component/connect/mutations.d.ts.map +1 -1
  59. package/dist/component/connect/mutations.js +2 -0
  60. package/dist/component/connect/mutations.js.map +1 -1
  61. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  62. package/dist/component/connect/reversalClaims.js +10 -1
  63. package/dist/component/connect/reversalClaims.js.map +1 -1
  64. package/dist/component/earnings/triggers.d.ts +408 -16
  65. package/dist/component/earnings/triggers.d.ts.map +1 -1
  66. package/dist/component/financialObservations/transferSchema.d.ts +1 -0
  67. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -1
  68. package/dist/component/financialObservations/transferSchema.js +1 -0
  69. package/dist/component/financialObservations/transferSchema.js.map +1 -1
  70. package/dist/component/payoutRevisionJournal/mutations.d.ts +15 -0
  71. package/dist/component/payoutRevisionJournal/mutations.d.ts.map +1 -0
  72. package/dist/component/payoutRevisionJournal/mutations.js +11 -0
  73. package/dist/component/payoutRevisionJournal/mutations.js.map +1 -0
  74. package/dist/component/payoutRevisionJournal/schema.d.ts +45 -0
  75. package/dist/component/payoutRevisionJournal/schema.d.ts.map +1 -0
  76. package/dist/component/payoutRevisionJournal/schema.js +22 -0
  77. package/dist/component/payoutRevisionJournal/schema.js.map +1 -0
  78. package/dist/component/payoutRevisionJournal/state.d.ts +36 -0
  79. package/dist/component/payoutRevisionJournal/state.d.ts.map +1 -0
  80. package/dist/component/payoutRevisionJournal/state.js +111 -0
  81. package/dist/component/payoutRevisionJournal/state.js.map +1 -0
  82. package/dist/component/payoutRevisionMigration/mutations.d.ts +36 -0
  83. package/dist/component/payoutRevisionMigration/mutations.d.ts.map +1 -0
  84. package/dist/component/payoutRevisionMigration/mutations.js +126 -0
  85. package/dist/component/payoutRevisionMigration/mutations.js.map +1 -0
  86. package/dist/component/payoutRevisionMigration/queries.d.ts +38 -0
  87. package/dist/component/payoutRevisionMigration/queries.d.ts.map +1 -0
  88. package/dist/component/payoutRevisionMigration/queries.js +39 -0
  89. package/dist/component/payoutRevisionMigration/queries.js.map +1 -0
  90. package/dist/component/payoutRevisionMigration/schema.d.ts +115 -0
  91. package/dist/component/payoutRevisionMigration/schema.d.ts.map +1 -0
  92. package/dist/component/payoutRevisionMigration/schema.js +52 -0
  93. package/dist/component/payoutRevisionMigration/schema.js.map +1 -0
  94. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts +4 -0
  95. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts.map +1 -0
  96. package/dist/component/payoutSnapshots/legacyRevisionWriter.js +33 -0
  97. package/dist/component/payoutSnapshots/legacyRevisionWriter.js.map +1 -0
  98. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  99. package/dist/component/payoutSnapshots/revisions.js +23 -29
  100. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  101. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  102. package/dist/component/refundSync/mutations.d.ts +1 -1
  103. package/dist/component/refundSync/mutations.d.ts.map +1 -1
  104. package/dist/component/reversalObservations/capture.d.ts +6 -0
  105. package/dist/component/reversalObservations/capture.d.ts.map +1 -0
  106. package/dist/component/reversalObservations/capture.js +96 -0
  107. package/dist/component/reversalObservations/capture.js.map +1 -0
  108. package/dist/component/reversalObservations/indexSlice.d.ts +29 -0
  109. package/dist/component/reversalObservations/indexSlice.d.ts.map +1 -0
  110. package/dist/component/reversalObservations/indexSlice.js +101 -0
  111. package/dist/component/reversalObservations/indexSlice.js.map +1 -0
  112. package/dist/component/reversalObservations/integrity.d.ts +25 -0
  113. package/dist/component/reversalObservations/integrity.d.ts.map +1 -0
  114. package/dist/component/reversalObservations/integrity.js +19 -0
  115. package/dist/component/reversalObservations/integrity.js.map +1 -0
  116. package/dist/component/reversalObservations/mutations.d.ts +37 -0
  117. package/dist/component/reversalObservations/mutations.d.ts.map +1 -0
  118. package/dist/component/reversalObservations/mutations.js +181 -0
  119. package/dist/component/reversalObservations/mutations.js.map +1 -0
  120. package/dist/component/reversalObservations/pagination.d.ts +34 -0
  121. package/dist/component/reversalObservations/pagination.d.ts.map +1 -0
  122. package/dist/component/reversalObservations/pagination.js +31 -0
  123. package/dist/component/reversalObservations/pagination.js.map +1 -0
  124. package/dist/component/reversalObservations/queries.d.ts +221 -0
  125. package/dist/component/reversalObservations/queries.d.ts.map +1 -0
  126. package/dist/component/reversalObservations/queries.js +114 -0
  127. package/dist/component/reversalObservations/queries.js.map +1 -0
  128. package/dist/component/reversalObservations/references.d.ts +17 -0
  129. package/dist/component/reversalObservations/references.d.ts.map +1 -0
  130. package/dist/component/reversalObservations/references.js +95 -0
  131. package/dist/component/reversalObservations/references.js.map +1 -0
  132. package/dist/component/reversalObservations/schema.d.ts +525 -0
  133. package/dist/component/reversalObservations/schema.d.ts.map +1 -0
  134. package/dist/component/reversalObservations/schema.js +92 -0
  135. package/dist/component/reversalObservations/schema.js.map +1 -0
  136. package/dist/component/reversalObservations/selectors.d.ts +3 -0
  137. package/dist/component/reversalObservations/selectors.d.ts.map +1 -0
  138. package/dist/component/reversalObservations/selectors.js +8 -0
  139. package/dist/component/reversalObservations/selectors.js.map +1 -0
  140. package/dist/component/reversalObservations/state.d.ts +34 -0
  141. package/dist/component/reversalObservations/state.d.ts.map +1 -0
  142. package/dist/component/reversalObservations/state.js +34 -0
  143. package/dist/component/reversalObservations/state.js.map +1 -0
  144. package/dist/component/schema.d.ts +275 -0
  145. package/dist/component/schema.js +10 -0
  146. package/dist/component/schema.js.map +1 -1
  147. package/dist/component/usage/allowance.fixtures.d.ts +291 -16
  148. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  149. package/dist/component/usageCredits/accounting.fixtures.d.ts +275 -0
  150. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  151. package/dist/react/workflows/Usage.types.d.ts +2 -23
  152. package/dist/react/workflows/Usage.types.d.ts.map +1 -1
  153. package/dist/react/workflows/Usage.types.js.map +1 -1
  154. package/dist/react/workflows/UsageConfiguration.types.d.ts +3 -11
  155. package/dist/react/workflows/UsageConfiguration.types.d.ts.map +1 -1
  156. package/docs/README.md +4 -1
  157. package/docs/client-api.md +6 -0
  158. package/docs/financial-observations.md +51 -8
  159. package/docs/payout-revision-migration.md +54 -0
  160. package/docs/react-workflows-audit.md +73 -2
  161. package/docs/usage-configuration.md +4 -0
  162. package/docs/usage-delivery.md +4 -0
  163. package/docs/usage-example.md +250 -0
  164. package/docs/usage-react.md +4 -0
  165. package/docs/usage-settlement.md +8 -3
  166. package/package.json +4 -2
  167. package/src/client/financialOwnership.ts +2 -2
  168. package/src/client/paymentSource/resolver.ts +14 -2
  169. package/src/client/paymentSource/zeroTierLines.ts +42 -0
  170. package/src/client/payoutRevisionMigration.test.ts +40 -0
  171. package/src/client/payoutRevisionMigration.ts +96 -0
  172. package/src/client/publicTypes.ts +15 -0
  173. package/src/client/reversalObservations.test.ts +69 -0
  174. package/src/client/reversalObservations.ts +151 -0
  175. package/src/client/usage/configuration.ts +9 -0
  176. package/src/client/usage/deliveryProvider.test.ts +77 -37
  177. package/src/client/usage/deliveryProvider.ts +19 -0
  178. package/src/client/usage/index.ts +4 -0
  179. package/src/client/usage/invoiceSale.test.ts +68 -0
  180. package/src/client/usage/invoiceSale.ts +20 -2
  181. package/src/client/usage/views.ts +23 -0
  182. package/src/component/_generated/api.ts +28 -0
  183. package/src/component/_generated/component.ts +423 -0
  184. package/src/component/connect/mutations.ts +2 -0
  185. package/src/component/connect/reversalClaims.ts +13 -1
  186. package/src/component/financialObservations/transferSchema.ts +1 -0
  187. package/src/component/payoutRevisionJournal/mutations.ts +11 -0
  188. package/src/component/payoutRevisionJournal/schema.ts +34 -0
  189. package/src/component/payoutRevisionJournal/state.ts +141 -0
  190. package/src/component/payoutRevisionMigration/mutations.ts +135 -0
  191. package/src/component/payoutRevisionMigration/queries.ts +50 -0
  192. package/src/component/payoutRevisionMigration/schema.ts +51 -0
  193. package/src/component/payoutSnapshots/legacy-revisions.test.ts +246 -0
  194. package/src/component/payoutSnapshots/legacyRevisionWriter.ts +39 -0
  195. package/src/component/payoutSnapshots/revision-journal-callbacks.test.ts +160 -0
  196. package/src/component/payoutSnapshots/revision-journal-held.test.ts +94 -0
  197. package/src/component/payoutSnapshots/revision-journal.test.ts +310 -0
  198. package/src/component/payoutSnapshots/revision-migration.test.ts +128 -0
  199. package/src/component/payoutSnapshots/revisions.ts +22 -30
  200. package/src/component/reversalObservations/boundaries.test.ts +62 -0
  201. package/src/component/reversalObservations/capture-integrity.test.ts +119 -0
  202. package/src/component/reversalObservations/capture.ts +129 -0
  203. package/src/component/reversalObservations/continuation.test.ts +131 -0
  204. package/src/component/reversalObservations/indexSlice.ts +124 -0
  205. package/src/component/reversalObservations/integrity.ts +31 -0
  206. package/src/component/reversalObservations/lifecycle.test.ts +81 -0
  207. package/src/component/reversalObservations/mutations.ts +211 -0
  208. package/src/component/reversalObservations/pagination.ts +40 -0
  209. package/src/component/reversalObservations/provenance.test.ts +167 -0
  210. package/src/component/reversalObservations/queries.ts +121 -0
  211. package/src/component/reversalObservations/references.ts +134 -0
  212. package/src/component/reversalObservations/schema.ts +100 -0
  213. package/src/component/reversalObservations/selectors.ts +9 -0
  214. package/src/component/reversalObservations/state.ts +42 -0
  215. package/src/component/schema.ts +18 -0
  216. package/src/react/workflows/Usage.types.ts +5 -29
  217. package/src/react/workflows/UsageConfiguration.types.ts +3 -11
@@ -0,0 +1,69 @@
1
+ // @vitest-environment edge-runtime
2
+ import { expect, it } from "vitest";
3
+ import schema from "../component/schema.js";
4
+ import { BetterStripe } from "./index.js";
5
+ import type { RunCtx } from "./helpers.js";
6
+ import { components, initConvexTest } from "./setup.test.js";
7
+ const modules = import.meta.glob("../component/**/*.ts");
8
+ it("navigates package-owned reversal history through the public facade without Stripe", async () => {
9
+ const t = initConvexTest();
10
+ t.registerComponent("betterStripe", schema, modules);
11
+ const client = new BetterStripe(components.betterStripe);
12
+ const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
13
+ await t.mutation(components.betterStripe.connect.mutations.upsertTransfer, {
14
+ stripeTransferId: "tr_sdk_history",
15
+ sourceChargeId: "ch_sdk_history",
16
+ destinationAccountId: "acct_sdk",
17
+ amount: 10,
18
+ currency: "usd",
19
+ role: "store",
20
+ status: "paid",
21
+ });
22
+ await t.mutation(
23
+ components.betterStripe.connect.mutations.claimReversalSlices,
24
+ {
25
+ operationId: "op_sdk_history",
26
+ sourceChargeId: "ch_sdk_history",
27
+ mode: { kind: "full" },
28
+ },
29
+ );
30
+ const history = await client.reversalObservations.history(ctx, {
31
+ selector: "sourceChargeId",
32
+ value: "ch_sdk_history",
33
+ paginationOpts: { numItems: 1, cursor: null },
34
+ });
35
+ expect(history).toMatchObject({ coverage: "unknown" });
36
+ if (!history.isDone) {
37
+ const end = await client.reversalObservations.history(ctx, {
38
+ selector: "sourceChargeId",
39
+ value: "ch_sdk_history",
40
+ paginationOpts: { numItems: 1, cursor: history.continueCursor },
41
+ });
42
+ expect(end).toMatchObject({ coverage: "unknown", isDone: true, page: [] });
43
+ }
44
+ expect(history.page).toHaveLength(1);
45
+ const operationId = history.page[0].originalOperationId;
46
+ let state = await client.reversalObservations.operation(ctx, { operationId });
47
+ for (let n = 0; n < 4 && state.observation?.status !== "complete"; n++)
48
+ state = await client.reversalObservations.resume(ctx, {
49
+ operationId,
50
+ expectedGeneration: state.observation!.generation,
51
+ batchSize: 1,
52
+ });
53
+ const page = await client.reversalObservations.bucket(ctx, {
54
+ bucketKey: "acct_sdk",
55
+ paginationOpts: { numItems: 1, cursor: null },
56
+ });
57
+ expect(page.page[0]).toMatchObject({
58
+ originalOperationId: operationId,
59
+ sliceIndex: 0,
60
+ });
61
+ const original = await client.reversalObservations.payload(ctx, {
62
+ operationId: page.page[0].originalOperationId,
63
+ version: "original",
64
+ });
65
+ expect(original.payload).toMatchObject({
66
+ operationId: "op_sdk_history",
67
+ sourceChargeId: "ch_sdk_history",
68
+ });
69
+ });
@@ -0,0 +1,151 @@
1
+ import type { PaginationResult } from "convex/server";
2
+ import type { Infer } from "convex/values";
3
+ import { z } from "zod";
4
+ import { PayoutRevisionMigrationHost } from "./payoutRevisionMigration.js";
5
+ import { runMutationOrThrow, type Component, type RunCtx } from "./helpers.js";
6
+ import { componentRef } from "./webhooks/helpers.js";
7
+ import { observationPagination } from "./observationPagination.js";
8
+ import type {
9
+ headerDoc,
10
+ sliceDoc,
11
+ payloadDoc,
12
+ } from "../component/reversalObservations/schema.js";
13
+ export type ReversalObservation = Infer<typeof headerDoc>;
14
+ export type ReversalObservationSlice = Infer<typeof sliceDoc>;
15
+ export type ReversalObservationPayload = Infer<typeof payloadDoc>;
16
+ export type ReversalObservationState = {
17
+ coverage: "unknown";
18
+ generation: number | null;
19
+ transferGeneration: number | null;
20
+ };
21
+ export type ReversalObservationResult = ReversalObservationState & {
22
+ observation: ReversalObservation | null;
23
+ };
24
+ export type ReversalObservationPage<T> = ReversalObservationState &
25
+ PaginationResult<T>;
26
+ type PageOptions = z.input<typeof observationPagination>;
27
+ const operationId = z.string().min(1).max(256);
28
+ /** Trusted host diagnostics only. History and indexed pages never authorize financial actions. */
29
+ export class ReversalObservationsClient {
30
+ constructor(private component: Component) {}
31
+ operation(
32
+ ctx: RunCtx,
33
+ input: { operationId: string },
34
+ ): Promise<ReversalObservationResult> {
35
+ const args = z.object({ operationId }).strict().parse(input);
36
+ return ctx.runQuery(
37
+ componentRef(this.component, "reversalObservations/queries/operation"),
38
+ args,
39
+ );
40
+ }
41
+ resume(
42
+ ctx: RunCtx,
43
+ input: {
44
+ operationId: string;
45
+ expectedGeneration: number;
46
+ batchSize?: number;
47
+ },
48
+ ): Promise<ReversalObservationResult> {
49
+ const args = z
50
+ .object({
51
+ operationId,
52
+ expectedGeneration: z
53
+ .number()
54
+ .int()
55
+ .min(1)
56
+ .max(Number.MAX_SAFE_INTEGER),
57
+ batchSize: z.number().int().min(1).max(20).optional(),
58
+ })
59
+ .strict()
60
+ .parse(input);
61
+ return runMutationOrThrow(
62
+ ctx,
63
+ componentRef(this.component, "reversalObservations/mutations/resume"),
64
+ args,
65
+ );
66
+ }
67
+ slices(
68
+ ctx: RunCtx,
69
+ input: { operationId: string; paginationOpts: PageOptions },
70
+ ): Promise<ReversalObservationPage<ReversalObservationSlice>> {
71
+ const args = z
72
+ .object({ operationId, paginationOpts: observationPagination })
73
+ .strict()
74
+ .parse(input);
75
+ return ctx.runQuery(
76
+ componentRef(this.component, "reversalObservations/queries/slices"),
77
+ args,
78
+ );
79
+ }
80
+ bucket(
81
+ ctx: RunCtx,
82
+ input: { bucketKey: string; paginationOpts: PageOptions },
83
+ ): Promise<ReversalObservationPage<ReversalObservationSlice>> {
84
+ const args = z
85
+ .object({ bucketKey: z.string(), paginationOpts: observationPagination })
86
+ .strict()
87
+ .parse(input);
88
+ return ctx.runQuery(
89
+ componentRef(this.component, "reversalObservations/queries/bucket"),
90
+ args,
91
+ );
92
+ }
93
+ owner(
94
+ ctx: RunCtx,
95
+ input: { userId: string; orgId?: string; paginationOpts: PageOptions },
96
+ ): Promise<ReversalObservationPage<ReversalObservationSlice>> {
97
+ const args = z
98
+ .object({
99
+ userId: z.string().min(1),
100
+ orgId: z.string().min(1).optional(),
101
+ paginationOpts: observationPagination,
102
+ })
103
+ .strict()
104
+ .parse(input);
105
+ return ctx.runQuery(
106
+ componentRef(this.component, "reversalObservations/queries/owner"),
107
+ args,
108
+ );
109
+ }
110
+ history(
111
+ ctx: RunCtx,
112
+ input: {
113
+ selector: "operationId" | "sourceChargeId";
114
+ value: string;
115
+ paginationOpts: PageOptions;
116
+ },
117
+ ): Promise<ReversalObservationPage<ReversalObservation>> {
118
+ const args = z
119
+ .object({
120
+ selector: z.enum(["operationId", "sourceChargeId"]),
121
+ value: z.string(),
122
+ paginationOpts: observationPagination,
123
+ })
124
+ .strict()
125
+ .parse(input);
126
+ return ctx.runQuery(
127
+ componentRef(this.component, "reversalObservations/queries/history"),
128
+ args,
129
+ );
130
+ }
131
+ payload(
132
+ ctx: RunCtx,
133
+ input: { operationId: string; version: "original" | "latest" },
134
+ ): Promise<
135
+ ReversalObservationState & { payload: ReversalObservationPayload | null }
136
+ > {
137
+ const args = z
138
+ .object({ operationId, version: z.enum(["original", "latest"]) })
139
+ .strict()
140
+ .parse(input);
141
+ return ctx.runQuery(
142
+ componentRef(this.component, "reversalObservations/queries/payload"),
143
+ args,
144
+ );
145
+ }
146
+ }
147
+ export abstract class ReversalObservationsHost extends PayoutRevisionMigrationHost {
148
+ readonly reversalObservations = new ReversalObservationsClient(
149
+ this.component,
150
+ );
151
+ }
@@ -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
+ };
@@ -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
+ };
@@ -113,8 +113,13 @@ import type * as payoutRelease_planning from "../payoutRelease/planning.js";
113
113
  import type * as payoutRelease_preview from "../payoutRelease/preview.js";
114
114
  import type * as payoutRelease_progress from "../payoutRelease/progress.js";
115
115
  import type * as payoutRelease_queries from "../payoutRelease/queries.js";
116
+ import type * as payoutRevisionJournal_mutations from "../payoutRevisionJournal/mutations.js";
117
+ import type * as payoutRevisionJournal_state from "../payoutRevisionJournal/state.js";
118
+ import type * as payoutRevisionMigration_mutations from "../payoutRevisionMigration/mutations.js";
119
+ import type * as payoutRevisionMigration_queries from "../payoutRevisionMigration/queries.js";
116
120
  import type * as payoutSnapshots_adoption from "../payoutSnapshots/adoption.js";
117
121
  import type * as payoutSnapshots_financial from "../payoutSnapshots/financial.js";
122
+ import type * as payoutSnapshots_legacyRevisionWriter from "../payoutSnapshots/legacyRevisionWriter.js";
118
123
  import type * as payoutSnapshots_liabilities from "../payoutSnapshots/liabilities.js";
119
124
  import type * as payoutSnapshots_localState from "../payoutSnapshots/localState.js";
120
125
  import type * as payoutSnapshots_mutations from "../payoutSnapshots/mutations.js";
@@ -158,6 +163,15 @@ import type * as refundSync_mutations from "../refundSync/mutations.js";
158
163
  import type * as refundSync_queries from "../refundSync/queries.js";
159
164
  import type * as refundSync_routing from "../refundSync/routing.js";
160
165
  import type * as refundSync_validators from "../refundSync/validators.js";
166
+ import type * as reversalObservations_capture from "../reversalObservations/capture.js";
167
+ import type * as reversalObservations_indexSlice from "../reversalObservations/indexSlice.js";
168
+ import type * as reversalObservations_integrity from "../reversalObservations/integrity.js";
169
+ import type * as reversalObservations_mutations from "../reversalObservations/mutations.js";
170
+ import type * as reversalObservations_pagination from "../reversalObservations/pagination.js";
171
+ import type * as reversalObservations_queries from "../reversalObservations/queries.js";
172
+ import type * as reversalObservations_references from "../reversalObservations/references.js";
173
+ import type * as reversalObservations_selectors from "../reversalObservations/selectors.js";
174
+ import type * as reversalObservations_state from "../reversalObservations/state.js";
161
175
  import type * as settlement_clawbackSchema from "../settlement/clawbackSchema.js";
162
176
  import type * as settlement_clawbacks from "../settlement/clawbacks.js";
163
177
  import type * as settlement_mutations from "../settlement/mutations.js";
@@ -317,8 +331,13 @@ const fullApi: ApiFromModules<{
317
331
  "payoutRelease/preview": typeof payoutRelease_preview;
318
332
  "payoutRelease/progress": typeof payoutRelease_progress;
319
333
  "payoutRelease/queries": typeof payoutRelease_queries;
334
+ "payoutRevisionJournal/mutations": typeof payoutRevisionJournal_mutations;
335
+ "payoutRevisionJournal/state": typeof payoutRevisionJournal_state;
336
+ "payoutRevisionMigration/mutations": typeof payoutRevisionMigration_mutations;
337
+ "payoutRevisionMigration/queries": typeof payoutRevisionMigration_queries;
320
338
  "payoutSnapshots/adoption": typeof payoutSnapshots_adoption;
321
339
  "payoutSnapshots/financial": typeof payoutSnapshots_financial;
340
+ "payoutSnapshots/legacyRevisionWriter": typeof payoutSnapshots_legacyRevisionWriter;
322
341
  "payoutSnapshots/liabilities": typeof payoutSnapshots_liabilities;
323
342
  "payoutSnapshots/localState": typeof payoutSnapshots_localState;
324
343
  "payoutSnapshots/mutations": typeof payoutSnapshots_mutations;
@@ -362,6 +381,15 @@ const fullApi: ApiFromModules<{
362
381
  "refundSync/queries": typeof refundSync_queries;
363
382
  "refundSync/routing": typeof refundSync_routing;
364
383
  "refundSync/validators": typeof refundSync_validators;
384
+ "reversalObservations/capture": typeof reversalObservations_capture;
385
+ "reversalObservations/indexSlice": typeof reversalObservations_indexSlice;
386
+ "reversalObservations/integrity": typeof reversalObservations_integrity;
387
+ "reversalObservations/mutations": typeof reversalObservations_mutations;
388
+ "reversalObservations/pagination": typeof reversalObservations_pagination;
389
+ "reversalObservations/queries": typeof reversalObservations_queries;
390
+ "reversalObservations/references": typeof reversalObservations_references;
391
+ "reversalObservations/selectors": typeof reversalObservations_selectors;
392
+ "reversalObservations/state": typeof reversalObservations_state;
365
393
  "settlement/clawbackSchema": typeof settlement_clawbackSchema;
366
394
  "settlement/clawbacks": typeof settlement_clawbacks;
367
395
  "settlement/mutations": typeof settlement_mutations;