@fantastic.dev/better-stripe 0.13.0 → 0.15.0

package/src/client/connect/dispute-upload.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { Component, RunCtx } from "../helpers.js";
+import { updateDispute, uploadDisputeEvidence } from "./disputes.js";
+
+function makeStripe() {
+  return {
+    disputes: {
+      update: vi.fn().mockResolvedValue({}),
+      close: vi.fn().mockResolvedValue({}),
+    },
+  };
+}
+const asStripe = (s: ReturnType<typeof makeStripe>) =>
+  s as unknown as Parameters<typeof updateDispute>[0];
+
+const TO_REF = Symbol.for("toReferencePath");
+
+/**
+ * Component proxy exposing the two connect query refs the dispute-action
+ * authorization resolves: the dispute (by its Stripe id) and the payment that
+ * dispute is linked to (by PaymentIntent id).
+ */
+function makeAuthComponent(): Component {
+  const ref = (path: string) => ({ [TO_REF]: `betterStripe/${path}` });
+  return {
+    connect: {
+      queries: {
+        getDisputeByStripeId: ref("connect/queries/getDisputeByStripeId"),
+        getPaymentByStripeId: ref("connect/queries/getPaymentByStripeId"),
+      },
+    },
+  } as unknown as Component;
+}
+
+/**
+ * A ctx whose runQuery dispatches by the query args: a `stripeDisputeId` lookup
+ * resolves the dispute row; a `stripePaymentIntentId` lookup resolves the
+ * payment row. Either may be null to exercise the fail-closed paths.
+ */
+function makeAuthCtx(disputeRow?: unknown, paymentRow?: unknown) {
+  const runQuery = vi.fn().mockImplementation((_ref, args) => {
+    if (args && "stripeDisputeId" in args)
+      return Promise.resolve(disputeRow ?? null);
+    if (args && "stripePaymentIntentId" in args)
+      return Promise.resolve(paymentRow ?? null);
+    return Promise.resolve(null);
+  });
+  return { runQuery } as unknown as RunCtx & {
+    runQuery: ReturnType<typeof vi.fn>;
+  };
+}
+
+describe("uploadDisputeEvidence", () => {
+  const file = {
+    data: new TextEncoder().encode("%PDF-1.7\nfixture"),
+    name: "evidence.pdf",
+    type: "application/pdf" as const,
+  };
+  const opts = {
+    stripeDisputeId: "dp_1",
+    actor: { type: "seller" as const, accountId: "acct_owner" },
+    field: "customer_communication" as const,
+    file,
+  };
+  function setup(owner = "acct_owner") {
+    const stripe = {
+      ...makeStripe(),
+      files: { create: vi.fn().mockResolvedValue({ id: "file_uploaded" }) },
+    };
+    const ctx = makeAuthCtx(
+      { stripePaymentIntentId: "pi_1" },
+      { destinationAccountId: owner },
+    );
+    return { stripe, ctx };
+  }
+  it("uploads bytes and binds only the returned file ID as draft", async () => {
+    const { stripe, ctx } = setup();
+    const result = await uploadDisputeEvidence(
+      asStripe(stripe),
+      makeAuthComponent(),
+      ctx,
+      opts,
+    );
+    expect(stripe.files.create).toHaveBeenCalledWith(
+      { purpose: "dispute_evidence", file },
+      undefined,
+    );
+    expect(stripe.disputes.update).toHaveBeenCalledWith(
+      "dp_1",
+      { evidence: { customer_communication: "file_uploaded" }, submit: false },
+      undefined,
+    );
+    expect(result).toEqual({
+      stripeFileId: "file_uploaded",
+      stripeDisputeId: "dp_1",
+    });
+  });
+  it("denies another seller before uploading", async () => {
+    const { stripe, ctx } = setup("acct_other");
+    await expect(
+      uploadDisputeEvidence(asStripe(stripe), makeAuthComponent(), ctx, opts),
+    ).rejects.toThrow(/not authorized/);
+    expect(stripe.files.create).not.toHaveBeenCalled();
+    expect(stripe.disputes.update).not.toHaveBeenCalled();
+  });
+  it.each([
+    { ...file, type: "text/plain" },
+    { ...file, data: new Uint8Array(0) },
+    { ...file, data: new Uint8Array(5_000_001) },
+    { ...file, data: new TextEncoder().encode("not a PDF") },
+  ])("rejects invalid files before provider calls", async (file) => {
+    const { stripe, ctx } = setup();
+    await expect(
+      uploadDisputeEvidence(asStripe(stripe), makeAuthComponent(), ctx, {
+        ...opts,
+        file: file as typeof opts.file,
+      }),
+    ).rejects.toThrow(/Invalid dispute evidence/);
+    expect(stripe.files.create).not.toHaveBeenCalled();
+  });
+  it("does not attach after an upload failure and preserves provider errors", async () => {
+    const { stripe, ctx } = setup();
+    stripe.files.create.mockRejectedValue({
+      type: "StripeInvalidRequestError",
+      code: "file_invalid",
+      message: "Corrupt PDF",
+    });
+    await expect(
+      uploadDisputeEvidence(asStripe(stripe), makeAuthComponent(), ctx, opts),
+    ).rejects.toMatchObject({
+      data: {
+        code: "DISPUTE_UPLOAD_FAILED",
+        stripeError: { code: "file_invalid" },
+      },
+    });
+    expect(stripe.disputes.update).not.toHaveBeenCalled();
+  });
+  it("surfaces draft attachment failure without submitting", async () => {
+    const { stripe, ctx } = setup();
+    stripe.disputes.update.mockRejectedValue(new Error("unavailable"));
+    await expect(
+      uploadDisputeEvidence(asStripe(stripe), makeAuthComponent(), ctx, opts),
+    ).rejects.toMatchObject({ data: { code: "DISPUTE_UPDATE_FAILED" } });
+    expect(stripe.disputes.update.mock.calls[0][1].submit).toBe(false);
+  });
+});
+
+it.each([
+  {
+    type: "image/png" as const,
+    data: new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]),
+  },
+  { type: "image/jpeg" as const, data: new Uint8Array([255, 216, 255]) },
+])(
+  "uploads supported image signatures to the owning request account",
+  async (file) => {
+    const stripe = {
+      ...makeStripe(),
+      files: { create: vi.fn().mockResolvedValue({ id: "file_image" }) },
+    };
+    await uploadDisputeEvidence(
+      asStripe(stripe),
+      makeAuthComponent(),
+      {} as RunCtx,
+      {
+        actor: { type: "admin" },
+        stripeDisputeId: "dp_1",
+        stripeAccountId: "acct_direct",
+        field: "receipt",
+        file: { ...file, name: "proof" },
+      },
+    );
+    expect(stripe.files.create.mock.calls[0][1]).toEqual({
+      stripeAccount: "acct_direct",
+    });
+    expect(stripe.disputes.update.mock.calls[0][2]).toEqual({
+      stripeAccount: "acct_direct",
+    });
+  },
+);
+
+it("rejects a malformed seller actor before any provider call", async () => {
+  const stripe = {
+    ...makeStripe(),
+    files: { create: vi.fn().mockResolvedValue({ id: "file_1" }) },
+  };
+  await expect(
+    uploadDisputeEvidence(
+      asStripe(stripe),
+      makeAuthComponent(),
+      makeAuthCtx({ stripePaymentIntentId: "pi_1" }, {}),
+      {
+        actor: { type: "seller" } as Parameters<
+          typeof uploadDisputeEvidence
+        >[3]["actor"],
+        stripeDisputeId: "dp_1",
+        field: "receipt",
+        file: {
+          data: new TextEncoder().encode("%PDF-1.7"),
+          name: "a.pdf",
+          type: "application/pdf",
+        },
+      },
+    ),
+  ).rejects.toThrow(/authenticated actor/);
+  expect(stripe.files.create).not.toHaveBeenCalled();
+});

package/src/client/connect/disputes.ts

@@ -148,6 +148,109 @@ export async function updateDispute(
   }
 }
 
+/** File fields supported by Stripe dispute evidence. */
+export type DisputeEvidenceFileField =
+  | "cancellation_policy"
+  | "customer_communication"
+  | "customer_signature"
+  | "duplicate_charge_documentation"
+  | "receipt"
+  | "refund_policy"
+  | "service_documentation"
+  | "shipping_documentation"
+  | "uncategorized_file";
+export type DisputeEvidenceUploadOptions = {
+  stripeDisputeId: string;
+  /** Derive this on the server from the authenticated session. */
+  actor: RefundActor;
+  field: DisputeEvidenceFileField;
+  file: {
+    data: Uint8Array;
+    name: string;
+    type: "application/pdf" | "image/jpeg" | "image/png";
+  };
+  /** Request account owning the charge, distinct from the seller actor. */
+  stripeAccountId?: string;
+};
+
+/** Upload and attach to one authorized dispute as a draft. Never submits. */
+export async function uploadDisputeEvidence(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  opts: DisputeEvidenceUploadOptions,
+): Promise<{ stripeFileId: string; stripeDisputeId: string }> {
+  if (
+    !opts.actor ||
+    !["admin", "seller"].includes(opts.actor.type) ||
+    (opts.actor.type === "seller" &&
+      (typeof opts.actor.accountId !== "string" ||
+        !opts.actor.accountId.trim()))
+  )
+    throwStripeError(
+      "DISPUTE_UNAUTHORIZED",
+      "Dispute upload requires an authenticated actor",
+    );
+  await assertDisputeAuthorized(component, ctx, opts);
+  const fields: DisputeEvidenceFileField[] = [
+    "cancellation_policy",
+    "customer_communication",
+    "customer_signature",
+    "duplicate_charge_documentation",
+    "receipt",
+    "refund_policy",
+    "service_documentation",
+    "shipping_documentation",
+    "uncategorized_file",
+  ];
+  const { data, name, type } = opts.file;
+  const signature =
+    type === "application/pdf"
+      ? [37, 80, 68, 70, 45]
+      : type === "image/jpeg"
+        ? [255, 216, 255]
+        : type === "image/png"
+          ? [137, 80, 78, 71, 13, 10, 26, 10]
+          : [];
+  if (
+    !fields.includes(opts.field) ||
+    !(data instanceof Uint8Array) ||
+    !data.byteLength ||
+    data.byteLength > 5_000_000 ||
+    !name.trim() ||
+    !signature.length ||
+    !signature.every((byte, i) => data[i] === byte)
+  )
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Invalid dispute evidence: use a nonempty PDF, JPEG or PNG up to 5 MB with a matching MIME type and filename",
+    );
+  let stripeFileId: string;
+  try {
+    const file = await stripe.files.create(
+      { purpose: "dispute_evidence", file: { data, name, type } },
+      opts.stripeAccountId
+        ? { stripeAccount: opts.stripeAccountId }
+        : undefined,
+    );
+    stripeFileId = file.id;
+  } catch (err) {
+    throwStripeError(
+      "DISPUTE_UPLOAD_FAILED",
+      "Failed to upload dispute evidence",
+      err,
+    );
+  }
+  await updateDispute(stripe, component, ctx, {
+    stripeDisputeId: opts.stripeDisputeId,
+    actor: opts.actor,
+    stripeAccountId: opts.stripeAccountId,
+    evidence: { [opts.field]: stripeFileId },
+    submit: false,
+  });
+  return { stripeFileId, stripeDisputeId: opts.stripeDisputeId };
+}
+
 /**
  * Accept a dispute (concede the chargeback). Irreversible.
  *

package/src/client/core/fees.ts

@@ -273,3 +273,11 @@ export function validateSplit(recipients: SplitRecipient[]): void {
     throw new Error(`split percents sum to ${percentSum}, which exceeds 100`);
   }
 }
+
+/** Deep-copy a platform fee config so stored/returned values can't be mutated. */
+export function clonePlatformFee(config: PlatformFeeConfig): PlatformFeeConfig {
+  return {
+    ...config,
+    tiers: config.tiers?.map((tier) => ({ ...tier })),
+  };
+}

package/src/client/costRecovery-import.test.ts

@@ -0,0 +1,174 @@
+import { componentsGeneric, type FunctionReference } from "convex/server";
+import { expect, it } from "vitest";
+import schema from "../component/schema.js";
+import { initConvexTest } from "./setup.test.js";
+import { BetterStripe } from "./index.js";
+import type { Component, RunCtx } from "./helpers.js";
+const modules = import.meta.glob("../component/**/*.{ts,js,tsx,jsx}");
+const scope = { accountId: "acct_owner", scopeKey: "store", currency: "usd" };
+const observation = {
+  ...scope,
+  claimKey: "cost:ch_original",
+  sourceChargeId: "ch_original",
+  sourceGross: 10000,
+  sourceProcessingFee: 320,
+  amountDue: 320,
+  revision: 0,
+};
+async function setup() {
+  const t = initConvexTest();
+  t.registerComponent("betterStripe", schema, modules);
+  const ctx = {
+    runQuery: (
+      ref: FunctionReference<"query">,
+      args: Record<string, unknown>,
+    ) => t.query(ref, args),
+    runMutation: (
+      ref: FunctionReference<"mutation">,
+      args: Record<string, unknown>,
+    ) => t.mutation(ref, args),
+  } as unknown as RunCtx;
+  return {
+    ctx,
+    recovery: new BetterStripe(
+      componentsGeneric().betterStripe as unknown as Component,
+      {},
+    ).costRecovery,
+  };
+}
+it("imports verified opening collections once and preserves the snapshot across newer observations", async () => {
+  const { ctx, recovery } = await setup();
+  const input = {
+    ...observation,
+    operationKey: "cutover:legacy-row",
+    collectedAmount: 200,
+  };
+  const first = await recovery.importClaim(ctx, input);
+  expect(first).toMatchObject({
+    amountDue: 320,
+    collectedAmount: 200,
+    outstanding: 120,
+    reservedAmount: 0,
+  });
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    amountDue: 320,
+    collectedAmount: 200,
+    outstanding: 120,
+  });
+  await recovery.recordClaim(ctx, {
+    ...observation,
+    amountDue: 100,
+    revision: 1,
+  });
+  const replay = await recovery.importClaim(ctx, input);
+  expect(replay).toMatchObject({
+    _id: first._id,
+    amountDue: 100,
+    revision: 1,
+    collectedAmount: 200,
+    outstanding: -100,
+  });
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    amountDue: 100,
+    collectedAmount: 200,
+    outstanding: -100,
+  });
+  await expect(
+    recovery.importClaim(ctx, { ...input, collectedAmount: 201 }),
+  ).rejects.toThrow(/snapshot/i);
+  await expect(
+    recovery.importClaim(ctx, { ...input, accountId: "acct_other" }),
+  ).rejects.toThrow(/identity/i);
+});
+it("preserves signed credit collections and currency isolation without Stripe credentials", async () => {
+  const { ctx, recovery } = await setup();
+  await recovery.importClaim(ctx, {
+    ...observation,
+    amountDue: -500,
+    collectedAmount: -200,
+    operationKey: "credit-import",
+  });
+  await recovery.importClaim(ctx, {
+    ...observation,
+    claimKey: "cost:eur",
+    currency: "eur",
+    collectedAmount: 300,
+    operationKey: "eur-import",
+  });
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    amountDue: -500,
+    collectedAmount: -200,
+    outstanding: -300,
+  });
+  expect(
+    await recovery.balance(ctx, { ...scope, currency: "eur" }),
+  ).toMatchObject({ amountDue: 320, collectedAmount: 300, outstanding: 20 });
+});
+it("refuses to overwrite live claims or import into a pending external recovery boundary", async () => {
+  const { ctx, recovery } = await setup();
+  await recovery.recordClaim(ctx, observation);
+  await expect(
+    recovery.importClaim(ctx, {
+      ...observation,
+      operationKey: "late-import",
+      collectedAmount: 200,
+    }),
+  ).rejects.toThrow(/existing/i);
+  await recovery.reserve(ctx, {
+    ...scope,
+    groupKey: "pending",
+    operationKey: "pending:1",
+    sourceKind: "invoice",
+    sourceId: "in_1",
+    maxDebit: 10000,
+    maxCredit: 10000,
+  });
+  await expect(
+    recovery.importClaim(ctx, {
+      ...observation,
+      claimKey: "other",
+      operationKey: "new-import",
+      collectedAmount: 10,
+    }),
+  ).rejects.toThrow(/pending/i);
+  await expect(
+    recovery.importClaim(ctx, {
+      ...observation,
+      claimKey: "invalid",
+      operationKey: "",
+      collectedAmount: 0.5,
+    }),
+  ).rejects.toThrow();
+});
+it("reserves only the uncollected remainder and keeps the opening import idempotent after collection", async () => {
+  const { ctx, recovery } = await setup();
+  const input = {
+    ...observation,
+    operationKey: "opening",
+    collectedAmount: 200,
+  };
+  await recovery.importClaim(ctx, input);
+  const group = {
+    ...scope,
+    groupKey: "funding",
+    operationKey: "funding:1",
+    sourceKind: "settlement" as const,
+    sourceId: "ch_funding",
+    sourceGross: 10000,
+    sourceProcessingFee: 320,
+    maxDebit: 10000,
+    maxCredit: 10000,
+  };
+  expect((await recovery.reserve(ctx, group)).group.amount).toBe(120);
+  await recovery.seal(ctx, { groupKey: "funding" });
+  await recovery.finish(ctx, { groupKey: "funding", outcome: "collect" });
+  await recovery.importClaim(ctx, input);
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    amountDue: 320,
+    collectedAmount: 320,
+    outstanding: 0,
+  });
+  await expect(
+    recovery.importClaim(ctx, { ...input, claimKey: "other" }),
+  ).rejects.toThrow(/identity/i);
+});

package/src/client/costRecovery-invoices.test.ts

@@ -399,3 +399,72 @@ it("never creates a new provider item for an already completed bookkeeping group
   await expect(recovery.attachInvoice(ctx, options)).rejects.toThrow(/sealed/i);
   expect(provider.invoiceItems.create).not.toHaveBeenCalled();
 });
+it("releases an unbound void invoice after a complete item scan without creating an adjustment", async () => {
+  const { ctx, recovery, invoice, items, provider } = await setup();
+  items.push(
+    ...Array.from(
+      { length: 105 },
+      (_, i) => ({ id: `ii_other_${i}`, metadata: {} }) as Stripe.InvoiceItem,
+    ),
+  );
+  invoice.status = "void";
+  const result = await recovery.reconcileInvoice(ctx, options);
+  expect(result).toMatchObject({
+    isDone: true,
+    invoiceItemId: null,
+    invoiceStatus: "void",
+  });
+  await recovery.reconcileInvoice(ctx, options);
+  expect(provider.invoiceItems.create).not.toHaveBeenCalled();
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    reservedAmount: 0,
+    collectedAmount: 0,
+    outstanding: 320,
+  });
+});
+it("keeps missing adjustments reserved for unpaid, paid, uncollectible or previously bound invoices", async () => {
+  for (const status of ["draft", "open", "paid", "uncollectible"]) {
+    const { ctx, recovery, invoice } = await setup();
+    invoice.status = status;
+    await expect(
+      recovery.reconcileInvoice(ctx, {
+        ...options,
+        releaseUncollectible: true,
+      }),
+    ).rejects.toThrow(/missing/i);
+    expect(await recovery.balance(ctx, scope)).toMatchObject({
+      reservedAmount: 320,
+      collectedAmount: 0,
+    });
+  }
+  const { ctx, recovery, invoice, items } = await setup();
+  await recovery.attachInvoice(ctx, options);
+  items.length = 0;
+  invoice.status = "void";
+  await expect(recovery.reconcileInvoice(ctx, options)).rejects.toThrow(
+    /bound.*missing/i,
+  );
+});
+it("does not release an unbound void invoice on an incomplete scan or ownership mismatch", async () => {
+  const { ctx, recovery, invoice, provider } = await setup();
+  invoice.status = "void";
+  const originalList = provider.invoiceItems.list.getMockImplementation()!;
+  provider.invoiceItems.list.mockImplementation(() =>
+    (async function* () {
+      yield { id: "ii_unrelated", metadata: {} } as Stripe.InvoiceItem;
+      throw new Error("pagination interrupted");
+    })(),
+  );
+  await expect(recovery.reconcileInvoice(ctx, options)).rejects.toThrow(
+    "pagination interrupted",
+  );
+  provider.invoiceItems.list.mockImplementation(originalList);
+  invoice.customer_account = "acct_other";
+  await expect(recovery.reconcileInvoice(ctx, options)).rejects.toThrow(
+    /ownership/i,
+  );
+  expect(await recovery.balance(ctx, scope)).toMatchObject({
+    reservedAmount: 320,
+    collectedAmount: 0,
+  });
+});

package/src/client/costRecovery-invoices.ts

@@ -6,6 +6,32 @@ const marker = "bsRecoveryGroup";
 const id = (value: string | { id: string } | null) =>
   typeof value === "string" ? value : value?.id;
 
+type InvoiceReceipt = {
+  group: RecoveryGroup;
+  invoiceItemId: string;
+  invoiceStatus: Stripe.Invoice["status"];
+};
+type BindInvoiceItem = (invoiceItemId: string) => Promise<RecoveryGroup>;
+
+/** Attachment always produces an item; reconciliation can release an unbound void invoice. */
+export function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: BindInvoiceItem,
+  create?: true,
+): Promise<InvoiceReceipt>;
+export function attachRecoveryInvoice(
+  stripe: Stripe,
+  group: RecoveryGroup | null,
+  opts: RecoveryInvoiceOptions,
+  bind: BindInvoiceItem,
+  create: false,
+): Promise<
+  | InvoiceReceipt
+  | (Omit<InvoiceReceipt, "invoiceItemId"> & { invoiceItemId: null })
+>;
+
 /** One immutable item per sealed group. Host serializes provider operations per group. */
 export async function attachRecoveryInvoice(
   stripe: Stripe,
@@ -66,6 +92,12 @@ export async function attachRecoveryInvoice(
       throw new Error(
         "Bound recovery invoice item is missing; reconcile before retrying.",
       );
+    if (
+      !create &&
+      invoice.status === "void" &&
+      ["sealed", "releasing", "released"].includes(group.status)
+    )
+      return { group, invoiceItemId: null, invoiceStatus: invoice.status };
     if (!create)
       throw new Error(
         "Recovery invoice item is missing; no collection can be confirmed.",

package/src/client/costRecovery.ts

@@ -26,6 +26,12 @@ export type RecoveryClaim = RecoveryObservation & {
   reservedAmount: number;
   outstanding: number;
   sign: "positive" | "negative" | "zero";
+  openingCollection?: {
+    operationKey: string;
+    amountDue: number;
+    revision: number;
+    collectedAmount: number;
+  };
 };
 export type RecoveryBalance = RecoveryScope & {
   amountDue: number;
@@ -194,6 +200,16 @@ export class CostRecoveryClient {
       }),
     };
   }
+  /** Import a host-verified opening collection. Never overwrites a live claim. */
+  importClaim(
+    ctx: RunCtx,
+    opts: RecoveryObservation & {
+      operationKey: string;
+      collectedAmount: number;
+    },
+  ) {
+    return this.mutate<RecoveryClaim>(ctx, "mutations/importClaim", opts);
+  }
   recordClaim(ctx: RunCtx, opts: RecoveryObservation) {
     return this.mutate<RecoveryClaim>(ctx, "mutations/record", opts);
   }

package/src/client/errors.ts

@@ -9,6 +9,7 @@ export type BetterStripeErrorCode =
   | "SUBSCRIPTION_UPDATE_FAILED"
   | "REFUND_CREATE_FAILED"
   | "REFUND_UNAUTHORIZED"
+  | "DISPUTE_UPLOAD_FAILED"
   | "DISPUTE_UPDATE_FAILED"
   | "DISPUTE_UNAUTHORIZED"
   | "CHECKOUT_CREATE_FAILED"