@fantastic.dev/better-stripe 0.4.0-bootstrap.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 (762) hide show
  1. package/CHANGELOG.md +318 -0
  2. package/README.md +1117 -0
  3. package/dist/client/billing/checkout.d.ts +75 -0
  4. package/dist/client/billing/checkout.d.ts.map +1 -0
  5. package/dist/client/billing/checkout.js +260 -0
  6. package/dist/client/billing/checkout.js.map +1 -0
  7. package/dist/client/billing/invoices.d.ts +37 -0
  8. package/dist/client/billing/invoices.d.ts.map +1 -0
  9. package/dist/client/billing/invoices.js +29 -0
  10. package/dist/client/billing/invoices.js.map +1 -0
  11. package/dist/client/billing/subscriptions.d.ts +179 -0
  12. package/dist/client/billing/subscriptions.d.ts.map +1 -0
  13. package/dist/client/billing/subscriptions.js +346 -0
  14. package/dist/client/billing/subscriptions.js.map +1 -0
  15. package/dist/client/connect/disputes.d.ts +112 -0
  16. package/dist/client/connect/disputes.d.ts.map +1 -0
  17. package/dist/client/connect/disputes.js +186 -0
  18. package/dist/client/connect/disputes.js.map +1 -0
  19. package/dist/client/connect/paymentMethodUtils.d.ts +17 -0
  20. package/dist/client/connect/paymentMethodUtils.d.ts.map +1 -0
  21. package/dist/client/connect/paymentMethodUtils.js +24 -0
  22. package/dist/client/connect/paymentMethodUtils.js.map +1 -0
  23. package/dist/client/connect/paymentMethods.d.ts +23 -0
  24. package/dist/client/connect/paymentMethods.d.ts.map +1 -0
  25. package/dist/client/connect/paymentMethods.js +27 -0
  26. package/dist/client/connect/paymentMethods.js.map +1 -0
  27. package/dist/client/connect/payouts.d.ts +47 -0
  28. package/dist/client/connect/payouts.d.ts.map +1 -0
  29. package/dist/client/connect/payouts.js +52 -0
  30. package/dist/client/connect/payouts.js.map +1 -0
  31. package/dist/client/connect/refundActor.d.ts +50 -0
  32. package/dist/client/connect/refundActor.d.ts.map +1 -0
  33. package/dist/client/connect/refundActor.js +17 -0
  34. package/dist/client/connect/refundActor.js.map +1 -0
  35. package/dist/client/connect/refunds.d.ts +75 -0
  36. package/dist/client/connect/refunds.d.ts.map +1 -0
  37. package/dist/client/connect/refunds.js +141 -0
  38. package/dist/client/connect/refunds.js.map +1 -0
  39. package/dist/client/connect/transfers.d.ts +189 -0
  40. package/dist/client/connect/transfers.d.ts.map +1 -0
  41. package/dist/client/connect/transfers.js +347 -0
  42. package/dist/client/connect/transfers.js.map +1 -0
  43. package/dist/client/constants.d.ts +15 -0
  44. package/dist/client/constants.d.ts.map +1 -0
  45. package/dist/client/constants.js +14 -0
  46. package/dist/client/constants.js.map +1 -0
  47. package/dist/client/core/accountLinks.d.ts +68 -0
  48. package/dist/client/core/accountLinks.d.ts.map +1 -0
  49. package/dist/client/core/accountLinks.js +131 -0
  50. package/dist/client/core/accountLinks.js.map +1 -0
  51. package/dist/client/core/accountStatus.d.ts +12 -0
  52. package/dist/client/core/accountStatus.d.ts.map +1 -0
  53. package/dist/client/core/accountStatus.js +56 -0
  54. package/dist/client/core/accountStatus.js.map +1 -0
  55. package/dist/client/core/accounts.d.ts +181 -0
  56. package/dist/client/core/accounts.d.ts.map +1 -0
  57. package/dist/client/core/accounts.js +359 -0
  58. package/dist/client/core/accounts.js.map +1 -0
  59. package/dist/client/core/config.d.ts +5 -0
  60. package/dist/client/core/config.d.ts.map +1 -0
  61. package/dist/client/core/config.js +11 -0
  62. package/dist/client/core/config.js.map +1 -0
  63. package/dist/client/core/descriptors.d.ts +24 -0
  64. package/dist/client/core/descriptors.d.ts.map +1 -0
  65. package/dist/client/core/descriptors.js +43 -0
  66. package/dist/client/core/descriptors.js.map +1 -0
  67. package/dist/client/core/fees.d.ts +83 -0
  68. package/dist/client/core/fees.d.ts.map +1 -0
  69. package/dist/client/core/fees.js +178 -0
  70. package/dist/client/core/fees.js.map +1 -0
  71. package/dist/client/errors.d.ts +20 -0
  72. package/dist/client/errors.d.ts.map +1 -0
  73. package/dist/client/errors.js +31 -0
  74. package/dist/client/errors.js.map +1 -0
  75. package/dist/client/helpers.d.ts +20 -0
  76. package/dist/client/helpers.d.ts.map +1 -0
  77. package/dist/client/helpers.js +46 -0
  78. package/dist/client/helpers.js.map +1 -0
  79. package/dist/client/index.d.ts +880 -0
  80. package/dist/client/index.d.ts.map +1 -0
  81. package/dist/client/index.js +791 -0
  82. package/dist/client/index.js.map +1 -0
  83. package/dist/client/products/prices.d.ts +61 -0
  84. package/dist/client/products/prices.d.ts.map +1 -0
  85. package/dist/client/products/prices.js +92 -0
  86. package/dist/client/products/prices.js.map +1 -0
  87. package/dist/client/products/products.d.ts +65 -0
  88. package/dist/client/products/products.d.ts.map +1 -0
  89. package/dist/client/products/products.js +186 -0
  90. package/dist/client/products/products.js.map +1 -0
  91. package/dist/client/stripe-types.d.ts +44 -0
  92. package/dist/client/stripe-types.d.ts.map +1 -0
  93. package/dist/client/stripe-types.js +2 -0
  94. package/dist/client/stripe-types.js.map +1 -0
  95. package/dist/client/types/documents.d.ts +195 -0
  96. package/dist/client/types/documents.d.ts.map +1 -0
  97. package/dist/client/types/documents.js +2 -0
  98. package/dist/client/types/documents.js.map +1 -0
  99. package/dist/client/types/events.d.ts +43 -0
  100. package/dist/client/types/events.d.ts.map +1 -0
  101. package/dist/client/types/events.js +2 -0
  102. package/dist/client/types/events.js.map +1 -0
  103. package/dist/client/types/index.d.ts +5 -0
  104. package/dist/client/types/index.d.ts.map +1 -0
  105. package/dist/client/types/index.js +2 -0
  106. package/dist/client/types/index.js.map +1 -0
  107. package/dist/client/types/options.d.ts +79 -0
  108. package/dist/client/types/options.d.ts.map +1 -0
  109. package/dist/client/types/options.js +2 -0
  110. package/dist/client/types/options.js.map +1 -0
  111. package/dist/client/types/triggers.d.ts +101 -0
  112. package/dist/client/types/triggers.d.ts.map +1 -0
  113. package/dist/client/types/triggers.js +2 -0
  114. package/dist/client/types/triggers.js.map +1 -0
  115. package/dist/client/types.d.ts +2 -0
  116. package/dist/client/types.d.ts.map +1 -0
  117. package/dist/client/types.js +2 -0
  118. package/dist/client/types.js.map +1 -0
  119. package/dist/client/utils/data.d.ts +10 -0
  120. package/dist/client/utils/data.d.ts.map +1 -0
  121. package/dist/client/utils/data.js +13 -0
  122. package/dist/client/utils/data.js.map +1 -0
  123. package/dist/client/utils/owner.d.ts +22 -0
  124. package/dist/client/utils/owner.d.ts.map +1 -0
  125. package/dist/client/utils/owner.js +20 -0
  126. package/dist/client/utils/owner.js.map +1 -0
  127. package/dist/client/utils/stripeDashboardUrl.d.ts +12 -0
  128. package/dist/client/utils/stripeDashboardUrl.d.ts.map +1 -0
  129. package/dist/client/utils/stripeDashboardUrl.js +39 -0
  130. package/dist/client/utils/stripeDashboardUrl.js.map +1 -0
  131. package/dist/client/utils/webhookEndpoints.d.ts +83 -0
  132. package/dist/client/utils/webhookEndpoints.d.ts.map +1 -0
  133. package/dist/client/utils/webhookEndpoints.js +185 -0
  134. package/dist/client/utils/webhookEndpoints.js.map +1 -0
  135. package/dist/client/webhooks/handler.d.ts +4 -0
  136. package/dist/client/webhooks/handler.d.ts.map +1 -0
  137. package/dist/client/webhooks/handler.js +170 -0
  138. package/dist/client/webhooks/handler.js.map +1 -0
  139. package/dist/client/webhooks/helpers.d.ts +56 -0
  140. package/dist/client/webhooks/helpers.d.ts.map +1 -0
  141. package/dist/client/webhooks/helpers.js +229 -0
  142. package/dist/client/webhooks/helpers.js.map +1 -0
  143. package/dist/client/webhooks/hooks.d.ts +11 -0
  144. package/dist/client/webhooks/hooks.d.ts.map +1 -0
  145. package/dist/client/webhooks/hooks.js +134 -0
  146. package/dist/client/webhooks/hooks.js.map +1 -0
  147. package/dist/client/webhooks/index.d.ts +23 -0
  148. package/dist/client/webhooks/index.d.ts.map +1 -0
  149. package/dist/client/webhooks/index.js +35 -0
  150. package/dist/client/webhooks/index.js.map +1 -0
  151. package/dist/client/webhooks/processors.d.ts +4 -0
  152. package/dist/client/webhooks/processors.d.ts.map +1 -0
  153. package/dist/client/webhooks/processors.js +932 -0
  154. package/dist/client/webhooks/processors.js.map +1 -0
  155. package/dist/client/webhooks/v2.d.ts +11 -0
  156. package/dist/client/webhooks/v2.d.ts.map +1 -0
  157. package/dist/client/webhooks/v2.js +94 -0
  158. package/dist/client/webhooks/v2.js.map +1 -0
  159. package/dist/client/webhooks.d.ts +2 -0
  160. package/dist/client/webhooks.d.ts.map +1 -0
  161. package/dist/client/webhooks.js +4 -0
  162. package/dist/client/webhooks.js.map +1 -0
  163. package/dist/component/_generated/component.d.ts +1262 -0
  164. package/dist/component/_generated/component.d.ts.map +1 -0
  165. package/dist/component/_generated/component.js +11 -0
  166. package/dist/component/_generated/component.js.map +1 -0
  167. package/dist/component/_generated/dataModel.d.ts +46 -0
  168. package/dist/component/_generated/dataModel.d.ts.map +1 -0
  169. package/dist/component/_generated/dataModel.js +11 -0
  170. package/dist/component/_generated/dataModel.js.map +1 -0
  171. package/dist/component/_generated/server.d.ts +129 -0
  172. package/dist/component/_generated/server.d.ts.map +1 -0
  173. package/dist/component/_generated/server.js +79 -0
  174. package/dist/component/_generated/server.js.map +1 -0
  175. package/dist/component/billing/mutations.d.ts +86 -0
  176. package/dist/component/billing/mutations.d.ts.map +1 -0
  177. package/dist/component/billing/mutations.js +131 -0
  178. package/dist/component/billing/mutations.js.map +1 -0
  179. package/dist/component/billing/queries.d.ts +425 -0
  180. package/dist/component/billing/queries.d.ts.map +1 -0
  181. package/dist/component/billing/queries.js +304 -0
  182. package/dist/component/billing/queries.js.map +1 -0
  183. package/dist/component/billing/schema.d.ts +228 -0
  184. package/dist/component/billing/schema.d.ts.map +1 -0
  185. package/dist/component/billing/schema.js +33 -0
  186. package/dist/component/billing/schema.js.map +1 -0
  187. package/dist/component/billing/validators.d.ts +364 -0
  188. package/dist/component/billing/validators.d.ts.map +1 -0
  189. package/dist/component/billing/validators.js +98 -0
  190. package/dist/component/billing/validators.js.map +1 -0
  191. package/dist/component/connect/mutations.d.ts +182 -0
  192. package/dist/component/connect/mutations.d.ts.map +1 -0
  193. package/dist/component/connect/mutations.js +480 -0
  194. package/dist/component/connect/mutations.js.map +1 -0
  195. package/dist/component/connect/queries.d.ts +347 -0
  196. package/dist/component/connect/queries.d.ts.map +1 -0
  197. package/dist/component/connect/queries.js +449 -0
  198. package/dist/component/connect/queries.js.map +1 -0
  199. package/dist/component/connect/schema.d.ts +258 -0
  200. package/dist/component/connect/schema.d.ts.map +1 -0
  201. package/dist/component/connect/schema.js +70 -0
  202. package/dist/component/connect/schema.js.map +1 -0
  203. package/dist/component/connect/validators.d.ts +468 -0
  204. package/dist/component/connect/validators.d.ts.map +1 -0
  205. package/dist/component/connect/validators.js +250 -0
  206. package/dist/component/connect/validators.js.map +1 -0
  207. package/dist/component/convex.config.d.ts +5 -0
  208. package/dist/component/convex.config.d.ts.map +1 -0
  209. package/dist/component/convex.config.js +17 -0
  210. package/dist/component/convex.config.js.map +1 -0
  211. package/dist/component/core/mutations.d.ts +52 -0
  212. package/dist/component/core/mutations.d.ts.map +1 -0
  213. package/dist/component/core/mutations.js +153 -0
  214. package/dist/component/core/mutations.js.map +1 -0
  215. package/dist/component/core/queries.d.ts +95 -0
  216. package/dist/component/core/queries.d.ts.map +1 -0
  217. package/dist/component/core/queries.js +86 -0
  218. package/dist/component/core/queries.js.map +1 -0
  219. package/dist/component/core/schema.d.ts +41 -0
  220. package/dist/component/core/schema.d.ts.map +1 -0
  221. package/dist/component/core/schema.js +12 -0
  222. package/dist/component/core/schema.js.map +1 -0
  223. package/dist/component/core/validators.d.ts +65 -0
  224. package/dist/component/core/validators.d.ts.map +1 -0
  225. package/dist/component/core/validators.js +35 -0
  226. package/dist/component/core/validators.js.map +1 -0
  227. package/dist/component/lib/fees.d.ts +74 -0
  228. package/dist/component/lib/fees.d.ts.map +1 -0
  229. package/dist/component/lib/fees.js +51 -0
  230. package/dist/component/lib/fees.js.map +1 -0
  231. package/dist/component/lib/idempotency.d.ts +9 -0
  232. package/dist/component/lib/idempotency.d.ts.map +1 -0
  233. package/dist/component/lib/idempotency.js +18 -0
  234. package/dist/component/lib/idempotency.js.map +1 -0
  235. package/dist/component/lib/reversals.d.ts +48 -0
  236. package/dist/component/lib/reversals.d.ts.map +1 -0
  237. package/dist/component/lib/reversals.js +79 -0
  238. package/dist/component/lib/reversals.js.map +1 -0
  239. package/dist/component/lib/stripeFactory.d.ts +7 -0
  240. package/dist/component/lib/stripeFactory.d.ts.map +1 -0
  241. package/dist/component/lib/stripeFactory.js +28 -0
  242. package/dist/component/lib/stripeFactory.js.map +1 -0
  243. package/dist/component/products/mutations.d.ts +22 -0
  244. package/dist/component/products/mutations.d.ts.map +1 -0
  245. package/dist/component/products/mutations.js +63 -0
  246. package/dist/component/products/mutations.js.map +1 -0
  247. package/dist/component/products/queries.d.ts +109 -0
  248. package/dist/component/products/queries.d.ts.map +1 -0
  249. package/dist/component/products/queries.js +122 -0
  250. package/dist/component/products/queries.js.map +1 -0
  251. package/dist/component/products/schema.d.ts +58 -0
  252. package/dist/component/products/schema.d.ts.map +1 -0
  253. package/dist/component/products/schema.js +20 -0
  254. package/dist/component/products/schema.js.map +1 -0
  255. package/dist/component/products/validators.d.ts +86 -0
  256. package/dist/component/products/validators.d.ts.map +1 -0
  257. package/dist/component/products/validators.js +47 -0
  258. package/dist/component/products/validators.js.map +1 -0
  259. package/dist/component/schema.d.ts +555 -0
  260. package/dist/component/schema.d.ts.map +1 -0
  261. package/dist/component/schema.js +28 -0
  262. package/dist/component/schema.js.map +1 -0
  263. package/dist/component/webhooks/mutations.d.ts +30 -0
  264. package/dist/component/webhooks/mutations.d.ts.map +1 -0
  265. package/dist/component/webhooks/mutations.js +124 -0
  266. package/dist/component/webhooks/mutations.js.map +1 -0
  267. package/dist/component/webhooks/queries.d.ts +35 -0
  268. package/dist/component/webhooks/queries.d.ts.map +1 -0
  269. package/dist/component/webhooks/queries.js +41 -0
  270. package/dist/component/webhooks/queries.js.map +1 -0
  271. package/dist/component/webhooks/schema.d.ts +22 -0
  272. package/dist/component/webhooks/schema.d.ts.map +1 -0
  273. package/dist/component/webhooks/schema.js +9 -0
  274. package/dist/component/webhooks/schema.js.map +1 -0
  275. package/dist/component/webhooks/validators.d.ts +37 -0
  276. package/dist/component/webhooks/validators.d.ts.map +1 -0
  277. package/dist/component/webhooks/validators.js +22 -0
  278. package/dist/component/webhooks/validators.js.map +1 -0
  279. package/dist/react/components/AccountCloseButton.d.ts +42 -0
  280. package/dist/react/components/AccountCloseButton.d.ts.map +1 -0
  281. package/dist/react/components/AccountCloseButton.js +33 -0
  282. package/dist/react/components/AccountCloseButton.js.map +1 -0
  283. package/dist/react/components/AccountCloseCard.d.ts +31 -0
  284. package/dist/react/components/AccountCloseCard.d.ts.map +1 -0
  285. package/dist/react/components/AccountCloseCard.js +22 -0
  286. package/dist/react/components/AccountCloseCard.js.map +1 -0
  287. package/dist/react/components/AccountCreateButton.d.ts +37 -0
  288. package/dist/react/components/AccountCreateButton.d.ts.map +1 -0
  289. package/dist/react/components/AccountCreateButton.js +30 -0
  290. package/dist/react/components/AccountCreateButton.js.map +1 -0
  291. package/dist/react/components/AccountCreateCard.d.ts +48 -0
  292. package/dist/react/components/AccountCreateCard.d.ts.map +1 -0
  293. package/dist/react/components/AccountCreateCard.js +29 -0
  294. package/dist/react/components/AccountCreateCard.js.map +1 -0
  295. package/dist/react/components/AccountLoginButton.d.ts +31 -0
  296. package/dist/react/components/AccountLoginButton.d.ts.map +1 -0
  297. package/dist/react/components/AccountLoginButton.js +31 -0
  298. package/dist/react/components/AccountLoginButton.js.map +1 -0
  299. package/dist/react/components/AccountLoginCard.d.ts +33 -0
  300. package/dist/react/components/AccountLoginCard.d.ts.map +1 -0
  301. package/dist/react/components/AccountLoginCard.js +19 -0
  302. package/dist/react/components/AccountLoginCard.js.map +1 -0
  303. package/dist/react/components/AccountOnboardingButton.d.ts +37 -0
  304. package/dist/react/components/AccountOnboardingButton.d.ts.map +1 -0
  305. package/dist/react/components/AccountOnboardingButton.js +30 -0
  306. package/dist/react/components/AccountOnboardingButton.js.map +1 -0
  307. package/dist/react/components/AccountOnboardingCard.d.ts +56 -0
  308. package/dist/react/components/AccountOnboardingCard.d.ts.map +1 -0
  309. package/dist/react/components/AccountOnboardingCard.js +36 -0
  310. package/dist/react/components/AccountOnboardingCard.js.map +1 -0
  311. package/dist/react/components/AddCardForm.d.ts +18 -0
  312. package/dist/react/components/AddCardForm.d.ts.map +1 -0
  313. package/dist/react/components/AddCardForm.js +49 -0
  314. package/dist/react/components/AddCardForm.js.map +1 -0
  315. package/dist/react/components/BillingPortalLink.d.ts +23 -0
  316. package/dist/react/components/BillingPortalLink.d.ts.map +1 -0
  317. package/dist/react/components/BillingPortalLink.js +55 -0
  318. package/dist/react/components/BillingPortalLink.js.map +1 -0
  319. package/dist/react/components/BuyerBillingView.d.ts +80 -0
  320. package/dist/react/components/BuyerBillingView.d.ts.map +1 -0
  321. package/dist/react/components/BuyerBillingView.js +44 -0
  322. package/dist/react/components/BuyerBillingView.js.map +1 -0
  323. package/dist/react/components/CheckoutSessionProvider.d.ts +34 -0
  324. package/dist/react/components/CheckoutSessionProvider.d.ts.map +1 -0
  325. package/dist/react/components/CheckoutSessionProvider.js +38 -0
  326. package/dist/react/components/CheckoutSessionProvider.js.map +1 -0
  327. package/dist/react/components/CheckoutSessionProviderWithKey.d.ts +36 -0
  328. package/dist/react/components/CheckoutSessionProviderWithKey.d.ts.map +1 -0
  329. package/dist/react/components/CheckoutSessionProviderWithKey.js +36 -0
  330. package/dist/react/components/CheckoutSessionProviderWithKey.js.map +1 -0
  331. package/dist/react/components/CheckoutStatus.d.ts +25 -0
  332. package/dist/react/components/CheckoutStatus.d.ts.map +1 -0
  333. package/dist/react/components/CheckoutStatus.js +22 -0
  334. package/dist/react/components/CheckoutStatus.js.map +1 -0
  335. package/dist/react/components/ConnectProvider.d.ts +29 -0
  336. package/dist/react/components/ConnectProvider.d.ts.map +1 -0
  337. package/dist/react/components/ConnectProvider.js +25 -0
  338. package/dist/react/components/ConnectProvider.js.map +1 -0
  339. package/dist/react/components/ConnectRequirements.d.ts +55 -0
  340. package/dist/react/components/ConnectRequirements.d.ts.map +1 -0
  341. package/dist/react/components/ConnectRequirements.js +58 -0
  342. package/dist/react/components/ConnectRequirements.js.map +1 -0
  343. package/dist/react/components/ConnectStatusBadge.d.ts +26 -0
  344. package/dist/react/components/ConnectStatusBadge.d.ts.map +1 -0
  345. package/dist/react/components/ConnectStatusBadge.js +20 -0
  346. package/dist/react/components/ConnectStatusBadge.js.map +1 -0
  347. package/dist/react/components/DeletePaymentMethodDialog.d.ts +25 -0
  348. package/dist/react/components/DeletePaymentMethodDialog.d.ts.map +1 -0
  349. package/dist/react/components/DeletePaymentMethodDialog.js +16 -0
  350. package/dist/react/components/DeletePaymentMethodDialog.js.map +1 -0
  351. package/dist/react/components/DisputeDetail.d.ts +42 -0
  352. package/dist/react/components/DisputeDetail.d.ts.map +1 -0
  353. package/dist/react/components/DisputeDetail.js +34 -0
  354. package/dist/react/components/DisputeDetail.js.map +1 -0
  355. package/dist/react/components/DisputesList.d.ts +42 -0
  356. package/dist/react/components/DisputesList.d.ts.map +1 -0
  357. package/dist/react/components/DisputesList.js +47 -0
  358. package/dist/react/components/DisputesList.js.map +1 -0
  359. package/dist/react/components/EarningsSummary.d.ts +53 -0
  360. package/dist/react/components/EarningsSummary.d.ts.map +1 -0
  361. package/dist/react/components/EarningsSummary.js +37 -0
  362. package/dist/react/components/EarningsSummary.js.map +1 -0
  363. package/dist/react/components/EmbeddedCheckout.d.ts +18 -0
  364. package/dist/react/components/EmbeddedCheckout.d.ts.map +1 -0
  365. package/dist/react/components/EmbeddedCheckout.js +17 -0
  366. package/dist/react/components/EmbeddedCheckout.js.map +1 -0
  367. package/dist/react/components/EmbeddedDisputes.d.ts +21 -0
  368. package/dist/react/components/EmbeddedDisputes.d.ts.map +1 -0
  369. package/dist/react/components/EmbeddedDisputes.js +17 -0
  370. package/dist/react/components/EmbeddedDisputes.js.map +1 -0
  371. package/dist/react/components/EvidenceForm.d.ts +63 -0
  372. package/dist/react/components/EvidenceForm.d.ts.map +1 -0
  373. package/dist/react/components/EvidenceForm.js +79 -0
  374. package/dist/react/components/EvidenceForm.js.map +1 -0
  375. package/dist/react/components/IntervalSelector.d.ts +20 -0
  376. package/dist/react/components/IntervalSelector.d.ts.map +1 -0
  377. package/dist/react/components/IntervalSelector.js +15 -0
  378. package/dist/react/components/IntervalSelector.js.map +1 -0
  379. package/dist/react/components/PaymentMethodActions.d.ts +27 -0
  380. package/dist/react/components/PaymentMethodActions.d.ts.map +1 -0
  381. package/dist/react/components/PaymentMethodActions.js +23 -0
  382. package/dist/react/components/PaymentMethodActions.js.map +1 -0
  383. package/dist/react/components/PaymentMethodsList.d.ts +32 -0
  384. package/dist/react/components/PaymentMethodsList.d.ts.map +1 -0
  385. package/dist/react/components/PaymentMethodsList.js +18 -0
  386. package/dist/react/components/PaymentMethodsList.js.map +1 -0
  387. package/dist/react/components/PayoutSchedule.d.ts +55 -0
  388. package/dist/react/components/PayoutSchedule.d.ts.map +1 -0
  389. package/dist/react/components/PayoutSchedule.js +51 -0
  390. package/dist/react/components/PayoutSchedule.js.map +1 -0
  391. package/dist/react/components/PriceBadge.d.ts +19 -0
  392. package/dist/react/components/PriceBadge.d.ts.map +1 -0
  393. package/dist/react/components/PriceBadge.js +25 -0
  394. package/dist/react/components/PriceBadge.js.map +1 -0
  395. package/dist/react/components/PriceCard.d.ts +34 -0
  396. package/dist/react/components/PriceCard.d.ts.map +1 -0
  397. package/dist/react/components/PriceCard.js +20 -0
  398. package/dist/react/components/PriceCard.js.map +1 -0
  399. package/dist/react/components/PricePicker.d.ts +28 -0
  400. package/dist/react/components/PricePicker.d.ts.map +1 -0
  401. package/dist/react/components/PricePicker.js +32 -0
  402. package/dist/react/components/PricePicker.js.map +1 -0
  403. package/dist/react/components/SplitBreakdown.d.ts +45 -0
  404. package/dist/react/components/SplitBreakdown.d.ts.map +1 -0
  405. package/dist/react/components/SplitBreakdown.js +48 -0
  406. package/dist/react/components/SplitBreakdown.js.map +1 -0
  407. package/dist/react/components/StripeProvider.d.ts +30 -0
  408. package/dist/react/components/StripeProvider.d.ts.map +1 -0
  409. package/dist/react/components/StripeProvider.js +38 -0
  410. package/dist/react/components/StripeProvider.js.map +1 -0
  411. package/dist/react/components/StripeProviderWithKey.d.ts +33 -0
  412. package/dist/react/components/StripeProviderWithKey.d.ts.map +1 -0
  413. package/dist/react/components/StripeProviderWithKey.js +44 -0
  414. package/dist/react/components/StripeProviderWithKey.js.map +1 -0
  415. package/dist/react/components/SubscriptionActions.d.ts +31 -0
  416. package/dist/react/components/SubscriptionActions.d.ts.map +1 -0
  417. package/dist/react/components/SubscriptionActions.js +30 -0
  418. package/dist/react/components/SubscriptionActions.js.map +1 -0
  419. package/dist/react/components/SubscriptionCard.d.ts +41 -0
  420. package/dist/react/components/SubscriptionCard.d.ts.map +1 -0
  421. package/dist/react/components/SubscriptionCard.js +18 -0
  422. package/dist/react/components/SubscriptionCard.js.map +1 -0
  423. package/dist/react/components/SubscriptionLineItems.d.ts +23 -0
  424. package/dist/react/components/SubscriptionLineItems.d.ts.map +1 -0
  425. package/dist/react/components/SubscriptionLineItems.js +20 -0
  426. package/dist/react/components/SubscriptionLineItems.js.map +1 -0
  427. package/dist/react/components/TrialAlert.d.ts +19 -0
  428. package/dist/react/components/TrialAlert.d.ts.map +1 -0
  429. package/dist/react/components/TrialAlert.js +16 -0
  430. package/dist/react/components/TrialAlert.js.map +1 -0
  431. package/dist/react/hooks/useAccount.d.ts +14 -0
  432. package/dist/react/hooks/useAccount.d.ts.map +1 -0
  433. package/dist/react/hooks/useAccount.js +18 -0
  434. package/dist/react/hooks/useAccount.js.map +1 -0
  435. package/dist/react/hooks/useAccountOnboarding.d.ts +15 -0
  436. package/dist/react/hooks/useAccountOnboarding.d.ts.map +1 -0
  437. package/dist/react/hooks/useAccountOnboarding.js +19 -0
  438. package/dist/react/hooks/useAccountOnboarding.js.map +1 -0
  439. package/dist/react/hooks/useCheckout.d.ts +14 -0
  440. package/dist/react/hooks/useCheckout.d.ts.map +1 -0
  441. package/dist/react/hooks/useCheckout.js +18 -0
  442. package/dist/react/hooks/useCheckout.js.map +1 -0
  443. package/dist/react/hooks/useCheckoutSession.d.ts +62 -0
  444. package/dist/react/hooks/useCheckoutSession.d.ts.map +1 -0
  445. package/dist/react/hooks/useCheckoutSession.js +68 -0
  446. package/dist/react/hooks/useCheckoutSession.js.map +1 -0
  447. package/dist/react/hooks/useConfirmPayment.d.ts +38 -0
  448. package/dist/react/hooks/useConfirmPayment.d.ts.map +1 -0
  449. package/dist/react/hooks/useConfirmPayment.js +91 -0
  450. package/dist/react/hooks/useConfirmPayment.js.map +1 -0
  451. package/dist/react/hooks/useDisputeWithCountdown.d.ts +25 -0
  452. package/dist/react/hooks/useDisputeWithCountdown.d.ts.map +1 -0
  453. package/dist/react/hooks/useDisputeWithCountdown.js +19 -0
  454. package/dist/react/hooks/useDisputeWithCountdown.js.map +1 -0
  455. package/dist/react/hooks/useDisputes.d.ts +14 -0
  456. package/dist/react/hooks/useDisputes.d.ts.map +1 -0
  457. package/dist/react/hooks/useDisputes.js +15 -0
  458. package/dist/react/hooks/useDisputes.js.map +1 -0
  459. package/dist/react/hooks/useEarnings.d.ts +92 -0
  460. package/dist/react/hooks/useEarnings.d.ts.map +1 -0
  461. package/dist/react/hooks/useEarnings.js +35 -0
  462. package/dist/react/hooks/useEarnings.js.map +1 -0
  463. package/dist/react/hooks/useInvoices.d.ts +11 -0
  464. package/dist/react/hooks/useInvoices.d.ts.map +1 -0
  465. package/dist/react/hooks/useInvoices.js +11 -0
  466. package/dist/react/hooks/useInvoices.js.map +1 -0
  467. package/dist/react/hooks/usePaymentMethodActions.d.ts +74 -0
  468. package/dist/react/hooks/usePaymentMethodActions.d.ts.map +1 -0
  469. package/dist/react/hooks/usePaymentMethodActions.js +156 -0
  470. package/dist/react/hooks/usePaymentMethodActions.js.map +1 -0
  471. package/dist/react/hooks/usePaymentMethods.d.ts +23 -0
  472. package/dist/react/hooks/usePaymentMethods.d.ts.map +1 -0
  473. package/dist/react/hooks/usePaymentMethods.js +18 -0
  474. package/dist/react/hooks/usePaymentMethods.js.map +1 -0
  475. package/dist/react/hooks/usePrices.d.ts +12 -0
  476. package/dist/react/hooks/usePrices.d.ts.map +1 -0
  477. package/dist/react/hooks/usePrices.js +16 -0
  478. package/dist/react/hooks/usePrices.js.map +1 -0
  479. package/dist/react/hooks/useProducts.d.ts +10 -0
  480. package/dist/react/hooks/useProducts.d.ts.map +1 -0
  481. package/dist/react/hooks/useProducts.js +11 -0
  482. package/dist/react/hooks/useProducts.js.map +1 -0
  483. package/dist/react/hooks/useSplitBreakdown.d.ts +58 -0
  484. package/dist/react/hooks/useSplitBreakdown.d.ts.map +1 -0
  485. package/dist/react/hooks/useSplitBreakdown.js +59 -0
  486. package/dist/react/hooks/useSplitBreakdown.js.map +1 -0
  487. package/dist/react/hooks/useStripeConfig.d.ts +14 -0
  488. package/dist/react/hooks/useStripeConfig.d.ts.map +1 -0
  489. package/dist/react/hooks/useStripeConfig.js +21 -0
  490. package/dist/react/hooks/useStripeConfig.js.map +1 -0
  491. package/dist/react/hooks/useStripeMode.d.ts +3 -0
  492. package/dist/react/hooks/useStripeMode.d.ts.map +1 -0
  493. package/dist/react/hooks/useStripeMode.js +6 -0
  494. package/dist/react/hooks/useStripeMode.js.map +1 -0
  495. package/dist/react/hooks/useStripePublishableKey.d.ts +2 -0
  496. package/dist/react/hooks/useStripePublishableKey.d.ts.map +1 -0
  497. package/dist/react/hooks/useStripePublishableKey.js +6 -0
  498. package/dist/react/hooks/useStripePublishableKey.js.map +1 -0
  499. package/dist/react/hooks/useSubscription.d.ts +17 -0
  500. package/dist/react/hooks/useSubscription.d.ts.map +1 -0
  501. package/dist/react/hooks/useSubscription.js +30 -0
  502. package/dist/react/hooks/useSubscription.js.map +1 -0
  503. package/dist/react/hooks/useSubscriptions.d.ts +11 -0
  504. package/dist/react/hooks/useSubscriptions.d.ts.map +1 -0
  505. package/dist/react/hooks/useSubscriptions.js +13 -0
  506. package/dist/react/hooks/useSubscriptions.js.map +1 -0
  507. package/dist/react/index.d.ts +108 -0
  508. package/dist/react/index.d.ts.map +1 -0
  509. package/dist/react/index.js +87 -0
  510. package/dist/react/index.js.map +1 -0
  511. package/dist/react/lib/connect-requirement-keys.d.ts +14 -0
  512. package/dist/react/lib/connect-requirement-keys.d.ts.map +1 -0
  513. package/dist/react/lib/connect-requirement-keys.js +57 -0
  514. package/dist/react/lib/connect-requirement-keys.js.map +1 -0
  515. package/dist/react/lib/price-helpers.d.ts +31 -0
  516. package/dist/react/lib/price-helpers.d.ts.map +1 -0
  517. package/dist/react/lib/price-helpers.js +46 -0
  518. package/dist/react/lib/price-helpers.js.map +1 -0
  519. package/dist/react/lib/stripe-element-styles.d.ts +91 -0
  520. package/dist/react/lib/stripe-element-styles.d.ts.map +1 -0
  521. package/dist/react/lib/stripe-element-styles.js +131 -0
  522. package/dist/react/lib/stripe-element-styles.js.map +1 -0
  523. package/dist/react/lib/subscription-helpers.d.ts +33 -0
  524. package/dist/react/lib/subscription-helpers.d.ts.map +1 -0
  525. package/dist/react/lib/subscription-helpers.js +47 -0
  526. package/dist/react/lib/subscription-helpers.js.map +1 -0
  527. package/dist/react/types.d.ts +20 -0
  528. package/dist/react/types.d.ts.map +1 -0
  529. package/dist/react/types.js +2 -0
  530. package/dist/react/types.js.map +1 -0
  531. package/dist/testing/assert-test-env.d.ts +6 -0
  532. package/dist/testing/assert-test-env.d.ts.map +1 -0
  533. package/dist/testing/assert-test-env.js +15 -0
  534. package/dist/testing/assert-test-env.js.map +1 -0
  535. package/dist/testing/fixtures.d.ts +38 -0
  536. package/dist/testing/fixtures.d.ts.map +1 -0
  537. package/dist/testing/fixtures.js +54 -0
  538. package/dist/testing/fixtures.js.map +1 -0
  539. package/dist/testing/index.d.ts +4 -0
  540. package/dist/testing/index.d.ts.map +1 -0
  541. package/dist/testing/index.js +4 -0
  542. package/dist/testing/index.js.map +1 -0
  543. package/dist/testing/mock-webhooks.d.ts +19 -0
  544. package/dist/testing/mock-webhooks.d.ts.map +1 -0
  545. package/dist/testing/mock-webhooks.js +81 -0
  546. package/dist/testing/mock-webhooks.js.map +1 -0
  547. package/package.json +131 -0
  548. package/src/client/billing/checkout.test.ts +1234 -0
  549. package/src/client/billing/checkout.ts +416 -0
  550. package/src/client/billing/invoices.test.ts +237 -0
  551. package/src/client/billing/invoices.ts +93 -0
  552. package/src/client/billing/subscriptions.test.ts +987 -0
  553. package/src/client/billing/subscriptions.ts +604 -0
  554. package/src/client/component-api-types.test.ts +137 -0
  555. package/src/client/connect/disputes.test.ts +487 -0
  556. package/src/client/connect/disputes.ts +302 -0
  557. package/src/client/connect/paymentMethodUtils.test.ts +83 -0
  558. package/src/client/connect/paymentMethodUtils.ts +28 -0
  559. package/src/client/connect/paymentMethods.test.ts +66 -0
  560. package/src/client/connect/paymentMethods.ts +55 -0
  561. package/src/client/connect/payouts.test.ts +132 -0
  562. package/src/client/connect/payouts.ts +105 -0
  563. package/src/client/connect/refundActor.test.ts +121 -0
  564. package/src/client/connect/refundActor.ts +60 -0
  565. package/src/client/connect/refunds.test.ts +341 -0
  566. package/src/client/connect/refunds.ts +256 -0
  567. package/src/client/connect/transfers.test.ts +492 -0
  568. package/src/client/connect/transfers.ts +572 -0
  569. package/src/client/constants.ts +15 -0
  570. package/src/client/core/accountLinks.test.ts +378 -0
  571. package/src/client/core/accountLinks.ts +211 -0
  572. package/src/client/core/accountStatus.test.ts +102 -0
  573. package/src/client/core/accountStatus.ts +91 -0
  574. package/src/client/core/accounts.test.ts +1496 -0
  575. package/src/client/core/accounts.ts +667 -0
  576. package/src/client/core/config.test.ts +68 -0
  577. package/src/client/core/config.ts +27 -0
  578. package/src/client/core/descriptors.test.ts +68 -0
  579. package/src/client/core/descriptors.ts +46 -0
  580. package/src/client/core/fees.test.ts +377 -0
  581. package/src/client/core/fees.ts +268 -0
  582. package/src/client/errors.test.ts +66 -0
  583. package/src/client/errors.ts +70 -0
  584. package/src/client/helpers.test.ts +74 -0
  585. package/src/client/helpers.ts +94 -0
  586. package/src/client/index.test.ts +1848 -0
  587. package/src/client/index.ts +1872 -0
  588. package/src/client/products/prices.test.ts +345 -0
  589. package/src/client/products/prices.ts +194 -0
  590. package/src/client/products/products.test.ts +476 -0
  591. package/src/client/products/products.ts +335 -0
  592. package/src/client/setup.test.ts +47 -0
  593. package/src/client/stripe-types.ts +108 -0
  594. package/src/client/types/documents.ts +245 -0
  595. package/src/client/types/events.ts +72 -0
  596. package/src/client/types/index.ts +43 -0
  597. package/src/client/types/options.ts +103 -0
  598. package/src/client/types/triggers.ts +293 -0
  599. package/src/client/types.ts +35 -0
  600. package/src/client/utils/data.test.ts +59 -0
  601. package/src/client/utils/data.ts +22 -0
  602. package/src/client/utils/owner.test.ts +35 -0
  603. package/src/client/utils/owner.ts +27 -0
  604. package/src/client/utils/stripeDashboardUrl.test.ts +71 -0
  605. package/src/client/utils/stripeDashboardUrl.ts +71 -0
  606. package/src/client/utils/webhookEndpoints.test.ts +454 -0
  607. package/src/client/utils/webhookEndpoints.ts +271 -0
  608. package/src/client/webhook-handlers.test.ts +603 -0
  609. package/src/client/webhooks/handler.test.ts +604 -0
  610. package/src/client/webhooks/handler.ts +256 -0
  611. package/src/client/webhooks/helpers.test.ts +330 -0
  612. package/src/client/webhooks/helpers.ts +277 -0
  613. package/src/client/webhooks/hooks.test.ts +111 -0
  614. package/src/client/webhooks/hooks.ts +177 -0
  615. package/src/client/webhooks/index.ts +51 -0
  616. package/src/client/webhooks/processors.test.ts +2392 -0
  617. package/src/client/webhooks/processors.ts +1166 -0
  618. package/src/client/webhooks/v2.test.ts +396 -0
  619. package/src/client/webhooks/v2.ts +124 -0
  620. package/src/client/webhooks.test.ts +1689 -0
  621. package/src/client/webhooks.ts +3 -0
  622. package/src/component/_generated/api.ts +86 -0
  623. package/src/component/_generated/component.ts +1758 -0
  624. package/src/component/_generated/dataModel.ts +60 -0
  625. package/src/component/_generated/server.ts +164 -0
  626. package/src/component/billing/mutations.ts +155 -0
  627. package/src/component/billing/queries.ts +378 -0
  628. package/src/component/billing/schema.ts +40 -0
  629. package/src/component/billing/validators.ts +137 -0
  630. package/src/component/config-queries.test.ts +47 -0
  631. package/src/component/connect/mutations.ts +624 -0
  632. package/src/component/connect/queries.ts +537 -0
  633. package/src/component/connect/schema.ts +90 -0
  634. package/src/component/connect/validators.ts +333 -0
  635. package/src/component/connect.test.ts +721 -0
  636. package/src/component/convex.config.ts +17 -0
  637. package/src/component/core/mutations.ts +182 -0
  638. package/src/component/core/queries.ts +100 -0
  639. package/src/component/core/schema.ts +13 -0
  640. package/src/component/core/validators.ts +55 -0
  641. package/src/component/earnings-totals.test.ts +196 -0
  642. package/src/component/fee-routing.test.ts +124 -0
  643. package/src/component/lib/fees.ts +64 -0
  644. package/src/component/lib/idempotency.test.ts +37 -0
  645. package/src/component/lib/idempotency.ts +20 -0
  646. package/src/component/lib/reversals.ts +113 -0
  647. package/src/component/lib/stripeFactory.ts +30 -0
  648. package/src/component/products/mutations.ts +73 -0
  649. package/src/component/products/queries.ts +149 -0
  650. package/src/component/products/schema.ts +22 -0
  651. package/src/component/products/validators.ts +63 -0
  652. package/src/component/public.test.ts +1858 -0
  653. package/src/component/reversal-races.test.ts +920 -0
  654. package/src/component/schema.ts +45 -0
  655. package/src/component/subscription-scoping.test.ts +118 -0
  656. package/src/component/transfers.test.ts +402 -0
  657. package/src/component/triggers.test.ts +359 -0
  658. package/src/component/webhooks/mutations.ts +151 -0
  659. package/src/component/webhooks/queries.ts +44 -0
  660. package/src/component/webhooks/schema.ts +10 -0
  661. package/src/component/webhooks/validators.ts +30 -0
  662. package/src/react/components/AccountCloseButton.tsx +91 -0
  663. package/src/react/components/AccountCloseCard.tsx +84 -0
  664. package/src/react/components/AccountCreateButton.tsx +83 -0
  665. package/src/react/components/AccountCreateCard.tsx +123 -0
  666. package/src/react/components/AccountLoginButton.tsx +69 -0
  667. package/src/react/components/AccountLoginCard.tsx +99 -0
  668. package/src/react/components/AccountOnboardingButton.tsx +83 -0
  669. package/src/react/components/AccountOnboardingCard.test.ts +27 -0
  670. package/src/react/components/AccountOnboardingCard.tsx +152 -0
  671. package/src/react/components/AddCardForm.tsx +80 -0
  672. package/src/react/components/BillingPortalLink.tsx +93 -0
  673. package/src/react/components/BuyerBillingView.render.test.tsx +207 -0
  674. package/src/react/components/BuyerBillingView.tsx +193 -0
  675. package/src/react/components/CheckoutSessionProvider.tsx +70 -0
  676. package/src/react/components/CheckoutSessionProviderWithKey.tsx +99 -0
  677. package/src/react/components/CheckoutStatus.tsx +71 -0
  678. package/src/react/components/ConnectProvider.tsx +58 -0
  679. package/src/react/components/ConnectRequirements.tsx +159 -0
  680. package/src/react/components/ConnectStatusBadge.tsx +60 -0
  681. package/src/react/components/DeletePaymentMethodDialog.tsx +61 -0
  682. package/src/react/components/DisputeDetail.render.test.tsx +143 -0
  683. package/src/react/components/DisputeDetail.tsx +111 -0
  684. package/src/react/components/DisputesList.render.test.tsx +244 -0
  685. package/src/react/components/DisputesList.tsx +120 -0
  686. package/src/react/components/EarningsSummary.render.test.tsx +153 -0
  687. package/src/react/components/EarningsSummary.tsx +131 -0
  688. package/src/react/components/EmbeddedCheckout.test.ts +25 -0
  689. package/src/react/components/EmbeddedCheckout.tsx +54 -0
  690. package/src/react/components/EmbeddedDisputes.render.test.tsx +142 -0
  691. package/src/react/components/EmbeddedDisputes.tsx +38 -0
  692. package/src/react/components/EvidenceForm.render.test.tsx +215 -0
  693. package/src/react/components/EvidenceForm.tsx +176 -0
  694. package/src/react/components/IntervalSelector.tsx +58 -0
  695. package/src/react/components/PaymentMethodActions.tsx +68 -0
  696. package/src/react/components/PaymentMethodsList.tsx +81 -0
  697. package/src/react/components/PayoutSchedule.render.test.tsx +178 -0
  698. package/src/react/components/PayoutSchedule.tsx +148 -0
  699. package/src/react/components/PriceBadge.render.test.tsx +134 -0
  700. package/src/react/components/PriceBadge.tsx +49 -0
  701. package/src/react/components/PriceCard.render.test.tsx +135 -0
  702. package/src/react/components/PriceCard.tsx +83 -0
  703. package/src/react/components/PricePicker.tsx +95 -0
  704. package/src/react/components/SplitBreakdown.render.test.tsx +168 -0
  705. package/src/react/components/SplitBreakdown.tsx +121 -0
  706. package/src/react/components/StripeProvider.test.ts +45 -0
  707. package/src/react/components/StripeProvider.tsx +80 -0
  708. package/src/react/components/StripeProviderWithKey.tsx +95 -0
  709. package/src/react/components/SubscriptionActions.tsx +79 -0
  710. package/src/react/components/SubscriptionCard.tsx +92 -0
  711. package/src/react/components/SubscriptionLineItems.tsx +62 -0
  712. package/src/react/components/TrialAlert.render.test.tsx +132 -0
  713. package/src/react/components/TrialAlert.tsx +44 -0
  714. package/src/react/hooks/skipSentinel.test.ts +85 -0
  715. package/src/react/hooks/useAccount.ts +28 -0
  716. package/src/react/hooks/useAccountOnboarding.test.ts +75 -0
  717. package/src/react/hooks/useAccountOnboarding.ts +35 -0
  718. package/src/react/hooks/useCheckout.ts +33 -0
  719. package/src/react/hooks/useCheckoutSession.ts +110 -0
  720. package/src/react/hooks/useConfirmPayment.ts +117 -0
  721. package/src/react/hooks/useDisputeWithCountdown.test.ts +90 -0
  722. package/src/react/hooks/useDisputeWithCountdown.ts +48 -0
  723. package/src/react/hooks/useDisputes.test.ts +75 -0
  724. package/src/react/hooks/useDisputes.ts +28 -0
  725. package/src/react/hooks/useEarnings.test.ts +159 -0
  726. package/src/react/hooks/useEarnings.ts +132 -0
  727. package/src/react/hooks/useInvoices.test.ts +79 -0
  728. package/src/react/hooks/useInvoices.ts +25 -0
  729. package/src/react/hooks/usePaymentMethodActions.ts +206 -0
  730. package/src/react/hooks/usePaymentMethods.ts +44 -0
  731. package/src/react/hooks/usePrices.ts +26 -0
  732. package/src/react/hooks/useProducts.test.ts +75 -0
  733. package/src/react/hooks/useProducts.ts +24 -0
  734. package/src/react/hooks/useSplitBreakdown.test.ts +151 -0
  735. package/src/react/hooks/useSplitBreakdown.ts +118 -0
  736. package/src/react/hooks/useStripeConfig.ts +31 -0
  737. package/src/react/hooks/useStripeMode.test.ts +49 -0
  738. package/src/react/hooks/useStripeMode.ts +9 -0
  739. package/src/react/hooks/useStripePublishableKey.test.ts +35 -0
  740. package/src/react/hooks/useStripePublishableKey.ts +9 -0
  741. package/src/react/hooks/useSubscription.ts +52 -0
  742. package/src/react/hooks/useSubscriptions.ts +33 -0
  743. package/src/react/index.payment-element.test.ts +41 -0
  744. package/src/react/index.test.ts +167 -0
  745. package/src/react/index.ts +279 -0
  746. package/src/react/lib/connect-requirement-keys.test.ts +73 -0
  747. package/src/react/lib/connect-requirement-keys.ts +66 -0
  748. package/src/react/lib/price-helpers.test.ts +199 -0
  749. package/src/react/lib/price-helpers.ts +68 -0
  750. package/src/react/lib/stripe-element-styles.test.ts +94 -0
  751. package/src/react/lib/stripe-element-styles.ts +178 -0
  752. package/src/react/lib/subscription-helpers.test.ts +127 -0
  753. package/src/react/lib/subscription-helpers.ts +64 -0
  754. package/src/react/types.ts +32 -0
  755. package/src/test.ts +5 -0
  756. package/src/testing/assert-test-env.test.ts +33 -0
  757. package/src/testing/assert-test-env.ts +20 -0
  758. package/src/testing/fixtures.ts +95 -0
  759. package/src/testing/index.ts +13 -0
  760. package/src/testing/mock-webhooks.test.ts +97 -0
  761. package/src/testing/mock-webhooks.ts +101 -0
  762. package/src/vite-env.d.ts +4 -0
package/README.md ADDED
@@ -0,0 +1,1117 @@
1
+ # better-stripe
2
+
3
+ A reusable [Convex component](https://docs.convex.dev/components) for the Stripe V2 Accounts API — a **Stripe V2 marketplace/Connect library**, not just a webhook wrapper. Provides a complete billing + marketplace-economics backend: schema, queries, mutations, actions, webhook handling, platform fees, multi-recipient splits, rolling payouts, dispute clawback, per-store statement descriptors, React hooks, and headless UI components.
4
+
5
+ Built for Convex + Next.js applications. Follows the conventions established by [`@convex-dev/stripe`](https://github.com/get-convex/stripe) and [`@convex-dev/better-auth`](https://github.com/get-convex/better-auth).
6
+
7
+ ## Status
8
+
9
+ **Version**: `0.4.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
10
+
11
+ Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
12
+
13
+ ### Releasing
14
+
15
+ Releases are automated with [Release Please](https://github.com/googleapis/release-please-action) and published to npmjs.com as `@fantastic.dev/better-stripe`. **Don't bump the version or edit `CHANGELOG.md` by hand.**
16
+
17
+ 1. **Give every PR a Conventional Commit title** (it becomes the squash-merge commit):
18
+ - `fix: …` makes a patch release.
19
+ - `feat: …` makes a minor release.
20
+ - `feat!: …` (or a `BREAKING CHANGE:` footer) makes a minor release while the package is pre-1.0.
21
+ - `docs:`, `chore:`, `ci:`, `refactor:`, `test:`, `build:` and `perf:` appear in the changelog too. On their own they still open a patch release PR, which you can leave open to collect more changes: nothing publishes until that PR is merged.
22
+
23
+ Write the title for consumers of the package: it becomes the changelog entry. A title that isn't a Conventional Commit is left out.
24
+ 2. **On merge to `main`**, the `Release` workflow opens or updates a release PR that bumps `package.json`, `CHANGELOG.md`, the version line above and `.release-please-manifest.json`.
25
+ 3. **Merging the release PR** is the release decision. The same run tags the version, creates the GitHub release and publishes to npm through [trusted publishing](https://docs.npmjs.com/trusted-publishers) with provenance. There's no npm token.
26
+
27
+ Release policy lives in `release-please-config.json`. Keep the workflow file named `release.yml`, because the trusted publisher on npmjs.com is bound to that filename. A manually pushed `vX.Y.Z` tag also publishes, but only if it matches `package.json` and `CHANGELOG.md` has a section for it (`scripts/release-notes.mjs`). If publishing fails after the GitHub release is created, use **Re-run failed jobs** on that run. Check npm first if the outcome is uncertain: a published version can't be overwritten.
28
+
29
+ The private `example` workspace isn't published.
30
+
31
+ ### Regenerating codegen
32
+
33
+ The component ships committed Convex codegen output at `src/component/_generated/{api,component,dataModel,server}.ts` — consumers reach the bindings via the `./_generated/component` subpath export. The example app also commits its own codegen at `example/convex/_generated/`. Running `pnpm dev` (which wraps `convex dev`) regenerates these automatically when the schema or function definitions change, but only against the live dev deployment and only while the dev server is watching.
34
+
35
+ If you add, remove, or rename a query/mutation/action on a branch without the dev server watching — or after a rebase — regenerate explicitly before committing:
36
+
37
+ ```bash
38
+ pnpm codegen # regen the library component + example app
39
+ pnpm codegen:lib # regen src/component/_generated only
40
+ pnpm codegen:example # regen example/convex/_generated only
41
+ ```
42
+
43
+ All three require a configured dev deployment (`CONVEX_DEPLOYMENT` env var, normally set by a prior `npx convex dev`). They write only the local `_generated/` files — they don't push code or data to the deployment.
44
+
45
+ **CI gate (BTS-104 / BTS-111 / BTS-112).** Two layers verify the committed files are not stale:
46
+
47
+ 1. **Structural drift check** (`pnpm codegen:check`, always runs in CI): two independent scans, each checking both directions (every source export appears in the generated file, and every generated entry still has a matching source), neither needing a deployment:
48
+ - Library component — scans `src/component/**/*.{queries,mutations,actions}.ts` and verifies every exported function appears in `src/component/_generated/component.ts`. This is the [BTS-31](https://linear.app/dojoco/issue/BTS-31)/[BTS-50](https://linear.app/dojoco/issue/BTS-50) and [BTS-74](https://linear.app/dojoco/issue/BTS-74) incident class. The reverse direction also flags a stale entry left behind by a *deleted* query/mutation/action (BTS-112). The export-detection regex intentionally matches only direct `query(...)`/`mutation(...)`/`action(...)` exports — not wrapper or re-export forms like `customQuery(...)` (convex-helpers) or `export { fn as name }`, which this component has none of today; widen the regex (and the reverse scan) rather than assuming that stays true.
49
+ - Example app — scans `example/convex/**/*.ts` and verifies every source module is imported and registered in `example/convex/_generated/api.ts`. Catches the common case of adding a new `example/convex/<module>.ts` (or nested file like `example/convex/lib/<module>.ts`) without regenerating (BTS-111). The reverse direction likewise flags a stale import left behind by a *deleted* module (BTS-112).
50
+ 2. **Authoritative regen-and-diff** (runs in CI when `CONVEX_DEPLOYMENT` is configured): runs `pnpm codegen` against the configured dev deployment and fails if `git diff` shows changes. Catches every drift case, including validator-shape changes the structural check can't see. To enable on a fork, set the `CONVEX_DEPLOYMENT` repo secret to a dev deployment name and authorize the CI runner — see Convex's [GitHub Actions guide](https://docs.convex.dev/production/integration/deployments#github-actions).
51
+
52
+ ### Relation to `@convex-dev/stripe`
53
+
54
+ This component targets the Stripe **V2 Accounts API** (Connect/marketplace-first) with a transactional trigger system. [`@convex-dev/stripe`](https://github.com/get-convex/stripe) targets the classic Customers/V1 API. They are different data models — there is no automated migration. Choose by which Stripe API generation your app uses.
55
+
56
+ ## Features
57
+
58
+ - **V2 Accounts API** -- Account creation, onboarding, Connect/marketplace, merchant and recipient configurations
59
+ - **Products and Prices** -- Full CRUD with trial day management as a first-class feature
60
+ - **Checkout** -- Both embedded (custom UI mode) and redirect checkout session creation
61
+ - **Subscriptions** -- Lifecycle management including cancel, reactivate, quantity updates, and trial tracking
62
+ - **Marketplace fees** -- Platform fee config (percent, fixed, tiered), resolved per-call or as a global default, applied via `application_fee_percent`/`application_fee_amount` or computed per invoice/charge
63
+ - **Split engine** -- Single-recipient destination charges or multi-recipient separate-charges-and-transfers (store + affiliate(s)), computed and executed by the webhook engine
64
+ - **Invoices** -- Invoice syncing and querying with metadata propagation from subscriptions
65
+ - **Payments** -- Payment intent tracking and status management
66
+ - **Payouts** -- Automatic rolling payouts for Connect/marketplace flows, with a recipient balance + cadence React surface
67
+ - **Refunds** -- Refund tracking with refunded-amount/status denormalized onto the linked payment, plus proportional platform-fee return and transfer reversal (destination charges via Stripe flags, split sales via webhook-driven ledger math)
68
+ - **Disputes** -- Chargeback/dispute tracking with evidence submission and close helpers, plus automatic transfer clawback on open, reinstatement on a won dispute, and auto-cancel of the disputed subscription
69
+ - **Per-store statement descriptors** -- Buyer-recognizable charge descriptors resolved per seller with a configurable platform fallback
70
+ - **Webhook handling** -- Single-endpoint processing with ledger-based deduplication and replay protection
71
+ - **Trigger system** -- BetterAuth-style sync triggers (same transaction) and async hooks (scheduled action) for app-layer extensibility
72
+ - **React hooks** -- Read hooks and flow hooks for all billing and marketplace-economics domains (fees, splits, earnings, payouts, disputes)
73
+ - **Headless UI components** -- Checkout, subscription, payment method, Connect, payout, split, and dispute components with render-prop customization
74
+ - **Test utilities** -- Typed fixture factories, mock webhook events, and `assertTestEnvironment` guard
75
+
76
+ See [Roadmap / Known Gaps](#roadmap--known-gaps) for what's still in flight.
77
+
78
+ ## Roadmap / Known Gaps
79
+
80
+ The marketplace economics layer described above — platform fees, the split engine, rolling payouts, dispute clawback/reinstate, refund fee/transfer reversal, and per-store statement descriptors — is **implemented and merged**, tracked as issues on the `BTS` team in Linear. This section lists what's honestly still open, by ticket, rather than letting the feature list overstate the current state:
81
+
82
+ - **[BTS-67](https://linear.app/dojoco/issue/BTS-67)** — the first charge of every destination-charge subscription carries no per-store statement descriptor. Direct `charge_automatically` subscriptions (and Checkout subscription mode) finalize and pay their first invoice synchronously at creation, before the `invoice.created` handler that sets the descriptor can run. Later invoices are unaffected. A product-level `statement_descriptor` fix (which would cover the first charge too) is proposed but not built.
83
+ - **[BTS-68](https://linear.app/dojoco/issue/BTS-68)** — investigating whether the fixed/tiered per-invoice platform fee has the same first-invoice gap as BTS-67 (same `invoice.created` timing), which would be a fee-revenue miss rather than a cosmetic one. Not yet confirmed or fixed.
84
+ - **[BTS-63](https://linear.app/dojoco/issue/BTS-63)** — dispute clawback (`reverseTransfers`) retrying after a partial success can hit Stripe idempotency-key conflicts on the legs that already succeeded.
85
+ - **[BTS-64](https://linear.app/dojoco/issue/BTS-64)** — the earnings/split ledger queries backing `useEarnings` and `useSplitBreakdown` (`listTransfersByAccount`, `listTransfersByCharge`) silently cap at 50 rows, which can understate gross/net totals for high-volume accounts or heavily-split sales.
86
+
87
+ ## Installation
88
+
89
+ ```bash
90
+ npm install @fantastic.dev/better-stripe
91
+ ```
92
+
93
+ The package bundles `stripe`, `@stripe/stripe-js`, and `@stripe/react-stripe-js` as dependencies. You do not need to install Stripe packages separately.
94
+
95
+ Peer dependencies: `convex >= 1.29.3`, `react >= 18.3.1`, `react-dom >= 18.3.1`.
96
+
97
+ ## Quick Start
98
+
99
+ The consumer contract has three steps:
100
+
101
+ ### Step 1: Register the component
102
+
103
+ ```typescript
104
+ // convex/convex.config.ts
105
+ import betterStripe from "@fantastic.dev/better-stripe/convex.config";
106
+ import { defineApp } from "convex/server";
107
+ import { v } from "convex/values";
108
+
109
+ // betterStripe requires STRIPE_SECRET_KEY; declare it at the app level and pass
110
+ // it to the component by reference (see "Wiring component env vars" below).
111
+ const app = defineApp({
112
+ env: { STRIPE_SECRET_KEY: v.string() },
113
+ });
114
+ app.use(betterStripe, {
115
+ env: { STRIPE_SECRET_KEY: app.env.STRIPE_SECRET_KEY },
116
+ });
117
+
118
+ export default app;
119
+ ```
120
+
121
+ ### Step 2: Create a BetterStripe instance with triggers
122
+
123
+ ```typescript
124
+ // convex/stripe.ts
125
+ import { BetterStripe } from "@fantastic.dev/better-stripe";
126
+
127
+ import { components } from "./_generated/api";
128
+
129
+ export const stripe = new BetterStripe(components.betterStripe, {
130
+ STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
131
+ triggers: {
132
+ checkoutSession: {
133
+ onCompleted: async (ctx, session) => {
134
+ // App-specific transactional logic (same DB transaction)
135
+ },
136
+ },
137
+ subscription: {
138
+ onUpdate: async (ctx, newSub, oldSub) => {
139
+ // Update app-owned tables within the same transaction
140
+ },
141
+ },
142
+ },
143
+ hooks: {
144
+ onCheckoutCompleted: async (ctx, session) => {
145
+ // Async side effects: email, Slack, analytics
146
+ },
147
+ },
148
+ });
149
+
150
+ // Export the webhook handler pair; http.ts passes their refs to registerRoutes.
151
+ // `syncWebhook` runs your sync triggers in the same transaction as the component
152
+ // upsert; `asyncWebhook` runs your async hooks after commit.
153
+ export const { syncWebhook, asyncWebhook } = stripe.webhookHandlers();
154
+ ```
155
+
156
+ ### Step 3: Register webhook routes
157
+
158
+ ```typescript
159
+ // convex/http.ts
160
+ import { registerRoutes } from "@fantastic.dev/better-stripe";
161
+ import { httpRouter } from "convex/server";
162
+
163
+ import { components, internal } from "./_generated/api";
164
+
165
+ const http = httpRouter();
166
+
167
+ registerRoutes(http, components.betterStripe, {
168
+ webhookPath: "/stripe/webhook",
169
+ stripeSecretKey: process.env.STRIPE_SECRET_KEY,
170
+ webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
171
+ webhookSecretV2: process.env.STRIPE_WEBHOOK_SECRET_V2,
172
+ webhooks: internal.stripe,
173
+ });
174
+
175
+ export default http;
176
+ ```
177
+
178
+ The `webhooks: internal.stripe` line passes the function references of the `syncWebhook`/`asyncWebhook` pair you exported in step 2 (here from `convex/stripe.ts`). Don't confuse this with the callback `triggers`/`hooks` on the `BetterStripe` constructor in step 2, which take your raw handlers. When `webhooks` is provided, webhook upserts run through `syncWebhook` so your sync triggers execute in the same transaction as the component write, and your async hooks are scheduled (via `asyncWebhook`) after commit. If omitted, the handler falls back to direct component upserts and no triggers fire.
179
+
180
+ > **Why two webhook secrets?** Stripe requires separate event destinations for V1 snapshot events (payments, subscriptions) and V2 thin events (Connect account lifecycle). Each destination has its own signing secret. The handler uses `webhookSecret` for V1 events and `webhookSecretV2` for V2 events. See [Webhook Setup](#webhook-setup) for details.
181
+
182
+ ## Client API Reference
183
+
184
+ All methods are available on the `BetterStripe` class instance. Methods that call the Stripe API are actions; methods that only read Convex data are queries.
185
+
186
+ Methods named `get<Entity>` take the component document ID (exception: `getInvoice`, which takes the Stripe invoice ID); methods named `get<Entity>ByStripeId` take the Stripe ID (`acct_...`, `prod_...`, `price_...`, `cs_...`, `sub_...`).
187
+
188
+ ### Account
189
+
190
+ | Method | Description |
191
+ | --------------------------------------------------------------------------------- | -------------------------------------------------------- |
192
+ | `createAccount(ctx, { userId, email?, name?, country?, orgId?, metadata? })` | Create a V2 account in Stripe and the component database |
193
+ | `getAccount(ctx, { accountId })` | Get account by component document ID |
194
+ | `getAccountByStripeId(ctx, { stripeAccountId })` | Get account by Stripe account ID |
195
+ | `getOrCreateAccount(ctx, { userId, email?, name?, country?, orgId?, metadata? })` | Get existing or create new account |
196
+ | `getAccountByUserId(ctx, { userId })` | Get account by app-layer user ID |
197
+ | `getAccountByOrgId(ctx, { orgId })` | Get account by organization/team ID |
198
+ | `getAccountOnboardingStatus(ctx, { accountId })` | Get Connect onboarding status (by component document ID) |
199
+ | `updateAccount(ctx, { stripeAccountId, email?, name?, metadata? })` | Update account fields |
200
+ | `createAccountLink(ctx, { stripeAccountId, refreshUrl, returnUrl, type })` | Create Connect onboarding or update link |
201
+ | `createAccountSession(ctx, { stripeAccountId, components })` | Create embedded account management session |
202
+ | `createLoginLink(ctx, { stripeAccountId })` | Create Express dashboard login link |
203
+ | `addRecipientConfiguration(ctx, { stripeAccountId })` | Add recipient configuration to an existing account |
204
+ | `getV2Account(ctx, { stripeAccountId, include? })` | Retrieve a V2 account directly from Stripe |
205
+ | `updateV2Account(ctx, { stripeAccountId, updateParams })` | Update a V2 account in Stripe |
206
+ | `listStripeAccounts(ctx, { limit? })` | List V2 accounts directly from Stripe |
207
+ | `closeAccount(ctx, { stripeAccountId })` | Close a V2 account; returns `{ closed: boolean }` |
208
+ | `restartAccountOnboarding(ctx, { stripeAccountId })` | Close the account so onboarding can restart fresh |
209
+ | `setAccountStatementDescriptor(ctx, { stripeAccountId, statementDescriptor })` | Set (or `null` to clear) the account's per-store statement-descriptor suffix |
210
+ | `createDisputeSession(ctx, { stripeAccountId })` | Create an embedded Account Session scoped to the seller's disputes |
211
+
212
+ ### Product and Price
213
+
214
+ | Method | Description |
215
+ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
216
+ | `createProduct(ctx, { name, description?, active?, accountId?, metadata? })` | Create product in Stripe and component DB |
217
+ | `getProduct(ctx, { productId })` | Get product by component document ID |
218
+ | `getProductByStripeId(ctx, { stripeProductId })` | Get product by Stripe product ID |
219
+ | `listProducts(ctx, { accountId?, active?, limit? })` | List products with optional filters |
220
+ | `updateProduct(ctx, { stripeProductId, ...updates })` | Update product fields |
221
+ | `deactivateProduct(ctx, { stripeProductId })` | Deactivate product in Stripe and component DB |
222
+ | `createPrice(ctx, { stripeProductId, unitAmount, type, currency?, interval?, intervalCount?, nickname?, metadata? })` | Create price in Stripe and component DB |
223
+ | `getPrice(ctx, { priceId })` | Get price by component document ID |
224
+ | `getPriceByStripeId(ctx, { stripePriceId })` | Get price by Stripe price ID |
225
+ | `listPrices(ctx, { productId?, active?, limit? })` | List prices with optional filters |
226
+ | `updatePrice(ctx, { stripePriceId, ...updates })` | Update price fields |
227
+ | `deactivatePrice(ctx, { stripePriceId })` | Deactivate price in Stripe and component DB |
228
+
229
+ ### Checkout and Subscription
230
+
231
+ | Method | Description |
232
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
233
+ | `createCheckoutSession(ctx, { userId, stripePriceId, mode, returnUrl, uiMode?, quantity?, trialDays?, accountId?, orgId?, customerEmail?, destinationAccountId?, split?, fee?, amount?, metadata?, sessionOverrides? })` | Create checkout session (embedded or redirect); `destinationAccountId`/`split` route funds, `fee` overrides the platform's configured default |
234
+ | `getCheckoutSession(ctx, { sessionId })` | Get checkout session by component document ID |
235
+ | `getCheckoutSessionByStripeId(ctx, { stripeSessionId })` | Get checkout session by Stripe session ID |
236
+ | `createSubscription(ctx, { userId, orgId?, customerAccount, stripePriceId, destinationAccountId?, split?, fee?, trialDays?, metadata? })` | Create a subscription directly for a V2 buyer (off the checkout flow), with the same routing/fee options as checkout |
237
+ | `getSubscription(ctx, { subscriptionId })` | Get subscription by component document ID |
238
+ | `getSubscriptionByStripeId(ctx, { stripeSubscriptionId })` | Get subscription by Stripe subscription ID |
239
+ | `listSubscriptions(ctx, { stripeAccountId?, status?, limit? })` | List subscriptions, optionally scoped to a Connect account (use `listSubscriptionsByUser` for per-user filtering) |
240
+ | `listSubscriptionsByUser(ctx, { userId, status? })` | List all subscriptions for a user |
241
+ | `listSubscriptionsByOrg(ctx, { orgId, status? })` | List all subscriptions for an organization |
242
+ | `getActiveSubscription(ctx, { userId, orgId? })` | Get the active subscription for a user or org |
243
+ | `getTrialStatus(ctx, { subscriptionId })` | Get trial state for a subscription |
244
+ | `cancelSubscription(ctx, { stripeSubscriptionId, cancelAtPeriodEnd? })` | Cancel subscription immediately or at period end |
245
+ | `reactivateSubscription(ctx, { stripeSubscriptionId })` | Reactivate a canceled subscription |
246
+ | `updateSubscriptionQuantity(ctx, { stripeSubscriptionId, quantity })` | Update subscription seat quantity |
247
+
248
+ ### Invoice, Payment Method, and Payout
249
+
250
+ | Method | Description |
251
+ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
252
+ | `getInvoice(ctx, { stripeInvoiceId })` | Get invoice by Stripe invoice ID |
253
+ | `getInvoiceByStripeId(ctx, { stripeInvoiceId })` | Alias for getInvoice |
254
+ | `listInvoices(ctx, { stripeAccountId?, userId?, subscriptionId?, status?, limit? })` | List invoices with optional filters |
255
+ | `listInvoicesByUser(ctx, { userId })` | List all invoices for a user |
256
+ | `getInvoiceFromStripe(ctx, { stripeInvoiceId })` | Fetch latest invoice data directly from Stripe |
257
+ | `listPaymentMethods(ctx, { stripeCustomerId, type? })` | List saved payment methods |
258
+ | `attachPaymentMethod(ctx, { paymentMethodId, stripeCustomerId })` | Attach a payment method to a customer account |
259
+ | `detachPaymentMethod(ctx, { paymentMethodId })` | Detach a payment method |
260
+ | `setDefaultPaymentMethod(ctx, { stripeAccountId, paymentMethodId })` | Not supported for V2 accounts — throws with guidance to use `createBillingPortalSession()` |
261
+ | `createBillingPortalSession(ctx, { stripeAccountId, returnUrl })` | Create a Stripe billing portal session URL |
262
+ | `createPayout(ctx, { stripeAccountId, amount, currency?, metadata? })` | Create a payout for a Connect account |
263
+ | `getPayout(ctx, { payoutId })` | Get payout by component document ID |
264
+ | `listPayouts(ctx, { stripeAccountId?, status?, limit? })` | List payouts with optional filters |
265
+
266
+ ### Refund and Dispute
267
+
268
+ | Method | Description |
269
+ | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
270
+ | `createRefund(ctx, { stripePaymentIntentId?, stripeChargeId?, amount?, reason?, metadata?, stripeAccountId?, refundApplicationFee?, reverseTransfer? })` | Issue a refund (provide a payment intent or charge); returns/reverses the platform fee and destination transfer by default; synced via `refund.created`/`.updated` |
271
+ | `getRefundByStripeId(ctx, { stripeRefundId })` | Get a refund by Stripe refund ID |
272
+ | `listRefunds(ctx, { stripeAccountId?, stripePaymentIntentId?, status?, limit? })` | List refunds with optional filters |
273
+ | `getDisputeByStripeId(ctx, { stripeDisputeId })` | Get a dispute by Stripe dispute ID |
274
+ | `getDisputeWithCountdown(ctx, { stripeDisputeId })` | Get a dispute plus its evidence-due countdown (`daysRemaining`, `isOverdue`) |
275
+ | `listDisputes(ctx, { stripeAccountId?, stripePaymentIntentId?, status?, limit? })` | List disputes with optional filters |
276
+ | `updateDispute(ctx, { stripeDisputeId, evidence?, metadata?, submit?, stripeAccountId? })` | Submit/stage dispute evidence (`submit: true` finalizes the response) |
277
+ | `closeDispute(ctx, { stripeDisputeId, stripeAccountId? })` | Accept a dispute (concede the chargeback) — irreversible |
278
+ | `reverseTransfers(ctx, { sourceChargeId, percent?, amount? })` | Reverse split/destination transfers for a charge (the primitive behind automatic dispute clawback; also callable manually) |
279
+
280
+ Refunds denormalize cumulative state onto the linked `payments` row (`refundedAmount`, `refundStatus: "partially_refunded" | "fully_refunded"`) so "is this payment whole?" is a single read.
281
+
282
+ ### Operational
283
+
284
+ | Method | Description |
285
+ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
286
+ | `syncAllAccounts(ctx)` | Sync all V2 accounts from Stripe to component DB |
287
+ | `syncAllProducts(ctx)` | Sync all products and prices from Stripe |
288
+ | `syncAllSubscriptions(ctx)` | Sync all subscriptions from Stripe |
289
+ | `setupEventDestination(ctx, { url, eventPayload?, name?, description?, enabledEvents? })` | Create or update a V2 event destination (snapshot or thin) |
290
+ | `listEventDestinations(ctx, { limit? })` | List all V2 event destinations |
291
+ | `listWebhookEndpoints(ctx, { limit? })` | List V1 webhook endpoints |
292
+ | `createWebhookEndpoint(ctx, { url, description?, enabledEvents? })` | Create a V1 webhook endpoint |
293
+ | `webhookHandlers()` | Returns the `{ syncWebhook, asyncWebhook }` pair to export from a Convex module |
294
+
295
+ ### Standalone Function
296
+
297
+ | Function | Description |
298
+ | ------------------------------------------ | ---------------------------------------------------------- |
299
+ | `registerRoutes(http, component, options)` | Register the webhook HTTP endpoint on a Convex HTTP router |
300
+
301
+ ## Webhook API
302
+
303
+ ### registerRoutes
304
+
305
+ Register the webhook endpoint on your Convex HTTP router:
306
+
307
+ ```typescript
308
+ import { registerRoutes } from "@fantastic.dev/better-stripe";
309
+
310
+ registerRoutes(http, components.betterStripe, {
311
+ webhookPath: "/stripe/webhook", // Default path
312
+ stripeSecretKey: process.env.STRIPE_SECRET_KEY,
313
+ webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
314
+ webhookSecretV2: process.env.STRIPE_WEBHOOK_SECRET_V2, // For V2 thin events
315
+ webhooks: internal.stripe, // The { syncWebhook, asyncWebhook } pair from webhookHandlers()
316
+ events: { ... }, // Optional per-event handlers (advanced)
317
+ onEvent: (ctx, event) => { ... }, // Optional catch-all handler (advanced)
318
+ });
319
+ ```
320
+
321
+ ### Webhook Setup
322
+
323
+ Stripe event destinations come in two flavors that cannot be mixed:
324
+
325
+ - **Snapshot** (`event_payload: 'snapshot'`) — V1 events include the full object in the payload. Used for payments, subscriptions, invoices, products, and payouts.
326
+ - **Thin** (`event_payload: 'thin'`) — V2 events include only the event type and object reference. The handler fetches the full object from the Stripe API. Used for Connect account lifecycle events.
327
+
328
+ You need **two** event destinations pointing to the same webhook URL, each with its own signing secret.
329
+
330
+ #### Programmatic setup
331
+
332
+ Use `setupEventDestination()` to create or update destinations:
333
+
334
+ ```typescript
335
+ // Create V1 snapshot destination
336
+ const v1 = await stripe.setupEventDestination(ctx, {
337
+ url: webhookUrl,
338
+ eventPayload: "snapshot",
339
+ });
340
+
341
+ // Create V2 thin destination
342
+ const v2 = await stripe.setupEventDestination(ctx, {
343
+ url: webhookUrl,
344
+ eventPayload: "thin",
345
+ });
346
+ ```
347
+
348
+ The method is idempotent — it finds an existing destination matching the URL and payload type, updates its events, or creates a new one.
349
+
350
+ #### Admin UI setup
351
+
352
+ The example app includes an `/admin/setup` page that handles webhook creation, env var verification, demo data seeding, and Stripe data syncing — all from the browser.
353
+
354
+ #### Event constants
355
+
356
+ ```typescript
357
+ import {
358
+ BETTER_STRIPE_WEBHOOK_EVENTS, // V1 snapshot events (20 events)
359
+ BETTER_STRIPE_V2_WEBHOOK_EVENTS, // V2 thin events (12 events)
360
+ ALL_BETTER_STRIPE_EVENTS, // Combined (32 events)
361
+ } from "@fantastic.dev/better-stripe";
362
+ ```
363
+
364
+ ### Event Processing
365
+
366
+ Records synced from Stripe objects without `userId` metadata are stored unattributed (`userId: ""`) and are not returned by user-scoped queries.
367
+
368
+ The webhook handler processes events through these steps:
369
+
370
+ 1. Verify Stripe signature
371
+ 2. Record the event in the `webhookEvents` ledger by `stripeEventId`. If the event was already seen and is `processing`, `processed`, or `ignored`, return 200 immediately. If the previous delivery `failed` (its writes rolled back), the ledger row is reset and the event is reprocessed on Stripe's retry.
372
+ 3. Upsert the component-owned domain table. When `webhooks` is configured, the upsert runs through `syncWebhook` — an internal mutation that performs the upsert **and** the sync trigger in the same transaction.
373
+ 4. On failure, mark the ledger row `failed` and return 500 so Stripe retries; otherwise mark it `processed`
374
+ 5. Schedule the matching `after*` async hook via `ctx.scheduler` (separate action)
375
+
376
+ ### Ledger-Based Deduplication
377
+
378
+ The component maintains a `webhookEvents` table that tracks every event by its Stripe event ID. This provides:
379
+
380
+ - **Replay protection** -- duplicate events are detected and skipped
381
+ - **Retry recovery** -- events whose processing failed (and rolled back) are reprocessed when Stripe retries, instead of deduplicating forever
382
+ - **Crash recovery** -- if a delivery dies mid-processing (timeout, restart), the `processing` row goes stale after 10 minutes and the event is reprocessed on Stripe's next retry instead of deduplicating forever
383
+ - **Failure tracking** -- failed events are marked with status and error message
384
+ - **Observability** -- all events (including unsupported types) are logged with `ignored` status
385
+
386
+ ### Supported Events
387
+
388
+ **Accounts V2 (thin events -- component fetches latest state, requires V2 event destination):**
389
+
390
+ - `v2.core.account.created`, `.updated`
391
+ - `v2.core.account[identity].updated`
392
+ - `v2.core.account[requirements].updated`
393
+ - `v2.core.account[configuration.merchant].updated`, `.capability_status_updated`
394
+ - `v2.core.account[configuration.customer].updated`
395
+ - `v2.core.account[configuration.recipient].updated`
396
+ - `v2.core.account[defaults].updated`
397
+ - `v2.core.account_person.created`, `.updated`
398
+ - `v2.core.account_link.returned`
399
+
400
+ **Billing (snapshot events -- payload contains full state):**
401
+
402
+ - `checkout.session.completed`
403
+ - `customer.subscription.created`, `.updated`, `.deleted`, `.trial_will_end`
404
+ - `invoice.created`, `.finalized`, `.paid`, `.payment_failed`
405
+ - `payment_intent.succeeded`, `.payment_failed`, `.canceled`
406
+ - `payout.created`, `.updated`, `.paid`, `.failed`
407
+ - `refund.created`, `.updated`, `.failed`
408
+ - `application_fee.refunded` -- keeps `feeCollectedAmount`/`feeRefundedAmount` accurate on the linked payment
409
+ - `charge.dispute.created`, `.updated`, `.closed`, `.funds_withdrawn`, `.funds_reinstated`
410
+ - `product.created`, `.updated`
411
+ - `price.created`, `.updated`
412
+
413
+ Note: Subscription and invoice events use v1 Billing API event names even when the billing entity is a V2 account referenced via `customer_account`.
414
+
415
+ ## Trigger API
416
+
417
+ The trigger system follows the BetterAuth pattern: define callbacks at client init time, export the `syncWebhook`/`asyncWebhook` pair via `webhookHandlers()`, and pass their function references to `registerRoutes` via `webhooks`.
418
+
419
+ ### SyncTriggers
420
+
421
+ Sync triggers run in the same transaction as the component's database write. They must be DB-only and idempotent. Throwing from a sync trigger rolls back the entire transaction (including the component upsert), causing Stripe to retry the webhook.
422
+
423
+ ```typescript
424
+ interface SyncTriggers {
425
+ account?: {
426
+ onCreate?: (ctx, doc) => Promise<void>;
427
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
428
+ };
429
+ subscription?: {
430
+ onCreate?: (ctx, doc) => Promise<void>;
431
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
432
+ onDelete?: (ctx, doc) => Promise<void>;
433
+ };
434
+ checkoutSession?: {
435
+ onCompleted?: (ctx, doc) => Promise<void>;
436
+ };
437
+ product?: {
438
+ onCreate?: (ctx, doc) => Promise<void>;
439
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
440
+ };
441
+ price?: {
442
+ onCreate?: (ctx, doc) => Promise<void>;
443
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
444
+ };
445
+ invoice?: {
446
+ onCreate?: (ctx, doc) => Promise<void>;
447
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
448
+ };
449
+ payment?: {
450
+ onCreate?: (ctx, doc) => Promise<void>;
451
+ };
452
+ payout?: {
453
+ onCreate?: (ctx, doc) => Promise<void>;
454
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
455
+ };
456
+ refund?: {
457
+ onCreate?: (ctx, doc) => Promise<void>;
458
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
459
+ };
460
+ dispute?: {
461
+ onCreate?: (ctx, doc) => Promise<void>;
462
+ onUpdate?: (ctx, newDoc, oldDoc) => Promise<void>;
463
+ };
464
+ }
465
+ ```
466
+
467
+ ### AsyncHooks
468
+
469
+ Async hooks run after the component's database write commits, in a separate scheduled action. Use these for external API calls (email, Slack, analytics). Failures do not roll back the component write.
470
+
471
+ ```typescript
472
+ interface AsyncHooks {
473
+ onAccountUpdated?: (ctx, account) => Promise<void>;
474
+ onCheckoutCompleted?: (ctx, session) => Promise<void>;
475
+ onSubscriptionUpdated?: (ctx, subscription) => Promise<void>;
476
+ onSubscriptionCanceled?: (ctx, subscription) => Promise<void>;
477
+ onTrialEnding?: (ctx, subscription) => Promise<void>;
478
+ onInvoicePaid?: (ctx, invoice) => Promise<void>;
479
+ onInvoicePaymentFailed?: (ctx, invoice) => Promise<void>;
480
+ onPaymentSucceeded?: (ctx, payment) => Promise<void>;
481
+ onPaymentFailed?: (ctx, payment) => Promise<void>;
482
+ onPayoutCompleted?: (ctx, payout) => Promise<void>;
483
+ onRefundCreated?: (ctx, refund) => Promise<void>;
484
+ onDisputeCreated?: (ctx, dispute) => Promise<void>;
485
+ onDisputeClosed?: (ctx, dispute) => Promise<void>;
486
+ }
487
+ ```
488
+
489
+ ### webhookHandlers()
490
+
491
+ Returns the `{ syncWebhook, asyncWebhook }` pair that bridges your app callbacks into the webhook processing pipeline. Export them from a Convex module (e.g. `convex/stripe.ts`) so they get function references the webhook handler can call:
492
+
493
+ ```typescript
494
+ export const { syncWebhook, asyncWebhook } = stripe.webhookHandlers();
495
+ ```
496
+
497
+ Then pass the module to `registerRoutes` as `webhooks: internal.stripe`.
498
+
499
+ **How `syncWebhook` works.** It is a single internal mutation that routes by a `dispatcher` discriminator to perform the component table upsert **and** your configured sync trigger inside one transaction. It reads the existing doc (to decide `onCreate` vs `onUpdate` and supply `oldDoc`), runs the upsert, re-reads the doc, and invokes your trigger. If the trigger throws, the whole mutation — including the component write — rolls back, the webhook handler marks the ledger row `failed`, and returns 500 so Stripe retries. On retry, failed ledger rows are reset and the event is reprocessed.
500
+
501
+ **How `asyncWebhook` works.** It is a single internal action that routes by a `hook` discriminator. After the `syncWebhook` transaction commits and the ledger marks the event `processed`, the webhook handler schedules `asyncWebhook` via `ctx.scheduler` with the committed doc. Hook failures never roll back the component write.
502
+
503
+ Exactly one hook (at most) is scheduled per event:
504
+
505
+ | Stripe event | Scheduled hook |
506
+ | ------------------------------------------------- | --------------------------- |
507
+ | `v2.core.account*` (all account lifecycle events) | `afterAccountUpdated` |
508
+ | `checkout.session.completed` | `afterCheckoutCompleted` |
509
+ | `customer.subscription.created` / `.updated` | `afterSubscriptionUpdated` |
510
+ | `customer.subscription.deleted` | `afterSubscriptionCanceled` |
511
+ | `customer.subscription.trial_will_end` | `afterTrialEnding` |
512
+ | `invoice.paid` | `afterInvoicePaid` |
513
+ | `invoice.payment_failed` | `afterInvoicePaymentFailed` |
514
+ | `payment_intent.succeeded` | `afterPaymentSucceeded` |
515
+ | `payment_intent.payment_failed` | `afterPaymentFailed` |
516
+ | `payout.paid` | `afterPayoutCompleted` |
517
+ | `refund.created` | `afterRefundCreated` |
518
+ | `charge.dispute.created` | `afterDisputeCreated` |
519
+ | `charge.dispute.closed` | `afterDisputeClosed` |
520
+
521
+ All other processed events (e.g. `payment_intent.canceled`, `payout.failed`, `invoice.created`, `refund.updated`, `charge.dispute.funds_withdrawn`) update the component tables but schedule no hook.
522
+
523
+ > **Note:** async hooks should be idempotent. Duplicate delivery is possible in rare ledger-failure cases (e.g. the event is processed and the hook scheduled, but the ledger update fails and Stripe redelivers).
524
+
525
+ The raw callbacks you pass to `triggers` and `hooks` on the `BetterStripe` constructor are the source of truth for app behavior. The exported `syncWebhook`/`asyncWebhook` pair is the bridge that makes them callable from the Convex runtime — events whose triggers you did not configure simply run the upsert (no sync trigger) and schedule no hook.
526
+
527
+ ### Dunning & smart retries
528
+
529
+ Failed recurring payments are recovered by **Stripe Smart Retries**, not by any retry loop in this library. The component never re-attempts a charge itself — it tracks the delinquency and fires hooks so your app can notify the customer. Retry _timing and count_ are owned entirely by Stripe.
530
+
531
+ **Required Dashboard settings** (Stripe controls the schedule; enable these once):
532
+
533
+ - **Subscriptions:** Dashboard → **Billing → Revenue recovery → Retries** — turn on **Smart Retries** (Stripe's recommended, ML-timed schedule). Also set what happens when retries are exhausted (leave `past_due`, mark `unpaid`, or cancel).
534
+ - **One-time invoices:** Dashboard → **Settings → Billing → Invoices** — configure retry behavior for invoices not tied to a subscription.
535
+ - Ensure the `invoice.payment_failed` and `customer.subscription.updated` events are delivered to your webhook endpoint.
536
+
537
+ **What the component surfaces:**
538
+
539
+ - The subscription row tracks Stripe's delinquency states — `past_due` (first failed charge) and `unpaid` (retries exhausted) — arriving via `customer.subscription.updated`, which fires **`onSubscriptionUpdated`**.
540
+ - Each `invoice.payment_failed` fires **`onInvoicePaymentFailed`** with the committed invoice. Under Smart Retries the invoice carries `nextPaymentAttempt` (ISO time of Stripe's next retry) and `attemptCount`, so a dunning email can tell the buyer exactly when Stripe will try again. Both clear once the invoice is paid or retries stop.
541
+
542
+ `onInvoicePaymentFailed` is the **invoice-level** (subscription-cycle) failure — distinct from `onPaymentFailed`, which fires on a one-time **PaymentIntent** failure (`payment_intent.payment_failed`) and receives a payment, not an invoice.
543
+
544
+ > **Limitation:** `nextPaymentAttempt` is captured from the `invoice.payment_failed` payload, which is correct for Smart Retries. If you instead use a **custom retry _automation_**, Stripe sets `next_payment_attempt` on `invoice.updated` (not `invoice.payment_failed`); the component does not currently process `invoice.updated`, so the retry timestamp may lag until the next handled invoice event.
545
+
546
+ ## Marketplace Economics
547
+
548
+ The platform is always the merchant of record (Skool-style marketplace model): sellers are Connect recipients, not merchants. This section covers the fee, split, payout, dispute, and refund/descriptor primitives that implement that model. All amounts are minor units (cents).
549
+
550
+ ### Fee Model
551
+
552
+ `PlatformFeeConfig` is the platform's take on a sale:
553
+
554
+ ```typescript
555
+ type FeeTier = { upTo: number | null; percent: number; fixed?: number };
556
+ type PlatformFeeConfig = {
557
+ percent: number; // base percentage (0–100)
558
+ fixed?: number; // optional fixed surcharge, minor units
559
+ tiers?: FeeTier[]; // optional; overrides the base by charge amount
560
+ };
561
+ ```
562
+
563
+ Configure a default at construction (`new BetterStripe(component, { platformFee: {...} })`), and/or pass a per-call `fee` override (type `FeeOverride`, same shape as `PlatformFeeConfig`) to `createCheckoutSession`/`createSubscription` — the override wins. `stripe.resolveFee(override?)` resolves the effective config the same way the client does internally, and `stripe.platformFee` reads the configured default back.
564
+
565
+ ```typescript
566
+ import { computeFee } from "@fantastic.dev/better-stripe";
567
+
568
+ const { feeAmount, percentApplied, fixedApplied, tier } = computeFee(2999, {
569
+ percent: 10,
570
+ fixed: 30,
571
+ });
572
+ ```
573
+
574
+ `computeFee(amount, config)` picks the first tier whose `upTo` covers the amount (a final `upTo: null` is the catch-all), rounds half-up, and caps the fee at the charge amount. It's exported so an app can preview "platform keeps $X" client-side before checkout.
575
+
576
+ **How the fee is charged** depends on shape and charge type:
577
+
578
+ - **Percent-only** fees (`isPercentOnlyFee(config)` — no `fixed`, no `tiers`) map directly to Stripe's `application_fee_percent` on the subscription/PaymentIntent — no per-invoice computation needed.
579
+ - **Fixed or tiered** fees can't be expressed as a flat Stripe percentage, so they're computed and applied per invoice (`applyPerInvoiceFee`, at `invoice.created`) or per one-time charge (`applyPerChargeFee`) in the webhook processor, via `application_fee_amount`.
580
+ - This per-invoice path shares the same first-invoice timing gap as statement descriptors — see [BTS-68](#roadmap--known-gaps).
581
+
582
+ Fees only apply to **destination charges** (`destinationAccountId` set, or a single-recipient `split`). The **separate-charges-and-transfers** path (multi-recipient `split`) never uses `application_fee` — the platform's cut is realized by transferring less than was charged (see Split Engine below).
583
+
584
+ ### Split Engine
585
+
586
+ For a sale split across multiple recipients (store + affiliate(s)), pass `split` instead of `destinationAccountId` to `createCheckoutSession`/`createSubscription`:
587
+
588
+ ```typescript
589
+ type SplitRecipient = {
590
+ destinationAccountId: string;
591
+ role: "store" | "affiliate" | "other";
592
+ amount?: number; // exactly one of amount/percent
593
+ percent?: number; // percent of the gross charge amount
594
+ };
595
+
596
+ await stripe.createCheckoutSession(ctx, {
597
+ userId,
598
+ stripePriceId,
599
+ mode: "payment",
600
+ returnUrl,
601
+ split: [
602
+ { destinationAccountId: storeAccountId, role: "store", percent: 80 },
603
+ { destinationAccountId: affiliateAccountId, role: "affiliate", percent: 10 },
604
+ ],
605
+ fee: { percent: 10 }, // per-call override; omit to use the configured default
606
+ });
607
+ ```
608
+
609
+ - **A single-recipient `split`** is treated as a plain destination charge (equivalent to `destinationAccountId`) — `application_fee_percent`/`application_fee_amount` applies as above.
610
+ - **A multi-recipient `split`** routes via **separate charges & transfers**: the platform charges the full amount, then the webhook engine (`createSplitTransfers`, on `payment_intent.succeeded`/`invoice.paid`) creates one Stripe `Transfer` per recipient with `source_transaction` linkage. No `application_fee` is used on this path — the platform's cut is the remainder after transfers.
611
+ - **Subscriptions** re-run the split on every billing cycle (each invoice re-reads the subscription's `split`/`feeConfig` markers), so per-cycle recipient amounts stay in sync with the config at charge time.
612
+
613
+ The core math is exported for previewing splits client-side:
614
+
615
+ ```typescript
616
+ import { computeSplit } from "@fantastic.dev/better-stripe";
617
+
618
+ const result = computeSplit(10000, { percent: 10 }, [
619
+ { destinationAccountId: "acct_store", role: "store", percent: 80 },
620
+ { destinationAccountId: "acct_affiliate", role: "affiliate", percent: 10 },
621
+ ]);
622
+ // result.transfers: [{ destinationAccountId, role, amount }, ...]
623
+ // result.platformFee: the resolver's cut; result.platformRetained: amount − sum(transfers)
624
+ ```
625
+
626
+ `computeSplit` throws if the transfers plus the platform fee would exceed the charge amount — the platform is always left with at least its configured cut. Any rounding remainder stays with the platform.
627
+
628
+ ### Payouts
629
+
630
+ Payouts are **automatic and rolling** (Stripe-managed schedule, via hosted Express onboarding) — there is no manual-withdrawal API. `listPayouts`/`createPayout` track/trigger payouts for a Connect account; `PayoutSchedule` (React) and `useEarnings` (React) surface the recipient's balance and next expected payout, with a link out to the hosted Express dashboard for details. See [React Hooks](#react-hooks) and [React Components](#react-components).
631
+
632
+ ### Disputes
633
+
634
+ The platform is merchant of record, so a chargeback lands on the platform's Stripe account even for a seller's sale. The dispute pipeline (all webhook-driven, on `charge.dispute.*`):
635
+
636
+ 1. **Clawback** — when a dispute opens (`charge.dispute.created`), `reverseTransfers` reverses the split/destination transfers funded by the disputed charge, pro-rata to the disputed amount, so recipients bear their share of the loss. Idempotent via the dispute id.
637
+ 2. **Reinstatement** — if the dispute is won (`.closed` with `status: "won"`, or `.funds_reinstated`), `reinstateTransfers` re-creates transfers for the amounts clawed back, paying recipients back from the platform balance (Stripe's own reversal is permanent, so winning means paying again).
638
+ 3. **Auto-cancel** — on dispute open, the disputed subscription (resolved PaymentIntent → invoice → subscription) is canceled by default (`registerRoutes`'s `autoCancelOnDispute`, default `true`; pairs with `cancelDisputeAtPeriodEnd`, default `false` → cancel-at-period-end, matching the Skool model of "cancel now, remove access at cycle end").
639
+
640
+ Sellers respond to their own disputes without platform staff involvement, via an embedded Stripe Connect session:
641
+
642
+ ```typescript
643
+ // server: expose the account session
644
+ export const createDisputeSession = action({
645
+ args: { stripeAccountId: v.string() },
646
+ handler: async (ctx, args) => stripe.createDisputeSession(ctx, args),
647
+ });
648
+ ```
649
+
650
+ `stripe.createDisputeSession(ctx, { stripeAccountId })` creates an Account Session scoped to `disputes_list`/`payment_disputes` — mount it with the `ConnectProvider`/`EmbeddedDisputes` React components (see [Embedded Disputes](#embedded-disputes-stripe-connect)), or build a custom UI on `updateDispute`/`closeDispute` plus the headless `DisputesList`/`DisputeDetail`/`EvidenceForm` components and `buildDisputeEvidence`/`disputeEvidenceCountdown` helpers (see [React Components](#react-components)).
651
+
652
+ `stripe.reverseTransfers(ctx, { sourceChargeId, percent?, amount? })` is also exposed directly, for manual clawback outside the automatic dispute flow (e.g. a support-initiated partial reversal). The internal engine additionally accepts an `operationId` for a stable Stripe idempotency key (used by the automatic dispute flow); the public method doesn't expose it yet, so a manual call relies on Stripe's default request idempotency.
653
+
654
+ ### Refunds and Statement Descriptors
655
+
656
+ `createRefund(ctx, { stripePaymentIntentId?, stripeChargeId?, amount?, reason?, refundApplicationFee?, reverseTransfer?, ... })` issues a Stripe refund with marketplace semantics, both defaulting **on**:
657
+
658
+ - `refundApplicationFee` — return the platform's application fee pro-rata with the refund (destination charges only; Stripe pro-rates partial refunds automatically).
659
+ - `reverseTransfer` — pull the refunded amount back from the destination account (destination charges only; also pro-rated for partials).
660
+
661
+ Stripe hard-errors if either flag is sent for a charge that doesn't carry an application fee / destination transfer, so `createRefund` resolves the charge first and only sends each flag when the charge can honor it. **Split (separate-charges) sales carry neither** — those go through the same charge, so their clawback is webhook-driven: on `refund.created`/`.updated`, `reverseTransfersForRefund` reverses each recipient's ledger leg pro-rata to Stripe's cumulative `amount_refunded`, converging correctly across multiple partial refunds (and coexisting with a prior dispute clawback on the same charge). A separate `application_fee.refunded` handler keeps the linked payment's `feeCollectedAmount`/`feeRefundedAmount` in sync. The `refunds` table and the linked `payments` row update as the corresponding webhooks arrive; `createRefund` itself returns only the new refund id.
662
+
663
+ Per-store statement descriptors make destination charges recognizable on a buyer's card statement (`PLATFORMPREFIX* SUFFIX`):
664
+
665
+ ```typescript
666
+ await stripe.setAccountStatementDescriptor(ctx, {
667
+ stripeAccountId,
668
+ statementDescriptor: "ACME STORE", // or null to clear
669
+ });
670
+ ```
671
+
672
+ Validated against Stripe's rules (`validateStatementDescriptorSuffix`: 1–22 chars, at least one Latin letter, no `< > \ ' " *`, no non-Latin — rejects rather than truncates) before writing. Resolution order per charge: the store's stored suffix → the platform's configured `statementDescriptorSuffix` default (constructor option) → none. One-time payments set the suffix directly on the PaymentIntent at checkout; subscriptions set it on each invoice via the webhook processor — see [BTS-67](#roadmap--known-gaps) for the one gap in that mechanism (the first subscription charge).
673
+
674
+ ## React Hooks
675
+
676
+ Import from `@fantastic.dev/better-stripe/react`. All hooks use Convex's `useQuery` and `useMutation` internally.
677
+
678
+ Read hooks are exported as factory functions that take the app's `useQuery` binding and a query function reference, allowing them to work with any component registration name. Hooks that take a single ID argument accept `undefined` and skip the query (via Convex's `"skip"` sentinel) until the ID is available.
679
+
680
+ ### Read Hooks
681
+
682
+ | Hook Factory | Hook Arguments | Returns |
683
+ | ---------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
684
+ | `createUseAccount` | `(userId?)` | `{ account, isLoading }` |
685
+ | `createUseProducts` | `({ accountId?, active? }?)` | `{ products, isLoading }` |
686
+ | `createUsePrices` | `(productId?)` | `{ prices, isLoading }` |
687
+ | `createUseSubscription` | `(subscriptionId?)` | `{ subscription, isActive, isTrialing, isCanceling, daysUntilRenewal, daysUntilTrialEnd, isLoading }` |
688
+ | `createUseSubscriptions` | `({ userId?, status? }?)` | `{ subscriptions, activeSubscription, isLoading }` |
689
+ | `createUseCheckout` | `(sessionId?)` | `{ session, status, isComplete, isLoading }` |
690
+ | `createUsePaymentMethods` | `(accountId?)` | `{ methods, defaultMethod, isLoading }` |
691
+ | `createUseInvoices` | `({ userId?, subscriptionId?, status? }?)` | `{ invoices, isLoading }` |
692
+ | `createUseAccountOnboarding` | `(accountId?)` | `{ account, status, isReady, missingRequirements, isLoading }` |
693
+ | `createUseEarnings` | `(accountId?)` | `{ gross, reversed, net, payouts, paidOut, transfers, isLoading }` — recipient balance/earnings (BTS-36) |
694
+ | `createUseSplitBreakdown` | `({ sourceChargeId?, saleAmount? })` | `{ breakdown: { legs, store, affiliate, other, recipientsTotal, platform? } \| null, isLoading }` — per-sale split (BTS-36) |
695
+ | `createUseDisputes` | `({ accountId?, status? }?)` | `{ disputes, isLoading }` |
696
+ | `createUseDisputeWithCountdown` | `(stripeDisputeId?)` | `{ dispute, countdown: { dueBy?, daysRemaining?, isOverdue } \| null, isLoading }` |
697
+
698
+ ### Checkout Session Hooks
699
+
700
+ For Stripe Checkout Session custom UI flows (CheckoutProvider-based):
701
+
702
+ | Hook / Component | Description |
703
+ | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
704
+ | `CheckoutSessionProvider` | Provider wrapping Stripe's `CheckoutProvider`. Accepts `publishableKey`, `clientSecret`, `appearance`. |
705
+ | `useCheckoutSession()` | Returns `{ type, sessionId, canConfirm, confirm(opts?) }` — discriminated union for checkout state/actions. |
706
+
707
+ ```tsx
708
+ import {
709
+ CheckoutSessionProvider,
710
+ PaymentElement,
711
+ useCheckoutSession,
712
+ } from "@fantastic.dev/better-stripe/react";
713
+
714
+ <CheckoutSessionProvider publishableKey={pk} clientSecret={token}>
715
+ <MyForm />
716
+ </CheckoutSessionProvider>;
717
+
718
+ function MyForm() {
719
+ const checkout = useCheckoutSession();
720
+ if (checkout.type !== "success") return <Spinner />;
721
+ return (
722
+ <>
723
+ <PaymentElement />
724
+ <button
725
+ disabled={!checkout.canConfirm}
726
+ onClick={() => checkout.confirm()}
727
+ >
728
+ Pay
729
+ </button>
730
+ </>
731
+ );
732
+ }
733
+ ```
734
+
735
+ ### Payment Confirmation Hooks
736
+
737
+ | Hook | Description |
738
+ | --------------------- | ----------------------------------------------------------------------------------------------------- |
739
+ | `useConfirmPayment()` | Provides `confirmPayment(clientSecret)`, `confirmCardSetup(clientSecret)`, `confirmSetup(returnUrl?)` |
740
+
741
+ All return `{ success: true } | { success: false, error: string }`.
742
+
743
+ ### Payment Method Action Hooks
744
+
745
+ | Hook | Description |
746
+ | ----------------------------- | ------------------------------------------------------------------------------------- |
747
+ | `usePaymentMethodActions(cb)` | Provides `createAndAttach()`, `detach(id)`, `setDefault(id)` with loading/error state |
748
+
749
+ Accepts app-provided callbacks for backend operations (attach, detach, setDefault, reload).
750
+
751
+ ### Theming
752
+
753
+ | API | Description |
754
+ | -------------------------------- | ------------------------------------------------------------------------- |
755
+ | `createStripeAppearance(config)` | Factory: color tokens → Stripe `Appearance` object |
756
+ | `createStripeElementStyles(cfg)` | Factory: color tokens → inline `style` for CardNumber/Expiry/CVC elements |
757
+ | `defaultStripeAppearance` | Light preset |
758
+ | `darkStripeAppearance` | Dark preset |
759
+
760
+ ### Re-exported Stripe Elements
761
+
762
+ These are re-exported so apps never need to import from `@stripe/react-stripe-js` directly:
763
+
764
+ `PaymentElement`, `CardElement`, `CardNumberElement`, `CardExpiryElement`, `CardCvcElement`
765
+
766
+ ## React Components
767
+
768
+ Import from `@fantastic.dev/better-stripe/react`. All components are headless by default -- they provide behavior and minimal structure. Style them with Tailwind or any CSS approach.
769
+
770
+ All components accept:
771
+
772
+ - `theme?: Stripe.Appearance` -- Stripe Appearance API object for styling
773
+ - `className?: string` -- outer wrapper styling
774
+ - String props for i18n with English defaults (e.g., `submitLabel?: string`)
775
+ - Standard React props (`children`, event handlers)
776
+
777
+ ### Provider
778
+
779
+ | Component | Description |
780
+ | ------------------------- | ------------------------------------------------------------------------------------------------ |
781
+ | `StripeProvider` | Stripe Elements context provider. Accepts `publishableKey` prop. |
782
+ | `CheckoutSessionProvider` | Checkout Session context provider for custom UI flows. Accepts `publishableKey`, `clientSecret`. |
783
+
784
+ ### Checkout and Subscription
785
+
786
+ | Component | Description |
787
+ | ----------------------- | --------------------------------------------------------- |
788
+ | `EmbeddedCheckout` | Headless embedded checkout with render-prop loading state |
789
+ | `CheckoutStatus` | Checkout session status display |
790
+ | `PricePicker` | Plan/price selection with render-prop customization |
791
+ | `PriceCard` | Individual price card (controlled or uncontrolled) |
792
+ | `IntervalSelector` | Billing interval toggle (month/year) |
793
+ | `SubscriptionCard` | Current subscription display |
794
+ | `SubscriptionLineItems` | Line item breakdown |
795
+ | `PriceBadge` | Price/plan badge |
796
+ | `TrialAlert` | Trial status and renewal alert |
797
+ | `BillingPortalLink` | Link/button to Stripe billing portal |
798
+ | `SubscriptionActions` | Cancel/reactivate action buttons (status-aware) |
799
+
800
+ ### Payment Methods
801
+
802
+ | Component | Description |
803
+ | --------------------------- | -------------------------------------------------- |
804
+ | `AddCardForm` | Headless add-payment-method form |
805
+ | `PaymentMethodsList` | Saved payment methods list with render props |
806
+ | `DeletePaymentMethodDialog` | Remove payment method (app provides dialog chrome) |
807
+ | `PaymentMethodActions` | Per-method set-default/delete actions |
808
+
809
+ ### Buyer Billing
810
+
811
+ | Component | Description |
812
+ | ------------------ | --------------------------------------------------------------------- |
813
+ | `BuyerBillingView` | Per-store buyer billing view: subscriptions grouped by store, reusable saved card, embedded card update |
814
+
815
+ An embedded-only billing surface for buyers: their subscriptions are grouped by
816
+ store (each store scoped via the `listSubscriptionsByUserAndStore` /
817
+ `groupSubscriptionsByStore` per-store queries) with per-store cancel/reactivate,
818
+ alongside the ONE saved payment method that is reusable across every store. The
819
+ card is updated in place via an embedded `AddCardForm` slot — no redirect.
820
+
821
+ ```tsx
822
+ import {
823
+ BuyerBillingView,
824
+ AddCardForm,
825
+ StripeProvider,
826
+ } from "@fantastic.dev/better-stripe/react";
827
+ import { groupSubscriptionsByStore } from "@fantastic.dev/better-stripe";
828
+
829
+ function BuyerBilling({ userId, customerAccount }: Props) {
830
+ const subscriptions = useQuery(api.stripe.listSubscriptionsByUser, { userId });
831
+ const { defaultMethod } = usePaymentMethods(customerAccount);
832
+ const cancel = useMutation(api.stripe.cancelSubscription);
833
+ const reactivate = useMutation(api.stripe.reactivateSubscription);
834
+
835
+ return (
836
+ <BuyerBillingView
837
+ // groupSubscriptionsByStore reused, not recomputed
838
+ subscriptions={subscriptions?.map((s) => ({ ...s, id: s.stripeSubscriptionId }))}
839
+ paymentMethod={defaultMethod}
840
+ isLoading={subscriptions === undefined}
841
+ onCancel={(sub) => cancel({ stripeSubscriptionId: sub.id })}
842
+ onReactivate={(sub) => reactivate({ stripeSubscriptionId: sub.id })}
843
+ updateCardSlot={
844
+ <StripeProvider publishableKey={pk}>
845
+ <AddCardForm onSuccess={handleCardSaved} />
846
+ </StripeProvider>
847
+ }
848
+ />
849
+ );
850
+ }
851
+ ```
852
+
853
+ ### Connect and Marketplace
854
+
855
+ | Component | Description |
856
+ | ------------------------- | --------------------------------------------- |
857
+ | `ConnectStatusBadge` | Connect verification status badge |
858
+ | `AccountOnboardingCard` | Connect onboarding progress display |
859
+ | `AccountOnboardingButton` | Continue onboarding action (status-aware) |
860
+ | `AccountCreateCard` | Create Connect account card |
861
+ | `AccountCreateButton` | Create account action with loading state |
862
+ | `AccountLoginCard` | Login to Connect dashboard card |
863
+ | `AccountLoginButton` | Dashboard login/open action |
864
+ | `AccountCloseCard` | Close/restart account card (status-aware) |
865
+ | `AccountCloseButton` | Close/restart action with status-aware labels |
866
+ | `ConnectRequirements` | Missing requirements checklist |
867
+
868
+ ### Payouts and Earnings
869
+
870
+ | Component | Description |
871
+ | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
872
+ | `PayoutSchedule` | Recipient balance + next-payout display, fed by a `balance` snapshot and `listPayouts` rows. Payouts are automatic/rolling — no manual-withdrawal action is offered. |
873
+ | `EarningsSummary` | Gross / reversals & adjustments / net + latest payout, fed by `useEarnings(accountId)`. Reversals cover both deferred fee collection and refund/dispute clawbacks — not a pure fees figure, hence the "Reversals & adjustments" label rather than "Fees". |
874
+ | `SplitBreakdown` | Per-sale store / affiliate / other / platform split lines, fed by `useSplitBreakdown`. The platform line reads "unknown" (not $0) when the hook wasn't given the sale amount. |
875
+
876
+ ### Disputes (headless)
877
+
878
+ The app-owned alternative to [Embedded Disputes](#embedded-disputes-stripe-connect) below — build a custom dispute UI on the read hooks and these components instead of Stripe's hosted ConnectJS components.
879
+
880
+ | Component | Description |
881
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
882
+ | `DisputesList` | Sorted-by-deadline dispute list (soonest evidence due-by first, no-deadline last), fed by `useDisputes` |
883
+ | `DisputeDetail` | Amount, reason, status, evidence-due countdown, and linked transfers for one dispute, fed by `useDisputeWithCountdown` |
884
+ | `EvidenceForm` | Plain-language evidence form (product description, access activity, additional info, customer communication) that maps through `buildDisputeEvidence` before calling an app-wired `onUpdateDispute`; `stage()` saves a draft, `submit()` finalizes |
885
+
886
+ ### Embedded Disputes (Stripe Connect)
887
+
888
+ The Stripe-hosted alternative to the headless dispute components: each seller
889
+ views and responds to their own disputes via Stripe's embedded `disputes_list`
890
+ / `payment_disputes` components, driven by the Account Session that
891
+ `createDisputeSession` creates.
892
+
893
+ | Component | Description |
894
+ | ------------------ | ---------------------------------------------------------------------------------------------- |
895
+ | `ConnectProvider` | Initializes ConnectJS with your publishable key + an account-session fetcher |
896
+ | `EmbeddedDisputes` | Mounts the embedded `disputes_list` (or `payment_disputes` when scoped via `payment`) component |
897
+
898
+ **Dependencies:** the wrapper uses [`@stripe/react-connect-js`](https://www.npmjs.com/package/@stripe/react-connect-js) and [`@stripe/connect-js`](https://www.npmjs.com/package/@stripe/connect-js), which ship as regular dependencies of this package (same convention as `@stripe/react-stripe-js` / `@stripe/stripe-js`) -- no extra install step. ConnectJS components are client-only iframes; render them in client components.
899
+
900
+ ```tsx
901
+ // convex/stripe.ts — expose the account session (server side, BTS-30)
902
+ export const createDisputeSession = action({
903
+ args: { stripeAccountId: v.string() },
904
+ handler: async (ctx, args) => stripe.createDisputeSession(ctx, args),
905
+ });
906
+
907
+ // Seller disputes page (client side)
908
+ import { ConnectProvider, EmbeddedDisputes } from "@fantastic.dev/better-stripe/react";
909
+
910
+ function SellerDisputes({ stripeAccountId }: { stripeAccountId: string }) {
911
+ const createSession = useAction(api.stripe.createDisputeSession);
912
+ return (
913
+ <ConnectProvider
914
+ publishableKey={import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY}
915
+ fetchClientSecret={async () =>
916
+ (await createSession({ stripeAccountId })).clientSecret
917
+ }
918
+ >
919
+ <EmbeddedDisputes />
920
+ </ConnectProvider>
921
+ );
922
+ }
923
+ ```
924
+
925
+ ## Testing Utilities
926
+
927
+ Import from `@fantastic.dev/better-stripe/testing`.
928
+
929
+ ### assertTestEnvironment
930
+
931
+ Guards against running test fixtures with live Stripe keys:
932
+
933
+ ```typescript
934
+ import { assertTestEnvironment } from "@fantastic.dev/better-stripe/testing";
935
+
936
+ assertTestEnvironment(); // Throws if STRIPE_SECRET_KEY does not start with sk_test_
937
+ ```
938
+
939
+ ### Fixture Factories
940
+
941
+ Typed factories for creating Stripe test data:
942
+
943
+ ```typescript
944
+ import {
945
+ createTestAccount,
946
+ createTestPrice,
947
+ createTestProduct,
948
+ createTestSubscription,
949
+ } from "@fantastic.dev/better-stripe/testing";
950
+
951
+ const account = await createTestAccount(stripe, { email: "test@example.com" });
952
+ const product = await createTestProduct(stripe, { name: "Pro Plan" });
953
+ const price = await createTestPrice(stripe, {
954
+ productId: product.id,
955
+ unitAmount: 2999,
956
+ interval: "month",
957
+ });
958
+ ```
959
+
960
+ ### Mock Webhook Events
961
+
962
+ Factories for creating mock webhook events in tests:
963
+
964
+ ```typescript
965
+ import {
966
+ mockAccountUpdated,
967
+ mockCheckoutCompleted,
968
+ mockInvoicePaid,
969
+ mockSubscriptionUpdated,
970
+ } from "@fantastic.dev/better-stripe/testing";
971
+
972
+ const event = mockCheckoutCompleted({
973
+ stripeSessionId: "cs_test_123",
974
+ metadata: { userId: "user_abc" },
975
+ });
976
+ ```
977
+
978
+ ## Configuration
979
+
980
+ ### Environment Variables
981
+
982
+ | Variable | Required | Read by | Description |
983
+ | -------------------------- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
984
+ | `STRIPE_SECRET_KEY` | Yes | Component | Declared in the component's `convex.config.ts` (required) and read by the component (e.g. `getStripeMode`). Also passed explicitly via the `BetterStripe` constructor and `registerRoutes`. The installing app must wire it to the component — see below. |
985
+ | `STRIPE_WEBHOOK_SECRET` | Yes | App | Signing secret for the V1 snapshot event destination. Read by `registerRoutes` in the app, not the component. |
986
+ | `STRIPE_WEBHOOK_SECRET_V2` | No\* | App | Signing secret for the V2 thin event destination (Connect account events). \*Required whenever your V2 destination has its own secret (the usual case); falls back to `STRIPE_WEBHOOK_SECRET` if unset. |
987
+ | `STRIPE_PUBLISHABLE_KEY` | Yes (React) | Frontend | A public, frontend-only key. Supply it from the frontend's own env (`VITE_STRIPE_PUBLISHABLE_KEY` / `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`) and pass it as the `publishableKey` prop to the React components. It is **not** a component env var. |
988
+
989
+ ### Wiring component env vars
990
+
991
+ The component declares `STRIPE_SECRET_KEY` as a required environment variable in
992
+ its `convex.config.ts`. Convex isolates a component's functions from the
993
+ deployment's `process.env`, so setting the var with `convex env set` is **not**
994
+ enough on its own — the installing app must provide it to the component via
995
+ `app.use`:
996
+
997
+ ```ts
998
+ // convex/convex.config.ts
999
+ import { defineApp } from "convex/server";
1000
+ import { v } from "convex/values";
1001
+ import betterStripe from "@fantastic.dev/better-stripe/convex.config";
1002
+
1003
+ const app = defineApp({
1004
+ env: { STRIPE_SECRET_KEY: v.string() },
1005
+ });
1006
+ // Pass by reference so the component always sees the deployment's current value
1007
+ // (set via `convex env set STRIPE_SECRET_KEY ...`).
1008
+ app.use(betterStripe, {
1009
+ env: { STRIPE_SECRET_KEY: app.env.STRIPE_SECRET_KEY },
1010
+ });
1011
+ export default app;
1012
+ ```
1013
+
1014
+ The webhook secrets (`STRIPE_WEBHOOK_SECRET`, `STRIPE_WEBHOOK_SECRET_V2`) are read
1015
+ by the app's `registerRoutes`, not the component, so they only need to be set in
1016
+ the deployment env — no `app.use` wiring required.
1017
+
1018
+ ### Stripe API Version
1019
+
1020
+ The component pins the Stripe API version internally (`2026-05-27.dahlia`). Upgrading the pinned version requires a package release and changelog entry. Apps do not need to set `STRIPE_API_VERSION`.
1021
+
1022
+ ### SDK Management
1023
+
1024
+ The component owns the Stripe SDK instance internally via a keyed client cache (keyed by API key). Apps pass `STRIPE_SECRET_KEY`; the component handles versioning and client lifecycle. Apps should not create their own Stripe SDK instances for operations that go through the component.
1025
+
1026
+ ## Architecture
1027
+
1028
+ ### Component-Owned Tables
1029
+
1030
+ The component manages 8 domain tables and 1 internal table:
1031
+
1032
+ | Table | Description |
1033
+ | ------------------ | -------------------------------------------------------- |
1034
+ | `accounts` | V2 account records with identity and configuration state |
1035
+ | `products` | Stripe products with optional trial day management |
1036
+ | `prices` | Stripe prices linked to products |
1037
+ | `subscriptions` | Subscription lifecycle with first-class trial tracking |
1038
+ | `checkoutSessions` | Checkout session state (embedded and redirect) |
1039
+ | `invoices` | Invoice records with subscription metadata |
1040
+ | `payments` | Payment intent records |
1041
+ | `payouts` | Payout records for Connect/marketplace |
1042
+ | `webhookEvents` | Internal ledger for replay protection and observability |
1043
+
1044
+ ### App-Layer Tables
1045
+
1046
+ The consuming app maintains its own tables for business context. The component never reads or writes app tables directly. App tables are updated via sync triggers that run in the same transaction as component writes.
1047
+
1048
+ Example app-layer tables (from a typical integration):
1049
+
1050
+ - Linking products to app-specific entities (e.g., communities, teams)
1051
+ - Linking subscriptions to app-specific purchase types
1052
+ - Payout percentage configurations
1053
+
1054
+ ### Trigger Flow
1055
+
1056
+ ```
1057
+ Stripe Webhook Event
1058
+ |
1059
+ v
1060
+ Webhook handler: Verify signature + check ledger
1061
+ |
1062
+ v
1063
+ syncWebhook (one mutation transaction)
1064
+ - Upsert component domain table
1065
+ - Run sync trigger --> App updates its own tables
1066
+ | Throwing rolls back the upsert;
1067
+ | Stripe retries and the failed
1068
+ | ledger row is reprocessed
1069
+ v
1070
+ Mark ledger row processed
1071
+ |
1072
+ v
1073
+ Async hook (scheduled action) --> App calls external APIs
1074
+ Failures do not roll back;
1075
+ hooks should be idempotent
1076
+ ```
1077
+
1078
+ ### Package Entry Points
1079
+
1080
+ | Entry Point | Contents |
1081
+ | -------------------------------------- | -------------------------------------------------------- |
1082
+ | `@fantastic.dev/better-stripe` | `BetterStripe` class, `registerRoutes`, TypeScript types |
1083
+ | `@fantastic.dev/better-stripe/react` | React hooks, headless UI components, formatting helpers |
1084
+ | `@fantastic.dev/better-stripe/testing` | Test fixtures, mock webhooks, `assertTestEnvironment` |
1085
+ | `@fantastic.dev/better-stripe/convex.config` | Convex component registration |
1086
+
1087
+ ### Error Handling
1088
+
1089
+ Structured errors are thrown as `ConvexError` with a `BetterStripeError` payload:
1090
+
1091
+ ```typescript
1092
+ interface BetterStripeError {
1093
+ code: BetterStripeErrorCode;
1094
+ message: string;
1095
+ stripeError?: {
1096
+ type: string;
1097
+ code?: string;
1098
+ message: string;
1099
+ };
1100
+ }
1101
+ ```
1102
+
1103
+ Error codes: `ACCOUNT_NOT_FOUND`, `ACCOUNT_CREATE_FAILED`, `PRODUCT_NOT_FOUND`, `PRICE_NOT_FOUND`, `SUBSCRIPTION_NOT_FOUND`, `SUBSCRIPTION_UPDATE_FAILED`, `CHECKOUT_CREATE_FAILED`, `CHECKOUT_NOT_FOUND`, `PAYMENT_METHOD_FAILED`, `WEBHOOK_VERIFICATION_FAILED`, `WEBHOOK_DUPLICATE_EVENT`, `STRIPE_API_ERROR`, `TEST_ENV_REQUIRED`, `INVALID_CONFIGURATION`.
1104
+
1105
+ > **Note:** All methods that throw their own errors or catch-and-rethrow now use structured `ConvexError(BetterStripeError)` payloads. Methods that let uncaught Stripe SDK errors propagate are a separate policy decision and not yet aligned.
1106
+
1107
+ ## Resources
1108
+
1109
+ - [Stripe V2 Accounts API](https://docs.stripe.com/connect/accounts-v2/api)
1110
+ - [Stripe Embedded Checkout](https://docs.stripe.com/payments/checkout/custom)
1111
+ - [Convex Component Authoring](https://docs.convex.dev/components/authoring)
1112
+ - [Stripe Webhook Event Reference](https://docs.stripe.com/api/events/types)
1113
+ - [Stripe Testing Guide](https://docs.stripe.com/testing)
1114
+
1115
+ ## License
1116
+
1117
+ MIT