create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/billing/index.ts

@@ -0,0 +1,36 @@
+// oss: false
+/**
+ * Org-billing route group (#3701 — the apps/api predecessor to the
+ * org-billing UI, #3697).
+ *
+ * Routes:
+ *   GET  /v1/billing                 — org-scoped billing read (tier, seat
+ *                                       count, billing-customer presence,
+ *                                       entitlements)
+ *   GET  /v1/billing/usage           — org-scoped usage read (#3717): the
+ *                                       current-period report summary + credit
+ *                                       status, client-safe (no Stripe id)
+ *   POST /v1/billing/portal-session  — create a Stripe customer-portal
+ *                                       session for the caller's own org
+ *
+ * Registered INSIDE server.ts's `tenantScope` (spec D4 / AC-5) so
+ * `request.tenant` is populated by `tenantPreHandlerPlugin` before either
+ * handler runs — NOT at the public/checkout registration site, and NOT
+ * behind the `X-Internal-Auth` gate (spec 2.1.5).
+ *
+ * API↔MCP parity: the read is admin/settings-shaped (a human managing their
+ * own org's billing), not an agent tool — no MCP twin is warranted (spec §5,
+ * AC-6). The tenant-scoped authed MCP surface is tracked separately (#3591),
+ * mirroring the sibling /v1/workspaces/* routes' parity note.
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { billingPortalSessionHandler } from "./portal.js";
+import { billingReadHandler } from "./read.js";
+import { billingUsageHandler } from "./usage.js";
+
+export const billingRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/billing", billingReadHandler);
+  fastify.get("/v1/billing/usage", billingUsageHandler);
+  fastify.post("/v1/billing/portal-session", billingPortalSessionHandler);
+};

package/templates/apps/api/src/routes/billing/portal.ts

@@ -0,0 +1,182 @@
+// oss: false
+/**
+ * POST /v1/billing/portal-session
+ *
+ * Creates a Stripe billing-portal session for the caller's OWN org (#3701 —
+ * the apps/api predecessor to the org-billing UI, #3697). Org scope is
+ * ALWAYS `request.tenant.organizationId` (spec D1) — never a client-supplied
+ * id, so this route can never act on a foreign org. Reuses the existing
+ * `createBillingPortalSession` wrapper (spec D3) and mirrors
+ * `checkout/sessions.ts`'s 404/500/502 error mapping exactly:
+ *
+ *   404 no-billing-customer   — the org has no Stripe customer yet (no Stripe call)
+ *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty (no Stripe call)
+ *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key (assertSandboxKey guard)
+ *   500 config-error          — STRIPE_SECRET_KEY invalid configuration (from the SDK wrapper)
+ *   502 portal-unavailable    — Stripe SDK threw an unexpected error
+ *
+ * Registered inside `server.ts`'s `tenantScope` (spec D4) behind
+ * `tenantPreHandlerPlugin` — cookie/session auth via the tenant scope, NOT
+ * the `X-Internal-Auth` internal gate `checkout/sessions.ts` uses (spec
+ * 2.1.5): the caller here is apps/workspace forwarding the browser cookie,
+ * not a server-to-server internal call.
+ *
+ * AUTHORIZATION (#3766): the tenant preHandler establishes session + org
+ * MEMBERSHIP only — it does not discriminate role. The billing portal is a
+ * privileged, MUTATING capability (Stripe's portal lets the holder change the
+ * payment method, download invoices, and cancel the subscription), so
+ * membership alone is not sufficient: this handler additionally requires an
+ * `owner` or `admin` role and answers 403 for a `member`. The check runs
+ * BEFORE the `getOrgBillingIdentity` lookup and before any Stripe call,
+ * mirroring `middleware/tenant.ts`'s default-deny ordering (deny before any
+ * lookup of the target, so an unauthorized caller learns nothing — not even
+ * whether the org has a billing customer).
+ *
+ * PII/secret-min: the raw `billingCustomerId` is used only as an input to
+ * `createBillingPortalSession` — it never appears in a response body or log
+ * line (spec 5.2).
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { config } from "../../config/index.js";
+import {
+  assertSandboxKey,
+  createBillingPortalSession,
+  StripeConfigError,
+} from "../../lib/stripe.js";
+import { getOrgBillingIdentity } from "../../services/entitlements.js";
+import type { MembershipRole } from "../../services/tenant-context.js";
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+/**
+ * Roles permitted to open the org's Stripe billing portal (#3766).
+ *
+ * Mirrors the owner/admin floor already applied to workspace creation in
+ * `services/tenant-context.ts` (`createWorkspaceForOrg` — "Creating a
+ * workspace requires the admin role"): same policy, same two roles. Expressed
+ * here as an allow-list rather than a `!==` chain so it is default-deny — a
+ * role later added to `MembershipRole` is refused until it is named here,
+ * instead of silently falling through into a privileged path.
+ */
+const BILLING_PORTAL_ROLES: ReadonlySet<MembershipRole> = new Set<MembershipRole>([
+  "owner",
+  "admin",
+]);
+
+// Provisional return path (spec OQ-2 — resolved at implementation): the
+// org-billing UI (#3697) has not landed a page path yet. Points at the
+// workspace app's future billing-settings page under the configured frontend
+// origin; finalize this constant when #3697 sets the real path.
+const PORTAL_RETURN_PATH = "/settings/billing";
+
+export async function billingPortalSessionHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  if (!tenant) return unauthorized(reply);
+
+  // Role gate (#3766) — BEFORE any lookup or Stripe call. The tenant
+  // preHandler proved membership; opening the billing portal additionally
+  // requires owner/admin.
+  if (!BILLING_PORTAL_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[billing] portal session denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const identity = await getOrgBillingIdentity(tenant.organizationId);
+  if (!identity.billingCustomerId) {
+    // No Stripe call — the org has no billing customer to open a portal for.
+    return reply.status(404).send({
+      ok: false,
+      error: {
+        code: "no-billing-customer",
+        message: "No billing customer for this organization",
+      },
+    });
+  }
+
+  const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
+  if (!stripeSecretKey) {
+    return reply.status(500).send({
+      ok: false,
+      error: {
+        code: "stripe-not-configured",
+        message: "Stripe is not configured",
+      },
+    });
+  }
+  try {
+    assertSandboxKey(stripeSecretKey);
+  } catch {
+    return reply.status(500).send({
+      ok: false,
+      error: {
+        code: "live-mode-forbidden",
+        message: "Live Stripe keys are not permitted",
+      },
+    });
+  }
+
+  try {
+    const { url } = await createBillingPortalSession({
+      stripeCustomerId: identity.billingCustomerId,
+      returnUrl: `${config.FRONTEND_URL}${PORTAL_RETURN_PATH}`,
+    });
+
+    request.log.info(
+      { method: request.method, path: request.url, status: 200 },
+      "[billing] portal session created",
+    );
+
+    return reply.status(200).send({ ok: true, data: { url } });
+  } catch (err) {
+    if (err instanceof StripeConfigError) {
+      // 500 — misconfiguration; log message (no PII) but never echo in response.
+      request.log.error(
+        {
+          method: request.method,
+          path: request.url,
+          errName: err.name,
+          message: err.message,
+        },
+        "[billing] config error",
+      );
+      return reply.status(500).send({
+        ok: false,
+        error: { code: "config-error", message: "Billing portal is misconfigured" },
+      });
+    }
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        errName: err instanceof Error ? err.name : "unknown",
+      },
+      "[billing] stripe error; portal-unavailable",
+    );
+    return reply.status(502).send({
+      ok: false,
+      error: {
+        code: "portal-unavailable",
+        message: "Billing portal is temporarily unavailable",
+      },
+    });
+  }
+}

package/templates/apps/api/src/routes/billing/read.ts

@@ -0,0 +1,75 @@
+// oss: false
+/**
+ * GET /v1/billing
+ *
+ * Org-scoped billing read (#3701 — the apps/api predecessor to the
+ * org-billing UI, #3697). The org is ALWAYS `request.tenant.organizationId`
+ * — there is no client-supplied org id, so cross-tenant enumeration is
+ * structurally impossible (spec D1). Returns a client-safe projection:
+ * `hasBillingCustomer` is a presence flag only — the raw Stripe customer id
+ * never crosses the API boundary (spec D2).
+ *
+ * Registered inside `server.ts`'s `tenantScope` (spec D4) — `request.tenant`
+ * is populated by `tenantPreHandlerPlugin` before this handler ever runs; a
+ * caller with no resolvable org membership is denied by the preHandler
+ * itself (403), never reaching this code.
+ *
+ * AUTHORIZATION (#3766) — membership is deliberately sufficient here; this
+ * route intentionally carries NO owner/admin role gate, unlike its sibling
+ * `portal.ts`. The distinction is capability, not merely read-vs-write:
+ *
+ *   - It exposes no financial detail. The projection is plan metadata only —
+ *     `tier`, `seatCount`, and the `hasBillingCustomer` PRESENCE FLAG. No
+ *     invoices, no amounts, no payment methods, no subscription dates, and
+ *     (per spec D2) never the raw Stripe customer id.
+ *   - It confers no capability. There is nothing here to mutate; contrast the
+ *     portal, whose session lets its holder change the payment method and
+ *     cancel the subscription — which is why that route gates on role.
+ *   - Its data is operationally load-bearing for ordinary members. `tier` and
+ *     `entitlements` are what the app reads to decide which features to
+ *     render; gating them on owner/admin would break the product for members
+ *     without protecting anything sensitive.
+ *
+ * If this projection is ever widened to carry invoices, amounts, payment
+ * methods, or subscription lifecycle state, that change MUST also add the
+ * `portal.ts` role gate — the reason for its absence would no longer hold.
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import {
+  getOrgBillingIdentity,
+  resolveEntitlements,
+} from "../../services/entitlements.js";
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+export async function billingReadHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  // Defensive fallback — the tenant preHandler denies an unresolvable tenant
+  // before this handler runs; `request.tenant` is `TenantContext | undefined`
+  // at the type level, so this mirrors the sibling workspace routes.
+  if (!tenant) return unauthorized(reply);
+
+  const [identity, entitlements] = await Promise.all([
+    getOrgBillingIdentity(tenant.organizationId),
+    resolveEntitlements(tenant.organizationId),
+  ]);
+
+  return reply.status(200).send({
+    ok: true,
+    data: {
+      tier: entitlements.limits.static.tier,
+      seatCount: entitlements.limits.static.seats,
+      hasBillingCustomer: identity.billingCustomerId != null,
+      entitlements,
+    },
+  });
+}

package/templates/apps/api/src/routes/billing/usage.ts

@@ -0,0 +1,153 @@
+// oss: false
+/**
+ * GET /v1/billing/usage
+ *
+ * Org-scoped usage read (#3717 — the read surface the P3 usage UI, #3706 P3.S3,
+ * consumes). Extends the `billing` route family established by #3701 — same
+ * tenant-guard + `/v1` pattern, NOT a forked family.
+ *
+ * The org is ALWAYS `request.tenant.organizationId` — there is no
+ * client-supplied org id, so cross-tenant enumeration is structurally
+ * impossible (spec D1 / AC-UB-10). Returns a client-safe projection: P2's
+ * aggregation summary (totals + eventCount + the attribution split) plus P3.S1's
+ * credit status (`includedRemaining`, `creditBalance`, `effectiveRemaining`).
+ * NEVER a Stripe id / `billingCustomerId` (spec D3) — the response is an
+ * explicit projection, not a spread of a service result.
+ *
+ * Registered inside `server.ts`'s `tenantScope` (spec D4) behind
+ * `tenantPreHandlerPlugin` — a caller with no resolvable org membership is
+ * denied by the preHandler (403), never reaching this handler.
+ *
+ * Read-only: the credit *consumption* waterfall (P3.S1 `consumeCredits`) is a
+ * server-internal service, not this route (spec 2.1.5). `aggregateUsagePeriod`
+ * is idempotent (it re-reads events and upserts the same report), so a GET that
+ * calls it recomputes rather than mutates.
+ */
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import type { MembershipRole } from "../../services/tenant-context.js";
+import { aggregateUsagePeriod } from "../../services/usage-aggregation.js";
+import { getCreditStatus } from "../../services/usage-credits.js";
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+/**
+ * Roles permitted to read the org's usage projection (#3819).
+ *
+ * Mirrors `BILLING_PORTAL_ROLES` in `portal.ts` (#3766) exactly — same
+ * owner/admin floor, same allow-list form. The tenant preHandler proves
+ * MEMBERSHIP, not authorization; the usage read exposes the org's actual spend
+ * (`totalBilledAmount`) and credit balance, so membership alone is not enough.
+ * Expressed as an allow-list rather than a `!==` chain so it is default-deny —
+ * a role later added to `MembershipRole` is refused until named here, instead
+ * of silently falling through into a privileged read.
+ */
+const BILLING_USAGE_ROLES: ReadonlySet<MembershipRole> = new Set<MembershipRole>([
+  "owner",
+  "admin",
+]);
+
+/**
+ * Resolve the read period from the optional `?period=` selector.
+ * `{ ok: true, period }` on success (a valid Date, or the current instant when
+ * absent); `{ ok: false }` when a supplied value is unparseable (→ 400). The
+ * raw value is never echoed back.
+ */
+function resolvePeriod(raw: unknown): { ok: true; period: Date } | { ok: false } {
+  if (raw == null || raw === "") return { ok: true, period: new Date() };
+  if (typeof raw !== "string") return { ok: false };
+  const period = new Date(raw);
+  if (!Number.isFinite(period.getTime())) return { ok: false };
+  return { ok: true, period };
+}
+
+export async function billingUsageHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  // Defensive fallback — the tenant preHandler denies an unresolvable tenant
+  // before this handler runs; `request.tenant` is `TenantContext | undefined`
+  // at the type level, so this mirrors the sibling billing routes.
+  if (!tenant) return unauthorized(reply);
+
+  // Role gate (#3819) — BEFORE any read (aggregation / credit) or even the
+  // period parse. The tenant preHandler proved membership; reading the org's
+  // spend + credit balance additionally requires owner/admin. Default-deny
+  // ordering, mirroring `portal.ts`'s #3766 gate: deny before any lookup, so an
+  // unauthorized caller learns nothing — not even whether a period is valid.
+  if (!BILLING_USAGE_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[billing] usage read denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const period = resolvePeriod((request.query as { period?: unknown }).period);
+  if (!period.ok) {
+    return reply.status(400).send({
+      ok: false,
+      error: {
+        code: "validation-error",
+        message: "period must be a valid date",
+      },
+    });
+  }
+
+  const [report, credit] = await Promise.all([
+    aggregateUsagePeriod(tenant.organizationId, period.period),
+    getCreditStatus(tenant.organizationId),
+  ]);
+
+  if (!report.ok || !credit.ok) {
+    // Log the service detail server-side; NEVER echo it (a service error can
+    // embed the org id) — return a generic, id-free client message.
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        reportError: report.ok ? undefined : report.error.kind,
+        creditError: credit.ok ? undefined : credit.error.kind,
+      },
+      "[billing] usage read unavailable",
+    );
+    return reply.status(500).send({
+      ok: false,
+      error: { code: "usage-unavailable", message: "Usage is unavailable" },
+    });
+  }
+
+  return reply.status(200).send({
+    ok: true,
+    data: {
+      usage: {
+        totalProviderCost: report.totals.totalProviderCost,
+        totalMarkupAmount: report.totals.totalMarkupAmount,
+        totalBilledAmount: report.totals.totalBilledAmount,
+        totalTokens: report.totals.totalTokens,
+        eventCount: report.totals.eventCount,
+        includedCents: report.totals.includedCents,
+        creditBalanceCents: report.totals.creditBalanceCents,
+        onDemandCents: report.totals.onDemandCents,
+      },
+      credit: {
+        includedRemaining: credit.includedRemaining,
+        creditBalance: credit.creditBalance,
+        effectiveRemaining: credit.effectiveRemaining,
+      },
+    },
+  });
+}

package/templates/apps/api/src/routes/checkout/__tests__/sessions.test.ts

@@ -24,6 +24,8 @@
  * 15. PII guard: log lines contain session-id prefix only (first 8 chars), not full URL
  * 16. StripeConfigError (missing key): 500 config-error
  * 17. StripeConfigError message NOT in response body
+ * 18. allowPromotionCodes forwarded when supplied, omitted when absent (#4398)
+ * 19. Validation — non-boolean allowPromotionCodes: 400 validation-error (#4398)
  */
 
 import type { FastifyInstance } from "fastify";
@@ -75,6 +77,9 @@ describe("POST /api/checkout/sessions", () => {
 
   beforeEach(async () => {
     jest.clearAllMocks();
+    // Default: a present sandbox key, so the new (#3757) emptiness check at
+    // the call site doesn't short-circuit tests that aren't exercising it.
+    process.env["STRIPE_SECRET_KEY"] = "sk_test_route_fixture";
     // Default: sandbox key guard passes
     mockAssertSandboxKey.mockImplementation(() => undefined);
     // Default: successful checkout session
@@ -123,6 +128,44 @@ describe("POST /api/checkout/sessions", () => {
     expect(callArg.productCode).toBe("my-exact-product");
   });
 
+  // ── allowPromotionCodes passthrough (#4398) ────────────────────────────────
+
+  it("forwards allowPromotionCodes to createCheckoutSession when supplied", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, allowPromotionCodes: true },
+    });
+
+    expect(mockCreateCheckoutSession).toHaveBeenCalledWith(
+      expect.objectContaining({ allowPromotionCodes: true }),
+    );
+  });
+
+  it("omits allowPromotionCodes from the client call when not supplied", async () => {
+    await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(mockCreateCheckoutSession.mock.calls[0][0]).not.toHaveProperty(
+      "allowPromotionCodes",
+    );
+  });
+
+  it("returns 400 validation-error for a non-boolean allowPromotionCodes", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: { ...VALID_BODY, allowPromotionCodes: "yes" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toBe("validation-error");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
   it("defaults quantity to 1 when omitted", async () => {
     await app.inject({
       method: "POST",
@@ -465,6 +508,59 @@ describe("POST /api/checkout/sessions", () => {
     // Stripe was NOT called
     expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
   });
+
+  it("returns 500 live-mode-forbidden when STRIPE_SECRET_KEY is a restricted live key", async () => {
+    // "cmtfbGl2ZV8=" decodes to the restricted-live-key prefix.
+    const restrictedLivePrefix = Buffer.from("cmtfbGl2ZV8=", "base64").toString(
+      "utf8",
+    );
+    process.env["STRIPE_SECRET_KEY"] = restrictedLivePrefix + "xxxFakeKeyForTest";
+    mockAssertSandboxKey.mockImplementation(() => {
+      throw new Error("live key detected");
+    });
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("live-mode-forbidden");
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  // ── 500 — missing/empty key (#3757) ───────────────────────────────────────
+
+  it("returns 500 stripe-not-configured when STRIPE_SECRET_KEY is missing, not live-mode-forbidden", async () => {
+    delete process.env["STRIPE_SECRET_KEY"];
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("stripe-not-configured");
+    expect(mockAssertSandboxKey).not.toHaveBeenCalled();
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
+
+  it("returns 500 stripe-not-configured when STRIPE_SECRET_KEY is an empty string, not live-mode-forbidden", async () => {
+    process.env["STRIPE_SECRET_KEY"] = "";
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/checkout/sessions",
+      payload: VALID_BODY,
+    });
+
+    expect(res.statusCode).toBe(500);
+    expect(res.json().error).toBe("stripe-not-configured");
+    expect(mockAssertSandboxKey).not.toHaveBeenCalled();
+    expect(mockCreateCheckoutSession).not.toHaveBeenCalled();
+  });
 });
 
 // ── X-Internal-Auth gate tests (#935) ─────────────────────────────────────────
@@ -480,6 +576,8 @@ describe("POST /v1/checkout/sessions — X-Internal-Auth gate (#935)", () => {
 
   beforeEach(async () => {
     jest.clearAllMocks();
+    // Default: a present sandbox key (see the sibling describe block above).
+    process.env["STRIPE_SECRET_KEY"] = "sk_test_route_fixture";
     mockAssertSandboxKey.mockImplementation(() => undefined);
     mockCreateCheckoutSession.mockResolvedValue({
       sessionId: "cs_test_abc12345xyz",
@@ -492,6 +590,7 @@ describe("POST /v1/checkout/sessions — X-Internal-Auth gate (#935)", () => {
 
   afterEach(async () => {
     await app.close();
+    delete process.env["STRIPE_SECRET_KEY"];
     delete process.env["OSS_API_INTERNAL_SECRET"];
   });
 

package/templates/apps/api/src/routes/checkout/sessions.ts

@@ -2,7 +2,9 @@
  * POST /api/checkout/sessions
  *
  * Generic Stripe checkout primitive. Resolves a productCode to a Stripe
- * hosted-page checkout session and returns the session ID + URL.
+ * hosted-page checkout session and returns the session ID + URL. The session
+ * mode is derived from the resolved price by the stripe-client (a recurring
+ * price opens a subscription session), so this route serves both (#4398).
  *
  * Security invariants:
  *   - Sandbox-only: live Stripe keys are rejected at runtime before any Stripe call.
@@ -18,11 +20,12 @@
  *
  * Error mapping:
  *   401 internal-auth-required — X-Internal-Auth missing/mismatch (only when env var set)
- *   400 validation-error  — Zod validation failed (missing/invalid fields)
- *   404 unknown-product-code — no active Stripe price for the given productCode
- *   500 live-mode-forbidden  — STRIPE_SECRET_KEY is a live key
- *   500 config-error         — STRIPE_SECRET_KEY missing or invalid configuration
- *   502 checkout-unavailable — Stripe SDK threw an unexpected error
+ *   400 validation-error      — Zod validation failed (missing/invalid fields)
+ *   404 unknown-product-code  — no active Stripe price for the given productCode
+ *   500 stripe-not-configured — STRIPE_SECRET_KEY is missing/empty (no Stripe call)
+ *   500 live-mode-forbidden   — STRIPE_SECRET_KEY is a live key
+ *   500 config-error          — STRIPE_SECRET_KEY invalid configuration (from the SDK wrapper)
+ *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
  */
 import { timingSafeEqual } from "node:crypto";
 
@@ -72,6 +75,7 @@ const CheckoutSessionRequestSchema = z.object({
       "cancelUrl must be a valid URL with a non-empty host and not use javascript: scheme",
   }),
   quantity: z.number().int().min(1).max(999).optional(),
+  allowPromotionCodes: z.boolean().optional(),
 });
 
 // ── Internal-auth gate ────────────────────────────────────────────────────────
@@ -119,8 +123,12 @@ export async function checkoutSessionsHandler(
     return reply.status(401).send({ error: "internal-auth-required" });
   }
 
+  const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
+  if (!stripeSecretKey) {
+    return reply.status(500).send({ error: "stripe-not-configured" });
+  }
   try {
-    assertSandboxKey(process.env["STRIPE_SECRET_KEY"] ?? "");
+    assertSandboxKey(stripeSecretKey);
   } catch {
     return reply.status(500).send({ error: "live-mode-forbidden" });
   }
@@ -133,7 +141,8 @@ export async function checkoutSessionsHandler(
     });
   }
 
-  const { productCode, successUrl, cancelUrl, quantity } = parsed.data;
+  const { productCode, successUrl, cancelUrl, quantity, allowPromotionCodes } =
+    parsed.data;
 
   try {
     const { sessionId, url } = await createCheckoutSession({
@@ -141,6 +150,9 @@ export async function checkoutSessionsHandler(
       successUrl,
       cancelUrl,
       quantity: quantity ?? 1,
+      // Omitted when the caller says nothing — Stripe's default (no promo-code
+      // field) is unchanged for every existing caller.
+      ...(allowPromotionCodes !== undefined && { allowPromotionCodes }),
     });
 
     request.log.info(

package/templates/apps/api/src/routes/content/create.ts

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * POST /v1/content/:type
  *

package/templates/apps/api/src/routes/content/delete.ts

@@ -1,3 +1,4 @@
+// oss: false
 /**
  * DELETE /v1/content/:type/:slug
  *