@fantastic.dev/better-stripe 0.38.0 → 0.40.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 (167) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/MIGRATION.md +9 -0
  3. package/README.md +21 -1
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +506 -2
  5. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +253 -1
  7. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +506 -2
  9. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts +253 -1
  11. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  12. package/dist/client/costRecovery-invoices.d.ts.map +1 -1
  13. package/dist/client/costRecovery-invoices.js +3 -5
  14. package/dist/client/costRecovery-invoices.js.map +1 -1
  15. package/dist/client/costRecovery.d.ts +18 -0
  16. package/dist/client/costRecovery.d.ts.map +1 -1
  17. package/dist/client/costRecovery.js +4 -0
  18. package/dist/client/costRecovery.js.map +1 -1
  19. package/dist/client/index.d.ts +4 -2
  20. package/dist/client/index.d.ts.map +1 -1
  21. package/dist/client/index.js +3 -2
  22. package/dist/client/index.js.map +1 -1
  23. package/dist/client/paymentSource/client.d.ts +21 -0
  24. package/dist/client/paymentSource/client.d.ts.map +1 -0
  25. package/dist/client/paymentSource/client.js +8 -0
  26. package/dist/client/paymentSource/client.js.map +1 -0
  27. package/dist/client/paymentSource/contracts.d.ts +30 -0
  28. package/dist/client/paymentSource/contracts.d.ts.map +1 -0
  29. package/dist/client/paymentSource/contracts.js +16 -0
  30. package/dist/client/paymentSource/contracts.js.map +1 -0
  31. package/dist/client/paymentSource/economics.d.ts +12 -0
  32. package/dist/client/paymentSource/economics.d.ts.map +1 -0
  33. package/dist/client/paymentSource/economics.js +13 -0
  34. package/dist/client/paymentSource/economics.js.map +1 -0
  35. package/dist/client/paymentSource/funding.d.ts +10 -0
  36. package/dist/client/paymentSource/funding.d.ts.map +1 -0
  37. package/dist/client/paymentSource/funding.js +12 -0
  38. package/dist/client/paymentSource/funding.js.map +1 -0
  39. package/dist/client/paymentSource/history.d.ts +13 -0
  40. package/dist/client/paymentSource/history.d.ts.map +1 -0
  41. package/dist/client/paymentSource/history.js +41 -0
  42. package/dist/client/paymentSource/history.js.map +1 -0
  43. package/dist/client/paymentSource/resolver.d.ts +6 -0
  44. package/dist/client/paymentSource/resolver.d.ts.map +1 -0
  45. package/dist/client/paymentSource/resolver.js +222 -0
  46. package/dist/client/paymentSource/resolver.js.map +1 -0
  47. package/dist/client/processingCostDeficit/index.d.ts +27 -0
  48. package/dist/client/processingCostDeficit/index.d.ts.map +1 -0
  49. package/dist/client/processingCostDeficit/index.js +54 -0
  50. package/dist/client/processingCostDeficit/index.js.map +1 -0
  51. package/dist/client/settlement/verifiedSale.d.ts.map +1 -1
  52. package/dist/client/settlement/verifiedSale.js +4 -6
  53. package/dist/client/settlement/verifiedSale.js.map +1 -1
  54. package/dist/component/_generated/api.d.ts +284 -0
  55. package/dist/component/_generated/api.d.ts.map +1 -0
  56. package/dist/component/_generated/api.js +31 -0
  57. package/dist/component/_generated/api.js.map +1 -0
  58. package/dist/component/_generated/component.d.ts +527 -0
  59. package/dist/component/_generated/component.d.ts.map +1 -1
  60. package/dist/component/balanceFunding/helpers.d.ts +86 -0
  61. package/dist/component/balanceFunding/helpers.d.ts.map +1 -0
  62. package/dist/component/balanceFunding/helpers.js +68 -0
  63. package/dist/component/balanceFunding/helpers.js.map +1 -0
  64. package/dist/component/balanceFunding/importHandler.d.ts +13 -0
  65. package/dist/component/balanceFunding/importHandler.d.ts.map +1 -0
  66. package/dist/component/balanceFunding/importHandler.js +130 -0
  67. package/dist/component/balanceFunding/importHandler.js.map +1 -0
  68. package/dist/component/balanceFunding/lifecycleHandlers.d.ts +85 -0
  69. package/dist/component/balanceFunding/lifecycleHandlers.d.ts.map +1 -0
  70. package/dist/component/balanceFunding/lifecycleHandlers.js +60 -0
  71. package/dist/component/balanceFunding/lifecycleHandlers.js.map +1 -0
  72. package/dist/component/balanceFunding/mutationValidators.d.ts +238 -0
  73. package/dist/component/balanceFunding/mutationValidators.d.ts.map +1 -0
  74. package/dist/component/balanceFunding/mutationValidators.js +55 -0
  75. package/dist/component/balanceFunding/mutationValidators.js.map +1 -0
  76. package/dist/component/balanceFunding/mutations.d.ts +335 -0
  77. package/dist/component/balanceFunding/mutations.d.ts.map +1 -0
  78. package/dist/component/balanceFunding/mutations.js +106 -0
  79. package/dist/component/balanceFunding/mutations.js.map +1 -0
  80. package/dist/component/balanceFunding/preparationHandlers.d.ts +55 -0
  81. package/dist/component/balanceFunding/preparationHandlers.d.ts.map +1 -0
  82. package/dist/component/balanceFunding/preparationHandlers.js +165 -0
  83. package/dist/component/balanceFunding/preparationHandlers.js.map +1 -0
  84. package/dist/component/balanceFunding/queries.d.ts +151 -0
  85. package/dist/component/balanceFunding/queries.d.ts.map +1 -0
  86. package/dist/component/balanceFunding/queries.js +180 -0
  87. package/dist/component/balanceFunding/queries.js.map +1 -0
  88. package/dist/component/balanceFunding/schema.d.ts +748 -0
  89. package/dist/component/balanceFunding/schema.d.ts.map +1 -0
  90. package/dist/component/balanceFunding/schema.js +124 -0
  91. package/dist/component/balanceFunding/schema.js.map +1 -0
  92. package/dist/component/balanceFunding/stateHandlers.d.ts +58 -0
  93. package/dist/component/balanceFunding/stateHandlers.d.ts.map +1 -0
  94. package/dist/component/balanceFunding/stateHandlers.js +160 -0
  95. package/dist/component/balanceFunding/stateHandlers.js.map +1 -0
  96. package/dist/component/convex.config.d.ts.map +1 -1
  97. package/dist/component/convex.config.js +2 -0
  98. package/dist/component/convex.config.js.map +1 -1
  99. package/dist/component/costRecovery/completion.d.ts +1 -0
  100. package/dist/component/costRecovery/completion.d.ts.map +1 -1
  101. package/dist/component/costRecovery/helpers.d.ts +1 -0
  102. package/dist/component/costRecovery/helpers.d.ts.map +1 -1
  103. package/dist/component/costRecovery/mutations.d.ts +5 -0
  104. package/dist/component/costRecovery/mutations.d.ts.map +1 -1
  105. package/dist/component/costRecovery/preparation.d.ts +50 -0
  106. package/dist/component/costRecovery/preparation.d.ts.map +1 -0
  107. package/dist/component/costRecovery/preparation.js +108 -0
  108. package/dist/component/costRecovery/preparation.js.map +1 -0
  109. package/dist/component/costRecovery/queries.d.ts +1 -0
  110. package/dist/component/costRecovery/queries.d.ts.map +1 -1
  111. package/dist/component/costRecovery/reservations.d.ts +2 -0
  112. package/dist/component/costRecovery/reservations.d.ts.map +1 -1
  113. package/dist/component/costRecovery/schema.d.ts +7 -2
  114. package/dist/component/costRecovery/schema.d.ts.map +1 -1
  115. package/dist/component/costRecovery/schema.js +1 -0
  116. package/dist/component/costRecovery/schema.js.map +1 -1
  117. package/dist/component/durableExecution/runtime.d.ts +3 -0
  118. package/dist/component/durableExecution/runtime.d.ts.map +1 -0
  119. package/dist/component/durableExecution/runtime.js +12 -0
  120. package/dist/component/durableExecution/runtime.js.map +1 -0
  121. package/dist/component/earnings/triggers.d.ts +242 -2
  122. package/dist/component/earnings/triggers.d.ts.map +1 -1
  123. package/dist/component/schema.d.ts +253 -1
  124. package/dist/component/schema.js +4 -0
  125. package/dist/component/schema.js.map +1 -1
  126. package/docs/settlement.md +48 -0
  127. package/package.json +4 -2
  128. package/src/client/costRecovery-invoices.ts +3 -7
  129. package/src/client/costRecovery.test.ts +34 -0
  130. package/src/client/costRecovery.ts +21 -0
  131. package/src/client/index.ts +7 -2
  132. package/src/client/paymentSource/client.ts +13 -0
  133. package/src/client/paymentSource/contracts.ts +33 -0
  134. package/src/client/paymentSource/economics.ts +20 -0
  135. package/src/client/paymentSource/funding.ts +23 -0
  136. package/src/client/paymentSource/history.ts +48 -0
  137. package/src/client/paymentSource/resolver.test.ts +582 -0
  138. package/src/client/paymentSource/resolver.ts +350 -0
  139. package/src/client/processingCostDeficit/README.md +35 -0
  140. package/src/client/processingCostDeficit/calculator.test.ts +176 -0
  141. package/src/client/processingCostDeficit/index.ts +91 -0
  142. package/src/client/settlement/verifiedSale.ts +4 -10
  143. package/src/component/_generated/api.ts +23 -1
  144. package/src/component/_generated/component.ts +693 -0
  145. package/src/component/balanceFunding/failure.test.ts +116 -0
  146. package/src/component/balanceFunding/helpers.ts +102 -0
  147. package/src/component/balanceFunding/import.test.ts +221 -0
  148. package/src/component/balanceFunding/importHandler.ts +146 -0
  149. package/src/component/balanceFunding/lifecycleHandlers.ts +90 -0
  150. package/src/component/balanceFunding/lookup.test.ts +113 -0
  151. package/src/component/balanceFunding/mutationValidators.ts +63 -0
  152. package/src/component/balanceFunding/mutations.ts +136 -0
  153. package/src/component/balanceFunding/preparation.test.ts +146 -0
  154. package/src/component/balanceFunding/preparationHandlers.ts +204 -0
  155. package/src/component/balanceFunding/queries.ts +221 -0
  156. package/src/component/balanceFunding/requestLookup.test.ts +160 -0
  157. package/src/component/balanceFunding/schema.ts +169 -0
  158. package/src/component/balanceFunding/state.test.ts +352 -0
  159. package/src/component/balanceFunding/stateHandlers.ts +198 -0
  160. package/src/component/balanceFunding/validation.test.ts +100 -0
  161. package/src/component/convex.config.ts +2 -0
  162. package/src/component/costRecovery/preparation.test.ts +355 -0
  163. package/src/component/costRecovery/preparation.ts +124 -0
  164. package/src/component/costRecovery/schema.ts +1 -0
  165. package/src/component/durableExecution/composition.test.ts +568 -0
  166. package/src/component/durableExecution/runtime.ts +12 -0
  167. package/src/component/schema.ts +8 -0
@@ -1,4 +1,254 @@
1
1
  declare const _default: import("convex/server").SchemaDefinition<{
2
+ balanceFundingPreparations: import("convex/server").TableDefinition<import("convex/values").VObject<{
3
+ accountId: string;
4
+ activeOperationId?: import("convex/values").GenericId<"balanceFundingOperations"> | undefined;
5
+ consentAt: number;
6
+ consentReference: string;
7
+ enabled: boolean;
8
+ operationVersion: number;
9
+ preparation: {
10
+ customerAccount: string;
11
+ paymentMethodId?: string | undefined;
12
+ previousPaymentMethodId: string | null;
13
+ previousPaymentMethodTypes: string[] | null;
14
+ stripeSubscriptionId: string;
15
+ };
16
+ preparationOperationId?: import("convex/values").GenericId<"balanceFundingOperations"> | undefined;
17
+ providerApiVersion: string;
18
+ scopeKey: string;
19
+ startsPaused: boolean;
20
+ verified: boolean;
21
+ }, {
22
+ accountId: import("convex/values").VString<string, "required">;
23
+ scopeKey: import("convex/values").VString<string, "required">;
24
+ preparation: import("convex/values").VObject<{
25
+ customerAccount: string;
26
+ paymentMethodId?: string | undefined;
27
+ previousPaymentMethodId: string | null;
28
+ previousPaymentMethodTypes: string[] | null;
29
+ stripeSubscriptionId: string;
30
+ }, {
31
+ customerAccount: import("convex/values").VString<string, "required">;
32
+ stripeSubscriptionId: import("convex/values").VString<string, "required">;
33
+ previousPaymentMethodId: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
34
+ previousPaymentMethodTypes: import("convex/values").VUnion<string[] | null, [import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">, import("convex/values").VNull<null, "required">], "required", never>;
35
+ paymentMethodId: import("convex/values").VString<string | undefined, "optional">;
36
+ }, "required", "customerAccount" | "paymentMethodId" | "previousPaymentMethodId" | "previousPaymentMethodTypes" | "stripeSubscriptionId">;
37
+ consentAt: import("convex/values").VFloat64<number, "required">;
38
+ consentReference: import("convex/values").VString<string, "required">;
39
+ providerApiVersion: import("convex/values").VString<string, "required">;
40
+ enabled: import("convex/values").VBoolean<boolean, "required">;
41
+ startsPaused: import("convex/values").VBoolean<boolean, "required">;
42
+ verified: import("convex/values").VBoolean<boolean, "required">;
43
+ preparationOperationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingOperations"> | undefined, "optional">;
44
+ operationVersion: import("convex/values").VFloat64<number, "required">;
45
+ activeOperationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingOperations"> | undefined, "optional">;
46
+ }, "required", "accountId" | "activeOperationId" | "consentAt" | "consentReference" | "enabled" | "operationVersion" | "preparation" | "preparation.customerAccount" | "preparation.paymentMethodId" | "preparation.previousPaymentMethodId" | "preparation.previousPaymentMethodTypes" | "preparation.stripeSubscriptionId" | "preparationOperationId" | "providerApiVersion" | "scopeKey" | "startsPaused" | "verified">, {
47
+ by_account_subscription: ["accountId", "preparation.stripeSubscriptionId", "_creationTime"];
48
+ }, {}, {}>;
49
+ balanceFundingOperations: import("convex/server").TableDefinition<import("convex/values").VObject<{
50
+ accountId: string;
51
+ cancelRequested: boolean;
52
+ enabled: boolean;
53
+ failureCode?: "invalid_scope" | "policy_invalid" | "unsupported_source" | undefined;
54
+ kind: "apply" | "prepare";
55
+ preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
56
+ providerKey: string;
57
+ providerKeys: {
58
+ attach?: string | undefined;
59
+ create?: string | undefined;
60
+ disable: string;
61
+ enable: string;
62
+ };
63
+ receipt?: {
64
+ customerAccount: string;
65
+ paymentMethodId: string | null;
66
+ paymentMethodTypes: string[] | null;
67
+ providerApiVersion: string;
68
+ stripeSubscriptionId: string;
69
+ } | undefined;
70
+ scopeKey: string;
71
+ state: "canceled" | "failed" | "pending" | "running" | "succeeded" | "unknown";
72
+ version: number;
73
+ }, {
74
+ accountId: import("convex/values").VString<string, "required">;
75
+ scopeKey: import("convex/values").VString<string, "required">;
76
+ preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
77
+ version: import("convex/values").VFloat64<number, "required">;
78
+ enabled: import("convex/values").VBoolean<boolean, "required">;
79
+ kind: import("convex/values").VUnion<"apply" | "prepare", [import("convex/values").VLiteral<"prepare", "required">, import("convex/values").VLiteral<"apply", "required">], "required", never>;
80
+ providerKey: import("convex/values").VString<string, "required">;
81
+ state: import("convex/values").VUnion<"canceled" | "failed" | "pending" | "running" | "succeeded" | "unknown", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"running", "required">, import("convex/values").VLiteral<"unknown", "required">, import("convex/values").VLiteral<"succeeded", "required">, import("convex/values").VLiteral<"canceled", "required">, import("convex/values").VLiteral<"failed", "required">], "required", never>;
82
+ cancelRequested: import("convex/values").VBoolean<boolean, "required">;
83
+ failureCode: import("convex/values").VUnion<"invalid_scope" | "policy_invalid" | "unsupported_source" | undefined, [import("convex/values").VLiteral<"invalid_scope", "required">, import("convex/values").VLiteral<"unsupported_source", "required">, import("convex/values").VLiteral<"policy_invalid", "required">], "optional", never>;
84
+ providerKeys: import("convex/values").VObject<{
85
+ attach?: string | undefined;
86
+ create?: string | undefined;
87
+ disable: string;
88
+ enable: string;
89
+ }, {
90
+ enable: import("convex/values").VString<string, "required">;
91
+ disable: import("convex/values").VString<string, "required">;
92
+ create: import("convex/values").VString<string | undefined, "optional">;
93
+ attach: import("convex/values").VString<string | undefined, "optional">;
94
+ }, "required", "attach" | "create" | "disable" | "enable">;
95
+ receipt: import("convex/values").VObject<{
96
+ customerAccount: string;
97
+ paymentMethodId: string | null;
98
+ paymentMethodTypes: string[] | null;
99
+ providerApiVersion: string;
100
+ stripeSubscriptionId: string;
101
+ } | undefined, {
102
+ customerAccount: import("convex/values").VString<string, "required">;
103
+ stripeSubscriptionId: import("convex/values").VString<string, "required">;
104
+ paymentMethodId: import("convex/values").VUnion<string | null, [import("convex/values").VString<string, "required">, import("convex/values").VNull<null, "required">], "required", never>;
105
+ paymentMethodTypes: import("convex/values").VUnion<string[] | null, [import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">, import("convex/values").VNull<null, "required">], "required", never>;
106
+ providerApiVersion: import("convex/values").VString<string, "required">;
107
+ }, "optional", "customerAccount" | "paymentMethodId" | "paymentMethodTypes" | "providerApiVersion" | "stripeSubscriptionId">;
108
+ }, "required", "accountId" | "cancelRequested" | "enabled" | "failureCode" | "kind" | "preparationId" | "providerKey" | "providerKeys" | "providerKeys.attach" | "providerKeys.create" | "providerKeys.disable" | "providerKeys.enable" | "receipt" | "receipt.customerAccount" | "receipt.paymentMethodId" | "receipt.paymentMethodTypes" | "receipt.providerApiVersion" | "receipt.stripeSubscriptionId" | "scopeKey" | "state" | "version">, {
109
+ by_preparation_version: ["preparationId", "version", "_creationTime"];
110
+ }, {}, {}>;
111
+ balanceFundingRequests: import("convex/server").TableDefinition<import("convex/values").VObject<{
112
+ imported?: {
113
+ operation?: {
114
+ accountId: string;
115
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
116
+ scopeKey: string;
117
+ version: number;
118
+ } | undefined;
119
+ preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
120
+ } | undefined;
121
+ payload: string;
122
+ preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
123
+ requestKey: string;
124
+ result?: {
125
+ operation: {
126
+ accountId: string;
127
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
128
+ scopeKey: string;
129
+ version: number;
130
+ };
131
+ status: "accepted";
132
+ } | {
133
+ enabled: boolean;
134
+ status: "unchanged";
135
+ } | {
136
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
137
+ retryable: false;
138
+ status: "conflict";
139
+ } | {
140
+ reason: "policy_invalid";
141
+ retryable: false;
142
+ status: "rejected";
143
+ } | {
144
+ reason: "provider_pending";
145
+ retryable: true;
146
+ status: "not_ready";
147
+ } | undefined;
148
+ }, {
149
+ requestKey: import("convex/values").VString<string, "required">;
150
+ payload: import("convex/values").VString<string, "required">;
151
+ preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
152
+ result: import("convex/values").VUnion<{
153
+ operation: {
154
+ accountId: string;
155
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
156
+ scopeKey: string;
157
+ version: number;
158
+ };
159
+ status: "accepted";
160
+ } | {
161
+ enabled: boolean;
162
+ status: "unchanged";
163
+ } | {
164
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
165
+ retryable: false;
166
+ status: "conflict";
167
+ } | {
168
+ reason: "policy_invalid";
169
+ retryable: false;
170
+ status: "rejected";
171
+ } | {
172
+ reason: "provider_pending";
173
+ retryable: true;
174
+ status: "not_ready";
175
+ } | undefined, [import("convex/values").VObject<{
176
+ operation: {
177
+ accountId: string;
178
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
179
+ scopeKey: string;
180
+ version: number;
181
+ };
182
+ status: "accepted";
183
+ }, {
184
+ status: import("convex/values").VLiteral<"accepted", "required">;
185
+ operation: import("convex/values").VObject<{
186
+ accountId: string;
187
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
188
+ scopeKey: string;
189
+ version: number;
190
+ }, {
191
+ accountId: import("convex/values").VString<string, "required">;
192
+ scopeKey: import("convex/values").VString<string, "required">;
193
+ operationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingOperations">, "required">;
194
+ version: import("convex/values").VFloat64<number, "required">;
195
+ }, "required", "accountId" | "operationId" | "scopeKey" | "version">;
196
+ }, "required", "operation" | "operation.accountId" | "operation.operationId" | "operation.scopeKey" | "operation.version" | "status">, import("convex/values").VObject<{
197
+ enabled: boolean;
198
+ status: "unchanged";
199
+ }, {
200
+ status: import("convex/values").VLiteral<"unchanged", "required">;
201
+ enabled: import("convex/values").VBoolean<boolean, "required">;
202
+ }, "required", "enabled" | "status">, import("convex/values").VObject<{
203
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
204
+ retryable: false;
205
+ status: "conflict";
206
+ }, {
207
+ status: import("convex/values").VLiteral<"conflict", "required">;
208
+ reason: import("convex/values").VUnion<"identity_changed" | "revision_changed" | "scope_busy", [import("convex/values").VLiteral<"scope_busy", "required">, import("convex/values").VLiteral<"identity_changed", "required">, import("convex/values").VLiteral<"revision_changed", "required">], "required", never>;
209
+ retryable: import("convex/values").VLiteral<false, "required">;
210
+ }, "required", "reason" | "retryable" | "status">, import("convex/values").VObject<{
211
+ reason: "policy_invalid";
212
+ retryable: false;
213
+ status: "rejected";
214
+ }, {
215
+ status: import("convex/values").VLiteral<"rejected", "required">;
216
+ reason: import("convex/values").VLiteral<"policy_invalid", "required">;
217
+ retryable: import("convex/values").VLiteral<false, "required">;
218
+ }, "required", "reason" | "retryable" | "status">, import("convex/values").VObject<{
219
+ reason: "provider_pending";
220
+ retryable: true;
221
+ status: "not_ready";
222
+ }, {
223
+ status: import("convex/values").VLiteral<"not_ready", "required">;
224
+ reason: import("convex/values").VLiteral<"provider_pending", "required">;
225
+ retryable: import("convex/values").VLiteral<true, "required">;
226
+ }, "required", "reason" | "retryable" | "status">], "optional", "enabled" | "operation" | "operation.accountId" | "operation.operationId" | "operation.scopeKey" | "operation.version" | "reason" | "retryable" | "status">;
227
+ imported: import("convex/values").VObject<{
228
+ operation?: {
229
+ accountId: string;
230
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
231
+ scopeKey: string;
232
+ version: number;
233
+ } | undefined;
234
+ preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
235
+ } | undefined, {
236
+ preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
237
+ operation: import("convex/values").VObject<{
238
+ accountId: string;
239
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
240
+ scopeKey: string;
241
+ version: number;
242
+ } | undefined, {
243
+ accountId: import("convex/values").VString<string, "required">;
244
+ scopeKey: import("convex/values").VString<string, "required">;
245
+ operationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingOperations">, "required">;
246
+ version: import("convex/values").VFloat64<number, "required">;
247
+ }, "optional", "accountId" | "operationId" | "scopeKey" | "version">;
248
+ }, "optional", "operation" | "operation.accountId" | "operation.operationId" | "operation.scopeKey" | "operation.version" | "preparationId">;
249
+ }, "required", "imported" | "imported.operation" | "imported.operation.accountId" | "imported.operation.operationId" | "imported.operation.scopeKey" | "imported.operation.version" | "imported.preparationId" | "payload" | "preparationId" | "requestKey" | "result" | "result.enabled" | "result.operation" | "result.operation.accountId" | "result.operation.operationId" | "result.operation.scopeKey" | "result.operation.version" | "result.reason" | "result.retryable" | "result.status">, {
250
+ by_request: ["requestKey", "_creationTime"];
251
+ }, {}, {}>;
2
252
  operationEvidencePayloads: import("convex/server").TableDefinition<import("convex/values").VObject<{
3
253
  commissionExposure?: {
4
254
  chargeAmount: number;
@@ -1291,6 +1541,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
1291
1541
  maxCredit: number;
1292
1542
  maxDebit: number;
1293
1543
  pendingOperations: number;
1544
+ preparationSequence?: number | undefined;
1294
1545
  scopeKey: string;
1295
1546
  sourceGross?: number | undefined;
1296
1547
  sourceId: string;
@@ -1310,6 +1561,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
1310
1561
  maxCredit: import("convex/values").VFloat64<number, "required">;
1311
1562
  amount: import("convex/values").VFloat64<number, "required">;
1312
1563
  pendingOperations: import("convex/values").VFloat64<number, "required">;
1564
+ preparationSequence: import("convex/values").VFloat64<number | undefined, "optional">;
1313
1565
  invoiceItemId: import("convex/values").VString<string | undefined, "optional">;
1314
1566
  invoiceFunding: import("convex/values").VObject<{
1315
1567
  sourceChargeId: string;
@@ -1321,7 +1573,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
1321
1573
  sourceProcessingFee: import("convex/values").VFloat64<number, "required">;
1322
1574
  }, "optional", "sourceChargeId" | "sourceGross" | "sourceProcessingFee">;
1323
1575
  status: import("convex/values").VUnion<"collected" | "collecting" | "open" | "released" | "releasing" | "sealed", [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"sealed", "required">, import("convex/values").VLiteral<"collecting", "required">, import("convex/values").VLiteral<"releasing", "required">, import("convex/values").VLiteral<"collected", "required">, import("convex/values").VLiteral<"released", "required">], "required", never>;
1324
- }, "required", "accountId" | "amount" | "currency" | "groupKey" | "invoiceFunding" | "invoiceFunding.sourceChargeId" | "invoiceFunding.sourceGross" | "invoiceFunding.sourceProcessingFee" | "invoiceItemId" | "maxCredit" | "maxDebit" | "pendingOperations" | "scopeKey" | "sourceGross" | "sourceId" | "sourceKind" | "sourceProcessingFee" | "status">, {
1576
+ }, "required", "accountId" | "amount" | "currency" | "groupKey" | "invoiceFunding" | "invoiceFunding.sourceChargeId" | "invoiceFunding.sourceGross" | "invoiceFunding.sourceProcessingFee" | "invoiceItemId" | "maxCredit" | "maxDebit" | "pendingOperations" | "preparationSequence" | "scopeKey" | "sourceGross" | "sourceId" | "sourceKind" | "sourceProcessingFee" | "status">, {
1325
1577
  by_key: ["groupKey", "_creationTime"];
1326
1578
  }, {}, {}>;
1327
1579
  recoveryReservations: import("convex/server").TableDefinition<import("convex/values").VObject<{
@@ -1,3 +1,4 @@
1
+ import { preparationsTable as balanceFundingPreparations, operationsTable as balanceFundingOperations, requestsTable as balanceFundingRequests, } from "./balanceFunding/schema.js";
1
2
  import { payloadsTable as operationEvidencePayloads, headersTable as operationEvidenceHeaders, } from "./operationEvidence/schema.js";
2
3
  import { transferBatchReferencesTable } from "./financialObservations/transferReferenceSchema.js";
3
4
  import { transferObservationsTable, transferBatchesTable, } from "./financialObservations/transferSchema.js";
@@ -21,6 +22,9 @@ import { accountsTable } from "./core/schema";
21
22
  import { pricesTable, productsTable } from "./products/schema";
22
23
  import { webhookEventsTable } from "./webhooks/schema";
23
24
  export default defineSchema({
25
+ balanceFundingPreparations,
26
+ balanceFundingOperations,
27
+ balanceFundingRequests,
24
28
  operationEvidencePayloads,
25
29
  operationEvidenceHeaders,
26
30
  financialTransferObservations: transferObservationsTable,
@@ -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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"}
@@ -5,6 +5,54 @@ and recovery. Your server authenticates the caller, resolves recipient accounts,
5
5
  selects rates, and authorizes the allocation. Never accept these values directly
6
6
  from a browser. Amounts below are integer minor units in one currency.
7
7
 
8
+ ## Resolve original payment provenance
9
+
10
+ Use `getVerifiedPaymentSource` when the host has an authorized PaymentIntent and
11
+ needs its original invoice price for settlement or processing-cost recovery:
12
+
13
+ ```ts
14
+ const source = await stripe.getVerifiedPaymentSource(ctx, {
15
+ paymentIntentId,
16
+ customerAccountId, // Optional expected binding; authorize this in your host.
17
+ stripeAccountId, // Optional connected-account execution scope.
18
+ gross: expectedGross,
19
+ currency: expectedCurrency,
20
+ maxHistoryPages: 5,
21
+ maxHistoryItems: 500,
22
+ });
23
+ if (source.status !== "ready") return source;
24
+ // Authorize source.value.stripeProductId before applying application policy.
25
+ ```
26
+
27
+ The read-only result contains provider IDs, original gross and processing fee,
28
+ currency and live/test mode. Optional expected `invoiceId` and `subscriptionId`
29
+ are also checked. Provider reads inherit the SDK's configured Stripe API version
30
+ and connected-account scope. Authentication, seller/product ownership, metadata
31
+ interpretation, commission and retry scheduling remain host responsibilities.
32
+
33
+ Resolution requires complete inverse PaymentIntent funding history, complete
34
+ invoice funding history, one fully paid PaymentIntent allocation and one original
35
+ priced invoice line. It verifies customer, invoice, subscription, charge and
36
+ balance-transaction bindings, currencies and reconciled gross/fee/net amounts.
37
+ Current subscription items and metadata never establish the original price.
38
+ Prorations, partial/credit/multiple-payment funding and ambiguous price allocation
39
+ are rejected instead of guessed. Refunded or disputed charges retain their
40
+ original provenance; a ready source does **not** establish settlement eligibility
41
+ or calculate subsequent refund/dispute costs.
42
+
43
+ Each of the three history walks has independent validated limits: 1–20 pages and
44
+ 1–2,000 items (defaults 5 and 500), at most 100 items per page. Reaching a limit
45
+ before `has_more: false`, malformed pages, repeated IDs or failed history reads
46
+ returns `unknown/history_incomplete`, with `retryable: false`. Missing processing
47
+ fees return `not_ready/fee_pending`; only a provider-verified zero fee becomes
48
+ zero. Identity conflicts and unsupported sources are terminal typed outcomes.
49
+ Other failed provider reads return sanitized `unknown/provider_outcome_unknown`.
50
+ The method performs no writes or automatic financial-operation retries.
51
+
52
+ `getVerifiedSale` and the existing cost readers keep their existing contracts,
53
+ including settlement eligibility checks. The new resolver shares their pure
54
+ currency/amount and single-funding checks without changing their result shapes.
55
+
8
56
  ## Read, allocate, settle
9
57
 
10
58
  ```ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.38.0",
3
+ "version": "0.40.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -110,6 +110,8 @@
110
110
  "check:agents": "repo-gates check-agents"
111
111
  },
112
112
  "dependencies": {
113
+ "@convex-dev/workflow": "0.4.10",
114
+ "@convex-dev/workpool": "0.4.14",
113
115
  "@stripe/connect-js": "^3.4.6",
114
116
  "@stripe/react-connect-js": "^3.4.4",
115
117
  "@stripe/react-stripe-js": "^7.0.0",
@@ -145,7 +147,7 @@
145
147
  "vitest": "^5.0.3"
146
148
  },
147
149
  "peerDependencies": {
148
- "convex": "^1.29.3",
150
+ "convex": "^1.46.0",
149
151
  "react": "^18.3.1 || ^19.0.0",
150
152
  "react-dom": "^18.3.1 || ^19.0.0"
151
153
  },
@@ -1,3 +1,4 @@
1
+ import { singleInvoiceFunding } from "./paymentSource/funding.js";
1
2
  import { getProcessingCostContext } from "./settlement/processingCosts.js";
2
3
  import type Stripe from "stripe";
3
4
  import type { RecoveryGroup, RecoveryScope } from "./costRecovery.js";
@@ -152,13 +153,8 @@ export async function readInvoiceFunding(stripe: Stripe, group: RecoveryGroup) {
152
153
  throw new Error("Invoice payment identity or currency does not match.");
153
154
  if (payment.status === "paid") payments.push(payment);
154
155
  }
155
- const payment = payments[0];
156
- if (
157
- payments.length !== 1 ||
158
- payment?.payment.type !== "payment_intent" ||
159
- !payment.payment.payment_intent ||
160
- payment.amount_paid !== invoice.amount_paid
161
- )
156
+ const payment = singleInvoiceFunding(payments, invoice.amount_paid);
157
+ if (!payment)
162
158
  return {
163
159
  status: "not_ready" as const,
164
160
  reason: "invoice_funding_allocation_required" as const,
@@ -74,3 +74,37 @@ it("uses the real component through the public recovery client without any provi
74
74
  reservedAmount: 0,
75
75
  });
76
76
  });
77
+ it("prepares recovery through one component mutation without a provider key", async () => {
78
+ const t = initConvexTest();
79
+ t.registerComponent("betterStripe", schema, modules);
80
+ const stripe = new BetterStripe(
81
+ componentsGeneric().betterStripe as unknown as Component,
82
+ {},
83
+ );
84
+ let writes = 0;
85
+ const ctx = {
86
+ runMutation: (
87
+ ref: FunctionReference<"mutation">,
88
+ args: Record<string, unknown>,
89
+ ) => {
90
+ writes++;
91
+ return t.mutation(ref, args);
92
+ },
93
+ } as unknown as RunCtx;
94
+ const opts = {
95
+ accountId: "acct_owner",
96
+ scopeKey: "store",
97
+ currency: "usd",
98
+ groupKey: "empty",
99
+ sourceKind: "invoice" as const,
100
+ sourceId: "in_empty",
101
+ maxDebit: 100,
102
+ maxCredit: 100,
103
+ };
104
+ expect(await stripe.costRecovery.prepareGroup(ctx, opts)).toMatchObject({
105
+ status: "prepared",
106
+ isDone: true,
107
+ group: { status: "sealed", amount: 0 },
108
+ });
109
+ expect(writes).toBe(1);
110
+ });
@@ -63,6 +63,7 @@ export type RecoveryGroup = RecoveryGroupOptions & {
63
63
  _creationTime: number;
64
64
  amount: number;
65
65
  pendingOperations: number;
66
+ preparationSequence?: number;
66
67
  invoiceItemId?: string;
67
68
  invoiceFunding?: {
68
69
  sourceChargeId: string;
@@ -82,6 +83,18 @@ export type RecoveryReservation = {
82
83
  allocations: { claimId: string; claimKey: string; amount: number }[];
83
84
  status: "reserved" | "collected" | "released" | "empty";
84
85
  };
86
+ export type RecoveryPreparationResult =
87
+ | { status: "prepared"; group: RecoveryGroup; isDone: boolean }
88
+ | {
89
+ status: "conflict";
90
+ reason: "scope_busy" | "identity_changed";
91
+ retryable: false;
92
+ }
93
+ | {
94
+ status: "rejected";
95
+ reason: "invalid_scope" | "policy_invalid";
96
+ retryable: false;
97
+ };
85
98
  /** Host authorizes policy and scope. Provider methods verify invoice outcomes. */
86
99
  export class CostRecoveryClient {
87
100
  constructor(
@@ -213,6 +226,14 @@ export class CostRecoveryClient {
213
226
  recordClaim(ctx: RunCtx, opts: RecoveryObservation) {
214
227
  return this.mutate<RecoveryClaim>(ctx, "mutations/record", opts);
215
228
  }
229
+ /** Authorize scope and limits first. Repeat bounded calls until isDone. */
230
+ prepareGroup(ctx: RunCtx, opts: RecoveryGroupOptions & { limit?: number }) {
231
+ return this.mutate<RecoveryPreparationResult>(
232
+ ctx,
233
+ "preparation/prepare",
234
+ opts,
235
+ );
236
+ }
216
237
  reserve(
217
238
  ctx: RunCtx,
218
239
  opts: RecoveryGroupOptions & { operationKey: string; limit?: number },
@@ -1,6 +1,7 @@
1
1
  import * as personalAccountMappingImpl from "./core/personalAccountMapping.js";
2
2
  export type * from "./publicTypes.js";
3
3
  export * from "./financialOutcomes/index.js";
4
+ export * from "./processingCostDeficit/index.js";
4
5
  import * as accountClosuresImpl from "./core/accountClosures.js";
5
6
  import type { PaginationOptions } from "convex/server";
6
7
  import { reconcilePayoutAndTrigger } from "./webhooks/payoutReconciliation.js";
@@ -19,7 +20,7 @@ import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js"
19
20
  export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
20
21
  import * as intentsImpl from "./billing/intents.js";
21
22
  export type * from "./billing/intents.js";
22
- import { CatalogClient } from "./products/catalogClient.js";
23
+ import { PaymentSourceClient } from "./paymentSource/client.js";
23
24
  export type {
24
25
  CreateBillingPortalConfigurationOptions,
25
26
  RetrieveBillingPortalConfigurationOptions,
@@ -90,6 +91,10 @@ export type {
90
91
  VerifiedSale,
91
92
  VerifiedSaleOptions,
92
93
  } from "./settlement/verifiedSale.js";
94
+ export type {
95
+ VerifiedPaymentSource,
96
+ VerifiedPaymentSourceOptions,
97
+ } from "./paymentSource/contracts.js";
93
98
  export type { SettleSaleOptions } from "./settlement/settleSale.js";
94
99
  export type { SettlementResult } from "./settlement/execution.js";
95
100
  export type {
@@ -204,7 +209,7 @@ export type BetterStripeComponent = ComponentApi;
204
209
 
205
210
  // BETTER STRIPE CLIENT
206
211
 
207
- export class BetterStripe extends CatalogClient {
212
+ export class BetterStripe extends PaymentSourceClient {
208
213
  readonly stripeApiVersion: SupportedStripeApiVersion;
209
214
  private _apiKey?: string;
210
215
  private _triggers?: SyncTriggers;
@@ -0,0 +1,13 @@
1
+ import { CatalogClient } from "../products/catalogClient.js";
2
+ import type { RunCtx } from "../helpers.js";
3
+ import { resolveVerifiedPaymentSource } from "./resolver.js";
4
+ import type { VerifiedPaymentSourceOptions } from "./contracts.js";
5
+
6
+ export abstract class PaymentSourceClient extends CatalogClient {
7
+ async getVerifiedPaymentSource(
8
+ _ctx: RunCtx,
9
+ opts: VerifiedPaymentSourceOptions,
10
+ ) {
11
+ return resolveVerifiedPaymentSource(this.stripe(), opts);
12
+ }
13
+ }
@@ -0,0 +1,33 @@
1
+ import { z } from "zod";
2
+
3
+ const identifier = z.string().min(1).max(200);
4
+ export const paymentSourceOptions = z
5
+ .object({
6
+ paymentIntentId: identifier,
7
+ customerAccountId: identifier.optional(),
8
+ stripeAccountId: identifier.optional(),
9
+ invoiceId: identifier.optional(),
10
+ subscriptionId: identifier.optional(),
11
+ currency: z.string().regex(/^[a-z]{3}$/),
12
+ gross: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
13
+ maxHistoryPages: z.number().int().min(1).max(20).default(5),
14
+ maxHistoryItems: z.number().int().min(1).max(2000).default(500),
15
+ })
16
+ .strict();
17
+ export type VerifiedPaymentSourceOptions = z.input<typeof paymentSourceOptions>;
18
+ /** Provider identities/economics only. The host still authorizes these identities. */
19
+ export type VerifiedPaymentSource = Readonly<{
20
+ paymentIntentId: string;
21
+ chargeId: string;
22
+ invoiceId: string;
23
+ invoicePaymentId: string;
24
+ subscriptionId?: string;
25
+ customerAccountId: string;
26
+ stripeAccountId?: string;
27
+ stripePriceId: string;
28
+ stripeProductId: string;
29
+ gross: number;
30
+ processingFee: number;
31
+ currency: string;
32
+ livemode: boolean;
33
+ }>;
@@ -0,0 +1,20 @@
1
+ /** The existing settlement amount/currency rules, shared without changing its result contract. */
2
+ export function saleAmountFailure(
3
+ payment: { currency: string; amount_received: number },
4
+ charge: { currency: string; amount: number },
5
+ balance: { currency: string; fee: number },
6
+ ): "currency" | "amounts" | null {
7
+ if (
8
+ balance.currency !== payment.currency ||
9
+ charge.currency !== payment.currency
10
+ )
11
+ return "currency";
12
+ if (
13
+ ![payment.amount_received, balance.fee].every(Number.isSafeInteger) ||
14
+ balance.fee < 0 ||
15
+ balance.fee > payment.amount_received ||
16
+ charge.amount !== payment.amount_received
17
+ )
18
+ return "amounts";
19
+ return null;
20
+ }
@@ -0,0 +1,23 @@
1
+ import type Stripe from "stripe";
2
+ export type IntentFunding = Stripe.InvoicePayment & {
3
+ payment: {
4
+ type: "payment_intent";
5
+ payment_intent: string | Stripe.PaymentIntent;
6
+ };
7
+ };
8
+ /** Shared existing funding rule; callers must independently prove scope and complete history. */
9
+ export function singleInvoiceFunding(
10
+ rows: Stripe.InvoicePayment[],
11
+ amountPaid: number,
12
+ ): IntentFunding | null {
13
+ const paid = rows.filter((row) => row.status === "paid");
14
+ const payment = paid[0];
15
+ if (
16
+ paid.length !== 1 ||
17
+ payment?.payment.type !== "payment_intent" ||
18
+ !payment.payment.payment_intent ||
19
+ payment.amount_paid !== amountPaid
20
+ )
21
+ return null;
22
+ return payment as IntentFunding;
23
+ }