@fantastic.dev/better-stripe 0.17.1 → 0.18.0

package/src/component/payoutPolicy/mutations.ts

@@ -0,0 +1,225 @@
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import {
+  prepareFields,
+  operationDoc,
+  scopeFields,
+  schedule,
+} from "./schema.js";
+import {
+  canonicalSchedule,
+  canonicalThresholds,
+  readPolicy,
+  holdingDays,
+  same,
+  validateScope,
+} from "./helpers.js";
+export const prepare = mutation({
+  args: prepareFields,
+  returns: operationDoc,
+  handler: async (ctx, input) => {
+    validateScope(input);
+    if (
+      !input.operationKey.trim() ||
+      input.operationKey.length > 180 ||
+      /[\r\n]/.test(input.operationKey) ||
+      !Number.isSafeInteger(input.expectedRevision) ||
+      input.expectedRevision < -1 ||
+      input.expectedRevision >= Number.MAX_SAFE_INTEGER
+    )
+      throw new Error("Invalid payout policy operation identity or revision.");
+    const days = holdingDays(input.country);
+    const args = {
+      ...input,
+      observedSchedule: canonicalSchedule(input.observedSchedule),
+      thresholds: canonicalThresholds(
+        input.thresholds,
+        input.mode === "custom",
+      ),
+    };
+    const old = await ctx.db
+      .query("payoutPolicyOperations")
+      .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (old) {
+      if (
+        old.accountId !== args.accountId ||
+        old.ownerKey !== args.ownerKey ||
+        old.expectedRevision !== args.expectedRevision ||
+        old.mode !== args.mode ||
+        old.country !== args.country ||
+        old.observedAt !== args.observedAt ||
+        !same(old.thresholds, args.thresholds) ||
+        !same(old.observedSchedule, args.observedSchedule)
+      )
+        throw new Error("Payout policy operation identity cannot be reused.");
+      return old;
+    }
+    if (
+      input.observedAt !== undefined &&
+      (!Number.isSafeInteger(input.observedAt) ||
+        input.observedAt > Date.now() ||
+        input.observedAt < Date.now() - 600000)
+    )
+      throw new Error("Payout policy observation is stale or in the future.");
+    const policy = await readPolicy(ctx, args);
+    if (policy?.status === "changing")
+      throw new Error("A payout policy operation is pending.");
+    if ((policy?.revision ?? -1) !== args.expectedRevision)
+      throw new Error("Payout policy revision changed.");
+    if (
+      policy?.mode === "custom" &&
+      args.observedSchedule.interval !== "manual"
+    )
+      throw new Error("Payout schedule drift requires reconciliation.");
+    if (
+      policy?.mode === "custom" &&
+      policy.country !== args.country &&
+      args.mode === "custom"
+    )
+      throw new Error("Payout policy country changed.");
+    if (
+      args.mode === "custom" &&
+      policy?.mode !== "custom" &&
+      args.observedSchedule.interval === "manual"
+    )
+      throw new Error("An existing manual schedule requires migration.");
+    const previousSchedule =
+      policy?.mode === "custom"
+        ? policy.previousSchedule!
+        : args.observedSchedule;
+    const targetSchedule =
+      args.mode === "custom"
+        ? { interval: "manual" as const }
+        : previousSchedule;
+    const revision = args.expectedRevision + 1;
+    const operationId = await ctx.db.insert("payoutPolicyOperations", {
+      ...args,
+      revision,
+      previousSchedule,
+      targetSchedule,
+      status: "pending",
+    });
+    const next = {
+      accountId: args.accountId,
+      ownerKey: args.ownerKey,
+      revision,
+      mode: policy?.mode ?? ("stripe_managed" as const),
+      thresholds: policy?.thresholds ?? [],
+      status: "changing" as const,
+      operationKey: args.operationKey,
+      country: args.country,
+      previousSchedule,
+      holdDeadline:
+        policy?.holdDeadline ??
+        (args.mode === "custom"
+          ? (args.observedAt ?? Date.now()) + days * 86400000
+          : undefined),
+    };
+    if (policy) await ctx.db.patch("payoutPolicies", policy._id, next);
+    else await ctx.db.insert("payoutPolicies", next);
+    return (await ctx.db.get("payoutPolicyOperations", operationId))!;
+  },
+});
+export const confirm = mutation({
+  args: {
+    ...scopeFields,
+    operationKey: v.string(),
+    observedSchedule: schedule,
+  },
+  returns: operationDoc,
+  handler: async (ctx, args) => {
+    const policy = await readPolicy(ctx, args);
+    const op = await ctx.db
+      .query("payoutPolicyOperations")
+      .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (!op || op.accountId !== args.accountId || op.ownerKey !== args.ownerKey)
+      throw new Error("Payout policy operation identity does not match.");
+    if (!same(canonicalSchedule(args.observedSchedule), op.targetSchedule))
+      throw new Error("Provider payout schedule was not confirmed.");
+    if (op.status === "complete") return op;
+    if (op.status === "canceled")
+      throw new Error("Payout policy operation was canceled.");
+    if (
+      !policy ||
+      policy.operationKey !== op.operationKey ||
+      policy.revision !== op.revision
+    )
+      throw new Error("Payout policy revision changed.");
+    await ctx.db.patch("payoutPolicyOperations", op._id, {
+      status: "complete",
+    });
+    await ctx.db.patch("payoutPolicies", policy._id, {
+      mode: op.mode,
+      thresholds: op.thresholds,
+      status: "ready",
+      ...(op.mode === "stripe_managed"
+        ? { previousSchedule: undefined, holdDeadline: undefined }
+        : {}),
+    });
+    return (await ctx.db.get("payoutPolicyOperations", op._id))!;
+  },
+});
+export const beginAttempt = mutation({
+  args: { ...scopeFields, operationKey: v.string() },
+  returns: operationDoc,
+  handler: async (ctx, args) => {
+    const policy = await readPolicy(ctx, args);
+    const op = await ctx.db
+      .query("payoutPolicyOperations")
+      .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (
+      !op ||
+      op.accountId !== args.accountId ||
+      op.ownerKey !== args.ownerKey ||
+      op.status !== "pending" ||
+      policy?.operationKey !== op.operationKey ||
+      policy.status !== "changing"
+    )
+      throw new Error("Payout policy operation is not pending.");
+    if (!op.attempted)
+      await ctx.db.patch("payoutPolicyOperations", op._id, { attempted: true });
+    return (await ctx.db.get("payoutPolicyOperations", op._id))!;
+  },
+});
+export const cancelUnattempted = mutation({
+  args: {
+    ...scopeFields,
+    operationKey: v.string(),
+    observedSchedule: schedule,
+  },
+  returns: operationDoc,
+  handler: async (ctx, args) => {
+    const policy = await readPolicy(ctx, args);
+    const op = await ctx.db
+      .query("payoutPolicyOperations")
+      .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (
+      !op ||
+      op.accountId !== args.accountId ||
+      op.ownerKey !== args.ownerKey ||
+      op.attempted ||
+      op.status !== "pending" ||
+      policy?.operationKey !== op.operationKey ||
+      policy.status !== "changing"
+    )
+      throw new Error(
+        "An attempted payout policy operation cannot be canceled.",
+      );
+    if (!same(canonicalSchedule(args.observedSchedule), op.observedSchedule))
+      throw new Error("Provider schedule changed before cancellation.");
+    await ctx.db.patch("payoutPolicyOperations", op._id, {
+      status: "canceled",
+    });
+    await ctx.db.patch("payoutPolicies", policy._id, {
+      status: "ready",
+      ...(policy.mode === "stripe_managed"
+        ? { previousSchedule: undefined, holdDeadline: undefined }
+        : {}),
+    });
+    return (await ctx.db.get("payoutPolicyOperations", op._id))!;
+  },
+});

package/src/component/payoutPolicy/queries.ts

@@ -0,0 +1,56 @@
+import { paginationOptsValidator } from "convex/server";
+import { v } from "convex/values";
+import { query } from "../_generated/server.js";
+import { scopeFields, policyDoc, operationDoc } from "./schema.js";
+import { readPolicy, validateScope } from "./helpers.js";
+export const get = query({
+  args: scopeFields,
+  returns: v.union(policyDoc, v.null()),
+  handler: readPolicy,
+});
+export const operation = query({
+  args: { ...scopeFields, operationKey: v.string() },
+  returns: v.union(operationDoc, v.null()),
+  handler: async (ctx, args) => {
+    validateScope(args);
+    const op = await ctx.db
+      .query("payoutPolicyOperations")
+      .withIndex("by_operation", (q) => q.eq("operationKey", args.operationKey))
+      .unique();
+    if (
+      op &&
+      (op.accountId !== args.accountId || op.ownerKey !== args.ownerKey)
+    )
+      throw new Error("Payout policy operation identity does not match.");
+    return op;
+  },
+});
+export const due = query({
+  args: { now: v.number(), paginationOpts: paginationOptsValidator },
+  returns: v.object({
+    page: v.array(policyDoc),
+    continueCursor: v.string(),
+    isDone: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    if (
+      !Number.isSafeInteger(args.now) ||
+      args.now < 0 ||
+      !Number.isInteger(args.paginationOpts.numItems) ||
+      args.paginationOpts.numItems < 1 ||
+      args.paginationOpts.numItems > 100
+    )
+      throw new Error("Invalid payout policy due page.");
+    const page = await ctx.db
+      .query("payoutPolicies")
+      .withIndex("by_deadline", (q) =>
+        q.gt("holdDeadline", 0).lte("holdDeadline", args.now),
+      )
+      .paginate(args.paginationOpts);
+    return {
+      page: page.page,
+      continueCursor: page.continueCursor,
+      isDone: page.isDone,
+    };
+  },
+});

package/src/component/payoutPolicy/schema.ts

@@ -0,0 +1,67 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+export const scopeFields = { accountId: v.string(), ownerKey: v.string() };
+export const schedule = v.object({
+  interval: v.union(
+    v.literal("daily"),
+    v.literal("weekly"),
+    v.literal("monthly"),
+    v.literal("manual"),
+  ),
+  weeklyDays: v.optional(v.array(v.string())),
+  monthlyDays: v.optional(v.array(v.number())),
+});
+export const mode = v.union(v.literal("stripe_managed"), v.literal("custom"));
+export const thresholds = v.array(
+  v.object({ currency: v.string(), amount: v.number() }),
+);
+export const prepareFields = {
+  ...scopeFields,
+  operationKey: v.string(),
+  expectedRevision: v.number(),
+  mode,
+  thresholds,
+  country: v.string(),
+  observedSchedule: schedule,
+  observedAt: v.optional(v.number()),
+};
+export const policyFields = {
+  ...scopeFields,
+  revision: v.number(),
+  mode,
+  thresholds,
+  status: v.union(v.literal("changing"), v.literal("ready")),
+  operationKey: v.string(),
+  country: v.string(),
+  previousSchedule: v.optional(schedule),
+  holdDeadline: v.optional(v.number()),
+};
+export const operationFields = {
+  ...prepareFields,
+  revision: v.number(),
+  previousSchedule: schedule,
+  targetSchedule: schedule,
+  status: v.union(
+    v.literal("pending"),
+    v.literal("complete"),
+    v.literal("canceled"),
+  ),
+  attempted: v.optional(v.boolean()),
+};
+export const policyDoc = v.object({
+  ...policyFields,
+  _id: v.id("payoutPolicies"),
+  _creationTime: v.number(),
+});
+export const operationDoc = v.object({
+  ...operationFields,
+  _id: v.id("payoutPolicyOperations"),
+  _creationTime: v.number(),
+});
+export const policiesTable = defineTable(policyFields)
+  .index("by_account", ["accountId"])
+  .index("by_deadline", ["holdDeadline"]);
+export const operationsTable = defineTable(operationFields).index(
+  "by_operation",
+  ["operationKey"],
+);

package/src/component/schema.ts

@@ -1,3 +1,4 @@
+import { policiesTable, operationsTable } from "./payoutPolicy/schema.js";
 import { currencyTotalsTable } from "./earnings/schema.js";
 import {
   claimsTable,
@@ -31,6 +32,8 @@ import { pricesTable, productsTable } from "./products/schema";
 import { webhookEventsTable } from "./webhooks/schema";
 
 export default defineSchema({
+  payoutPolicies: policiesTable,
+  payoutPolicyOperations: operationsTable,
   currencyTotals: currencyTotalsTable,
   recoveryClaims: claimsTable,
   recoveryBalances: balancesTable,