@fantastic.dev/better-stripe 0.33.0 → 0.35.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 (314) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +30 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +522 -2
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +261 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +522 -2
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +261 -1
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/connect/refundCommandEvidence.d.ts +14 -0
  12. package/dist/client/connect/refundCommandEvidence.d.ts.map +1 -0
  13. package/dist/client/connect/refundCommandEvidence.js +20 -0
  14. package/dist/client/connect/refundCommandEvidence.js.map +1 -0
  15. package/dist/client/connect/refundCommandNormalization.d.ts +11 -0
  16. package/dist/client/connect/refundCommandNormalization.d.ts.map +1 -0
  17. package/dist/client/connect/refundCommandNormalization.js +12 -0
  18. package/dist/client/connect/refundCommandNormalization.js.map +1 -0
  19. package/dist/client/core/accountClosures.d.ts +15 -0
  20. package/dist/client/core/accountClosures.d.ts.map +1 -0
  21. package/dist/client/core/accountClosures.js +10 -0
  22. package/dist/client/core/accountClosures.js.map +1 -0
  23. package/dist/client/core/accounts.d.ts.map +1 -1
  24. package/dist/client/core/accounts.js +15 -23
  25. package/dist/client/core/accounts.js.map +1 -1
  26. package/dist/client/core/personalAccountMapping.d.ts +8 -0
  27. package/dist/client/core/personalAccountMapping.d.ts.map +1 -0
  28. package/dist/client/core/personalAccountMapping.js +11 -0
  29. package/dist/client/core/personalAccountMapping.js.map +1 -0
  30. package/dist/client/financialObservations.d.ts +42 -0
  31. package/dist/client/financialObservations.d.ts.map +1 -0
  32. package/dist/client/financialObservations.js +58 -0
  33. package/dist/client/financialObservations.js.map +1 -0
  34. package/dist/client/financialOwnership.d.ts +52 -0
  35. package/dist/client/financialOwnership.d.ts.map +1 -0
  36. package/dist/client/financialOwnership.js +72 -0
  37. package/dist/client/financialOwnership.js.map +1 -0
  38. package/dist/client/index.d.ts +57 -4
  39. package/dist/client/index.d.ts.map +1 -1
  40. package/dist/client/index.js +15 -2
  41. package/dist/client/index.js.map +1 -1
  42. package/dist/client/observationPagination.d.ts +10 -0
  43. package/dist/client/observationPagination.d.ts.map +1 -0
  44. package/dist/client/observationPagination.js +12 -0
  45. package/dist/client/observationPagination.js.map +1 -0
  46. package/dist/client/publicTypes.d.ts +10 -0
  47. package/dist/client/publicTypes.d.ts.map +1 -0
  48. package/dist/client/publicTypes.js +2 -0
  49. package/dist/client/publicTypes.js.map +1 -0
  50. package/dist/client/readContracts.d.ts +29 -0
  51. package/dist/client/readContracts.d.ts.map +1 -1
  52. package/dist/client/readContracts.js +10 -0
  53. package/dist/client/readContracts.js.map +1 -1
  54. package/dist/client/transferObservations.d.ts +59 -0
  55. package/dist/client/transferObservations.d.ts.map +1 -0
  56. package/dist/client/transferObservations.js +82 -0
  57. package/dist/client/transferObservations.js.map +1 -0
  58. package/dist/component/_generated/component.d.ts +594 -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/affiliateRecovery/mutations.d.ts.map +1 -1
  77. package/dist/component/affiliateRecovery/mutations.js +4 -1
  78. package/dist/component/affiliateRecovery/mutations.js.map +1 -1
  79. package/dist/component/connect/mutations.d.ts.map +1 -1
  80. package/dist/component/connect/mutations.js +18 -2
  81. package/dist/component/connect/mutations.js.map +1 -1
  82. package/dist/component/connect/queries.d.ts +8 -0
  83. package/dist/component/connect/queries.d.ts.map +1 -1
  84. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  85. package/dist/component/connect/reversalClaims.js +7 -1
  86. package/dist/component/connect/reversalClaims.js.map +1 -1
  87. package/dist/component/connect/reversalReceipts.d.ts.map +1 -1
  88. package/dist/component/connect/reversalReceipts.js +2 -0
  89. package/dist/component/connect/reversalReceipts.js.map +1 -1
  90. package/dist/component/connect/schema.d.ts +11 -1
  91. package/dist/component/connect/schema.d.ts.map +1 -1
  92. package/dist/component/connect/schema.js +9 -1
  93. package/dist/component/connect/schema.js.map +1 -1
  94. package/dist/component/connect/validators.d.ts +9 -1
  95. package/dist/component/connect/validators.d.ts.map +1 -1
  96. package/dist/component/connect/validators.js +2 -0
  97. package/dist/component/connect/validators.js.map +1 -1
  98. package/dist/component/core/mutations.d.ts.map +1 -1
  99. package/dist/component/core/mutations.js +5 -0
  100. package/dist/component/core/mutations.js.map +1 -1
  101. package/dist/component/core/personalAccountMapping.d.ts +95 -0
  102. package/dist/component/core/personalAccountMapping.d.ts.map +1 -0
  103. package/dist/component/core/personalAccountMapping.js +54 -0
  104. package/dist/component/core/personalAccountMapping.js.map +1 -0
  105. package/dist/component/core/queries.d.ts +27 -0
  106. package/dist/component/core/queries.d.ts.map +1 -1
  107. package/dist/component/core/queries.js +7 -0
  108. package/dist/component/core/queries.js.map +1 -1
  109. package/dist/component/earnings/triggers.d.ts +468 -2
  110. package/dist/component/earnings/triggers.d.ts.map +1 -1
  111. package/dist/component/earnings/triggers.js +7 -1
  112. package/dist/component/earnings/triggers.js.map +1 -1
  113. package/dist/component/financialObservations/continuation.d.ts +7 -0
  114. package/dist/component/financialObservations/continuation.d.ts.map +1 -0
  115. package/dist/component/financialObservations/continuation.js +131 -0
  116. package/dist/component/financialObservations/continuation.js.map +1 -0
  117. package/dist/component/financialObservations/generations.d.ts +6 -0
  118. package/dist/component/financialObservations/generations.d.ts.map +1 -0
  119. package/dist/component/financialObservations/generations.js +46 -0
  120. package/dist/component/financialObservations/generations.js.map +1 -0
  121. package/dist/component/financialObservations/mutations.d.ts +62 -0
  122. package/dist/component/financialObservations/mutations.d.ts.map +1 -0
  123. package/dist/component/financialObservations/mutations.js +69 -0
  124. package/dist/component/financialObservations/mutations.js.map +1 -0
  125. package/dist/component/financialObservations/queries.d.ts +307 -0
  126. package/dist/component/financialObservations/queries.d.ts.map +1 -0
  127. package/dist/component/financialObservations/queries.js +219 -0
  128. package/dist/component/financialObservations/queries.js.map +1 -0
  129. package/dist/component/financialObservations/schema.d.ts +182 -0
  130. package/dist/component/financialObservations/schema.d.ts.map +1 -0
  131. package/dist/component/financialObservations/schema.js +53 -0
  132. package/dist/component/financialObservations/schema.js.map +1 -0
  133. package/dist/component/financialObservations/settlement.d.ts +7 -0
  134. package/dist/component/financialObservations/settlement.d.ts.map +1 -0
  135. package/dist/component/financialObservations/settlement.js +118 -0
  136. package/dist/component/financialObservations/settlement.js.map +1 -0
  137. package/dist/component/financialObservations/settlementHelpers.d.ts +46 -0
  138. package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -0
  139. package/dist/component/financialObservations/settlementHelpers.js +70 -0
  140. package/dist/component/financialObservations/settlementHelpers.js.map +1 -0
  141. package/dist/component/financialObservations/transferBatches.d.ts +12 -0
  142. package/dist/component/financialObservations/transferBatches.d.ts.map +1 -0
  143. package/dist/component/financialObservations/transferBatches.js +76 -0
  144. package/dist/component/financialObservations/transferBatches.js.map +1 -0
  145. package/dist/component/financialObservations/transferContinuation.d.ts +5 -0
  146. package/dist/component/financialObservations/transferContinuation.d.ts.map +1 -0
  147. package/dist/component/financialObservations/transferContinuation.js +35 -0
  148. package/dist/component/financialObservations/transferContinuation.js.map +1 -0
  149. package/dist/component/financialObservations/transferContinuationState.d.ts +8 -0
  150. package/dist/component/financialObservations/transferContinuationState.d.ts.map +1 -0
  151. package/dist/component/financialObservations/transferContinuationState.js +69 -0
  152. package/dist/component/financialObservations/transferContinuationState.js.map +1 -0
  153. package/dist/component/financialObservations/transferContinuationSteps.d.ts +5 -0
  154. package/dist/component/financialObservations/transferContinuationSteps.d.ts.map +1 -0
  155. package/dist/component/financialObservations/transferContinuationSteps.js +174 -0
  156. package/dist/component/financialObservations/transferContinuationSteps.js.map +1 -0
  157. package/dist/component/financialObservations/transferHelpers.d.ts +18 -0
  158. package/dist/component/financialObservations/transferHelpers.d.ts.map +1 -0
  159. package/dist/component/financialObservations/transferHelpers.js +37 -0
  160. package/dist/component/financialObservations/transferHelpers.js.map +1 -0
  161. package/dist/component/financialObservations/transferReferenceSchema.d.ts +56 -0
  162. package/dist/component/financialObservations/transferReferenceSchema.d.ts.map +1 -0
  163. package/dist/component/financialObservations/transferReferenceSchema.js +21 -0
  164. package/dist/component/financialObservations/transferReferenceSchema.js.map +1 -0
  165. package/dist/component/financialObservations/transferSchema.d.ts +237 -0
  166. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -0
  167. package/dist/component/financialObservations/transferSchema.js +65 -0
  168. package/dist/component/financialObservations/transferSchema.js.map +1 -0
  169. package/dist/component/financialObservations/transfers.d.ts +7 -0
  170. package/dist/component/financialObservations/transfers.d.ts.map +1 -0
  171. package/dist/component/financialObservations/transfers.js +79 -0
  172. package/dist/component/financialObservations/transfers.js.map +1 -0
  173. package/dist/component/financialOwnership/helpers.d.ts +37 -0
  174. package/dist/component/financialOwnership/helpers.d.ts.map +1 -0
  175. package/dist/component/financialOwnership/helpers.js +76 -0
  176. package/dist/component/financialOwnership/helpers.js.map +1 -0
  177. package/dist/component/financialOwnership/mutations.d.ts +28 -0
  178. package/dist/component/financialOwnership/mutations.d.ts.map +1 -0
  179. package/dist/component/financialOwnership/mutations.js +74 -0
  180. package/dist/component/financialOwnership/mutations.js.map +1 -0
  181. package/dist/component/financialOwnership/queries.d.ts +57 -0
  182. package/dist/component/financialOwnership/queries.d.ts.map +1 -0
  183. package/dist/component/financialOwnership/queries.js +50 -0
  184. package/dist/component/financialOwnership/queries.js.map +1 -0
  185. package/dist/component/financialOwnership/schema.d.ts +140 -0
  186. package/dist/component/financialOwnership/schema.d.ts.map +1 -0
  187. package/dist/component/financialOwnership/schema.js +35 -0
  188. package/dist/component/financialOwnership/schema.js.map +1 -0
  189. package/dist/component/payoutRelease/queries.d.ts +2 -2
  190. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  191. package/dist/component/refundHistory/commandBinding.d.ts +17 -0
  192. package/dist/component/refundHistory/commandBinding.d.ts.map +1 -0
  193. package/dist/component/refundHistory/commandBinding.js +41 -0
  194. package/dist/component/refundHistory/commandBinding.js.map +1 -0
  195. package/dist/component/refundHistory/commandEvidence.d.ts +50 -0
  196. package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -0
  197. package/dist/component/refundHistory/commandEvidence.js +54 -0
  198. package/dist/component/refundHistory/commandEvidence.js.map +1 -0
  199. package/dist/component/refundHistory/commandEvidenceValidator.d.ts +89 -0
  200. package/dist/component/refundHistory/commandEvidenceValidator.d.ts.map +1 -0
  201. package/dist/component/refundHistory/commandEvidenceValidator.js +8 -0
  202. package/dist/component/refundHistory/commandEvidenceValidator.js.map +1 -0
  203. package/dist/component/refundHistory/commandFields.d.ts +8 -0
  204. package/dist/component/refundHistory/commandFields.d.ts.map +1 -0
  205. package/dist/component/refundHistory/commandFields.js +9 -0
  206. package/dist/component/refundHistory/commandFields.js.map +1 -0
  207. package/dist/component/refundHistory/mutations.d.ts +8 -0
  208. package/dist/component/refundHistory/mutations.d.ts.map +1 -0
  209. package/dist/component/refundHistory/mutations.js +25 -0
  210. package/dist/component/refundHistory/mutations.js.map +1 -0
  211. package/dist/component/refundHistory/queries.d.ts +51 -0
  212. package/dist/component/refundHistory/queries.d.ts.map +1 -1
  213. package/dist/component/refundHistory/queries.js +14 -0
  214. package/dist/component/refundHistory/queries.js.map +1 -1
  215. package/dist/component/schema.d.ts +261 -1
  216. package/dist/component/schema.js +14 -0
  217. package/dist/component/schema.js.map +1 -1
  218. package/dist/component/settlement/mutations.d.ts.map +1 -1
  219. package/dist/component/settlement/mutations.js +5 -1
  220. package/dist/component/settlement/mutations.js.map +1 -1
  221. package/dist/shared/refundCommandScope.d.ts +10 -0
  222. package/dist/shared/refundCommandScope.d.ts.map +1 -0
  223. package/dist/shared/refundCommandScope.js +9 -0
  224. package/dist/shared/refundCommandScope.js.map +1 -0
  225. package/docs/financial-observations.md +159 -0
  226. package/docs/financial-ownership.md +54 -0
  227. package/docs/personal-account-mapping.md +54 -0
  228. package/docs/refund-command-evidence.md +49 -0
  229. package/package.json +6 -2
  230. package/src/client/connect/refundCommandEvidence.ts +41 -0
  231. package/src/client/connect/refundCommandNormalization.ts +28 -0
  232. package/src/client/core/account-close-orchestration.test.ts +131 -0
  233. package/src/client/core/account-closure.test.ts +317 -0
  234. package/src/client/core/accountClosures.ts +37 -0
  235. package/src/client/core/accounts.test.ts +0 -111
  236. package/src/client/core/accounts.ts +24 -29
  237. package/src/client/core/personal-account-mapping.test.ts +71 -0
  238. package/src/client/core/personalAccountMapping.ts +23 -0
  239. package/src/client/financialObservations.test.ts +109 -0
  240. package/src/client/financialObservations.ts +106 -0
  241. package/src/client/financialOwnership.test.ts +80 -0
  242. package/src/client/financialOwnership.ts +116 -0
  243. package/src/client/index.ts +38 -35
  244. package/src/client/observationPagination.ts +11 -0
  245. package/src/client/publicTypes.ts +72 -0
  246. package/src/client/readContracts.ts +21 -0
  247. package/src/client/refund-command-evidence.test.ts +68 -0
  248. package/src/client/refund-command-normalization.test.ts +61 -0
  249. package/src/client/transferContinuation.test.ts +94 -0
  250. package/src/client/transferObservations.test.ts +98 -0
  251. package/src/client/transferObservations.ts +180 -0
  252. package/src/component/_generated/api.ts +52 -0
  253. package/src/component/_generated/component.ts +716 -0
  254. package/src/component/accountClosure/helpers.ts +21 -0
  255. package/src/component/accountClosure/mutations.ts +56 -0
  256. package/src/component/accountClosure/queries.ts +43 -0
  257. package/src/component/accountClosure/schema.ts +20 -0
  258. package/src/component/affiliateRecovery/mutations.ts +10 -1
  259. package/src/component/connect/mutations.ts +29 -2
  260. package/src/component/connect/reversalClaims.ts +19 -1
  261. package/src/component/connect/reversalReceipts.ts +2 -0
  262. package/src/component/connect/schema.ts +9 -1
  263. package/src/component/connect/validators.ts +2 -0
  264. package/src/component/core/mutations.ts +3 -0
  265. package/src/component/core/personal-account-mapping.test.ts +173 -0
  266. package/src/component/core/personalAccountMapping.ts +81 -0
  267. package/src/component/core/queries.ts +11 -0
  268. package/src/component/core/reset.test.ts +8 -1
  269. package/src/component/earnings/earnings-totals.test.ts +14 -10
  270. package/src/component/earnings/triggers.ts +9 -1
  271. package/src/component/financialObservations/continuation.test.ts +445 -0
  272. package/src/component/financialObservations/continuation.ts +159 -0
  273. package/src/component/financialObservations/generations.ts +53 -0
  274. package/src/component/financialObservations/mutations.ts +75 -0
  275. package/src/component/financialObservations/observation-boundaries.test.ts +466 -0
  276. package/src/component/financialObservations/queries.ts +246 -0
  277. package/src/component/financialObservations/schema.ts +68 -0
  278. package/src/component/financialObservations/settlement-observations.test.ts +86 -0
  279. package/src/component/financialObservations/settlement.ts +142 -0
  280. package/src/component/financialObservations/settlementHelpers.ts +92 -0
  281. package/src/component/financialObservations/transfer-batches.test.ts +61 -0
  282. package/src/component/financialObservations/transfer-boundaries.test.ts +116 -0
  283. package/src/component/financialObservations/transfer-continuation-guards.test.ts +428 -0
  284. package/src/component/financialObservations/transfer-continuation.test.ts +154 -0
  285. package/src/component/financialObservations/transfer-observations.test.ts +212 -0
  286. package/src/component/financialObservations/transfer-overflow.test.ts +181 -0
  287. package/src/component/financialObservations/transfer-writers.test.ts +162 -0
  288. package/src/component/financialObservations/transferBatches.ts +96 -0
  289. package/src/component/financialObservations/transferContinuation.ts +53 -0
  290. package/src/component/financialObservations/transferContinuationState.ts +85 -0
  291. package/src/component/financialObservations/transferContinuationSteps.ts +232 -0
  292. package/src/component/financialObservations/transferHelpers.ts +38 -0
  293. package/src/component/financialObservations/transferReferenceSchema.ts +20 -0
  294. package/src/component/financialObservations/transferSchema.ts +74 -0
  295. package/src/component/financialObservations/transfers.ts +99 -0
  296. package/src/component/financialOwnership/financial-ownership.test.ts +102 -0
  297. package/src/component/financialOwnership/helpers.ts +98 -0
  298. package/src/component/financialOwnership/mutations.ts +83 -0
  299. package/src/component/financialOwnership/ownership-boundaries.test.ts +308 -0
  300. package/src/component/financialOwnership/queries.ts +65 -0
  301. package/src/component/financialOwnership/schema.ts +35 -0
  302. package/src/component/refundHistory/command-evidence.test.ts +288 -0
  303. package/src/component/refundHistory/command-normalization-resource.test.ts +77 -0
  304. package/src/component/refundHistory/command-normalization.test.ts +229 -0
  305. package/src/component/refundHistory/command-provenance.test.ts +59 -0
  306. package/src/component/refundHistory/commandBinding.ts +54 -0
  307. package/src/component/refundHistory/commandEvidence.ts +71 -0
  308. package/src/component/refundHistory/commandEvidenceValidator.ts +18 -0
  309. package/src/component/refundHistory/commandFields.ts +9 -0
  310. package/src/component/refundHistory/mutations.ts +33 -0
  311. package/src/component/refundHistory/queries.ts +15 -0
  312. package/src/component/schema.ts +24 -0
  313. package/src/component/settlement/mutations.ts +5 -1
  314. package/src/shared/refundCommandScope.ts +19 -0
@@ -0,0 +1,109 @@
1
+ // @vitest-environment edge-runtime
2
+ import { componentRef } from "./webhooks/helpers.js";
3
+ import { expect, it, vi } from "vitest";
4
+ import schema from "../component/schema.js";
5
+ import { BetterStripe } from "./index.js";
6
+ import type { RunCtx } from "./helpers.js";
7
+ import { components, initConvexTest } from "./setup.test.js";
8
+
9
+ it("exposes UNKNOWN source and owner diagnostics through the actual component without Stripe credentials", async () => {
10
+ const t = initConvexTest();
11
+ t.registerComponent(
12
+ "betterStripe",
13
+ schema,
14
+ import.meta.glob("../component/**/*.ts"),
15
+ );
16
+ const client = new BetterStripe(components.betterStripe);
17
+ const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
18
+ await client.financialOwnership.register(ctx, {
19
+ bucketKey: "opaque",
20
+ kind: "logical",
21
+ userId: "user",
22
+ source: { integration: "host", recordId: "fact" },
23
+ });
24
+ const row = await t.mutation(
25
+ componentRef(
26
+ components.betterStripe,
27
+ "settlement/mutations/reserveSettlementAllocation",
28
+ ),
29
+ {
30
+ sourceChargeId: "ch_sdk",
31
+ gross: 3,
32
+ currency: "usd",
33
+ processingFee: 1,
34
+ platformNet: 1,
35
+ transfers: [{ destinationAccountId: "opaque", role: "store", amount: 1 }],
36
+ },
37
+ );
38
+ expect(
39
+ await client.financialObservations.source(ctx, { allocationId: row._id }),
40
+ ).toMatchObject({ coverage: "unknown", observation: { generation: 1 } });
41
+ const paginationOpts = { numItems: 25, cursor: null, id: 7 };
42
+ expect(
43
+ await client.financialObservations.owner(ctx, {
44
+ userId: "user",
45
+ paginationOpts,
46
+ }),
47
+ ).toMatchObject({
48
+ coverage: "unknown",
49
+ generation: 1,
50
+ page: [expect.objectContaining({ bucketKey: "opaque", userId: "user" })],
51
+ });
52
+ });
53
+ it.each([0, 101])(
54
+ "refuses page size %i before trusted dispatch",
55
+ async (numItems) => {
56
+ const client = new BetterStripe(components.betterStripe);
57
+ const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
58
+ await expect(
59
+ client.financialObservations.bucket(ctx, {
60
+ bucketKey: "opaque",
61
+ paginationOpts: { numItems, cursor: null },
62
+ }),
63
+ ).rejects.toThrow();
64
+ expect(ctx.runQuery).not.toHaveBeenCalled();
65
+ },
66
+ );
67
+ it("drains oversized raw reservations through the installed public client", async () => {
68
+ const t = initConvexTest();
69
+ t.registerComponent(
70
+ "betterStripe",
71
+ schema,
72
+ import.meta.glob("../component/**/*.ts"),
73
+ );
74
+ const client = new BetterStripe(components.betterStripe);
75
+ const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
76
+ const row = await t.mutation(
77
+ componentRef(
78
+ components.betterStripe,
79
+ "settlement/mutations/reserveSettlementAllocation",
80
+ ),
81
+ {
82
+ sourceChargeId: "ch_sdk_continue",
83
+ gross: 303,
84
+ currency: "usd",
85
+ processingFee: 1,
86
+ platformNet: 1,
87
+ transfers: Array.from({ length: 301 }, (_, i) => ({
88
+ destinationAccountId: `logical_${i}`,
89
+ role: "store",
90
+ amount: 1,
91
+ })),
92
+ },
93
+ );
94
+ let result = await client.financialObservations.source(ctx, {
95
+ allocationId: row._id,
96
+ });
97
+ while (result.observation?.continuation?.state !== "complete")
98
+ result = await client.financialObservations.resume(ctx, {
99
+ allocationId: row._id,
100
+ expectedGeneration: result.observation!.generation,
101
+ });
102
+ expect(result).toMatchObject({
103
+ coverage: "unknown",
104
+ observation: {
105
+ indexedLegCount: 301,
106
+ continuation: { state: "complete", validatedLegs: 301 },
107
+ },
108
+ });
109
+ });
@@ -0,0 +1,106 @@
1
+ import { TransferObservationsClient } from "./transferObservations.js";
2
+ import { observationPagination } from "./observationPagination.js";
3
+ import type { PaginationOptions, PaginationResult } from "convex/server";
4
+ import type { Infer } from "convex/values";
5
+ import { z } from "zod";
6
+ import {
7
+ assertOwner,
8
+ assertSelector,
9
+ } from "../component/financialOwnership/helpers.js";
10
+ import type {
11
+ legDoc,
12
+ sourceDoc,
13
+ } from "../component/financialObservations/schema.js";
14
+ import { InvoiceReadClient } from "./invoiceReads.js";
15
+ import type { Component, RunCtx } from "./helpers.js";
16
+ import { runMutationOrThrow } from "./helpers.js";
17
+ import { componentRef } from "./webhooks/helpers.js";
18
+
19
+ export type FinancialSourceObservation = Infer<typeof sourceDoc>;
20
+ export type FinancialSourceLeg = Infer<typeof legDoc>;
21
+ export type FinancialSourceResult = {
22
+ coverage: "unknown";
23
+ observation: FinancialSourceObservation | null;
24
+ };
25
+ export type FinancialObservationPage = PaginationResult<FinancialSourceLeg> & {
26
+ coverage: "unknown";
27
+ generation: number | null;
28
+ };
29
+ export type FinancialObservationOwner = { userId: string; orgId?: string };
30
+ /** Trusted host diagnostics only; neither caller selectors nor exhausted pages authorize closure. */
31
+ export class FinancialObservationsClient extends TransferObservationsClient {
32
+ constructor(component: Component) {
33
+ super(component);
34
+ }
35
+ async source(
36
+ ctx: RunCtx,
37
+ input: { allocationId: string },
38
+ ): Promise<FinancialSourceResult> {
39
+ const args = z
40
+ .object({ allocationId: z.string().min(1).max(256) })
41
+ .strict()
42
+ .parse(input);
43
+ return ctx.runQuery(
44
+ componentRef(this.component, "financialObservations/queries/source"),
45
+ args,
46
+ );
47
+ }
48
+ async resume(
49
+ ctx: RunCtx,
50
+ input: { allocationId: string; expectedGeneration: number },
51
+ ): Promise<FinancialSourceResult> {
52
+ const args = z
53
+ .object({
54
+ allocationId: z.string().min(1).max(256),
55
+ expectedGeneration: z
56
+ .number()
57
+ .int()
58
+ .min(1)
59
+ .max(Number.MAX_SAFE_INTEGER),
60
+ })
61
+ .strict()
62
+ .parse(input);
63
+ return runMutationOrThrow(
64
+ ctx,
65
+ componentRef(this.component, "financialObservations/mutations/resume"),
66
+ args,
67
+ );
68
+ }
69
+ async bucket(
70
+ ctx: RunCtx,
71
+ input: { bucketKey: string; paginationOpts: PaginationOptions },
72
+ ): Promise<FinancialObservationPage> {
73
+ const args = z
74
+ .object({ bucketKey: z.string(), paginationOpts: observationPagination })
75
+ .strict()
76
+ .parse(input);
77
+ assertSelector(args.bucketKey);
78
+ return ctx.runQuery(
79
+ componentRef(this.component, "financialObservations/queries/bucket"),
80
+ args,
81
+ );
82
+ }
83
+ async owner(
84
+ ctx: RunCtx,
85
+ input: FinancialObservationOwner & { paginationOpts: PaginationOptions },
86
+ ): Promise<FinancialObservationPage> {
87
+ const args = z
88
+ .object({
89
+ userId: z.string(),
90
+ orgId: z.string().optional(),
91
+ paginationOpts: observationPagination,
92
+ })
93
+ .strict()
94
+ .parse(input);
95
+ assertOwner(args);
96
+ return ctx.runQuery(
97
+ componentRef(this.component, "financialObservations/queries/owner"),
98
+ args,
99
+ );
100
+ }
101
+ }
102
+ export abstract class FinancialObservationsHost extends InvoiceReadClient {
103
+ readonly financialObservations = new FinancialObservationsClient(
104
+ this.component,
105
+ );
106
+ }
@@ -0,0 +1,80 @@
1
+ // @vitest-environment edge-runtime
2
+ import { describe, expect, it, vi } 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
+
8
+ const modules = import.meta.glob("../component/**/*.ts");
9
+ function fixture() {
10
+ const t = initConvexTest();
11
+ t.registerComponent("betterStripe", schema, modules);
12
+ return {
13
+ client: new BetterStripe(components.betterStripe),
14
+ ctx: { runQuery: t.query, runMutation: t.mutation } as RunCtx,
15
+ };
16
+ }
17
+ describe("public financial ownership client", () => {
18
+ it("registers and reads actual component provenance without configuring Stripe", async () => {
19
+ const { client, ctx } = fixture();
20
+ expect(
21
+ await client.financialOwnership.lookup(ctx, { bucketKey: "opaque" }),
22
+ ).toEqual({ status: "unknown", coverage: "unknown" });
23
+ const registered = await client.financialOwnership.register(ctx, {
24
+ bucketKey: "opaque",
25
+ kind: "logical",
26
+ userId: "user_one",
27
+ source: { integration: "trusted-host", recordId: "award_42" },
28
+ });
29
+ expect(
30
+ await client.financialOwnership.lookup(ctx, { bucketKey: "opaque" }),
31
+ ).toEqual(registered);
32
+ expect(
33
+ await client.financialOwnership.discover(ctx, {
34
+ userId: "user_one",
35
+ paginationOpts: { numItems: 10, cursor: null },
36
+ }),
37
+ ).toMatchObject({
38
+ coverage: "unknown",
39
+ generation: 1,
40
+ isDone: true,
41
+ page: [registered.registration],
42
+ });
43
+ });
44
+ it("preserves native pagination identity on trusted discovery callbacks", async () => {
45
+ const { client, ctx } = fixture();
46
+ const paginationOpts = { numItems: 10, cursor: null, id: 7 };
47
+ expect(
48
+ await client.financialOwnership.discover(ctx, {
49
+ userId: "user_one",
50
+ paginationOpts,
51
+ }),
52
+ ).toMatchObject({ coverage: "unknown", page: [] });
53
+ });
54
+ it.each(["", " leading", "x".repeat(257)])(
55
+ "rejects invalid selector %j before dispatch",
56
+ async (bucketKey) => {
57
+ const { client } = fixture();
58
+ const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
59
+ await expect(
60
+ client.financialOwnership.lookup(ctx, { bucketKey }),
61
+ ).rejects.toThrow();
62
+ expect(ctx.runQuery).not.toHaveBeenCalled();
63
+ },
64
+ );
65
+ it("rejects caller complete flags and physical proof fields before dispatch", async () => {
66
+ const { client } = fixture();
67
+ const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
68
+ const input = {
69
+ bucketKey: "acct_one",
70
+ kind: "stripe_account" as const,
71
+ userId: "user_one",
72
+ source: { integration: "forged", recordId: "forged" },
73
+ complete: true,
74
+ };
75
+ await expect(
76
+ client.financialOwnership.register(ctx, input),
77
+ ).rejects.toThrow();
78
+ expect(ctx.runMutation).not.toHaveBeenCalled();
79
+ });
80
+ });
@@ -0,0 +1,116 @@
1
+ import type { PaginationOptions, PaginationResult } from "convex/server";
2
+ import type { Infer } from "convex/values";
3
+ import { z } from "zod";
4
+ import {
5
+ assertOwner,
6
+ assertSelector,
7
+ } from "../component/financialOwnership/helpers.js";
8
+ import type { registrationDoc } from "../component/financialOwnership/schema.js";
9
+ import { FinancialObservationsHost } from "./financialObservations.js";
10
+ import type { Component, RunCtx } from "./helpers.js";
11
+ import { runMutationOrThrow } from "./helpers.js";
12
+ import { componentRef } from "./webhooks/helpers.js";
13
+
14
+ export type FinancialOwnershipRegistration = Infer<typeof registrationDoc>;
15
+ export type FinancialOwnershipResult =
16
+ | {
17
+ status: "registered";
18
+ coverage: "unknown";
19
+ registration: FinancialOwnershipRegistration;
20
+ }
21
+ | { status: "unknown"; coverage: "unknown" };
22
+ export type FinancialOwnershipOwner = { userId: string; orgId?: string };
23
+ export type RegisterFinancialOwnershipOptions = FinancialOwnershipOwner & {
24
+ bucketKey: string;
25
+ } & (
26
+ | { kind: "stripe_account" }
27
+ | { kind: "logical"; source: { integration: string; recordId: string } }
28
+ );
29
+ export type FinancialOwnershipPage =
30
+ PaginationResult<FinancialOwnershipRegistration> & {
31
+ coverage: "unknown";
32
+ generation: number;
33
+ };
34
+ const owner = { userId: z.string(), orgId: z.string().optional() };
35
+ const registrationInput = z.discriminatedUnion("kind", [
36
+ z
37
+ .object({
38
+ ...owner,
39
+ bucketKey: z.string(),
40
+ kind: z.literal("stripe_account"),
41
+ })
42
+ .strict(),
43
+ z
44
+ .object({
45
+ ...owner,
46
+ bucketKey: z.string(),
47
+ kind: z.literal("logical"),
48
+ source: z
49
+ .object({ integration: z.string(), recordId: z.string() })
50
+ .strict(),
51
+ })
52
+ .strict(),
53
+ ]);
54
+
55
+ /** Trusted host-server provenance only. Authenticate the actor and verify logical source ownership first. */
56
+ export class FinancialOwnershipClient {
57
+ constructor(private component: Component) {}
58
+ async register(
59
+ ctx: RunCtx,
60
+ input: RegisterFinancialOwnershipOptions,
61
+ ): Promise<Extract<FinancialOwnershipResult, { status: "registered" }>> {
62
+ const args = registrationInput.parse(input);
63
+ assertOwner(args);
64
+ assertSelector(args.bucketKey);
65
+ if (args.kind === "logical") {
66
+ assertSelector(args.source.integration);
67
+ assertSelector(args.source.recordId);
68
+ }
69
+ return runMutationOrThrow(
70
+ ctx,
71
+ componentRef(this.component, "financialOwnership/mutations/register"),
72
+ args,
73
+ );
74
+ }
75
+ async lookup(
76
+ ctx: RunCtx,
77
+ input: { bucketKey: string },
78
+ ): Promise<FinancialOwnershipResult> {
79
+ const args = z.object({ bucketKey: z.string() }).strict().parse(input);
80
+ assertSelector(args.bucketKey);
81
+ return ctx.runQuery(
82
+ componentRef(this.component, "financialOwnership/queries/lookup"),
83
+ args,
84
+ );
85
+ }
86
+ async discover(
87
+ ctx: RunCtx,
88
+ input: FinancialOwnershipOwner & { paginationOpts: PaginationOptions },
89
+ ): Promise<FinancialOwnershipPage> {
90
+ const args = z
91
+ .object({
92
+ ...owner,
93
+ paginationOpts: z
94
+ .object({
95
+ numItems: z.number().int().min(1).max(100),
96
+ cursor: z.string().nullable(),
97
+ id: z.number().optional(),
98
+ endCursor: z.string().nullable().optional(),
99
+ maximumRowsRead: z.number().optional(),
100
+ maximumBytesRead: z.number().optional(),
101
+ })
102
+ .strict(),
103
+ })
104
+ .strict()
105
+ .parse(input);
106
+ assertOwner(args);
107
+ return ctx.runQuery(
108
+ componentRef(this.component, "financialOwnership/queries/discover"),
109
+ args,
110
+ );
111
+ }
112
+ }
113
+ /** Extends the existing facade without expanding its frozen entry-file budget. */
114
+ export abstract class FinancialOwnershipHost extends FinancialObservationsHost {
115
+ readonly financialOwnership = new FinancialOwnershipClient(this.component);
116
+ }
@@ -1,3 +1,7 @@
1
+ import * as personalAccountMappingImpl from "./core/personalAccountMapping.js";
2
+ export type * from "./publicTypes.js";
3
+ import * as accountClosuresImpl from "./core/accountClosures.js";
4
+ import type { PaginationOptions } from "convex/server";
1
5
  import { reconcilePayoutAndTrigger } from "./webhooks/payoutReconciliation.js";
2
6
  import { AffiliateRecoveryClient } from "./affiliateRecovery.js";
3
7
  export * from "./affiliateRecovery.js";
@@ -14,7 +18,7 @@ import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js"
14
18
  export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
15
19
  import * as intentsImpl from "./billing/intents.js";
16
20
  export type * from "./billing/intents.js";
17
- import { InvoiceReadClient } from "./invoiceReads.js";
21
+ import { FinancialOwnershipHost } from "./financialOwnership.js";
18
22
  import { CostRecoveryClient } from "./costRecovery.js";
19
23
  export * from "./charge-currency.js";
20
24
  export * from "./costRecovery.js";
@@ -190,48 +194,15 @@ export type {
190
194
  BetterStripeWebhookEvent,
191
195
  } from "./utils/webhookEndpoints.js";
192
196
  // Re-export types for consumers
193
- export type {
194
- BetterStripeOptions,
195
- FeeOverride,
196
- FeeTier,
197
- PlatformFeeConfig,
198
- RegisterRoutesConfig,
199
- } from "./types.js";
200
197
  export type {
201
198
  StripeDashboardResourceType,
202
199
  StripeMode,
203
200
  } from "./utils/stripeDashboardUrl.js";
204
- export type {
205
- AccountLinkWithStatus,
206
- AsyncHookCtx,
207
- AsyncHooks,
208
- PaymentMethodCard,
209
- PaymentMethodLike,
210
- StripeComponentAccount,
211
- StripeComponentCheckoutSession,
212
- StripeComponentDispute,
213
- StripeComponentInvoice,
214
- StripeComponentPayment,
215
- StripeComponentPayout,
216
- StripeComponentPrice,
217
- StripeComponentProduct,
218
- StripeComponentRefund,
219
- StripeComponentSubscription,
220
- StripeCountrySpecs,
221
- StripeEventHandler,
222
- StripeEventHandlers,
223
- StripeV2Account,
224
- StripeWebhookEvent,
225
- SyncTriggerCtx,
226
- SyncTriggers,
227
- V2ThinEvent,
228
- WebhookActionCtx,
229
- } from "./types.js";
230
201
  export type BetterStripeComponent = ComponentApi;
231
202
 
232
203
  // BETTER STRIPE CLIENT
233
204
 
234
- export class BetterStripe extends InvoiceReadClient {
205
+ export class BetterStripe extends FinancialOwnershipHost {
235
206
  readonly stripeApiVersion: SupportedStripeApiVersion;
236
207
  private _apiKey?: string;
237
208
  private _triggers?: SyncTriggers;
@@ -368,6 +339,38 @@ export class BetterStripe extends InvoiceReadClient {
368
339
  return accountsImpl.getAccountByUserId(this.component, ctx, opts);
369
340
  }
370
341
 
342
+ /** Unambiguous personal mapping only; host authentication and provider usability remain separate. */
343
+ getPersonalAccountMapping(ctx: RunCtx, opts: { userId: string }) {
344
+ return personalAccountMappingImpl.getPersonalAccountMapping(
345
+ this.component,
346
+ ctx,
347
+ opts,
348
+ );
349
+ }
350
+
351
+ /** Authenticate the host actor before consulting closed-account provenance. */
352
+ async getClosedAccountByStripeId(
353
+ ctx: RunCtx,
354
+ opts: { stripeAccountId: string },
355
+ ) {
356
+ return accountClosuresImpl.getClosedAccountByStripeId(
357
+ this.component,
358
+ ctx,
359
+ opts,
360
+ );
361
+ }
362
+
363
+ async listClosedAccountsByUserId(
364
+ ctx: RunCtx,
365
+ opts: { userId: string; paginationOpts: PaginationOptions },
366
+ ) {
367
+ return accountClosuresImpl.listClosedAccountsByUserId(
368
+ this.component,
369
+ ctx,
370
+ opts,
371
+ );
372
+ }
373
+
371
374
  async getAccountByOrgId(
372
375
  ctx: RunCtx,
373
376
  opts: { orgId: string },
@@ -0,0 +1,11 @@
1
+ import { z } from "zod";
2
+ export const observationPagination = z
3
+ .object({
4
+ numItems: z.number().int().min(1).max(100),
5
+ cursor: z.string().nullable(),
6
+ id: z.number().optional(),
7
+ endCursor: z.string().nullable().optional(),
8
+ maximumRowsRead: z.number().optional(),
9
+ maximumBytesRead: z.number().optional(),
10
+ })
11
+ .strict();
@@ -0,0 +1,72 @@
1
+ export type { StripeAccountClosure } from "./core/accountClosures.js";
2
+ export type {
3
+ BetterStripeOptions,
4
+ FeeOverride,
5
+ FeeTier,
6
+ PlatformFeeConfig,
7
+ RegisterRoutesConfig,
8
+ } from "./types.js";
9
+ export type {
10
+ AccountLinkWithStatus,
11
+ AsyncHookCtx,
12
+ AsyncHooks,
13
+ PaymentMethodCard,
14
+ PaymentMethodLike,
15
+ StripeComponentAccount,
16
+ StripeComponentCheckoutSession,
17
+ StripeComponentDispute,
18
+ StripeComponentInvoice,
19
+ StripeComponentPayment,
20
+ StripeComponentPayout,
21
+ StripeComponentPrice,
22
+ StripeComponentProduct,
23
+ StripeComponentRefund,
24
+ StripeComponentSubscription,
25
+ StripeCountrySpecs,
26
+ StripeEventHandler,
27
+ StripeEventHandlers,
28
+ StripeV2Account,
29
+ StripeWebhookEvent,
30
+ SyncTriggerCtx,
31
+ SyncTriggers,
32
+ V2ThinEvent,
33
+ WebhookActionCtx,
34
+ } from "./types.js";
35
+ export type { PersonalAccountMapping } from "./core/personalAccountMapping.js";
36
+
37
+ export type {
38
+ FinancialOwnershipOwner,
39
+ FinancialOwnershipRegistration,
40
+ FinancialOwnershipResult,
41
+ FinancialOwnershipPage,
42
+ RegisterFinancialOwnershipOptions,
43
+ } from "./financialOwnership.js";
44
+
45
+ export type {
46
+ FinancialSourceObservation,
47
+ FinancialSourceLeg,
48
+ FinancialSourceResult,
49
+ FinancialObservationPage,
50
+ FinancialObservationOwner,
51
+ } from "./financialObservations.js";
52
+
53
+ export type {
54
+ RefundCommandEvidence,
55
+ RefundCommandEvidenceOptions,
56
+ } from "./connect/refundCommandEvidence.js";
57
+ export type {
58
+ FinancialTransferObservation,
59
+ FinancialTransferBatch,
60
+ FinancialTransferReadState,
61
+ FinancialTransferResult,
62
+ FinancialTransferPage,
63
+ FinancialTransferBatchPage,
64
+ FinancialTransferReference,
65
+ FinancialTransferBatchResult,
66
+ FinancialTransferReferencePage,
67
+ } from "./transferObservations.js";
68
+
69
+ export type {
70
+ RefundCommandNormalizationOptions,
71
+ RefundCommandNormalizationResult,
72
+ } from "./connect/refundCommandNormalization.js";
@@ -1,3 +1,11 @@
1
+ import {
2
+ normalizeRefundCommandBindings,
3
+ type RefundCommandNormalizationOptions,
4
+ } from "./connect/refundCommandNormalization.js";
5
+ import {
6
+ getRefundCommandEvidence,
7
+ type RefundCommandEvidenceOptions,
8
+ } from "./connect/refundCommandEvidence.js";
1
9
  import * as checkoutImpl from "./billing/checkout.js";
2
10
  import * as subscriptionsImpl from "./billing/subscriptions.js";
3
11
  import * as payoutsImpl from "./connect/payouts.js";
@@ -15,6 +23,19 @@ import { componentRef } from "./webhooks/helpers.js";
15
23
  /** Shared component readers inherited by BetterStripe. */
16
24
  export class ReadContractClient {
17
25
  constructor(public component: Component) {}
26
+
27
+ /** Trusted-host projection maintenance; never a financial or provider operation. */
28
+ normalizeRefundCommandBindings(
29
+ ctx: RunCtx,
30
+ opts: RefundCommandNormalizationOptions,
31
+ ) {
32
+ return normalizeRefundCommandBindings(this.component, ctx, opts);
33
+ }
34
+
35
+ /** Exact component observation only; callers authorize and bind original commands. */
36
+ getRefundCommandEvidence(ctx: RunCtx, opts: RefundCommandEvidenceOptions) {
37
+ return getRefundCommandEvidence(this.component, ctx, opts);
38
+ }
18
39
  async paginateProducts(
19
40
  ctx: RunCtx,
20
41
  opts: {