@openlup/platform 0.17.0 → 0.19.0

package/src/catalog/bundleAvailabilityService.ts

@@ -0,0 +1,171 @@
+import type {
+  BundleAvailability,
+  BundleAvailabilityComponent,
+} from "./bundleAvailability.js";
+import type {
+  BundleStockAvailability as CommerceOfferAvailability,
+  BundleStockPort as CommerceOfferAvailabilityPort,
+  BundleStockRequestItem as CommerceOfferAvailabilityRequestItem,
+} from "./bundleBindings.js";
+import type {
+  ActiveBundleComposition,
+  BundleCatalogReadPort,
+  BundleComponentRow,
+} from "./bundleCatalogReadPort.js";
+
+/**
+ * Derived bundle stock, composed from the two ports that already know the halves:
+ * the bundle read port knows the bill of materials, the EXISTING commerce offer
+ * availability port knows what a unit's stock is. Nothing here re-derives stock and
+ * nothing here opens a database handle.
+ *
+ * ONE BATCHED CALL, ALWAYS. Every component of every bundle in the request is
+ * asked for in a single `getAvailability`, deduplicated by sku, because the
+ * underlying port answers a set in three queries — asking per bundle would turn a
+ * catalogue listing into a query storm and would let two bundles sharing a unit
+ * disagree about its stock inside one response.
+ *
+ * A sku the availability port does not answer for is a MISSING figure, not zero:
+ * it is folded in as `sellableNow: null`, so the pure kernel reports the bundle as
+ * unknown and names the component rather than quietly overselling or hiding it.
+ */
+
+export interface BundleAvailabilityServiceDeps {
+  bundleCatalogReadPort: BundleCatalogReadPort;
+  offerAvailabilityPort: CommerceOfferAvailabilityPort;
+  /** Threshold handed to the pure kernel; its own default applies when omitted. */
+  lowStockThreshold?: number;
+  includeAddonsInStock?: boolean;
+}
+
+export interface BundleAvailabilityRow {
+  composition: ActiveBundleComposition;
+  availability: BundleAvailability;
+  /**
+   * The EXACT rows the kernel was given, carried out again rather than recomputed.
+   *
+   * The bundle-level answer names one limiting component; an operator staring at a bundle that
+   * cannot ship needs to know how far off every OTHER component is too, so they can tell "order one
+   * more of this" from "this bundle is months away". These rows are the only place that figure
+   * exists — the kernel folds them into a single number and the sellable feed's components carry
+   * price, never stock. Returning them costs nothing here and is the alternative to a second stock
+   * derivation somewhere that can disagree with this one.
+   */
+  components: readonly BundleAvailabilityComponent[];
+}
+
+export interface BundleAvailabilityService {
+  /** Fold stock into a set of compositions the caller already holds. */
+  describeCompositions(
+    compositions: readonly ActiveBundleComposition[],
+  ): Promise<BundleAvailabilityRow[]>;
+  /** Read the live sellable set and fold stock into it. */
+  describeActiveBundles(input?: { currency?: string }): Promise<BundleAvailabilityRow[]>;
+}
+
+export function createBundleAvailabilityServices({ deriveBundleAvailability }: { deriveBundleAvailability: (input: import("./bundleAvailability.js").DeriveBundleAvailabilityInput) => BundleAvailability }) {
+function createBundleAvailabilityService(
+  deps: BundleAvailabilityServiceDeps,
+): BundleAvailabilityService {
+  async function describeCompositions(
+    compositions: readonly ActiveBundleComposition[],
+  ): Promise<BundleAvailabilityRow[]> {
+    if (compositions.length === 0) return [];
+
+    const items = requestItems(compositions);
+    const stock = items.length === 0
+      ? new Map<string, number | null>()
+      : sellableBySku(await deps.offerAvailabilityPort.getAvailability({ items }));
+
+    return compositions.map((composition) => {
+      const components = composition.components.map((component) => ({
+        sku: component.sku,
+        quantity: component.quantity,
+        isAddon: component.isAddon,
+        // `has` distinguishes "answered null" from "never answered"; both fold to
+        // null, and neither is allowed to become a number here.
+        sellableNow: stock.has(component.sku) ? (stock.get(component.sku) ?? null) : null,
+      }));
+      return {
+        composition,
+        components,
+        availability: deriveBundleAvailability({
+          components,
+          lowStockThreshold: deps.lowStockThreshold,
+          includeAddonsInStock: deps.includeAddonsInStock,
+        }),
+      };
+    });
+  }
+
+  return {
+    describeCompositions,
+    async describeActiveBundles(input: { currency?: string } = {}) {
+      return describeCompositions(
+        await deps.bundleCatalogReadPort.listActiveBundleCompositions(input),
+      );
+    },
+  };
+}
+
+  return { createBundleAvailabilityService };
+}
+
+/**
+ * The port to use where no stock source is bound at all.
+ *
+ * It answers every item with `sellableNow: null`, which the kernel reads as
+ * unknown — so a deployment without an inventory rail publishes bundles whose
+ * price is exact and whose stock is honestly unstated. The alternative, omitting
+ * the availability block, would have made "we do not know" indistinguishable from
+ * "we did not ask", and the alternative to THAT — defaulting to available —
+ * oversells on a deployment that never counted anything.
+ */
+export function createUnknownOfferAvailabilityPort(): CommerceOfferAvailabilityPort {
+  return {
+    getAvailability({ items }) {
+      return Promise.resolve(
+        items.map((item) => ({
+          sku: item.sku,
+          productSlug: item.productSlug,
+          variantId: item.variantId,
+          status: "unknown" as const,
+          visibleInConfigurator: true,
+          sellableNow: null,
+          reasonCode: "stock_unknown",
+          source: "unbound",
+        })),
+      );
+    },
+  };
+}
+
+/**
+ * One request item per distinct sku across every bundle. `requestedQuantity` stays
+ * at the port's own default of one: the question asked is "how many units exist",
+ * and the multiplication by the bill of materials belongs to the pure kernel,
+ * which is the only place that knows how many bundles a figure buys.
+ */
+function requestItems(
+  compositions: readonly ActiveBundleComposition[],
+): CommerceOfferAvailabilityRequestItem[] {
+  const bySku = new Map<string, BundleComponentRow>();
+  for (const composition of compositions) {
+    for (const component of composition.components) {
+      if (!bySku.has(component.sku)) bySku.set(component.sku, component);
+    }
+  }
+  return [...bySku.values()].map((component) => ({
+    sku: component.sku,
+    productSlug: component.productSlug,
+    variantId: component.variantId,
+    requestedQuantity: 1,
+    checkoutMode: "one_time" as const,
+  }));
+}
+
+function sellableBySku(
+  answers: readonly CommerceOfferAvailability[],
+): Map<string, number | null> {
+  return new Map(answers.map((answer) => [answer.sku, answer.sellableNow ?? null]));
+}

package/src/catalog/bundleBindings.ts

@@ -0,0 +1,29 @@
+import type { BundleActorKind } from "./bundleRuleCodes.js";
+
+/** The host's normalized stock seam; no inventory implementation is owned here. */
+export type BundleStockStatus = "available" | "low_stock" | "out_of_stock" | "unknown";
+export interface BundleStockRequestItem {
+  sku: string;
+  productSlug: string;
+  variantId: string;
+  requestedQuantity: number;
+  checkoutMode: "one_time" | "subscription";
+}
+export interface BundleStockAvailability {
+  sku: string;
+  productSlug: string;
+  variantId: string;
+  status: BundleStockStatus;
+  visibleInConfigurator: boolean;
+  sellableNow: number | null;
+  reasonCode: string;
+  source: string;
+}
+export interface BundleStockPort {
+  getAvailability(input: { items: readonly BundleStockRequestItem[] }): Promise<BundleStockAvailability[]>;
+}
+export interface BundleRuleBindings {
+  assertActivateNotMachineActor(input: { operation: string; actorKind: BundleActorKind }): "DRAFT_ONLY_FOR_MACHINE" | null;
+  offerAvailabilityStatusFor(sellableNow: number | null, lowStockThreshold?: number): BundleStockStatus;
+  offerAvailabilityReasonCode(status: BundleStockStatus): string;
+}

package/src/catalog/bundleCatalogQueries.ts

@@ -0,0 +1,98 @@
+/**
+ * The statements the direct-Postgres bundle read adapter renders.
+ *
+ * They live beside the adapter rather than inside it because they are the part a
+ * reader comes here to check — which relations are touched, which columns are
+ * asked for, and how a component's reference price is resolved — and reading them
+ * should not mean scrolling past the row marshalling that consumes them.
+ */
+
+export const SUMMARY_COLUMNS = `
+  b.id, b.code, b.title, b.status, b.fulfillment_mode, b.updated_at,
+  b.composition_constraint, b.metadata,
+  (SELECT count(*) FROM public.catalog_bundle_components c WHERE c.bundle_id = b.id)
+    AS component_count,
+  EXISTS (SELECT 1 FROM public.catalog_bundle_prices p WHERE p.bundle_id = b.id AND p.active)
+    AS has_active_target_price`;
+
+export const LIST_FILTER = `
+  WHERE ($1::text = 'all' OR b.status = $1::text)
+    AND ($2::text IS NULL OR b.code ILIKE '%' || $2 || '%' OR b.title ILIKE '%' || $2 || '%')`;
+
+export const LIST_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b ${LIST_FILTER}
+  ORDER BY b.code LIMIT $3 OFFSET $4`;
+
+export const COUNT_SQL = `SELECT count(*) AS total FROM public.catalog_bundles b ${LIST_FILTER}`;
+
+export const DETAIL_SQL = `SELECT ${SUMMARY_COLUMNS} FROM public.catalog_bundles b WHERE b.code = $1`;
+
+/**
+ * The unit's reference price in ONE named list: the lowest tier that is active,
+ * newest window first. A unit the list prices nothing for resolves to NULL rather
+ * than dropping the component, so a caller sees an unpriced part instead of a
+ * shorter bill of materials.
+ */
+export const REFERENCE_PRICE = `(
+  SELECT pe.unit_price_minor FROM public.price_entries pe
+   WHERE pe.variant_id = s.id AND pe.price_list_id = %LIST% AND pe.active
+   ORDER BY pe.min_qty ASC, pe.valid_from DESC LIMIT 1)`;
+
+export const COMPONENT_SQL = `
+  SELECT c.bundle_id, s.sku, s.title, pr.slug AS product_slug, s.id AS variant_id,
+         c.quantity, c.is_addon, c.sort_order,
+         ${REFERENCE_PRICE.replace("%LIST%", "$2::uuid")} AS reference_unit_price_minor
+    FROM public.catalog_bundle_components c
+    JOIN public.catalog_skus s ON s.id = c.catalog_sku_id
+    JOIN public.catalog_products pr ON pr.id = s.product_id
+   WHERE c.bundle_id = $1::uuid
+   ORDER BY c.sort_order, s.sku`;
+
+// One statement for the whole feed: each bundle carries its own price list, so the
+// per-bundle list is zipped in rather than looped over.
+export const FEED_COMPONENT_SQL = `
+  SELECT c.bundle_id, s.sku, s.title, pr.slug AS product_slug, s.id AS variant_id,
+         c.quantity, c.is_addon, c.sort_order,
+         ${REFERENCE_PRICE.replace("%LIST%", "selected.price_list_id")} AS reference_unit_price_minor
+    FROM unnest($1::uuid[], $2::uuid[]) AS selected(bundle_id, price_list_id)
+    JOIN public.catalog_bundle_components c ON c.bundle_id = selected.bundle_id
+    JOIN public.catalog_skus s ON s.id = c.catalog_sku_id
+    JOIN public.catalog_products pr ON pr.id = s.product_id
+   ORDER BY c.bundle_id, c.sort_order, s.sku`;
+
+export const PRICE_SQL = `
+  SELECT p.mode, p.target_price_minor, list.currency, p.amount_kind, p.active,
+         p.valid_from, p.valid_to
+    FROM public.catalog_bundle_prices p
+    JOIN public.price_lists AS list ON list.id = p.price_list_id
+   WHERE p.bundle_id = $1::uuid
+   ORDER BY p.valid_from DESC`;
+
+export const OWN_LIST_SQL = `
+  SELECT list.id, list.currency
+    FROM public.catalog_bundle_prices p
+    JOIN public.price_lists AS list ON list.id = p.price_list_id
+   WHERE p.bundle_id = $1::uuid AND p.active AND ($2::text IS NULL OR p.mode = $2::text)
+   ORDER BY p.valid_from DESC LIMIT 1`;
+
+export const CURRENCY_LIST_SQL = `
+  SELECT id, currency FROM public.price_lists
+   WHERE currency = $1::text AND status = 'active'
+   ORDER BY created_at DESC LIMIT 1`;
+
+export const FEED_SQL = `
+  SELECT b.id, b.code, b.title, b.fulfillment_mode, p.mode, p.target_price_minor,
+         p.price_list_id, list.currency
+    FROM public.catalog_bundles b
+    JOIN public.catalog_bundle_prices p ON p.bundle_id = b.id AND p.active
+    JOIN public.price_lists AS list ON list.id = p.price_list_id
+   WHERE b.status = 'active' AND ($1::text IS NULL OR list.currency = $1::text)
+   ORDER BY b.code, p.valid_from DESC`;
+
+export const HISTORY_SQL = `
+  SELECT id, bundle_code, action, before_state, after_state, created_at
+    FROM public.catalog_bundle_write_events
+   WHERE bundle_code = $1::text
+   ORDER BY created_at DESC LIMIT $2 OFFSET $3`;
+
+export const HISTORY_COUNT_SQL = `
+  SELECT count(*) AS total FROM public.catalog_bundle_write_events WHERE bundle_code = $1::text`;

package/src/catalog/bundleCatalogReadPort.ts

@@ -0,0 +1,181 @@
+/**
+ * The semantic READ port for bundles.
+ *
+ * This file names the CAPABILITY, never the storage: no table, no routine, no
+ * data-client type and no vendor appears here, and the domain layer opens no
+ * database handle of its own. Both shipped read adapters implement exactly this
+ * interface and are proved against ONE shared scenario table, so a caller cannot
+ * tell them apart. It is the same shape the write port
+ * (`adminBundleWritePort.ts`) established in the previous wave.
+ *
+ * Reads are plain SELECTs rather than security-definer routines: the write
+ * boundary is where authority lives, and a read that re-implemented it would be a
+ * second place for the same rules to be written down. The admin surface reads the
+ * whole lifecycle (draft, active, archived); the sellable feed asks a separate
+ * question and gets only what is live.
+ *
+ * COMPONENT PRICES ARE RESOLVED, NOT STORED. A bundle stores one target price for
+ * the whole set; a component's REFERENCE unit price is whatever the selected
+ * price list says today. The adapters therefore join the catalogue and the price
+ * list themselves, and hand back a resolved figure (or `null` when the list
+ * prices nothing for that unit) so the allocator upstream never re-reads storage.
+ */
+
+/**
+ * A read that FAILED, as opposed to a read that found nothing.
+ *
+ * Both adapters raise this rather than returning an empty page, because the two
+ * outcomes are opposite: an empty catalogue is a fact a storefront may cache and
+ * show, and a failed query is not. The class lives on the port so neither chain
+ * owns the distinction.
+ */
+export class BundleCatalogReadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BundleCatalogReadError";
+  }
+}
+
+/** Which lifecycle rows an admin list asks for. `all` is the admin default. */
+export type BundleListStatusFilter = "draft" | "active" | "archived" | "all";
+
+export interface ListBundlesInput {
+  status: BundleListStatusFilter;
+  /** Free-text match over code and title; absent means no narrowing. */
+  query?: string;
+  limit: number;
+  offset: number;
+}
+
+export interface BundleSummary {
+  code: string;
+  title: string;
+  status: string;
+  fulfillmentMode: string;
+  componentCount: number;
+  hasActiveTargetPrice: boolean;
+  updatedAt: string;
+}
+
+export interface ListBundlesResult {
+  bundles: BundleSummary[];
+  total: number;
+}
+
+/**
+ * One line of the bill of materials, already joined to the catalogue.
+ *
+ * `productSlug` and `variantId` are carried because the availability port
+ * addresses stock by all three coordinates; a caller that had only the sku would
+ * have to re-open the catalogue to ask about stock, which is exactly the
+ * round-trip this DTO exists to remove.
+ */
+export interface BundleComponentRow {
+  sku: string;
+  title: string | null;
+  productSlug: string;
+  variantId: string;
+  quantity: number;
+  isAddon: boolean;
+  sortOrder: number;
+  /** Resolved from the selected price list; `null` when it prices no such unit. */
+  referenceUnitPriceMinor: number | null;
+}
+
+export interface BundleTargetPriceRow {
+  mode: string;
+  targetPriceMinor: number;
+  currency: string;
+  amountKind: string;
+  active: boolean;
+  validFrom: string;
+  validTo: string | null;
+}
+
+export interface BundleDetail extends BundleSummary {
+  /** The opaque `{kind, version, data}` envelope; `null` for an unconstrained bundle. */
+  compositionConstraint: { kind: string; version: number; data: Record<string, unknown> } | null;
+  metadata: Record<string, unknown>;
+  components: BundleComponentRow[];
+  prices: BundleTargetPriceRow[];
+  /** Present only when the host selects effective price authority. */
+  resolvedTargetPrice?: BundleTargetPriceRow | null;
+  /** The currency whose list resolved `referenceUnitPriceMinor`; `null` if none did. */
+  resolvedCurrency: string | null;
+  /**
+   * The price list those reference figures came from. Carried because a price
+   * preview has to name the list it priced against — an amount without the list
+   * that gave it meaning is not reproducible.
+   */
+  resolvedPriceListId: string | null;
+}
+
+export interface GetBundleInput {
+  code: string;
+  /**
+   * Price the components against THIS currency's active list. Omitted means "the
+   * list this bundle's own active target price is written into", which is the
+   * only currency an operator has actually chosen for it.
+   */
+  currency?: string;
+  /** Narrow the target price whose list is selected; omitted means any mode (the opt-in effective store defaults to one_time). */
+  mode?: string;
+  regionCode?: string;
+  atTime?: string;
+}
+
+/**
+ * One live, sellable bundle: active status, an active target price, and its
+ * components priced in that price's own currency. This is the feed's row, and it
+ * is deliberately a different question from `getBundle` — the storefront must
+ * never be able to see a draft by asking the read port nicely.
+ */
+export interface ActiveBundleComposition {
+  code: string;
+  title: string;
+  fulfillmentMode: string;
+  currency: string;
+  targetPriceMinor: number;
+  mode: string;
+  components: BundleComponentRow[];
+}
+
+export interface BundleHistoryEvent {
+  id: string;
+  action: string;
+  actorKind: string | null;
+  actorEmail: string | null;
+  entityId: string | null;
+  oldValue: unknown;
+  newValue: unknown;
+  occurredAt: string;
+}
+
+export interface BundleHistoryInput {
+  code: string;
+  limit: number;
+  offset: number;
+}
+
+export interface BundleHistoryResult {
+  events: BundleHistoryEvent[];
+  total: number;
+}
+
+export interface BundleCatalogReadPort {
+  /** Admin list across the whole lifecycle, newest-agnostic and code-ordered. */
+  listBundles(input: ListBundlesInput): Promise<ListBundlesResult>;
+  /** Full admin detail, or `null` when no bundle carries that code. */
+  getBundle(input: GetBundleInput): Promise<BundleDetail | null>;
+  /**
+   * Every bundle a storefront may sell right now. Never returns a draft or an
+   * archived bundle, and never a bundle without an active target price.
+   */
+  listActiveBundleCompositions(input?: { currency?: string; regionCode?: string; mode?: "one_time" | "subscription"; atTime?: string }): Promise<ActiveBundleComposition[]>;
+  /**
+   * The operator trail for one bundle. The two chains answer from different
+   * ledgers — a managed audit table and the platform's neutral write-event
+   * relation — which is why this is a port method rather than a shared query.
+   */
+  listBundleHistory(input: BundleHistoryInput): Promise<BundleHistoryResult>;
+}