create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/deliverable-fulfillment.ts

@@ -0,0 +1,523 @@
+/**
+ * @file deliverable-fulfillment.ts
+ * @description The deliverable-fulfillment service (#3961 D3/D4/D5/D7;
+ * extended #3998 D1/D3/D5; extended FEAT-074 U4b, #4718 D4).
+ *
+ * `fulfillDeliverable` is the one entry point, called from flow-engine's
+ * completion branch after `routeLead` succeeds and only when the session's
+ * `configSnapshot` carries a `deliverables` block (D4 — the block is opt-in
+ * per flow; flow-engine.ts itself gates the call on the block's presence).
+ * Resolves the request-local segment against the flow's `deliverables`
+ * asset map (D3), mints a capability-token grant (D5), and sends the
+ * lead-facing delivery email (D7) — every non-happy path is a log-and-skip,
+ * never a throw, so a caller that DOES let an exception escape (a DB error)
+ * is the only case its own wrapping needs to catch (flow-engine.ts's D4
+ * "the submission still succeeds" posture).
+ *
+ * An `entry.assetKey` prefixed `playbook:` (FEAT-074 U4b, #4718 D4) is a
+ * VIRTUAL asset — a per-lead COMPILED `PlaybookInstance`, never an
+ * operator-uploaded `DeliverableAsset` row — so it skips the asset lookup
+ * entirely, requires at least one instance for `(siteId, leadId,
+ * experimentKey)` (else `playbook_missing`, the `asset_missing` posture's
+ * virtual-asset twin), and mints the grant with `assetId = entry.assetKey`
+ * itself (the column is a plain string with no `@relation`, D4 — no schema
+ * change). Every other `assetKey` follows the unchanged operator-uploaded
+ * path below.
+ *
+ * `resendDeliverableGrant` and `listSendlessGrants` (#3998) are the
+ * `deliverable:resend` CLI's two modes. Both share the extracted post-mint
+ * "resolve copy → build link → send → stamp + log" tail with
+ * `fulfillDeliverable` (#3998 D5) — the ONE place a delivery email is ever
+ * sent and its outcome stamped. The resend path never mints a grant (#3998
+ * D3) — it looks the grant up and reuses its id, producing a byte-identical
+ * download link to the original.
+ *
+ * PII boundary: logs carry only `{ siteId, flowSlug, sessionId, outcome }` —
+ * never email/asset-key/copy values (mirrors flow-engine.ts's + abandon-
+ * email.ts's boundary).
+ */
+
+import { sendDeliverableEmail } from "@working-theory/email";
+import { logger } from "@working-theory/observability";
+import { flowConfigSchema, type FlowConfig } from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type FulfillDeliverableInput = {
+  siteId: string;
+  flowSlug: string;
+  configSnapshot: FlowConfig;
+  /** The request-local segment (#3959 D3) — undefined for an N=1 flow. */
+  segment?: string;
+  leadId: string;
+  sessionId: string;
+  email: string;
+  locale: string;
+};
+
+type DeliverableAssetRow = {
+  id: string;
+  siteId: string;
+  key: string;
+};
+
+// Derived from the schema type (not hand-rolled) so it never drifts from
+// `deliverableAssetMapEntrySchema`'s actual Zod-inferred optional shape.
+type DeliverableEntry = NonNullable<
+  FlowConfig["deliverables"]
+>["assets"][number];
+
+// Same derivation discipline for the copy block (#3998) — never hand-rolled,
+// so it can never drift from `deliverableCopySchema`'s actual shape.
+type DeliverableCopy = NonNullable<FlowConfig["deliverables"]>["copy"];
+
+// ─── PII-safe outcome logging (mirrors abandon-email.ts's logOutcome) ──────────
+
+type FulfillmentOutcome =
+  | "sent"
+  | "no_entry"
+  | "asset_missing"
+  | "playbook_missing"
+  | "sender_unconfigured"
+  | "send_failed";
+
+// The exact post-mint subset (#3998 D1) — derived from FulfillmentOutcome,
+// not a second hand-rolled union, so it can never drift. A grant only ever
+// exists for one of these three; `no_entry`/`asset_missing`/
+// `playbook_missing` (FEAT-074 U4b, #4718 — the virtual-asset analog of
+// `asset_missing`) all occur before a grant is minted and are never
+// stamped.
+type PostMintOutcome = Extract<
+  FulfillmentOutcome,
+  "sent" | "send_failed" | "sender_unconfigured"
+>;
+
+const OUTCOME_MESSAGE: Record<FulfillmentOutcome, string> = {
+  sent: "[deliverable-fulfillment] delivery email sent",
+  no_entry: "[deliverable-fulfillment] no matching asset-map entry — skipped",
+  asset_missing: "[deliverable-fulfillment] asset row not found — skipped",
+  playbook_missing:
+    "[deliverable-fulfillment] no PlaybookInstance for this lead/experiment — skipped",
+  sender_unconfigured:
+    "[deliverable-fulfillment] no from-address configured — skipped",
+  send_failed: "[deliverable-fulfillment] email send failed",
+};
+
+function logOutcome(
+  input: { siteId: string; flowSlug: string; sessionId: string },
+  outcome: FulfillmentOutcome,
+): void {
+  logger.info(
+    {
+      siteId: input.siteId,
+      flowSlug: input.flowSlug,
+      sessionId: input.sessionId,
+      outcome,
+    },
+    OUTCOME_MESSAGE[outcome],
+  );
+}
+
+// ─── D7 — copy resolution ───────────────────────────────────────────────────────
+
+/**
+ * `copy[locale] ?? copy[defaultLocale]` (D7). `defaultLocale` is a required
+ * key on every `deliverables.copy` LocalizedString the `deliverablesSchema`
+ * superRefine walk enforces, so the final fallback is always resolvable
+ * against a schema-valid config.
+ */
+function resolveCopy(
+  copy: Record<string, string>,
+  locale: string,
+  defaultLocale: string,
+): string {
+  return copy[locale] ?? copy[defaultLocale] ?? "";
+}
+
+// ─── D3 — segment → entry resolution ────────────────────────────────────────────
+
+/**
+ * `entry = assets.find(a => a.segment === segment) ?? assets.find(a =>
+ * a.segment === undefined)` (D3) — the default entry, if declared, is the
+ * fallback for a derivation miss; a map with segment entries but no default
+ * relies on the #3959 band map's totality guarantee for the happy path.
+ */
+function resolveEntry(
+  assets: DeliverableEntry[],
+  segment: string | undefined,
+): DeliverableEntry | undefined {
+  return (
+    assets.find((a) => a.segment === segment) ??
+    assets.find((a) => a.segment === undefined)
+  );
+}
+
+// ─── FEAT-074 U4b (#4718) D4 — the `playbook:` virtual asset ────────────────
+
+const PLAYBOOK_ASSET_PREFIX = "playbook:";
+
+/**
+ * `entry.assetKey`'s `experimentKey` suffix when it names the `playbook:`
+ * virtual asset (spec D4), else `undefined` — the one branch point every
+ * other `assetKey` (an operator-uploaded `DeliverableAsset` key) never
+ * takes.
+ */
+function playbookExperimentKey(assetKey: string): string | undefined {
+  return assetKey.startsWith(PLAYBOOK_ASSET_PREFIX)
+    ? assetKey.slice(PLAYBOOK_ASSET_PREFIX.length)
+    : undefined;
+}
+
+// ─── #3998 D1 — send-outcome stamp ───────────────────────────────────────────────
+
+/**
+ * Stamps the post-mint outcome on the grant row (#3998 D1). Caught and
+ * logged, never escalated (#3998 D5) — a stamp write failing must not become
+ * a new way to fail a submission or a resend; the existing `logOutcome` log
+ * line is the audit trail of record either way.
+ */
+async function stampOutcome(
+  grantId: string,
+  outcome: PostMintOutcome,
+  now: Date,
+): Promise<void> {
+  try {
+    await prisma.deliverableGrant.update({
+      where: { id: grantId },
+      data: { sendStatus: outcome, sendAt: now },
+    });
+  } catch (err) {
+    logger.warn(
+      {
+        grantId,
+        outcome,
+        err: err instanceof Error ? err.message : "Unknown error",
+      },
+      "[deliverable-fulfillment] failed to stamp send outcome",
+    );
+  }
+}
+
+// ─── #3998 D5 — the shared post-mint tail ────────────────────────────────────────
+
+type SendAndStampInput = {
+  siteId: string;
+  flowSlug: string;
+  sessionId: string;
+  grantId: string;
+  email: string;
+  locale: string;
+  defaultLocale: string;
+  copy: DeliverableCopy;
+};
+
+/**
+ * The post-mint tail shared by `fulfillDeliverable` and
+ * `resendDeliverableGrant` (#3998 D5): resolve copy → build link → send →
+ * stamp + log. The ONE place a delivery email is ever sent and its outcome
+ * stamped — extracted so the resend CLI never carries a second copy of the
+ * copy-resolution / link-building logic to drift.
+ */
+async function sendAndStamp(input: SendAndStampInput): Promise<PostMintOutcome> {
+  const { siteId, flowSlug, sessionId, grantId, email, locale, defaultLocale, copy } =
+    input;
+  const logCtx = { siteId, flowSlug, sessionId };
+
+  const fromAddress =
+    process.env.AILK_DELIVERABLE_EMAIL_FROM ??
+    process.env.AILK_LEAD_NOTIFICATION_FROM;
+
+  if (!fromAddress) {
+    await stampOutcome(grantId, "sender_unconfigured", new Date());
+    logOutcome(logCtx, "sender_unconfigured");
+    return "sender_unconfigured";
+  }
+
+  const subject = resolveCopy(copy.subject, locale, defaultLocale);
+  const body = resolveCopy(copy.body, locale, defaultLocale);
+  const cta = copy.cta ? resolveCopy(copy.cta, locale, defaultLocale) : undefined;
+
+  // D5 (#3961): no PII in link params — the link carries the opaque grant id
+  // and nothing else. D3 (#3998): this is the SAME expression on both the
+  // fulfillment path and the resend path, so a resend's link is
+  // byte-identical to the original.
+  const base = process.env.AILK_PUBLIC_API_URL ?? "";
+  const downloadLink = `${base}/v1/deliverables/${grantId}`;
+
+  const sendResult = await sendDeliverableEmail({
+    to: email,
+    fromAddress,
+    subject,
+    body,
+    downloadLink,
+    ...(cta !== undefined && { cta }),
+  });
+
+  const outcome: PostMintOutcome = sendResult.ok ? "sent" : "send_failed";
+  await stampOutcome(grantId, outcome, new Date());
+  logOutcome(logCtx, outcome);
+  return outcome;
+}
+
+// ─── fulfillDeliverable ─────────────────────────────────────────────────────────
+
+export async function fulfillDeliverable(
+  input: FulfillDeliverableInput,
+): Promise<void> {
+  const {
+    siteId,
+    flowSlug,
+    configSnapshot,
+    segment,
+    leadId,
+    sessionId,
+    email,
+    locale,
+  } = input;
+
+  // D4: the block is opt-in per flow. Callers (flow-engine.ts) already gate
+  // the call on this being present; re-checking here is defense in depth,
+  // never load-bearing for the "no block → no call" AC4 regression floor.
+  const block = configSnapshot.deliverables;
+  if (!block) return;
+
+  const logCtx = { siteId, flowSlug, sessionId };
+
+  // D3: no entry (segment derived but unmapped AND no default) — never fail
+  // the submission, just skip fulfillment.
+  const entry = resolveEntry(block.assets, segment);
+  if (!entry) {
+    logOutcome(logCtx, "no_entry");
+    return;
+  }
+
+  // FEAT-074 U4b (#4718) D4 — the `playbook:` virtual asset: a per-lead
+  // COMPILED PlaybookInstance, never an operator-uploaded DeliverableAsset
+  // row. Skips the asset lookup entirely; requires at least one instance
+  // for (siteId, leadId, experimentKey) — the SAME log-and-skip,
+  // no-grant-minted posture `asset_missing` already has for an
+  // un-uploaded key (D4).
+  const playbookKey = playbookExperimentKey(entry.assetKey);
+
+  let assetId: string;
+  if (playbookKey !== undefined) {
+    const instance = await prisma.playbookInstance.findFirst({
+      where: { siteId, leadId, experimentKey: playbookKey },
+      select: { id: true },
+    });
+    if (!instance) {
+      logOutcome(logCtx, "playbook_missing");
+      return;
+    }
+    assetId = entry.assetKey;
+  } else {
+    // A missing row (config references an un-uploaded key) → same
+    // skip-and-log posture (D3).
+    const asset = (await prisma.deliverableAsset.findUnique({
+      where: { siteId_key: { siteId, key: entry.assetKey } },
+    })) as DeliverableAssetRow | null;
+
+    if (!asset) {
+      logOutcome(logCtx, "asset_missing");
+      return;
+    }
+    assetId = asset.id;
+  }
+
+  // D5: the grant IS the token — minted before the send is attempted so a
+  // later email-config gap or send failure never wastes it (a later
+  // manual/operator resend can reuse the same grant id).
+  const grant = (await prisma.deliverableGrant.create({
+    data: { siteId, assetId, leadId, sessionId },
+    select: { id: true },
+  })) as { id: string };
+
+  // #3998 D5: resolve copy → build link → send → stamp + log, shared with
+  // the resend path.
+  await sendAndStamp({
+    siteId,
+    flowSlug,
+    sessionId,
+    grantId: grant.id,
+    email,
+    locale,
+    defaultLocale: configSnapshot.defaultLocale,
+    copy: block.copy,
+  });
+}
+
+// ─── #3998 D3 — resend: reuses the existing grant id, never mints ───────────────
+
+export type ResendGrantError = {
+  kind:
+    | "grant_not_found"
+    | "lead_not_found"
+    | "session_not_found"
+    | "invalid_config_snapshot"
+    | "no_deliverables_block";
+  message: string;
+};
+
+export type ResendGrantResult =
+  | { ok: true; outcome: PostMintOutcome }
+  | { ok: false; error: ResendGrantError };
+
+type DeliverableGrantRow = {
+  id: string;
+  siteId: string;
+  leadId: string;
+  sessionId: string;
+};
+
+type LeadRow = { email: string };
+
+type FlowSessionConfigRow = {
+  flowSlug: string;
+  configSnapshot: unknown;
+  locale: string | null;
+};
+
+/**
+ * Re-sends the delivery email for an existing grant (#3998 D3/D4). Reuses
+ * `grant.id` — this function contains no `deliverableGrant.create` call, so
+ * a resend can never mint a second capability token for one lead. Resolves
+ * copy from the session's PINNED `configSnapshot` (never a live
+ * `FlowDefinition` lookup, #3998 D3) — a mid-flight config edit must never
+ * change what a resend delivers.
+ */
+export async function resendDeliverableGrant(
+  grantId: string,
+): Promise<ResendGrantResult> {
+  const grant = (await prisma.deliverableGrant.findUnique({
+    where: { id: grantId },
+    select: { id: true, siteId: true, leadId: true, sessionId: true },
+  })) as DeliverableGrantRow | null;
+
+  if (!grant) {
+    return {
+      ok: false,
+      error: {
+        kind: "grant_not_found",
+        message: `No deliverable grant found for id "${grantId}".`,
+      },
+    };
+  }
+
+  const lead = (await prisma.lead.findUnique({
+    where: { id: grant.leadId },
+    select: { email: true },
+  })) as LeadRow | null;
+
+  if (!lead) {
+    return {
+      ok: false,
+      error: {
+        kind: "lead_not_found",
+        message: `Grant "${grantId}" references lead "${grant.leadId}", which no longer exists.`,
+      },
+    };
+  }
+
+  const session = (await prisma.flowSession.findUnique({
+    where: { id: grant.sessionId },
+    select: { flowSlug: true, configSnapshot: true, locale: true },
+  })) as FlowSessionConfigRow | null;
+
+  if (!session) {
+    return {
+      ok: false,
+      error: {
+        kind: "session_not_found",
+        message: `Grant "${grantId}" references session "${grant.sessionId}", which no longer exists.`,
+      },
+    };
+  }
+
+  // #3998 D3: re-parse the pinned snapshot through flowConfigSchema — a
+  // snapshot that no longer parses is reported and skipped, never thrown.
+  const parsed = flowConfigSchema.safeParse(session.configSnapshot);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_config_snapshot",
+        message:
+          parsed.error.issues[0]?.message ??
+          "The session's configSnapshot failed schema validation.",
+      },
+    };
+  }
+
+  const config = parsed.data;
+  const block = config.deliverables;
+  if (!block) {
+    return {
+      ok: false,
+      error: {
+        kind: "no_deliverables_block",
+        message: `The session's pinned configSnapshot for grant "${grantId}" carries no deliverables block.`,
+      },
+    };
+  }
+
+  const outcome = await sendAndStamp({
+    siteId: grant.siteId,
+    flowSlug: session.flowSlug,
+    sessionId: grant.sessionId,
+    grantId: grant.id,
+    email: lead.email,
+    locale: session.locale ?? config.defaultLocale,
+    defaultLocale: config.defaultLocale,
+    copy: block.copy,
+  });
+
+  return { ok: true, outcome };
+}
+
+// ─── #3998 D4 — list: sendless grants for one site ──────────────────────────────
+
+export type SendlessGrantRow = {
+  grantId: string;
+  createdAt: Date;
+  sessionId: string;
+};
+
+export type ListSendlessGrantsOptions = {
+  siteId: string;
+  since?: Date;
+  limit?: number;
+};
+
+type DeliverableGrantListRow = {
+  id: string;
+  createdAt: Date;
+  sessionId: string;
+};
+
+/**
+ * Lists grants whose post-mint send never completed (`sendStatus IS NULL`,
+ * #3998 D1's selection term) for one site, oldest first. Read-only — this is
+ * the `deliverable:resend` CLI's default (no-`--grant`) mode.
+ */
+export async function listSendlessGrants(
+  opts: ListSendlessGrantsOptions,
+): Promise<SendlessGrantRow[]> {
+  const rows = (await prisma.deliverableGrant.findMany({
+    where: {
+      siteId: opts.siteId,
+      sendStatus: null,
+      ...(opts.since !== undefined && { createdAt: { gte: opts.since } }),
+    },
+    orderBy: { createdAt: "asc" },
+    select: { id: true, createdAt: true, sessionId: true },
+    ...(opts.limit !== undefined && { take: opts.limit }),
+  })) as DeliverableGrantListRow[];
+
+  return rows.map((row) => ({
+    grantId: row.id,
+    createdAt: row.createdAt,
+    sessionId: row.sessionId,
+  }));
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Per-Organization entitlement resolver (org-scoped billing, #3601).
+ *
+ * The TENANT-layer entitlement answer: "what is this Organization entitled to?"
+ * — distinct from the DEPLOYMENT/operator license layer (`require-paid-tier` →
+ * `checkLicense()`, "does this deployment hold the paid module"). The two
+ * layers compose; neither is folded into the other (spec D6).
+ *
+ * ADR-0009 D3: this is cross-namespace service-layer assembly (it reads the
+ * auth-namespace Organization billing record), so it lives in
+ * `apps/api/src/services/` — NOT in `@working-theory/license`, which stays
+ * JWT-pure / DB-free (only the `Entitlements` TYPE lives there; spec D4).
+ *
+ * Keyed on the Organization; members inherit (no per-user billing read). This
+ * foundation fills `features` + `limits.static` (tier + seat count) and returns
+ * `limits.metered` as the reserved empty shape FEAT-047 (#3679) fills — this
+ * spec builds NO metering engine (spec D5).
+ */
+import type { Entitlements } from "@working-theory/license";
+
+import { prisma } from "../lib/prisma.js";
+
+/**
+ * Feature flags unlocked per tier. Free unlocks none; every paid tier unlocks
+ * the Pro v1 feature set (mirrors `ProFeature` in `@working-theory/license`).
+ * A flat projection, matching AILK's flat billing shape (spec D1) — the richer
+ * per-plan allowance model is FEAT-047's, not this foundation's.
+ */
+const PAID_FEATURES: readonly string[] = [
+  "lead-destinations",
+  "lead-provenance",
+  "schema-pack-registry",
+  "onboard-site",
+];
+
+function featuresForTier(tier: string): readonly string[] {
+  return tier === "free" ? [] : PAID_FEATURES;
+}
+
+/**
+ * Resolve the entitlements for one Organization. An unknown / un-billed org
+ * (no row, or defaulted columns) resolves to the free-tier baseline
+ * (`seats: 1`, `tier: "free"`, no features) — safe-by-default.
+ *
+ * `limits.metered` is returned as the reserved empty `MeteredLimits` (`{}`);
+ * FEAT-047 (#3679) fills it when it ports the metering engine.
+ */
+export async function resolveEntitlements(
+  organizationId: string,
+): Promise<Entitlements> {
+  const org = await prisma.organization.findUnique({
+    where: { id: organizationId },
+    select: { tier: true, seatCount: true },
+  });
+
+  const tier = org?.tier ?? "free";
+  const seats = org?.seatCount ?? 1;
+
+  return {
+    features: featuresForTier(tier),
+    limits: {
+      static: { seats, tier },
+      // RESERVED — FEAT-047 (#3679) fills the metered side; empty here.
+      metered: {},
+    },
+  };
+}
+
+/**
+ * The org's Stripe billing-customer identity (#3701 — the apps/api
+ * predecessor to the org-billing UI, #3697).
+ *
+ * `billingCustomerId` is the RAW Stripe customer id — a server-side-only
+ * value. Callers (the `/v1/billing` route family) must never return it to the
+ * client: the read route projects it to a boolean `hasBillingCustomer`
+ * presence flag (spec D2), and the portal route uses it only as an input to
+ * `createBillingPortalSession`, never in a response body or log line.
+ */
+export interface OrgBillingIdentity {
+  /** Raw Stripe customer id (`cus_xxx`), or `null` when the org has none yet. */
+  billingCustomerId: string | null;
+}
+
+/**
+ * Reads the org's Stripe billing-customer id by explicit organization id.
+ * Touches only the `Organization.billingCustomerId` field — the sanctioned
+ * tenant-scope exception for this file (architecture.yaml § Tenant-scope
+ * boundary, #3601): no un-scoped tenant/content enumeration.
+ *
+ * An unknown org resolves to `{ billingCustomerId: null }` — safe-by-default,
+ * mirroring `resolveEntitlements`'s un-billed-org handling.
+ */
+export async function getOrgBillingIdentity(
+  organizationId: string,
+): Promise<OrgBillingIdentity> {
+  const org = await prisma.organization.findUnique({
+    where: { id: organizationId },
+    select: { billingCustomerId: true },
+  });
+
+  return { billingCustomerId: org?.billingCustomerId ?? null };
+}