create-ailk 0.2.0 → 0.4.0

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

@@ -1,36 +0,0 @@
-// 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

@@ -1,182 +0,0 @@
-// 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

@@ -1,75 +0,0 @@
-// 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

@@ -1,153 +0,0 @@
-// 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,
-      },
-    },
-  });
-}