create-ailk 0.4.0 → 0.6.0

package/templates/apps/api/src/services/dunning-policy.ts

@@ -0,0 +1,294 @@
+/**
+ * @file dunning-policy.ts
+ * @description The per-tenant dunning grace policy (#6034 §§ D4, D5) — one
+ * function that resolves how many days a `past_due`/`unpaid` subscription
+ * keeps access before a subsequent `canceled` revokes it, plus the two
+ * read-side predicates that decide whether a subscriber has lost access or
+ * merely needs to act.
+ *
+ * NOT marked `oss: false` (§ D1) — `routes/webhooks/stripe.ts`, this file's
+ * only caller, deliberately left `commerce.ownedFiles`
+ * (`packages/create-ailk/src/module-architecture.ts:1818-1846`) so a keyless
+ * scaffold still carries and registers it; gating happens at CALL time on the
+ * commerce claim already settled at `stripe.ts:174` (NFR-3), not at file
+ * presence.
+ *
+ * The policy blob lives in `SiteSetting` (`database/config/schema.prisma:15`)
+ * — a model with NO reader anywhere in the tree before this file (§ 1.7) and
+ * a globally-`@unique` `key` column with no `siteId` column of its own. Per-
+ * tenant scoping therefore lives in the key STRING:
+ * `commerce.dunning_policy:<siteId>` — never an unsuffixed fallback, which
+ * would let one site's policy silently govern another's money.
+ *
+ * The read never throws (AC-3) — see the resolution table on
+ * `dunningPolicyFor` below, which mirrors `listing-config.ts`'s
+ * absent/malformed → documented-default contract for the same reason: an
+ * anonymous webhook delivery must not 500 because an operator (or nothing at
+ * all) wrote a bad policy row.
+ */
+
+import { logger } from "@working-theory/observability";
+import { z } from "zod";
+
+import { isModuleEnabled } from "../config/modules.js";
+import { prisma } from "../lib/prisma.js";
+import { resolveWorkspaceIdForAlias } from "../lib/site.js";
+
+/** The lifecycle values this record persists. A narrower set than
+ * `SubscriptionLifecycleStatus` (`@working-theory/stripe-client`): `trialing`
+ * never persists on its own — an arriving `active` OR `trialing` status is
+ * always rewritten to a recorded `status: "active"` (#6034 § D7's clean-
+ * recovery contract), so the record's own vocabulary only ever needs three
+ * members. */
+export type DunningRecordedStatus = "past_due" | "active" | "canceled";
+
+/** One subscription's recorded dunning state (#6034 § D2). */
+export interface DunningEntry {
+  status: DunningRecordedStatus;
+  accessState: "granted" | "revoked";
+  /** ISO-8601, or `null` before the subscription has ever failed. Set once,
+   * on first entry into a failing state, and never moved while it stays
+   * failing (§ D5) — re-arming on every retry would slide the grace window
+   * forward with every Stripe attempt and it would never expire. */
+  dunningArmedAt: string | null;
+  /** ISO-8601, or `null` while nothing has scheduled a revocation. Present
+   * (possibly in the future) the instant a `canceled` event is recorded —
+   * the read-side lazily evaluates it rather than any scheduler waking up to
+   * flip the row (§ D5 — NFR-7 forbids one). */
+  accessRevokesAt: string | null;
+  /** Stripe `event.created`, seconds — the ordering watermark § D6's
+   * admission rule compares incoming events against. */
+  lastEventAt: number;
+  /** The durable twin of the in-process `hasSeen` map (§ D6 rule 1) — a
+   * replay of the SAME event id is a no-op even after a process restart. */
+  lastEventId: string;
+}
+
+/** The whole `UserData` blob for the reserved
+ * `commerce.subscription_dunning` key — one row per subscriber, keyed by
+ * Stripe subscription id because one customer can hold more than one
+ * subscription (§ D2 — the map is what stops a second subscription's
+ * `active` clobbering the first's `past_due`). */
+export interface DunningRecord {
+  v: 1;
+  subscriptions: Record<string, DunningEntry>;
+}
+
+/** The reserved `UserData` key this record lives at (§ D12 — refused on
+ * `GET`/`PUT`/`DELETE /v1/user/data/:key`; the subject of the access
+ * decision may not read, write or erase it). */
+export const DUNNING_USER_DATA_KEY = "commerce.subscription_dunning";
+
+/** The map is capped so a per-event read-and-rewrite of the whole blob
+ * doesn't grow with a customer's entire subscription history (§ D2, § 9
+ * SEC-08). Eviction is oldest-first by `lastEventAt`, skipping any entry
+ * that is not yet terminal-and-settled (`status: "active"` with
+ * `accessState: "granted"`) — an entry still being dunned is never evicted
+ * out from under an in-flight decision. */
+export const DUNNING_MAX_SUBSCRIPTIONS = 50;
+
+export interface DunningPolicy {
+  graceDays: number;
+}
+
+/** 14 days — chosen because Stripe's Smart Retries schedule runs up to
+ * roughly three weeks and the grace clock starts at the FIRST failure, not
+ * at cancellation (§ D5). A shorter default would have the platform cut a
+ * buyer off while Stripe is still actively recovering the payment. */
+export const DUNNING_POLICY_DEFAULTS: DunningPolicy = { graceDays: 14 };
+
+/** A tenant may not configure a grace window longer than this. Clamped, not
+ * rejected — an operator's out-of-range number is a mistake to correct, not
+ * grounds to fall back to a platform default that may be MORE permissive
+ * than what they wrote (`listing-config.ts:55-62`'s disposition). */
+export const DUNNING_GRACE_DAYS_MAX = 90;
+
+/** Validated shape of the `SiteSetting.value` blob. Accepts any object with
+ * unknown extra keys (`.passthrough()`) so the "is this a JSON object at
+ * all" check is separated from the fine-grained `graceDays` validation below
+ * — zod v4's own `z.number()` already refuses `NaN`/`Infinity` outright,
+ * which would collapse the resolution table's distinct `malformed` and
+ * `non_finite` outcomes into one, so `graceDays` is read as `unknown` here
+ * and narrowed by hand. Deliberately NOT promoted to
+ * `@working-theory/validation` (§ D4) — one consumer, no cross-package
+ * reader; promoting it now would widen the published surface for nothing. */
+const DunningPolicyBlobSchema = z.object({}).passthrough();
+
+/** Logged once per process, the first time a `multi-tenant` deployment reads
+ * the policy (§ D4) — an operator should learn that one grace window governs
+ * every seller from a log line, not from a wrongful revocation. Process
+ * restart re-arms it, mirroring `enrichment-shim.ts`'s pro-sentinel flag. */
+let deploymentWidePolicyWarned = false;
+
+/**
+ * Resolve `siteId`'s dunning grace policy. Never throws (AC-3) — every
+ * branch below resolves to a value, logged at the level the § D4 resolution
+ * table specifies:
+ *
+ *   no row                                   → default, info  "no_policy_row"
+ *   not a JSON object                        → default, error "malformed"
+ *   `graceDays` absent / wrong type           → default, error "malformed"
+ *   `graceDays` non-finite (e.g. `1e999`)     → default, error "non_finite"
+ *   `graceDays` negative and finite           → clamp 0,  error "clamped_low"
+ *   `graceDays` finite and > the ceiling      → clamp max, error "clamped_high"
+ *   `graceDays` non-integer (e.g. `7.5`)      → floored,  warn  "floored"
+ *   the query itself throws                  → default, error "read_failed"
+ *   a valid integer in `[0, DUNNING_GRACE_DAYS_MAX]` → that value, no log
+ *
+ * `siteId` is a PARAMETER, never read via `currentSiteId()` inside this
+ * function (§ D4) — a later per-seller resolution is then a caller change
+ * only, no signature churn.
+ */
+export async function dunningPolicyFor(siteId: string): Promise<DunningPolicy> {
+  // #6374 D3 — the key is built from the UNRESOLVED `siteId` parameter, and
+  // that is deliberate, not an oversight. `site_settings` never had a
+  // `site_id` column, so the site alias was embedded in the key STRING
+  // (`commerce.dunning_policy:default`); the migration's backfill leaves
+  // every `key` verbatim. Rebuilding it from the RESOLVED workspace id would
+  // match no row and hand every seller the built-in default policy —
+  // silently, which is the failure mode this whole function's log table
+  // exists to make visible.
+  const key = `commerce.dunning_policy:${siteId}`;
+
+  if (isModuleEnabled("multi-tenant") && !deploymentWidePolicyWarned) {
+    deploymentWidePolicyWarned = true;
+    logger.warn(
+      { key, outcome: "deployment_wide_policy" },
+      "[dunning-policy] this deployment's grace policy is shared by every seller — the multi-tenant module is enabled but the policy key carries no per-seller resolution yet",
+    );
+  }
+
+  // #6374 D3 — `site_settings` is now keyed by (workspace_id, key): `key`
+  // alone is no longer unique, because two sellers may each hold a
+  // `feature_flags` row. The WORKSPACE half is resolved from the alias here;
+  // the KEY half keeps its embedded alias (see the note above). An alias
+  // that resolves to nothing takes the same branch a missing row already
+  // takes — the built-in default policy — rather than throwing on a
+  // payment-webhook path.
+  const workspaceId = await resolveWorkspaceIdForAlias(siteId);
+  if (workspaceId === null) {
+    logger.info(
+      { siteId, key, outcome: "no_policy_row" },
+      "[dunning-policy] site alias resolves to no workspace — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  let row: { value: unknown } | null;
+  try {
+    row = await prisma.siteSetting.findUnique({
+      where: { workspaceId_key: { workspaceId, key } },
+      select: { value: true },
+    });
+  } catch (err) {
+    logger.error(
+      {
+        siteId,
+        key,
+        outcome: "read_failed",
+        errName: err instanceof Error ? err.name : "UnknownError",
+      },
+      "[dunning-policy] policy read failed — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  if (!row) {
+    logger.info(
+      { siteId, key, outcome: "no_policy_row" },
+      "[dunning-policy] no policy row — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  const parsed = DunningPolicyBlobSchema.safeParse(row.value);
+  if (!parsed.success) {
+    logger.error(
+      { siteId, key, outcome: "malformed" },
+      "[dunning-policy] stored policy is not a JSON object — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  const graceDaysRaw: unknown = (parsed.data as Record<string, unknown>)[
+    "graceDays"
+  ];
+  if (typeof graceDaysRaw !== "number") {
+    logger.error(
+      { siteId, key, outcome: "malformed" },
+      "[dunning-policy] stored graceDays is missing or not a number — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  // `Number.isFinite` covers both the reachable `1e999 → Infinity` overflow
+  // AND `NaN`, which cannot arrive from `jsonb` in the first place (there is
+  // no `NaN` literal in JSON) — one guard, both cases (§ 9 SEC-10).
+  if (!Number.isFinite(graceDaysRaw)) {
+    logger.error(
+      { siteId, key, outcome: "non_finite" },
+      "[dunning-policy] stored graceDays is not finite — using the platform default",
+    );
+    return DUNNING_POLICY_DEFAULTS;
+  }
+
+  if (graceDaysRaw < 0) {
+    logger.error(
+      { siteId, key, outcome: "clamped_low", stored: graceDaysRaw },
+      "[dunning-policy] stored graceDays is negative — clamped to 0",
+    );
+    return { graceDays: 0 };
+  }
+
+  if (graceDaysRaw > DUNNING_GRACE_DAYS_MAX) {
+    logger.error(
+      { siteId, key, outcome: "clamped_high", stored: graceDaysRaw },
+      "[dunning-policy] stored graceDays exceeds the ceiling — clamped",
+    );
+    return { graceDays: DUNNING_GRACE_DAYS_MAX };
+  }
+
+  if (!Number.isInteger(graceDaysRaw)) {
+    const floored = Math.floor(graceDaysRaw);
+    logger.warn(
+      { siteId, key, outcome: "floored", stored: graceDaysRaw },
+      "[dunning-policy] stored graceDays is not an integer — floored",
+    );
+    return { graceDays: floored };
+  }
+
+  return { graceDays: graceDaysRaw };
+}
+
+/**
+ * Access is gone for this subscription: either already stamped `revoked`, or
+ * the lazily-evaluated `accessRevokesAt` instant has passed. No scheduler
+ * flips this — every reader evaluates it fresh (§ D5, NFR-7).
+ */
+export function isSubscriberRevoked(
+  entry: DunningEntry,
+  now: number = Date.now(),
+): boolean {
+  return (
+    entry.accessState === "revoked" ||
+    (entry.accessRevokesAt !== null && now >= Date.parse(entry.accessRevokesAt))
+  );
+}
+
+/**
+ * The buyer must act — #6038's banner predicate (§ D5), exported so #6038
+ * CALLS it rather than re-deriving it. Deliberately WIDER than
+ * `status === "past_due"`: a subscription cancelled with its grace window
+ * still open carries `status: "canceled"`, `accessState: "granted"` — a
+ * buyer about to lose access who has not been told. Both cases are covered
+ * here; neither alone is (§ 9 SEC-09).
+ */
+export function isSubscriberActionRequired(
+  entry: DunningEntry,
+  now: number = Date.now(),
+): boolean {
+  return (
+    !isSubscriberRevoked(entry, now) &&
+    (entry.status === "past_due" || entry.accessRevokesAt !== null)
+  );
+}

package/templates/apps/api/src/services/entitlements.ts

@@ -17,6 +17,11 @@
  * spec builds NO metering engine (spec D5).
  */
 import type { Entitlements } from "@working-theory/license";
+import {
+  MAGNET_KIND_MIN_RANK,
+  planRank,
+  type FlowConfig,
+} from "@working-theory/validation";
 
 import { prisma } from "../lib/prisma.js";
 
@@ -66,6 +71,56 @@ export async function resolveEntitlements(
   };
 }
 
+/**
+ * #6287 — the org's plan RANK (never the deployment-wide `checkLicense()`),
+ * for the magnet routes' server-side plan gate. Composes `resolveEntitlements`
+ * above + `planRank` (`@working-theory/validation`, the same table the
+ * Admin's own UI-only gate reads) and NEVER throws: any failure (a DB
+ * error, or a tier string `planRank` doesn't recognize) collapses to
+ * `undefined` — the caller's fail-closed signal for a gated kind (spec D
+ * "the plan-rank resolver never throws").
+ */
+export async function resolveOrgPlanRank(
+  organizationId: string,
+): Promise<number | undefined> {
+  try {
+    const entitlements = await resolveEntitlements(organizationId);
+    return planRank(entitlements.limits.static.tier);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * #6305 — the minimum plan rank a GATED-SHAPE config requires, independent
+ * of the `kind` label the caller chose. Derived from `MAGNET_KIND_MIN_RANK`
+ * (never hand-duplicated) as the lowest non-zero rank in that table: today
+ * that is the same Pro-tier rank every gated kind already requires, so a
+ * gated-shape config on an ungated kind is refused exactly as a gated-kind
+ * refusal would be (#6305 AC-1).
+ */
+export const GATED_FLOW_SHAPE_MIN_RANK = Math.min(
+  ...Object.values(MAGNET_KIND_MIN_RANK).filter((rank) => rank > 0),
+);
+
+/**
+ * #6305 — whether a `FlowConfig` carries the shape the flow runtime actually
+ * branches on for gated (recommending-mode) behavior, regardless of which
+ * `kind` label the row carries. This is the SAME predicate family
+ * `deriveFlowKind`-style logic elsewhere in this codebase reads
+ * (`mode === "recommending"`, or the presence of `deliverables` / `offers` /
+ * `scoring`) — the label and the capability it confers can no longer diverge.
+ */
+export function configHasGatedShape(config: FlowConfig | undefined): boolean {
+  if (!config) return false;
+  return (
+    config.mode === "recommending" ||
+    config.deliverables !== undefined ||
+    config.offers !== undefined ||
+    config.scoring !== undefined
+  );
+}
+
 /**
  * The org's Stripe billing-customer identity (#3701 — the apps/api
  * predecessor to the org-billing UI, #3697).
@@ -100,3 +155,28 @@ export async function getOrgBillingIdentity(
 
   return { billingCustomerId: org?.billingCustomerId ?? null };
 }
+
+/**
+ * Whether ANY Organization row carries the given Stripe customer id (#6038
+ * D3.2, closes SA-4). Touches only `Organization.billingCustomerId` by
+ * explicit value — the same sanctioned-exception shape as
+ * `getOrgBillingIdentity` above (by id) and `resolveEntitlements` (by id),
+ * never an un-scoped tenant/content query.
+ *
+ * Exists because no code in this repo stamps `metadata.organizationId` onto
+ * a Stripe customer, so every `customer.created` takes the `User` branch
+ * (`webhooks/stripe.ts`'s `upsertBillingIdentity`) and a single `cus_…` can
+ * end up projected onto BOTH a `User` row and an `Organization` row. A
+ * caller resolving "the caller's own portal" from `User.billingCustomerId`
+ * alone would then risk opening the ORGANIZATION's billing record instead —
+ * this is the collision check that refuses that case.
+ */
+export async function isBillingCustomerAnOrganization(
+  billingCustomerId: string,
+): Promise<boolean> {
+  const org = await prisma.organization.findFirst({
+    where: { billingCustomerId },
+    select: { id: true },
+  });
+  return org !== null;
+}

package/templates/apps/api/src/services/lead-promotion.ts

@@ -0,0 +1,160 @@
+/**
+ * @file lead-promotion.ts
+ * @description Lead → user promotion across the inbox/auth namespace boundary
+ * (ADR 0009 D3 service-layer pattern; spec
+ * docs/specs/3586-lead-user-promotion-spec.md).
+ *
+ * Reconciles an anonymous inbox.Lead with an auth.User by stable email, once
+ * the reconciling user's own email is verified (D2 — the consent basis for
+ * linking anonymous-lead PII to a user) and only within that user's own
+ * tenant workspaces (D3 — the tenant-safety invariant). Workspace resolution
+ * is delegated to `owner-workspaces.ts` — the one site→workspace resolution in
+ * this app, which in turn delegates to the sole cross-namespace tenancy
+ * assembler — so this file never issues a raw membership or workspace model
+ * query of its own (architecture.yaml's tenant-scope forbidden pattern
+ * reserves those to the tenant-context / tenant-db modules).
+ *
+ * Mirrors lead-routing.ts's shape: discriminated `{ ok } | { ok: false, error }`
+ * result, no throw on the expected (no-op) paths, PII-safe (never logs email /
+ * payload / name / phone).
+ */
+
+import type { Id } from "@working-theory/ids";
+
+import { prisma } from "../lib/prisma.js";
+
+import { resolveOwnerWorkspaces } from "./owner-workspaces.js";
+import { findVerifiedEmail } from "./verified-email.js";
+
+/**
+ * Workspace resolution moved to `owner-workspaces.ts` (#5678) so the leads
+ * READ path can share it rather than write a second one. The module-
+ * conditional slice load, the zero-workspace semantics and the delegation to
+ * the tenancy assembler are unchanged — this file simply calls it now.
+ *
+ * It had to be a separate module rather than an export from here:
+ * `paidModuleTemplateExclusions()` drops every file that reaches a paid
+ * module's `ownedFiles` through the import graph, this file is inside that
+ * closure, and importing it from the leads read would have carried the
+ * closure all the way into `server.ts`. See `owner-workspaces.ts`'s own
+ * header.
+ *
+ * Semantics on a build without the multi-tenant module, CORRECTED by #5677
+ * and carried across the move. `services/default-tenant.ts` now resolves the
+ * seeded default Workspace on every build, so a module-less deployment DOES
+ * have a resolvable workspace — the shared resolver's empty result there is a
+ * deliberate scope limit, not a statement that there is nothing to resolve.
+ *
+ * PROMOTION specifically is not wired to that default resolution, and that is
+ * #5677's own disposition rather than an oversight of this move: single-tenant
+ * leads would start acquiring `promotedUserId`, which is what
+ * `/v1/flow-checkouts/me` and `/v1/waitlist-signups/me` join a respondent's own
+ * rows through — a respondent's `/account` would begin showing purchases where
+ * it shows none today. It also needs the deployment to pin `AILK_SITE_ID` to
+ * `DEFAULT_WORKSPACE_ID`, because `siteId` comes from `lib/site.ts`
+ * (`AILK_SITE_ID ?? "default"`) while `workspaceId` is the sentinel, and
+ * `siteId ∈ workspaceIds` only matches when those agree.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type PromotedLead = {
+  leadId: string;
+  siteId: string;
+  source: string;
+};
+
+export type PromoteLeadsResult =
+  | { ok: true; count: number; promoted: PromotedLead[] }
+  | {
+      ok: false;
+      error: { kind: "user_not_found" | "internal_error"; message: string };
+    };
+
+// ─── Main export ──────────────────────────────────────────────────────────────
+
+/**
+ * Promote every un-promoted `inbox.Lead` matching the verifying user's own
+ * email, within that user's own tenant workspaces (D1/D3). No-ops
+ * (`count: 0`) — never throws — when: the user's email is unverified (D2),
+ * the user belongs to no workspace, or no matching un-promoted lead exists.
+ * Idempotent: a lead already carrying `promotedUserId` is excluded from the
+ * match set, so re-invocation promotes nothing (AC-6).
+ */
+export async function promoteLeadsForVerifiedUser(params: {
+  userId: string;
+}): Promise<PromoteLeadsResult> {
+  const { userId } = params;
+
+  try {
+    // D2 — the verified-email gate is a service-level invariant, not a
+    // caller obligation: it cannot be bypassed by a wrong call-site. The read
+    // and the refusal both live in `services/verified-email.ts` (#5701 D4),
+    // shared with the four other email-keyed paths.
+    const verified = await findVerifiedEmail(userId);
+    if (!verified.ok) {
+      if (verified.reason === "user_not_found") {
+        return {
+          ok: false,
+          error: { kind: "user_not_found", message: "User not found" },
+        };
+      }
+      return { ok: true, count: 0, promoted: [] };
+    }
+    const user = verified.value;
+
+    // D3/D4 — resolve the verifying user's OWN workspaces through the one
+    // shared resolution (`owner-workspaces.ts`). Role-agnostic here:
+    // promotion links a lead to the person whose verified email it carries,
+    // in any workspace they belong to, exactly as it did before the move.
+    // Without the multi-tenant module the shared resolver yields nothing and
+    // the early return below fires — a scope limit since #5677, not an
+    // absence of anything to resolve; see the header.
+    const workspaces = await resolveOwnerWorkspaces(user.id as Id<"user">);
+    if (!workspaces.ok) {
+      return {
+        ok: false,
+        error: { kind: "internal_error", message: workspaces.error.message },
+      };
+    }
+    const workspaceIds = workspaces.value.map((workspace) => workspace.id);
+
+    if (workspaceIds.length === 0) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    // D3/AC-4 (tenant-safety — load-bearing): the match set is siteId ∈ the
+    // user's OWN workspaceIds, so a lead captured under a different
+    // organization's workspace is never matched, by construction.
+    const candidates = await prisma.lead.findMany({
+      where: {
+        email: user.email,
+        siteId: { in: workspaceIds },
+        promotedUserId: null,
+      },
+      select: { id: true, siteId: true, source: true },
+    });
+
+    if (candidates.length === 0) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    await prisma.lead.updateMany({
+      where: { id: { in: candidates.map((lead) => lead.id) } },
+      data: { promotedUserId: user.id, promotedAt: new Date() },
+    });
+
+    return {
+      ok: true,
+      count: candidates.length,
+      promoted: candidates.map((lead) => ({
+        leadId: lead.id,
+        siteId: lead.siteId,
+        source: lead.source,
+      })),
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { kind: "internal_error", message } };
+  }
+}