@fantastic.dev/better-stripe 0.21.0 → 0.23.0

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

@@ -0,0 +1,421 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference } from "convex/server";
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import schema from "../../component/schema.js";
+import type { Component, RunCtx } from "../helpers.js";
+import { releaseRecipientPayout } from "./payoutExecution.js";
+import { adoptRecipientPayouts } from "./payoutAdoption.js";
+const modules = import.meta.glob("../../component/**/*.*s");
+const symbol = Symbol.for("toReferencePath");
+const component = {
+  payoutPolicy: {
+    queries: { get: { [symbol]: "betterStripe/payoutPolicy/queries/get" } },
+  },
+} as unknown as Component;
+const scope = {
+  accountId: "acct_recipient",
+  ownerKey: "owner",
+  operationKey: "release-1",
+  currency: "usd",
+  independentLiabilities: 0,
+};
+async function setup(amounts = [600, 400]) {
+  const t = convexTest(schema, modules);
+  await t.run(async (ctx) => {
+    await ctx.db.insert("payoutPolicies", {
+      accountId: scope.accountId,
+      ownerKey: scope.ownerKey,
+      mode: "stripe_managed",
+      status: "ready",
+      revision: 0,
+      operationKey: "enable",
+      country: "US",
+      thresholds: [],
+      holdDeadline: Date.now() + 86400000,
+    });
+    for (let i = 0; i < amounts.length; i++)
+      await ctx.db.insert("transfers", {
+        stripeTransferId: `tr_${i}`,
+        destinationAccountId: scope.accountId,
+        sourceChargeId: `ch_${i}`,
+        amount: amounts[i],
+        currency: "usd",
+        status: "paid",
+        role: i % 2 ? "affiliate" : "store",
+      });
+  });
+  const path = (ref: Record<symbol, string>) =>
+    ref[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
+  const ctx = {
+    runQuery: (ref: Record<symbol, string>, args: never) =>
+      t.query(makeFunctionReference<"query">(path(ref)), args),
+    runMutation: (ref: Record<symbol, string>, args: never) =>
+      t.mutation(makeFunctionReference<"mutation">(path(ref)), args),
+  } as unknown as RunCtx;
+  let transactions = amounts.map((amount, i) => ({
+    id: `txn_${i}`,
+    source: `py_${i}`,
+    amount,
+    fee: 0,
+    net: amount,
+    currency: "usd",
+    created: 100,
+    available_on: 200,
+    status: "available",
+    type: "payment",
+    exchange_rate: null,
+  }));
+  let payout: Record<string, unknown> | undefined;
+  const provider = {
+    accounts: {
+      listExternalAccounts: vi.fn(async () => ({
+        data: [
+          {
+            id: "ba_one",
+            object: "bank_account",
+            currency: "usd",
+            default_for_currency: true,
+          },
+        ],
+        has_more: false,
+      })),
+    },
+    transfers: {
+      retrieve: vi.fn(async (id: string) => {
+        const i = Number(id.slice(3));
+        return {
+          id,
+          destination: scope.accountId,
+          destination_payment: `py_${i}`,
+          source_transaction: `ch_${i}`,
+          amount: amounts[i],
+          currency: "usd",
+          amount_reversed: 0,
+        };
+      }),
+      listReversals: vi.fn(async () => ({ data: [], has_more: false })),
+    },
+    charges: {
+      retrieve: vi.fn(async (id: string) => {
+        const i = Number(id.slice(3));
+        return {
+          id,
+          source_transfer: `tr_${i}`,
+          amount: amounts[i],
+          currency: "usd",
+          paid: true,
+          status: "succeeded",
+          balance_transaction: `txn_${i}`,
+        };
+      }),
+    },
+    balanceTransactions: {
+      list: vi.fn(async (params: { source?: string; limit?: number }) => ({
+        data: params.source
+          ? transactions.filter((t) => t.source === params.source)
+          : transactions.slice(0, params.limit),
+        has_more: false,
+      })),
+      retrieve: vi.fn(async (id: string) =>
+        transactions.find((t) => t.id === id),
+      ),
+    },
+    balance: {
+      retrieve: vi.fn(async () => ({
+        available: [
+          {
+            currency: "usd",
+            amount: transactions
+              .filter((t) => t.status === "available")
+              .reduce((a, t) => a + t.net, 0),
+            source_types: {
+              card: transactions
+                .filter((t) => t.status === "available")
+                .reduce((a, t) => a + t.net, 0),
+            },
+          },
+        ],
+        pending: [],
+      })),
+    },
+    payouts: {
+      list: vi.fn(async () => ({
+        data: payout ? [payout] : [],
+        has_more: false,
+      })),
+      retrieve: vi.fn(async () => payout),
+      create: vi.fn(
+        async (params: {
+          amount: number;
+          currency: string;
+          metadata: object;
+        }) => {
+          payout = {
+            id: "po_one",
+            ...params,
+            status: "paid",
+            automatic: false,
+            method: "standard",
+            type: "bank_account",
+            source_type: "card",
+            destination: "ba_one",
+            created: Math.floor(Date.now() / 1000),
+            arrival_date: Math.floor(Date.now() / 1000),
+            balance_transaction: "txn_debit",
+            failure_balance_transaction: null,
+            reversed_by: null,
+          };
+          transactions = [
+            {
+              id: "txn_debit",
+              source: "po_one",
+              amount: -params.amount,
+              fee: 0,
+              net: -params.amount,
+              currency: "usd",
+              created: Math.floor(Date.now() / 1000),
+              available_on: Math.floor(Date.now() / 1000),
+              status: "available",
+              type: "payout",
+              exchange_rate: null,
+            },
+            ...transactions,
+          ];
+          return payout;
+        },
+      ),
+    },
+  };
+  const verify = vi.fn(async () => ({
+    status: "verified" as const,
+    policy: (await t.run((ctx) => ctx.db.query("payoutPolicies").first()))!,
+  }));
+  const run = (extra = {}) =>
+    releaseRecipientPayout(
+      provider as unknown as Stripe,
+      component,
+      ctx,
+      { ...scope, ...extra },
+      verify,
+    );
+  return {
+    t,
+    ctx,
+    provider,
+    verify,
+    run,
+    setTransactions: (rows: typeof transactions) => {
+      transactions = rows;
+    },
+    transactions: () => transactions,
+  };
+}
+async function historical() {
+  const s = await setup();
+  await s.provider.payouts.create({
+    amount: 1000,
+    currency: "usd",
+    metadata: {},
+  });
+  s.provider.payouts.create.mockClear();
+  const opts = {
+    accountId: scope.accountId,
+    ownerKey: scope.ownerKey,
+    currency: "usd",
+    expectedRevision: 0,
+    payouts: [
+      {
+        stripePayoutId: "po_one",
+        allocations: [
+          { stripeTransferId: "tr_0", amount: 600 },
+          { stripeTransferId: "tr_1", amount: 400 },
+        ],
+      },
+    ],
+  };
+  const adopt = (extra = {}) =>
+    adoptRecipientPayouts(s.provider as unknown as Stripe, component, s.ctx, {
+      ...opts,
+      ...extra,
+    });
+  return { ...s, adopt, opts };
+}
+it("imports a verified historical manual payout with exact source allocations", async () => {
+  const s = await historical();
+  expect(await s.adopt()).toMatchObject({
+    status: "adopted",
+    claims: [{ historical: true, status: "paid", amount: 1000 }],
+  });
+  await s.adopt();
+  expect(s.provider.payouts.create).not.toHaveBeenCalled();
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toMatchObject([
+    { paidAmount: 600, reservedAmount: 0 },
+    { paidAmount: 400, reservedAmount: 0 },
+  ]);
+});
+it("requires explicit historical allocations instead of inferring ownership from balance", async () => {
+  const s = await historical();
+  expect(await s.adopt({ payouts: [] })).toMatchObject({
+    status: "held",
+    reason: "historical_allocation_required",
+  });
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+});
+it("rejects unavailable funding without writing any partial import", async () => {
+  const s = await historical();
+  s.setTransactions(
+    s
+      .transactions()
+      .map((t) =>
+        t.source === "py_1"
+          ? { ...t, available_on: Math.floor(Date.now() / 1000) + 100 }
+          : t,
+      ),
+  );
+  await expect(s.adopt()).rejects.toThrow(/funding/i);
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutReleaseClaims").collect()),
+  ).toEqual([]);
+});
+it("holds unrelated history before writing source allocations", async () => {
+  const s = await historical();
+  s.setTransactions([
+    ...s.transactions(),
+    { ...s.transactions()[0], id: "txn_unowned", source: "po_unknown" },
+  ]);
+  expect(await s.adopt()).toMatchObject({
+    status: "held",
+    reason: "unallocated_history",
+  });
+  expect(
+    await s.t.run((ctx) => ctx.db.query("payoutSourceAllocations").collect()),
+  ).toEqual([]);
+});
+async function activation() {
+  const s = await setup();
+  const now = Math.floor(Date.now() / 1000);
+  s.setTransactions(
+    s
+      .transactions()
+      .map((t) => ({ ...t, created: now - 100, available_on: now - 50 })),
+  );
+  let schedule: Record<string, unknown> = {
+    interval: "weekly",
+    weekly_payout_days: ["monday"],
+  };
+  const settings = {
+    retrieve: vi.fn(async () => ({
+      payments: { payouts: { status: "enabled", schedule } },
+    })),
+    update: vi.fn(
+      async (args: {
+        payments: { payouts: { schedule: Record<string, unknown> } };
+      }) => {
+        schedule = args.payments.payouts.schedule;
+        return { payments: { payouts: { status: "enabled", schedule } } };
+      },
+    ),
+  };
+  Object.assign(s.provider, {
+    v2: {
+      core: {
+        accounts: {
+          retrieve: vi.fn(async () => ({
+            id: scope.accountId,
+            dashboard: "none",
+            identity: { country: "US" },
+          })),
+        },
+      },
+    },
+    balanceSettings: settings,
+  });
+  const { PayoutPolicyClient } = await import("../payoutPolicy.js");
+  const client = new PayoutPolicyClient(
+    component,
+    () => s.provider as unknown as Stripe,
+  );
+  const opts = {
+    accountId: scope.accountId,
+    ownerKey: scope.ownerKey,
+    operationKey: "activate",
+    expectedRevision: 0,
+    mode: "custom" as const,
+    thresholds: [{ currency: "usd", amount: 1000 }],
+    consent: true as const,
+    adoptExistingBalance: true as const,
+  };
+  return { ...s, client, settings, opts };
+}
+it("explicit funded activation verifies complete history, then releases through the public package", async () => {
+  const s = await activation();
+  expect(await s.client.prepare(s.ctx, s.opts)).toMatchObject({
+    status: "prepared",
+    operation: { adoption: { oldestHeldAt: expect.any(Number) } },
+  });
+  expect(
+    await s.client.apply(s.ctx, { ...scope, operationKey: "activate" }),
+  ).toMatchObject({ status: "ready" });
+  expect(await s.client.release(s.ctx, scope)).toMatchObject({
+    status: "updated",
+    claim: { status: "paid", amount: 1000 },
+  });
+  expect(s.provider.payouts.create).toHaveBeenCalledTimes(1);
+});
+it("new unallocated provider history before a delayed attempt cancels activation safely", async () => {
+  const s = await activation();
+  await s.client.prepare(s.ctx, s.opts);
+  s.setTransactions([
+    ...s.transactions(),
+    {
+      ...s.transactions()[0],
+      id: "txn_unknown",
+      source: "py_unknown",
+      amount: 10,
+      net: 10,
+    },
+  ]);
+  expect(
+    await s.client.apply(s.ctx, { ...scope, operationKey: "activate" }),
+  ).toMatchObject({
+    status: "migration_required",
+    adoptionReason: "unallocated_history",
+  });
+  expect(s.settings.update).not.toHaveBeenCalled();
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+  });
+});
+it("funded activation remains explicit", async () => {
+  const s = await activation();
+  expect(
+    await s.client.prepare(s.ctx, {
+      ...s.opts,
+      adoptExistingBalance: undefined,
+    }),
+  ).toMatchObject({ status: "migration_required", reason: "existing_balance" });
+  expect(s.settings.update).not.toHaveBeenCalled();
+});
+it("cannot restart the holding period for already-expired funds", async () => {
+  const s = await activation();
+  s.setTransactions(
+    s.transactions().map((t) => ({ ...t, created: 100, available_on: 200 })),
+  );
+  expect(await s.client.prepare(s.ctx, s.opts)).toMatchObject({
+    status: "migration_required",
+    adoptionReason: "holding_deadline_expired",
+  });
+  expect(await s.client.get(s.ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+    revision: 0,
+  });
+  expect(s.settings.update).not.toHaveBeenCalled();
+});