@fantastic.dev/better-stripe 0.7.0 → 0.8.1

package/docs/react-workflows-audit.md

@@ -0,0 +1,88 @@
+# Example UI audit
+
+Every financial/account page has a public React component or workflow hook in
+`@fantastic.dev/better-stripe/react`. Native unstyled components implement the
+shared workflows. The example binds authenticated Convex queries/actions and
+uses render props or companion hooks to apply shadcn styling.
+
+| Example page or adapter                   | Package UI and workflow ownership                                                                                                                      |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Home and stores                           | `Storefront`, including store filtering, active catalog prices, purchase actions, and referral attribution                                             |
+| Checkout chooser                          | `CheckoutChooser`, `CHECKOUT_OPTIONS`, recurring-product compatibility and selection                                                                   |
+| Checkout session / PaymentIntent adapters | `Checkout`, `CheckoutElementsForm`, `PaymentIntentForm`, `CheckoutForm`, `EmbeddedCheckout`, including loading, retry, validation and confirmation     |
+| Checkout status                           | `CheckoutStatus`, `PaymentReceipt`, server/webhook confirmation                                                                                        |
+| Customer overview                         | `SubscriptionOverview`                                                                                                                                 |
+| Customer subscription billing             | `useSubscriptionManager`, `SubscriptionManager`, `BuyerBillingView`, `SubscriptionCard`, `Invoices`, `BillingPortalLink`                               |
+| Customer invoices                         | `Invoices`                                                                                                                                             |
+| Customer payment methods                  | `usePaymentMethodsManager`, `PaymentMethods`, `PaymentMethodsList`, `AddCardForm`, Stripe providers                                                    |
+| Seller overview                           | `PayoutOverview`, `AccountCreateCard`, `ConnectStatusBadge`                                                                                            |
+| Seller and affiliate payouts              | `Payouts`, `PayoutHistory`, live balances, upcoming date, history and pagination                                                                       |
+| Seller earnings                           | `EarningsSummary`, `PayoutSchedule`, `PayoutHistory`, `earningsFromBalance`, `useWorkflowResource`                                                     |
+| Seller sales                              | `Sales`                                                                                                                                                |
+| Seller subscriptions                      | `Subscriptions`, `SubscriptionCard`                                                                                                                    |
+| Seller and admin products                 | `useProductManager`, `Products`, `PriceCard`, product/price creation, editing and archiving                                                            |
+| Seller account details                    | `useAccountManager`, `Account`, `AccountLoginCard`, `ConnectRequirements`                                                                              |
+| Seller onboarding / account setup         | `useOnboarding`, `Onboarding`, `AccountCloseCard`, `DEFAULT_CONNECT_COUNTRIES`                                                                         |
+| Seller marketplace account                | Account/onboarding hooks, `AccountConfigurations`, `ConnectStatusBadge`, `CheckoutStatus`, shared action lifecycle                                     |
+| Seller billing                            | `usePlanBilling`, `BillingPlans`, `EmbeddedCheckout`, `useInvoiceEstimate`, `InvoiceEstimate`, `useBalanceFunding`, `BalancePaymentSource`             |
+| Seller refunds                            | `useRefunds`, `Refunds`, `RefundHistory`, `PaymentDetails`, `CostRecovery`                                                                             |
+| Seller disputes                           | `useDisputeResponse`, `Disputes`, `DisputesList`, `DisputeDetail`, `EvidenceForm`, `ChargebackLedger`, `CostRecovery`                                  |
+| Affiliate earnings                        | `Earnings`, `EarningsSummary`                                                                                                                          |
+| Affiliate referred sales                  | `ReferredSales`, store attribution and commission                                                                                                      |
+| Affiliate links                           | `useReferralLinks`, `ReferralLinks`, `ClipboardButton`                                                                                                 |
+| Admin overview                            | `Overview`                                                                                                                                             |
+| Admin subscriptions                       | `Subscriptions`, `useSubscriptionFilter`                                                                                                               |
+| Admin webhooks                            | `WebhookEvents`, `useWebhookFilters`                                                                                                                   |
+| Admin setup                               | `useWebhookSetup`, `WebhookSetup`, `EnvironmentStatus`, `FixtureProgress`, `useTaskRunner`, `StripeSetup`, `ClipboardButton`, shared actions/resources |
+| Admin sandbox testing                     | `useTaskRunner`, `SandboxTesting`, `WorkflowTasks`                                                                                                     |
+| Legacy affiliate split demo               | `Checkout`, `SplitBreakdown`, `EarningsSummary`, bound package hook factories                                                                          |
+| Legacy destination-charge module          | `Checkout`, `ChargeSummary`; the legacy public route currently resolves to the split demo                                                              |
+| Integration presentation switch           | `IntegrationSwitch`; only the active view mounts                                                                                                       |
+| Connect alternatives                      | `Connect` with account management, onboarding, payments/refunds, disputes, balances, payouts and notifications                                         |
+| Styled shared tables                      | `Collection` and domain collections; `WorkflowTable` only maps their state/columns to shadcn                                                           |
+
+The example owns app branding, navigation, theme controls, the persona/store
+switcher, route guards, URL state, and styling. It also owns its users and
+server bindings, fee plans, referral-share policy, recovery billing rules,
+sandbox scenario definitions, and authorization. These are application choices,
+not prerequisites imposed by the public React package.
+
+Some examples use companion hooks with styled markup instead of mounting the
+native component. That markup changes presentation; the package owns the
+workflow state, validation, duplicate-action handling, and async errors. Reusable
+native components exist for consumers who do not want to write those renderers.
+Connect and hosted Stripe UI remain available only where Stripe supports them.
+
+## Verification
+
+- Public-entry tests render native components without example providers, routing,
+  CSS classes, or inline styling and without calling server actions during render.
+- Interaction tests exercise native product-price creation, partial refunds,
+  balance consent, checkout selection, and other workflow controllers.
+- Account changes and duplicate actions have regression tests.
+- Browser smoke coverage visits all five personas' pages and the integration views.
+- Checkout tests complete referred guest purchases through all five integrations
+  in a Stripe sandbox and verify webhook receipts and settlement.
+- `pnpm run check:all` enforces all repository gates, including Shadscan at 100.
+
+## Follow-up audit
+
+The final sandbox QA and follow-up audit checked every example route and its
+adapters against the public React exports. Checkout delegates through the
+session and PaymentIntent adapters. The remaining local state controls the
+app's command menu, mobile sidebar, URL parameters, or selected demo price.
+Financial actions use package workflow controllers or components.
+
+The follow-up removed payout-status filtering from the example. Both native
+`Payouts` and its render-prop example now consume the package's
+`upcomingPayouts`, `previousPayouts`, and `nextPayout`. Regression tests cover
+mixed payout statuses and arrival ordering. Dispute lists and detail views hide
+stale evidence deadlines after a dispute leaves a response-required status.
+
+Live browser checks cover reset/reseed, all persona routes, integration tabs,
+five checkout integrations, saved-card add/remove and persistence, product
+editing, subscription pause/resume, invoice estimates, balance-payment consent,
+affiliate link copying, dispute evidence, and partial/remaining-balance refunds.
+The tests use Stripe sandbox objects and await action results or webhook state.
+Native public-entry tests also render the workflows without example providers,
+CSS classes, inline styles, or example URLs.

package/docs/react-workflows.md

@@ -0,0 +1,234 @@
+# React workflows
+
+Import the example's reusable UI and workflow hooks from
+`@fantastic.dev/better-stripe/react`. You do not need the example's route tree,
+role provider, Tailwind, or shadcn components.
+
+Components render semantic HTML without package CSS. Use their render props or
+companion hooks to supply your own design system. Stripe iframe contents use
+Stripe's `appearance` options and retain Stripe's own styling.
+
+## Bind your backend
+
+Pass authenticated server callbacks and query results to the components. This
+keeps your user IDs, authorization, database schema, and business rules in your
+application. The example's pages demonstrate Convex adapters for these callbacks.
+A callback is an API contract, not an authorization boundary. The server must
+check account ownership, price IDs, amounts, referral attribution, and permissions.
+
+`scopeKey` identifies the authenticated account or customer. Change it when that
+identity changes so pending responses cannot populate another account's UI.
+For checkout, change `orderKey` when the customer, price, or attribution changes.
+Do not put secret keys in these props. Browser code needs only a publishable key
+and short-lived client secrets returned by your server.
+
+## Choose a checkout
+
+`Checkout` supports all five checkout integrations. It creates the session or
+PaymentIntent, handles loading and retry, mounts the required Stripe provider,
+and reports confirmation errors. Hosted Checkout waits for an explicit click.
+`CheckoutChooser` renders the five choices and their pros and cons. It supports
+controlled selection, render props, and a recurring-product compatibility notice.
+`CHECKOUT_OPTIONS` also exports the descriptions.
+
+```tsx
+import { Checkout } from "@fantastic.dev/better-stripe/react";
+
+// createSession is your authenticated server binding. It must validate priceId.
+function Purchase({ publishableKey, priceId, createSession }) {
+  return (
+    <Checkout
+      mode="custom"
+      publishableKey={publishableKey}
+      orderKey={priceId}
+      returnUrl={`${window.location.origin}/receipt?session_id={CHECKOUT_SESSION_ID}`}
+      createSession={({ mode, requestId }) =>
+        createSession({ priceId, uiMode: mode, requestId })
+      }
+    />
+  );
+}
+```
+
+The callback returns `{ stripeSessionId, clientSecret?, url? }`. It must return
+`url` for `redirect` and `clientSecret` for the other session modes. Use the
+request ID for server idempotency. A user-triggered retry creates a new request
+ID; also enforce application-level duplicate-order protection on the server.
+
+| Mode             | Stripe integration                    | Tradeoff                                                               |
+| ---------------- | ------------------------------------- | ---------------------------------------------------------------------- |
+| `redirect`       | Hosted Checkout Session               | Least UI work, leaves your app                                         |
+| `embedded`       | Embedded Checkout Session             | Complete Stripe checkout in your page, less layout control             |
+| `custom`         | Checkout Session with Payment Element | Custom form layout with Checkout's session model                       |
+| `payment-intent` | PaymentIntent with Payment Element    | Payment control, application owns order and subscription orchestration |
+| `form`           | Preview Embedded Checkout Form        | Compact Stripe form, requires the supported Stripe preview             |
+
+For `payment-intent`, provide `createPaymentIntent({ requestId })` instead of
+`createSession`. Return `{ paymentIntentId, clientSecret }`. Payment Intents do
+not create subscriptions. Stripe.js supplies the browser SDK and publishable-key
+handling for these flows; it is not a separate server payment model.
+
+Use `renderForm` on the custom and PaymentIntent modes to render your own email
+input, `paymentElement`, error, and submit button. The preview `form` mode renders
+Stripe's form and does not use that renderer. `children` replaces the outer
+checkout frame and receives `content`, `isLoading`, `error`, and `retry`.
+The lower-level `CheckoutElementsForm`, `PaymentIntentForm`, and `CheckoutForm`
+are also exported for an existing client secret.
+
+Only a server-confirmed payment or checkout session should grant access to the
+product. Use `PaymentReceipt` or `CheckoutStatus` with webhook-backed query data;
+a browser return URL alone does not prove payment.
+
+## Headless or Stripe embedded
+
+`Account`, `Onboarding`, `Disputes`, `Refunds`, `Earnings`, and `Payouts` accept
+`presentation="embedded"` with Connect session props. Their default headless
+presentation accepts domain-specific data and callbacks. `Connect` also exposes
+account, onboarding, payments, refunds, disputes, balances, payouts, and
+notifications widgets directly.
+
+```tsx
+import { IntegrationSwitch, Payouts } from "@fantastic.dev/better-stripe/react";
+
+function AccountPayouts({
+  accountId,
+  publishableKey,
+  loadPayouts,
+  createSession,
+}) {
+  return (
+    <IntegrationSwitch
+      views={{
+        headless: <Payouts scopeKey={accountId} load={loadPayouts} />,
+        embedded: (
+          <Payouts
+            presentation="embedded"
+            scopeKey={accountId}
+            publishableKey={publishableKey}
+            fetchClientSecret={async () => (await createSession()).clientSecret}
+          />
+        ),
+      }}
+    />
+  );
+}
+```
+
+The server creates an Account Session for the authenticated connected account
+and enables the requested component and features. Session refresh uses the latest callback. Appearance and locale updates apply
+to the active Connect instance without remounting it. Changing the publishable
+key creates a new instance. `IntegrationSwitch` mounts only the active view and has
+no router dependency. It also supports controlled `value`/`onValueChange` and
+`components` and `hosted` views when your workflow has those alternatives.
+
+Connect displays only the payment data supported for that connected account.
+The example's platform-owned separate-charges-and-transfers ledger remains in
+its headless sales/refund/dispute views. A Connect embed cannot turn that ledger
+into connected-account-owned charges. Refunds use the Connect Payments widget;
+there is no separate Connect refund catalog widget. Product management,
+customer subscriptions, and platform billing do not have equivalent Connect
+widgets. Use package UI or the hosted Billing Portal for those workflows.
+
+## Component and hook reference
+
+| Workflow              | Unstyled components                                                                                            | Companion hooks/helpers                                                      |
+| --------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Store browsing        | `Storefront`, `PriceCard`                                                                                      | Store/product/price models and purchase callbacks                            |
+| Checkout              | `CheckoutChooser`, `Checkout`, `CheckoutElementsForm`, `PaymentIntentForm`, `CheckoutForm`, `EmbeddedCheckout` | `CHECKOUT_OPTIONS`                                                           |
+| Receipts              | `PaymentReceipt`, `CheckoutStatus`                                                                             | Server-backed payment/session data                                           |
+| Earnings              | `Earnings`, `EarningsSummary`                                                                                  | `earningsFromBalance`                                                        |
+| Payouts               | `Payouts`, `PayoutSchedule`, `PayoutHistory`, `PayoutOverview`                                                 | `getPayoutTotals`                                                            |
+| Sales                 | `Sales`, `ReferredSales`                                                                                       | Server-authoritative economic rows                                           |
+| Refunds               | `Refunds`, `RefundHistory`                                                                                     | `useRefunds`, `parseAmountCents`                                             |
+| Disputes              | `Disputes`, `DisputesList`, `DisputeDetail`, `EvidenceForm`, `ChargebackLedger`                                | `useDisputeResponse`                                                         |
+| Onboarding            | `Onboarding`                                                                                                   | `useOnboarding`                                                              |
+| Accounts              | `Account`, `AccountConfigurations`                                                                             | `useAccountManager`                                                          |
+| Product management    | `Products`                                                                                                     | `useProductManager`                                                          |
+| Subscriptions         | `Subscriptions`, `SubscriptionManager`, `SubscriptionOverview`, `SubscriptionCard`                             | `useSubscriptionManager`, `useSubscriptionFilter`, `currentSubscriptionFrom` |
+| Billing               | `BillingPlans`, `BillingPortal`, `InvoiceEstimate`, `Invoices`, `BalancePaymentSource`                         | `usePlanBilling`, `useInvoiceEstimate`, `useBalanceFunding`                  |
+| Payment methods       | `PaymentMethods`, `PaymentMethodsList`, `AddCardForm`                                                          | `usePaymentMethodsManager`, `toPaymentMethodItem`                            |
+| Seller cost recovery  | `CostRecovery`                                                                                                 | Server-calculated outstanding/collected/invoiced amounts                     |
+| Referral sharing      | `ReferralLinks`, `ClipboardButton`                                                                             | `useReferralLinks`                                                           |
+| Admin                 | `Overview`, `WebhookEvents`                                                                                    | `useWebhookFilters`, `webhookQueryArgs`                                      |
+| Sandbox setup/testing | `StripeSetup`, `SandboxTesting`, `WorkflowTasks`, `WebhookSetup`, `EnvironmentStatus`, `FixtureProgress`       | `useTaskRunner`, `useWebhookSetup`                                           |
+| Shared state/tables   | `IntegrationSwitch`, `Collection`                                                                              | `useWorkflowAction`, `useWorkflowResource`                                   |
+
+The example still owns its navigation, persona switcher, application branding,
+server authorization, sandbox fixture definitions, and marketplace fee policy.
+Its styled forms and tables consume package hooks/render props. The package's
+default components implement those workflows without the example's providers.
+The package does not seed or reset a Stripe account just because a component
+mounts. Setup/testing tasks call the operations you explicitly bind.
+
+## Data contracts and styling
+
+`Payouts.load(cursor?)` returns a `PayoutSnapshot` with `balances`, `payouts`,
+`upcoming`, and `nextCursor`. Each balance has `currency`, `available`, and
+`pending`. Payout rows include `id`, `amount`, `currency`, `status`, `arrivalDate`,
+and `created`. The component shows available and pending balances, the next
+known payout and arrival date, upcoming payouts, and paginated previous payouts.
+Render props expose `upcomingPayouts` sorted by arrival date,
+`previousPayouts`, and `nextPayout`. Use these package-owned classifications
+in custom UI; completed or failed payouts are excluded from upcoming payouts.
+If Stripe has not provided an upcoming payout, the UI says so rather than
+inventing a date.
+
+Payout, invoice-estimate, cost, and webhook timestamps use Unix milliseconds.
+Subscription period/trial fields use ISO date strings, matching the existing
+subscription API. Convert raw Stripe Unix seconds in your adapter. Money values use integer minor units. The current decimal refund
+input and price-formatting helpers use two decimal places, as in the USD
+example. Supply custom rendering/input conversion for zero-decimal and
+three-decimal currencies. Never combine balances across currencies.
+
+Sale fees, affiliate shares, recovery costs, invoice estimates, and settlement
+statuses come from server data. The UI does not recalculate the example's fee
+policy or charge outstanding costs by itself. Balance funding requires explicit
+consent and a server integration with Stripe's supported preview. Card fallback,
+renewal recovery, and debt collection remain server business rules.
+
+Use exported `*Props`, row models, and render-state types for typed adapters.
+Tables accept optional columns and a `children(state)` renderer. Action hooks
+expose pending, error, and results so your buttons and alerts share the same
+validation and duplicate-submit handling as the native components.
+
+```tsx
+import { Invoices } from "@fantastic.dev/better-stripe/react";
+
+function InvoiceList({ invoices }) {
+  return (
+    <Invoices rows={invoices}>
+      {({ rows, isLoading, isEmpty }) =>
+        isLoading ? (
+          <p>Loading invoices…</p>
+        ) : isEmpty ? (
+          <p>No invoices yet.</p>
+        ) : (
+          <ul>
+            {rows.map((row) => (
+              <li key={row.stripeInvoiceId}>{row.stripeInvoiceId}</li>
+            ))}
+          </ul>
+        )
+      }
+    </Invoices>
+  );
+}
+```
+
+Default markup has `data-better-stripe` attributes for scoped CSS. Use render
+props to replace markup with your design system, including labels and locale
+formatting. A render function replaces the supplied markup; render its `content`
+or `paymentElement` where those are part of the state's contract.
+
+## Example coverage
+
+See [the page audit](react-workflows-audit.md) for the mapping from every example
+page to package components and hooks. `ChargeSummary` displays server-calculated
+charge/fee/payout figures. `PaymentDetails` displays recorded charge and refund
+state. `PayoutOverview` shows payout activity totals, which are separate from the
+available and pending Stripe balances shown by `Payouts`.
+
+`DEFAULT_CONNECT_COUNTRIES` provides the example's eight country choices and is
+shared by its account pages and native `Onboarding`. Supply `countries` to limit
+or expand the UI for your platform. This default is not a complete list of
+Stripe-supported countries; your server must validate account eligibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",
@@ -57,6 +57,8 @@
   "files": [
     "dist",
     "src",
+    "docs/react-workflows.md",
+    "docs/react-workflows-audit.md",
     "CHANGELOG.md",
     "MIGRATION.md"
   ],
@@ -83,7 +85,18 @@
     "prepublishOnly": "npm run clean && npm run build && npm run typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "check:design-system": "eslint --config eslint.design-system.config.mjs . --max-warnings 0",
+    "check:shadscan": "shadscan \"./example\" --json --fail-under 100 --no-roast --no-interactive",
+    "check:all": "repo-gates check-all",
+    "check:size": "repo-gates check-size",
+    "check:debt": "repo-gates check-debt",
+    "check:circular": "repo-gates check-circular",
+    "check:secrets": "repo-gates check-secrets",
+    "check:ci-parity": "repo-gates check-ci-parity",
+    "check:coverage": "repo-gates check-coverage",
+    "format:check": "pnpm run format",
+    "check:agents": "repo-gates check-agents"
   },
   "dependencies": {
     "@stripe/connect-js": "^3.4.6",
@@ -95,6 +108,7 @@
   "devDependencies": {
     "@convex-dev/eslint-plugin": "^5.0.0",
     "@edge-runtime/vm": "^5.0.0",
+    "@fantastic.dev/repo-gates": "^0.4.0",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.7",
@@ -113,7 +127,9 @@
     "pretty-quick": "^4.2.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "typescript-eslint": "^8.71.1",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.3",
+    "@shadcn/lint": "0.1.5",
+    "@shadscan/cli": "0.7.0"
   },
   "peerDependencies": {
     "convex": "^1.29.3",

package/src/client/billing/checkout-ui-modes.test.ts

@@ -0,0 +1,49 @@
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "../helpers.js";
+import { createCheckoutSession } from "./checkout.js";
+for (const [mode, expected] of [
+  ["custom", "elements"],
+  ["form", "form"],
+] as const)
+  it(`creates ${mode} checkout without hosted URLs`, async () => {
+    const create = vi.fn().mockResolvedValue({
+      id: "cs_test",
+      status: "open",
+      mode: "payment",
+      client_secret: "client_secret_test",
+      metadata: {},
+      expires_at: 1800000000,
+    });
+    const component = {
+      billing: {
+        mutations: {
+          upsertCheckoutSession: {
+            [Symbol.for("toReferencePath")]:
+              "betterStripe/billing/mutations/upsertCheckoutSession",
+          },
+        },
+      },
+    } as unknown as Component;
+    await createCheckoutSession(
+      { checkout: { sessions: { create } } } as unknown as Stripe,
+      component,
+      {
+        runQuery: vi.fn().mockResolvedValue(null),
+        runMutation: vi.fn(),
+      } as unknown as RunCtx,
+      {
+        userId: "user_1",
+        stripePriceId: "price_1",
+        mode: "payment",
+        uiMode: mode,
+        returnUrl: "https://app.test/return",
+      },
+    );
+    expect(create.mock.calls[0][0]).toMatchObject({
+      ui_mode: expected,
+      return_url: "https://app.test/return",
+    });
+    expect(create.mock.calls[0][0].success_url).toBeUndefined();
+    expect(create.mock.calls[0][0].cancel_url).toBeUndefined();
+  });

package/src/client/billing/checkout.ts

@@ -114,7 +114,7 @@ export async function createCheckoutSession(
     orgId?: string;
     stripePriceId: string;
     mode: "payment" | "subscription" | "setup";
-    uiMode?: "embedded" | "redirect";
+    uiMode?: "embedded" | "redirect" | "custom" | "form";
     quantity?: number;
     returnUrl: string;
     trialDays?: number;
@@ -295,8 +295,13 @@ export async function createCheckoutSession(
     sessionParams.payment_intent_data = paymentIntentData;
   }
 
-  if (uiMode === "embedded") {
-    sessionParams.ui_mode = "embedded_page";
+  if (uiMode === "embedded" || uiMode === "custom" || uiMode === "form") {
+    sessionParams.ui_mode =
+      uiMode === "custom"
+        ? "elements"
+        : uiMode === "form"
+          ? "form"
+          : "embedded_page";
     sessionParams.return_url = opts.returnUrl;
   } else {
     sessionParams.success_url = `${opts.returnUrl}?session_id={CHECKOUT_SESSION_ID}`;

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

@@ -75,7 +75,9 @@ describe("listInvoices", () => {
 
     expect(result).toEqual([]);
     const [ref, args] = ctx.runQuery.mock.calls[0];
-    expect(ref[TO_REF]).toBe(refPath(component, "billing/queries/listInvoices"));
+    expect(ref[TO_REF]).toBe(
+      refPath(component, "billing/queries/listInvoices"),
+    );
     expect(args).toEqual({});
   });
 
@@ -125,7 +127,9 @@ describe("listInvoicesByUser", () => {
 
     expect(result).toBe(rows);
     const [ref, args] = ctx.runQuery.mock.calls[0];
-    expect(ref[TO_REF]).toBe(refPath(component, "billing/queries/listInvoices"));
+    expect(ref[TO_REF]).toBe(
+      refPath(component, "billing/queries/listInvoices"),
+    );
     expect(args).toEqual({ userId: "u_9" });
   });
 });
@@ -177,9 +181,9 @@ describe("upsertInvoice", () => {
   it("throws when ctx has no runMutation (runMutationOrThrow guard)", async () => {
     const ctx = { runQuery: vi.fn() } as unknown as RunCtx;
 
-    await expect(
-      upsertInvoice(makeComponent(), ctx, baseOpts),
-    ).rejects.toThrow(/requires a Convex ctx with runMutation/);
+    await expect(upsertInvoice(makeComponent(), ctx, baseOpts)).rejects.toThrow(
+      /requires a Convex ctx with runMutation/,
+    );
   });
 });
 
@@ -189,7 +193,9 @@ describe("getInvoice", () => {
     const row = { stripeInvoiceId: "in_4", status: "paid" };
     const ctx = makeCtx(row);
 
-    const result = await getInvoice(component, ctx, { stripeInvoiceId: "in_4" });
+    const result = await getInvoice(component, ctx, {
+      stripeInvoiceId: "in_4",
+    });
 
     expect(result).toBe(row);
     const [ref, args] = ctx.runQuery.mock.calls[0];

package/src/client/connect/disputes.test.ts

@@ -73,6 +73,21 @@ describe("buildDisputeEvidence (BTS-31)", () => {
     });
   });
 
+  it("sends communication prose as text while preserving other context", () => {
+    expect(
+      buildDisputeEvidence({
+        additionalInfo: "Delivered",
+        customerCommunication: "Customer confirmed receipt",
+      }),
+    ).toEqual({
+      uncategorized_text:
+        "Delivered\n\nCustomer communication:\nCustomer confirmed receipt",
+    });
+    expect(buildDisputeEvidence({ customerCommunication: "file_123" })).toEqual(
+      { customer_communication: "file_123" },
+    );
+  });
+
   it("omits unset categories", () => {
     expect(buildDisputeEvidence({ productDescription: "X" })).toEqual({
       product_description: "X",

package/src/client/connect/disputes.ts

@@ -260,9 +260,19 @@ export function buildDisputeEvidence(input: {
   accessActivity?: string;
   /** Off-platform context / anything else (Stripe: uncategorized_text). */
   additionalInfo?: string;
-  /** Communications with the buyer (Stripe: customer_communication). */
+  /** Communication prose is appended to text evidence; file_ IDs remain file evidence. */
   customerCommunication?: string;
 }): import("stripe").Stripe.DisputeUpdateParams.Evidence {
+  const communication = input.customerCommunication;
+  const file = communication?.startsWith("file_") ? communication : undefined;
+  const text = [
+    input.additionalInfo,
+    !file && communication
+      ? `Customer communication:\n${communication}`
+      : undefined,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
   return {
     ...(input.productDescription
       ? { product_description: input.productDescription }
@@ -270,12 +280,8 @@ export function buildDisputeEvidence(input: {
     ...(input.accessActivity
       ? { access_activity_log: input.accessActivity }
       : {}),
-    ...(input.additionalInfo
-      ? { uncategorized_text: input.additionalInfo }
-      : {}),
-    ...(input.customerCommunication
-      ? { customer_communication: input.customerCommunication }
-      : {}),
+    ...(text ? { uncategorized_text: text } : {}),
+    ...(file ? { customer_communication: file } : {}),
   };
 }
 

package/src/client/connect/paymentMethods.test.ts

@@ -60,7 +60,9 @@ describe("payment methods are keyed to the customer_account (BTS-19 reuse)", ()
 
   it("detaches a payment method by id", async () => {
     const stripe = makeStripe();
-    await detachPaymentMethod(asStripe(stripe), ctx, { paymentMethodId: "pm_1" });
+    await detachPaymentMethod(asStripe(stripe), ctx, {
+      paymentMethodId: "pm_1",
+    });
     expect(stripe.paymentMethods.detach).toHaveBeenCalledWith("pm_1");
   });
 });

package/src/client/connect/paymentMethods.ts

@@ -51,5 +51,8 @@ export async function setDefaultPaymentMethod(
   _ctx: RunCtx,
   _opts: { stripeAccountId: string; paymentMethodId: string },
 ) {
-  throwStripeError("PAYMENT_METHOD_FAILED", "[better-stripe] setDefaultPaymentMethod is not yet implemented for V2 Accounts. Use createBillingPortalSession() to let users manage payment methods.");
+  throwStripeError(
+    "PAYMENT_METHOD_FAILED",
+    "[better-stripe] setDefaultPaymentMethod is not yet implemented for V2 Accounts. Use createBillingPortalSession() to let users manage payment methods.",
+  );
 }

package/src/client/connect/refundActor.ts

@@ -19,8 +19,7 @@ import type { SplitRecipientRole } from "../../component/lib/fees.js";
 
 /** Who is initiating a refund. `accountId` is the seller's `acct_…` id. */
 export type RefundActor =
-  | { type: "admin" }
-  | { type: "seller"; accountId: string };
+  { type: "admin" } | { type: "seller"; accountId: string };
 
 /**
  * The subset of a payment's routing needed to authorize a seller refund, read