@fantastic.dev/better-stripe 0.17.1 → 0.18.0

package/dist/component/schema.js

@@ -1,3 +1,4 @@
+import { policiesTable, operationsTable } from "./payoutPolicy/schema.js";
 import { currencyTotalsTable } from "./earnings/schema.js";
 import { claimsTable, balancesTable, groupsTable, reservationsTable, } from "./costRecovery/schema";
 import { allocationsTable, commissionTermsTable, commissionDecisionsTable, } from "./settlement/schema";
@@ -8,6 +9,8 @@ import { accountsTable } from "./core/schema";
 import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 export default defineSchema({
+    payoutPolicies: policiesTable,
+    payoutPolicyOperations: operationsTable,
     currencyTotals: currencyTotalsTable,
     recoveryClaims: claimsTable,
     recoveryBalances: balancesTable,

package/dist/component/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IAEvB,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}

package/docs/settlement.md

@@ -156,3 +156,65 @@ It requires a selected retention boundary and migration policy. Applications mus
 not describe a displayed threshold as enforced while Stripe controls automatic
 payouts. A numeric below/exact/above provider-floor demonstration is unavailable
 without a supported provider floor read; surface this capability limitation.
+
+## Recipient-held payout policy controls
+
+`stripe.payoutPolicy` stages versioned, account-wide schedule changes for a
+user-level recipient. The host authenticates `ownerKey`, authorizes the policy,
+and records explicit consent. Thresholds use integer minor units per currency;
+they combine creator and affiliate funds rather than creating category gates.
+The untouched default remains Stripe-managed automatic payouts.
+
+Call `prepare(ctx, { accountId, ownerKey, operationKey, expectedRevision, mode:
+"custom", thresholds: [{ currency: "usd", amount: 1000 }], consent: true })` in
+an authorized action. Revision `-1` means no existing policy. Persisted preparation
+captures the original payout schedule and country holding deadline before any
+provider update. If preparation returns `prepared`, call `apply` with the same
+account, owner and operation key. Replays preserve the immutable request;
+competing operations and stale revisions are rejected. A provider timeout or
+failed confirmation stays pending for reconciliation, rather than being treated
+as a completed schedule change.
+
+These APIs currently require a verified `dashboard: none` account and enabled
+payouts for custom activation. Accounts with Dashboard withdrawal access return
+an explicit control limitation: restricting schedule edits alone cannot prevent
+manual withdrawals. The API never changes dashboard access or loss liability to
+obtain control. Stripe also validates update permissions. Before each subsequent
+payout attempt, `verify` must confirm live manual settings, unchanged country,
+and an unexpired policy; stored `ready` state alone is insufficient.
+
+Initial activation rejects existing nonzero available or pending balances,
+in-flight payouts, and existing manual schedules with `migration_required`.
+The preflight is repeated before an initial schedule update; a delayed activation
+with newly arrived funds is canceled before changing Stripe. This is a bounded
+preflight, not an ownership inference or automatic adoption.
+Already-mixed funds need a reconciled source ledger and explicit adoption before
+custom release can be enabled. Zero-balance activation does not classify later
+unrelated deposits as earnings. Payout claims must use that source ledger and a
+fresh provider balance when the separate release boundary is integrated.
+
+The host must schedule a recurring server job that pages `due(ctx,
+{ cursor: null, numItems: 100 })`, follows its cursor, and calls `expire` for each
+returned account/owner. `expire` reconciles pending operations and restores the
+original automatic schedule when the holding deadline is reached. Unattempted
+expired enables are canceled without changing Stripe. Failed/unknown restores
+remain visible and retryable; alert operators if they cannot complete. Editing
+thresholds never extends the original deadline. Current limits are 10 days for
+Thailand, a conservative 730 days for the US, and 90 days elsewhere; verify
+current provider rules before enabling the feature in production.
+
+For opt-out, prepare a new operation with the latest revision,
+`mode: "stripe_managed"`, and `thresholds: []`, then apply it. Restoration remains
+available after Dashboard control is lost, subject to Stripe permissions. It
+restores only the captured schedule; other balance settings remain untouched.
+
+This is the durable policy/control boundary. Automatic combined payout execution,
+adoption of existing balances, and its UI integration are separate work and are
+not supplied by these schedule APIs. Do not expose a custom minimum as fully
+enforced until those boundaries and the recurring expiry job are installed.
+`verify.providerMinimum` is `null`: the Balance Settings API does not expose a
+numeric payout-floor field, and retained balance reserves are not payout triggers.
+
+Sources: [payout schedules](https://docs.stripe.com/connect/manage-payout-schedule),
+[manual payout holding limits](https://docs.stripe.com/connect/manual-payouts), and
+[Dashboard control limits](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts#control-payout-timing).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/connect/payouts.ts

@@ -53,17 +53,19 @@ export async function getAccountBalance(
   return [...byCurrency.values()];
 }
 
+export type CreatePayoutOptions = {
+  stripeAccountId: string;
+  amount: number;
+  currency?: string;
+  metadata?: Record<string, string>;
+  /** Stripe idempotency key for retry-safe payout creation. */
+  idempotencyKey?: string;
+};
+
 export async function createPayout(
   stripe: Stripe,
   _ctx: RunCtx,
-  opts: {
-    stripeAccountId: string;
-    amount: number;
-    currency?: string;
-    metadata?: Record<string, string>;
-    /** Stripe idempotency key for retry-safe payout creation. */
-    idempotencyKey?: string;
-  },
+  opts: CreatePayoutOptions,
 ) {
   const payout = await stripe.payouts.create(
     {

package/src/client/index.ts

@@ -1,3 +1,5 @@
+import { PayoutPolicyClient } from "./payoutPolicy.js";
+export * from "./payoutPolicy.js";
 import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
 export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
 import * as intentsImpl from "./billing/intents.js";
@@ -1146,17 +1148,7 @@ export class BetterStripe extends ReadContractClient {
 
   // PAYOUT METHODS
 
-  async createPayout(
-    ctx: RunCtx,
-    opts: {
-      stripeAccountId: string;
-      amount: number;
-      currency?: string;
-      metadata?: Record<string, string>;
-      /** Stripe idempotency key for retry-safe payout creation. */
-      idempotencyKey?: string;
-    },
-  ) {
+  async createPayout(ctx: RunCtx, opts: payoutsImpl.CreatePayoutOptions) {
     return payoutsImpl.createPayout(this.stripe(), ctx, opts);
   }
 
@@ -1263,6 +1255,10 @@ export class BetterStripe extends ReadContractClient {
   ) {
     return providerReads.getCouponFromStripe(this.stripe(), opts);
   }
+  get payoutPolicy() {
+    return new PayoutPolicyClient(this.component, () => this.stripe());
+  }
+
   get costRecovery() {
     return new CostRecoveryClient(this.component, () => this.stripe());
   }

package/src/client/payoutPolicy.test.ts

@@ -0,0 +1,320 @@
+// @vitest-environment edge-runtime
+import { convexTest } from "convex-test";
+import { makeFunctionReference, type FunctionReference } from "convex/server";
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import type { Component, RunCtx } from "./helpers.js";
+import schema from "../component/schema.js";
+const modules = import.meta.glob("../component/**/*.*s");
+const symbol = Symbol.for("toReferencePath");
+const ref = (path: string) => ({ [symbol]: `betterStripe/${path}` });
+const component = {
+  payoutPolicy: { queries: { get: ref("payoutPolicy/queries/get") } },
+} as unknown as Component;
+const scope = { accountId: "acct_recipient", ownerKey: "user_1" };
+const options = {
+  ...scope,
+  operationKey: "enable",
+  expectedRevision: -1,
+  mode: "custom" as const,
+  thresholds: [{ currency: "usd", amount: 1000 }],
+  consent: true as const,
+};
+async function feature() {
+  const mod = (await import("./payoutPolicy.js").catch(() => ({}))) as {
+    PayoutPolicyClient?: typeof import("./payoutPolicy.js").PayoutPolicyClient;
+  };
+  expect(
+    mod.PayoutPolicyClient,
+    "public payout-policy client is missing",
+  ).toBeTypeOf("function");
+  return mod.PayoutPolicyClient!;
+}
+async function setup() {
+  const t = convexTest(schema, modules);
+  const path = (r: Record<symbol, string>) =>
+    r[symbol].replace("betterStripe/", "").replace(/\/(\w+)$/, ":$1");
+  const ctx = {
+    runQuery: async (
+      r: Record<symbol, string>,
+      args: Record<string, unknown>,
+    ) => t.query(makeFunctionReference<"query">(path(r)), args),
+    runMutation: async (
+      r: Record<symbol, string>,
+      args: Record<string, unknown>,
+    ) => t.mutation(makeFunctionReference<"mutation">(path(r)), args),
+  } as unknown as RunCtx;
+  let schedule: Record<string, unknown> = {
+    interval: "weekly",
+    weekly_payout_days: ["monday"],
+  };
+  const provider = {
+    v2: {
+      core: {
+        accounts: {
+          retrieve: vi.fn().mockResolvedValue({
+            id: scope.accountId,
+            dashboard: "none",
+            identity: { country: "US" },
+          }),
+        },
+      },
+    },
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: "usd", amount: 0 }],
+        pending: [],
+      }),
+    },
+    payouts: { list: vi.fn().mockResolvedValue({ data: [], has_more: false }) },
+    balanceSettings: {
+      retrieve: vi.fn(async () => ({
+        payments: { payouts: { status: "enabled", schedule } },
+      })),
+      update: vi.fn(
+        async (
+          args: {
+            payments: { payouts: { schedule: Record<string, unknown> } };
+          },
+          _request?: unknown,
+        ) => {
+          schedule = args.payments.payouts.schedule;
+          return { payments: { payouts: { status: "enabled", schedule } } };
+        },
+      ),
+    },
+  };
+  const Client = await feature();
+  const client = new Client(component, () => provider as unknown as Stripe);
+  return {
+    t,
+    ctx,
+    provider,
+    client,
+    setSchedule: (value: Record<string, unknown>) => {
+      schedule = value;
+    },
+  };
+}
+it("persists original provider settings, verifies manual schedule and restores opt-out", async () => {
+  const { client, ctx, provider } = await setup();
+  const prepared = await client.prepare(ctx, options);
+  expect(prepared.status).toBe("prepared");
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+  expect((await client.get(ctx, scope))!.status).toBe("changing");
+  const applied = await client.apply(ctx, { ...scope, operationKey: "enable" });
+  expect(applied.status).toBe("ready");
+  expect(await client.verify(ctx, scope)).toMatchObject({
+    status: "verified",
+    providerMinimum: null,
+  });
+  await client.prepare(ctx, {
+    ...options,
+    operationKey: "disable",
+    expectedRevision: 0,
+    mode: "stripe_managed",
+    thresholds: [],
+    consent: undefined,
+  });
+  await client.apply(ctx, { ...scope, operationKey: "disable" });
+  expect(provider.balanceSettings.update.mock.calls[1][0]).toMatchObject({
+    payments: {
+      payouts: {
+        schedule: { interval: "weekly", weekly_payout_days: ["monday"] },
+      },
+    },
+  });
+  expect((await client.get(ctx, scope))!.mode).toBe("stripe_managed");
+});
+it("recovers provider success after a failed persistence write without changing the request", async () => {
+  const { client, ctx, provider } = await setup();
+  await client.prepare(ctx, options);
+  const original = ctx.runMutation!;
+  let fail = true;
+  ctx.runMutation = (async (
+    ref: FunctionReference<"mutation", "public" | "internal">,
+    args: Record<string, unknown>,
+  ) => {
+    if (
+      fail &&
+      (ref as unknown as Record<symbol, string>)[symbol].endsWith("/confirm")
+    ) {
+      fail = false;
+      throw new Error("write failed");
+    }
+    return original(ref, args);
+  }) as RunCtx["runMutation"];
+  await expect(
+    client.apply(ctx, { ...scope, operationKey: "enable" }),
+  ).rejects.toThrow("write failed");
+  expect((await client.get(ctx, scope))!.status).toBe("changing");
+  expect(
+    (await client.apply(ctx, { ...scope, operationKey: "enable" })).status,
+  ).toBe("ready");
+  expect(provider.balanceSettings.update).toHaveBeenCalledTimes(1);
+  expect(provider.balanceSettings.update.mock.calls[0][1]).toMatchObject({
+    stripeAccount: scope.accountId,
+    idempotencyKey: expect.any(String),
+  });
+});
+it("does not adopt arbitrary existing balances or in-flight payouts as earnings", async () => {
+  const { client, ctx, provider } = await setup();
+  provider.balance.retrieve.mockResolvedValueOnce({
+    available: [{ currency: "usd", amount: 100 }],
+    pending: [],
+  });
+  expect(await client.prepare(ctx, options)).toMatchObject({
+    status: "migration_required",
+    reason: "existing_balance",
+  });
+  expect(await client.get(ctx, scope))!.toBeNull();
+  provider.payouts.list.mockResolvedValueOnce({
+    data: [{ id: "po_old" }],
+    has_more: false,
+  } as never);
+  expect(await client.prepare(ctx, options)).toMatchObject({
+    status: "migration_required",
+    reason: "in_flight_payouts",
+  });
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+});
+it("returns a limitation for Dashboard withdrawal bypass and never changes account liability", async () => {
+  const { client, ctx, provider } = await setup();
+  provider.v2.core.accounts.retrieve.mockResolvedValueOnce({
+    id: scope.accountId,
+    dashboard: "full",
+    identity: { country: "US" },
+  });
+  expect(await client.prepare(ctx, options)).toMatchObject({
+    status: "unsupported",
+    reason: "payout_control_unverified",
+  });
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+});
+it("fails closed on drift and leaves an unknown provider write pending for retry", async () => {
+  const { client, ctx, provider, setSchedule } = await setup();
+  await client.prepare(ctx, options);
+  provider.balanceSettings.update.mockRejectedValueOnce(
+    new Error("network unavailable"),
+  );
+  await expect(
+    client.apply(ctx, { ...scope, operationKey: "enable" }),
+  ).rejects.toThrow("network unavailable");
+  expect((await client.get(ctx, scope))!.status).toBe("changing");
+  setSchedule({ interval: "daily" });
+  expect(
+    await client.apply(ctx, { ...scope, operationKey: "enable" }),
+  ).toMatchObject({ status: "schedule_drift" });
+});
+it("requires consent and scope/version validation before provider access", async () => {
+  const { client, ctx, provider } = await setup();
+  await expect(
+    client.prepare(ctx, { ...options, consent: undefined }),
+  ).rejects.toThrow(/consent/);
+  await expect(
+    client.prepare(ctx, { ...options, expectedRevision: 0.5 }),
+  ).rejects.toThrow(/revision/);
+  expect(provider.v2.core.accounts.retrieve).not.toHaveBeenCalled();
+});
+it("restores original settings at the holding deadline, without extending it", async () => {
+  const { client, ctx, t, provider } = await setup();
+  await client.prepare(ctx, options);
+  await client.apply(ctx, { ...scope, operationKey: "enable" });
+  expect((await client.expire(ctx, scope)).status).toBe("not_due");
+  await t.run(async (c) => {
+    const p = await c.db.query("payoutPolicies").first();
+    await c.db.patch(p!._id, { holdDeadline: Date.now() - 1 });
+  });
+  expect((await client.expire(ctx, scope)).status).toBe("ready");
+  expect((await client.get(ctx, scope))!.mode).toBe("stripe_managed");
+  expect(provider.balanceSettings.update).toHaveBeenCalledTimes(2);
+});
+it("re-checks live control on every payout-policy verification", async () => {
+  const { client, ctx, setSchedule } = await setup();
+  await client.prepare(ctx, options);
+  await client.apply(ctx, { ...scope, operationKey: "enable" });
+  setSchedule({ interval: "daily" });
+  expect(await client.verify(ctx, scope)).toMatchObject({
+    status: "schedule_drift",
+  });
+});
+it("reports a staged initial enable as pending rather than unconfigured", async () => {
+  const { client, ctx } = await setup();
+  await client.prepare(ctx, options);
+  expect(await client.verify(ctx, scope)).toMatchObject({
+    status: "pending_operation",
+  });
+});
+it("restores opt-out even after exclusive Dashboard control is lost", async () => {
+  const { client, ctx, provider } = await setup();
+  await client.prepare(ctx, options);
+  await client.apply(ctx, { ...scope, operationKey: "enable" });
+  provider.v2.core.accounts.retrieve.mockResolvedValue({
+    id: scope.accountId,
+    dashboard: "full",
+    identity: { country: "US" },
+  });
+  expect(
+    (
+      await client.prepare(ctx, {
+        ...options,
+        operationKey: "off-lost-control",
+        expectedRevision: 0,
+        mode: "stripe_managed",
+        thresholds: [],
+      })
+    ).status,
+  ).toBe("prepared");
+  expect(
+    (await client.apply(ctx, { ...scope, operationKey: "off-lost-control" }))
+      .status,
+  ).toBe("ready");
+});
+it("cancels an expired, unattempted enable without switching a live schedule to manual", async () => {
+  const { client, ctx, t, provider } = await setup();
+  await client.prepare(ctx, options);
+  await t.run(async (c) => {
+    const p = await c.db.query("payoutPolicies").first();
+    await c.db.patch(p!._id, { holdDeadline: Date.now() - 1 });
+  });
+  await client.expire(ctx, scope);
+  expect((await client.get(ctx, scope))!.mode).toBe("stripe_managed");
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+});
+it("reports explicit Stripe permission denials and keeps uncertain operations held", async () => {
+  const { client, ctx, provider } = await setup();
+  const denied = () =>
+    Object.assign(new Error("permission denied"), {
+      type: "StripePermissionError",
+    });
+  provider.v2.core.accounts.retrieve.mockRejectedValueOnce(denied());
+  expect(await client.prepare(ctx, options)).toMatchObject({
+    status: "unsupported",
+    reason: "provider_permission_denied",
+  });
+  await client.prepare(ctx, options);
+  provider.balanceSettings.update.mockRejectedValueOnce(denied());
+  expect(
+    await client.apply(ctx, { ...scope, operationKey: "enable" }),
+  ).toMatchObject({
+    status: "unsupported",
+    reason: "provider_permission_denied",
+  });
+  expect((await client.get(ctx, scope))!.status).toBe("changing");
+});
+it("rechecks delayed activation and cancels safely when funds arrive after preparation", async () => {
+  const { client, ctx, provider } = await setup();
+  await client.prepare(ctx, options);
+  provider.balance.retrieve.mockResolvedValueOnce({
+    available: [{ currency: "usd", amount: 100 }],
+    pending: [],
+  });
+  expect(
+    await client.apply(ctx, { ...scope, operationKey: "enable" }),
+  ).toMatchObject({ status: "migration_required", reason: "existing_balance" });
+  expect(provider.balanceSettings.update).not.toHaveBeenCalled();
+  expect(await client.get(ctx, scope)).toMatchObject({
+    mode: "stripe_managed",
+    status: "ready",
+  });
+});