feat(webapp,plugins): provision a free plan contract through the billing plugin when an organization is created

When the billing plugin is enabled and its free plan contracts are turned on, creating an organization also provisions a free plan contract through the plugin, before the organization is returned. Provisioning is idempotent and fails closed: if it can't complete, the new organization is removed and creation fails. With the option off (the default), organization creation behaves as before.

Mono-RevId: e9fe47352051c004483603a4006ea9246ed60cba

Author: 0ski

apps/webapp/app/env.server.ts

@@ -2839,6 +2839,7 @@ const EnvironmentSchema = z
 
     BILLING_PLUGIN_ENABLED: BoolEnv.default(false),
     BILLING_FORCE_FALLBACK: BoolEnv.default(false),
+    BILLING_V2_ENABLED: BoolEnv.default(false),
     BILLING_DATABASE_CONNECTION_LIMIT: z.coerce.number().int().default(2),
   })
   .and(GithubAppEnvSchema)

apps/webapp/app/services/billingPlugin.server.ts

@@ -17,6 +17,7 @@ const billingPlugin = billing.create({
 export function provisionBillingCustomerForOrg(organizationId: string): Promise<void> {
   return provisionBillingCustomerForNewOrg(organizationId, {
     enabled: billingEnabled,
+    createFreePlanContract: env.BILLING_V2_ENABLED,
     controller: billingPlugin,
     deleteOrganization: async (id) => {
       await prisma.organization.delete({ where: { id } });

apps/webapp/app/services/provisionBillingCustomer.server.test.ts

@@ -4,6 +4,8 @@ import type {
   BillingCustomerError,
   ProvisionBillingCustomerParams,
   ProvisionBillingCustomerResult,
+  ProvisionFreePlanContractParams,
+  ProvisionFreePlanContractResult,
 } from "@trigger.dev/billing";
 import { errAsync, okAsync, ResultAsync } from "neverthrow";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -14,37 +16,58 @@ import {
   type NewOrgProvisionDependencies,
 } from "./provisionBillingCustomer.server";
 
-type Outcome = () => ResultAsync<ProvisionBillingCustomerResult, BillingCustomerError>;
+type Outcome = () => ResultAsync<ProvisionFreePlanContractResult, BillingCustomerError>;
 
 const created: Outcome = () =>
-  okAsync({ organizationId: "org_1", billingCustomerId: "cus_1", outcome: "created" as const });
+  okAsync({
+    organizationId: "org_1",
+    billingCustomerId: "cus_1",
+    contractId: "con_1",
+    outcome: "created" as const,
+  });
 
 const never: Outcome = () => new ResultAsync(new Promise(() => {}));
 
-function harness(outcomes: Outcome[], options: { usingPlugin?: () => Promise<boolean> } = {}) {
-  const calls: ProvisionBillingCustomerParams[] = [];
+function harness(
+  outcomes: Outcome[],
+  options: {
+    usingPlugin?: () => Promise<boolean>;
+    customerOutcomes?: ProvisionBillingCustomerResult["outcome"][];
+  } = {}
+) {
+  const calls: ProvisionFreePlanContractParams[] = [];
+  const customerCalls: ProvisionBillingCustomerParams[] = [];
   const deleted: string[] = [];
+  const customerOutcomes: ProvisionBillingCustomerResult["outcome"][] =
+    options.customerOutcomes ?? ["created"];
 
   const controller: BillingController = {
     isUsingPlugin: options.usingPlugin ?? (async () => true),
     getCustomer(): ResultAsync<BillingCustomer | null, BillingCustomerError> {
       return okAsync(null);
     },
     provisionCustomer(params) {
+      customerCalls.push(params);
+      const outcome =
+        customerOutcomes[Math.min(customerCalls.length - 1, customerOutcomes.length - 1)];
+      return okAsync({ organizationId: "org_1", billingCustomerId: "cus_1", outcome });
+    },
+    provisionFreePlanContract(params) {
       calls.push(params);
       return outcomes[Math.min(calls.length - 1, outcomes.length - 1)]();
     },
   };
 
   const deps: NewOrgProvisionDependencies = {
     enabled: true,
+    createFreePlanContract: true,
     controller,
     deleteOrganization: async (id) => {
       deleted.push(id);
     },
   };
 
-  return { deps, calls, deleted };
+  return { deps, calls, customerCalls, deleted };
 }
 
 function run(deps: NewOrgProvisionDependencies) {
@@ -71,7 +94,7 @@ describe("provisionBillingCustomerForNewOrg", () => {
     expect(deleted).toHaveLength(0);
   });
 
-  it("blocks until the customer is provisioned and keeps the org", async () => {
+  it("blocks until the customer and free plan contract are provisioned and keeps the org", async () => {
     const { deps, calls, deleted } = harness([created]);
 
     expect(await run(deps)).toBe("ok");
@@ -81,12 +104,37 @@ describe("provisionBillingCustomerForNewOrg", () => {
     expect(deleted).toHaveLength(0);
   });
 
+  it("provisions only the customer, without a contract, when free plan contracts are off", async () => {
+    const { deps, calls, customerCalls, deleted } = harness([created]);
+
+    expect(await run({ ...deps, createFreePlanContract: false })).toBe("ok");
+    expect(calls).toHaveLength(0);
+    expect(customerCalls).toHaveLength(1);
+    expect(customerCalls[0].organizationId).toBe("org_1");
+    expect(deleted).toHaveLength(0);
+  });
+
+  it("retries a customer that is still in progress when free plan contracts are off", async () => {
+    const { deps, calls, customerCalls, deleted } = harness([created], {
+      customerOutcomes: ["in_progress", "created"],
+    });
+
+    const result = run({ ...deps, createFreePlanContract: false });
+    await vi.runAllTimersAsync();
+
+    expect(await result).toBe("ok");
+    expect(calls).toHaveLength(0);
+    expect(customerCalls).toHaveLength(2);
+    expect(deleted).toHaveLength(0);
+  });
+
   it("accepts an org that was already provisioned", async () => {
     const { deps, deleted } = harness([
       () =>
         okAsync({
           organizationId: "org_1",
           billingCustomerId: "cus_1",
+          contractId: "con_1",
           outcome: "already_provisioned" as const,
         }),
     ]);
@@ -170,24 +218,6 @@ describe("provisionBillingCustomerForNewOrg", () => {
     expect(calls).toHaveLength(2);
   });
 
-  it("retries an in_progress outcome instead of treating it as done", async () => {
-    const { deps, calls } = harness([
-      () =>
-        okAsync({
-          organizationId: "org_1",
-          billingCustomerId: null,
-          outcome: "in_progress" as const,
-        }),
-      created,
-    ]);
-
-    const settled = run(deps);
-    await vi.advanceTimersByTimeAsync(200);
-
-    expect(await settled).toBe("ok");
-    expect(calls).toHaveLength(2);
-  });
-
   it("deletes the org and fails creation once retries are exhausted", async () => {
     const { deps, calls, deleted } = harness([() => errAsync("upstream_unavailable")]);
 

apps/webapp/app/services/provisionBillingCustomer.server.ts

@@ -1,10 +1,6 @@
-import type {
-  BillingController,
-  BillingCustomerError,
-  ProvisionBillingCustomerResult,
-} from "@trigger.dev/billing";
+import type { BillingController, BillingCustomerError } from "@trigger.dev/billing";
 import { tryCatch } from "@trigger.dev/core/utils";
-import type { Result } from "neverthrow";
+import type { Result, ResultAsync } from "neverthrow";
 import { logger } from "~/services/logger.server";
 
 const PROVISION_DEADLINE_MS = 20_000;
@@ -21,6 +17,7 @@ const NOT_CONFIGURED_POLICY: NotConfiguredPolicy = "fail";
 
 export type NewOrgProvisionDependencies = {
   enabled: boolean;
+  createFreePlanContract: boolean;
   controller: BillingController;
   deleteOrganization: (organizationId: string) => Promise<void>;
   now?: () => number;
@@ -30,7 +27,7 @@ export type NewOrgProvisionDependencies = {
 
 type Budget = { deadlineAt: number; now: () => number; signal: AbortSignal };
 
-type ProvisionAttempt = Result<ProvisionBillingCustomerResult, BillingCustomerError> | "aborted";
+type ProvisionAttempt = Result<boolean, BillingCustomerError> | "aborted";
 
 export function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise<void>((resolve) => {
@@ -67,7 +64,7 @@ export async function provisionBillingCustomerForNewOrg(
   const error = await provisionOrError(organizationId, deps);
   if (!error) return;
 
-  logger.error("Billing customer provisioning failed; rolling back organization creation", {
+  logger.error("Billing provisioning failed; rolling back organization creation", {
     organizationId,
     error,
   });
@@ -131,19 +128,19 @@ async function provisionWithRetry(
 
   for (let attempt = 1; attempt <= PROVISION_MAX_ATTEMPTS; attempt++) {
     const [thrown, result] = await tryCatch<ProvisionAttempt>(
-      untilAborted(deps.controller.provisionCustomer({ organizationId, signal }), signal)
+      untilAborted(provisionOnce(organizationId, deps, signal), signal)
     );
 
     if (thrown) {
-      logger.error("Billing customer provisioning threw", {
+      logger.error("Billing provisioning threw", {
         organizationId,
         error: thrown instanceof Error ? thrown.message : thrown,
       });
       lastError = "internal";
     } else if (result === "aborted") {
       return "upstream_unavailable";
     } else if (result.isOk()) {
-      if (result.value.outcome !== "in_progress") return undefined;
+      if (result.value) return undefined;
       lastError = "internal";
     } else {
       if (!RETRYABLE_ERRORS.has(result.error)) return result.error;
@@ -158,3 +155,17 @@ async function provisionWithRetry(
 
   return lastError;
 }
+
+// Resolves to whether provisioning is complete; a customer still in progress is retried.
+function provisionOnce(
+  organizationId: string,
+  deps: NewOrgProvisionDependencies,
+  signal: AbortSignal
+): ResultAsync<boolean, BillingCustomerError> {
+  if (deps.createFreePlanContract) {
+    return deps.controller.provisionFreePlanContract({ organizationId, signal }).map(() => true);
+  }
+  return deps.controller
+    .provisionCustomer({ organizationId, signal })
+    .map((result) => result.outcome !== "in_progress");
+}

internal-packages/billing/src/fallback.ts

@@ -3,6 +3,7 @@ import type {
   BillingCustomer,
   BillingCustomerError,
   ProvisionBillingCustomerResult,
+  ProvisionFreePlanContractResult,
 } from "@trigger.dev/plugins";
 import { errAsync, okAsync, type ResultAsync } from "neverthrow";
 
@@ -24,4 +25,8 @@ class BillingFallbackController implements BillingController {
   provisionCustomer(): ResultAsync<ProvisionBillingCustomerResult, BillingCustomerError> {
     return errAsync("feature_disabled");
   }
+
+  provisionFreePlanContract(): ResultAsync<ProvisionFreePlanContractResult, BillingCustomerError> {
+    return errAsync("feature_disabled");
+  }
 }

internal-packages/billing/src/index.ts

@@ -6,6 +6,8 @@ import type {
   PluginDatabaseConfig,
   ProvisionBillingCustomerParams,
   ProvisionBillingCustomerResult,
+  ProvisionFreePlanContractParams,
+  ProvisionFreePlanContractResult,
 } from "@trigger.dev/plugins";
 import { ResultAsync } from "neverthrow";
 import { BillingFallback } from "./fallback.js";
@@ -16,6 +18,8 @@ export type {
   BillingCustomerError,
   ProvisionBillingCustomerParams,
   ProvisionBillingCustomerResult,
+  ProvisionFreePlanContractParams,
+  ProvisionFreePlanContractResult,
 } from "@trigger.dev/plugins";
 
 export type BillingCreateOptions = {
@@ -110,6 +114,12 @@ export class LazyController implements BillingController {
   ): ResultAsync<ProvisionBillingCustomerResult, BillingCustomerError> {
     return this.call((c) => c.provisionCustomer(params));
   }
+
+  provisionFreePlanContract(
+    params: ProvisionFreePlanContractParams
+  ): ResultAsync<ProvisionFreePlanContractResult, BillingCustomerError> {
+    return this.call((c) => c.provisionFreePlanContract(params));
+  }
 }
 
 class Billing {

internal-packages/billing/src/loader.test.ts

@@ -22,6 +22,14 @@ function makeStubController(overrides: Partial<BillingController> = {}): Billing
         outcome: "created" as const,
       });
     },
+    provisionFreePlanContract(params) {
+      return okAsync({
+        organizationId: params.organizationId,
+        billingCustomerId: "cus_stub",
+        contractId: "con_stub",
+        outcome: "created" as const,
+      });
+    },
     ...overrides,
   };
   return stub;
@@ -142,6 +150,27 @@ describe("billing loader", () => {
     expect(result._unsafeUnwrap()).toBeNull();
   });
 
+  it("fallback refuses to provision a free plan contract", async () => {
+    const controller = loader.create({ forceFallback: true });
+
+    const result = await controller.provisionFreePlanContract({ organizationId: "org_1" });
+    expect(result._unsafeUnwrapErr()).toBe("feature_disabled");
+  });
+
+  it("delegates free plan contract provisioning to the plugin", async () => {
+    const controller = new LazyController({
+      importer: async () => makePluginModule(makeStubController()),
+    });
+
+    const result = await controller.provisionFreePlanContract({ organizationId: "org_1" });
+    expect(result._unsafeUnwrap()).toEqual({
+      organizationId: "org_1",
+      billingCustomerId: "cus_stub",
+      contractId: "con_stub",
+      outcome: "created",
+    });
+  });
+
   it("loads the plugin once and reuses it across calls", async () => {
     const importer = vi.fn(async () => makePluginModule(makeStubController()));
     const controller = new LazyController({ importer });

packages/plugins/src/billing.ts

@@ -28,6 +28,18 @@ export type ProvisionBillingCustomerParams = {
   signal?: AbortSignal;
 };
 
+export type ProvisionFreePlanContractParams = {
+  organizationId: string;
+  signal?: AbortSignal;
+};
+
+export type ProvisionFreePlanContractResult = {
+  organizationId: string;
+  billingCustomerId: string;
+  contractId: string;
+  outcome: "created" | "already_provisioned";
+};
+
 export interface BillingController {
   isUsingPlugin(): Promise<boolean>;
 
@@ -36,6 +48,10 @@ export interface BillingController {
   provisionCustomer(
     params: ProvisionBillingCustomerParams
   ): ResultAsync<ProvisionBillingCustomerResult, BillingCustomerError>;
+
+  provisionFreePlanContract(
+    params: ProvisionFreePlanContractParams
+  ): ResultAsync<ProvisionFreePlanContractResult, BillingCustomerError>;
 }
 
 export type BillingPluginConfig = {

packages/plugins/src/index.ts

@@ -81,4 +81,6 @@ export type {
   ProvisionBillingCustomerParams,
   ProvisionBillingCustomerResult,
   ProvisionBillingCustomerOutcome,
+  ProvisionFreePlanContractParams,
+  ProvisionFreePlanContractResult,
 } from "./billing.js";