create-ailk 0.24.0 → 0.26.0

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

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

@@ -1,318 +0,0 @@
-/**
- * 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;
-}
-
-/**
- * An Offerings `plan` Product: `metadata.ailk_group` exactly `"plan"` — the
- * normalizer's own group read, the stricter sibling of `isOfferingsProduct`.
- * The Billing tab's plan checkout sells only a Price whose Product passes
- * this (#9338 DD4), so an unmarked hub plan never sells from it.
- */
-export function isOfferingsPlanProduct(product: CatalogProduct): boolean {
-  return groupOf(product) === "plan";
-}
-
-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 };
-}