@fantastic.dev/better-stripe 0.32.0 → 0.34.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 (129) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +36 -1
  3. package/dist/client/billing/checkoutPages.d.ts +26 -0
  4. package/dist/client/billing/checkoutPages.d.ts.map +1 -0
  5. package/dist/client/billing/checkoutPages.js +111 -0
  6. package/dist/client/billing/checkoutPages.js.map +1 -0
  7. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +36 -0
  8. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +18 -0
  10. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  11. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +36 -0
  12. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  13. package/dist/client/connect/payoutSyncTestHelpers.d.ts +18 -0
  14. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  15. package/dist/client/connect/refundContext.d.ts +6 -0
  16. package/dist/client/connect/refundContext.d.ts.map +1 -0
  17. package/dist/client/connect/refundContext.js +109 -0
  18. package/dist/client/connect/refundContext.js.map +1 -0
  19. package/dist/client/connect/refundContextHistory.d.ts +20 -0
  20. package/dist/client/connect/refundContextHistory.d.ts.map +1 -0
  21. package/dist/client/connect/refundContextHistory.js +55 -0
  22. package/dist/client/connect/refundContextHistory.js.map +1 -0
  23. package/dist/client/connect/refundContextTypes.d.ts +39 -0
  24. package/dist/client/connect/refundContextTypes.d.ts.map +1 -0
  25. package/dist/client/connect/refundContextTypes.js +15 -0
  26. package/dist/client/connect/refundContextTypes.js.map +1 -0
  27. package/dist/client/connect/refundTarget.d.ts +14 -0
  28. package/dist/client/connect/refundTarget.d.ts.map +1 -0
  29. package/dist/client/connect/refundTarget.js +17 -0
  30. package/dist/client/connect/refundTarget.js.map +1 -0
  31. package/dist/client/connect/refunds.d.ts +17 -1
  32. package/dist/client/connect/refunds.d.ts.map +1 -1
  33. package/dist/client/connect/refunds.js +7 -17
  34. package/dist/client/connect/refunds.js.map +1 -1
  35. package/dist/client/core/accountClosures.d.ts +15 -0
  36. package/dist/client/core/accountClosures.d.ts.map +1 -0
  37. package/dist/client/core/accountClosures.js +10 -0
  38. package/dist/client/core/accountClosures.js.map +1 -0
  39. package/dist/client/core/accounts.d.ts.map +1 -1
  40. package/dist/client/core/accounts.js +15 -23
  41. package/dist/client/core/accounts.js.map +1 -1
  42. package/dist/client/core/personalAccountMapping.d.ts +8 -0
  43. package/dist/client/core/personalAccountMapping.d.ts.map +1 -0
  44. package/dist/client/core/personalAccountMapping.js +11 -0
  45. package/dist/client/core/personalAccountMapping.js.map +1 -0
  46. package/dist/client/index.d.ts +57 -2
  47. package/dist/client/index.d.ts.map +1 -1
  48. package/dist/client/index.js +13 -0
  49. package/dist/client/index.js.map +1 -1
  50. package/dist/client/invoiceReads.d.ts +7 -1
  51. package/dist/client/invoiceReads.d.ts.map +1 -1
  52. package/dist/client/invoiceReads.js +11 -1
  53. package/dist/client/invoiceReads.js.map +1 -1
  54. package/dist/client/publicTypes.d.ts +5 -0
  55. package/dist/client/publicTypes.d.ts.map +1 -0
  56. package/dist/client/publicTypes.js +2 -0
  57. package/dist/client/publicTypes.js.map +1 -0
  58. package/dist/component/_generated/component.d.ts +88 -0
  59. package/dist/component/_generated/component.d.ts.map +1 -1
  60. package/dist/component/accountClosure/helpers.d.ts +18 -0
  61. package/dist/component/accountClosure/helpers.d.ts.map +1 -0
  62. package/dist/component/accountClosure/helpers.js +18 -0
  63. package/dist/component/accountClosure/helpers.js.map +1 -0
  64. package/dist/component/accountClosure/mutations.d.ts +20 -0
  65. package/dist/component/accountClosure/mutations.d.ts.map +1 -0
  66. package/dist/component/accountClosure/mutations.js +55 -0
  67. package/dist/component/accountClosure/mutations.js.map +1 -0
  68. package/dist/component/accountClosure/queries.d.ts +34 -0
  69. package/dist/component/accountClosure/queries.d.ts.map +1 -0
  70. package/dist/component/accountClosure/queries.js +36 -0
  71. package/dist/component/accountClosure/queries.js.map +1 -0
  72. package/dist/component/accountClosure/schema.d.ts +46 -0
  73. package/dist/component/accountClosure/schema.d.ts.map +1 -0
  74. package/dist/component/accountClosure/schema.js +20 -0
  75. package/dist/component/accountClosure/schema.js.map +1 -0
  76. package/dist/component/core/mutations.d.ts.map +1 -1
  77. package/dist/component/core/mutations.js +5 -0
  78. package/dist/component/core/mutations.js.map +1 -1
  79. package/dist/component/core/personalAccountMapping.d.ts +95 -0
  80. package/dist/component/core/personalAccountMapping.d.ts.map +1 -0
  81. package/dist/component/core/personalAccountMapping.js +54 -0
  82. package/dist/component/core/personalAccountMapping.js.map +1 -0
  83. package/dist/component/core/queries.d.ts +27 -0
  84. package/dist/component/core/queries.d.ts.map +1 -1
  85. package/dist/component/core/queries.js +7 -0
  86. package/dist/component/core/queries.js.map +1 -1
  87. package/dist/component/earnings/triggers.d.ts +42 -0
  88. package/dist/component/earnings/triggers.d.ts.map +1 -1
  89. package/dist/component/payoutRelease/queries.d.ts +2 -2
  90. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  91. package/dist/component/schema.d.ts +18 -0
  92. package/dist/component/schema.js +2 -0
  93. package/dist/component/schema.js.map +1 -1
  94. package/docs/checkout-session-pages.md +71 -0
  95. package/docs/personal-account-mapping.md +54 -0
  96. package/docs/read-contracts.md +28 -0
  97. package/docs/refund-context.md +84 -0
  98. package/package.json +5 -2
  99. package/src/client/billing/checkoutPages.test.ts +251 -0
  100. package/src/client/billing/checkoutPages.ts +135 -0
  101. package/src/client/connect/refundContext.ts +140 -0
  102. package/src/client/connect/refundContextHistory.ts +84 -0
  103. package/src/client/connect/refundContextTypes.ts +56 -0
  104. package/src/client/connect/refundTarget.ts +39 -0
  105. package/src/client/connect/refunds.test.ts +72 -0
  106. package/src/client/connect/refunds.ts +8 -22
  107. package/src/client/core/account-close-orchestration.test.ts +131 -0
  108. package/src/client/core/account-closure.test.ts +317 -0
  109. package/src/client/core/accountClosures.ts +37 -0
  110. package/src/client/core/accounts.test.ts +0 -111
  111. package/src/client/core/accounts.ts +24 -29
  112. package/src/client/core/personal-account-mapping.test.ts +71 -0
  113. package/src/client/core/personalAccountMapping.ts +23 -0
  114. package/src/client/index.ts +45 -33
  115. package/src/client/invoiceReads.ts +17 -1
  116. package/src/client/publicTypes.ts +35 -0
  117. package/src/client/refund-context-shapes.test.ts +127 -0
  118. package/src/client/refund-context.test.ts +404 -0
  119. package/src/component/_generated/api.ts +8 -0
  120. package/src/component/_generated/component.ts +126 -0
  121. package/src/component/accountClosure/helpers.ts +21 -0
  122. package/src/component/accountClosure/mutations.ts +56 -0
  123. package/src/component/accountClosure/queries.ts +43 -0
  124. package/src/component/accountClosure/schema.ts +20 -0
  125. package/src/component/core/mutations.ts +3 -0
  126. package/src/component/core/personal-account-mapping.test.ts +173 -0
  127. package/src/component/core/personalAccountMapping.ts +81 -0
  128. package/src/component/core/queries.ts +11 -0
  129. package/src/component/schema.ts +2 -0
@@ -1,4 +1,25 @@
1
1
  export declare const mutation: import("convex-helpers/server/customFunctions").CustomBuilder<"mutation", Record<string, never>, import("convex/server").GenericMutationCtx<{
2
+ accountClosures: {
3
+ document: {
4
+ _creationTime: number;
5
+ _id: import("convex/values").GenericId<"accountClosures">;
6
+ appliedConfigurations?: ("customer" | "merchant" | "recipient")[] | undefined;
7
+ closedAt?: number | undefined;
8
+ orgId?: string | undefined;
9
+ state: "closed" | "pending";
10
+ stripeAccountId: string;
11
+ userId?: string | undefined;
12
+ };
13
+ fieldPaths: "_id" | ("_creationTime" | "appliedConfigurations" | "closedAt" | "orgId" | "state" | "stripeAccountId" | "userId");
14
+ indexes: {
15
+ by_id: ["_id"];
16
+ by_creation_time: ["_creationTime"];
17
+ by_stripe_account_id: ["stripeAccountId", "_creationTime"];
18
+ by_user_state: ["userId", "orgId", "state", "_creationTime"];
19
+ };
20
+ searchIndexes: {};
21
+ vectorIndexes: {};
22
+ };
2
23
  accounts: {
3
24
  document: {
4
25
  _creationTime: number;
@@ -1284,6 +1305,27 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
1284
1305
  vectorIndexes: {};
1285
1306
  };
1286
1307
  }>, Record<string, never>, import("convex/server").GenericMutationCtx<{
1308
+ accountClosures: {
1309
+ document: {
1310
+ _creationTime: number;
1311
+ _id: import("convex/values").GenericId<"accountClosures">;
1312
+ appliedConfigurations?: ("customer" | "merchant" | "recipient")[] | undefined;
1313
+ closedAt?: number | undefined;
1314
+ orgId?: string | undefined;
1315
+ state: "closed" | "pending";
1316
+ stripeAccountId: string;
1317
+ userId?: string | undefined;
1318
+ };
1319
+ fieldPaths: "_id" | ("_creationTime" | "appliedConfigurations" | "closedAt" | "orgId" | "state" | "stripeAccountId" | "userId");
1320
+ indexes: {
1321
+ by_id: ["_id"];
1322
+ by_creation_time: ["_creationTime"];
1323
+ by_stripe_account_id: ["stripeAccountId", "_creationTime"];
1324
+ by_user_state: ["userId", "orgId", "state", "_creationTime"];
1325
+ };
1326
+ searchIndexes: {};
1327
+ vectorIndexes: {};
1328
+ };
1287
1329
  accounts: {
1288
1330
  document: {
1289
1331
  _creationTime: number;
@@ -1 +1 @@
1
- {"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../../src/component/earnings/triggers.ts"],"names":[],"mappings":"AAiGA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAA0D,CAAC"}
1
+ {"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../../src/component/earnings/triggers.ts"],"names":[],"mappings":"AAiGA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAA0D,CAAC"}
@@ -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
- status: "held";
167
- reason: "snapshot_limit";
168
166
  transfers?: undefined;
169
167
  claims?: undefined;
168
+ status: "held";
169
+ reason: "snapshot_limit";
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"}
@@ -1140,6 +1140,24 @@ declare const _default: import("convex/server").SchemaDefinition<{
1140
1140
  by_stripe_account_id: ["stripeAccountId", "_creationTime"];
1141
1141
  by_user_id: ["userId", "_creationTime"];
1142
1142
  }, {}, {}>;
1143
+ accountClosures: import("convex/server").TableDefinition<import("convex/values").VObject<{
1144
+ appliedConfigurations?: ("customer" | "merchant" | "recipient")[] | undefined;
1145
+ closedAt?: number | undefined;
1146
+ orgId?: string | undefined;
1147
+ state: "closed" | "pending";
1148
+ stripeAccountId: string;
1149
+ userId?: string | undefined;
1150
+ }, {
1151
+ stripeAccountId: import("convex/values").VString<string, "required">;
1152
+ userId: import("convex/values").VString<string | undefined, "optional">;
1153
+ orgId: import("convex/values").VString<string | undefined, "optional">;
1154
+ appliedConfigurations: import("convex/values").VArray<("customer" | "merchant" | "recipient")[] | undefined, import("convex/values").VUnion<"customer" | "merchant" | "recipient", [import("convex/values").VLiteral<"customer", "required">, import("convex/values").VLiteral<"merchant", "required">, import("convex/values").VLiteral<"recipient", "required">], "required", never>, "optional">;
1155
+ state: import("convex/values").VUnion<"closed" | "pending", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"closed", "required">], "required", never>;
1156
+ closedAt: import("convex/values").VFloat64<number | undefined, "optional">;
1157
+ }, "required", "appliedConfigurations" | "closedAt" | "orgId" | "state" | "stripeAccountId" | "userId">, {
1158
+ by_stripe_account_id: ["stripeAccountId", "_creationTime"];
1159
+ by_user_state: ["userId", "orgId", "state", "_creationTime"];
1160
+ }, {}, {}>;
1143
1161
  products: import("convex/server").TableDefinition<import("convex/values").VObject<{
1144
1162
  accountId?: string | undefined;
1145
1163
  active: boolean;
@@ -1,3 +1,4 @@
1
+ import { accountClosuresTable } from "./accountClosure/schema.js";
1
2
  import { jobsTable as payoutWorkerJobsTable } from "./payoutWorker/schema.js";
2
3
  import { financialRevisionsTable, riskEventsTable, riskRevisionsTable, snapshotsTable, snapshotSourcesTable, snapshotClaimsTable, snapshotFeesTable, } from "./payoutSnapshots/schema.js";
3
4
  import { claimsTable as payoutSyncClaimsTable } from "./payoutSync/schema.js";
@@ -46,6 +47,7 @@ export default defineSchema({
46
47
  commissionDecisions: commissionDecisionsTable,
47
48
  // Core
48
49
  accounts: accountsTable,
50
+ accountClosures: accountClosuresTable,
49
51
  // Products
50
52
  products: productsTable,
51
53
  prices: pricesTable,
@@ -1 +1 @@
1
- {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,71 @@
1
+ # Buyer Checkout-session provider pages
2
+
3
+ `BetterStripe.getCheckoutSessionPageFromStripe` discovers one bounded page of
4
+ actual provider Checkout sessions for a V2 buyer account. It complements invoice
5
+ pages: an open or asynchronous Checkout can exist before any invoice exists.
6
+ This reader performs no provider write, component synchronization, commission
7
+ award or settlement operation.
8
+
9
+ ```ts
10
+ import type {
11
+ CheckoutSessionPageOptions,
12
+ ProviderCheckoutSessionPage,
13
+ } from "@fantastic.dev/better-stripe";
14
+
15
+ // Obtain the personal buyer account from authenticated host-owned mapping.
16
+ const options: CheckoutSessionPageOptions = {
17
+ customerAccount: authorizedBuyerAccount,
18
+ limit: 25,
19
+ cursor: previousPage?.continueCursor,
20
+ };
21
+ const result: ProviderCheckoutSessionPage =
22
+ await stripe.getCheckoutSessionPageFromStripe(ctx, options);
23
+ ```
24
+
25
+ The server-only Vite reference is
26
+ `example/convex/billing/checkoutHistory.ts`. Its buyer identity must come from
27
+ host authentication. The demonstration's browser personas are not production
28
+ authorization. It obtains the personal account from the component, rejects
29
+ missing, foreign or organization mappings, and overrides any browser-supplied
30
+ account selector. Existing React `Checkout` workflows remain responsible for
31
+ checkout presentation; hosts such as Dojo retain their own styles and routing.
32
+
33
+ ## Selectors and results
34
+
35
+ - `customerAccount` must be a V2 `acct_…` identifier. Legacy customer selectors
36
+ and arbitrary provider parameters are rejected.
37
+ - Optional `status` is `open`, `complete` or `expired`. Omit it when discovering
38
+ all lifecycle states. Paid-only invoice discovery cannot find unresolved
39
+ Checkouts with no invoice.
40
+ - Optional `created.gte` and `created.lte` are inclusive integer Unix seconds.
41
+ An empty range object is normalized away. Creation time is not payment time;
42
+ an older session can complete or become paid during a later membership episode.
43
+ - `limit` defaults to 25 and must be an integer from 1 to 100. It may change
44
+ between pages. `cursor` is opaque and bound to buyer, status and creation range.
45
+ It is a continuation selector, not a signed authorization token.
46
+ - Results contain `page`, `hasMore` and `continueCursor`. Raw lifecycle values,
47
+ metadata, original currency/amount units and expanded subscription/payment
48
+ references are preserved. A complete session, payment reference or amount is
49
+ not independently proof of payment, refundable proceeds or affiliate credit.
50
+
51
+ The reader validates buyer/resource identity and selected status/time filters.
52
+ It rejects oversized pages, duplicate IDs within a page, a repeated immediately
53
+ preceding continuation ID, and empty nonterminal pages. Provider failures
54
+ propagate instead of becoming empty successful history.
55
+
56
+ ## Host reconciliation
57
+
58
+ These are mutable provider pages, not an atomic snapshot or a complete-history
59
+ attestation. A stateless cursor cannot remember every earlier page. Hosts must
60
+ retain bounded durable checkpoints and seen IDs, detect cross-page overlap,
61
+ cycles and reordered/new records, and revalidate canonical buyer, community,
62
+ episode and registered request lineage before making a business decision.
63
+
64
+ An exhausted page alone does not prove absence. Missing/unregistered provenance,
65
+ unmapped references, incomplete scans, truncated related-resource previews,
66
+ unsupported lifecycle states and unresolved asynchronous attempts remain
67
+ unknown. Provider retention does not prove historical absence. Reconcile
68
+ actual supported session, subscription and invoice reads with immutable trusted
69
+ paid facts. Guard provider-read/database races and same-second ordering; do not
70
+ replace historical payment time with event arrival or deployment dates. This
71
+ reader does not fill referral locks or change already settled awards.
@@ -0,0 +1,54 @@
1
+ # Unambiguous personal account mappings
2
+
3
+ `stripe.getPersonalAccountMapping(ctx, { userId })` reads component identity
4
+ mappings without contacting Stripe. It returns the exported
5
+ `PersonalAccountMapping` discriminated union:
6
+
7
+ - `status: "unique"` includes the original account document.
8
+ - `status: "unavailable"` includes `missing`, `ambiguous`, `organization`,
9
+ `invalid_account`, `closure_unresolved` or `closed` as its reason.
10
+
11
+ The required user selector is exact, nonempty, at most 256 characters and free of
12
+ ASCII control characters. Extra SDK options are rejected before component reads.
13
+ A successful result requires exactly one user-index match, no organization field
14
+ (including an empty organization ID), a canonical `acct_` identifier of at most
15
+ 128 characters and exactly one reciprocal Stripe-account-index match pointing
16
+ to the same document. Each index read takes at most two rows. A candidate's
17
+ closure index also takes at most two rows: duplicate closure provenance, pending
18
+ closure or terminal closure makes that candidate unavailable. At most six rows
19
+ are read; there is no whole-table scan, provider read or financial write.
20
+
21
+ Two records for one user are ambiguous even when the older record was inserted
22
+ first, or one record belongs to an organization. The reader neither selects the
23
+ newest account nor migrates ownership or funds. It preserves the existing
24
+ `getAccountByUserId`, `getAccountByStripeId` and organization getters for consumers
25
+ that depend on their legacy behavior. Do not use those first-match getters as
26
+ proof of unique personal ownership.
27
+
28
+ Authenticate and authorize the enabled host actor before deriving `userId` on
29
+ the server. User IDs supplied by the browser or a Vite demo persona do not prove
30
+ authentication. For a refund, derive the original merchant from verified payment
31
+ routing first, then compare that original identifier to the unique mapping for
32
+ the authorized owner. A community ownership transfer cannot remap an old
33
+ merchant's payment to its new owner. Unknown or ambiguous mappings must remain
34
+ unavailable.
35
+
36
+ The matching Vite server binding is
37
+ [`requireOriginalPersonalAccount`](../example/convex/billing/personalAccountMapping.ts).
38
+ It takes an already-authenticated server identity and the server-verified original
39
+ account identifier, rejects a different owner, organization or replacement
40
+ account, and forwards component errors. It is a reference adapter, not a session
41
+ authentication implementation. A production host supplies its real session,
42
+ tenant authorization and immutable payment provenance.
43
+
44
+ Component mutations can reuse `resolvePersonalAccountMapping` from
45
+ `src/component/core/personalAccountMapping.ts` in their transaction; mutation
46
+ contexts satisfy its query-context database interface. This avoids duplicating
47
+ the reciprocal and closure checks when admitting an ownership binding.
48
+
49
+ A unique component mapping is identity evidence at the time of the read. It does
50
+ not prove provider freshness, merchant capabilities, settlement eligibility,
51
+ available balance or permission to create a refund. Original invoice allocation,
52
+ buyer, currency, charge, refund history and creation-time revalidation remain
53
+ separate requirements. Closed-account history uses the dedicated historical
54
+ provenance APIs; this reader never revives a closed account.
@@ -294,3 +294,31 @@ Invoice allocations are not the PaymentIntent's remaining refundable balance.
294
294
  The host authorizes the actual session, verifies original merchant and sale scope,
295
295
  and revalidates creation-time eligibility through the existing refund APIs. This
296
296
  reader writes no financial records and changes no access or subscription state.
297
+
298
+ ## Provider Checkout-session pages
299
+
300
+ `getCheckoutSessionPageFromStripe(ctx, { customerAccount, status?, created?,
301
+ limit?, cursor? })` discovers actual V2 buyer Checkout sessions, including open
302
+ or asynchronous sessions that have no invoice yet. It preserves raw lifecycle,
303
+ metadata and payment/subscription references and performs no synchronization or
304
+ financial write. The server-only Vite adapter derives its account from the
305
+ host-authorized personal buyer mapping.
306
+
307
+ See [Checkout-session discovery](./checkout-session-pages.md) for public types,
308
+ scope-bound continuation, response validation and host obligations. Within-page
309
+ duplicates and immediately repeated continuation IDs reject; cross-page overlap
310
+ requires host checkpoints and seen-ID reconciliation. Neither an exhausted page
311
+ nor a complete Checkout status proves historical absence or payment. Unknown
312
+ provenance, mutable provider states and provider-read/database races remain host
313
+ responsibilities before any referral qualification or award.
314
+
315
+ ## Refund context
316
+
317
+ `getRefundContext(ctx, { stripePaymentIntentId, actor, maxRefundPages?,
318
+ stripeAccountId? })` observes the authorized original captured charge and complete
319
+ bounded refund history. It returns a ready original-currency remainder or an
320
+ explicit unavailable reason, and propagates provider failures. Required actors,
321
+ partial-capture units, history budgets and creation-time host obligations are
322
+ specified in [refund context](./refund-context.md). Invoice allocations and
323
+ authorized gross amounts are not remaining refundable principal. No access,
324
+ subscription or financial state is changed by this reader.
@@ -0,0 +1,84 @@
1
+ # Refund context observation
2
+
3
+ `BetterStripe.getRefundContext(ctx, options)` reads one original PaymentIntent,
4
+ its captured charge and a bounded refund history after actor authorization. It
5
+ performs no provider write, component synchronization, transfer reversal or
6
+ access/subscription change. It complements the existing public React `Refunds`
7
+ review workflow; no additional renderer is required.
8
+
9
+ ```ts
10
+ const context = await stripe.getRefundContext(ctx, {
11
+ stripePaymentIntentId: originalPayment.stripePaymentIntentId,
12
+ actor: { type: "seller", accountId: originalMerchantAccount },
13
+ maxRefundPages: 5,
14
+ });
15
+ if (context.status === "ready") {
16
+ // Original currency minor units; revalidate before creating the refund.
17
+ const remaining = context.remainingRefundableAmount;
18
+ }
19
+ ```
20
+
21
+ ## Authority and original scope
22
+
23
+ The required `actor` is either `{ type: "seller", accountId }` or
24
+ `{ type: "admin" }`. Runtime validation rejects missing or malformed actors and
25
+ noncanonical `pi_`/`acct_` selectors before component or provider reads. Sellers
26
+ must own the original destination or `store` split leg; affiliate and collaborator
27
+ legs do not confer refund authority. Admin authority must be established by the
28
+ host. The legacy optional actor on `createRefund` is not inherited by this reader.
29
+
30
+ The original synchronized payment must exist. Its V2 buyer account is correlated
31
+ with the live PaymentIntent; the original currency, PaymentIntent, latest charge
32
+ and charge's PaymentIntent reference must agree. Nullable legacy customer
33
+ references must also be canonical and agree; they do not replace the V2 buyer.
34
+ Malformed provider objects or contradictory lifecycle flags cannot produce a
35
+ ready result. A disputed, uncaptured or zero-captured charge is unavailable.
36
+
37
+ `stripeAccountId`, when supplied, is a **server-owned provider request scope**,
38
+ not the buyer account or merchant identity. Derive it from the original payment's
39
+ known charge context. Never accept it or the actor from browser input. The Vite
40
+ server-only `example/convex/connect/refundContext.ts` reference intentionally
41
+ supports platform charges only, derives the personal seller mapping and verifies
42
+ original merchant ownership. Demo personas still require real authentication in
43
+ a production host; the helper registers no public endpoint.
44
+
45
+ ## Result and units
46
+
47
+ Public types are `RefundContextOptions`, `RefundContext` and
48
+ `RefundContextUnavailableReason`. A ready result contains `stripePaymentIntentId`,
49
+ `stripeChargeId`, `customerAccount`, `currency`, `capturedAmount`, `refundedAmount`,
50
+ `remainingRefundableAmount` and `observedAt` (milliseconds).
51
+
52
+ Amounts remain safe integer minor units in the original currency; no conversion
53
+ or fixed two-decimal assumption is applied. `capturedAmount` comes from
54
+ `charge.amount_captured`, checked against `paymentIntent.amount_received`.
55
+ Authorized `paymentIntent.amount`, `charge.amount` and synchronized payment
56
+ amount can exceed a partial capture and are not refund limits. `refundedAmount`
57
+ is the complete succeeded-refund total, reconciled with `charge.amount_refunded`.
58
+ The full-refund flag must agree in both directions with whether that total equals
59
+ captured principal. The remaining amount is captured principal minus that total. Dispute principal,
60
+ processing fees, balance transactions and invoice allocations are not subtracted
61
+ or substituted into this calculation.
62
+
63
+ An unavailable result has only `{ status: "unavailable", reason }`, with no
64
+ invented zero balance. Provider failures reject with their original identity so
65
+ callers can retry rather than present a completed observation.
66
+
67
+ ## Bounded completeness and host obligations
68
+
69
+ Each refund page is requested explicitly with limit 100. `maxRefundPages` defaults
70
+ to 5 and accepts integers 1–10. Every observed row must have a canonical refund
71
+ identity, matching charge, PaymentIntent and currency, and a known lifecycle.
72
+ Pending or requires-action refunds block ready; failed/canceled refunds do not
73
+ count as returned principal. Unknown states, malformed or oversized envelopes,
74
+ duplicate IDs anywhere in the bounded traversal, exhausted nonterminal pages,
75
+ unsafe amounts and counter disagreements return unavailable.
76
+
77
+ `observedAt` is an observation, not a reservation or immutable snapshot. Hosts
78
+ must authenticate the actual session, authorize tenant/community and original
79
+ merchant scope, and revalidate immediately before `createRefund`. Invoice
80
+ `amount_paid` is allocated principal for that invoice, not the whole
81
+ PaymentIntent's refund authority. Deny ambiguous cross-invoice/community scopes
82
+ until a safe original-payment binding is established. A ready zero remainder
83
+ must not enable another refund. This reader does not grant authority to remove
84
+ access, cancel a subscription or change the original financial recipients.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.32.0",
3
+ "version": "0.34.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -65,7 +65,10 @@
65
65
  "CHANGELOG.md",
66
66
  "MIGRATION.md",
67
67
  "docs/read-contracts.md",
68
- "docs/invoice-payment-pages.md"
68
+ "docs/invoice-payment-pages.md",
69
+ "docs/checkout-session-pages.md",
70
+ "docs/refund-context.md",
71
+ "docs/personal-account-mapping.md"
69
72
  ],
70
73
  "scripts": {
71
74
  "build": "tsc --project ./tsconfig.build.json",
@@ -0,0 +1,251 @@
1
+ import { afterEach, expect, it, vi } from "vitest";
2
+ import { BetterStripe } from "../index.js";
3
+ import { getStripeClient } from "../helpers.js";
4
+
5
+ afterEach(() => vi.restoreAllMocks());
6
+
7
+ function fixture() {
8
+ const key = `sk_test_checkout_page_${crypto.randomUUID()}`;
9
+ const client = new BetterStripe({} as never, { STRIPE_SECRET_KEY: key });
10
+ const list = vi.spyOn(getStripeClient(key).checkout.sessions, "list");
11
+ const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
12
+ const session = (id: string, customerAccount = "acct_buyer") => ({
13
+ id,
14
+ object: "checkout.session",
15
+ customer_account: customerAccount,
16
+ customer: null,
17
+ status: "open",
18
+ payment_status: "unpaid",
19
+ mode: "subscription",
20
+ created: 100,
21
+ metadata: { dojoPurchaseIntentId: "intent_original" },
22
+ subscription: null,
23
+ payment_intent: null,
24
+ });
25
+ return {
26
+ client,
27
+ list,
28
+ ctx,
29
+ session,
30
+ opts: { customerAccount: "acct_buyer" },
31
+ };
32
+ }
33
+
34
+ it("reads a bounded public V2 buyer Checkout page without syncing or claiming completeness", async () => {
35
+ const f = fixture();
36
+ const row = f.session("cs_test_original");
37
+ f.list.mockResolvedValue({ data: [row], has_more: false } as never);
38
+ expect(f.client.getCheckoutSessionPageFromStripe).toEqual(
39
+ expect.any(Function),
40
+ );
41
+ const result = await f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts);
42
+ expect(f.list).toHaveBeenCalledExactlyOnceWith({
43
+ customer_account: "acct_buyer",
44
+ limit: 25,
45
+ });
46
+ expect(result).toEqual({ page: [row], hasMore: false, continueCursor: null });
47
+ expect(result.page[0]).toBe(row);
48
+ expect(f.ctx.runQuery).not.toHaveBeenCalled();
49
+ expect(f.ctx.runMutation).not.toHaveBeenCalled();
50
+ });
51
+
52
+ it("resumes with canonical filters while allowing a different bounded page size", async () => {
53
+ const f = fixture();
54
+ f.list
55
+ .mockResolvedValueOnce({
56
+ data: [f.session("cs_newer")],
57
+ has_more: true,
58
+ } as never)
59
+ .mockResolvedValueOnce({
60
+ data: [f.session("cs_older")],
61
+ has_more: false,
62
+ } as never);
63
+ const first = await f.client.getCheckoutSessionPageFromStripe(f.ctx, {
64
+ ...f.opts,
65
+ status: "open",
66
+ created: { lte: 200, gte: 0 },
67
+ limit: 1,
68
+ });
69
+ expect(first.continueCursor).toEqual(expect.any(String));
70
+ const next = await f.client.getCheckoutSessionPageFromStripe(f.ctx, {
71
+ ...f.opts,
72
+ status: "open",
73
+ created: { gte: 0, lte: 200 },
74
+ limit: 2,
75
+ cursor: first.continueCursor,
76
+ });
77
+ expect(f.list).toHaveBeenLastCalledWith({
78
+ customer_account: "acct_buyer",
79
+ status: "open",
80
+ created: { gte: 0, lte: 200 },
81
+ limit: 2,
82
+ starting_after: "cs_newer",
83
+ });
84
+ expect(next).toEqual({
85
+ page: [f.session("cs_older")],
86
+ hasMore: false,
87
+ continueCursor: null,
88
+ });
89
+ });
90
+
91
+ it.each([
92
+ { customerAccount: "acct_foreign" },
93
+ { status: "expired" as const },
94
+ { created: { lte: 201 } },
95
+ { created: undefined },
96
+ ])(
97
+ "rejects continuation filter mutation before provider I/O %#",
98
+ async (change) => {
99
+ const f = fixture();
100
+ f.list.mockResolvedValue({
101
+ data: [f.session("cs_original")],
102
+ has_more: true,
103
+ } as never);
104
+ const opts = { ...f.opts, status: "open" as const, created: { lte: 200 } };
105
+ const first = await f.client.getCheckoutSessionPageFromStripe(f.ctx, opts);
106
+ f.list.mockClear();
107
+ await expect(
108
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, {
109
+ ...opts,
110
+ ...change,
111
+ cursor: first.continueCursor,
112
+ }),
113
+ ).rejects.toThrow(/cursor|scope/i);
114
+ expect(f.list).not.toHaveBeenCalled();
115
+ },
116
+ );
117
+
118
+ it.each([
119
+ { customerAccount: "cus_legacy" },
120
+ { customerAccount: "acct_" },
121
+ { limit: 0 },
122
+ { limit: 101 },
123
+ { limit: 1.5 },
124
+ { status: "paid" },
125
+ { created: { gte: 2, lte: 1 } },
126
+ { created: { gte: -1 } },
127
+ { customer: "cus_legacy" },
128
+ { cursor: "" },
129
+ { cursor: "not a cursor" },
130
+ ])(
131
+ "rejects invalid public selectors before provider I/O %#",
132
+ async (change) => {
133
+ const f = fixture();
134
+ await expect(
135
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, {
136
+ ...f.opts,
137
+ ...change,
138
+ } as never),
139
+ ).rejects.toThrow();
140
+ expect(f.list).not.toHaveBeenCalled();
141
+ },
142
+ );
143
+
144
+ it.each([
145
+ { customer_account: "acct_foreign" },
146
+ { customer_account: undefined },
147
+ { customer: "cus_legacy" },
148
+ { id: "in_wrong_resource" },
149
+ { object: "invoice" },
150
+ { created: -1 },
151
+ ])("rejects invalid provider buyer/resource identity %#", async (change) => {
152
+ const f = fixture();
153
+ f.list.mockResolvedValue({
154
+ data: [{ ...f.session("cs_original"), ...change }],
155
+ has_more: false,
156
+ } as never);
157
+ await expect(
158
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts),
159
+ ).rejects.toThrow(/scope|identity/i);
160
+ });
161
+
162
+ it.each([{ status: "expired" }, { created: 99 }, { created: 201 }])(
163
+ "rejects a provider response outside the selected filters %#",
164
+ async (change) => {
165
+ const f = fixture();
166
+ f.list.mockResolvedValue({
167
+ data: [{ ...f.session("cs_original"), ...change }],
168
+ has_more: false,
169
+ } as never);
170
+ await expect(
171
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, {
172
+ ...f.opts,
173
+ status: "open",
174
+ created: { gte: 100, lte: 200 },
175
+ }),
176
+ ).rejects.toThrow(/scope|identity/i);
177
+ },
178
+ );
179
+
180
+ it("preserves unknown lifecycle and raw expanded references without treating them as payment proof", async () => {
181
+ const f = fixture();
182
+ const row = {
183
+ ...f.session("cs_async"),
184
+ status: "future_provider_state",
185
+ payment_status: "unpaid",
186
+ currency: "kwd",
187
+ amount_total: 1234,
188
+ subscription: { id: "sub_original", status: "incomplete" },
189
+ payment_intent: { id: "pi_original", status: "processing" },
190
+ invoice: null,
191
+ metadata: { communityId: "community_original" },
192
+ };
193
+ f.list.mockResolvedValue({ data: [row], has_more: false } as never);
194
+ const result = await f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts);
195
+ expect(result.page[0]).toBe(row);
196
+ expect(result).not.toHaveProperty("completeHistory");
197
+ });
198
+
199
+ it("rejects oversized, duplicate and nonadvancing provider pages", async () => {
200
+ const f = fixture();
201
+ const row = f.session("cs_original");
202
+ f.list.mockResolvedValueOnce({
203
+ data: [row, f.session("cs_second")],
204
+ has_more: false,
205
+ } as never);
206
+ await expect(
207
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, { ...f.opts, limit: 1 }),
208
+ ).rejects.toThrow(/page/i);
209
+ f.list.mockResolvedValueOnce({ data: [row, row], has_more: false } as never);
210
+ await expect(
211
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts),
212
+ ).rejects.toThrow(/duplicate|page/i);
213
+ f.list.mockResolvedValueOnce({ data: [], has_more: true } as never);
214
+ await expect(
215
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts),
216
+ ).rejects.toThrow(/continuation/i);
217
+ f.list.mockResolvedValueOnce({ data: [row], has_more: true } as never);
218
+ const first = await f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts);
219
+ f.list.mockResolvedValueOnce({ data: [row], has_more: false } as never);
220
+ await expect(
221
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, {
222
+ ...f.opts,
223
+ cursor: first.continueCursor,
224
+ }),
225
+ ).rejects.toThrow(/continuation/i);
226
+ });
227
+
228
+ it("normalizes an empty filter and returns an exhausted empty page", async () => {
229
+ const f = fixture();
230
+ f.list.mockResolvedValue({ data: [], has_more: false } as never);
231
+ await expect(
232
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, {
233
+ ...f.opts,
234
+ created: {},
235
+ cursor: null,
236
+ }),
237
+ ).resolves.toEqual({ page: [], hasMore: false, continueCursor: null });
238
+ expect(f.list).toHaveBeenCalledExactlyOnceWith({
239
+ customer_account: "acct_buyer",
240
+ limit: 25,
241
+ });
242
+ });
243
+
244
+ it("propagates provider failure rather than turning it into empty history", async () => {
245
+ const f = fixture();
246
+ const failure = new Error("provider unavailable");
247
+ f.list.mockRejectedValue(failure);
248
+ await expect(
249
+ f.client.getCheckoutSessionPageFromStripe(f.ctx, f.opts),
250
+ ).rejects.toBe(failure);
251
+ });