@fantastic.dev/better-stripe 0.15.0 → 0.16.0

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.15.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/connect/payoutSnapshot.test.ts

@@ -89,3 +89,30 @@ it("reports bounded upcoming previews and not-ready accounts explicitly", async
     reason: "account_unavailable",
   });
 });
+
+it("exposes optional provider failure details in history", async () => {
+  const stripe = {
+    balance: { retrieve: async () => ({ available: [], pending: [] }) },
+    payouts: {
+      list: async (args: { status?: string }) => ({
+        data: args.status
+          ? []
+          : [
+              {
+                ...payout("po_failed", "failed"),
+                failure_code: "account_closed",
+                failure_message: "Bank account closed",
+              },
+            ],
+        has_more: false,
+      }),
+    },
+  };
+  const result = await getPayoutSnapshot(stripe as unknown as Stripe, {
+    stripeAccountId: "acct_a",
+  });
+  expect(result.payouts[0]).toMatchObject({
+    failureCode: "account_closed",
+    failureMessage: "Bank account closed",
+  });
+});

package/src/client/connect/payoutSnapshot.ts

@@ -8,6 +8,8 @@ export type RecipientPayoutRow = {
   status: string;
   arrivalDate: number | null;
   created: number;
+  failureCode?: string;
+  failureMessage?: string;
 };
 export type RecipientPayoutSnapshot = {
   balances: AccountBalance[];
@@ -31,6 +33,8 @@ const row = (p: Stripe.Payout): RecipientPayoutRow => ({
   status: p.status,
   arrivalDate: p.arrival_date ? p.arrival_date * 1000 : null,
   created: p.created * 1000,
+  ...(p.failure_code != null ? { failureCode: p.failure_code } : {}),
+  ...(p.failure_message != null ? { failureMessage: p.failure_message } : {}),
 });
 /** Account-scoped live balance and cursor history. Upcoming truncation is explicit. */
 export async function getPayoutSnapshot(

package/src/client/index.ts

@@ -2,6 +2,7 @@ import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js"
 export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
 import * as intentsImpl from "./billing/intents.js";
 export type * from "./billing/intents.js";
+import { ReadContractClient } from "./readContracts.js";
 import { CostRecoveryClient } from "./costRecovery.js";
 export * from "./charge-currency.js";
 export * from "./costRecovery.js";
@@ -107,7 +108,7 @@ export type { RefundActor } from "./connect/refunds.js";
 import type { RefundActor } from "./connect/refunds.js";
 export type { AccountBalance } from "./connect/payouts.js";
 export type { WedgedReversalClaim } from "./connect/transfers.js";
-import type { Component, RunCtx } from "./helpers.js";
+import type { RunCtx } from "./helpers.js";
 import { getStripeClient } from "./helpers.js";
 import type {
   V2AccountRetrieveInclude,
@@ -210,8 +211,7 @@ export type BetterStripeComponent = ComponentApi;
 
 // BETTER STRIPE CLIENT
 
-export class BetterStripe {
-  public component: Component;
+export class BetterStripe extends ReadContractClient {
   readonly stripeApiVersion: SupportedStripeApiVersion;
   private _apiKey?: string;
   private _triggers?: SyncTriggers;
@@ -220,7 +220,7 @@ export class BetterStripe {
   private _statementDescriptorSuffix?: string;
 
   constructor(component: BetterStripeComponent, options?: BetterStripeOptions) {
-    this.component = component;
+    super(component);
     this.stripeApiVersion = resolveStripeApiVersion(options?.stripeApiVersion);
     this._apiKey = options?.STRIPE_SECRET_KEY;
     this._triggers = options?.triggers;

package/src/client/readContracts.ts

@@ -0,0 +1,90 @@
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { PaginationOptions, PaginationResult } from "convex/server";
+import type { Component, RunCtx } from "./helpers.js";
+import type { PayoutStatus } from "../component/connect/validators.js";
+import type {
+  StripeComponentPayout,
+  StripeComponentProduct,
+  StripeComponentPrice,
+} from "./types/documents.js";
+import { componentRef } from "./webhooks/helpers.js";
+/** Shared component readers inherited by BetterStripe. */
+export class ReadContractClient {
+  constructor(public component: Component) {}
+  async paginateProducts(
+    ctx: RunCtx,
+    opts: {
+      accountId?: string;
+      active?: boolean;
+      paginationOpts: PaginationOptions;
+    },
+  ): Promise<PaginationResult<StripeComponentProduct>> {
+    return ctx.runQuery(
+      componentRef(this.component, "products/queries/paginateProducts"),
+      opts,
+    );
+  }
+  async paginatePrices(
+    ctx: RunCtx,
+    opts: {
+      productId?: string;
+      active?: boolean;
+      paginationOpts: PaginationOptions;
+    },
+  ): Promise<PaginationResult<StripeComponentPrice>> {
+    return ctx.runQuery(
+      componentRef(this.component, "products/queries/paginatePrices"),
+      opts,
+    );
+  }
+  async paginatePayouts(
+    ctx: RunCtx,
+    opts: {
+      accountId: string;
+      status?: PayoutStatus;
+      paginationOpts: PaginationOptions;
+    },
+  ): Promise<PaginationResult<StripeComponentPayout>> {
+    return ctx.runQuery(
+      componentRef(this.component, "connect/queries/paginatePayouts"),
+      opts,
+    );
+  }
+
+  async getAccountEarningsByCurrency(
+    ctx: RunCtx,
+    opts: { destinationAccountId: string; previewLimit?: number },
+  ): Promise<{
+    totals: {
+      currency: string;
+      gross: number;
+      reversed: number;
+      net: number;
+      transferCount: number;
+    }[];
+    transfers: ComponentApi["connect"]["queries"]["getAccountEarningsByCurrency"]["_returnType"]["transfers"];
+  }> {
+    return ctx.runQuery(
+      componentRef(
+        this.component,
+        "connect/queries/getAccountEarningsByCurrency",
+      ),
+      opts,
+    );
+  }
+  async getAccountPayoutsByCurrency(
+    ctx: RunCtx,
+    opts: { accountId: string; previewLimit?: number },
+  ): Promise<{
+    totals: { currency: string; paidOut: number; payoutCount: number }[];
+    payouts: StripeComponentPayout[];
+  }> {
+    return ctx.runQuery(
+      componentRef(
+        this.component,
+        "connect/queries/getAccountPayoutsByCurrency",
+      ),
+      opts,
+    );
+  }
+}

package/src/client/readPagination.test.ts

@@ -0,0 +1,62 @@
+import { expect, it, vi } from "vitest";
+import { BetterStripe } from "./index.js";
+import { components } from "./setup.test.js";
+it("forwards typed component cursors and account scope through public readers", async () => {
+  const bs = new BetterStripe(components.betterStripe, {
+    STRIPE_SECRET_KEY: "sk_test_reader_fixture",
+  });
+  const page = { page: [], isDone: true, continueCursor: "end" };
+  const ctx = { runQuery: vi.fn().mockResolvedValue(page) };
+  const paginationOpts = { numItems: 10, cursor: "opaque" };
+  expect(
+    await bs.paginatePayouts(ctx, {
+      accountId: "acct_a",
+      status: "paid",
+      paginationOpts,
+    }),
+  ).toBe(page);
+  expect(ctx.runQuery).toHaveBeenLastCalledWith(
+    components.betterStripe.connect.queries.paginatePayouts,
+    { accountId: "acct_a", status: "paid", paginationOpts },
+  );
+  expect(
+    await bs.paginateProducts(ctx, {
+      accountId: "acct_a",
+      active: true,
+      paginationOpts,
+    }),
+  ).toBe(page);
+  expect(ctx.runQuery).toHaveBeenLastCalledWith(
+    components.betterStripe.products.queries.paginateProducts,
+    { accountId: "acct_a", active: true, paginationOpts },
+  );
+  expect(
+    await bs.paginatePrices(ctx, {
+      productId: "prod_a",
+      active: false,
+      paginationOpts,
+    }),
+  ).toBe(page);
+  expect(ctx.runQuery).toHaveBeenLastCalledWith(
+    components.betterStripe.products.queries.paginatePrices,
+    { productId: "prod_a", active: false, paginationOpts },
+  );
+});
+it("forwards exact currency summary reads through the public client", async () => {
+  const bs = new BetterStripe(components.betterStripe);
+  const ctx = { runQuery: vi.fn().mockResolvedValue({ totals: [] }) };
+  expect(
+    await bs.getAccountEarningsByCurrency(ctx, {
+      destinationAccountId: "acct_a",
+    }),
+  ).toEqual({ totals: [] });
+  expect(ctx.runQuery).toHaveBeenLastCalledWith(
+    components.betterStripe.connect.queries.getAccountEarningsByCurrency,
+    { destinationAccountId: "acct_a" },
+  );
+  await bs.getAccountPayoutsByCurrency(ctx, { accountId: "acct_a" });
+  expect(ctx.runQuery).toHaveBeenLastCalledWith(
+    components.betterStripe.connect.queries.getAccountPayoutsByCurrency,
+    { accountId: "acct_a" },
+  );
+});

package/src/client/types/documents.ts

@@ -124,6 +124,8 @@ export type StripeComponentPayout = {
   status: PayoutStatus;
   arrivalDate?: string;
   method?: string;
+  failureCode?: string;
+  failureMessage?: string;
   metadata?: Record<string, unknown>;
 };
 

package/src/client/webhooks/payout-canceled.integration.test.ts

@@ -190,3 +190,28 @@ it.each([
     expect(transport).not.toHaveBeenCalled();
   },
 );
+
+it("persists signed failure details and clears them on a later snapshot", async () => {
+  const f = fixture("payout.failed", "failed");
+  f.event.data.object.failure_code = "account_closed";
+  f.event.data.object.failure_message = "Bank account closed";
+  expect((await f.deliver()).status).toBe(200);
+  const failed = await f.payout();
+  expect(failed).toMatchObject({
+    failureCode: "account_closed",
+    failureMessage: "Bank account closed",
+    accountId: "acct_qa_recipient",
+  });
+  expect((await f.deliver()).body).toMatchObject({ deduplicated: true });
+  expect(await f.payout()).toEqual(failed);
+  f.event.id = "evt_failure_cleared";
+  f.event.type = "payout.updated";
+  f.event.data.object.status = "pending";
+  f.event.data.object.failure_code = null;
+  f.event.data.object.failure_message = null;
+  expect((await f.deliver()).status).toBe(200);
+  const cleared = await f.payout();
+  expect(cleared?._id).toBe(failed?._id);
+  expect(cleared).not.toHaveProperty("failureCode");
+  expect(cleared).not.toHaveProperty("failureMessage");
+});

package/src/client/webhooks/processors.ts

@@ -921,6 +921,8 @@ async function handlePayoutEvent(
       "pending" | "paid" | "failed" | "canceled" | "in_transit",
     arrivalDate: epochToIso(payout.arrival_date),
     method: payout.method ?? undefined,
+    failureCode: payout.failure_code ?? undefined,
+    failureMessage: payout.failure_message ?? undefined,
     metadata: payout.metadata ?? undefined,
   });
 }

package/src/component/_generated/api.ts

@@ -24,6 +24,10 @@ import type * as costRecovery_imports from "../costRecovery/imports.js";
 import type * as costRecovery_mutations from "../costRecovery/mutations.js";
 import type * as costRecovery_queries from "../costRecovery/queries.js";
 import type * as costRecovery_reservations from "../costRecovery/reservations.js";
+import type * as earnings_legacyReads from "../earnings/legacyReads.js";
+import type * as earnings_mutations from "../earnings/mutations.js";
+import type * as earnings_reads from "../earnings/reads.js";
+import type * as earnings_triggers from "../earnings/triggers.js";
 import type * as lib_fees from "../lib/fees.js";
 import type * as lib_idempotency from "../lib/idempotency.js";
 import type * as lib_paymentSeller from "../lib/paymentSeller.js";
@@ -62,6 +66,10 @@ const fullApi: ApiFromModules<{
   "costRecovery/mutations": typeof costRecovery_mutations;
   "costRecovery/queries": typeof costRecovery_queries;
   "costRecovery/reservations": typeof costRecovery_reservations;
+  "earnings/legacyReads": typeof earnings_legacyReads;
+  "earnings/mutations": typeof earnings_mutations;
+  "earnings/reads": typeof earnings_reads;
+  "earnings/triggers": typeof earnings_triggers;
   "lib/fees": typeof lib_fees;
   "lib/idempotency": typeof lib_idempotency;
   "lib/paymentSeller": typeof lib_paymentSeller;