create-ailk 0.23.0 → 0.25.1

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

@@ -1,242 +0,0 @@
-/**
- * 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

@@ -1,295 +0,0 @@
-/**
- * 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/);
-  });
-});