@fantastic.dev/better-stripe 0.14.0 → 0.16.0

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAMnF,8CAA8C;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAK3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAMvE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,uCAAuC,CAAC;AAM/C,iBAAiB;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG7D,wBAAwB;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAElF,OAAO,EAAE,8BAA8B,EAAE,MAAM,gDAAgD,CAAC;AAGhG,2BAA2B;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAMnE,+BAA+B;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGjE,iCAAiC;AACjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAO7E,gFAAgF;AAChF,OAAO,EACL,cAAc,IAAI,sBAAsB,EACxC,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,WAAW,GACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAElE,uCAAuC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAK1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,+BAA+B;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAK5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAKxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AAEtF,sCAAsC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAQpE,wBAAwB;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAM5D,OAAO,EACL,aAAa,EACb,mBAAmB,GACpB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAQ5D,gCAAgC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAOhE,kCAAkC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAOxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAK9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAMtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAKpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAKxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAKpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAK1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAKxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAKlF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAQ1E,0CAA0C;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAMhE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAMlE,YAAY;AACZ,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,SAAS,GACV,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mCAAmC,CAAC;AAE3C,8BAA8B;AAC9B,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAS3E,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,IAAI,0BAA0B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/react/workflows/SaveCard.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+import { type StripeProviderProps } from "../components/StripeProvider.js";
+export type SaveCardFormState = {
+    paymentElement: ReactNode;
+    consent: boolean;
+    setConsent: (value: boolean) => void;
+    submit: () => Promise<void>;
+    isPending: boolean;
+    error: string | null;
+};
+export type SaveCardProps = Pick<StripeProviderProps, "publishableKey" | "appearance"> & {
+    scopeKey: string;
+    requestId?: string;
+    returnUrl: string;
+    /** Authenticated callback authorizes customer, records usage consent and durable request identity. */
+    createSetupIntent: (request: {
+        requestId: string;
+    }) => Promise<{
+        setupIntentId: string;
+        clientSecret: string;
+    }>;
+    onSuccess?: (setupIntentId: string) => void;
+    renderForm?: (state: SaveCardFormState) => ReactNode;
+};
+/** Unstyled card setup. Host owns usage disclosures and authorization. */
+export declare function SaveCard(props: SaveCardProps): import("react").JSX.Element;
+//# sourceMappingURL=SaveCard.d.ts.map

package/dist/react/workflows/SaveCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SaveCard.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/SaveCard.tsx"],"names":[],"mappings":"AACA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,iCAAiC,CAAC;AAIzC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,SAAS,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,mBAAmB,EACnB,gBAAgB,GAAG,YAAY,CAChC,GAAG;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,iBAAiB,EAAE,CAAC,OAAO,EAAE;QAC3B,SAAS,EAAE,MAAM,CAAC;KACnB,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,SAAS,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,SAAS,CAAC;CACtD,CAAC;AACF,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,+BAO5C"}

package/dist/react/workflows/SaveCard.js

@@ -0,0 +1,56 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { PaymentElement } from "@stripe/react-stripe-js";
+import { StripeProvider, } from "../components/StripeProvider.js";
+import { useConfirmPayment } from "../hooks/useConfirmPayment.js";
+import { useWorkflowResource } from "./useWorkflowResource.js";
+import { useWorkflowAction } from "./useWorkflowAction.js";
+/** Unstyled card setup. Host owns usage disclosures and authorization. */
+export function SaveCard(props) {
+    return (_jsx(SaveCardBody, { ...props }, `${props.scopeKey}:${props.requestId ?? ""}`));
+}
+function SaveCardBody(props) {
+    const [requestId] = useState(() => props.requestId ?? crypto.randomUUID());
+    const state = useWorkflowResource(() => props.createSetupIntent({ requestId }));
+    if (state.error)
+        return (_jsxs("div", { role: "alert", children: [state.error, _jsx("button", { type: "button", onClick: state.refresh, children: "Retry" })] }));
+    if (!state.data || state.isLoading)
+        return _jsx("p", { role: "status", children: "Preparing card setup\u2026" });
+    return (_jsx(StripeProvider, { publishableKey: props.publishableKey, appearance: props.appearance, elementsOptions: { clientSecret: state.data.clientSecret }, children: _jsx(SaveCardForm, { ...props, setupIntentId: state.data.setupIntentId }) }));
+}
+function SaveCardForm(props) {
+    const { confirmSetup, isReady, hasElements } = useConfirmPayment();
+    const [consent, setConsent] = useState(false);
+    const completed = useRef(false);
+    const action = useWorkflowAction(async () => {
+        if (completed.current)
+            return false;
+        if (!consent)
+            throw new Error("Consent is required to save this card.");
+        const result = await confirmSetup(props.returnUrl, "always");
+        if (!result.success)
+            throw new Error(result.error);
+        completed.current = true;
+        return true;
+    });
+    const state = {
+        paymentElement: _jsx(PaymentElement, {}),
+        consent,
+        setConsent,
+        submit: async () => {
+            const saved = await action.run();
+            if (saved)
+                props.onSuccess?.(props.setupIntentId);
+        },
+        isPending: action.isPending ||
+            !isReady ||
+            !hasElements ||
+            action.result !== undefined,
+        error: action.error,
+    };
+    if (props.renderForm)
+        return _jsx(_Fragment, { children: props.renderForm(state) });
+    return (_jsxs("div", { children: [state.paymentElement, _jsxs("label", { children: [_jsx("input", { type: "checkbox", checked: consent, onChange: (e) => setConsent(e.target.checked) }), "Save this card for future payments and show it at checkout."] }), state.error && _jsx("p", { role: "alert", children: state.error }), _jsx("button", { type: "button", disabled: !consent || state.isPending, onClick: () => void state.submit(), children: "Save card" })] }));
+}
+//# sourceMappingURL=SaveCard.js.map

package/dist/react/workflows/SaveCard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SaveCard.js","sourceRoot":"","sources":["../../../src/react/workflows/SaveCard.tsx"],"names":[],"mappings":"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"}

package/docs/react-workflows.md

@@ -531,3 +531,50 @@ implementation PR. Version 0.13.0 does not contain them. Consumers must upgrade
 to that release before removing their navigation guard or using the upload API.
 Production storage, session authorization, styling, translations and extended
 hosted onboarding verification remain application responsibilities.
+
+## Save a card through SetupIntent confirmation
+
+`SaveCard` provisions a customer-bound SetupIntent through an authenticated
+`createSetupIntent({ requestId })` callback and mounts Payment Element. It keeps
+creation retries on the same request, blocks duplicate confirmation, exposes
+failures and only calls `onSuccess(setupIntentId)` after Stripe reports
+`succeeded`. Stripe.js handles required authentication and redirects.
+
+```tsx
+<SaveCard
+  publishableKey={publishableKey}
+  scopeKey={`${authenticatedUserId}:${customerAccount}:off_session`}
+  requestId={persistedSaveRequestId}
+  returnUrl="https://app.example/billing/cards"
+  createSetupIntent={createAuthorizedSetupIntent}
+  onSuccess={refreshPaymentMethods}
+/>
+```
+
+The host callback calls `stripe.createSetupIntent(ctx, { userId,
+customerAccount, usage: "off_session", consent: true, idempotencyKey })` with
+server-resolved values. Record consent to the selected usage before mounting
+this workflow. The default confirmation checkbox separately grants permission
+to save and redisplay the card, sent as `allow_redisplay: "always"`. Use
+`renderForm` for your own disclosures, consent copy, Payment Element, pending
+state and errors. `useConfirmPayment().confirmSetup(returnUrl, allowRedisplay)`
+supports `always`, `limited` and `unspecified` when a different redisplay policy
+is required. Off-session usage does not guarantee that future payments will
+never require authentication.
+
+Persist the logical request and immutable customer/usage scope server-side.
+`requestId` and `scopeKey` isolate UI lifecycles; they do not authorize access.
+Handle redirect returns by retrieving the SetupIntent through an authenticated
+server adapter and checking ownership and status before displaying completion.
+Do not infer success from a URL parameter. Do not attach the confirmed method
+again or treat confirmation as changing a subscription default.
+
+Existing `AddCardForm` and `PaymentMethods` tokenization/attach integrations remain
+available. Tokenization plus attachment does not complete SetupIntent or SCA
+verification.
+
+## Component history and currency summaries
+
+See the [read contract guide](read-contracts.md) for reactive product, price and payout
+cursors, exact currency summaries, legacy backfill, payout failure details, and
+published-version adoption requirements.

package/docs/read-contracts.md

@@ -0,0 +1,136 @@
+# Reactive history and currency totals
+
+`BetterStripe.paginateProducts`, `paginatePrices`, and `paginatePayouts` read
+webhook-synchronized component records. They return standard Convex
+`{ page, isDone, continueCursor }` results. Pass `paginationOpts` with an opaque
+`cursor` or `null` and an integer `numItems` between 1 and 100. These readers use
+one indexed pagination call per invocation, ordered newest first. Existing array
+methods remain available. Neither an array preview nor one cursor page is an
+exact financial total.
+
+Products support `accountId` and `active`. Prices support the component's
+`productId` and `active`; this ID differs from `stripeProductId`. Authorize the
+parent product before exposing price reads. Payout history requires `accountId`
+and optionally accepts `status`. No filter means no restriction on that field.
+An omitted product account filter includes all accounts, including platform
+products. Host applications must derive allowed account and product scope from
+the authenticated user. A client-supplied account ID is not authorization.
+
+The Vite reference provides bindings in `example/convex/readContracts.ts` and
+`example/src/lib/stripe-hooks.ts`. Its selectable personas are demo identities.
+Production hosts must replace them with session authorization.
+
+## React pagination
+
+Wrap the public client method in an authorized host Convex query with
+`paginationOptsValidator` in its arguments. Return the package result unchanged.
+Bind that query with `useComponentPaginatedQuery` from the package React export.
+This uses the helper-compatible hook to pin end cursors when another page loads.
+Native `convex/react` pagination does not pin component helper cursors and can
+leave gaps when new rows arrive between loaded pages.
+
+```tsx
+const products = useComponentPaginatedQuery(
+  api.catalog.paginateProducts,
+  {}, // Host derives account scope from the session.
+  { initialNumItems: 25 },
+);
+const manager = useProductManager({
+  scopeKey: authenticatedUser.id,
+  createProduct,
+  createPrice,
+  updateProduct,
+  deactivateProduct,
+  deactivatePrice,
+});
+// Render products.results with the existing Products/useProductManager callbacks.
+// Expand each product with a separate useComponentPaginatedQuery for its component productId.
+// Do not join unbounded prices onto every product in a page.
+<button
+  disabled={products.status !== "CanLoadMore"}
+  onClick={() => products.loadMore(25)}
+>
+  Load more products
+</button>;
+```
+
+Use the standard `LoadingFirstPage`, `LoadingMore`, `CanLoadMore`, and `Exhausted`
+statuses for loading, empty, and terminal states. Queries react to writes
+and reset when their arguments change. Keep price hooks in a child component
+keyed by product ID. Do not invoke hooks inside a variable-length loop. A payout
+history binding uses the same contract. Pinned ranges can grow beyond the requested
+page size. The server caps each read at 200 rows or 1 MB and returns split hints
+for the hook to split large ranges without dropping rows. The `Payouts` workflow's live snapshot
+loader remains a separate Stripe action API, not a substitute for reactive
+component history or exact paid totals.
+
+## Exact totals by currency
+
+Use `getAccountEarningsByCurrency` and `getAccountPayoutsByCurrency` through the
+client or component. They return `totals` sorted by currency and bounded
+`transfers` or `payouts` previews. `previewLimit` is an integer from 0 to 100,
+defaulting to 50. Earnings totals include `gross`, `reversed`, `net`, and
+`transferCount`; payout totals include `paidOut` and `payoutCount`. Only payouts
+with status `paid` contribute to `paidOut`. Reinstatement transfers contribute to
+gross, while the original transfer's reversal remains recorded.
+
+All amounts use the currency's original minor units. Never add different
+currencies, or apply a fixed two-decimal conversion to JPY or KWD. The package
+maintains summaries transactionally with every supported transfer and payout
+mutation, including reversal mutations. Reads examine at most 501 summary rows,
+one unbackfilled-row probe, and 100 preview rows, regardless of history size.
+Accounts with more than 500 distinct currency strings fail explicitly. Summary
+updates serialize per account/currency through Convex OCC.
+
+Bind authorized wrappers to `createUseCurrencyEarnings(useQuery, earningsRef,
+payoutsRef)`. Its `totals` joins the two summaries by currency and never sums the
+previews. Render an `EarningsSummary` for each currency, passing that row's
+`currency` and only that currency's payout preview. The default earnings formatter handles supported ordinary charge currencies.
+Pass an explicit `formatAmount` callback for other observed currency precision,
+including KWD, or render the raw typed totals with your own currency policy.
+Use `getAccountBalance` or
+`getPayoutSnapshot` for per-currency available/pending balances. The component's
+earnings ledger does not determine settlement availability.
+
+### Existing installations
+
+After deploying the optional marker fields and summary table, invoke
+`components.betterStripe.earnings.mutations.backfillCurrencyTotals` from a trusted
+server migration. Run separately for `kind: "earnings"` and `kind: "payouts"`,
+starting with `cursor: null` and continuing with each `continueCursor` until
+`isDone`. Each mutation visits at most 100 rows. Retrying a page is safe, and
+ordinary package writes can continue during migration. A row's marker and its
+summary contribution commit together. New readers throw while an account has
+unbackfilled rows, so callers cannot mistake incomplete totals for zero.
+
+Keep raw imports and direct database edits out of normal application writes.
+If importing historical ledger rows, omit `totalsRecorded` and run the backfill.
+Never copy markers without their matching summaries.
+
+Legacy `getAccountEarnings`, `getAccountPayouts`, and `createUseEarnings` retain
+their single-currency shapes. The legacy queries now reject mixed-currency
+accounts and direct callers to the new methods. Their historical scans remain
+subject to Convex read limits; migrate busy accounts to the maintained summaries.
+Full referred-sale history uses `paginateTransfersByAccount`, not the preview.
+
+## Payout failures
+
+Component payout rows and live `RecipientPayoutRow` snapshots expose optional
+`failureCode` and `failureMessage`. Signed payout events write the provider's
+current snapshot to the existing payout identity. A later snapshot with absent
+or null provider failure fields clears stored details. Legacy rows remain valid.
+Ordinary event replay is deduplicated. This is snapshot reconciliation and does
+not guarantee convergence for globally out-of-order events.
+
+Host apps should translate known codes into safe recovery instructions and a
+settings link. Do not log or blindly render raw provider messages. Authorize
+reads using the recipient's shared connected account.
+
+## Publication and consumer acceptance
+
+A source merge does not activate an API in a published package. DOJO-908,
+DOJO-1037, DOJO-1041, and DOJO-2257 require a verified published version and
+explicit consumer adoption, authorized adapters, translated UI, and their own
+acceptance evidence. These package changes do not complete those tickets or add
+a second Dojo financial ledger, payout table, catalog store, or webhook processor.
+Use the repository release workflow; do not publish npm manually.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",
@@ -62,7 +62,8 @@
     "docs/accounts-v2-preview.md",
     "docs/react-workflows-audit.md",
     "CHANGELOG.md",
-    "MIGRATION.md"
+    "MIGRATION.md",
+    "docs/read-contracts.md"
   ],
   "scripts": {
     "build": "tsc --project ./tsconfig.build.json",

package/src/client/billing/checkoutOptions.ts

@@ -0,0 +1,27 @@
+import type { SplitRecipient } from "../../component/lib/fees.js";
+import type { FeeOverride } from "../types.js";
+
+/** Host-authorized Checkout Session request. */
+export type CreateCheckoutSessionOptions = {
+  idempotencyKey?: string;
+  userId: string;
+  orgId?: string;
+  stripePriceId: string;
+  mode: "payment" | "subscription" | "setup";
+  uiMode?: "embedded" | "redirect" | "custom" | "form";
+  quantity?: number;
+  returnUrl: string;
+  trialDays?: number;
+  accountId?: string;
+  customerEmail?: string;
+  /** Seller/recipient connected account to route funds to (destination charge). */
+  destinationAccountId?: string;
+  /** Multiple recipients (store + affiliate[s]); >1 routes via separate charges & transfers. */
+  split?: SplitRecipient[];
+  /** Per-call platform fee override; falls back to the configured default. */
+  fee?: FeeOverride;
+  /** Charge total (minor units) for one-time payment fee computation. */
+  amount?: number;
+  metadata?: Record<string, string>;
+  sessionOverrides?: Record<string, unknown>;
+};

package/src/client/billing/intents.test.ts

@@ -0,0 +1,216 @@
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "../index.js";
+import { getStripeClient, type Component, type RunCtx } from "../helpers.js";
+
+function fixture() {
+  const ref = { [Symbol.for("toReferencePath")]: "account" };
+  const component = {
+    core: { queries: { getAccountByStripeId: ref } },
+  } as unknown as Component;
+  const key = `sk_test_intents_${crypto.randomUUID()}`;
+  const client = new BetterStripe(component, { STRIPE_SECRET_KEY: key });
+  const sdk = getStripeClient(key);
+  const ctx = {
+    runQuery: vi
+      .fn()
+      .mockResolvedValue({ userId: "buyer", stripeAccountId: "acct_buyer" }),
+  } as unknown as RunCtx;
+  const price = vi.spyOn(sdk.prices, "retrieve").mockResolvedValue({
+    id: "price_one",
+    active: true,
+    type: "one_time",
+    unit_amount: 1200,
+    currency: "usd",
+    product: { id: "prod_one", active: true },
+  } as never);
+  const payment = vi.spyOn(sdk.paymentIntents, "create").mockResolvedValue({
+    id: "pi_one",
+    client_secret: "secret",
+    amount: 1200,
+  } as never);
+  const setup = vi.spyOn(sdk.setupIntents, "create").mockResolvedValue({
+    id: "seti_one",
+    client_secret: "setup_secret",
+  } as never);
+  const opts = {
+    userId: "buyer",
+    customerAccount: "acct_buyer",
+    idempotencyKey: "order:one",
+  };
+  return { client, ctx, price, payment, setup, opts };
+}
+it("creates a card-only intent with provider price economics and protected ownership metadata", async () => {
+  const { client, ctx, payment, opts } = fixture();
+  const args = {
+    ...opts,
+    stripePriceId: "price_one",
+    metadata: { userId: "forged", bsSplit: "forged", planId: "plan_one" },
+  };
+  expect(await client.createPaymentIntent(ctx, args)).toEqual({
+    paymentIntentId: "pi_one",
+    clientSecret: "secret",
+  });
+  await client.createPaymentIntent(ctx, args);
+  expect(payment).toHaveBeenNthCalledWith(
+    2,
+    {
+      amount: 1200,
+      currency: "usd",
+      customer_account: "acct_buyer",
+      receipt_email: undefined,
+      allowed_payment_method_types: ["card"],
+      metadata: {
+        userId: "buyer",
+        planId: "plan_one",
+        stripePriceId: "price_one",
+        stripeProductId: "prod_one",
+      },
+    },
+    { idempotencyKey: "order:one" },
+  );
+});
+it.each([
+  { active: false },
+  { type: "recurring" },
+  { unit_amount: null },
+  { unit_amount: 0 },
+  { product: { id: "prod_one", active: false } },
+])("rejects unsupported price economics %j", async (override) => {
+  const { client, ctx, price, payment, opts } = fixture();
+  price.mockResolvedValue({
+    active: true,
+    type: "one_time",
+    unit_amount: 1200,
+    currency: "usd",
+    product: { id: "prod_one", active: true },
+    ...override,
+  } as never);
+  await expect(
+    client.createPaymentIntent(ctx, { ...opts, stripePriceId: "price_one" }),
+  ).rejects.toThrow();
+  expect(payment).not.toHaveBeenCalled();
+});
+it("rejects another customer's account before provider writes", async () => {
+  const { client, ctx, payment, setup, opts } = fixture();
+  await expect(
+    client.createPaymentIntent(ctx, {
+      ...opts,
+      userId: "attacker",
+      stripePriceId: "price_one",
+    }),
+  ).rejects.toThrow(/belong/);
+  await expect(
+    client.createSetupIntent(ctx, {
+      ...opts,
+      userId: "attacker",
+      usage: "off_session",
+      consent: true,
+    }),
+  ).rejects.toThrow(/belong/);
+  expect(payment).not.toHaveBeenCalled();
+  expect(setup).not.toHaveBeenCalled();
+});
+it("provisions consented card setup, preserves retry key after transport failure, and returns minimal secrets", async () => {
+  const { client, ctx, setup, opts } = fixture();
+  const args = {
+    ...opts,
+    usage: "off_session" as const,
+    consent: true as const,
+  };
+  setup.mockRejectedValueOnce(new Error("connection lost"));
+  await expect(client.createSetupIntent(ctx, args)).rejects.toThrow(
+    "connection lost",
+  );
+  expect(await client.createSetupIntent(ctx, args)).toEqual({
+    setupIntentId: "seti_one",
+    clientSecret: "setup_secret",
+  });
+  expect(setup).toHaveBeenNthCalledWith(
+    2,
+    {
+      customer_account: "acct_buyer",
+      usage: "off_session",
+      allowed_payment_method_types: ["card"],
+      metadata: { userId: "buyer" },
+    },
+    { idempotencyKey: "order:one" },
+  );
+});
+it.each([undefined, "", "\n", "x".repeat(256)])(
+  "requires a valid explicit retry key %j",
+  async (key) => {
+    const { client, ctx, setup, payment, opts } = fixture();
+    const args = { ...opts, idempotencyKey: key as string };
+    await expect(
+      client.createSetupIntent(ctx, {
+        ...args,
+        usage: "on_session",
+        consent: true,
+      }),
+    ).rejects.toThrow();
+    await expect(
+      client.createPaymentIntent(ctx, { ...args, stripePriceId: "price_one" }),
+    ).rejects.toThrow();
+    expect(setup).not.toHaveBeenCalled();
+    expect(payment).not.toHaveBeenCalled();
+  },
+);
+it("requires setup consent and a supported usage", async () => {
+  const { client, ctx, setup, opts } = fixture();
+  await expect(
+    client.createSetupIntent(ctx, {
+      ...opts,
+      usage: "off_session",
+      consent: false as unknown as true,
+    }),
+  ).rejects.toThrow(/consent/);
+  await expect(
+    client.createSetupIntent(ctx, {
+      ...opts,
+      usage: "invalid" as "on_session",
+      consent: true,
+    }),
+  ).rejects.toThrow(/usage/);
+  expect(setup).not.toHaveBeenCalled();
+});
+it("rejects missing client secrets", async () => {
+  const { client, ctx, setup, payment, opts } = fixture();
+  setup.mockResolvedValue({ id: "seti_one", client_secret: null } as never);
+  payment.mockResolvedValue({ id: "pi_one", client_secret: null } as never);
+  await expect(
+    client.createSetupIntent(ctx, {
+      ...opts,
+      usage: "on_session",
+      consent: true,
+    }),
+  ).rejects.toThrow(/secret/);
+  await expect(
+    client.createPaymentIntent(ctx, { ...opts, stripePriceId: "price_one" }),
+  ).rejects.toThrow(/secret/);
+});
+it("preserves host-authorized guest purchases without inventing a customer account", async () => {
+  const { client, ctx, payment } = fixture();
+  await client.createPaymentIntent(ctx, {
+    userId: "",
+    stripePriceId: "price_one",
+    idempotencyKey: "guest:one",
+  });
+  expect(payment).toHaveBeenCalledWith(
+    expect.objectContaining({
+      customer_account: undefined,
+      metadata: expect.objectContaining({ userId: "" }),
+    }),
+    { idempotencyKey: "guest:one" },
+  );
+});
+it("preserves automatic-method checkout when the host selects it", async () => {
+  const { client, ctx, payment, opts } = fixture();
+  await client.createPaymentIntent(ctx, {
+    ...opts,
+    stripePriceId: "price_one",
+    paymentMethods: "automatic",
+  });
+  const request = payment.mock.calls[0][0];
+  expect(request.automatic_payment_methods).toEqual({ enabled: true });
+  expect(request.allowed_payment_method_types).toBeUndefined();
+});