feat(webapp): reject new triggers while a billing limit is active

Reject triggers with a 422 once entitlement reports no access, and bust the entitlement cache on state changes.

Author: kathiekiwi

apps/webapp/app/routes/admin.api.v1.orgs.$organizationId.billing-limit.reject.ts

@@ -0,0 +1,37 @@
+import { type ActionFunctionArgs, json } from "@remix-run/server-runtime";
+import { z } from "zod";
+import { prisma } from "~/db.server";
+import { requireAdminApiRequest } from "~/services/personalAccessToken.server";
+import { bustBillingLimitCaches } from "~/services/platform.v3.server";
+import { BillingLimitConvergeEnvironmentsService } from "~/v3/services/billingLimit/billingLimitConvergeEnvironmentsService.server";
+import { enqueueBillingLimitConverge } from "~/v3/billingLimitWorker.server";
+
+const ParamsSchema = z.object({
+  organizationId: z.string(),
+});
+
+/** Billing platform webhook: org billing limit grace expired. Idempotent — returns 202. */
+export async function action({ request, params }: ActionFunctionArgs) {
+  await requireAdminApiRequest(request);
+
+  if (request.method.toLowerCase() !== "post") {
+    return json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  const { organizationId } = ParamsSchema.parse(params);
+
+  const organization = await prisma.organization.findFirst({
+    where: { id: organizationId },
+    select: { id: true },
+  });
+
+  if (!organization) {
+    return json({ error: "Organization not found" }, { status: 404 });
+  }
+
+  bustBillingLimitCaches(organizationId);
+  await BillingLimitConvergeEnvironmentsService.seedReconcileQueue(organizationId);
+  await enqueueBillingLimitConverge(organizationId, "rejected");
+
+  return json({ success: true, accepted: true }, { status: 202 });
+}

apps/webapp/app/routes/admin.api.v1.orgs.$organizationId.billing-limit.resolve.ts

@@ -0,0 +1,69 @@
+import { type ActionFunctionArgs, json } from "@remix-run/server-runtime";
+import { z } from "zod";
+import { prisma } from "~/db.server";
+import { requireAdminApiRequest } from "~/services/personalAccessToken.server";
+import { completeBillingLimitResolve } from "~/services/platform.v3.server";
+import { logger } from "~/services/logger.server";
+import {
+  convergeBillingLimitResolve,
+  type PendingBillingLimitResolve,
+} from "~/v3/services/billingLimit/billingLimitConvergeResolve.server";
+
+const ParamsSchema = z.object({
+  organizationId: z.string(),
+});
+
+const BodySchema = z.object({
+  resumeMode: z.enum(["queue", "new_only"]),
+  resolvedAt: z.string(),
+});
+
+/** Billing platform webhook: org resolved billing limit to ok. Idempotent — returns 202. */
+export async function action({ request, params }: ActionFunctionArgs) {
+  await requireAdminApiRequest(request);
+
+  if (request.method.toLowerCase() !== "post") {
+    return json({ error: "Method not allowed" }, { status: 405 });
+  }
+
+  const { organizationId } = ParamsSchema.parse(params);
+
+  const organization = await prisma.organization.findFirst({
+    where: { id: organizationId },
+    select: { id: true },
+  });
+
+  if (!organization) {
+    return json({ error: "Organization not found" }, { status: 404 });
+  }
+
+  let pending: PendingBillingLimitResolve;
+  try {
+    const body = await request.json();
+    pending = {
+      organizationId,
+      ...BodySchema.parse(body),
+    };
+  } catch (error) {
+    logger.error("Invalid billing limit resolve webhook payload", {
+      error,
+      organizationId,
+    });
+    return json({ error: "Invalid request body" }, { status: 400 });
+  }
+
+  try {
+    await convergeBillingLimitResolve(pending);
+    await completeBillingLimitResolve(organizationId);
+  } catch (error) {
+    logger.error("Billing limit resolve webhook failed", {
+      error,
+      organizationId,
+      resumeMode: pending.resumeMode,
+      resolvedAt: pending.resolvedAt,
+    });
+    return json({ error: "Failed to process billing limit resolve" }, { status: 500 });
+  }
+
+  return json({ success: true, accepted: true }, { status: 202 });
+}

apps/webapp/app/runEngine/validators/triggerTaskValidator.ts

@@ -1,7 +1,7 @@
 import { MAX_TAGS_PER_RUN } from "~/models/taskRunTag.server";
 import { logger } from "~/services/logger.server";
 import { getEntitlement } from "~/services/platform.v3.server";
-import { MAX_ATTEMPTS, OutOfEntitlementError } from "~/v3/services/triggerTask.server";
+import { MAX_ATTEMPTS } from "~/v3/services/triggerTask.server";
 import { isFinalRunStatus } from "~/v3/taskStatus";
 import type {
   EntitlementValidationParams,
@@ -12,6 +12,7 @@ import type {
   TriggerTaskValidator,
   ValidationResult,
 } from "../types";
+import { validateProductionEntitlement } from "./validateProductionEntitlement.server";
 import { ServiceValidationError } from "~/v3/services/common.server";
 
 export class DefaultTriggerTaskValidator implements TriggerTaskValidator {
@@ -41,22 +42,7 @@ export class DefaultTriggerTaskValidator implements TriggerTaskValidator {
   async validateEntitlement(
     params: EntitlementValidationParams
   ): Promise<EntitlementValidationResult> {
-    const { environment } = params;
-
-    if (environment.type === "DEVELOPMENT") {
-      return { ok: true };
-    }
-
-    const result = await getEntitlement(environment.organizationId);
-
-    if (result && result.hasAccess === false) {
-      return {
-        ok: false,
-        error: new OutOfEntitlementError(),
-      };
-    }
-
-    return { ok: true, plan: result?.plan };
+    return validateProductionEntitlement(params, getEntitlement);
   }
 
   validateMaxAttempts(params: MaxAttemptsValidationParams): ValidationResult {

apps/webapp/app/runEngine/validators/validateProductionEntitlement.server.ts

@@ -0,0 +1,29 @@
+import type { ReportUsageResult } from "@trigger.dev/platform/v3";
+import { OutOfEntitlementError } from "~/v3/outOfEntitlementError.server";
+import type { EntitlementValidationParams, EntitlementValidationResult } from "../types";
+
+export type GetEntitlementFn = (
+  organizationId: string
+) => Promise<ReportUsageResult | undefined>;
+
+export async function validateProductionEntitlement(
+  params: EntitlementValidationParams,
+  getEntitlementFn: GetEntitlementFn
+): Promise<EntitlementValidationResult> {
+  const { environment } = params;
+
+  if (environment.type === "DEVELOPMENT") {
+    return { ok: true };
+  }
+
+  const result = await getEntitlementFn(environment.organizationId);
+
+  if (result && result.hasAccess === false) {
+    return {
+      ok: false,
+      error: new OutOfEntitlementError(),
+    };
+  }
+
+  return { ok: true, plan: result?.plan };
+}

apps/webapp/app/v3/outOfEntitlementError.server.ts

@@ -0,0 +1,6 @@
+export class OutOfEntitlementError extends Error {
+  constructor() {
+    super("You can't trigger a task because you have run out of credits.");
+    this.name = "OutOfEntitlementError";
+  }
+}

apps/webapp/app/v3/services/triggerTask.server.ts

@@ -37,11 +37,7 @@ export type TriggerTaskServiceOptions = {
   triggerAction?: string;
 };
 
-export class OutOfEntitlementError extends Error {
-  constructor() {
-    super("You can't trigger a task because you have run out of credits.");
-  }
-}
+export { OutOfEntitlementError } from "../outOfEntitlementError.server";
 
 export type TriggerTaskServiceResult = {
   run: TaskRun;

apps/webapp/test/billingLimitTriggerEntitlement.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { validateProductionEntitlement } from "~/runEngine/validators/validateProductionEntitlement.server";
+
+const productionEnv = {
+  type: "PRODUCTION" as const,
+  organizationId: "org_123",
+};
+
+const developmentEnv = {
+  type: "DEVELOPMENT" as const,
+  organizationId: "org_123",
+};
+
+describe("validateProductionEntitlement", () => {
+  it("allows development environments without checking entitlement", async () => {
+    const result = await validateProductionEntitlement(
+      { environment: developmentEnv as never },
+      async () => ({ hasAccess: false, reason: "billing_limit" })
+    );
+
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("rejects production triggers when entitlement has billing_limit denial", async () => {
+    const result = await validateProductionEntitlement(
+      { environment: productionEnv as never },
+      async () => ({
+        hasAccess: false,
+        reason: "billing_limit",
+        plan: { type: "paid", code: "pro", isPaying: true },
+      })
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.name).toBe("OutOfEntitlementError");
+    }
+  });
+
+  it("allows production triggers when entitlement grants access", async () => {
+    const plan = { type: "paid" as const, code: "pro", isPaying: true };
+
+    const result = await validateProductionEntitlement(
+      { environment: productionEnv as never },
+      async () => ({
+        hasAccess: true,
+        plan,
+      })
+    );
+
+    expect(result).toEqual({ ok: true, plan });
+  });
+});