feat(core): make provider layer pluggable with batch product sync and preflight checks

Replace single syncProduct with batch syncProducts on PaymentProvider interface.
Add provider preflight checks (external customers, cross-provider subscriptions)
to push and status CLI commands. Lazy provider customer creation — customers are
created on the provider only when needed (subscribe, portal, payment method).
Remove checkout fallback from upgrade flow since active subscriptions already
have payment methods on file. Exclude scheduled subscriptions from duplicate
detection warnings.

Author: maxktz

CLAUDE.md

@@ -3,3 +3,6 @@
 - do never commit unless you're asked to.
 - only commit what you're asked to commit, no adding extra changes unless asked
 - when person asks the question, but not asking you to do the thing, you only answer the question, you don't do the thing you're not asked to do!
+- STOP before any file edit. Ask yourself: "Did they explicitly say to make changes?" If no → DO NOT EDIT. Present findings and wait.
+- "find", "check", "investigate", "research", "explain", "look into" = RESEARCH ONLY. Never edit code.
+- The ONLY trigger for code changes is explicit words like: "do it", "fix it", "implement", "make the change", "go ahead"

e2e/smoke/setup.ts

@@ -150,11 +150,11 @@ export async function createTestPayKit(): Promise<TestPayKit> {
   // confirmation which isn't possible in automated tests.
   (ctx.provider as unknown as Record<string, unknown>).createSubscription = async (data: {
     providerCustomerId: string;
-    providerPriceId: string;
+    providerProduct: Record<string, string>;
   }) => {
     const sub = await stripeClient.subscriptions.create({
       customer: data.providerCustomerId,
-      items: [{ price: data.providerPriceId }],
+      items: [{ price: data.providerProduct.priceId }],
       payment_behavior: "allow_incomplete",
       expand: ["latest_invoice"],
     });

packages/paykit/src/cli/commands/push.ts

@@ -5,7 +5,9 @@ import { Command } from "commander";
 import picocolors from "picocolors";
 
 import {
+  checkActiveSubscriptionsOnOtherProvider,
   checkProvider,
+  checkProviderCustomers,
   createPool,
   formatProductDiffs,
   loadCliDeps,
@@ -60,6 +62,24 @@ async function pushAction(options: { config?: string; cwd: string; yes?: boolean
     const { ctx, diffs } = await loadProductDiffs(config, deps);
     const hasChanges = diffs.some((d) => d.action !== "unchanged");
 
+    // Preflight checks
+    s.message("Running preflight checks");
+    const providerId = config.options.provider.id;
+    const [subscriptionErrors, customerErrors] = await Promise.all([
+      checkActiveSubscriptionsOnOtherProvider(ctx, providerId),
+      checkProviderCustomers(ctx, providerResult.customerSample),
+    ]);
+    const allErrors = [...providerResult.errors, ...subscriptionErrors, ...customerErrors];
+
+    if (allErrors.length > 0) {
+      s.stop("");
+      for (const err of allErrors) {
+        p.log.error(err);
+      }
+      p.cancel("Push blocked by preflight checks");
+      process.exit(1);
+    }
+
     s.stop("");
 
     // Render all sections

packages/paykit/src/cli/commands/status.ts

@@ -5,8 +5,10 @@ import { Command } from "commander";
 import picocolors from "picocolors";
 
 import {
+  checkActiveSubscriptionsOnOtherProvider,
   checkDatabase,
   checkProvider,
+  checkProviderCustomers,
   createPool,
   formatProductDiffs,
   loadCliDeps,
@@ -85,6 +87,8 @@ async function statusAction(options: {
 
   const pendingMigrations = dbResult.pendingMigrations;
 
+  let preflightErrors: string[] = [...providerResult.errors];
+
   let webhookStatus: string;
   if (providerResult.webhookEndpoints === null) {
     webhookStatus = `${picocolors.dim("?")} Could not check webhook status`;
@@ -107,6 +111,13 @@ async function statusAction(options: {
   } else {
     const { ctx, diffs } = await loadProductDiffs(config, deps);
 
+    const providerId = config.options.provider.id;
+    const [subscriptionErrors, customerErrors] = await Promise.all([
+      checkActiveSubscriptionsOnOtherProvider(ctx, providerId),
+      checkProviderCustomers(ctx, providerResult.customerSample),
+    ]);
+    preflightErrors = [...preflightErrors, ...subscriptionErrors, ...customerErrors];
+
     if (diffs.length === 0) {
       productsBlock = `Products\n  ${picocolors.dim("No products defined")}`;
     } else {
@@ -149,8 +160,13 @@ async function statusAction(options: {
 
   p.log.info(productsBlock);
 
+  if (preflightErrors.length > 0) {
+    const errorLines = preflightErrors.map((err) => `  ${picocolors.red("✖")} ${err}`);
+    p.log.error(`Preflight\n${errorLines.join("\n")}`);
+  }
+
   const needsMigration = pendingMigrations > 0;
-  const hasIssues = needsMigration || needsSync;
+  const hasIssues = needsMigration || needsSync || preflightErrors.length > 0;
 
   if (hasIssues) {
     const action =

packages/paykit/src/cli/utils/shared.ts

@@ -103,6 +103,8 @@ export async function checkDatabase(
 
 export interface ProviderCheckResult {
   account: { ok: true; displayName: string; mode: string } | { ok: false; message: string };
+  customerSample: Array<{ providerEmail: string; paykitCustomerId: string | null }>;
+  errors: string[];
   webhookEndpoints: Array<{ url: string; status: string }> | null;
 }
 
@@ -116,30 +118,94 @@ export async function checkProvider(
     if (!result) {
       return {
         account: { ok: true, displayName: providerConfig.name, mode: "unknown" },
+        customerSample: [],
+        errors: [],
         webhookEndpoints: null,
       };
     }
 
     if (result.ok) {
       return {
         account: { ok: true, displayName: result.displayName, mode: result.mode },
+        customerSample: result.customerSample ?? [],
+        errors: result.errors ?? [],
         webhookEndpoints: result.webhookEndpoints ?? null,
       };
     }
 
     return {
       account: { ok: false, message: result.error ?? "Provider check failed" },
+      customerSample: [],
+      errors: result.errors ?? [],
       webhookEndpoints: null,
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : "Provider check failed";
     return {
       account: { ok: false, message },
+      customerSample: [],
+      errors: [],
       webhookEndpoints: null,
     };
   }
 }
 
+export async function checkProviderCustomers(
+  ctx: PayKitContext,
+  customerSample: ProviderCheckResult["customerSample"],
+): Promise<string[]> {
+  if (customerSample.length === 0) return [];
+
+  const message = `${ctx.provider.name} account has existing customers that are not synced with PayKit. Use a fresh ${ctx.provider.name} account or remove existing customers from it before proceeding.`;
+
+  const hasUnmanaged = customerSample.some((s) => !s.paykitCustomerId);
+  if (hasUnmanaged) return [message];
+
+  const paykitIds = customerSample
+    .map((s) => s.paykitCustomerId)
+    .filter((id): id is string => id !== null);
+
+  if (paykitIds.length > 0) {
+    const { customer } = await import("../../database/schema");
+    const { inArray } = await import("drizzle-orm");
+    const rows = await ctx.database
+      .select({ id: customer.id })
+      .from(customer)
+      .where(inArray(customer.id, paykitIds));
+    if (rows.length < paykitIds.length) return [message];
+  }
+
+  return [];
+}
+
+export async function checkActiveSubscriptionsOnOtherProvider(
+  ctx: PayKitContext,
+  currentProviderId: string,
+): Promise<string[]> {
+  const errors: string[] = [];
+  const { subscription } = await import("../../database/schema");
+  const { and, eq, ne, isNotNull, count } = await import("drizzle-orm");
+  const rows = await ctx.database
+    .select({ count: count(), providerId: subscription.providerId })
+    .from(subscription)
+    .where(
+      and(
+        eq(subscription.status, "active"),
+        isNotNull(subscription.providerId),
+        ne(subscription.providerId, currentProviderId),
+      ),
+    )
+    .groupBy(subscription.providerId);
+  for (const row of rows) {
+    if (row.count > 0 && row.providerId) {
+      errors.push(
+        `Found ${String(row.count)} active subscription${row.count === 1 ? "" : "s"} linked to "${row.providerId}" but current provider is "${currentProviderId}". Existing subscriptions must be canceled before switching providers.`,
+      );
+    }
+  }
+  return errors;
+}
+
 export async function loadProductDiffs(
   config: LoadedConfig,
   deps: Pick<CliDeps, "createContext" | "dryRunSyncProducts">,

packages/paykit/src/customer/__tests__/customer.service.test.ts

@@ -76,7 +76,7 @@ describe("customer/service", () => {
       listActiveSubscriptions: vi.fn(),
       resumeSubscription: vi.fn(),
       scheduleSubscriptionChange: vi.fn(),
-      syncProduct: vi.fn(),
+      syncProducts: vi.fn(),
       updateSubscription: vi.fn(),
       createCustomer: vi.fn().mockResolvedValue({
         providerCustomer: {
@@ -173,7 +173,7 @@ describe("customer/service", () => {
       listActiveSubscriptions: vi.fn(),
       resumeSubscription: vi.fn(),
       scheduleSubscriptionChange: vi.fn(),
-      syncProduct: vi.fn(),
+      syncProducts: vi.fn(),
       updateSubscription: vi.fn(),
       createCustomer: vi.fn().mockResolvedValue({
         providerCustomer: {

packages/paykit/src/customer/customer.api.ts

@@ -4,10 +4,10 @@ import { definePayKitMethod, returnUrl } from "../api/define-route";
 import { PayKitError, PAYKIT_ERROR_CODES } from "../core/errors";
 import {
   getCustomerWithDetails,
-  getProviderCustomerIdForCustomer,
   hardDeleteCustomer,
   listCustomers,
   upsertCustomer as upsertCustomerService,
+  upsertProviderCustomer,
 } from "./customer.service";
 
 const upsertCustomerSchema = z.object({
@@ -60,15 +60,10 @@ export const customerPortal = definePayKitMethod(
     },
   },
   async (ctx) => {
-    const providerCustomerId = await getProviderCustomerIdForCustomer(ctx.paykit.database, {
+    const { providerCustomerId } = await upsertProviderCustomer(ctx.paykit, {
       customerId: ctx.customer.id,
-      providerId: ctx.paykit.provider.id,
     });
 
-    if (!providerCustomerId) {
-      throw PayKitError.from("NOT_FOUND", PAYKIT_ERROR_CODES.PROVIDER_CUSTOMER_NOT_FOUND);
-    }
-
     const { url } = await ctx.paykit.provider.createPortalSession({
       providerCustomerId,
       returnUrl: ctx.input.returnUrl,

packages/paykit/src/customer/customer.service.ts

@@ -182,17 +182,8 @@ export async function upsertCustomer(
 ): Promise<Customer> {
   const syncedCustomer = await syncCustomer(ctx.database, input);
   await ensureDefaultPlansForCustomer(ctx, syncedCustomer.id);
-  const { providerCustomer } = await upsertProviderCustomer(ctx, {
-    customerId: syncedCustomer.id,
-  });
 
-  return {
-    ...syncedCustomer,
-    provider: {
-      ...(syncedCustomer.provider ?? {}),
-      [ctx.provider.id]: providerCustomer,
-    },
-  };
+  return syncedCustomer;
 }
 
 export async function getCustomerById(
@@ -247,6 +238,7 @@ export async function getCustomerWithDetails(
 
   const subscriptionsByGroup = new Map<string, string[]>();
   for (const row of subRows) {
+    if (row.status === "scheduled") continue;
     const currentGroup = subscriptionsByGroup.get(row.planGroup) ?? [];
     currentGroup.push(row.planId);
     subscriptionsByGroup.set(row.planGroup, currentGroup);

packages/paykit/src/database/schema.ts

@@ -64,7 +64,7 @@ export const feature = pgTable("feature", {
   updatedAt,
 });
 
-type ProviderProductMap = Record<string, { productId: string; priceId: string | null }>;
+type ProviderProductMap = Record<string, Record<string, string>>;
 
 export const product = pgTable(
   "product",

packages/paykit/src/product/product-sync.service.ts

@@ -95,6 +95,15 @@ export async function syncProducts(ctx: PayKitContext): Promise<SyncProductResul
     await upsertFeature(ctx.database, schemaFeature);
   }
 
+  const paidPlansToSync: Array<{
+    id: string;
+    name: string;
+    priceAmount: number;
+    priceInterval: string;
+    existingProviderProduct: Record<string, string> | null;
+    storedProductInternalId: string;
+  }> = [];
+
   for (const plan of ctx.plans.plans) {
     const existing = await getLatestProductSnapshot(ctx.database, plan.id);
     const existingProviderProduct = existing
@@ -151,24 +160,13 @@ export async function syncProducts(ctx: PayKitContext): Promise<SyncProductResul
     }
 
     if (storedProduct.priceAmount !== null && storedProduct.priceInterval !== null) {
-      const shouldReuseExistingPriceId =
-        action !== "created" && existingProviderProduct?.priceId !== undefined;
-      const providerResult = await ctx.provider.syncProduct({
-        existingProviderPriceId: shouldReuseExistingPriceId
-          ? (existingProviderProduct?.priceId ?? null)
-          : null,
-        existingProviderProductId: existingProviderProduct?.productId ?? null,
+      paidPlansToSync.push({
+        existingProviderProduct: existingProviderProduct ?? null,
         id: plan.id,
         name: plan.name,
         priceAmount: storedProduct.priceAmount,
         priceInterval: storedProduct.priceInterval,
-      });
-
-      await upsertProviderProduct(ctx.database, {
-        productInternalId: storedProduct.internalId,
-        providerId,
-        providerProductId: providerResult.providerProductId,
-        providerPriceId: providerResult.providerPriceId,
+        storedProductInternalId: storedProduct.internalId,
       });
     }
 
@@ -179,5 +177,28 @@ export async function syncProducts(ctx: PayKitContext): Promise<SyncProductResul
     });
   }
 
+  if (paidPlansToSync.length > 0) {
+    const providerResults = await ctx.provider.syncProducts({
+      products: paidPlansToSync.map((p) => ({
+        existingProviderProduct: p.existingProviderProduct,
+        id: p.id,
+        name: p.name,
+        priceAmount: p.priceAmount,
+        priceInterval: p.priceInterval,
+      })),
+    });
+
+    for (const providerResult of providerResults.results) {
+      const plan = paidPlansToSync.find((p) => p.id === providerResult.id);
+      if (plan) {
+        await upsertProviderProduct(ctx.database, {
+          productInternalId: plan.storedProductInternalId,
+          providerId,
+          providerProduct: providerResult.providerProduct,
+        });
+      }
+    }
+  }
+
   return results;
 }