@fantastic.dev/better-stripe 0.21.0 → 0.22.0

package/src/component/_generated/component.ts

@@ -2494,6 +2494,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
             observations: Array<{
@@ -2542,6 +2543,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
             observations: Array<{
@@ -2578,6 +2580,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           {
             accountId: string;
             currency: string;
+            destinationId?: string;
             expectedRevision: number;
             independentLiabilities: number;
             observations: Array<{
@@ -2607,6 +2610,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               currency: string;
               debitFee?: number;
               debitTransactionId?: string;
+              destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
               observations: Array<{
@@ -2678,6 +2682,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
             observations: Array<{
@@ -2732,6 +2737,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
             observations: Array<{
@@ -2789,6 +2795,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             currency: string;
             debitFee?: number;
             debitTransactionId?: string;
+            destinationId?: string;
             expectedRevision: number;
             feeRevision?: number;
             observations: Array<{
@@ -2851,6 +2858,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               currency: string;
               debitFee?: number;
               debitTransactionId?: string;
+              destinationId?: string;
               expectedRevision: number;
               feeRevision?: number;
               observations: Array<{
@@ -2882,6 +2890,78 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           },
           Name
         >;
+        snapshot: FunctionReference<
+          "query",
+          "internal",
+          { accountId: string; ownerKey: string },
+          | { reason: "snapshot_limit"; status: "held" }
+          | {
+              claims: Array<{
+                _creationTime: number;
+                _id: string;
+                accountId: string;
+                allocations: Array<{
+                  amount: number;
+                  role?: "store" | "affiliate" | "other";
+                  stripeTransferId: string;
+                }>;
+                amount: number;
+                attemptedAt?: number;
+                currency: string;
+                debitFee?: number;
+                debitTransactionId?: string;
+                destinationId?: string;
+                expectedRevision: number;
+                feeRevision?: number;
+                observations: Array<{
+                  currency: string;
+                  ledgerFingerprint: string;
+                  matureNet: number;
+                  observedAt: number;
+                  pendingCredits: number;
+                  stripeTransferId: string;
+                  transactionIds: Array<string>;
+                }>;
+                operationKey: string;
+                ownerKey: string;
+                providerFee?: number;
+                rejection?: {
+                  code: "balance_insufficient" | "amount_too_small";
+                  requestId: string;
+                };
+                returnTransactionId?: string;
+                status:
+                  | "reserved"
+                  | "submitted"
+                  | "paid"
+                  | "returned"
+                  | "canceled"
+                  | "rejected";
+                stripePayoutId?: string;
+              }>;
+              status: "ready";
+              transfers: 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;
+                totalsRecorded?: true;
+              }>;
+            },
+          Name
+        >;
       };
     };
     products: {

package/src/component/payout-release-snapshot.test.ts

@@ -0,0 +1,57 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "./schema.js";
+const modules = import.meta.glob("./**/*.*s");
+const snapshot = makeFunctionReference<"query">(
+  "payoutRelease/queries:snapshot",
+);
+const scope = { accountId: "acct_recipient", ownerKey: "owner" };
+async function setup(count = 2) {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("payoutPolicies", {
+      ...scope,
+      mode: "custom",
+      status: "ready",
+      revision: 0,
+      operationKey: "enable",
+      thresholds: [{ currency: "usd", amount: 1000 }],
+      country: "US",
+      previousSchedule: { interval: "daily" },
+      holdDeadline: Date.now() + 86400000,
+    });
+    for (let i = 0; i < count; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: scope.accountId,
+        amount: 500,
+        currency: "usd",
+        status: "paid",
+        role: i % 2 ? "affiliate" : "store",
+      });
+  });
+  return t;
+}
+it("returns complete source membership and historical claims for the owned account", async () => {
+  const t = await setup();
+  expect(await t.query(snapshot, scope)).toMatchObject({
+    status: "ready",
+    transfers: [{ stripeTransferId: "tr_0" }, { stripeTransferId: "tr_1" }],
+    claims: [],
+  });
+});
+it("holds an account exceeding the atomic claim bound rather than qualifying a partial page", async () => {
+  const t = await setup(101);
+  expect(await t.query(snapshot, scope)).toEqual({
+    status: "held",
+    reason: "snapshot_limit",
+  });
+});
+it("rejects another owner", async () => {
+  const t = await setup();
+  await expect(
+    t.query(snapshot, { ...scope, ownerKey: "other" }),
+  ).rejects.toThrow(/owner/i);
+});

package/src/component/payoutRelease/mutations.ts

@@ -31,6 +31,7 @@ export const claim = mutation({
     ...identity,
     expectedRevision: v.number(),
     currency: v.string(),
+    destinationId: v.optional(v.string()),
     providerAvailable: v.number(),
     independentLiabilities: v.number(),
     observations: v.array(observation),
@@ -38,11 +39,17 @@ export const claim = mutation({
   returns: v.union(claimDoc, held),
   handler: async (ctx, args) => {
     validateIdentity(args);
+    if (
+      args.destinationId !== undefined &&
+      !/^ba_\w+$/.test(args.destinationId)
+    )
+      throw new Error("Invalid payout bank destination.");
     const existing = await claimByKey(ctx, args);
     if (existing) {
       if (
         existing.currency !== args.currency ||
-        existing.expectedRevision !== args.expectedRevision
+        existing.expectedRevision !== args.expectedRevision ||
+        existing.destinationId !== args.destinationId
       )
         throw new Error("Payout claim identity cannot be reused.");
       return existing;
@@ -122,6 +129,7 @@ export const claim = mutation({
       expectedRevision: args.expectedRevision,
       currency: args.currency,
       amount: plan.amount,
+      ...(args.destinationId ? { destinationId: args.destinationId } : {}),
       allocations: plan.allocations,
       observations: args.observations,
       feeRevision: fees?.revision ?? 0,

package/src/component/payoutRelease/queries.ts

@@ -1,3 +1,4 @@
+import { transferDocValidator } from "../connect/validators.js";
 import { readFees } from "./fees.js";
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
@@ -65,3 +66,37 @@ export const fees = query({
     return { amount: balance?.amount ?? 0, revision: balance?.revision ?? 0 };
   },
 });
+
+/** Complete bounded input for package qualification. Partial membership never qualifies. */
+export const snapshot = query({
+  args: { accountId: v.string(), ownerKey: v.string() },
+  returns: v.union(
+    v.object({
+      status: v.literal("held"),
+      reason: v.literal("snapshot_limit"),
+    }),
+    v.object({
+      status: v.literal("ready"),
+      transfers: v.array(transferDocValidator),
+      claims: v.array(claimDoc),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    await readPolicy(ctx, args);
+    const transfers = await ctx.db
+      .query("transfers")
+      .withIndex("by_destination_account_id", (q) =>
+        q.eq("destinationAccountId", args.accountId),
+      )
+      .take(101);
+    const claims = await ctx.db
+      .query("payoutReleaseClaims")
+      .withIndex("by_account_status", (q) => q.eq("accountId", args.accountId))
+      .take(101);
+    if (transfers.length > 100 || claims.length > 100)
+      return { status: "held" as const, reason: "snapshot_limit" as const };
+    if (claims.some((c) => c.ownerKey !== args.ownerKey))
+      throw new Error("Payout history owner does not match.");
+    return { status: "ready" as const, transfers, claims };
+  },
+});

package/src/component/payoutRelease/schema.ts

@@ -23,6 +23,7 @@ export const claimFields = {
   expectedRevision: v.number(),
   currency: v.string(),
   amount: v.number(),
+  destinationId: v.optional(v.string()),
   allocations: v.array(allocation),
   observations: v.array(observation),
   status: v.union(