@fantastic.dev/better-stripe 0.20.1 → 0.21.0

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

@@ -0,0 +1,312 @@
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { getRecipientPayoutReceipt } from "./payoutReceipt.js";
+const scope = { accountId: "acct_recipient", stripePayoutId: "po_one" };
+const timestamp = Math.floor(Date.now() / 1000) - 10;
+const payout = (extra = {}) => ({
+  id: "po_one",
+  object: "payout",
+  amount: 1000,
+  currency: "usd",
+  status: "paid",
+  automatic: false,
+  method: "standard",
+  type: "bank_account",
+  source_type: "card",
+  balance_transaction: "txn_debit",
+  failure_balance_transaction: null,
+  reversed_by: null,
+  destination: "ba_one",
+  created: timestamp,
+  arrival_date: timestamp + 86400,
+  metadata: {},
+  ...extra,
+});
+const transaction = (extra = {}) => ({
+  id: "txn_debit",
+  source: "po_one",
+  amount: -1000,
+  fee: 0,
+  net: -1000,
+  currency: "usd",
+  status: "available",
+  available_on: timestamp,
+  created: timestamp,
+  type: "payout",
+  ...extra,
+});
+function setup(extra = {}, debit = {}, credit = {}) {
+  const provider = {
+    payouts: { retrieve: vi.fn().mockResolvedValue(payout(extra)) },
+    balanceTransactions: {
+      retrieve: vi.fn(async (id: string) =>
+        id === "txn_debit"
+          ? transaction(debit)
+          : transaction({
+              id: "txn_return",
+              amount: 1000,
+              net: 1000,
+              type: "payout_failure",
+              ...credit,
+            }),
+      ),
+    },
+  };
+  return {
+    provider,
+    read: (options = scope) =>
+      getRecipientPayoutReceipt(provider as unknown as Stripe, options),
+  };
+}
+it("verifies a paid manual bank payout against its actual scoped debit", async () => {
+  const { provider, read } = setup();
+  expect(await read()).toMatchObject({
+    status: "ready",
+    ...scope,
+    amount: 1000,
+    currency: "usd",
+    providerStatus: "paid",
+    automatic: false,
+    returnedPrincipal: 0,
+    returnedNet: 0,
+    debit: { id: "txn_debit", amount: -1000, net: -1000, fee: 0 },
+  });
+  expect(provider.payouts.retrieve).toHaveBeenNthCalledWith(
+    1,
+    "po_one",
+    {},
+    { stripeAccount: scope.accountId },
+  );
+  expect(provider.balanceTransactions.retrieve).toHaveBeenCalledWith(
+    "txn_debit",
+    {},
+    { stripeAccount: scope.accountId },
+  );
+  expect(provider.payouts.retrieve).toHaveBeenCalledTimes(2);
+});
+it("reads automatic history without pretending it identifies per-source allocations", async () => {
+  const { read } = setup({ automatic: true });
+  expect(await read()).toMatchObject({
+    status: "ready",
+    automatic: true,
+    returnedPrincipal: 0,
+  });
+});
+it.each(["pending", "in_transit"])(
+  "preserves %s without saying the bank was paid",
+  async (status) => {
+    expect(await setup({ status }).read()).toMatchObject({
+      status: "ready",
+      providerStatus: status,
+    });
+  },
+);
+it.each(["failed", "canceled"])(
+  "verifies exact principal and signed fees returned after a %s payout",
+  async (status) => {
+    const result = await setup(
+      { status, failure_balance_transaction: "txn_return" },
+      { fee: 30, net: -1030 },
+      {
+        type: status === "failed" ? "payout_failure" : "payout_cancel",
+        fee: -10,
+        net: 1010,
+      },
+    ).read();
+    expect(result).toMatchObject({
+      status: "ready",
+      providerStatus: status,
+      returnedPrincipal: 1000,
+      returnedNet: 1010,
+      debit: { fee: 30 },
+      credit: { id: "txn_return", fee: -10, net: 1010 },
+    });
+  },
+);
+it("does not release a failure without a return receipt", async () => {
+  expect(await setup({ status: "failed" }).read()).toEqual({
+    status: "not_ready",
+    ...scope,
+    reason: "return_unavailable",
+  });
+});
+it.each([{ status: "pending" }, { available_on: timestamp + 86400 }])(
+  "does not release an immature return (%j)",
+  async (credit) => {
+    const result = await setup(
+      { status: "failed", failure_balance_transaction: "txn_return" },
+      {},
+      credit,
+    ).read();
+    expect(result).toEqual({
+      status: "not_ready",
+      ...scope,
+      reason: "return_pending",
+    });
+    expect(result).not.toHaveProperty("amount");
+  },
+);
+it("preserves a non-refundable payout fee separately from returned principal", async () => {
+  expect(
+    await setup(
+      { status: "failed", failure_balance_transaction: "txn_return" },
+      { fee: 30, net: -1030 },
+    ).read(),
+  ).toMatchObject({
+    status: "ready",
+    returnedPrincipal: 1000,
+    returnedNet: 1000,
+    debit: { fee: 30 },
+    credit: { fee: 0 },
+  });
+});
+it("fails closed when the provider changes the payout during receipt reads", async () => {
+  const { provider, read } = setup();
+  provider.payouts.retrieve
+    .mockResolvedValueOnce(payout())
+    .mockResolvedValueOnce(payout({ status: "failed" }));
+  expect(await read()).toEqual({
+    status: "not_ready",
+    ...scope,
+    reason: "provider_changed",
+  });
+});
+it("does not allocate a reversed bank payout as a failed payout", async () => {
+  expect(await setup({ reversed_by: "po_reversal" }).read()).toEqual({
+    status: "not_ready",
+    ...scope,
+    reason: "reversal_allocation_required",
+  });
+});
+it("fails closed when settlement currencies differ", async () => {
+  expect(await setup({}, { currency: "eur" }).read()).toEqual({
+    status: "not_ready",
+    ...scope,
+    reason: "currency_allocation_required",
+  });
+});
+it.each([
+  { id: "txn_other" },
+  { source: "po_other" },
+  { amount: -999, net: -999 },
+  { net: -1001 },
+  { amount: -1000.1 },
+  { fee: NaN },
+  { type: "charge" },
+])("rejects mismatched or unsafe payout debit %j", async (debit) => {
+  await expect(setup({}, debit).read()).rejects.toThrow(/receipt|integer/);
+});
+it.each([
+  { source: "po_other" },
+  { amount: 999, net: 999 },
+  { amount: 1001, net: 1001 },
+  { net: 999 },
+  { type: "charge" },
+  { id: "txn_debit" },
+])("rejects mismatched payout return %j", async (credit) => {
+  await expect(
+    setup(
+      { status: "failed", failure_balance_transaction: "txn_return" },
+      {},
+      credit,
+    ).read(),
+  ).rejects.toThrow(/receipt|integer/);
+});
+it("does not trust expanded receipt objects without retrieving their scoped records", async () => {
+  const { provider, read } = setup({
+    balance_transaction: { id: "txn_debit", amount: -5000 },
+  });
+  expect(await read()).toMatchObject({
+    status: "ready",
+    debit: { amount: -1000 },
+  });
+  expect(provider.balanceTransactions.retrieve).toHaveBeenCalledTimes(1);
+});
+it("binds recovery to the expected durable claim marker when requested", async () => {
+  const { provider } = setup({ metadata: { bsPayoutClaim: "claim-1" } });
+  const read = (operationKey: string) =>
+    getRecipientPayoutReceipt(provider as unknown as Stripe, {
+      ...scope,
+      operationKey,
+    });
+  expect(await read("claim-1")).toMatchObject({
+    status: "ready",
+    operationKey: "claim-1",
+  });
+  await expect(read("other")).rejects.toThrow(/claim/);
+});
+it("detects claim marker drift on the final payout read", async () => {
+  const { provider } = setup();
+  provider.payouts.retrieve
+    .mockResolvedValueOnce(payout({ metadata: { bsPayoutClaim: "claim-1" } }))
+    .mockResolvedValueOnce(payout({ metadata: { bsPayoutClaim: "other" } }));
+  expect(
+    await getRecipientPayoutReceipt(provider as unknown as Stripe, {
+      ...scope,
+      operationKey: "claim-1",
+    }),
+  ).toMatchObject({ status: "not_ready", reason: "provider_changed" });
+});
+it("does not suppress provider errors as proof of a missing receipt", async () => {
+  const { provider, read } = setup();
+  provider.balanceTransactions.retrieve.mockRejectedValue(
+    new Error("provider unavailable"),
+  );
+  await expect(read()).rejects.toThrow("provider unavailable");
+});
+it("returns no totals when the original debit is not available", async () => {
+  expect(await setup({ balance_transaction: null }).read()).toEqual({
+    status: "not_ready",
+    ...scope,
+    reason: "debit_unavailable",
+  });
+});
+it("rejects foreign payout identities and malformed scope", async () => {
+  await expect(setup({ id: "po_other" }).read()).rejects.toThrow(/identity/);
+  await expect(
+    setup().read({ accountId: "acct_recipient\n", stripePayoutId: "po_one" }),
+  ).rejects.toThrow(/identity/);
+});
+it("exposes the verifier through the public payout policy client", async () => {
+  const { PayoutPolicyClient } = await import("../payoutPolicy.js");
+  const { provider } = setup();
+  const client = new PayoutPolicyClient(
+    {} as never,
+    () => provider as unknown as Stripe,
+  );
+  expect(
+    client.payoutReceipt,
+    "public payout receipt reader missing",
+  ).toBeTypeOf("function");
+  expect(await client.payoutReceipt(scope)).toMatchObject({
+    status: "ready",
+    stripePayoutId: "po_one",
+  });
+});
+it.each([{ automatic: true }, { method: "instant" }, { type: "card" }])(
+  "does not bind a non-standard payout to a durable bank claim (%j)",
+  async (extra) => {
+    const { provider } = setup({
+      ...extra,
+      metadata: { bsPayoutClaim: "claim-1" },
+    });
+    await expect(
+      getRecipientPayoutReceipt(provider as unknown as Stripe, {
+        ...scope,
+        operationKey: "claim-1",
+      }),
+    ).rejects.toThrow(/claim/);
+  },
+);
+it.each([{ status: "pending" }, { available_on: timestamp + 86400 }])(
+  "does not book a payout debit before its fees and net are available (%j)",
+  async (debit) => {
+    const receipt = await setup({}, debit).read();
+    expect(receipt).toEqual({
+      status: "not_ready",
+      ...scope,
+      reason: "debit_pending",
+    });
+    expect(receipt).not.toHaveProperty("amount");
+  },
+);

package/src/client/connect/payoutReceipt.ts

@@ -0,0 +1,287 @@
+import type Stripe from "stripe";
+import type { PayoutStatus } from "../../component/connect/validators.js";
+export type RecipientPayoutReceiptOptions = {
+  accountId: string;
+  stripePayoutId: string;
+  /** Required when adopting a provider payout into a previously attempted claim. */
+  operationKey?: string;
+};
+export type PayoutReceiptTransaction = {
+  id: string;
+  amount: number;
+  fee: number;
+  net: number;
+  currency: string;
+  status: "available" | "pending";
+  created: number;
+  availableOn: number;
+  type: string;
+};
+export type RecipientPayoutReceipt =
+  | {
+      status: "not_ready";
+      accountId: string;
+      stripePayoutId: string;
+      reason:
+        | "debit_unavailable"
+        | "debit_pending"
+        | "return_unavailable"
+        | "return_pending"
+        | "provider_changed"
+        | "reversal_allocation_required"
+        | "currency_allocation_required";
+    }
+  | {
+      status: "ready";
+      accountId: string;
+      stripePayoutId: string;
+      operationKey?: string;
+      amount: number;
+      currency: string;
+      providerStatus: PayoutStatus;
+      automatic: boolean;
+      method: string;
+      type: string;
+      sourceType: string;
+      destinationId: string;
+      created: number;
+      arrivalDate: number;
+      debit: PayoutReceiptTransaction;
+      credit?: PayoutReceiptTransaction;
+      returnedPrincipal: number;
+      returnedNet: number;
+      observedAt: number;
+    };
+function id(value: unknown) {
+  return typeof value === "string"
+    ? value
+    : value &&
+        typeof value === "object" &&
+        "id" in value &&
+        typeof value.id === "string"
+      ? value.id
+      : undefined;
+}
+function safeInteger(value: number) {
+  if (!Number.isSafeInteger(value))
+    throw new Error(
+      "Payout receipt requires safe integer amounts and timestamps.",
+    );
+  return value;
+}
+function timestamp(value: number) {
+  if (safeInteger(value) < 0)
+    throw new Error("Payout receipt timestamp is invalid.");
+  return value;
+}
+function currency(value: string) {
+  if (value.length !== 3 || !/^[a-z]{3}$/.test(value))
+    throw new Error("Payout receipt currency is invalid.");
+}
+function fingerprint(p: Stripe.Payout) {
+  return JSON.stringify([
+    p.id,
+    p.amount,
+    p.currency,
+    p.status,
+    p.automatic,
+    p.method,
+    p.type,
+    p.source_type,
+    id(p.destination),
+    id(p.balance_transaction),
+    id(p.failure_balance_transaction),
+    id(p.reversed_by),
+    p.created,
+    p.arrival_date,
+    p.metadata?.bsPayoutClaim,
+  ]);
+}
+function transaction(
+  t: Stripe.BalanceTransaction,
+  expectedId: string,
+  payoutId: string,
+  amount: number,
+  types: string[],
+): PayoutReceiptTransaction {
+  if (
+    t.id !== expectedId ||
+    id(t.source) !== payoutId ||
+    t.amount !== amount ||
+    !types.includes(t.type)
+  )
+    throw new Error(
+      "Payout transaction receipt identity or principal does not match.",
+    );
+  safeInteger(t.amount);
+  safeInteger(t.fee);
+  safeInteger(t.net);
+  if (safeInteger(t.amount - t.fee) !== t.net)
+    throw new Error("Payout transaction receipt net amount does not match.");
+  if (
+    !["available", "pending"].includes(t.status) ||
+    ("balance_type" in t && t.balance_type !== "payments")
+  )
+    throw new Error("Payout transaction receipt balance is unsupported.");
+  currency(t.currency);
+  return {
+    id: t.id,
+    amount: t.amount,
+    fee: t.fee,
+    net: t.net,
+    currency: t.currency,
+    status: t.status as "available" | "pending",
+    created: timestamp(t.created),
+    availableOn: timestamp(t.available_on),
+    type: t.type,
+  };
+}
+/**
+ * Read-only provider receipts, not unpaid entitlement or authorization to release
+ * a reservation. Fees remain separate from principal and must be accounted for
+ * by the payout/recovery ledger. Manual payout receipts do not identify the
+ * original transfers that funded them. Host authorizes access to this account.
+ */
+export async function getRecipientPayoutReceipt(
+  stripe: Stripe,
+  options: RecipientPayoutReceiptOptions,
+): Promise<RecipientPayoutReceipt> {
+  const scope = {
+    accountId: options.accountId,
+    stripePayoutId: options.stripePayoutId,
+  };
+  if (
+    !/^acct_\w+$/.test(scope.accountId) ||
+    scope.accountId.trim() !== scope.accountId ||
+    scope.accountId.length > 80 ||
+    !/^po_\w+$/.test(scope.stripePayoutId) ||
+    scope.stripePayoutId.trim() !== scope.stripePayoutId ||
+    scope.stripePayoutId.length > 100
+  )
+    throw new Error("Invalid recipient payout identity.");
+  if (
+    options.operationKey !== undefined &&
+    (!options.operationKey.trim() ||
+      options.operationKey.length > 180 ||
+      /[\r\n]/.test(options.operationKey))
+  )
+    throw new Error("Invalid payout claim identity.");
+  const request = { stripeAccount: scope.accountId };
+  const readPayout = () =>
+    stripe.payouts.retrieve(scope.stripePayoutId, {}, request);
+  const payout = await readPayout();
+  if (payout.id !== scope.stripePayoutId)
+    throw new Error("Provider payout identity does not match.");
+  if (safeInteger(payout.amount) <= 0)
+    throw new Error("Payout receipt principal is invalid.");
+  currency(payout.currency);
+  timestamp(payout.created);
+  timestamp(payout.arrival_date);
+  if (
+    !["pending", "in_transit", "paid", "failed", "canceled"].includes(
+      payout.status,
+    ) ||
+    typeof payout.automatic !== "boolean" ||
+    !["standard", "instant"].includes(payout.method) ||
+    !["bank_account", "card"].includes(payout.type) ||
+    !["card", "bank_account", "fpx"].includes(payout.source_type) ||
+    !id(payout.destination)
+  )
+    throw new Error("Payout receipt state is unsupported.");
+  if (
+    options.operationKey !== undefined &&
+    payout.metadata?.bsPayoutClaim !== options.operationKey
+  )
+    throw new Error("Provider payout claim identity does not match.");
+  if (
+    options.operationKey !== undefined &&
+    (payout.automatic ||
+      payout.method !== "standard" ||
+      payout.type !== "bank_account")
+  )
+    throw new Error(
+      "Provider payout does not match a standard manual bank claim.",
+    );
+  if (payout.reversed_by != null)
+    return {
+      status: "not_ready",
+      ...scope,
+      reason: "reversal_allocation_required",
+    };
+  const debitId = id(payout.balance_transaction);
+  if (!debitId)
+    return { status: "not_ready", ...scope, reason: "debit_unavailable" };
+  const debit = transaction(
+    await stripe.balanceTransactions.retrieve(debitId, {}, request),
+    debitId,
+    payout.id,
+    -payout.amount,
+    ["payout"],
+  );
+  if (debit.currency !== payout.currency)
+    return {
+      status: "not_ready",
+      ...scope,
+      reason: "currency_allocation_required",
+    };
+  if (
+    debit.status !== "available" ||
+    debit.availableOn > Math.floor(Date.now() / 1000)
+  )
+    return { status: "not_ready", ...scope, reason: "debit_pending" };
+  let credit: PayoutReceiptTransaction | undefined;
+  if (payout.status === "failed" || payout.status === "canceled") {
+    const creditId = id(payout.failure_balance_transaction);
+    if (!creditId)
+      return { status: "not_ready", ...scope, reason: "return_unavailable" };
+    if (creditId === debitId)
+      throw new Error(
+        "Payout return receipt cannot also be the original debit.",
+      );
+    credit = transaction(
+      await stripe.balanceTransactions.retrieve(creditId, {}, request),
+      creditId,
+      payout.id,
+      payout.amount,
+      ["payout_failure", "payout_cancel"],
+    );
+    if (credit.currency !== payout.currency)
+      return {
+        status: "not_ready",
+        ...scope,
+        reason: "currency_allocation_required",
+      };
+    if (
+      credit.status !== "available" ||
+      credit.availableOn > Math.floor(Date.now() / 1000)
+    )
+      return { status: "not_ready", ...scope, reason: "return_pending" };
+  } else if (payout.failure_balance_transaction != null) {
+    return { status: "not_ready", ...scope, reason: "provider_changed" };
+  }
+  const verified = await readPayout();
+  if (fingerprint(payout) !== fingerprint(verified))
+    return { status: "not_ready", ...scope, reason: "provider_changed" };
+  return {
+    status: "ready",
+    ...scope,
+    ...(payout.metadata?.bsPayoutClaim
+      ? { operationKey: payout.metadata.bsPayoutClaim }
+      : {}),
+    amount: payout.amount,
+    currency: payout.currency,
+    providerStatus: payout.status as PayoutStatus,
+    automatic: payout.automatic,
+    method: payout.method,
+    type: payout.type,
+    sourceType: payout.source_type,
+    destinationId: id(payout.destination)!,
+    created: payout.created,
+    arrivalDate: payout.arrival_date,
+    debit,
+    ...(credit ? { credit } : {}),
+    returnedPrincipal: credit?.amount ?? 0,
+    returnedNet: credit?.net ?? 0,
+    observedAt: Date.now(),
+  };
+}