@fantastic.dev/better-stripe 0.8.1 → 0.10.0

package/src/client/settlement/verifiedSale.test.ts

@@ -0,0 +1,139 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import { getVerifiedSale } from "./verifiedSale.js";
+function fixture() {
+  const payment = {
+    id: "pi_1",
+    status: "succeeded",
+    currency: "usd",
+    amount_received: 10000,
+    metadata: { seller: "store" },
+    latest_charge: {
+      id: "ch_1",
+      amount: 10000,
+      currency: "usd",
+      amount_refunded: 0,
+      disputed: false,
+      balance_transaction: { currency: "usd", fee: 320 },
+    },
+  };
+  const raw = {
+    paymentIntents: { retrieve: vi.fn().mockResolvedValue(payment) },
+    subscriptions: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "sub_1",
+        metadata: { ref: "a" },
+        items: {
+          data: [{ price: { id: "price_current", product: "prod_current" } }],
+        },
+      }),
+    },
+    invoices: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "in_1",
+        status: "paid",
+        amount_paid: 10000,
+        currency: "usd",
+        parent: { subscription_details: { subscription: "sub_1" } },
+      }),
+    },
+    invoicePayments: {
+      list: vi.fn().mockResolvedValue({
+        data: [{ status: "paid", payment: { payment_intent: "pi_1" } }],
+        has_more: false,
+      }),
+    },
+  };
+  return { payment, raw, stripe: raw as unknown as Stripe };
+}
+it("returns actual fees, verified invoice linkage and current price instead of stale metadata", async () => {
+  const { stripe, raw } = fixture();
+  expect(
+    await getVerifiedSale(stripe, {
+      paymentIntentId: "pi_1",
+      subscriptionId: "sub_1",
+      invoiceId: "in_1",
+    }),
+  ).toMatchObject({
+    status: "ready",
+    chargeId: "ch_1",
+    processingFee: 320,
+    currency: "usd",
+    stripePriceId: "price_current",
+    stripeProductId: "prod_current",
+    invoiceId: "in_1",
+  });
+  expect(raw.paymentIntents.retrieve).toHaveBeenCalledWith("pi_1", {
+    expand: ["latest_charge.balance_transaction"],
+  });
+});
+it("reports missing fees and unsuccessful payments as non-ready, never zero fees", async () => {
+  const { stripe, raw, payment } = fixture();
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    latest_charge: { ...payment.latest_charge, balance_transaction: null },
+  });
+  expect(await getVerifiedSale(stripe, { paymentIntentId: "pi_1" })).toEqual({
+    status: "pending",
+    reason: "processing_fee_unavailable",
+    retryable: true,
+  });
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    status: "requires_payment_method",
+  });
+  expect(
+    await getVerifiedSale(stripe, { paymentIntentId: "pi_1" }),
+  ).toMatchObject({ status: "not_payable", retryable: false });
+});
+it("rejects mismatched currencies and unrelated invoice payments", async () => {
+  const { stripe, raw, payment } = fixture();
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    latest_charge: {
+      ...payment.latest_charge,
+      balance_transaction: { currency: "eur", fee: 320 },
+    },
+  });
+  await expect(
+    getVerifiedSale(stripe, { paymentIntentId: "pi_1" }),
+  ).rejects.toThrow();
+  raw.paymentIntents.retrieve.mockResolvedValue(payment);
+  raw.invoicePayments.list.mockResolvedValue({
+    data: [{ status: "paid", payment: { payment_intent: "pi_other" } }],
+    has_more: false,
+  });
+  await expect(
+    getVerifiedSale(stripe, {
+      paymentIntentId: "pi_1",
+      invoiceId: "in_1",
+      subscriptionId: "sub_1",
+    }),
+  ).rejects.toThrow();
+});
+it("marks processing payments as retryable without paying recipients", async () => {
+  const { stripe, raw, payment } = fixture();
+  raw.paymentIntents.retrieve.mockResolvedValue({
+    ...payment,
+    status: "processing",
+  });
+  expect(await getVerifiedSale(stripe, { paymentIntentId: "pi_1" })).toEqual({
+    status: "pending",
+    reason: "payment_processing",
+    retryable: true,
+  });
+});
+
+it("refuses partial invoice payments rather than awarding a fixed commission more than once", async () => {
+  const { stripe, raw } = fixture();
+  raw.invoices.retrieve.mockResolvedValue({
+    id: "in_1",
+    status: "paid",
+    amount_paid: 20000,
+    currency: "usd",
+    parent: { subscription_details: { subscription: "sub_1" } },
+  });
+  await expect(
+    getVerifiedSale(stripe, { paymentIntentId: "pi_1", invoiceId: "in_1" }),
+  ).rejects.toThrow("Partial invoice payments");
+});

package/src/client/settlement/verifiedSale.ts

@@ -0,0 +1,159 @@
+import type Stripe from "stripe";
+import { isBetterStripeError, throwStripeError } from "../errors.js";
+export type VerifiedSaleOptions = {
+  paymentIntentId: string;
+  subscriptionId?: string;
+  invoiceId?: string;
+};
+export type VerifiedSale =
+  | { status: "pending" | "not_payable"; reason: string; retryable: boolean }
+  | {
+      status: "ready";
+      paymentIntentId: string;
+      chargeId: string;
+      gross: number;
+      processingFee: number;
+      currency: string;
+      metadata: Record<string, string>;
+      invoiceId?: string;
+      subscriptionId?: string;
+      stripePriceId?: string;
+      stripeProductId?: string;
+    };
+const id = (value: string | { id: string } | null | undefined) =>
+  typeof value === "string" ? value : value?.id;
+export async function getVerifiedSale(
+  stripe: Stripe,
+  opts: VerifiedSaleOptions,
+): Promise<VerifiedSale> {
+  try {
+    const payment = await stripe.paymentIntents.retrieve(opts.paymentIntentId, {
+      expand: ["latest_charge.balance_transaction"],
+    });
+    if (payment.status === "processing")
+      return {
+        status: "pending",
+        reason: "payment_processing",
+        retryable: true,
+      };
+    if (payment.status !== "succeeded")
+      return {
+        status: "not_payable",
+        reason: "payment_not_succeeded",
+        retryable: false,
+      };
+    const charge = payment.latest_charge;
+    if (!charge || typeof charge === "string")
+      return {
+        status: "pending",
+        reason: "charge_unavailable",
+        retryable: true,
+      };
+    if (charge.amount_refunded > 0 || charge.disputed)
+      return {
+        status: "not_payable",
+        reason: "charge_refunded_or_disputed",
+        retryable: false,
+      };
+    const balance = charge.balance_transaction;
+    if (!balance || typeof balance === "string")
+      return {
+        status: "pending",
+        reason: "processing_fee_unavailable",
+        retryable: true,
+      };
+    if (
+      balance.currency !== payment.currency ||
+      charge.currency !== payment.currency
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Settlement currency must match the payment and processing currency.",
+      );
+    if (
+      ![payment.amount_received, balance.fee].every(Number.isSafeInteger) ||
+      balance.fee < 0 ||
+      balance.fee > payment.amount_received ||
+      charge.amount !== payment.amount_received
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Unsupported payment or processing amounts.",
+      );
+    if (opts.subscriptionId && !opts.invoiceId)
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Subscription settlement requires a paid invoice.",
+      );
+    const invoice = opts.invoiceId
+      ? await stripe.invoices.retrieve(opts.invoiceId)
+      : null;
+    if (invoice && invoice.status !== "paid")
+      return { status: "pending", reason: "invoice_not_paid", retryable: true };
+    const subscriptionId = id(
+      invoice?.parent?.subscription_details?.subscription,
+    );
+    if (
+      invoice &&
+      (invoice.currency !== payment.currency ||
+        (opts.subscriptionId && subscriptionId !== opts.subscriptionId))
+    )
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Invoice currency or subscription does not match settlement.",
+      );
+    if (invoice) {
+      if (invoice.amount_paid !== payment.amount_received)
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "Partial invoice payments require an explicitly resolved invoice allocation.",
+        );
+      const linked = await stripe.invoicePayments.list({
+        invoice: invoice.id,
+        limit: 100,
+        status: "paid",
+        payment: { type: "payment_intent", payment_intent: payment.id },
+      });
+      if (
+        !linked.data.some(
+          (row) =>
+            row.status === "paid" &&
+            id(row.payment.payment_intent) === payment.id,
+        )
+      )
+        throwStripeError(
+          "INVALID_CONFIGURATION",
+          "Payment does not belong to this paid invoice.",
+        );
+    }
+    const subscription = subscriptionId
+      ? await stripe.subscriptions.retrieve(subscriptionId)
+      : null;
+    if (subscription && subscription.items.data.length !== 1)
+      throwStripeError(
+        "INVALID_CONFIGURATION",
+        "Resolve multi-price subscription allocations explicitly.",
+      );
+    const price = subscription?.items.data[0]?.price;
+    const metadata = subscription?.metadata ?? payment.metadata;
+    return {
+      status: "ready",
+      paymentIntentId: payment.id,
+      chargeId: charge.id,
+      gross: payment.amount_received,
+      processingFee: balance.fee,
+      currency: payment.currency,
+      metadata,
+      invoiceId: invoice?.id,
+      subscriptionId,
+      stripePriceId: price?.id ?? metadata.stripePriceId,
+      stripeProductId: id(price?.product) ?? metadata.stripeProductId,
+    };
+  } catch (error) {
+    if (isBetterStripeError(error)) throw error;
+    throwStripeError(
+      "STRIPE_API_ERROR",
+      "Could not retrieve verified sale context.",
+    );
+  }
+}

package/src/client/webhooks/asyncHooks.ts

@@ -0,0 +1,38 @@
+import type { AsyncHooks, AsyncHookCtx } from "../types.js";
+import type { AsyncHookName } from "../types/triggers.js";
+/** Route async webhook hooks through the shared public callback contract. */
+export function buildAsyncHookRoutes(hooks: AsyncHooks | undefined) {
+  const routes: Record<
+    AsyncHookName,
+    ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined
+  > = {
+    afterAccountUpdated: hooks?.onAccountUpdated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterCheckoutCompleted: hooks?.onCheckoutCompleted as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterSubscriptionUpdated: hooks?.onSubscriptionUpdated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterSubscriptionCanceled: hooks?.onSubscriptionCanceled as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterTrialEnding: hooks?.onTrialEnding as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterInvoicePaid: hooks?.onInvoicePaid as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterInvoicePaymentFailed: hooks?.onInvoicePaymentFailed as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterPaymentSucceeded: hooks?.onPaymentSucceeded as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterPaymentFailed: hooks?.onPaymentFailed as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterPayoutCompleted: hooks?.onPayoutCompleted as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterRefundCreated: hooks?.onRefundCreated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterDisputeCreated: hooks?.onDisputeCreated as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+    afterDisputeClosed: hooks?.onDisputeClosed as
+      ((ctx: AsyncHookCtx, doc: unknown) => Promise<void>) | undefined,
+  };
+
+  return routes;
+}

package/src/client/webhooks/processors.test.ts

@@ -1,8 +1,4 @@
 // @vitest-environment edge-runtime
-/**
- * Drives Stripe event normalization through processEvent and checks the payloads
- * passed to component mutations, including owner, fee, and trial fields.
- */
 import type Stripe from "stripe";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -12,7 +8,6 @@ import { processEvent } from "./processors.js";
 
 const TO_REF = Symbol.for("toReferencePath");
 
-/** Fake component exposing every query/mutation ref processors.ts resolves. */
 function makeComponent() {
   const refs = (namespace: string, names: string[]) =>
     Object.fromEntries(
@@ -44,12 +39,16 @@ function makeCtx(opts?: { query?: unknown; queryThrows?: boolean }) {
   const runQuery = vi.fn();
   if (opts?.queryThrows) runQuery.mockRejectedValue(new Error("not found"));
   else runQuery.mockResolvedValue(opts?.query ?? null);
-  // `claimReversalSlices` returns the slices the reversal engines execute
-  // (BTS-63). Fake only its storage: the slice math is the REAL shared
-  // computeReversalSlices, applied to this ctx's ledger legs.
+  // Fake claim storage; use the shared reversal sizing math.
   const runMutation = vi.fn(
     async (ref: Record<symbol, string>, args: Record<string, unknown>) => {
       const path = ref?.[TO_REF] ?? "";
+      if (
+        String(path).endsWith(
+          "settlement/mutations/reserveSettlementAllocation",
+        )
+      )
+        return args;
       if (!String(path).endsWith("connect/mutations/claimReversalSlices")) {
         return undefined;
       }
@@ -107,7 +106,9 @@ function makeStripe() {
       update: vi.fn().mockResolvedValue({}),
       retrieve: vi.fn(),
     },
+    charges: { retrieve: vi.fn().mockResolvedValue({ created: 1 }) },
     transfers: {
+      list: vi.fn().mockResolvedValue({ data: [], has_more: false }),
       create: vi.fn(async (_params: unknown) => ({
         id: `tr_${++trCreateSeq}`,
       })),
@@ -146,7 +147,6 @@ function makeStripe() {
       retrieve: vi.fn(),
       update: vi.fn().mockResolvedValue({}),
     },
-    charges: { retrieve: vi.fn() },
   };
 }
 

package/src/component/_generated/api.ts

@@ -25,6 +25,8 @@ import type * as lib_stripeFactory from "../lib/stripeFactory.js";
 import type * as products_mutations from "../products/mutations.js";
 import type * as products_queries from "../products/queries.js";
 import type * as products_validators from "../products/validators.js";
+import type * as settlement_mutations from "../settlement/mutations.js";
+import type * as settlement_queries from "../settlement/queries.js";
 import type * as webhooks_mutations from "../webhooks/mutations.js";
 import type * as webhooks_queries from "../webhooks/queries.js";
 import type * as webhooks_validators from "../webhooks/validators.js";
@@ -54,6 +56,8 @@ const fullApi: ApiFromModules<{
   "products/mutations": typeof products_mutations;
   "products/queries": typeof products_queries;
   "products/validators": typeof products_validators;
+  "settlement/mutations": typeof settlement_mutations;
+  "settlement/queries": typeof settlement_queries;
   "webhooks/mutations": typeof webhooks_mutations;
   "webhooks/queries": typeof webhooks_queries;
   "webhooks/validators": typeof webhooks_validators;

package/src/component/_generated/component.ts

@@ -611,6 +611,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             destinationAccountId?: string;
             feeCollectedAmount?: number;
             feeRefundedAmount?: number;
+            isCollectionPaused?: boolean;
             isTrialing: boolean;
             metadata?: any;
             orgId?: string;
@@ -1339,6 +1340,46 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           }>,
           Name
         >;
+        paginateTransfersByAccount: FunctionReference<
+          "query",
+          "internal",
+          {
+            destinationAccountId: string;
+            paginationOpts: {
+              cursor: string | null;
+              endCursor?: string | null;
+              id?: number;
+              maximumBytesRead?: number;
+              maximumRowsRead?: number;
+              numItems: number;
+            };
+          },
+          {
+            continueCursor: string;
+            isDone: boolean;
+            page: Array<{
+              _creationTime: number;
+              _id: string;
+              amount: number;
+              currency: string;
+              destinationAccountId: string;
+              metadata?: any;
+              paymentId?: string;
+              reinstatement?: boolean;
+              reversalClaimedAmount?: number;
+              reversalStatus?: "partially_reversed" | "fully_reversed";
+              reversedAmount?: number;
+              role?: "store" | "affiliate" | "other";
+              sourceChargeId?: string;
+              sourceInvoiceId?: string;
+              status: "pending" | "paid" | "failed" | "reversed";
+              stripeTransferId: string;
+            }>;
+            pageStatus?: "SplitRecommended" | "SplitRequired" | null;
+            splitCursor?: string | null;
+          },
+          Name
+        >;
       };
     };
     core: {
@@ -1722,6 +1763,106 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         >;
       };
     };
+    settlement: {
+      mutations: {
+        claimCommissionInvoice: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            affiliateAccountId?: string;
+            firstPaidInvoiceId: string;
+            invoiceId: string;
+            subscriptionId: string;
+            term: "forever" | "one_time";
+          },
+          {
+            claimKey: string;
+            eligible: boolean;
+            firstPaidInvoiceId: string;
+            replay: boolean;
+            term: "forever" | "one_time";
+          },
+          Name
+        >;
+        reserveSettlementAllocation: FunctionReference<
+          "mutation",
+          "internal",
+          {
+            adjustmentAmount?: number;
+            currency: string;
+            gross: number;
+            paymentId?: string;
+            paymentIntentId?: string;
+            platformNet: number;
+            processingFee: number;
+            sourceChargeId: string;
+            sourceInvoiceId?: string;
+            transfers: Array<{
+              amount: number;
+              destinationAccountId: string;
+              role: "store" | "affiliate" | "other";
+            }>;
+          },
+          {
+            _creationTime: number;
+            _id: string;
+            adjustmentAmount?: number;
+            currency: string;
+            gross: number;
+            paymentId?: string;
+            paymentIntentId?: string;
+            platformNet: number;
+            processingFee: number;
+            sourceChargeId: string;
+            sourceInvoiceId?: string;
+            transfers: Array<{
+              amount: number;
+              destinationAccountId: string;
+              role: "store" | "affiliate" | "other";
+            }>;
+          },
+          Name
+        >;
+      };
+      queries: {
+        getCommissionTerm: FunctionReference<
+          "query",
+          "internal",
+          { subscriptionId: string },
+          {
+            affiliateAccountId?: string;
+            firstPaidInvoiceId: string;
+            subscriptionId: string;
+            term: "forever" | "one_time";
+          } | null,
+          Name
+        >;
+        getSettlementAllocation: FunctionReference<
+          "query",
+          "internal",
+          { sourceChargeId: string },
+          {
+            _creationTime: number;
+            _id: string;
+            adjustmentAmount?: number;
+            currency: string;
+            gross: number;
+            paymentId?: string;
+            paymentIntentId?: string;
+            platformNet: number;
+            processingFee: number;
+            sourceChargeId: string;
+            sourceInvoiceId?: string;
+            transfers: Array<{
+              amount: number;
+              destinationAccountId: string;
+              role: "store" | "affiliate" | "other";
+            }>;
+          } | null,
+          Name
+        >;
+      };
+    };
     webhooks: {
       mutations: {
         insertWebhookEvent: FunctionReference<

package/src/component/connect/queries.ts

@@ -1,4 +1,10 @@
 import { v } from "convex/values";
+import { paginator } from "convex-helpers/server/pagination";
+import schema from "../schema.js";
+import {
+  paginationOptsValidator,
+  paginationResultValidator,
+} from "convex/server";
 
 import type { Doc } from "../_generated/dataModel";
 import { query } from "../_generated/server";
@@ -343,6 +349,23 @@ export const listTransfersByAccount = query({
   },
 });
 
+/** Newest transfers for a recipient, with bounded cursor pagination. */
+export const paginateTransfersByAccount = query({
+  args: {
+    destinationAccountId: v.string(),
+    paginationOpts: paginationOptsValidator,
+  },
+  returns: paginationResultValidator(transferDocValidator),
+  handler: (ctx, args) =>
+    paginator(ctx.db, schema)
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.destinationAccountId),
+      )
+      .order("desc")
+      .paginate(args.paginationOpts),
+});
+
 // =============================================================================
 // REVERSAL-CLAIM RECLAIM (BTS-74) — ops diagnostics for wedged legs
 // =============================================================================
@@ -442,7 +465,7 @@ export const listWedgedReversalClaims = query({
  * Exact earnings totals for one connected account (BTS-64): `gross` (sum of all
  * transfer amounts, incl. reinstatements — the earnings view) and `reversed`
  * (sum of all `reversedAmount`), iterated to completion so totals are never
- * capped. `transfers` is a bounded preview (`previewLimit ?? 50` rows) for
+ * capped. `transfers` is a newest-first bounded preview (`previewLimit ?? 50` rows) for
  * drill-down; use `gross`/`reversed`/`transferCount` for the money figures.
  */
 export const getAccountEarnings = query({
@@ -467,7 +490,8 @@ export const getAccountEarnings = query({
       .query("transfers")
       .withIndex("by_destination_account_id", (q) =>
         q.eq("destinationAccountId", args.destinationAccountId),
-      )) {
+      )
+      .order("desc")) {
       gross += tr.amount;
       reversed += tr.reversedAmount ?? 0;
       transferCount += 1;

package/src/component/earnings-totals.test.ts

@@ -50,6 +50,18 @@ describe("getAccountEarnings — exact totals past the 50-row cap (BTS-64)", ()
     expect(result.transferCount).toBe(120);
     // The preview is still bounded (drill-down rows), but the totals are exact.
     expect(result.transfers.length).toBe(50);
+    expect(result.transfers[0].stripeTransferId).toBe("tr_big_119");
+    expect(
+      result.transfers.some((row) => row.stripeTransferId === "tr_big_0"),
+    ).toBe(false);
+    const newest = await t.query(api.connect.queries.getAccountEarnings, {
+      destinationAccountId: "acct_big",
+      previewLimit: 1,
+    });
+    expect(newest.transfers.map((row) => row.stripeTransferId)).toEqual([
+      "tr_big_119",
+    ]);
+    expect(newest.gross).toBe(12000);
   });
 
   it("returns exact totals and all rows for a small account (regression)", async () => {
@@ -208,6 +220,7 @@ describe("aggregate read-limit failures (BTS-116)", () => {
       "Too many documents read in a single function execution",
     );
     const rows = {
+      order: () => rows,
       async *[Symbol.asyncIterator]() {
         yield { amount: 100, reversedAmount: 10, status: "paid" };
         throw readLimit;

package/src/component/schema.ts

@@ -1,3 +1,8 @@
+import {
+  allocationsTable,
+  commissionTermsTable,
+  commissionDecisionsTable,
+} from "./settlement/schema";
 import { defineSchema } from "convex/server";
 
 import {
@@ -19,6 +24,9 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  settlementAllocations: allocationsTable,
+  commissionTerms: commissionTermsTable,
+  commissionDecisions: commissionDecisionsTable,
   // Core
   accounts: accountsTable,