@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.
- package/CHANGELOG.md +318 -0
- package/README.md +1117 -0
- package/dist/client/billing/checkout.d.ts +75 -0
- package/dist/client/billing/checkout.d.ts.map +1 -0
- package/dist/client/billing/checkout.js +260 -0
- package/dist/client/billing/checkout.js.map +1 -0
- package/dist/client/billing/invoices.d.ts +37 -0
- package/dist/client/billing/invoices.d.ts.map +1 -0
- package/dist/client/billing/invoices.js +29 -0
- package/dist/client/billing/invoices.js.map +1 -0
- package/dist/client/billing/subscriptions.d.ts +179 -0
- package/dist/client/billing/subscriptions.d.ts.map +1 -0
- package/dist/client/billing/subscriptions.js +346 -0
- package/dist/client/billing/subscriptions.js.map +1 -0
- package/dist/client/connect/disputes.d.ts +112 -0
- package/dist/client/connect/disputes.d.ts.map +1 -0
- package/dist/client/connect/disputes.js +186 -0
- package/dist/client/connect/disputes.js.map +1 -0
- package/dist/client/connect/paymentMethodUtils.d.ts +17 -0
- package/dist/client/connect/paymentMethodUtils.d.ts.map +1 -0
- package/dist/client/connect/paymentMethodUtils.js +24 -0
- package/dist/client/connect/paymentMethodUtils.js.map +1 -0
- package/dist/client/connect/paymentMethods.d.ts +23 -0
- package/dist/client/connect/paymentMethods.d.ts.map +1 -0
- package/dist/client/connect/paymentMethods.js +27 -0
- package/dist/client/connect/paymentMethods.js.map +1 -0
- package/dist/client/connect/payouts.d.ts +47 -0
- package/dist/client/connect/payouts.d.ts.map +1 -0
- package/dist/client/connect/payouts.js +52 -0
- package/dist/client/connect/payouts.js.map +1 -0
- package/dist/client/connect/refundActor.d.ts +50 -0
- package/dist/client/connect/refundActor.d.ts.map +1 -0
- package/dist/client/connect/refundActor.js +17 -0
- package/dist/client/connect/refundActor.js.map +1 -0
- package/dist/client/connect/refunds.d.ts +75 -0
- package/dist/client/connect/refunds.d.ts.map +1 -0
- package/dist/client/connect/refunds.js +141 -0
- package/dist/client/connect/refunds.js.map +1 -0
- package/dist/client/connect/transfers.d.ts +189 -0
- package/dist/client/connect/transfers.d.ts.map +1 -0
- package/dist/client/connect/transfers.js +347 -0
- package/dist/client/connect/transfers.js.map +1 -0
- package/dist/client/constants.d.ts +15 -0
- package/dist/client/constants.d.ts.map +1 -0
- package/dist/client/constants.js +14 -0
- package/dist/client/constants.js.map +1 -0
- package/dist/client/core/accountLinks.d.ts +68 -0
- package/dist/client/core/accountLinks.d.ts.map +1 -0
- package/dist/client/core/accountLinks.js +131 -0
- package/dist/client/core/accountLinks.js.map +1 -0
- package/dist/client/core/accountStatus.d.ts +12 -0
- package/dist/client/core/accountStatus.d.ts.map +1 -0
- package/dist/client/core/accountStatus.js +56 -0
- package/dist/client/core/accountStatus.js.map +1 -0
- package/dist/client/core/accounts.d.ts +181 -0
- package/dist/client/core/accounts.d.ts.map +1 -0
- package/dist/client/core/accounts.js +359 -0
- package/dist/client/core/accounts.js.map +1 -0
- package/dist/client/core/config.d.ts +5 -0
- package/dist/client/core/config.d.ts.map +1 -0
- package/dist/client/core/config.js +11 -0
- package/dist/client/core/config.js.map +1 -0
- package/dist/client/core/descriptors.d.ts +24 -0
- package/dist/client/core/descriptors.d.ts.map +1 -0
- package/dist/client/core/descriptors.js +43 -0
- package/dist/client/core/descriptors.js.map +1 -0
- package/dist/client/core/fees.d.ts +83 -0
- package/dist/client/core/fees.d.ts.map +1 -0
- package/dist/client/core/fees.js +178 -0
- package/dist/client/core/fees.js.map +1 -0
- package/dist/client/errors.d.ts +20 -0
- package/dist/client/errors.d.ts.map +1 -0
- package/dist/client/errors.js +31 -0
- package/dist/client/errors.js.map +1 -0
- package/dist/client/helpers.d.ts +20 -0
- package/dist/client/helpers.d.ts.map +1 -0
- package/dist/client/helpers.js +46 -0
- package/dist/client/helpers.js.map +1 -0
- package/dist/client/index.d.ts +880 -0
- package/dist/client/index.d.ts.map +1 -0
- package/dist/client/index.js +791 -0
- package/dist/client/index.js.map +1 -0
- package/dist/client/products/prices.d.ts +61 -0
- package/dist/client/products/prices.d.ts.map +1 -0
- package/dist/client/products/prices.js +92 -0
- package/dist/client/products/prices.js.map +1 -0
- package/dist/client/products/products.d.ts +65 -0
- package/dist/client/products/products.d.ts.map +1 -0
- package/dist/client/products/products.js +186 -0
- package/dist/client/products/products.js.map +1 -0
- package/dist/client/stripe-types.d.ts +44 -0
- package/dist/client/stripe-types.d.ts.map +1 -0
- package/dist/client/stripe-types.js +2 -0
- package/dist/client/stripe-types.js.map +1 -0
- package/dist/client/types/documents.d.ts +195 -0
- package/dist/client/types/documents.d.ts.map +1 -0
- package/dist/client/types/documents.js +2 -0
- package/dist/client/types/documents.js.map +1 -0
- package/dist/client/types/events.d.ts +43 -0
- package/dist/client/types/events.d.ts.map +1 -0
- package/dist/client/types/events.js +2 -0
- package/dist/client/types/events.js.map +1 -0
- package/dist/client/types/index.d.ts +5 -0
- package/dist/client/types/index.d.ts.map +1 -0
- package/dist/client/types/index.js +2 -0
- package/dist/client/types/index.js.map +1 -0
- package/dist/client/types/options.d.ts +79 -0
- package/dist/client/types/options.d.ts.map +1 -0
- package/dist/client/types/options.js +2 -0
- package/dist/client/types/options.js.map +1 -0
- package/dist/client/types/triggers.d.ts +101 -0
- package/dist/client/types/triggers.d.ts.map +1 -0
- package/dist/client/types/triggers.js +2 -0
- package/dist/client/types/triggers.js.map +1 -0
- package/dist/client/types.d.ts +2 -0
- package/dist/client/types.d.ts.map +1 -0
- package/dist/client/types.js +2 -0
- package/dist/client/types.js.map +1 -0
- package/dist/client/utils/data.d.ts +10 -0
- package/dist/client/utils/data.d.ts.map +1 -0
- package/dist/client/utils/data.js +13 -0
- package/dist/client/utils/data.js.map +1 -0
- package/dist/client/utils/owner.d.ts +22 -0
- package/dist/client/utils/owner.d.ts.map +1 -0
- package/dist/client/utils/owner.js +20 -0
- package/dist/client/utils/owner.js.map +1 -0
- package/dist/client/utils/stripeDashboardUrl.d.ts +12 -0
- package/dist/client/utils/stripeDashboardUrl.d.ts.map +1 -0
- package/dist/client/utils/stripeDashboardUrl.js +39 -0
- package/dist/client/utils/stripeDashboardUrl.js.map +1 -0
- package/dist/client/utils/webhookEndpoints.d.ts +83 -0
- package/dist/client/utils/webhookEndpoints.d.ts.map +1 -0
- package/dist/client/utils/webhookEndpoints.js +185 -0
- package/dist/client/utils/webhookEndpoints.js.map +1 -0
- package/dist/client/webhooks/handler.d.ts +4 -0
- package/dist/client/webhooks/handler.d.ts.map +1 -0
- package/dist/client/webhooks/handler.js +170 -0
- package/dist/client/webhooks/handler.js.map +1 -0
- package/dist/client/webhooks/helpers.d.ts +56 -0
- package/dist/client/webhooks/helpers.d.ts.map +1 -0
- package/dist/client/webhooks/helpers.js +229 -0
- package/dist/client/webhooks/helpers.js.map +1 -0
- package/dist/client/webhooks/hooks.d.ts +11 -0
- package/dist/client/webhooks/hooks.d.ts.map +1 -0
- package/dist/client/webhooks/hooks.js +134 -0
- package/dist/client/webhooks/hooks.js.map +1 -0
- package/dist/client/webhooks/index.d.ts +23 -0
- package/dist/client/webhooks/index.d.ts.map +1 -0
- package/dist/client/webhooks/index.js +35 -0
- package/dist/client/webhooks/index.js.map +1 -0
- package/dist/client/webhooks/processors.d.ts +4 -0
- package/dist/client/webhooks/processors.d.ts.map +1 -0
- package/dist/client/webhooks/processors.js +932 -0
- package/dist/client/webhooks/processors.js.map +1 -0
- package/dist/client/webhooks/v2.d.ts +11 -0
- package/dist/client/webhooks/v2.d.ts.map +1 -0
- package/dist/client/webhooks/v2.js +94 -0
- package/dist/client/webhooks/v2.js.map +1 -0
- package/dist/client/webhooks.d.ts +2 -0
- package/dist/client/webhooks.d.ts.map +1 -0
- package/dist/client/webhooks.js +4 -0
- package/dist/client/webhooks.js.map +1 -0
- package/dist/component/_generated/component.d.ts +1262 -0
- package/dist/component/_generated/component.d.ts.map +1 -0
- package/dist/component/_generated/component.js +11 -0
- package/dist/component/_generated/component.js.map +1 -0
- package/dist/component/_generated/dataModel.d.ts +46 -0
- package/dist/component/_generated/dataModel.d.ts.map +1 -0
- package/dist/component/_generated/dataModel.js +11 -0
- package/dist/component/_generated/dataModel.js.map +1 -0
- package/dist/component/_generated/server.d.ts +129 -0
- package/dist/component/_generated/server.d.ts.map +1 -0
- package/dist/component/_generated/server.js +79 -0
- package/dist/component/_generated/server.js.map +1 -0
- package/dist/component/billing/mutations.d.ts +86 -0
- package/dist/component/billing/mutations.d.ts.map +1 -0
- package/dist/component/billing/mutations.js +131 -0
- package/dist/component/billing/mutations.js.map +1 -0
- package/dist/component/billing/queries.d.ts +425 -0
- package/dist/component/billing/queries.d.ts.map +1 -0
- package/dist/component/billing/queries.js +304 -0
- package/dist/component/billing/queries.js.map +1 -0
- package/dist/component/billing/schema.d.ts +228 -0
- package/dist/component/billing/schema.d.ts.map +1 -0
- package/dist/component/billing/schema.js +33 -0
- package/dist/component/billing/schema.js.map +1 -0
- package/dist/component/billing/validators.d.ts +364 -0
- package/dist/component/billing/validators.d.ts.map +1 -0
- package/dist/component/billing/validators.js +98 -0
- package/dist/component/billing/validators.js.map +1 -0
- package/dist/component/connect/mutations.d.ts +182 -0
- package/dist/component/connect/mutations.d.ts.map +1 -0
- package/dist/component/connect/mutations.js +480 -0
- package/dist/component/connect/mutations.js.map +1 -0
- package/dist/component/connect/queries.d.ts +347 -0
- package/dist/component/connect/queries.d.ts.map +1 -0
- package/dist/component/connect/queries.js +449 -0
- package/dist/component/connect/queries.js.map +1 -0
- package/dist/component/connect/schema.d.ts +258 -0
- package/dist/component/connect/schema.d.ts.map +1 -0
- package/dist/component/connect/schema.js +70 -0
- package/dist/component/connect/schema.js.map +1 -0
- package/dist/component/connect/validators.d.ts +468 -0
- package/dist/component/connect/validators.d.ts.map +1 -0
- package/dist/component/connect/validators.js +250 -0
- package/dist/component/connect/validators.js.map +1 -0
- package/dist/component/convex.config.d.ts +5 -0
- package/dist/component/convex.config.d.ts.map +1 -0
- package/dist/component/convex.config.js +17 -0
- package/dist/component/convex.config.js.map +1 -0
- package/dist/component/core/mutations.d.ts +52 -0
- package/dist/component/core/mutations.d.ts.map +1 -0
- package/dist/component/core/mutations.js +153 -0
- package/dist/component/core/mutations.js.map +1 -0
- package/dist/component/core/queries.d.ts +95 -0
- package/dist/component/core/queries.d.ts.map +1 -0
- package/dist/component/core/queries.js +86 -0
- package/dist/component/core/queries.js.map +1 -0
- package/dist/component/core/schema.d.ts +41 -0
- package/dist/component/core/schema.d.ts.map +1 -0
- package/dist/component/core/schema.js +12 -0
- package/dist/component/core/schema.js.map +1 -0
- package/dist/component/core/validators.d.ts +65 -0
- package/dist/component/core/validators.d.ts.map +1 -0
- package/dist/component/core/validators.js +35 -0
- package/dist/component/core/validators.js.map +1 -0
- package/dist/component/lib/fees.d.ts +74 -0
- package/dist/component/lib/fees.d.ts.map +1 -0
- package/dist/component/lib/fees.js +51 -0
- package/dist/component/lib/fees.js.map +1 -0
- package/dist/component/lib/idempotency.d.ts +9 -0
- package/dist/component/lib/idempotency.d.ts.map +1 -0
- package/dist/component/lib/idempotency.js +18 -0
- package/dist/component/lib/idempotency.js.map +1 -0
- package/dist/component/lib/reversals.d.ts +48 -0
- package/dist/component/lib/reversals.d.ts.map +1 -0
- package/dist/component/lib/reversals.js +79 -0
- package/dist/component/lib/reversals.js.map +1 -0
- package/dist/component/lib/stripeFactory.d.ts +7 -0
- package/dist/component/lib/stripeFactory.d.ts.map +1 -0
- package/dist/component/lib/stripeFactory.js +28 -0
- package/dist/component/lib/stripeFactory.js.map +1 -0
- package/dist/component/products/mutations.d.ts +22 -0
- package/dist/component/products/mutations.d.ts.map +1 -0
- package/dist/component/products/mutations.js +63 -0
- package/dist/component/products/mutations.js.map +1 -0
- package/dist/component/products/queries.d.ts +109 -0
- package/dist/component/products/queries.d.ts.map +1 -0
- package/dist/component/products/queries.js +122 -0
- package/dist/component/products/queries.js.map +1 -0
- package/dist/component/products/schema.d.ts +58 -0
- package/dist/component/products/schema.d.ts.map +1 -0
- package/dist/component/products/schema.js +20 -0
- package/dist/component/products/schema.js.map +1 -0
- package/dist/component/products/validators.d.ts +86 -0
- package/dist/component/products/validators.d.ts.map +1 -0
- package/dist/component/products/validators.js +47 -0
- package/dist/component/products/validators.js.map +1 -0
- package/dist/component/schema.d.ts +555 -0
- package/dist/component/schema.d.ts.map +1 -0
- package/dist/component/schema.js +28 -0
- package/dist/component/schema.js.map +1 -0
- package/dist/component/webhooks/mutations.d.ts +30 -0
- package/dist/component/webhooks/mutations.d.ts.map +1 -0
- package/dist/component/webhooks/mutations.js +124 -0
- package/dist/component/webhooks/mutations.js.map +1 -0
- package/dist/component/webhooks/queries.d.ts +35 -0
- package/dist/component/webhooks/queries.d.ts.map +1 -0
- package/dist/component/webhooks/queries.js +41 -0
- package/dist/component/webhooks/queries.js.map +1 -0
- package/dist/component/webhooks/schema.d.ts +22 -0
- package/dist/component/webhooks/schema.d.ts.map +1 -0
- package/dist/component/webhooks/schema.js +9 -0
- package/dist/component/webhooks/schema.js.map +1 -0
- package/dist/component/webhooks/validators.d.ts +37 -0
- package/dist/component/webhooks/validators.d.ts.map +1 -0
- package/dist/component/webhooks/validators.js +22 -0
- package/dist/component/webhooks/validators.js.map +1 -0
- package/dist/react/components/AccountCloseButton.d.ts +42 -0
- package/dist/react/components/AccountCloseButton.d.ts.map +1 -0
- package/dist/react/components/AccountCloseButton.js +33 -0
- package/dist/react/components/AccountCloseButton.js.map +1 -0
- package/dist/react/components/AccountCloseCard.d.ts +31 -0
- package/dist/react/components/AccountCloseCard.d.ts.map +1 -0
- package/dist/react/components/AccountCloseCard.js +22 -0
- package/dist/react/components/AccountCloseCard.js.map +1 -0
- package/dist/react/components/AccountCreateButton.d.ts +37 -0
- package/dist/react/components/AccountCreateButton.d.ts.map +1 -0
- package/dist/react/components/AccountCreateButton.js +30 -0
- package/dist/react/components/AccountCreateButton.js.map +1 -0
- package/dist/react/components/AccountCreateCard.d.ts +48 -0
- package/dist/react/components/AccountCreateCard.d.ts.map +1 -0
- package/dist/react/components/AccountCreateCard.js +29 -0
- package/dist/react/components/AccountCreateCard.js.map +1 -0
- package/dist/react/components/AccountLoginButton.d.ts +31 -0
- package/dist/react/components/AccountLoginButton.d.ts.map +1 -0
- package/dist/react/components/AccountLoginButton.js +31 -0
- package/dist/react/components/AccountLoginButton.js.map +1 -0
- package/dist/react/components/AccountLoginCard.d.ts +33 -0
- package/dist/react/components/AccountLoginCard.d.ts.map +1 -0
- package/dist/react/components/AccountLoginCard.js +19 -0
- package/dist/react/components/AccountLoginCard.js.map +1 -0
- package/dist/react/components/AccountOnboardingButton.d.ts +37 -0
- package/dist/react/components/AccountOnboardingButton.d.ts.map +1 -0
- package/dist/react/components/AccountOnboardingButton.js +30 -0
- package/dist/react/components/AccountOnboardingButton.js.map +1 -0
- package/dist/react/components/AccountOnboardingCard.d.ts +56 -0
- package/dist/react/components/AccountOnboardingCard.d.ts.map +1 -0
- package/dist/react/components/AccountOnboardingCard.js +36 -0
- package/dist/react/components/AccountOnboardingCard.js.map +1 -0
- package/dist/react/components/AddCardForm.d.ts +18 -0
- package/dist/react/components/AddCardForm.d.ts.map +1 -0
- package/dist/react/components/AddCardForm.js +49 -0
- package/dist/react/components/AddCardForm.js.map +1 -0
- package/dist/react/components/BillingPortalLink.d.ts +23 -0
- package/dist/react/components/BillingPortalLink.d.ts.map +1 -0
- package/dist/react/components/BillingPortalLink.js +55 -0
- package/dist/react/components/BillingPortalLink.js.map +1 -0
- package/dist/react/components/BuyerBillingView.d.ts +80 -0
- package/dist/react/components/BuyerBillingView.d.ts.map +1 -0
- package/dist/react/components/BuyerBillingView.js +44 -0
- package/dist/react/components/BuyerBillingView.js.map +1 -0
- package/dist/react/components/CheckoutSessionProvider.d.ts +34 -0
- package/dist/react/components/CheckoutSessionProvider.d.ts.map +1 -0
- package/dist/react/components/CheckoutSessionProvider.js +38 -0
- package/dist/react/components/CheckoutSessionProvider.js.map +1 -0
- package/dist/react/components/CheckoutSessionProviderWithKey.d.ts +36 -0
- package/dist/react/components/CheckoutSessionProviderWithKey.d.ts.map +1 -0
- package/dist/react/components/CheckoutSessionProviderWithKey.js +36 -0
- package/dist/react/components/CheckoutSessionProviderWithKey.js.map +1 -0
- package/dist/react/components/CheckoutStatus.d.ts +25 -0
- package/dist/react/components/CheckoutStatus.d.ts.map +1 -0
- package/dist/react/components/CheckoutStatus.js +22 -0
- package/dist/react/components/CheckoutStatus.js.map +1 -0
- package/dist/react/components/ConnectProvider.d.ts +29 -0
- package/dist/react/components/ConnectProvider.d.ts.map +1 -0
- package/dist/react/components/ConnectProvider.js +25 -0
- package/dist/react/components/ConnectProvider.js.map +1 -0
- package/dist/react/components/ConnectRequirements.d.ts +55 -0
- package/dist/react/components/ConnectRequirements.d.ts.map +1 -0
- package/dist/react/components/ConnectRequirements.js +58 -0
- package/dist/react/components/ConnectRequirements.js.map +1 -0
- package/dist/react/components/ConnectStatusBadge.d.ts +26 -0
- package/dist/react/components/ConnectStatusBadge.d.ts.map +1 -0
- package/dist/react/components/ConnectStatusBadge.js +20 -0
- package/dist/react/components/ConnectStatusBadge.js.map +1 -0
- package/dist/react/components/DeletePaymentMethodDialog.d.ts +25 -0
- package/dist/react/components/DeletePaymentMethodDialog.d.ts.map +1 -0
- package/dist/react/components/DeletePaymentMethodDialog.js +16 -0
- package/dist/react/components/DeletePaymentMethodDialog.js.map +1 -0
- package/dist/react/components/DisputeDetail.d.ts +42 -0
- package/dist/react/components/DisputeDetail.d.ts.map +1 -0
- package/dist/react/components/DisputeDetail.js +34 -0
- package/dist/react/components/DisputeDetail.js.map +1 -0
- package/dist/react/components/DisputesList.d.ts +42 -0
- package/dist/react/components/DisputesList.d.ts.map +1 -0
- package/dist/react/components/DisputesList.js +47 -0
- package/dist/react/components/DisputesList.js.map +1 -0
- package/dist/react/components/EarningsSummary.d.ts +53 -0
- package/dist/react/components/EarningsSummary.d.ts.map +1 -0
- package/dist/react/components/EarningsSummary.js +37 -0
- package/dist/react/components/EarningsSummary.js.map +1 -0
- package/dist/react/components/EmbeddedCheckout.d.ts +18 -0
- package/dist/react/components/EmbeddedCheckout.d.ts.map +1 -0
- package/dist/react/components/EmbeddedCheckout.js +17 -0
- package/dist/react/components/EmbeddedCheckout.js.map +1 -0
- package/dist/react/components/EmbeddedDisputes.d.ts +21 -0
- package/dist/react/components/EmbeddedDisputes.d.ts.map +1 -0
- package/dist/react/components/EmbeddedDisputes.js +17 -0
- package/dist/react/components/EmbeddedDisputes.js.map +1 -0
- package/dist/react/components/EvidenceForm.d.ts +63 -0
- package/dist/react/components/EvidenceForm.d.ts.map +1 -0
- package/dist/react/components/EvidenceForm.js +79 -0
- package/dist/react/components/EvidenceForm.js.map +1 -0
- package/dist/react/components/IntervalSelector.d.ts +20 -0
- package/dist/react/components/IntervalSelector.d.ts.map +1 -0
- package/dist/react/components/IntervalSelector.js +15 -0
- package/dist/react/components/IntervalSelector.js.map +1 -0
- package/dist/react/components/PaymentMethodActions.d.ts +27 -0
- package/dist/react/components/PaymentMethodActions.d.ts.map +1 -0
- package/dist/react/components/PaymentMethodActions.js +23 -0
- package/dist/react/components/PaymentMethodActions.js.map +1 -0
- package/dist/react/components/PaymentMethodsList.d.ts +32 -0
- package/dist/react/components/PaymentMethodsList.d.ts.map +1 -0
- package/dist/react/components/PaymentMethodsList.js +18 -0
- package/dist/react/components/PaymentMethodsList.js.map +1 -0
- package/dist/react/components/PayoutSchedule.d.ts +55 -0
- package/dist/react/components/PayoutSchedule.d.ts.map +1 -0
- package/dist/react/components/PayoutSchedule.js +51 -0
- package/dist/react/components/PayoutSchedule.js.map +1 -0
- package/dist/react/components/PriceBadge.d.ts +19 -0
- package/dist/react/components/PriceBadge.d.ts.map +1 -0
- package/dist/react/components/PriceBadge.js +25 -0
- package/dist/react/components/PriceBadge.js.map +1 -0
- package/dist/react/components/PriceCard.d.ts +34 -0
- package/dist/react/components/PriceCard.d.ts.map +1 -0
- package/dist/react/components/PriceCard.js +20 -0
- package/dist/react/components/PriceCard.js.map +1 -0
- package/dist/react/components/PricePicker.d.ts +28 -0
- package/dist/react/components/PricePicker.d.ts.map +1 -0
- package/dist/react/components/PricePicker.js +32 -0
- package/dist/react/components/PricePicker.js.map +1 -0
- package/dist/react/components/SplitBreakdown.d.ts +45 -0
- package/dist/react/components/SplitBreakdown.d.ts.map +1 -0
- package/dist/react/components/SplitBreakdown.js +48 -0
- package/dist/react/components/SplitBreakdown.js.map +1 -0
- package/dist/react/components/StripeProvider.d.ts +30 -0
- package/dist/react/components/StripeProvider.d.ts.map +1 -0
- package/dist/react/components/StripeProvider.js +38 -0
- package/dist/react/components/StripeProvider.js.map +1 -0
- package/dist/react/components/StripeProviderWithKey.d.ts +33 -0
- package/dist/react/components/StripeProviderWithKey.d.ts.map +1 -0
- package/dist/react/components/StripeProviderWithKey.js +44 -0
- package/dist/react/components/StripeProviderWithKey.js.map +1 -0
- package/dist/react/components/SubscriptionActions.d.ts +31 -0
- package/dist/react/components/SubscriptionActions.d.ts.map +1 -0
- package/dist/react/components/SubscriptionActions.js +30 -0
- package/dist/react/components/SubscriptionActions.js.map +1 -0
- package/dist/react/components/SubscriptionCard.d.ts +41 -0
- package/dist/react/components/SubscriptionCard.d.ts.map +1 -0
- package/dist/react/components/SubscriptionCard.js +18 -0
- package/dist/react/components/SubscriptionCard.js.map +1 -0
- package/dist/react/components/SubscriptionLineItems.d.ts +23 -0
- package/dist/react/components/SubscriptionLineItems.d.ts.map +1 -0
- package/dist/react/components/SubscriptionLineItems.js +20 -0
- package/dist/react/components/SubscriptionLineItems.js.map +1 -0
- package/dist/react/components/TrialAlert.d.ts +19 -0
- package/dist/react/components/TrialAlert.d.ts.map +1 -0
- package/dist/react/components/TrialAlert.js +16 -0
- package/dist/react/components/TrialAlert.js.map +1 -0
- package/dist/react/hooks/useAccount.d.ts +14 -0
- package/dist/react/hooks/useAccount.d.ts.map +1 -0
- package/dist/react/hooks/useAccount.js +18 -0
- package/dist/react/hooks/useAccount.js.map +1 -0
- package/dist/react/hooks/useAccountOnboarding.d.ts +15 -0
- package/dist/react/hooks/useAccountOnboarding.d.ts.map +1 -0
- package/dist/react/hooks/useAccountOnboarding.js +19 -0
- package/dist/react/hooks/useAccountOnboarding.js.map +1 -0
- package/dist/react/hooks/useCheckout.d.ts +14 -0
- package/dist/react/hooks/useCheckout.d.ts.map +1 -0
- package/dist/react/hooks/useCheckout.js +18 -0
- package/dist/react/hooks/useCheckout.js.map +1 -0
- package/dist/react/hooks/useCheckoutSession.d.ts +62 -0
- package/dist/react/hooks/useCheckoutSession.d.ts.map +1 -0
- package/dist/react/hooks/useCheckoutSession.js +68 -0
- package/dist/react/hooks/useCheckoutSession.js.map +1 -0
- package/dist/react/hooks/useConfirmPayment.d.ts +38 -0
- package/dist/react/hooks/useConfirmPayment.d.ts.map +1 -0
- package/dist/react/hooks/useConfirmPayment.js +91 -0
- package/dist/react/hooks/useConfirmPayment.js.map +1 -0
- package/dist/react/hooks/useDisputeWithCountdown.d.ts +25 -0
- package/dist/react/hooks/useDisputeWithCountdown.d.ts.map +1 -0
- package/dist/react/hooks/useDisputeWithCountdown.js +19 -0
- package/dist/react/hooks/useDisputeWithCountdown.js.map +1 -0
- package/dist/react/hooks/useDisputes.d.ts +14 -0
- package/dist/react/hooks/useDisputes.d.ts.map +1 -0
- package/dist/react/hooks/useDisputes.js +15 -0
- package/dist/react/hooks/useDisputes.js.map +1 -0
- package/dist/react/hooks/useEarnings.d.ts +92 -0
- package/dist/react/hooks/useEarnings.d.ts.map +1 -0
- package/dist/react/hooks/useEarnings.js +35 -0
- package/dist/react/hooks/useEarnings.js.map +1 -0
- package/dist/react/hooks/useInvoices.d.ts +11 -0
- package/dist/react/hooks/useInvoices.d.ts.map +1 -0
- package/dist/react/hooks/useInvoices.js +11 -0
- package/dist/react/hooks/useInvoices.js.map +1 -0
- package/dist/react/hooks/usePaymentMethodActions.d.ts +74 -0
- package/dist/react/hooks/usePaymentMethodActions.d.ts.map +1 -0
- package/dist/react/hooks/usePaymentMethodActions.js +156 -0
- package/dist/react/hooks/usePaymentMethodActions.js.map +1 -0
- package/dist/react/hooks/usePaymentMethods.d.ts +23 -0
- package/dist/react/hooks/usePaymentMethods.d.ts.map +1 -0
- package/dist/react/hooks/usePaymentMethods.js +18 -0
- package/dist/react/hooks/usePaymentMethods.js.map +1 -0
- package/dist/react/hooks/usePrices.d.ts +12 -0
- package/dist/react/hooks/usePrices.d.ts.map +1 -0
- package/dist/react/hooks/usePrices.js +16 -0
- package/dist/react/hooks/usePrices.js.map +1 -0
- package/dist/react/hooks/useProducts.d.ts +10 -0
- package/dist/react/hooks/useProducts.d.ts.map +1 -0
- package/dist/react/hooks/useProducts.js +11 -0
- package/dist/react/hooks/useProducts.js.map +1 -0
- package/dist/react/hooks/useSplitBreakdown.d.ts +58 -0
- package/dist/react/hooks/useSplitBreakdown.d.ts.map +1 -0
- package/dist/react/hooks/useSplitBreakdown.js +59 -0
- package/dist/react/hooks/useSplitBreakdown.js.map +1 -0
- package/dist/react/hooks/useStripeConfig.d.ts +14 -0
- package/dist/react/hooks/useStripeConfig.d.ts.map +1 -0
- package/dist/react/hooks/useStripeConfig.js +21 -0
- package/dist/react/hooks/useStripeConfig.js.map +1 -0
- package/dist/react/hooks/useStripeMode.d.ts +3 -0
- package/dist/react/hooks/useStripeMode.d.ts.map +1 -0
- package/dist/react/hooks/useStripeMode.js +6 -0
- package/dist/react/hooks/useStripeMode.js.map +1 -0
- package/dist/react/hooks/useStripePublishableKey.d.ts +2 -0
- package/dist/react/hooks/useStripePublishableKey.d.ts.map +1 -0
- package/dist/react/hooks/useStripePublishableKey.js +6 -0
- package/dist/react/hooks/useStripePublishableKey.js.map +1 -0
- package/dist/react/hooks/useSubscription.d.ts +17 -0
- package/dist/react/hooks/useSubscription.d.ts.map +1 -0
- package/dist/react/hooks/useSubscription.js +30 -0
- package/dist/react/hooks/useSubscription.js.map +1 -0
- package/dist/react/hooks/useSubscriptions.d.ts +11 -0
- package/dist/react/hooks/useSubscriptions.d.ts.map +1 -0
- package/dist/react/hooks/useSubscriptions.js +13 -0
- package/dist/react/hooks/useSubscriptions.js.map +1 -0
- package/dist/react/index.d.ts +108 -0
- package/dist/react/index.d.ts.map +1 -0
- package/dist/react/index.js +87 -0
- package/dist/react/index.js.map +1 -0
- package/dist/react/lib/connect-requirement-keys.d.ts +14 -0
- package/dist/react/lib/connect-requirement-keys.d.ts.map +1 -0
- package/dist/react/lib/connect-requirement-keys.js +57 -0
- package/dist/react/lib/connect-requirement-keys.js.map +1 -0
- package/dist/react/lib/price-helpers.d.ts +31 -0
- package/dist/react/lib/price-helpers.d.ts.map +1 -0
- package/dist/react/lib/price-helpers.js +46 -0
- package/dist/react/lib/price-helpers.js.map +1 -0
- package/dist/react/lib/stripe-element-styles.d.ts +91 -0
- package/dist/react/lib/stripe-element-styles.d.ts.map +1 -0
- package/dist/react/lib/stripe-element-styles.js +131 -0
- package/dist/react/lib/stripe-element-styles.js.map +1 -0
- package/dist/react/lib/subscription-helpers.d.ts +33 -0
- package/dist/react/lib/subscription-helpers.d.ts.map +1 -0
- package/dist/react/lib/subscription-helpers.js +47 -0
- package/dist/react/lib/subscription-helpers.js.map +1 -0
- package/dist/react/types.d.ts +20 -0
- package/dist/react/types.d.ts.map +1 -0
- package/dist/react/types.js +2 -0
- package/dist/react/types.js.map +1 -0
- package/dist/testing/assert-test-env.d.ts +6 -0
- package/dist/testing/assert-test-env.d.ts.map +1 -0
- package/dist/testing/assert-test-env.js +15 -0
- package/dist/testing/assert-test-env.js.map +1 -0
- package/dist/testing/fixtures.d.ts +38 -0
- package/dist/testing/fixtures.d.ts.map +1 -0
- package/dist/testing/fixtures.js +54 -0
- package/dist/testing/fixtures.js.map +1 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +4 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/mock-webhooks.d.ts +19 -0
- package/dist/testing/mock-webhooks.d.ts.map +1 -0
- package/dist/testing/mock-webhooks.js +81 -0
- package/dist/testing/mock-webhooks.js.map +1 -0
- package/package.json +131 -0
- package/src/client/billing/checkout.test.ts +1234 -0
- package/src/client/billing/checkout.ts +416 -0
- package/src/client/billing/invoices.test.ts +237 -0
- package/src/client/billing/invoices.ts +93 -0
- package/src/client/billing/subscriptions.test.ts +987 -0
- package/src/client/billing/subscriptions.ts +604 -0
- package/src/client/component-api-types.test.ts +137 -0
- package/src/client/connect/disputes.test.ts +487 -0
- package/src/client/connect/disputes.ts +302 -0
- package/src/client/connect/paymentMethodUtils.test.ts +83 -0
- package/src/client/connect/paymentMethodUtils.ts +28 -0
- package/src/client/connect/paymentMethods.test.ts +66 -0
- package/src/client/connect/paymentMethods.ts +55 -0
- package/src/client/connect/payouts.test.ts +132 -0
- package/src/client/connect/payouts.ts +105 -0
- package/src/client/connect/refundActor.test.ts +121 -0
- package/src/client/connect/refundActor.ts +60 -0
- package/src/client/connect/refunds.test.ts +341 -0
- package/src/client/connect/refunds.ts +256 -0
- package/src/client/connect/transfers.test.ts +492 -0
- package/src/client/connect/transfers.ts +572 -0
- package/src/client/constants.ts +15 -0
- package/src/client/core/accountLinks.test.ts +378 -0
- package/src/client/core/accountLinks.ts +211 -0
- package/src/client/core/accountStatus.test.ts +102 -0
- package/src/client/core/accountStatus.ts +91 -0
- package/src/client/core/accounts.test.ts +1496 -0
- package/src/client/core/accounts.ts +667 -0
- package/src/client/core/config.test.ts +68 -0
- package/src/client/core/config.ts +27 -0
- package/src/client/core/descriptors.test.ts +68 -0
- package/src/client/core/descriptors.ts +46 -0
- package/src/client/core/fees.test.ts +377 -0
- package/src/client/core/fees.ts +268 -0
- package/src/client/errors.test.ts +66 -0
- package/src/client/errors.ts +70 -0
- package/src/client/helpers.test.ts +74 -0
- package/src/client/helpers.ts +94 -0
- package/src/client/index.test.ts +1848 -0
- package/src/client/index.ts +1872 -0
- package/src/client/products/prices.test.ts +345 -0
- package/src/client/products/prices.ts +194 -0
- package/src/client/products/products.test.ts +476 -0
- package/src/client/products/products.ts +335 -0
- package/src/client/setup.test.ts +47 -0
- package/src/client/stripe-types.ts +108 -0
- package/src/client/types/documents.ts +245 -0
- package/src/client/types/events.ts +72 -0
- package/src/client/types/index.ts +43 -0
- package/src/client/types/options.ts +103 -0
- package/src/client/types/triggers.ts +293 -0
- package/src/client/types.ts +35 -0
- package/src/client/utils/data.test.ts +59 -0
- package/src/client/utils/data.ts +22 -0
- package/src/client/utils/owner.test.ts +35 -0
- package/src/client/utils/owner.ts +27 -0
- package/src/client/utils/stripeDashboardUrl.test.ts +71 -0
- package/src/client/utils/stripeDashboardUrl.ts +71 -0
- package/src/client/utils/webhookEndpoints.test.ts +454 -0
- package/src/client/utils/webhookEndpoints.ts +271 -0
- package/src/client/webhook-handlers.test.ts +603 -0
- package/src/client/webhooks/handler.test.ts +604 -0
- package/src/client/webhooks/handler.ts +256 -0
- package/src/client/webhooks/helpers.test.ts +330 -0
- package/src/client/webhooks/helpers.ts +277 -0
- package/src/client/webhooks/hooks.test.ts +111 -0
- package/src/client/webhooks/hooks.ts +177 -0
- package/src/client/webhooks/index.ts +51 -0
- package/src/client/webhooks/processors.test.ts +2392 -0
- package/src/client/webhooks/processors.ts +1166 -0
- package/src/client/webhooks/v2.test.ts +396 -0
- package/src/client/webhooks/v2.ts +124 -0
- package/src/client/webhooks.test.ts +1689 -0
- package/src/client/webhooks.ts +3 -0
- package/src/component/_generated/api.ts +86 -0
- package/src/component/_generated/component.ts +1758 -0
- package/src/component/_generated/dataModel.ts +60 -0
- package/src/component/_generated/server.ts +164 -0
- package/src/component/billing/mutations.ts +155 -0
- package/src/component/billing/queries.ts +378 -0
- package/src/component/billing/schema.ts +40 -0
- package/src/component/billing/validators.ts +137 -0
- package/src/component/config-queries.test.ts +47 -0
- package/src/component/connect/mutations.ts +624 -0
- package/src/component/connect/queries.ts +537 -0
- package/src/component/connect/schema.ts +90 -0
- package/src/component/connect/validators.ts +333 -0
- package/src/component/connect.test.ts +721 -0
- package/src/component/convex.config.ts +17 -0
- package/src/component/core/mutations.ts +182 -0
- package/src/component/core/queries.ts +100 -0
- package/src/component/core/schema.ts +13 -0
- package/src/component/core/validators.ts +55 -0
- package/src/component/earnings-totals.test.ts +196 -0
- package/src/component/fee-routing.test.ts +124 -0
- package/src/component/lib/fees.ts +64 -0
- package/src/component/lib/idempotency.test.ts +37 -0
- package/src/component/lib/idempotency.ts +20 -0
- package/src/component/lib/reversals.ts +113 -0
- package/src/component/lib/stripeFactory.ts +30 -0
- package/src/component/products/mutations.ts +73 -0
- package/src/component/products/queries.ts +149 -0
- package/src/component/products/schema.ts +22 -0
- package/src/component/products/validators.ts +63 -0
- package/src/component/public.test.ts +1858 -0
- package/src/component/reversal-races.test.ts +920 -0
- package/src/component/schema.ts +45 -0
- package/src/component/subscription-scoping.test.ts +118 -0
- package/src/component/transfers.test.ts +402 -0
- package/src/component/triggers.test.ts +359 -0
- package/src/component/webhooks/mutations.ts +151 -0
- package/src/component/webhooks/queries.ts +44 -0
- package/src/component/webhooks/schema.ts +10 -0
- package/src/component/webhooks/validators.ts +30 -0
- package/src/react/components/AccountCloseButton.tsx +91 -0
- package/src/react/components/AccountCloseCard.tsx +84 -0
- package/src/react/components/AccountCreateButton.tsx +83 -0
- package/src/react/components/AccountCreateCard.tsx +123 -0
- package/src/react/components/AccountLoginButton.tsx +69 -0
- package/src/react/components/AccountLoginCard.tsx +99 -0
- package/src/react/components/AccountOnboardingButton.tsx +83 -0
- package/src/react/components/AccountOnboardingCard.test.ts +27 -0
- package/src/react/components/AccountOnboardingCard.tsx +152 -0
- package/src/react/components/AddCardForm.tsx +80 -0
- package/src/react/components/BillingPortalLink.tsx +93 -0
- package/src/react/components/BuyerBillingView.render.test.tsx +207 -0
- package/src/react/components/BuyerBillingView.tsx +193 -0
- package/src/react/components/CheckoutSessionProvider.tsx +70 -0
- package/src/react/components/CheckoutSessionProviderWithKey.tsx +99 -0
- package/src/react/components/CheckoutStatus.tsx +71 -0
- package/src/react/components/ConnectProvider.tsx +58 -0
- package/src/react/components/ConnectRequirements.tsx +159 -0
- package/src/react/components/ConnectStatusBadge.tsx +60 -0
- package/src/react/components/DeletePaymentMethodDialog.tsx +61 -0
- package/src/react/components/DisputeDetail.render.test.tsx +143 -0
- package/src/react/components/DisputeDetail.tsx +111 -0
- package/src/react/components/DisputesList.render.test.tsx +244 -0
- package/src/react/components/DisputesList.tsx +120 -0
- package/src/react/components/EarningsSummary.render.test.tsx +153 -0
- package/src/react/components/EarningsSummary.tsx +131 -0
- package/src/react/components/EmbeddedCheckout.test.ts +25 -0
- package/src/react/components/EmbeddedCheckout.tsx +54 -0
- package/src/react/components/EmbeddedDisputes.render.test.tsx +142 -0
- package/src/react/components/EmbeddedDisputes.tsx +38 -0
- package/src/react/components/EvidenceForm.render.test.tsx +215 -0
- package/src/react/components/EvidenceForm.tsx +176 -0
- package/src/react/components/IntervalSelector.tsx +58 -0
- package/src/react/components/PaymentMethodActions.tsx +68 -0
- package/src/react/components/PaymentMethodsList.tsx +81 -0
- package/src/react/components/PayoutSchedule.render.test.tsx +178 -0
- package/src/react/components/PayoutSchedule.tsx +148 -0
- package/src/react/components/PriceBadge.render.test.tsx +134 -0
- package/src/react/components/PriceBadge.tsx +49 -0
- package/src/react/components/PriceCard.render.test.tsx +135 -0
- package/src/react/components/PriceCard.tsx +83 -0
- package/src/react/components/PricePicker.tsx +95 -0
- package/src/react/components/SplitBreakdown.render.test.tsx +168 -0
- package/src/react/components/SplitBreakdown.tsx +121 -0
- package/src/react/components/StripeProvider.test.ts +45 -0
- package/src/react/components/StripeProvider.tsx +80 -0
- package/src/react/components/StripeProviderWithKey.tsx +95 -0
- package/src/react/components/SubscriptionActions.tsx +79 -0
- package/src/react/components/SubscriptionCard.tsx +92 -0
- package/src/react/components/SubscriptionLineItems.tsx +62 -0
- package/src/react/components/TrialAlert.render.test.tsx +132 -0
- package/src/react/components/TrialAlert.tsx +44 -0
- package/src/react/hooks/skipSentinel.test.ts +85 -0
- package/src/react/hooks/useAccount.ts +28 -0
- package/src/react/hooks/useAccountOnboarding.test.ts +75 -0
- package/src/react/hooks/useAccountOnboarding.ts +35 -0
- package/src/react/hooks/useCheckout.ts +33 -0
- package/src/react/hooks/useCheckoutSession.ts +110 -0
- package/src/react/hooks/useConfirmPayment.ts +117 -0
- package/src/react/hooks/useDisputeWithCountdown.test.ts +90 -0
- package/src/react/hooks/useDisputeWithCountdown.ts +48 -0
- package/src/react/hooks/useDisputes.test.ts +75 -0
- package/src/react/hooks/useDisputes.ts +28 -0
- package/src/react/hooks/useEarnings.test.ts +159 -0
- package/src/react/hooks/useEarnings.ts +132 -0
- package/src/react/hooks/useInvoices.test.ts +79 -0
- package/src/react/hooks/useInvoices.ts +25 -0
- package/src/react/hooks/usePaymentMethodActions.ts +206 -0
- package/src/react/hooks/usePaymentMethods.ts +44 -0
- package/src/react/hooks/usePrices.ts +26 -0
- package/src/react/hooks/useProducts.test.ts +75 -0
- package/src/react/hooks/useProducts.ts +24 -0
- package/src/react/hooks/useSplitBreakdown.test.ts +151 -0
- package/src/react/hooks/useSplitBreakdown.ts +118 -0
- package/src/react/hooks/useStripeConfig.ts +31 -0
- package/src/react/hooks/useStripeMode.test.ts +49 -0
- package/src/react/hooks/useStripeMode.ts +9 -0
- package/src/react/hooks/useStripePublishableKey.test.ts +35 -0
- package/src/react/hooks/useStripePublishableKey.ts +9 -0
- package/src/react/hooks/useSubscription.ts +52 -0
- package/src/react/hooks/useSubscriptions.ts +33 -0
- package/src/react/index.payment-element.test.ts +41 -0
- package/src/react/index.test.ts +167 -0
- package/src/react/index.ts +279 -0
- package/src/react/lib/connect-requirement-keys.test.ts +73 -0
- package/src/react/lib/connect-requirement-keys.ts +66 -0
- package/src/react/lib/price-helpers.test.ts +199 -0
- package/src/react/lib/price-helpers.ts +68 -0
- package/src/react/lib/stripe-element-styles.test.ts +94 -0
- package/src/react/lib/stripe-element-styles.ts +178 -0
- package/src/react/lib/subscription-helpers.test.ts +127 -0
- package/src/react/lib/subscription-helpers.ts +64 -0
- package/src/react/types.ts +32 -0
- package/src/test.ts +5 -0
- package/src/testing/assert-test-env.test.ts +33 -0
- package/src/testing/assert-test-env.ts +20 -0
- package/src/testing/fixtures.ts +95 -0
- package/src/testing/index.ts +13 -0
- package/src/testing/mock-webhooks.test.ts +97 -0
- package/src/testing/mock-webhooks.ts +101 -0
- 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
|