create-ailk 0.19.0 → 0.20.0

package/templates/database/__tests__/person-contact.db.test.ts

@@ -0,0 +1,563 @@
+/**
+ * @file person-contact.db.test.ts
+ *
+ * LIVE-DATABASE proof of the contact columns on the client record (#8435,
+ * spec docs/specs/8435-contact-details-on-the-client-spec.md D1, D2; AC-1 and
+ * the backfill half of AC-3). Requires DATABASE_URL pointing at a Postgres
+ * with the migrations applied — every live suite SKIPS when DATABASE_URL is
+ * unset, keeping the workspace Jest run DB-free (the repo convention; the
+ * `apps/api Route Tests (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `person.db.test.ts` does. What it proves
+ * that a mock cannot:
+ *   1. The people table's four new CHECKs (E.164 telephone, alpha-2 country,
+ *      whole-or-nothing address, the confirmation pair) and the two new
+ *      composite foreign keys (callbacks.person_id, subscribers.person_id).
+ *   2. The backfill: the committed fixture, backfilled by the migration's own
+ *      text, yields exactly the expected Persons and stamps; the post-cutover
+ *      script is byte-identical, changes nothing on a second run, and stamps
+ *      a subscriber written after the first.
+ *
+ * Two cases need no database and always run: the script and the migration
+ * are byte-identical, and the Person model carries no deferred column.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+type Fixture = {
+  workspaces: Record<string, string>;
+  input: {
+    people: Array<{
+      key: string;
+      workspace: string;
+      email: string;
+      name: string | null;
+      user: string | null;
+    }>;
+    subscribers: Array<{
+      key: string;
+      workspace: string;
+      email: string;
+      createdAt: string;
+    }>;
+    callbacks: Array<{
+      key: string;
+      workspace: string;
+      name: string;
+      phone: string;
+      payload: Record<string, unknown>;
+      buyerEmail: string | null;
+      createdAt: string;
+    }>;
+  };
+  expected: {
+    people: Array<{
+      workspace: string;
+      email: string;
+      name: string | null;
+      telephone: string | null;
+    }>;
+    stamps: Record<string, { workspace: string; email: string } | null>;
+  };
+};
+
+const fixture = JSON.parse(
+  readFileSync(
+    join(__dirname, "fixtures", "person-contact-backfill.json"),
+    "utf8",
+  ),
+) as Fixture;
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261014120000_person_contact",
+  "migration.sql",
+);
+const BACKFILL_MARK =
+  "-- ===== #8435 contact backfill (idempotent; runs after the DDL above) =====";
+
+/** The backfill half of the single person_contact migration. */
+function backfillSql(): string {
+  const text = readFileSync(MIGRATION, "utf8");
+  const at = text.indexOf(BACKFILL_MARK);
+  if (at < 0) throw new Error("the backfill marker is missing from the migration");
+  return text.slice(at);
+}
+
+describe("the Person contact files (#8435 D1, D2)", () => {
+  it("the backfill is the second half of the single person_contact migration", () => {
+    const text = readFileSync(MIGRATION, "utf8");
+    const at = text.indexOf(BACKFILL_MARK);
+    expect(at).toBeGreaterThan(0);
+    expect(text.slice(0, at)).toMatch(/ALTER TABLE "people"/);
+    expect(text.slice(at)).not.toMatch(/ALTER TABLE/);
+  });
+
+  it("the Person model carries no deferred column (map, second phone, company id)", () => {
+    const schema = readFileSync(
+      join(__dirname, "..", "inbox", "schema.prisma"),
+      "utf8",
+    );
+    const block = /^model Person \{[\s\S]*?^\}/m.exec(schema)?.[0] ?? "";
+    expect(block).not.toBe("");
+    expect(block).not.toMatch(/latitude|longitude|placeId|place_id|companyId/);
+    expect(schema).not.toMatch(/^model Company /m);
+  });
+});
+
+describeDb("the contact columns (#8435 D1, AC-1, live DB)", () => {
+  let db: Client;
+  const WS_1 = "wksp_01920000-8435-7000-8000-0000000000c1";
+  const WS_2 = "wksp_01920000-8435-7000-8000-0000000000c2";
+  const WORKSPACES = [WS_1, WS_2];
+
+  async function cleanup(): Promise<void> {
+    await db.query(`DELETE FROM "callbacks" WHERE "workspace_id" = ANY($1)`, [
+      WORKSPACES,
+    ]);
+    await db.query(`DELETE FROM "subscribers" WHERE "workspace_id" = ANY($1)`, [
+      WORKSPACES,
+    ]);
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = ANY($1)`, [
+      WORKSPACES,
+    ]);
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  let counter = 0;
+  const email = () => `p8435-${(counter += 1)}@example.com`;
+
+  type Cols = Record<string, unknown>;
+
+  /** Insert one Person; `cols` maps column name → value on top of the required pair. */
+  const insertPerson = async (cols: Cols = {}, workspace = WS_1) => {
+    const all: Cols = {
+      workspace_id: workspace,
+      email: email(),
+      updated_at: new Date(),
+      ...cols,
+    };
+    const names = Object.keys(all);
+    return db.query<{ id: string }>(
+      `INSERT INTO "people" (${names.map((n) => `"${n}"`).join(", ")})
+       VALUES (${names.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING "id"`,
+      names.map((n) => all[n]),
+    );
+  };
+
+  const FULL = {
+    given_name: "Ada",
+    family_name: "Lovelace",
+    telephone: "+14155550123",
+    address_line1: "1 Analytical Way",
+    address_line2: "Suite 2",
+    address_city: "London",
+    address_region: "LDN",
+    address_postal_code: "N1 1AA",
+    address_country: "GB",
+    company_name: "Engines Ltd",
+    job_title: "Countess",
+    contact_confirmed_at: new Date("2026-10-12T00:00:00.000Z"),
+    contact_confirmed_by: "client",
+  };
+
+  it("a Person with all thirteen columns set inserts and reads back", async () => {
+    const { rows } = await insertPerson(FULL);
+    const read = await db.query(`SELECT * FROM "people" WHERE "id" = $1`, [
+      rows[0]!.id,
+    ]);
+    expect(read.rows[0]).toMatchObject({
+      given_name: "Ada",
+      family_name: "Lovelace",
+      telephone: "+14155550123",
+      address_line1: "1 Analytical Way",
+      address_line2: "Suite 2",
+      address_city: "London",
+      address_region: "LDN",
+      address_postal_code: "N1 1AA",
+      address_country: "GB",
+      company_name: "Engines Ltd",
+      job_title: "Countess",
+      contact_confirmed_by: "client",
+    });
+  });
+
+  it.each([
+    ["a stamp with no timestamp", { contact_confirmed_by: "client" }],
+    [
+      "an actor outside the two",
+      { contact_confirmed_at: new Date(), contact_confirmed_by: "agent" },
+    ],
+    ["a timestamp with no actor", { contact_confirmed_at: new Date() }],
+  ])("refuses %s (people_contact_confirmed)", async (_label, cols) => {
+    await expect(insertPerson(cols)).rejects.toMatchObject({
+      code: "23514",
+      constraint: "people_contact_confirmed",
+    });
+  });
+
+  it.each([
+    ["a national number", "4155550123"],
+    ["a leading +0", "+0123456789"],
+    ["spaces", "+1 415 555 0123"],
+    ["a letter inside", "+1415555012a"],
+  ])(
+    "refuses a telephone with %s (people_telephone_e164)",
+    async (_label, telephone) => {
+      await expect(insertPerson({ telephone })).rejects.toMatchObject({
+        code: "23514",
+        constraint: "people_telephone_e164",
+      });
+    },
+  );
+
+  it("accepts an E.164 telephone and NULL", async () => {
+    await expect(
+      insertPerson({ telephone: "+442071234567" }),
+    ).resolves.toHaveProperty("rowCount", 1);
+    await expect(insertPerson({ telephone: null })).resolves.toHaveProperty(
+      "rowCount",
+      1,
+    );
+  });
+
+  it.each([
+    ["lower case", "us"],
+    ["a digit", "U1"],
+  ])(
+    "refuses a country in %s (people_address_country_format)",
+    async (_label, address_country) => {
+      await expect(
+        insertPerson({
+          address_line1: "1 Main",
+          address_city: "Austin",
+          address_region: "TX",
+          address_postal_code: "78701",
+          address_country,
+        }),
+      ).rejects.toMatchObject({
+        code: "23514",
+        constraint: "people_address_country_format",
+      });
+    },
+  );
+
+  it("refuses a sixteen-digit telephone and a three-letter country by column width", async () => {
+    await expect(
+      insertPerson({ telephone: "+1234567890123456" }),
+    ).rejects.toMatchObject({ code: "22001" });
+    await expect(
+      insertPerson({
+        address_line1: "1 Main",
+        address_city: "Austin",
+        address_region: "TX",
+        address_postal_code: "78701",
+        address_country: "USA",
+      }),
+    ).rejects.toMatchObject({ code: "22001" });
+  });
+
+  it("refuses a half-written address (people_address_complete)", async () => {
+    await expect(insertPerson({ address_country: "US" })).rejects.toMatchObject(
+      {
+        code: "23514",
+        constraint: "people_address_complete",
+      },
+    );
+    await expect(
+      insertPerson({
+        address_line1: "1 Main",
+        address_city: "Austin",
+        address_region: "TX",
+        address_country: "US",
+      }),
+    ).rejects.toMatchObject({
+      code: "23514",
+      constraint: "people_address_complete",
+    });
+  });
+
+  it("accepts an address with all six NULL, and one with five set and address_line2 NULL", async () => {
+    await expect(insertPerson({})).resolves.toHaveProperty("rowCount", 1);
+    await expect(
+      insertPerson({
+        address_line1: "1 Main",
+        address_line2: null,
+        address_city: "Austin",
+        address_region: "TX",
+        address_postal_code: "78701",
+        address_country: "US",
+      }),
+    ).resolves.toHaveProperty("rowCount", 1);
+  });
+
+  const insertCallback = (workspace: string, personId: string | null) =>
+    db.query(
+      `INSERT INTO "callbacks" ("site_id", "workspace_id", "name", "phone", "payload", "person_id")
+       VALUES ($1, $1, 'Cal', '+14155550123', '{}', $2)`,
+      [workspace, personId],
+    );
+  const insertSubscriber = (workspace: string, personId: string | null) =>
+    db.query(
+      `INSERT INTO "subscribers" ("site_id", "workspace_id", "email", "source", "person_id")
+       VALUES ($1, $1, $2, 'p8435', $3)`,
+      [workspace, email(), personId],
+    );
+
+  it.each([
+    ["callbacks", "callbacks_person_fk", insertCallback],
+    ["subscribers", "subscribers_person_fk", insertSubscriber],
+  ] as const)(
+    "%s.person_id accepts a Person of the row's workspace and NULL, refuses another workspace's (%s)",
+    async (_table, constraint, insert) => {
+      const own = (await insertPerson({}, WS_1)).rows[0]!.id;
+      const foreign = (await insertPerson({}, WS_2)).rows[0]!.id;
+      await expect(insert(WS_1, own)).resolves.toHaveProperty("rowCount", 1);
+      await expect(insert(WS_1, null)).resolves.toHaveProperty("rowCount", 1);
+      await expect(insert(WS_1, foreign)).rejects.toMatchObject({
+        code: "23503",
+        constraint,
+      });
+    },
+  );
+
+  it.each([
+    ["callbacks", "callbacks_person_id_format", insertCallback],
+    ["subscribers", "subscribers_person_id_format", insertSubscriber],
+  ] as const)(
+    "%s.person_id refuses a lead_ id (%s)",
+    async (_table, constraint, insert) => {
+      await expect(
+        insert(WS_1, "lead_01920000-8435-7000-8000-0000000000c9"),
+      ).rejects.toMatchObject({
+        code: "23514",
+        constraint,
+      });
+    },
+  );
+
+  it("refuses to delete a Person a callback or a subscriber names (RESTRICT)", async () => {
+    const callbackPerson = (await insertPerson({}, WS_1)).rows[0]!.id;
+    await insertCallback(WS_1, callbackPerson);
+    await expect(
+      db.query(`DELETE FROM "people" WHERE "id" = $1`, [callbackPerson]),
+    ).rejects.toMatchObject({
+      code: "23503",
+      constraint: "callbacks_person_fk",
+    });
+    const subscriberPerson = (await insertPerson({}, WS_1)).rows[0]!.id;
+    await insertSubscriber(WS_1, subscriberPerson);
+    await expect(
+      db.query(`DELETE FROM "people" WHERE "id" = $1`, [subscriberPerson]),
+    ).rejects.toMatchObject({
+      code: "23503",
+      constraint: "subscribers_person_fk",
+    });
+  });
+});
+
+describeDb("the contact backfill (#8435 D2, AC-3, live DB)", () => {
+  let db: Client;
+  const WS = fixture.workspaces;
+  const WORKSPACES = Object.values(WS);
+  const subscriberIds = new Map<string, string>();
+  const callbackIds = new Map<string, string>();
+  const preIds = new Map<string, string>();
+
+  async function cleanup(): Promise<void> {
+    await db.query(`DELETE FROM "callbacks" WHERE "workspace_id" = ANY($1)`, [
+      WORKSPACES,
+    ]);
+    await db.query(`DELETE FROM "subscribers" WHERE "workspace_id" = ANY($1)`, [
+      WORKSPACES,
+    ]);
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = ANY($1)`, [
+      WORKSPACES,
+    ]);
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+
+    for (const p of fixture.input.people) {
+      const { rows } = await db.query<{ id: string }>(
+        `INSERT INTO "people" ("workspace_id", "email", "name", "user_id", "updated_at")
+         VALUES ($1, $2, $3, $4, now()) RETURNING "id"`,
+        [WS[p.workspace], p.email, p.name, p.user],
+      );
+      preIds.set(p.key, rows[0]!.id);
+    }
+    for (const s of fixture.input.subscribers) {
+      const { rows } = await db.query<{ id: string }>(
+        `INSERT INTO "subscribers" ("site_id", "workspace_id", "email", "source", "created_at")
+         VALUES ($1, $1, $2, 'p8435', $3) RETURNING "id"`,
+        [WS[s.workspace], s.email, s.createdAt],
+      );
+      subscriberIds.set(s.key, rows[0]!.id);
+    }
+    for (const c of fixture.input.callbacks) {
+      const { rows } = await db.query<{ id: string }>(
+        `INSERT INTO "callbacks" ("site_id", "workspace_id", "name", "phone", "payload", "buyer_email", "created_at")
+         VALUES ($1, $1, $2, $3, $4, $5, $6) RETURNING "id"`,
+        [
+          WS[c.workspace],
+          c.name,
+          c.phone,
+          JSON.stringify(c.payload),
+          c.buyerEmail,
+          c.createdAt,
+        ],
+      );
+      callbackIds.set(c.key, rows[0]!.id);
+    }
+
+    await db.query(backfillSql());
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  type PersonRow = {
+    id: string;
+    workspace_id: string;
+    email: string;
+    name: string | null;
+    telephone: string | null;
+  };
+
+  const readPeople = async () =>
+    (
+      await db.query<PersonRow>(
+        `SELECT "id", "workspace_id", "email", "name", "telephone"
+         FROM "people" WHERE "workspace_id" = ANY($1) ORDER BY "workspace_id", "email"`,
+        [WORKSPACES],
+      )
+    ).rows;
+
+  const snapshot = async () => ({
+    people: (
+      await db.query(
+        `SELECT * FROM "people" WHERE "workspace_id" = ANY($1) ORDER BY "id"`,
+        [WORKSPACES],
+      )
+    ).rows,
+    subscribers: (
+      await db.query(
+        `SELECT "id", "person_id" FROM "subscribers" WHERE "workspace_id" = ANY($1) ORDER BY "id"`,
+        [WORKSPACES],
+      )
+    ).rows,
+    callbacks: (
+      await db.query(
+        `SELECT "id", "person_id" FROM "callbacks" WHERE "workspace_id" = ANY($1) ORDER BY "id"`,
+        [WORKSPACES],
+      )
+    ).rows,
+  });
+
+  const wsKey = (id: string) => Object.keys(WS).find((k) => WS[k] === id);
+
+  it("makes exactly the expected Persons (email, name, telephone)", async () => {
+    const people = await readPeople();
+    expect(
+      people.map((p) => ({
+        workspace: wsKey(p.workspace_id),
+        email: p.email,
+        name: p.name,
+        telephone: p.telephone,
+      })),
+    ).toEqual(fixture.expected.people);
+  });
+
+  it("keeps the pre-existing Persons' ids, names and users", async () => {
+    const people = await readPeople();
+    for (const [key, id] of preIds) {
+      const pre = fixture.input.people.find((p) => p.key === key)!;
+      const row = people.find((p) => p.id === id);
+      expect({ key, email: row?.email, name: row?.name }).toEqual({
+        key,
+        email: pre.email,
+        name: pre.name,
+      });
+    }
+  });
+
+  it("stamps every subscriber and callback with a storable email with its workspace's Person; the rest stay NULL", async () => {
+    const people = await readPeople();
+    const personOf = (stamp: { workspace: string; email: string } | null) =>
+      stamp === null
+        ? null
+        : (people.find(
+            (p) =>
+              p.workspace_id === WS[stamp.workspace] && p.email === stamp.email,
+          )?.id ?? "MISSING");
+    for (const [key, stamp] of Object.entries(fixture.expected.stamps)) {
+      const table = key.startsWith("S") ? "subscribers" : "callbacks";
+      const id = (key.startsWith("S") ? subscriberIds : callbackIds).get(key);
+      const { rows } = await db.query<{ person_id: string | null }>(
+        `SELECT "person_id" FROM "${table}" WHERE "id" = $1`,
+        [id],
+      );
+      expect({ key, personId: rows[0]!.person_id }).toEqual({
+        key,
+        personId: personOf(stamp),
+      });
+    }
+  });
+
+  it("makes no Person for the buyer_email of a callback whose payload.email is storable", async () => {
+    const people = await readPeople();
+    expect(people.find((p) => p.email === "other@example.com")).toBeUndefined();
+  });
+
+  it("fills a telephone only from an E.164 callback phone on an uncurated Person", async () => {
+    const people = await readPeople();
+    const tel = (email: string) =>
+      people.find((p) => p.email === email && p.workspace_id === WS.A)
+        ?.telephone;
+    expect(tel("both@example.com")).toBe("+14155550123");
+    expect(tel("buyer@example.com")).toBeNull();
+    expect(tel("linked@example.com")).toBeNull();
+  });
+
+  it("a second run of the post-cutover script changes no row, and stamps a subscriber written after the first", async () => {
+    const before = await snapshot();
+    await db.query(backfillSql());
+    expect(await snapshot()).toEqual(before);
+
+    const { rows } = await db.query<{ id: string }>(
+      `INSERT INTO "subscribers" ("site_id", "workspace_id", "email", "source")
+       VALUES ($1, $1, 'Both@Example.com', 'p8435-late') RETURNING "id"`,
+      [WS.A],
+    );
+    await db.query(backfillSql());
+    const stamped = await db.query<{ person_id: string | null }>(
+      `SELECT "person_id" FROM "subscribers" WHERE "id" = $1`,
+      [rows[0]!.id],
+    );
+    const people = await readPeople();
+    expect(stamped.rows[0]!.person_id).toBe(
+      people.find((p) => p.email === "both@example.com")!.id,
+    );
+  });
+});