create-ailk 0.19.0 → 0.20.0

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

@@ -21,6 +21,10 @@
  *     only while its `userId` is the caller.
  *   - `setPersonPlanOffering` — the plan's only writer (#7877 D8), called by
  *     the Admin's plan route and the checkout-lead rule in `lead-routing.ts`.
+ *   - the contact details (#8435): `findOrCreatePerson` fills BLANK contact
+ *     fields of an uncurated Person (D4); `updatePersonContact` (the
+ *     operator's save), `ensureMemberPerson` and `setOwnPersonContact` (the
+ *     client's save) overwrite and stamp who confirmed them (D9, D11).
  *
  * ## Match order (D3) — fixed, and there is no merge
  *
@@ -76,6 +80,7 @@
 
 import type { Prisma } from "@working-theory/database";
 import type { Id } from "@working-theory/ids";
+import type { PersonContactPatch } from "@working-theory/validation";
 
 import { prisma } from "../lib/prisma.js";
 
@@ -127,6 +132,317 @@ export function normalizePersonName(raw: unknown): string | null {
   return cleaned === "" ? null : cleaned;
 }
 
+// ─── Contact normalization (#8435 D3) ────────────────────────────────────────
+
+export type PersonAddress = {
+  addressLine1: string;
+  addressLine2: string | null;
+  city: string;
+  region: string;
+  postalCode: string;
+  country: string;
+};
+
+export type PersonContact = {
+  givenName: string | null;
+  familyName: string | null;
+  telephone: string | null;
+  address: PersonAddress | null;
+  companyName: string | null;
+  jobTitle: string | null;
+};
+
+/**
+ * What a capture offers, as untrusted `unknown` values: the magnet's tagged
+ * answers or a caller's explicit contact (`RouteLeadOptions.contact`).
+ */
+export type LeadContact = {
+  name?: unknown;
+  givenName?: unknown;
+  familyName?: unknown;
+  phone?: unknown;
+  address?: unknown;
+  company?: unknown;
+  jobTitle?: unknown;
+};
+
+/** The widths of the person-level text columns, in code points. */
+const CONTACT_MAX = {
+  givenName: 100,
+  familyName: 100,
+  companyName: 200,
+  jobTitle: 100,
+} as const;
+/** The address parts' widths — `ADDRESS_PART_MAX_LENGTHS` in `packages/validation`. */
+const ADDRESS_MAX = {
+  addressLine1: 100,
+  addressLine2: 60,
+  city: 60,
+  region: 40,
+  postalCode: 20,
+} as const;
+const E164 = /^\+[1-9]\d{6,14}$/;
+const SHORT_REGION = /^[A-Za-z0-9]{1,3}$/;
+const ALPHA2 = /^[A-Z]{2}$/;
+/**
+ * The code-point ranges `CONTACT_STRIP` removes (SEC-8435-L): `NAME_STRIP`'s
+ * C0/C1 and bidi controls plus the zero-width characters U+200B–U+200D and
+ * U+FEFF and the separators U+2028/U+2029. Numbers, not a regex literal, so no
+ * tool can rewrite a separator into a line break inside it. The same set
+ * `packages/validation`'s `people-contact.ts` strips on the wire.
+ */
+const CONTACT_STRIPPED: ReadonlyArray<readonly [number, number]> = [
+  [0x0000, 0x001f],
+  [0x007f, 0x009f],
+  [0x200b, 0x200f],
+  [0x2028, 0x2029],
+  [0x202a, 0x202e],
+  [0x2066, 0x2069],
+  [0xfeff, 0xfeff],
+];
+
+function stripContactChars(raw: string): string {
+  let out = "";
+  for (const ch of raw) {
+    const cp = ch.codePointAt(0) ?? 0;
+    if (!CONTACT_STRIPPED.some(([lo, hi]) => cp >= lo && cp <= hi)) out += ch;
+  }
+  return out;
+}
+
+const cutToCodePoints = (value: string, max: number): string =>
+  Array.from(value).slice(0, max).join("");
+
+/** Stripped, trimmed, cut to `max` code points; empty or not a string → `null`. */
+function normalizeContactText(raw: unknown, max: number): string | null {
+  if (typeof raw !== "string") return null;
+  const cleaned = cutToCodePoints(stripContactChars(raw).trim(), max);
+  return cleaned === "" ? null : cleaned;
+}
+
+/**
+ * Strip spaces, `( ) . -` (and the invisible characters), then the result
+ * must be an E.164 number — else `null`.
+ */
+export function normalizeTelephone(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const compact = stripContactChars(raw)
+    .replace(/[ ().-]/g, "")
+    .trim();
+  return E164.test(compact) ? compact : null;
+}
+
+/**
+ * An address as stored: whole or not at all. Every required part must be a
+ * non-empty string within its width after stripping; a short region is
+ * upper-cased (C3); the country must be an upper-case alpha-2 code.
+ */
+function normalizeAddress(raw: unknown): PersonAddress | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+    return null;
+  const value = raw as Record<string, unknown>;
+  const part = (key: keyof typeof ADDRESS_MAX): string | null => {
+    const field = value[key];
+    if (typeof field !== "string") return null;
+    const cleaned = stripContactChars(field).trim();
+    return cleaned === "" || Array.from(cleaned).length > ADDRESS_MAX[key]
+      ? null
+      : cleaned;
+  };
+  const addressLine1 = part("addressLine1");
+  const city = part("city");
+  const region = part("region");
+  const postalCode = part("postalCode");
+  const country = value["country"];
+  if (
+    addressLine1 === null ||
+    city === null ||
+    region === null ||
+    postalCode === null ||
+    typeof country !== "string" ||
+    !ALPHA2.test(country)
+  ) {
+    return null;
+  }
+  const line2Raw = value["addressLine2"];
+  const line2 = part("addressLine2");
+  // An over-long or non-string second line makes the address unusable; an
+  // absent or blank one is simply null.
+  if (line2 === null && line2Raw !== undefined && line2Raw !== null) {
+    if (
+      typeof line2Raw !== "string" ||
+      stripContactChars(line2Raw).trim() !== ""
+    )
+      return null;
+  }
+  return {
+    addressLine1,
+    addressLine2: line2,
+    city,
+    region: SHORT_REGION.test(region) ? region.toUpperCase() : region,
+    postalCode,
+    country,
+  };
+}
+
+/** Capture-side: every usable field, each normalized; unusable ones dropped. */
+export function normalizeCapturedContact(
+  raw: LeadContact,
+): Partial<PersonContact> {
+  const out: Partial<PersonContact> = {};
+  const givenName = normalizeContactText(raw.givenName, CONTACT_MAX.givenName);
+  if (givenName !== null) out.givenName = givenName;
+  const familyName = normalizeContactText(
+    raw.familyName,
+    CONTACT_MAX.familyName,
+  );
+  if (familyName !== null) out.familyName = familyName;
+  const telephone = normalizeTelephone(raw.phone);
+  if (telephone !== null) out.telephone = telephone;
+  const address = normalizeAddress(raw.address);
+  if (address !== null) out.address = address;
+  const companyName = normalizeContactText(
+    raw.company,
+    CONTACT_MAX.companyName,
+  );
+  if (companyName !== null) out.companyName = companyName;
+  const jobTitle = normalizeContactText(raw.jobTitle, CONTACT_MAX.jobTitle);
+  if (jobTitle !== null) out.jobTitle = jobTitle;
+  return out;
+}
+
+// ─── The contact columns, as rows and as the wire's shape ───────────────────
+
+/** The thirteen contact columns a read names (`select`). */
+export const PERSON_CONTACT_SELECT = {
+  givenName: true,
+  familyName: true,
+  telephone: true,
+  addressLine1: true,
+  addressLine2: true,
+  addressCity: true,
+  addressRegion: true,
+  addressPostalCode: true,
+  addressCountry: true,
+  companyName: true,
+  jobTitle: true,
+  contactConfirmedAt: true,
+  contactConfirmedBy: true,
+} as const;
+
+export type PersonContactRow = {
+  givenName: string | null;
+  familyName: string | null;
+  telephone: string | null;
+  addressLine1: string | null;
+  addressLine2: string | null;
+  addressCity: string | null;
+  addressRegion: string | null;
+  addressPostalCode: string | null;
+  addressCountry: string | null;
+  companyName: string | null;
+  jobTitle: string | null;
+  contactConfirmedAt: Date | null;
+  contactConfirmedBy: string | null;
+};
+
+/** The wire's contact: every key present, `null` where blank, the address whole or `null`. */
+export function personContactFromRow(row: PersonContactRow): PersonContact {
+  // `?? null` so a row that does not carry a column reads as blank, never as
+  // `undefined` on the wire.
+  const line1 = row.addressLine1 ?? null;
+  const city = row.addressCity ?? null;
+  const region = row.addressRegion ?? null;
+  const postalCode = row.addressPostalCode ?? null;
+  const country = row.addressCountry ?? null;
+  const address: PersonAddress | null =
+    line1 !== null && city !== null && region !== null && postalCode !== null && country !== null
+      ? {
+          addressLine1: line1,
+          addressLine2: row.addressLine2 ?? null,
+          city,
+          region,
+          postalCode,
+          country,
+        }
+      : null;
+  return {
+    givenName: row.givenName ?? null,
+    familyName: row.familyName ?? null,
+    telephone: row.telephone ?? null,
+    address,
+    companyName: row.companyName ?? null,
+    jobTitle: row.jobTitle ?? null,
+  };
+}
+
+/** Who last saved the contact by hand, and when — `null` while only captures have written it. */
+export function contactConfirmedFromRow(
+  row: Pick<PersonContactRow, "contactConfirmedAt" | "contactConfirmedBy">,
+): { by: "operator" | "client"; at: string } | null {
+  if (row.contactConfirmedAt === null || row.contactConfirmedAt === undefined)
+    return null;
+  if (
+    row.contactConfirmedBy !== "operator" &&
+    row.contactConfirmedBy !== "client"
+  )
+    return null;
+  return {
+    by: row.contactConfirmedBy,
+    at: row.contactConfirmedAt.toISOString(),
+  };
+}
+
+type AddressColumns = {
+  addressLine1: string | null;
+  addressLine2: string | null;
+  addressCity: string | null;
+  addressRegion: string | null;
+  addressPostalCode: string | null;
+  addressCountry: string | null;
+};
+
+/** The six address columns for an address — all six `null` for `null`. */
+function addressColumns(address: PersonAddress | null): AddressColumns {
+  return {
+    addressLine1: address?.addressLine1 ?? null,
+    addressLine2: address?.addressLine2 ?? null,
+    addressCity: address?.city ?? null,
+    addressRegion: address?.region ?? null,
+    addressPostalCode: address?.postalCode ?? null,
+    addressCountry: address?.country ?? null,
+  };
+}
+
+/** The scalar contact fields, each its own column of the same name. */
+const SCALAR_CONTACT_FIELDS = [
+  "givenName",
+  "familyName",
+  "telephone",
+  "companyName",
+  "jobTitle",
+] as const;
+
+/** Every supplied contact field as insert columns. */
+function contactInsertColumns(
+  contact: Partial<PersonContact>,
+): Record<string, string | null> {
+  const columns: Record<string, string | null> = {};
+  for (const field of SCALAR_CONTACT_FIELDS) {
+    const value = contact[field];
+    if (value !== undefined && value !== null) columns[field] = value;
+  }
+  if (contact.address) Object.assign(columns, addressColumns(contact.address));
+  return columns;
+}
+
+/** `"Ada" + "Lovelace"` → `"Ada Lovelace"`, `"Ada"` alone → `"Ada"`, neither → `null`. */
+function joinedName(contact: Partial<PersonContact>): string | null {
+  return normalizePersonName(
+    [contact.givenName, contact.familyName].filter((part) => part).join(" "),
+  );
+}
+
 function usableCustomerId(raw: string | null | undefined): string | null {
   return typeof raw === "string" &&
     raw.length > 0 &&
@@ -156,6 +472,16 @@ type MatchedPerson = {
   name: string | null;
   userId: string | null;
   billingCustomerId: string | null;
+  // #8435 D4.4 — the blank-sentinels the contact fill reads. A value reading
+  // `undefined` (a test double that does not carry the key) is "not blank",
+  // and an undefined `contactConfirmedAt` is "confirmed": no fill runs.
+  givenName?: string | null;
+  familyName?: string | null;
+  telephone?: string | null;
+  addressLine1?: string | null;
+  companyName?: string | null;
+  jobTitle?: string | null;
+  contactConfirmedAt?: Date | null;
 };
 
 const MATCH_SELECT = {
@@ -163,6 +489,13 @@ const MATCH_SELECT = {
   name: true,
   userId: true,
   billingCustomerId: true,
+  givenName: true,
+  familyName: true,
+  telephone: true,
+  addressLine1: true,
+  companyName: true,
+  jobTitle: true,
+  contactConfirmedAt: true,
 } as const;
 
 /**
@@ -199,6 +532,53 @@ async function enrichMatched(
   return billing;
 }
 
+/**
+ * The contact fill on an email match (#8435 D4.3): for each supplied field
+ * whose stored value is `null`, one guarded `updateMany`; the address is one
+ * statement guarded on `addressLine1: null` writing all six. It runs ONLY
+ * while the Person is uncurated — linked to no user and never saved by hand
+ * (`contactConfirmedAt` null) — and every guard repeats that condition, so a
+ * link or a save that lands between the read and the write still wins
+ * (SEC-8435-A). A stored value, whoever wrote it, is never overwritten.
+ * Best-effort: a failed write is swallowed, never refusing the capture.
+ */
+async function fillBlankContact(
+  db: PersonDb,
+  workspaceId: string,
+  person: MatchedPerson,
+  contact: Partial<PersonContact>,
+  plainName: string | null,
+): Promise<void> {
+  if (person.userId !== null || person.contactConfirmedAt !== null) return;
+  const uncurated = { id: person.id, workspaceId, userId: null, contactConfirmedAt: null };
+  try {
+    for (const field of SCALAR_CONTACT_FIELDS) {
+      const value = contact[field];
+      if (value !== undefined && value !== null && person[field] === null) {
+        await db.person.updateMany({
+          where: { ...uncurated, [field]: null } as Prisma.PersonWhereInput,
+          data: { [field]: value } as Prisma.PersonUpdateManyMutationInput,
+        });
+      }
+    }
+    if (contact.address && person.addressLine1 === null) {
+      await db.person.updateMany({
+        where: { ...uncurated, addressLine1: null },
+        data: addressColumns(contact.address),
+      });
+    }
+    // The display name from given + family, only when nothing named it.
+    if (plainName === null && person.name === null) {
+      const derived = joinedName(contact);
+      if (derived !== null) {
+        await db.person.updateMany({ where: { ...uncurated, name: null }, data: { name: derived } });
+      }
+    }
+  } catch {
+    // A contact fill never changes the capture's outcome.
+  }
+}
+
 /**
  * Find this workspace's Person for an email, or create it.
  *
@@ -206,6 +586,9 @@ async function enrichMatched(
  * @param input.email the raw address; normalized here.
  * @param input.name an optional display name, from anonymous text.
  * @param input.billingCustomerId an optional provider customer id.
+ * @param input.contact optional, already-normalized contact fields
+ *   (`normalizeCapturedContact`): a created Person carries them all; a matched
+ *   uncurated Person gains only the ones it has blank (#8435 D4).
  * @param db the shared client by default; the appointment path passes its
  *   transaction client so the step runs on the lock's own connection.
  */
@@ -215,6 +598,7 @@ export async function findOrCreatePerson(
     email: string;
     name?: string | null;
     billingCustomerId?: string | null;
+    contact?: Partial<PersonContact>;
   },
   db: PersonDb = prisma,
 ): Promise<FindOrCreatePersonResult> {
@@ -225,6 +609,8 @@ export async function findOrCreatePerson(
   }
   const name = normalizePersonName(input.name);
   const customerId = usableCustomerId(input.billingCustomerId);
+  const contact = input.contact ?? {};
+  const hasContact = Object.keys(contact).length > 0;
 
   try {
     // Step 2 — a customer id names its Person; nothing is written.
@@ -253,6 +639,7 @@ export async function findOrCreatePerson(
     });
     if (byEmail) {
       const billing = await enrichMatched(db, workspaceId, byEmail, name, customerId);
+      if (hasContact) await fillBlankContact(db, workspaceId, byEmail, contact, name);
       return {
         ok: true,
         value: { personId: byEmail.id as Id<"person">, created: false, billing },
@@ -265,11 +652,13 @@ export async function findOrCreatePerson(
         {
           workspaceId,
           email,
-          name,
+          // A supplied name wins; else given + family joined (#8435 D4.2).
+          name: name ?? joinedName(contact),
           ...(customerId !== null && {
             billingProvider: "stripe",
             billingCustomerId: customerId,
           }),
+          ...(hasContact && contactInsertColumns(contact)),
         },
       ],
       skipDuplicates: true,
@@ -291,6 +680,7 @@ export async function findOrCreatePerson(
     }
     // A concurrent create won the race: treat its row as an email match.
     const billing = await enrichMatched(db, workspaceId, winner, name, customerId);
+    if (hasContact) await fillBlankContact(db, workspaceId, winner, contact, name);
     return {
       ok: true,
       value: { personId: winner.id as Id<"person">, created: false, billing },
@@ -539,3 +929,113 @@ export async function setPersonPlanOffering(
     return "internal_error";
   }
 }
+
+// ─── The two human edits of the contact (#8435 D9, D11) ───────────────────────
+
+export type SavedContact = {
+  contact: PersonContact;
+  confirmed: { by: "operator" | "client"; at: string } | null;
+};
+
+export type SaveContactOutcome =
+  | { kind: "saved"; value: SavedContact }
+  | { kind: "not_found" | "internal_error" };
+
+/** The columns a patch writes: only the keys present; the address key writes (or clears) all six. */
+function patchColumns(patch: PersonContactPatch): Record<string, string | null> {
+  const columns: Record<string, string | null> = {};
+  for (const field of SCALAR_CONTACT_FIELDS) {
+    const value = patch[field];
+    if (value !== undefined) columns[field] = value;
+  }
+  if (patch.address !== undefined) Object.assign(columns, addressColumns(patch.address));
+  return columns;
+}
+
+async function readSavedContact(workspaceId: string, personId: string): Promise<SaveContactOutcome> {
+  const row = await prisma.person.findFirst({
+    where: { id: personId, workspaceId },
+    select: PERSON_CONTACT_SELECT,
+  });
+  if (!row) return { kind: "not_found" };
+  return { kind: "saved", value: { contact: personContactFromRow(row), confirmed: contactConfirmedFromRow(row) } };
+}
+
+/**
+ * The operator's save (#8435 D9): one `updateMany` scoped by the
+ * server-resolved workspace, writing only the keys present plus the
+ * confirmation stamp (`operator`). No row → `not_found`. Never throws.
+ */
+export async function updatePersonContact(
+  workspaceId: string,
+  personId: string,
+  patch: PersonContactPatch,
+): Promise<SaveContactOutcome> {
+  try {
+    const { count } = await prisma.person.updateMany({
+      where: { id: personId, workspaceId },
+      data: {
+        ...patchColumns(patch),
+        contactConfirmedAt: new Date(),
+        contactConfirmedBy: "operator",
+      } as Prisma.PersonUpdateManyMutationInput,
+    });
+    if (count === 0) return { kind: "not_found" };
+    return await readSavedContact(workspaceId, personId);
+  } catch {
+    return { kind: "internal_error" };
+  }
+}
+
+/**
+ * The Person a client's first contact save belongs to (#8435 D11): the
+ * caller's VERIFIED email's Person in this workspace, found or created, and
+ * linked to the caller through `stampPersonUser`'s own rule. Anything but a
+ * stamped or already-linked outcome is `unavailable` — nothing is written for
+ * the contact. Never throws.
+ */
+export async function ensureMemberPerson(
+  workspaceId: string,
+  userId: string,
+): Promise<{ ok: true; personId: string } | { ok: false }> {
+  try {
+    const verified = await findVerifiedEmail(userId);
+    if (!verified.ok) return { ok: false };
+    const person = await findOrCreatePerson(workspaceId, { email: verified.value.email });
+    if (!person.ok) return { ok: false };
+    const outcome = await stampPersonUser(workspaceId, person.value.personId, userId);
+    if (outcome !== "stamped" && outcome !== "already_linked") return { ok: false };
+    return { ok: true, personId: person.value.personId };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * The client's save (#8435 D11): ONE `updateMany` guarded on `{ id,
+ * workspaceId, userId }` — only the caller's own linked Person is ever
+ * written — replacing all six contact keys with the body and stamping
+ * `client`, so no value the client never saw survives it (SEC-8435-B). No
+ * row → `not_found`. Never throws.
+ */
+export async function setOwnPersonContact(
+  workspaceId: string,
+  personId: string,
+  userId: string,
+  contact: PersonContactPatch,
+): Promise<SaveContactOutcome> {
+  try {
+    const { count } = await prisma.person.updateMany({
+      where: { id: personId, workspaceId, userId },
+      data: {
+        ...patchColumns(contact),
+        contactConfirmedAt: new Date(),
+        contactConfirmedBy: "client",
+      } as Prisma.PersonUpdateManyMutationInput,
+    });
+    if (count === 0) return { kind: "not_found" };
+    return await readSavedContact(workspaceId, personId);
+  } catch {
+    return { kind: "internal_error" };
+  }
+}

package/templates/apps/api/src/services/project-listings.ts

@@ -868,10 +868,15 @@ export async function startProjectListingDraft(
       select: { id: true },
     });
     const subject = { siteId, subjectType: "project_listing", subjectId: created.id };
+    // #8438 D3 — a listing names no magnet slug (ProjectListing carries no
+    // link to its flow), so `magnet` would be unprovable: the source is `api`.
     if (consents) {
-      await recordConsent({ ...subject, locale, config: consentConfig, consents }, tx);
+      await recordConsent(
+        { ...subject, personId: null, source: "api", locale, config: consentConfig, consents },
+        tx,
+      );
     } else {
-      await recordLegacyConsent({ ...subject, config: consentConfig }, tx);
+      await recordLegacyConsent({ ...subject, source: "api", config: consentConfig }, tx);
     }
     return created;
   });

package/templates/apps/api/src/services/public-site-resolver.ts

@@ -352,14 +352,33 @@ export async function resolvePublicContentAdapter(
   if (site.kind === "not-required" || resolvedAdapterKind() !== "database") {
     return getContentAdapter();
   }
+  return workspaceContentAdapter(site.workspaceId);
+}
+
+/**
+ * The content adapter holding ONE workspace's own pages, or `null` when no
+ * content is that workspace's (#8514 D9, C13). On the database adapter it is
+ * that workspace's database adapter. Off it, the shared content is the
+ * deployment's one site — the default workspace's — so only that workspace
+ * gets it and every other workspace gets `null`, never the hub's pages
+ * (SEC-8514-I). The Admin's plan picker reads its offerings through it.
+ */
+export async function workspaceContentAdapter(
+  workspaceId: string,
+): Promise<ContentAdapter | null> {
+  if (resolvedAdapterKind() !== "database") {
+    // Deferred — see the module-load note in this file's header (#5852 D6).
+    const { resolveDefaultWorkspaceId } = await import("./default-tenant.js");
+    return (await resolveDefaultWorkspaceId()) === workspaceId ? getContentAdapter() : null;
+  }
 
-  // The database path, and the only caller that needs apps/api's client. The
+  // The database path, and the only one that needs apps/api's client. The
   // import is deferred for the reason the header gives (#5852 D6), and the
   // generated client is structurally wider than the narrow read surface the
   // adapter declares — the cast names that, and nothing else.
   const { prisma } = await import("../lib/prisma.js");
   return getContentAdapter({
-    workspaceId: site.workspaceId,
+    workspaceId,
     prisma: prisma as unknown as ArtifactPrismaClient,
   });
 }