create-ailk 0.22.0 → 0.23.0

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

@@ -0,0 +1,231 @@
+/**
+ * services/offerings/source.ts — the paged Stripe catalog source (#8922, spec
+ * docs/specs/8922-the-may-sell-product-list-spec.md D2, AC-6): built lazily,
+ * paged through both lists concurrently, bounded by calls and by time, and
+ * never reading a disconnected or unusable connection as an empty catalog.
+ *
+ * `connection.js`'s `stripeClientForOrganization` is mocked to answer each
+ * case's client, so no key is decrypted and no Stripe call is made.
+ */
+const mockStripeClientForOrganization = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- connection.ts's per-key client is the Stripe HTTP boundary (#8907 D12); each case answers its own client
+jest.mock("../connection.js", () => ({
+  stripeClientForOrganization: (...args: unknown[]) => mockStripeClientForOrganization(...args),
+}));
+
+const mockWarn = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: { warn: (...args: unknown[]) => mockWarn(...args), error: jest.fn(), info: jest.fn(), debug: jest.fn() },
+}));
+
+import { OFFERINGS_CATALOG_PRICES_MAX, OFFERINGS_CATALOG_PRODUCTS_MAX } from "../catalog.js";
+import {
+  OFFERINGS_CATALOG_READ_TIMEOUT_MS,
+  OfferingsCatalogUnavailableError,
+  stripeCatalogSourceFor,
+} from "../source.js";
+
+const ORG = "org_01920000-8922-7000-8000-0000000000a1";
+
+type Params = { active?: boolean; limit?: number; starting_after?: string };
+type Page = { data: Array<{ id: string }>; has_more: boolean };
+
+/** A list call answering `pages[i]` on its i-th call, then an empty last page. */
+function pagedList(prefix: string, sizes: number[]) {
+  let call = 0;
+  let next = 0;
+  return jest.fn(async (_params: Params): Promise<Page> => {
+    const size = sizes[call] ?? 0;
+    const hasMore = call < sizes.length - 1;
+    call += 1;
+    const data = Array.from({ length: size }, () => ({ id: `${prefix}_${next++}` }));
+    return { data, has_more: hasMore };
+  });
+}
+
+/** A list call that answers `size` fresh items with `has_more: true`, forever. */
+function endlessList(prefix: string, size: number) {
+  let next = 0;
+  return jest.fn(async (_params: Params): Promise<Page> => ({
+    data: Array.from({ length: size }, () => ({ id: `${prefix}_${next++}` })),
+    has_more: true,
+  }));
+}
+
+function clientOf(products: jest.Mock, prices: jest.Mock) {
+  return { products: { list: products }, prices: { list: prices } };
+}
+
+function connect(client: unknown): void {
+  mockStripeClientForOrganization.mockResolvedValue({ kind: "ok", client, mode: "test" });
+}
+
+beforeEach(() => {
+  jest.useRealTimers();
+  mockStripeClientForOrganization.mockReset();
+  mockWarn.mockReset();
+});
+
+describe("stripeCatalogSourceFor (#8922 D2, AC-6)", () => {
+  it("does nothing until listActiveCatalog is called", () => {
+    const source = stripeCatalogSourceFor(ORG);
+    expect(typeof source.listActiveCatalog).toBe("function");
+    expect(mockStripeClientForOrganization).not.toHaveBeenCalled();
+  });
+
+  it("pages each list with starting_after until has_more is false, concurrently", async () => {
+    const products = pagedList("prod", [100, 100, 50]);
+    const prices = pagedList("price", [100, 20]);
+    let productsFirstPageResolved = false;
+    const productsList = jest.fn(async (params: Params) => {
+      const page = await products(params);
+      productsFirstPageResolved = true;
+      return page;
+    });
+    let pricesStartedBeforeProductsResolved = false;
+    const pricesList = jest.fn(async (params: Params) => {
+      if (pricesList.mock.calls.length === 1) pricesStartedBeforeProductsResolved = !productsFirstPageResolved;
+      return prices(params);
+    });
+    connect(clientOf(productsList, pricesList));
+
+    const catalog = await stripeCatalogSourceFor(ORG).listActiveCatalog();
+
+    expect(mockStripeClientForOrganization).toHaveBeenCalledWith(ORG);
+    expect(productsList.mock.calls.map(([p]) => p)).toEqual([
+      { active: true, limit: 100 },
+      { active: true, limit: 100, starting_after: "prod_99" },
+      { active: true, limit: 100, starting_after: "prod_199" },
+    ]);
+    expect(catalog.products).toHaveLength(250);
+    expect(catalog.products.map((p) => p.id)).toEqual(Array.from({ length: 250 }, (_, i) => `prod_${i}`));
+    expect(pricesList.mock.calls.map(([p]) => p)).toEqual([
+      { active: true, limit: 100 },
+      { active: true, limit: 100, starting_after: "price_99" },
+    ]);
+    expect(catalog.prices).toHaveLength(120);
+    expect(pricesStartedBeforeProductsResolved).toBe(true);
+    expect(mockWarn).not.toHaveBeenCalled();
+  });
+
+  it("stops at the caps: 10 product calls and 30 price calls of full pages", async () => {
+    const products = endlessList("prod", 100);
+    const prices = endlessList("price", 100);
+    connect(clientOf(products, prices));
+    const catalog = await stripeCatalogSourceFor(ORG).listActiveCatalog();
+    expect(products).toHaveBeenCalledTimes(OFFERINGS_CATALOG_PRODUCTS_MAX / 100);
+    expect(prices).toHaveBeenCalledTimes(OFFERINGS_CATALOG_PRICES_MAX / 100);
+    expect(catalog.products).toHaveLength(1000);
+    expect(catalog.prices).toHaveLength(3000);
+    // Cut off with more to read: logged once, with the Organization alone (SEC-8922-7).
+    expect(mockWarn).toHaveBeenCalledTimes(1);
+    expect(mockWarn).toHaveBeenCalledWith({ organizationId: ORG, reason: "catalog_truncated" }, expect.any(String));
+  });
+
+  it("bounds by calls, not items: pages of one item still stop at 10 and 30 calls", async () => {
+    const products = endlessList("prod", 1);
+    const prices = endlessList("price", 1);
+    connect(clientOf(products, prices));
+    const catalog = await stripeCatalogSourceFor(ORG).listActiveCatalog();
+    expect(products).toHaveBeenCalledTimes(10);
+    expect(prices).toHaveBeenCalledTimes(30);
+    expect(catalog.products).toHaveLength(10);
+    expect(catalog.prices).toHaveLength(30);
+  });
+
+  it("ends a loop on an empty page that still says has_more", async () => {
+    const products = jest.fn(async (): Promise<Page> => ({ data: [], has_more: true }));
+    const prices = pagedList("price", [3]);
+    connect(clientOf(products, prices));
+    const catalog = await stripeCatalogSourceFor(ORG).listActiveCatalog();
+    expect(products).toHaveBeenCalledTimes(1);
+    expect(catalog.products).toEqual([]);
+  });
+
+  it("ends a loop on a page whose last id repeats the starting_after it was asked with", async () => {
+    const products = jest.fn(async (params: Params): Promise<Page> => ({
+      data: [{ id: params.starting_after ?? "prod_a" }],
+      has_more: true,
+    }));
+    const prices = pagedList("price", [1]);
+    connect(clientOf(products, prices));
+    const catalog = await stripeCatalogSourceFor(ORG).listActiveCatalog();
+    expect(products.mock.calls.map(([p]) => p)).toEqual([
+      { active: true, limit: 100 },
+      { active: true, limit: 100, starting_after: "prod_a" },
+    ]);
+    expect(catalog.products).toEqual([{ id: "prod_a" }, { id: "prod_a" }]);
+  });
+
+  it.each(["none", "unusable"] as const)(
+    "rejects a %s connection with OfferingsCatalogUnavailableError and no list call",
+    async (kind) => {
+      mockStripeClientForOrganization.mockResolvedValue({ kind });
+      const products = jest.fn();
+      const err = await stripeCatalogSourceFor(ORG)
+        .listActiveCatalog()
+        .catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(OfferingsCatalogUnavailableError);
+      expect((err as Error).message).toBe("The Offerings catalog source is unavailable");
+      expect((err as { cause?: unknown }).cause).toBeUndefined();
+      expect(products).not.toHaveBeenCalled();
+    },
+  );
+
+  it("rejects a hung page after the timeout, starts no call after it, and leaves no unhandled rejection", async () => {
+    jest.useFakeTimers();
+    const unhandled = jest.fn();
+    process.on("unhandledRejection", unhandled);
+    try {
+      let rejectHung: (err: Error) => void = () => undefined;
+      const products = jest.fn(
+        () =>
+          new Promise<Page>((_resolve, reject) => {
+            rejectHung = reject;
+          }),
+      );
+      const prices = jest.fn(
+        () =>
+          new Promise<Page>((resolve) => {
+            setTimeout(() => resolve({ data: [{ id: "price_late" }], has_more: true }), OFFERINGS_CATALOG_READ_TIMEOUT_MS + 1000);
+          }),
+      );
+      connect(clientOf(products, prices));
+
+      const read = stripeCatalogSourceFor(ORG).listActiveCatalog();
+      const settled = read.catch((e: unknown) => e);
+      await jest.advanceTimersByTimeAsync(OFFERINGS_CATALOG_READ_TIMEOUT_MS);
+      expect(await settled).toBeInstanceOf(OfferingsCatalogUnavailableError);
+
+      // The late page resolves after the timeout: no further call is started.
+      await jest.advanceTimersByTimeAsync(2000);
+      expect(prices).toHaveBeenCalledTimes(1);
+      // The hung page rejects after the timeout: never an unhandled rejection.
+      rejectHung(new Error("late failure"));
+      await jest.advanceTimersByTimeAsync(0);
+      jest.useRealTimers();
+      await new Promise((resolve) => setImmediate(resolve));
+      expect(unhandled).not.toHaveBeenCalled();
+      expect(products).toHaveBeenCalledTimes(1);
+    } finally {
+      process.off("unhandledRejection", unhandled);
+    }
+  });
+
+  it("rejects with the Stripe error object itself", async () => {
+    const stripeError = new Error("Invalid API Key provided: rk_test_********************abcd");
+    const products = jest.fn(async () => Promise.reject(stripeError));
+    const prices = pagedList("price", [1]);
+    connect(clientOf(products, prices));
+    await expect(stripeCatalogSourceFor(ORG).listActiveCatalog()).rejects.toBe(stripeError);
+  });
+
+  it("requests the client again on every read, never reusing one", async () => {
+    connect(clientOf(pagedList("prod", [1]), pagedList("price", [1])));
+    const source = stripeCatalogSourceFor(ORG);
+    await source.listActiveCatalog();
+    connect(clientOf(pagedList("prod", [1]), pagedList("price", [1])));
+    await source.listActiveCatalog();
+    expect(mockStripeClientForOrganization).toHaveBeenCalledTimes(2);
+  });
+});

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

@@ -0,0 +1,308 @@
+/**
+ * The one Offerings normalizer (#8876, spec
+ * docs/specs/8876-the-offerings-data-model-typed-spec.md D5) — turns a
+ * seller's Stripe Products and Prices into the typed shape every Offerings
+ * surface consumes, and names why each other Product is held out.
+ *
+ * Stripe text is seller-authored and untrusted (contract
+ * docs/specs/8879-the-offerings-security-contract-key-spec.md §3.6). It is
+ * normalized here once (T1) and parsed by `@working-theory/validation`'s
+ * Offerings schemas before any surface sees it. Only the fields the contract
+ * lists are read: a Product's `images` and `url`, a Price's `nickname` and
+ * `statement_descriptor`, and every other metadata key never reach the
+ * output.
+ *
+ * The lookup key is split only by `parseLookupKey` (G1), and a Price's period
+ * read only by `periodOfStripePrice` (G3).
+ *
+ * `normalizeCatalog` is pure: no I/O, no clock, no logging.
+ */
+import {
+  LOOKUP_KEY_PERIODS,
+  OFFERINGS_AMOUNT_MAX,
+  OFFERINGS_DESCRIPTION_MAX,
+  OFFERINGS_FEATURES_MAX,
+  OFFERINGS_FEATURE_MAX,
+  OFFERINGS_NAME_MAX,
+  OFFERINGS_NOTE_MAX,
+  OFFERINGS_UNIT_LABEL_MAX,
+  offeringsHeldProductSchema,
+  offeringsSnapshotProductSchema,
+  offeringsStripeIdSchema,
+  parseLookupKey,
+  periodOfStripePrice,
+  type OfferingsGroup,
+  type OfferingsHeldProduct,
+  type OfferingsHeldReason,
+  type OfferingsPrice,
+  type OfferingsSnapshotProduct,
+} from "@working-theory/validation";
+
+/** The most Products and Prices a source pages through, and the normalizer reads. */
+export const OFFERINGS_CATALOG_PRODUCTS_MAX = 1000;
+export const OFFERINGS_CATALOG_PRICES_MAX = 3000;
+
+/**
+ * A Stripe Product as the normalizer reads it. Every field is `unknown`, so a
+ * Stripe SDK object fits with no import and nothing is trusted.
+ */
+export interface CatalogProduct {
+  readonly id?: unknown;
+  readonly active?: unknown;
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly marketing_features?: unknown;
+  readonly unit_label?: unknown;
+  readonly metadata?: unknown;
+}
+
+/** A Stripe Price as the normalizer reads it. */
+export interface CatalogPrice {
+  readonly id?: unknown;
+  readonly active?: unknown;
+  readonly product?: unknown;
+  readonly lookup_key?: unknown;
+  readonly type?: unknown;
+  readonly recurring?: unknown;
+  readonly billing_scheme?: unknown;
+  readonly unit_amount?: unknown;
+  readonly currency?: unknown;
+}
+
+export interface OfferingsCatalog {
+  products: CatalogProduct[];
+  prices: CatalogPrice[];
+}
+
+/**
+ * Where a seller's catalog comes from. #8857 implements it with the per-key
+ * client, paginated (#8054), stopping at the two caps above.
+ */
+export interface OfferingsCatalogSource {
+  listActiveCatalog(): Promise<OfferingsCatalog>;
+}
+
+export interface NormalizedCatalog {
+  offerings: OfferingsSnapshotProduct[];
+  held: OfferingsHeldProduct[];
+}
+
+// Unicode Cc, Cf, Zl, Zp and Cs (lone surrogates) — T1's stripped categories.
+const STRIPPED = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/gu;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * T1: strip the categories (`\n` kept only when `keepNewlines`), NFC, trim,
+ * and cut to `max` code points. A non-string, or nothing left, is `null`.
+ * Exported for the Offerings session read's line-item names (#8931 D9).
+ */
+export function normalizeText(value: unknown, max: number, keepNewlines = false): string | null {
+  if (typeof value !== "string") return null;
+  const stripped = value.replace(STRIPPED, (ch) => (keepNewlines && ch === "\n" ? ch : ""));
+  const text = [...stripped.normalize("NFC").trim()].slice(0, max).join("").trimEnd();
+  return text.length > 0 ? text : null;
+}
+
+/**
+ * The Offerings product marker (contract G6, A9): any non-empty
+ * `metadata.ailk_group`. Deliberately wider than the group check below, so a
+ * malformed group such as `Plan` is held out of Offerings and still refused
+ * on the env checkout path (#8861).
+ */
+export function isOfferingsProduct(product: CatalogProduct): boolean {
+  return isRecord(product.metadata) && typeof product.metadata.ailk_group === "string"
+    && product.metadata.ailk_group.length > 0;
+}
+
+function metadataOf(product: CatalogProduct): Record<string, unknown> {
+  return isRecord(product.metadata) ? product.metadata : {};
+}
+
+function groupOf(product: CatalogProduct): OfferingsGroup | null {
+  const group = metadataOf(product).ailk_group;
+  return group === "plan" || group === "addon" ? group : null;
+}
+
+/** `metadata.ailk_order` when it is 1–4 digits, else `null` (sorts last). */
+function orderOf(product: CatalogProduct): number | null {
+  const order = metadataOf(product).ailk_order;
+  return typeof order === "string" && /^[0-9]{1,4}$/.test(order) ? Number(order) : null;
+}
+
+function featuresOf(product: CatalogProduct): string[] {
+  if (!Array.isArray(product.marketing_features)) return [];
+  return product.marketing_features
+    .map((feature: unknown) =>
+      isRecord(feature) ? normalizeText(feature.name, OFFERINGS_FEATURE_MAX) : null,
+    )
+    .filter((name): name is string => name !== null)
+    .slice(0, OFFERINGS_FEATURES_MAX);
+}
+
+function productIdOfPrice(price: CatalogPrice): unknown {
+  return isRecord(price.product) ? price.product.id : price.product;
+}
+
+function isStripeId(value: unknown): value is string {
+  return offeringsStripeIdSchema.safeParse(value).success;
+}
+
+/** One Price as a sellable offering price (G3), or `null`. */
+function sellablePrice(price: CatalogPrice): OfferingsPrice | null {
+  const parsed = parseLookupKey(price.lookup_key);
+  const period = periodOfStripePrice(price);
+  if (!parsed || parsed.period !== period) return null;
+  if (price.billing_scheme !== "per_unit") return null;
+  const amount = price.unit_amount;
+  if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 0 || amount > OFFERINGS_AMOUNT_MAX) {
+    return null;
+  }
+  if (typeof price.currency !== "string" || !/^[a-z]{3}$/.test(price.currency)) return null;
+  if (isRecord(price.recurring) && price.recurring.usage_type === "metered") return null;
+  return {
+    priceId: price.id as string,
+    lookupKey: price.lookup_key as string,
+    plan: parsed.plan,
+    period: parsed.period,
+    interval: isRecord(price.recurring) && price.type === "recurring"
+      ? (price.recurring.interval as "month" | "year")
+      : null,
+    amount,
+    currency: price.currency,
+  };
+}
+
+/** Compare two strings by code point (not UTF-16 unit). */
+function compareCodePoints(a: string, b: string): number {
+  const x = [...a];
+  const y = [...b];
+  for (let i = 0; i < Math.min(x.length, y.length); i++) {
+    const d = x[i]!.codePointAt(0)! - y[i]!.codePointAt(0)!;
+    if (d !== 0) return d;
+  }
+  return x.length - y.length;
+}
+
+/** D5 step 5: plan before addon, `ailkOrder` (null last), name, then id. */
+function compareOfferings(a: OfferingsSnapshotProduct, b: OfferingsSnapshotProduct): number {
+  if (a.ailkGroup !== b.ailkGroup) return a.ailkGroup === "plan" ? -1 : 1;
+  if (a.ailkOrder !== b.ailkOrder) {
+    if (a.ailkOrder === null) return 1;
+    if (b.ailkOrder === null) return -1;
+    return a.ailkOrder - b.ailkOrder;
+  }
+  return compareCodePoints(a.name, b.name) || compareCodePoints(a.productId, b.productId);
+}
+
+type Candidate =
+  | { productId: string; name: string; held: OfferingsHeldReason }
+  | { productId: string; name: string; offering: OfferingsSnapshotProduct };
+
+/**
+ * Normalize one seller's catalog (D5). Reads at most
+ * `OFFERINGS_CATALOG_PRODUCTS_MAX` Products and `OFFERINGS_CATALOG_PRICES_MAX`
+ * Prices; an inactive Product, a Product or Price whose id is not a Stripe
+ * id, and a repeat of a Product or Price id already read, is left out of both
+ * lists. Every other Product is either an
+ * offering or held with its reason. One Product that fails its parse is held
+ * `invalid`, never failing the catalog.
+ */
+export function normalizeCatalog(input: OfferingsCatalog): NormalizedCatalog {
+  // A Product id the source answers twice (a paging bug) counts once.
+  const seen = new Set<unknown>();
+  const products = input.products
+    .slice(0, OFFERINGS_CATALOG_PRODUCTS_MAX)
+    .filter((p) => p.active === true && isStripeId(p.id) && !seen.has(p.id) && seen.add(p.id));
+  const pricesByProduct = new Map<string, CatalogPrice[]>();
+  const seenPrices = new Set<unknown>();
+  for (const price of input.prices.slice(0, OFFERINGS_CATALOG_PRICES_MAX)) {
+    const productId = productIdOfPrice(price);
+    if (price.active !== true || !isStripeId(price.id) || typeof productId !== "string") continue;
+    if (seenPrices.has(price.id)) continue;
+    seenPrices.add(price.id);
+    const list = pricesByProduct.get(productId) ?? [];
+    list.push(price);
+    pricesByProduct.set(productId, list);
+  }
+
+  // G4: every plan any active Product's Prices carry, by Product — two
+  // Products carrying one plan hold both, whatever else holds them.
+  const plansByProduct = new Map<string, Set<string>>();
+  const productsByPlan = new Map<string, Set<string>>();
+  for (const product of products) {
+    const id = product.id as string;
+    const plans = new Set(
+      (pricesByProduct.get(id) ?? [])
+        .map((price) => parseLookupKey(price.lookup_key)?.plan)
+        .filter((plan): plan is string => plan !== undefined),
+    );
+    plansByProduct.set(id, plans);
+    for (const plan of plans) {
+      const holders = productsByPlan.get(plan) ?? new Set<string>();
+      holders.add(id);
+      productsByPlan.set(plan, holders);
+    }
+  }
+
+  const candidates: Candidate[] = products.map((product) => {
+    const productId = product.id as string;
+    const name = normalizeText(product.name, OFFERINGS_NAME_MAX) ?? "";
+    const group = groupOf(product);
+    if (group === null) return { productId, name, held: "group_invalid" };
+    if (name === "") return { productId, name, held: "name_missing" };
+
+    const active = pricesByProduct.get(productId) ?? [];
+    const sellable = active.map(sellablePrice);
+    if (sellable.length === 0 || sellable.some((price) => price === null)) {
+      return { productId, name, held: "needs_lookup_key" };
+    }
+    const prices = sellable as OfferingsPrice[];
+    const plan = prices[0]!.plan;
+    const periods = new Set(prices.map((price) => price.period));
+    if (prices.some((price) => price.plan !== plan) || periods.size !== prices.length) {
+      return { productId, name, held: "needs_lookup_key" };
+    }
+    if ([...plansByProduct.get(productId)!].some((p) => productsByPlan.get(p)!.size > 1)) {
+      return { productId, name, held: "plan_conflict" };
+    }
+
+    const metadata = metadataOf(product);
+    const offering = offeringsSnapshotProductSchema.safeParse({
+      productId,
+      plan,
+      name,
+      description: normalizeText(product.description, OFFERINGS_DESCRIPTION_MAX, true),
+      marketingFeatures: featuresOf(product),
+      unitLabel: normalizeText(product.unit_label, OFFERINGS_UNIT_LABEL_MAX),
+      note: normalizeText(metadata.ailk_note, OFFERINGS_NOTE_MAX),
+      termsNote: normalizeText(metadata.ailk_terms_note, OFFERINGS_NOTE_MAX),
+      ailkGroup: group,
+      ailkOrder: orderOf(product),
+      prices: [...prices].sort(
+        (a, b) => LOOKUP_KEY_PERIODS.indexOf(a.period) - LOOKUP_KEY_PERIODS.indexOf(b.period),
+      ),
+    });
+    return offering.success
+      ? { productId, name, offering: offering.data }
+      : { productId, name, held: "invalid" };
+  });
+
+  const offerings: OfferingsSnapshotProduct[] = [];
+  const held: OfferingsHeldProduct[] = [];
+  for (const candidate of candidates) {
+    if ("offering" in candidate) {
+      offerings.push(candidate.offering);
+      continue;
+    }
+    const parsed = offeringsHeldProductSchema.safeParse({
+      productId: candidate.productId,
+      name: candidate.name,
+      reason: candidate.held,
+    });
+    if (parsed.success) held.push(parsed.data);
+  }
+  return { offerings: offerings.sort(compareOfferings), held };
+}