@fantastic.dev/better-stripe 0.8.1 → 0.10.0

package/src/client/index.ts

@@ -1,3 +1,37 @@
+export type {
+  CheckoutSessionReadOptions,
+  SubscriptionReadOptions,
+  CouponReadOptions,
+} from "./billing/providerReads.js";
+import * as providerReads from "./billing/providerReads.js";
+export type { CreateAccountOptions } from "./core/accounts.js";
+import { buildAsyncHookRoutes } from "./webhooks/asyncHooks.js";
+import * as saleContextImpl from "./settlement/verifiedSale.js";
+import * as settlementImpl from "./settlement/settleSale.js";
+import * as commissionImpl from "./settlement/commissions.js";
+import * as payoutSnapshotImpl from "./connect/payoutSnapshot.js";
+export { allocateSale } from "./settlement/allocation.js";
+export type {
+  SaleAllocation,
+  SaleAllocationOptions,
+} from "./settlement/allocation.js";
+export type {
+  VerifiedSale,
+  VerifiedSaleOptions,
+} from "./settlement/verifiedSale.js";
+export type { SettleSaleOptions } from "./settlement/settleSale.js";
+export type { SettlementResult } from "./settlement/execution.js";
+export type {
+  CommissionTerm,
+  CommissionSelectionOptions,
+  CommissionSelection,
+  CommissionDecision,
+} from "./settlement/commissions.js";
+export type {
+  RecipientPayoutSnapshot,
+  RecipientPayoutRow,
+  PayoutSnapshotOptions,
+} from "./connect/payoutSnapshot.js";
 import { internalActionGeneric, internalMutationGeneric } from "convex/server";
 import { v } from "convex/values";
 import Stripe from "stripe";
@@ -146,9 +180,7 @@ function clonePlatformFee(config: PlatformFeeConfig): PlatformFeeConfig {
   };
 }
 
-// =============================================================================
 // BETTER STRIPE CLIENT
-// =============================================================================
 
 export class BetterStripe {
   public component: Component;
@@ -212,9 +244,7 @@ export class BetterStripe {
     return getStripeClient(this.apiKey, apiVersion);
   }
 
-  // ============================================================================
   // Static defaults (preserved for backwards compatibility)
-  // ============================================================================
 
   static DEFAULT_ACCOUNT_CONFIGURATION =
     accountsImpl.DEFAULT_ACCOUNT_CONFIGURATION;
@@ -222,21 +252,9 @@ export class BetterStripe {
   static DEFAULT_CUSTOMER_CONFIGURATION =
     accountsImpl.DEFAULT_CUSTOMER_CONFIGURATION;
 
-  // ============================================================================
   // ACCOUNT METHODS
-  // ============================================================================
 
-  async createAccount(
-    ctx: RunCtx,
-    opts: {
-      userId: string;
-      email?: string;
-      name?: string;
-      country?: string;
-      orgId?: string;
-      metadata?: Record<string, string>;
-    },
-  ) {
+  async createAccount(ctx: RunCtx, opts: accountsImpl.CreateAccountOptions) {
     return accountsImpl.createAccount(this.stripe(), this.component, ctx, opts);
   }
 
@@ -276,14 +294,7 @@ export class BetterStripe {
 
   async getOrCreateAccount(
     ctx: RunCtx,
-    opts: {
-      userId: string;
-      email?: string;
-      name?: string;
-      country?: string;
-      orgId?: string;
-      metadata?: Record<string, string>;
-    },
+    opts: accountsImpl.CreateAccountOptions,
   ) {
     return accountsImpl.getOrCreateAccount(
       this.stripe(),
@@ -453,14 +464,7 @@ export class BetterStripe {
    */
   async ensureCustomerAccount(
     ctx: RunCtx,
-    opts: {
-      userId: string;
-      email?: string;
-      name?: string;
-      country?: string;
-      orgId?: string;
-      metadata?: Record<string, string>;
-    },
+    opts: accountsImpl.CreateAccountOptions,
   ) {
     return accountsImpl.ensureCustomerAccount(
       this.stripe(),
@@ -470,9 +474,7 @@ export class BetterStripe {
     );
   }
 
-  // ============================================================================
   // PRODUCT METHODS
-  // ============================================================================
 
   async createProduct(
     ctx: RunCtx,
@@ -559,9 +561,7 @@ export class BetterStripe {
     return productsImpl.deleteProduct(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // PRICE METHODS
-  // ============================================================================
 
   async createPrice(
     ctx: RunCtx,
@@ -649,13 +649,12 @@ export class BetterStripe {
     return pricesImpl.listStripePrices(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // CHECKOUT METHODS
-  // ============================================================================
 
   async createCheckoutSession(
     ctx: RunCtx,
     opts: {
+      idempotencyKey?: string;
       userId: string;
       orgId?: string;
       stripePriceId: string;
@@ -744,9 +743,7 @@ export class BetterStripe {
     return checkoutImpl.updateCheckoutSession(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // SUBSCRIPTION METHODS
-  // ============================================================================
 
   /**
    * Create a subscription directly for a V2 buyer (`customer_account`), off the
@@ -943,14 +940,7 @@ export class BetterStripe {
       accountId?: string;
       userId: string;
       orgId?: string;
-      status:
-        | "active"
-        | "trialing"
-        | "past_due"
-        | "canceled"
-        | "incomplete"
-        | "unpaid"
-        | "paused";
+      status: SubscriptionStatus;
       priceId?: string;
       quantity?: number;
       currentPeriodStart?: string;
@@ -970,9 +960,7 @@ export class BetterStripe {
     return subscriptionsImpl.getTrialStatus(this.component, ctx, opts);
   }
 
-  // ============================================================================
   // INVOICE METHODS
-  // ============================================================================
 
   async listInvoices(
     ctx: RunCtx,
@@ -1039,9 +1027,7 @@ export class BetterStripe {
     return invoicesImpl.getInvoiceFromStripe(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // PAYMENT METHOD METHODS
-  // ============================================================================
 
   async listPaymentMethods(
     ctx: RunCtx,
@@ -1072,9 +1058,7 @@ export class BetterStripe {
     return paymentMethodsImpl.setDefaultPaymentMethod(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // ACCOUNT LINK METHODS
-  // ============================================================================
 
   async createAccountLink(
     ctx: RunCtx,
@@ -1150,9 +1134,7 @@ export class BetterStripe {
     return accountLinksImpl.getCountrySpecs(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // PAYOUT METHODS
-  // ============================================================================
 
   async createPayout(
     ctx: RunCtx,
@@ -1253,6 +1235,50 @@ export class BetterStripe {
    * (`{ available, pending, currency }`, minor units) per currency — each entry
    * feeds the headless `PayoutSchedule` component's `balance` prop directly.
    */
+  async getCheckoutSessionFromStripe(
+    _ctx: RunCtx,
+    opts: providerReads.CheckoutSessionReadOptions,
+  ) {
+    return providerReads.getCheckoutSessionFromStripe(this.stripe(), opts);
+  }
+  async getSubscriptionFromStripe(
+    _ctx: RunCtx,
+    opts: providerReads.SubscriptionReadOptions,
+  ) {
+    return providerReads.getSubscriptionFromStripe(this.stripe(), opts);
+  }
+  async getCouponFromStripe(
+    _ctx: RunCtx,
+    opts: providerReads.CouponReadOptions,
+  ) {
+    return providerReads.getCouponFromStripe(this.stripe(), opts);
+  }
+  async getVerifiedSale(
+    _ctx: RunCtx,
+    opts: saleContextImpl.VerifiedSaleOptions,
+  ) {
+    return saleContextImpl.getVerifiedSale(this.stripe(), opts);
+  }
+  async settleSale(ctx: RunCtx, opts: settlementImpl.SettleSaleOptions) {
+    return settlementImpl.settleSale(this.stripe(), this.component, ctx, opts);
+  }
+  async selectCommissionInvoice(
+    ctx: RunCtx,
+    opts: commissionImpl.CommissionSelectionOptions,
+  ) {
+    return commissionImpl.selectCommissionInvoice(
+      this.stripe(),
+      this.component,
+      ctx,
+      opts,
+    );
+  }
+  async getPayoutSnapshot(
+    _ctx: RunCtx,
+    opts: payoutSnapshotImpl.PayoutSnapshotOptions,
+  ) {
+    return payoutSnapshotImpl.getPayoutSnapshot(this.stripe(), opts);
+  }
   async getAccountBalance(_ctx: RunCtx, opts: { stripeAccountId: string }) {
     return payoutsImpl.getAccountBalance(this.stripe(), opts);
   }
@@ -1268,9 +1294,7 @@ export class BetterStripe {
     return payoutsImpl.listPayouts(this.component, ctx, opts);
   }
 
-  // ============================================================================
   // REFUND METHODS
-  // ============================================================================
 
   /**
    * Issue a refund (BTS-34). `refundApplicationFee` and `reverseTransfer`
@@ -1325,9 +1349,7 @@ export class BetterStripe {
     return refundsImpl.listRefunds(this.component, ctx, opts);
   }
 
-  // ============================================================================
   // DISPUTE METHODS
-  // ============================================================================
 
   async getDisputeByStripeId(
     ctx: RunCtx,
@@ -1397,9 +1419,7 @@ export class BetterStripe {
     return disputesImpl.closeDispute(this.stripe(), this.component, ctx, opts);
   }
 
-  // ============================================================================
   // WEBHOOK ENDPOINT MANAGEMENT
-  // ============================================================================
 
   async listWebhookEndpoints(ctx: RunCtx, opts?: { limit?: number }) {
     return webhookEndpointsImpl.listWebhookEndpoints(this.stripe(), ctx, opts);
@@ -1439,9 +1459,7 @@ export class BetterStripe {
     return webhookEndpointsImpl.setupEventDestination(this.stripe(), ctx, opts);
   }
 
-  // ============================================================================
   // WEBHOOK EVENT QUERIES
-  // ============================================================================
 
   async listWebhookEvents(
     ctx: RunCtx,
@@ -1462,17 +1480,13 @@ export class BetterStripe {
     }>;
   }
 
-  // ============================================================================
   // DATA MANAGEMENT
-  // ============================================================================
 
   async clearAll(ctx: RunCtx): Promise<{ cleared: number; tables: string[] }> {
     return dataImpl.clearAll(this.component, ctx);
   }
 
-  // ============================================================================
   // SYNC METHODS
-  // ============================================================================
 
   async syncAllAccounts(ctx: RunCtx) {
     return accountsImpl.syncAllAccounts(this.stripe(), this.component, ctx);
@@ -1490,9 +1504,7 @@ export class BetterStripe {
     );
   }
 
-  // ============================================================================
   // WEBHOOK HANDLER EXPORT (BetterAuth-style)
-  // ============================================================================
 
   /**
    * Build the two webhook handler function definitions for the app to export
@@ -1811,38 +1823,7 @@ export class BetterStripe {
         ),
     };
 
-    /** One routing entry per async hook — identical mapping to the old API. */
-    const ASYNC: 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,
-    };
+    const ASYNC = buildAsyncHookRoutes(hooks);
 
     const syncWebhook = internalMutationGeneric({
       args: { dispatcher: v.string(), data: v.any() },

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

@@ -0,0 +1,98 @@
+import { expect, it } from "vitest";
+import { allocateSale } from "./allocation.js";
+it("allocates processing and plan fees before affiliate and collaborators", () => {
+  const result = allocateSale({
+    gross: 10000,
+    processingFee: 320,
+    feeBasisPoints: 900,
+    creatorAccountId: "acct_creator",
+    affiliate: { destinationAccountId: "acct_affiliate", basisPoints: 2000 },
+    collaborators: [{ destinationAccountId: "acct_other", basisPoints: 2500 }],
+  });
+  expect(result).toMatchObject({
+    sellingFee: 900,
+    platformNet: 580,
+    affiliateNet: 1820,
+    creatorNet: 5460,
+    collaboratorNet: 1820,
+  });
+  expect(
+    result.transfers.reduce((n, t) => n + t.amount, 0) + result.sellingFee,
+  ).toBe(result.gross);
+});
+it("caps fixed commissions and applies the processing fee floor", () => {
+  expect(
+    allocateSale({
+      gross: 10000,
+      processingFee: 700,
+      feeBasisPoints: 490,
+      creatorAccountId: "acct_creator",
+      affiliate: { destinationAccountId: "acct_a", fixedAmount: 99999 },
+    }),
+  ).toMatchObject({ affiliateNet: 9300, creatorNet: 0, platformNet: 0 });
+  expect(
+    allocateSale({
+      gross: 12900,
+      processingFee: 404,
+      feeBasisPoints: 490,
+      creatorAccountId: "acct_c",
+      affiliate: { destinationAccountId: "acct_a", basisPoints: 2000 },
+    }),
+  ).toMatchObject({ affiliateNet: 2453, creatorNet: 9815 });
+});
+it("retains rounding residue for the creator and rejects invalid or duplicate shares", () => {
+  const opts = {
+    gross: 101,
+    processingFee: 0,
+    creatorAccountId: "acct_c",
+    collaborators: [
+      { destinationAccountId: "acct_a", basisPoints: 3333 },
+      { destinationAccountId: "acct_b", basisPoints: 3333 },
+    ],
+  };
+  expect(allocateSale(opts)).toMatchObject({
+    creatorNet: 35,
+    collaboratorNet: 66,
+    affiliateNet: 0,
+  });
+  expect(() =>
+    allocateSale({
+      ...opts,
+      collaborators: [{ destinationAccountId: "acct_a", basisPoints: 10001 }],
+    }),
+  ).toThrow();
+  expect(() =>
+    allocateSale({
+      ...opts,
+      collaborators: [opts.collaborators[0], opts.collaborators[0]],
+    }),
+  ).toThrow();
+  expect(() => allocateSale({ ...opts, gross: 1.5 })).toThrow();
+  expect(() =>
+    allocateSale({
+      ...opts,
+      affiliate: {
+        destinationAccountId: "acct_z",
+        fixedAmount: 1,
+        basisPoints: 1,
+      },
+    }),
+  ).toThrow();
+});
+it("supports zero-dollar previews and zero affiliate shares", () => {
+  expect(
+    allocateSale({
+      gross: 0,
+      processingFee: 0,
+      creatorAccountId: "acct_creator",
+    }),
+  ).toMatchObject({ gross: 0, creatorNet: 0, affiliateNet: 0, platformNet: 0 });
+  expect(
+    allocateSale({
+      gross: 100,
+      processingFee: 3,
+      creatorAccountId: "acct_creator",
+      affiliate: { destinationAccountId: "acct_a", basisPoints: 0 },
+    }),
+  ).toMatchObject({ creatorNet: 97, affiliateNet: 0 });
+});

package/src/client/settlement/allocation.ts

@@ -0,0 +1,110 @@
+import type { SplitTransfer } from "../core/fees.js";
+export type SaleAllocationOptions = {
+  gross: number;
+  processingFee: number;
+  /** Inclusive sale fee, with actual Stripe processing as its floor. */
+  feeBasisPoints?: number | null;
+  creatorAccountId: string;
+  affiliate?: {
+    destinationAccountId: string;
+    basisPoints?: number;
+    fixedAmount?: number;
+  };
+  collaborators?: { destinationAccountId: string; basisPoints: number }[];
+};
+export type SaleAllocation = {
+  gross: number;
+  processingFee: number;
+  sellingFee: number;
+  platformNet: number;
+  affiliateNet: number;
+  creatorNet: number;
+  collaboratorNet: number;
+  transfers: SplitTransfer[];
+};
+const basisPoints = (n: number) => {
+  if (!Number.isSafeInteger(n) || n < 0 || n > 10000)
+    throw new Error("Share must be an integer from 0 to 10000 basis points.");
+  return n;
+};
+const units = (n: number) => {
+  if (!Number.isSafeInteger(n) || n < 0)
+    throw new Error(
+      "Amounts must be non-negative safe integer currency units.",
+    );
+  return n;
+};
+const share = (amount: number, rate: number) =>
+  Number((BigInt(amount) * BigInt(basisPoints(rate))) / 10000n);
+/** Pure fee-first allocation. Fixed amounts are minor units of the sale currency. */
+export function allocateSale(opts: SaleAllocationOptions): SaleAllocation {
+  const gross = units(opts.gross),
+    processingFee = units(opts.processingFee);
+  if (processingFee > gross || !opts.creatorAccountId)
+    throw new Error("Invalid gross amount, processing fee or creator account.");
+  const rate = basisPoints(opts.feeBasisPoints ?? 0);
+  const sellingFee = Math.max(
+    processingFee,
+    Number((BigInt(gross) * BigInt(rate) + 5000n) / 10000n),
+  );
+  const net = gross - sellingFee;
+  const affiliate = opts.affiliate;
+  if (
+    affiliate &&
+    (!affiliate.destinationAccountId ||
+      (affiliate.fixedAmount !== undefined &&
+        affiliate.basisPoints !== undefined))
+  )
+    throw new Error(
+      "Choose one affiliate amount or percentage and a destination.",
+    );
+  const affiliateNet = affiliate
+    ? Math.min(
+        net,
+        affiliate.fixedAmount !== undefined
+          ? units(affiliate.fixedAmount)
+          : share(net, affiliate.basisPoints ?? 0),
+      )
+    : 0;
+  const creatorRemainder = net - affiliateNet;
+  const collaborators = opts.collaborators ?? [];
+  if (
+    collaborators.reduce((sum, r) => sum + basisPoints(r.basisPoints), 0) >
+    10000
+  )
+    throw new Error("Collaborator shares exceed the creator remainder.");
+  const seen = new Set<string>();
+  const transfers: SplitTransfer[] = collaborators.map((r) => {
+    if (!r.destinationAccountId || seen.has(r.destinationAccountId))
+      throw new Error("Collaborator destinations must be nonempty and unique.");
+    seen.add(r.destinationAccountId);
+    return {
+      destinationAccountId: r.destinationAccountId,
+      role: "other",
+      amount: share(creatorRemainder, r.basisPoints),
+    };
+  });
+  const collaboratorNet = transfers.reduce((sum, r) => sum + r.amount, 0);
+  const creatorNet = creatorRemainder - collaboratorNet;
+  transfers.unshift({
+    destinationAccountId: opts.creatorAccountId,
+    role: "store",
+    amount: creatorNet,
+  });
+  if (affiliate)
+    transfers.push({
+      destinationAccountId: affiliate.destinationAccountId,
+      role: "affiliate",
+      amount: affiliateNet,
+    });
+  return {
+    gross,
+    processingFee,
+    sellingFee,
+    platformNet: sellingFee - processingFee,
+    affiliateNet,
+    creatorNet,
+    collaboratorNet,
+    transfers,
+  };
+}

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

@@ -0,0 +1,103 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import type { Component, RunCtx } from "../helpers.js";
+import { selectCommissionInvoice } from "./commissions.js";
+const ref = (path: string) => ({
+  [Symbol.for("toReferencePath")]: `betterStripe/${path}`,
+});
+const component = {
+  settlement: {
+    commissions: {
+      get: ref("settlement/queries/getCommissionTerm"),
+      claim: ref("settlement/mutations/claimCommissionInvoice"),
+    },
+  },
+} as unknown as Component;
+it("finds the first paid nonzero invoice across provider pages and ignores trial invoices", async () => {
+  const list = vi
+    .fn()
+    .mockResolvedValueOnce({
+      data: [
+        {
+          id: "in_later",
+          amount_paid: 100,
+          status_transitions: { paid_at: 20 },
+          created: 20,
+        },
+        {
+          id: "in_trial",
+          amount_paid: 0,
+          status_transitions: { paid_at: 1 },
+          created: 1,
+        },
+      ],
+      has_more: true,
+    })
+    .mockResolvedValueOnce({
+      data: [
+        {
+          id: "in_first",
+          amount_paid: 100,
+          status_transitions: { paid_at: 10 },
+          created: 2,
+        },
+      ],
+      has_more: false,
+    });
+  const raw = {
+    invoices: {
+      list,
+      retrieve: vi.fn().mockResolvedValue({
+        id: "in_later",
+        status: "paid",
+        amount_paid: 100,
+        parent: { subscription_details: { subscription: "sub_1" } },
+      }),
+    },
+  };
+  const runMutation = vi.fn(async (_ref, args) => ({
+    ...args,
+    eligible: false,
+    replay: false,
+    claimKey: "key",
+  }));
+  const ctx = {
+    runQuery: vi.fn().mockResolvedValue(null),
+    runMutation,
+  } as unknown as RunCtx;
+  await selectCommissionInvoice(raw as unknown as Stripe, component, ctx, {
+    subscriptionId: "sub_1",
+    invoiceId: "in_later",
+    affiliateAccountId: "acct_a",
+    term: "one_time",
+  });
+  expect(runMutation).toHaveBeenCalledWith(
+    expect.anything(),
+    expect.objectContaining({
+      firstPaidInvoiceId: "in_first",
+      term: "one_time",
+    }),
+  );
+  expect(list).toHaveBeenCalledTimes(2);
+});
+it("does not consume a failed or zero-dollar invoice", async () => {
+  const raw = {
+    invoices: {
+      retrieve: vi.fn().mockResolvedValue({
+        id: "in_trial",
+        status: "paid",
+        amount_paid: 0,
+        parent: { subscription_details: { subscription: "sub_1" } },
+      }),
+    },
+  };
+  const mutation = vi.fn(),
+    ctx = { runQuery: vi.fn(), runMutation: mutation } as unknown as RunCtx;
+  expect(
+    await selectCommissionInvoice(raw as unknown as Stripe, component, ctx, {
+      subscriptionId: "sub_1",
+      invoiceId: "in_trial",
+    }),
+  ).toMatchObject({ status: "not_payable", eligible: false });
+  expect(mutation).not.toHaveBeenCalled();
+});