create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,176 @@
+/**
+ * @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 tenant-context.ts's `listTenancy` — 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 tenant-context.ts / tenant-db.ts). That delegation is
+ * module-conditional as of #5182; see the note above TENANT_CONTEXT_SPECIFIER.
+ *
+ * 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 { isModuleEnabled } from "../config/modules.js";
+import { prisma } from "../lib/prisma.js";
+
+/**
+ * `tenant-context.ts` is a multi-tenant SLICE file the OSS strip removes
+ * (#5182), and `listTenancy` is a VALUE — a runtime call, not an erasable type
+ * — so neither a static import nor a literal `await import("./tenant-context.js")`
+ * survives the strip: `tsc` resolves a string-literal specifier whether or not
+ * the branch containing it can ever run, and either form is TS2307 on the
+ * public tree (spec D1).
+ *
+ * The remedy is the one `server.ts` and `routes/content/index.ts` already use:
+ * gate the call on `isModuleEnabled('multi-tenant')` and read the specifier
+ * from this constant so it is not a literal written at the call site. What
+ * defeats resolution is the INDIRECTION, not the type of the value.
+ *
+ * `apps/api` is a `tsc`-only surface with no bundler, which is the precondition
+ * that makes this mechanism sound here — it is NOT sound in `packages/ui`,
+ * where webpack compiles a non-analysable `import()` to an empty context.
+ *
+ * Semantics on a build without the module: there is no workspace concept at
+ * all, so a user has no workspaces, so no lead can match `siteId ∈ workspaceIds`
+ * — which is exactly the zero-workspace early return below. The no-op is
+ * correct rather than degraded.
+ */
+const TENANT_CONTEXT_SPECIFIER = "./tenant-context.js";
+
+/** The one export this file needs from the multi-tenant slice. */
+interface TenantContextSlice {
+  listTenancy: (params: {
+    userId: Id<"user">;
+    sessionTenant: undefined;
+  }) => Promise<
+    | {
+        ok: true;
+        value: { organizations: Array<{ workspaces: Array<{ id: string }> }> };
+      }
+    | { ok: false; error: { message: string } }
+  >;
+}
+
+// ─── 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 {
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { id: true, email: true, emailVerified: true },
+    });
+
+    if (!user) {
+      return {
+        ok: false,
+        error: { kind: "user_not_found", message: "User not found" },
+      };
+    }
+
+    // D2 — the verified-email gate is a service-level invariant, not a
+    // caller obligation: it cannot be bypassed by a wrong call-site.
+    if (!user.emailVerified) {
+      return { ok: true, count: 0, promoted: [] };
+    }
+
+    // D3/D4 — resolve the verifying user's OWN workspaces via the sole
+    // tenant-context assembler (never a raw membership or workspace model
+    // query in this file). Module-conditional per the note on
+    // TENANT_CONTEXT_SPECIFIER above: no multi-tenant module, no workspaces.
+    let workspaceIds: string[] = [];
+    if (isModuleEnabled("multi-tenant")) {
+      const specifier: string = TENANT_CONTEXT_SPECIFIER;
+      const { listTenancy } = (await import(specifier)) as TenantContextSlice;
+      const tenancy = await listTenancy({
+        userId: user.id as Id<"user">,
+        sessionTenant: undefined,
+      });
+      if (!tenancy.ok) {
+        return {
+          ok: false,
+          error: { kind: "internal_error", message: tenancy.error.message },
+        };
+      }
+
+      workspaceIds = tenancy.value.organizations.flatMap((org) =>
+        org.workspaces.map((workspace) => workspace.id as string),
+      );
+    }
+
+    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 } };
+  }
+}

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

@@ -26,11 +26,11 @@ import { enrichLead } from "./enrichment-shim.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
-export type LeadKind = "lead" | "subscribe" | "callback";
+export type LeadKind = "submit" | "subscribe" | "callback";
 
 export type RouteLeadInput =
   | {
-      kind: "lead";
+      kind: "submit";
       siteId: string;
       source: string;
       email: string;
@@ -99,7 +99,7 @@ type PersistResult =
   | { ok: false; error: string };
 
 async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
-  if (input.kind === "lead") {
+  if (input.kind === "submit") {
     const row = (await prisma.lead.create({
       data: {
         siteId: input.siteId,

package/templates/apps/api/src/services/listing-config.ts

@@ -0,0 +1,102 @@
+/**
+ * @file listing-config.ts
+ * @description The per-site project-listings config read (#5033) — one
+ * function, `listingConfigFor`, that resolves a site's window bounds and
+ * featured switch.
+ *
+ * This is the whole reason the surface is a platform feature rather than one
+ * site's: the ninety-day maximum window and twenty-one-day default that used
+ * to be `BACKLINK_DAYS = 90` in `project-listing-decision.ts` were
+ * salessmyth/samhenry's commercial terms compiled into the published package.
+ * They are configuration now.
+ *
+ * The read is SERVER-SIDE ONLY. No route accepts any of these values from a
+ * request body — the apply payload carries a *requested* window and the
+ * server clamps it (`clampWindowDays`). A founder who could post their own
+ * bound could post an unbounded one.
+ *
+ * A site with no `SiteListingConfig` row gets `SITE_LISTING_CONFIG_DEFAULTS`,
+ * the schema's own conservative defaults — deliberately not any site's terms.
+ *
+ * A row whose stored blob fails the schema gets the same defaults rather than
+ * throwing: an anonymous application must not 500 because an operator saved a
+ * malformed config. That fallback is the one direction in which this read can
+ * end up MORE permissive than the operator wrote, which is why
+ * `siteListingConfigSchema` clamps the operator mistakes it can (a default
+ * that no longer fits under a tightened maximum) instead of rejecting them,
+ * and why this logs at ERROR: reaching here means a site is running on
+ * platform terms rather than its own, and someone needs to know.
+ */
+
+import { logger } from "@working-theory/observability";
+import {
+  siteListingConfigSchema,
+  SITE_LISTING_CONFIG_DEFAULTS,
+  type SiteListingConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+import { currentSiteId } from "../lib/site.js";
+
+export async function listingConfigFor(siteId: string): Promise<SiteListingConfig> {
+  const row = await prisma.siteListingConfig.findUnique({
+    where: { siteId },
+    select: { data: true },
+  });
+  if (!row) return SITE_LISTING_CONFIG_DEFAULTS;
+
+  const parsed = siteListingConfigSchema.safeParse(row.data);
+  if (!parsed.success) {
+    logger.error(
+      { siteId, issues: parsed.error.issues },
+      "[listing-config] stored config failed its schema — this site is running on PLATFORM defaults, not its own terms",
+    );
+    return SITE_LISTING_CONFIG_DEFAULTS;
+  }
+  return parsed.data;
+}
+
+/**
+ * Resolve a site from its PUBLIC SITE KEY (#5048 D2).
+ *
+ * This is the function that lets the consuming site's proxy route go away. The
+ * anonymous application names its site with a public key; the server maps that
+ * key to a `siteId` HERE, so no request body ever carries a tenant identifier
+ * and no site has to stand up a route whose only job is to append one.
+ *
+ * The key is not a credential. It ships in browser JavaScript and in an agent's
+ * request by design (#5039 keeps that channel open), and holding it grants
+ * nothing beyond the ability to open a draft the holder must then complete.
+ * Treating it as a secret would buy nothing and would break both callers.
+ *
+ * Two resolution paths, in order:
+ *
+ *   1. A `SiteListingConfig` row whose `publicKey` matches. This is the
+ *      multi-tenant path and the only one that can name a site other than the
+ *      deployment's own.
+ *   2. `AILK_LISTING_PUBLIC_KEY`, matched against the env, resolving to
+ *      `currentSiteId()`. This is the SINGLE-TENANT path: the default
+ *      `create-ailk` scaffold is one customer per deployment and has no
+ *      config row, so requiring one would mean a site could not accept an
+ *      application until an operator wrote a database row.
+ *
+ * An unmatched key resolves to `null` and the route answers 400. It does NOT
+ * fall through to `currentSiteId()`: a typo would otherwise silently file one
+ * site's applications against another.
+ *
+ * The env comparison is a plain `===` on an opaque public identifier — there is
+ * no secret here to leak through a timing difference, and pretending otherwise
+ * would imply a guarantee this value does not carry.
+ */
+export async function siteIdForPublicKey(publicKey: string): Promise<string | null> {
+  const row = await prisma.siteListingConfig.findUnique({
+    where: { publicKey },
+    select: { siteId: true },
+  });
+  if (row) return row.siteId;
+
+  const envKey = process.env["AILK_LISTING_PUBLIC_KEY"];
+  if (envKey && envKey === publicKey) return currentSiteId();
+
+  return null;
+}