create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/services/magnet-completion.ts

@@ -0,0 +1,242 @@
+/**
+ * What happens after someone submits a magnet (#8757, spec
+ * docs/specs/8757-a-per-magnet-completion-setting-spec.md D6).
+ *
+ * `POST /v1/leads/submit` calls `magnetCompletionFor` after a `flow:<slug>`
+ * lead is written to the database. It reads the LIVE magnet at that slug
+ * (`lib/flow-completion-store.ts`) and answers the 201's `next`:
+ *
+ *   - `lead`, a missing or a draft magnet → `null` (the 201 is unchanged);
+ *   - `invite` → `{ completion: "invite" }`, only where the caller has an
+ *     account to sign in to (`accountTargetFor`); else `null` (NFR4);
+ *   - `checkout` → `{ completion: "checkout", checkoutOffering }`, re-checked
+ *     at submit time (SEC-8757-E): the `commerce` claim must read `claimed`
+ *     and the offering must still be listed. Anything else is `null`.
+ *
+ * `sendInviteConfirmation` is the invite email: one `sendDeliverableEmail` to
+ * the lead's address whose one link (`downloadLink`, labelled by `cta`) starts
+ * sign-in with that address prefilled. It never signs anyone in (NFR2). Two
+ * caps run first, counted in the database (SEC-8757-A, SEC-8757-B): one email
+ * per recipient per magnet per day — which also stops the second email of an
+ * unkeyed double submit — and fifty per magnet per hour. A capped send still
+ * leaves the page's link in place. Every outcome is one
+ * `{ event: "magnet-invite", outcome }` line that never names the address.
+ *
+ * Where the link points (`accountTargetFor`): a keyless caller gets
+ * `FRONTEND_URL`'s origin with the site sign-in path, and only on a build that
+ * has an account area (`workspace` or `multi-tenant`); a spoke gets the origin
+ * of its enabled sign-in client's registered callback with the hub sign-in
+ * path, `https:` unless `NODE_ENV` is `development` (SEC-8757-I). The origin is never
+ * taken from the request.
+ *
+ * Base tree (SEC-8757-D, NFR6): no `oss: false` marker and no `MODULE_SLICES`
+ * entry, and it imports none — the never-gate lead route imports it. So the
+ * sender is resolved here (`inviteSenderAddress`, the same rule as
+ * `deliverable-fulfillment.ts`'s `deliverableSenderAddress`, which
+ * `module-architecture.ts` holds out of a slice only until #5364), and
+ * `@working-theory/email` — the templates the lead route otherwise never
+ * loads — is imported on the first send, not with the route.
+ */
+import { logger } from "@working-theory/observability";
+import {
+  accountInvitePath,
+  completionEmailSchema,
+  INVITE_EMAIL_DEFAULTS,
+  INVITE_EMAILS_PER_RECIPIENT_PER_DAY,
+  INVITE_EMAILS_PER_SITE_PER_HOUR,
+  type AccountInviteProvider,
+  type CompletionEmailConfig,
+  type LeadSubmitNext,
+} from "@working-theory/validation";
+
+import { isModuleEnabled } from "../config/modules.js";
+import { inviteSendCounts, liveCompletionBySlug } from "../lib/flow-completion-store.js";
+import { findClientByClientId } from "../lib/hub-sign-in-store.js";
+import { resolveCommerceClaim } from "../lib/require-commerce-claim.js";
+
+import { listPlanOfferings } from "./plan-offerings.js";
+import type { CallerSite } from "./public-site-resolver.js";
+
+/**
+ * The invite email's sender: `AILK_DELIVERABLE_EMAIL_FROM`, else
+ * `AILK_LEAD_NOTIFICATION_FROM` — every completion email's sender. `||`, not
+ * `??`: an env var set to "" names no sender.
+ */
+export function inviteSenderAddress(): string | undefined {
+  return (
+    process.env.AILK_DELIVERABLE_EMAIL_FROM ||
+    process.env.AILK_LEAD_NOTIFICATION_FROM ||
+    undefined
+  );
+}
+
+/** Where an account link starts sign-in: the site's origin and its sign-in path. */
+export interface AccountTarget {
+  origin: string;
+  provider: AccountInviteProvider;
+}
+
+/** The origin of `raw` when it is `https:` (or `http:` in development), else `null`. */
+function linkOrigin(raw: string | undefined): string | null {
+  if (!raw) return null;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol === "https:") return url.origin;
+  if (url.protocol === "http:" && process.env.NODE_ENV === "development") return url.origin;
+  return null;
+}
+
+/** Where the caller's account link points, or `null` when it has nowhere to sign in. */
+export async function accountTargetFor(
+  caller: Exclude<CallerSite, { kind: "refused" }>,
+): Promise<AccountTarget | null> {
+  if (caller.kind === "spoke") {
+    const client = await findClientByClientId(caller.spokeId);
+    if (!client?.enabled) return null;
+    const origin = linkOrigin(client.redirectUris[0]);
+    return origin === null ? null : { origin, provider: "hub" };
+  }
+  // A build with no account area has no `/account` to land on.
+  if (!isModuleEnabled("workspace") && !isModuleEnabled("multi-tenant")) return null;
+  const origin = linkOrigin(process.env.FRONTEND_URL);
+  return origin === null ? null : { origin, provider: "site" };
+}
+
+/** A submit's completion: the 201's `next`, plus what the invite email needs. */
+export interface MagnetCompletion {
+  next: LeadSubmitNext;
+  title: string;
+  config: unknown;
+  target: AccountTarget | null;
+}
+
+/**
+ * How long the anonymous submit waits on `magnetCompletionFor` before it
+ * answers without `next`: the lead is already written, and a slow licence or
+ * content read must not turn it into a client-side timeout and a resubmit.
+ */
+export const MAGNET_COMPLETION_BUDGET_MS = 1500;
+
+/** `magnetCompletionFor`, or `null` once `MAGNET_COMPLETION_BUDGET_MS` has passed. */
+export async function magnetCompletionWithinBudget(
+  ...args: Parameters<typeof magnetCompletionFor>
+): Promise<MagnetCompletion | null> {
+  let timer: NodeJS.Timeout | undefined;
+  const budget = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), MAGNET_COMPLETION_BUDGET_MS);
+  });
+  try {
+    return await Promise.race([magnetCompletionFor(...args), budget]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The completion of a `flow:<slug>` lead just written to `workspaceId`, or `null` for `lead`. */
+export async function magnetCompletionFor(
+  workspaceId: string,
+  slug: string,
+  resolveTarget: () => Promise<AccountTarget | null>,
+): Promise<MagnetCompletion | null> {
+  const magnet = await liveCompletionBySlug(workspaceId, slug);
+  if (magnet === null) return null;
+  const { title, config } = magnet;
+  if (magnet.completion === "invite") {
+    const target = await resolveTarget();
+    return target === null ? null : { next: { completion: "invite" }, title, config, target };
+  }
+  if (magnet.completion === "checkout") {
+    // A claim or offerings read that fails is never a pass: it degrades to `lead`.
+    if ((await resolveCommerceClaim()) !== "claimed") return null;
+    const offerings = await listPlanOfferings(workspaceId);
+    if (!Array.isArray(offerings)) return null;
+    const offering = magnet.checkoutOffering;
+    if (!offerings.some((item) => item.key === offering)) return null;
+    return { next: { completion: "checkout", checkoutOffering: offering }, title, config, target: null };
+  }
+  return null;
+}
+
+export type InviteOutcome =
+  | "sent"
+  | "send_failed"
+  | "capped_recipient"
+  | "capped_site"
+  | "sender_unconfigured"
+  | "no_link";
+
+export interface InviteConfirmationInput {
+  workspaceId: string;
+  slug: string;
+  email: string;
+  locale: string | undefined;
+  completion: MagnetCompletion;
+  now: Date;
+}
+
+const fill = (template: string, title: string) => template.replaceAll("{title}", title);
+
+/**
+ * `copy[locale] ?? copy[defaultLocale]`, the completion email's own
+ * resolution. Own keys only: `locale` comes from the anonymous payload, and
+ * `"constructor"` must not read an inherited member.
+ */
+function resolveCopy(copy: Record<string, string>, locale: string, defaultLocale: string) {
+  const own = (key: string) => (Object.hasOwn(copy, key) ? copy[key] : undefined);
+  return own(locale) ?? own(defaultLocale) ?? Object.values(copy)[0] ?? "";
+}
+
+function declaredCopy(config: unknown): { copy: CompletionEmailConfig; defaultLocale: string } | null {
+  if (typeof config !== "object" || config === null) return null;
+  const record = config as { completionEmail?: unknown; defaultLocale?: unknown };
+  const parsed = completionEmailSchema.safeParse(record.completionEmail);
+  if (!parsed.success) return null;
+  const defaultLocale = typeof record.defaultLocale === "string" ? record.defaultLocale : "en";
+  return { copy: parsed.data, defaultLocale };
+}
+
+/**
+ * The invite email (D6). Never throws and never names the address in a log;
+ * the caller fires it with `void` after a first, unreplayed write.
+ */
+export async function sendInviteConfirmation(input: InviteConfirmationInput): Promise<InviteOutcome> {
+  const outcome = await send().catch(() => "send_failed" as const);
+  logger.info({ event: "magnet-invite", outcome }, "[magnet-completion] invite email");
+  return outcome;
+
+  async function send(): Promise<InviteOutcome> {
+    const { workspaceId, slug, email, locale, completion, now } = input;
+    if (completion.target === null) return "no_link";
+    const counts = await inviteSendCounts(workspaceId, slug, email, now);
+    if (counts.recipientDay > INVITE_EMAILS_PER_RECIPIENT_PER_DAY) return "capped_recipient";
+    if (counts.siteHour > INVITE_EMAILS_PER_SITE_PER_HOUR) return "capped_site";
+    const fromAddress = inviteSenderAddress();
+    if (!fromAddress) return "sender_unconfigured";
+
+    let downloadLink: string;
+    try {
+      downloadLink = completion.target.origin + accountInvitePath(completion.target.provider, email);
+    } catch {
+      return "no_link";
+    }
+    const declared = declaredCopy(completion.config);
+    const lang = locale ?? declared?.defaultLocale ?? "en";
+    const subject = declared
+      ? resolveCopy(declared.copy.subject, lang, declared.defaultLocale)
+      : fill(INVITE_EMAIL_DEFAULTS.subject, completion.title);
+    const body = declared
+      ? resolveCopy(declared.copy.body, lang, declared.defaultLocale)
+      : fill(INVITE_EMAIL_DEFAULTS.body, completion.title);
+    const cta = declared?.copy.cta
+      ? resolveCopy(declared.copy.cta, lang, declared.defaultLocale)
+      : INVITE_EMAIL_DEFAULTS.cta;
+
+    const { sendDeliverableEmail } = await import("@working-theory/email");
+    const result = await sendDeliverableEmail({ to: email, fromAddress, subject, body, cta, downloadLink });
+    return result.ok ? "sent" : "send_failed";
+  }
+}

package/templates/apps/api/src/services/offerings/__tests__/catalog.test.ts

@@ -0,0 +1,295 @@
+/**
+ * services/offerings/catalog.ts — the one normalizer (#8876 spec D5, AC-5):
+ * text normalization (T1), the product marker (G6), sellable Prices (G3) and
+ * one plan per Product (G4), in D5's order, one bad Product never failing the
+ * catalog.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { offeringsSnapshotProductSchema } from "@working-theory/validation";
+
+import {
+  isOfferingsProduct,
+  normalizeCatalog,
+  type CatalogPrice,
+  type CatalogProduct,
+} from "../catalog.js";
+import {
+  EXPECTED_FIXTURE_HELD,
+  EXPECTED_FIXTURE_OFFERINGS,
+  OFFERINGS_FIXTURE_CATALOG,
+} from "./fixtures.js";
+
+function product(id: string, patch: Record<string, unknown> = {}): CatalogProduct {
+  return {
+    id,
+    active: true,
+    name: "Growth",
+    description: null,
+    marketing_features: [],
+    unit_label: null,
+    metadata: { ailk_group: "plan" },
+    ...patch,
+  };
+}
+
+function price(id: string, productId: string, patch: Record<string, unknown> = {}): CatalogPrice {
+  return {
+    id,
+    active: true,
+    product: productId,
+    lookup_key: "growth_monthly",
+    type: "recurring",
+    recurring: { interval: "month", interval_count: 1, usage_type: "licensed" },
+    billing_scheme: "per_unit",
+    unit_amount: 4900,
+    currency: "usd",
+    ...patch,
+  };
+}
+
+/** Normalize one Product with its Prices. */
+function one(p: CatalogProduct, prices: CatalogPrice[]) {
+  return normalizeCatalog({ products: [p], prices });
+}
+
+describe("normalizeCatalog (#8876 D5, AC-5)", () => {
+  it("answers the fixture's offerings and held list exactly, in D5's order", () => {
+    expect(normalizeCatalog(OFFERINGS_FIXTURE_CATALOG)).toEqual({
+      offerings: EXPECTED_FIXTURE_OFFERINGS,
+      held: EXPECTED_FIXTURE_HELD,
+    });
+  });
+
+  it("is pure: the same input answers the same output and is not mutated", () => {
+    const input = structuredClone(OFFERINGS_FIXTURE_CATALOG);
+    expect(normalizeCatalog(input)).toEqual(normalizeCatalog(OFFERINGS_FIXTURE_CATALOG));
+    expect(input).toEqual(OFFERINGS_FIXTURE_CATALOG);
+  });
+
+  describe("text (T1)", () => {
+    it("strips bidi overrides, zero-width characters and a CR from a name", () => {
+      const { offerings } = one(product("prod_a", { name: "Gro‮wth​\r plan" }), [price("price_a", "prod_a")]);
+      expect(offerings[0]!.name).toBe("Growth plan");
+    });
+
+    it("answers the NFC form of a decomposed character", () => {
+      const { offerings } = one(product("prod_a", { name: "Café" }), [price("price_a", "prod_a")]);
+      expect(offerings[0]!.name).toBe("Café");
+    });
+
+    it("keeps a newline in the description only", () => {
+      const { offerings } = one(
+        product("prod_a", {
+          name: "Two\nlines",
+          description: "  First\nsecond
third  ",
+          marketing_features: [{ name: "a\nb" }],
+        }),
+        [price("price_a", "prod_a")],
+      );
+      expect(offerings[0]!.name).toBe("Twolines");
+      expect(offerings[0]!.description).toBe("First\nsecondthird");
+      expect(offerings[0]!.marketingFeatures).toEqual(["ab"]);
+    });
+
+    it("cuts a 2001-code-point description to 2000", () => {
+      const { offerings } = one(product("prod_a", { description: "x".repeat(2001) }), [price("price_a", "prod_a")]);
+      expect([...offerings[0]!.description!]).toHaveLength(2000);
+    });
+
+    it("keeps a name of 200 astral-plane emoji whole, and it parses", () => {
+      const name = "😀".repeat(200);
+      const { offerings } = one(product("prod_a", { name }), [price("price_a", "prod_a")]);
+      expect(offerings[0]!.name).toBe(name);
+      expect(offeringsSnapshotProductSchema.safeParse(offerings[0]).success).toBe(true);
+    });
+
+    it("reads a non-string as null and an empty text as null", () => {
+      const { offerings } = one(
+        product("prod_a", { description: 42, unit_label: "   ", metadata: { ailk_group: "plan", ailk_note: {} } }),
+        [price("price_a", "prod_a")],
+      );
+      expect(offerings[0]).toMatchObject({ description: null, unitLabel: null, note: null });
+    });
+
+    it("never reads images, url, nickname, statement_descriptor or other metadata", () => {
+      const { offerings } = one(
+        product("prod_a", {
+          images: ["https://evil.example/x.png"],
+          url: "https://evil.example",
+          metadata: { ailk_group: "plan", other: "secret-metadata" },
+        } as Record<string, unknown>),
+        [price("price_a", "prod_a", { nickname: "Nick", statement_descriptor: "STMT" } as Record<string, unknown>)],
+      );
+      const text = JSON.stringify(offerings);
+      for (const leaked of ["evil.example", "secret-metadata", "Nick", "STMT", "images", "url", "nickname"]) {
+        expect(text).not.toContain(leaked);
+      }
+    });
+  });
+
+  describe("the marker (G6)", () => {
+    it.each([
+      ["no ailk_group", {}],
+      ["ailk_group Plan", { ailk_group: "Plan" }],
+      ["ailk_group other", { ailk_group: "other" }],
+    ])("holds %s group_invalid", (_label, metadata) => {
+      expect(one(product("prod_a", { metadata }), [price("price_a", "prod_a")])).toEqual({
+        offerings: [],
+        held: [{ productId: "prod_a", name: "Growth", reason: "group_invalid" }],
+      });
+    });
+
+    it("holds an empty name name_missing", () => {
+      expect(one(product("prod_a", { name: "​ " }), [price("price_a", "prod_a")]).held).toEqual([
+        { productId: "prod_a", name: "", reason: "name_missing" },
+      ]);
+    });
+
+    it("isOfferingsProduct is true for any non-empty ailk_group, Plan included", () => {
+      expect(isOfferingsProduct(product("prod_a", { metadata: { ailk_group: "Plan" } }))).toBe(true);
+      expect(isOfferingsProduct(product("prod_a", { metadata: { ailk_group: "addon" } }))).toBe(true);
+      expect(isOfferingsProduct(product("prod_a", { metadata: { ailk_group: "" } }))).toBe(false);
+      expect(isOfferingsProduct(product("prod_a", { metadata: {} }))).toBe(false);
+      expect(isOfferingsProduct(product("prod_a", { metadata: null }))).toBe(false);
+    });
+
+    it("keeps ailk_order of 1–4 digits and sorts anything else last", () => {
+      const products = [
+        product("prod_a", { name: "A", metadata: { ailk_group: "plan", ailk_order: "12345" } }),
+        product("prod_b", { name: "B", metadata: { ailk_group: "plan", ailk_order: "2" } }),
+        product("prod_c", { name: "C", metadata: { ailk_group: "plan", ailk_order: 1 } }),
+      ];
+      const prices = [
+        price("price_a", "prod_a", { lookup_key: "a_monthly" }),
+        price("price_b", "prod_b", { lookup_key: "b_monthly" }),
+        price("price_c", "prod_c", { lookup_key: "c_monthly" }),
+      ];
+      const { offerings } = normalizeCatalog({ products, prices });
+      expect(offerings.map((o) => [o.productId, o.ailkOrder])).toEqual([
+        ["prod_b", 2],
+        ["prod_a", null],
+        ["prod_c", null],
+      ]);
+    });
+  });
+
+  describe("sellable Prices (G3) and one plan per Product (G4)", () => {
+    it.each([
+      ["one sellable and one growth_quarterly Price", [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { lookup_key: "growth_quarterly", recurring: { interval: "month", interval_count: 3 } }),
+      ]],
+      ["a metered Price", [price("price_a", "prod_a", { recurring: { interval: "month", interval_count: 1, usage_type: "metered" } })]],
+      ["a tiered Price", [price("price_a", "prod_a", { billing_scheme: "tiered", unit_amount: null })]],
+      ["a period that disagrees with the Price", [price("price_a", "prod_a", { recurring: { interval: "year", interval_count: 1 } })]],
+      ["no active Price", [price("price_a", "prod_a", { active: false })]],
+      ["no Price at all", []],
+      ["a null unit_amount", [price("price_a", "prod_a", { unit_amount: null })]],
+      ["an uppercase currency", [price("price_a", "prod_a", { currency: "USD" })]],
+      ["two Prices of one period", [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { lookup_key: "growth_monthly" }),
+      ]],
+      ["two plans on one Product", [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { lookup_key: "basic_yearly", recurring: { interval: "year", interval_count: 1 } }),
+      ]],
+    ])("holds a Product with %s needs_lookup_key", (_label, prices) => {
+      expect(one(product("prod_a"), prices as CatalogPrice[]).held).toEqual([
+        { productId: "prod_a", name: "Growth", reason: "needs_lookup_key" },
+      ]);
+    });
+
+    it("ignores an inactive Price beside a sellable one", () => {
+      const { offerings } = one(product("prod_a"), [
+        price("price_a", "prod_a"),
+        price("price_b", "prod_a", { active: false, lookup_key: "growth_quarterly" }),
+      ]);
+      expect(offerings[0]!.prices.map((p) => p.priceId)).toEqual(["price_a"]);
+    });
+
+    it("holds both Products carrying one plan plan_conflict", () => {
+      const { offerings, held } = normalizeCatalog({
+        products: [product("prod_a"), product("prod_b", { name: "Growth two" })],
+        prices: [
+          price("price_a", "prod_a"),
+          price("price_b", "prod_b", { lookup_key: "growth_yearly", recurring: { interval: "year", interval_count: 1 } }),
+        ],
+      });
+      expect(offerings).toEqual([]);
+      expect(held).toEqual([
+        { productId: "prod_a", name: "Growth", reason: "plan_conflict" },
+        { productId: "prod_b", name: "Growth two", reason: "plan_conflict" },
+      ]);
+    });
+
+    it("reads an expanded product object on a Price", () => {
+      const { offerings } = one(product("prod_a"), [price("price_a", "prod_a", { product: { id: "prod_a" } })]);
+      expect(offerings).toHaveLength(1);
+    });
+
+    it("leaves out an inactive Product and an id that is not a Stripe id", () => {
+      expect(
+        normalizeCatalog({
+          products: [product("prod_a", { active: false }), product("prod a"), { ...product("prod_x"), id: 42 }],
+          prices: [price("price_a", "prod_a")],
+        }),
+      ).toEqual({ offerings: [], held: [] });
+    });
+
+    it("holds a Product whose offering fails its parse invalid, and every other still normalizes", () => {
+      // Nothing the normalizer keeps fails the schema today, so the per-Product
+      // parse is driven by a schema that refuses one Product.
+      const original = offeringsSnapshotProductSchema.safeParse.bind(offeringsSnapshotProductSchema);
+      const spy = jest
+        .spyOn(offeringsSnapshotProductSchema, "safeParse")
+        .mockImplementation((value: unknown) =>
+          (value as { productId?: string }).productId === "prod_a"
+            ? ({ success: false } as never)
+            : original(value),
+        );
+      try {
+        const { offerings, held } = normalizeCatalog({
+          products: [product("prod_a"), product("prod_b", { name: "Basic" })],
+          prices: [price("price_a", "prod_a"), price("price_b", "prod_b", { lookup_key: "basic_monthly" })],
+        });
+        expect(held).toEqual([{ productId: "prod_a", name: "Growth", reason: "invalid" }]);
+        expect(offerings.map((o) => o.productId)).toEqual(["prod_b"]);
+      } finally {
+        spy.mockRestore();
+      }
+    });
+
+    it("counts a Product id the source answers twice once", () => {
+      const { offerings, held } = normalizeCatalog({
+        products: [product("prod_a"), product("prod_a", { name: "Growth again" })],
+        prices: [price("price_a", "prod_a")],
+      });
+      expect(offerings.map((o) => [o.productId, o.name])).toEqual([["prod_a", "Growth"]]);
+      expect(held).toEqual([]);
+    });
+
+    it("counts a Price id the source answers twice once", () => {
+      const { offerings } = one(product("prod_a"), [price("price_a", "prod_a"), price("price_a", "prod_a")]);
+      expect(offerings[0]!.prices.map((p) => p.priceId)).toEqual(["price_a"]);
+    });
+
+    it("reads no more than the catalog caps", () => {
+      const products = Array.from({ length: 1001 }, (_, i) =>
+        product(`prod_${i}`, { name: `P${i}`, metadata: {} }),
+      );
+      const { held } = normalizeCatalog({ products, prices: [] });
+      expect(held).toHaveLength(1000);
+      expect(held.some((h) => h.productId === "prod_1000")).toBe(false);
+    });
+  });
+
+  it("splits a lookup key only through parseLookupKey (AC-9)", () => {
+    const source = readFileSync(join(__dirname, "..", "catalog.ts"), "utf8");
+    expect(source).toContain("parseLookupKey(");
+    expect(source).not.toMatch(/split\(\s*["']_["']\s*\)/);
+    expect(source).not.toMatch(/monthly\|yearly/);
+  });
+});