@openlup/platform 0.16.0 → 0.18.0

package/src/catalog/readPorts.ts

@@ -0,0 +1,61 @@
+import type { SellableCatalogItem, SellableCatalogProfile, CatalogSkuEnvelopeSelector, NeutralSkuEnvelopeV1 } from "./contracts/index.js";
+
+/**
+ * Minimal neutral catalog seam used by the local reference storefront. It is
+ * independent of richer application catalog read ports.
+ */
+export interface SellableCatalogPort {
+  getStorefrontProfile(): Promise<SellableCatalogProfile>;
+  listSellableItems(): Promise<SellableCatalogItem[]>;
+}
+
+/**
+ * Dark W2a read seam. Its row-safe return value deliberately contains document
+ * references, never a document payload or a SKU-level document override.
+ */
+export interface CatalogSkuEnvelopeReadPort {
+  listSkuEnvelopes(query: CatalogSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage>;
+  /**
+   * Page only active trade items that are sellable in at least one commerce
+   * channel. This is intentionally distinct from the neutral inventory-style
+   * listing above: consumers such as compatibility must not discover dormant
+   * SKUs and then try to filter them with a second authority.
+   */
+  listActiveSkuEnvelopes(query: CatalogActiveSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage>;
+  getSkuEnvelope(selector: CatalogSkuEnvelopeSelector): Promise<NeutralSkuEnvelopeV1 | null>;
+  /** Compatibility lookup for callers that already persist the neutral SKU UUID. */
+  getSkuEnvelopeById(skuId: string): Promise<NeutralSkuEnvelopeV1 | null>;
+}
+
+/**
+ * Additive discovery capability. Existing commerce consumers remain typed to
+ * {@link CatalogSkuEnvelopeReadPort} and therefore cannot accidentally use it.
+ */
+export interface PublicCatalogSkuEnvelopeReadPort extends CatalogSkuEnvelopeReadPort {
+  /**
+   * Public discovery's active-only page. Unlike the commerce method above it
+   * intentionally includes temporarily unsellable active variants.
+   */
+  listPublicActiveSkuEnvelopes(query: CatalogSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage>;
+  /** Active-only cursor page restricted to one already-authoritative product. */
+  listPublicActiveProductSkuEnvelopes(
+    productId: string,
+    query: CatalogSkuEnvelopeListQuery,
+  ): Promise<CatalogSkuEnvelopePage>;
+}
+
+export interface CatalogSkuEnvelopeListQuery {
+  cursor: string | null;
+  limit: number;
+}
+
+export interface CatalogActiveSkuEnvelopeListQuery extends CatalogSkuEnvelopeListQuery {
+  /** Optional server-selected scope; supplied selections contain 1–100 unique SKU codes. */
+  skuCodes?: readonly string[];
+}
+
+export interface CatalogSkuEnvelopePage {
+  items: NeutralSkuEnvelopeV1[];
+  nextCursor: string | null;
+}
+

package/src/catalog/referenceCatalogHandler.ts

@@ -0,0 +1,39 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import {
+  SELLABLE_CATALOG_CONTRACT_VERSION,
+  sellableCatalogListResponseSchema,
+} from "./sellableSchemas.js";
+import type { SellableCatalogPort } from "./readPorts.js";
+
+export function createReferenceCatalogItemsHandler({
+  catalogPort, responder,
+}: {
+  catalogPort: SellableCatalogPort;
+  responder: BffResponder;
+}) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    try {
+      const response = sellableCatalogListResponseSchema.safeParse({
+        contractVersion: SELLABLE_CATALOG_CONTRACT_VERSION,
+        profile: await catalogPort.getStorefrontProfile(),
+        items: await catalogPort.listSellableItems(),
+      });
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Reference catalog returned invalid items");
+        return;
+      }
+      sendBffSuccess(res, response.data, { contractVersion: SELLABLE_CATALOG_CONTRACT_VERSION }, {
+        cacheControl: "no-store",
+      });
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Reference catalog is unavailable");
+    }
+  };
+}

package/src/catalog/resolvedSkuProjection.ts

@@ -0,0 +1,76 @@
+import { z } from "./validation.js";
+import {
+  CatalogSkuAuthorityError,
+  assertPrimaryUnitGtinAuthority,
+  neutralSkuEnvelopeV1Schema,
+  type NeutralSkuEnvelopeV1,
+} from "./foundationSchemas.js";
+
+const uuidSchema = z.guid();
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const currencySchema = z.string().regex(/^[A-Z]{3}$/u);
+const moneyMinorSchema = z.number().int().nonnegative();
+
+/**
+ * Server-only, read-safe projection. It intentionally composes opaque document
+ * references with resolved prices and never selects or exposes document payload.
+ */
+export const RESOLVED_SKU_PROJECTION_VERSION = "catalog.resolved-sku.v1";
+
+export const resolvedSkuProjectionSchema = z.object({
+  contractVersion: z.literal(RESOLVED_SKU_PROJECTION_VERSION),
+  envelope: neutralSkuEnvelopeV1Schema,
+  priceContext: z.object({
+    priceListId: uuidSchema,
+    regionCode: z.string().regex(/^[A-Z]{2,3}$/u),
+    currency: currencySchema,
+    channel: z.string().trim().min(1).max(64),
+    atTime: z.string().datetime({ offset: true }),
+  }).strict(),
+  pricing: z.object({
+    base: z.object({
+      priceEntryId: uuidSchema,
+      amountMinor: moneyMinorSchema,
+    }).strict(),
+    subscription: z.object({
+      policyRevisionId: uuidSchema,
+      policyDigest: digestSchema,
+      amountMinor: moneyMinorSchema,
+    }).strict().nullable(),
+  }).strict(),
+}).strict().superRefine((projection, context) => {
+  try {
+    assertPrimaryUnitGtinAuthority(projection.envelope.identifiers);
+  } catch (error) {
+    if (!(error instanceof CatalogSkuAuthorityError)) throw error;
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["envelope", "identifiers"],
+      message: error.code,
+    });
+  }
+  const subscriptionSellable = projection.envelope.sku.sellability.subscription;
+  if (subscriptionSellable && projection.pricing.subscription === null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["pricing", "subscription"], message: "subscription-sellable SKUs require a subscription price" });
+  }
+  if (!subscriptionSellable && projection.pricing.subscription !== null) {
+    context.addIssue({ code: z.ZodIssueCode.custom, path: ["pricing", "subscription"], message: "one-time-only SKUs must not carry a subscription price" });
+  }
+});
+
+export type ResolvedSkuProjection = z.infer<typeof resolvedSkuProjectionSchema>;
+
+/** Row-safe constructor boundary for adapters; it accepts no raw document row/payload. */
+export interface ResolvedSkuProjectionInput {
+  envelope: NeutralSkuEnvelopeV1;
+  priceContext: ResolvedSkuProjection["priceContext"];
+  pricing: ResolvedSkuProjection["pricing"];
+}
+
+export function buildResolvedSkuProjection(input: ResolvedSkuProjectionInput): ResolvedSkuProjection {
+  assertPrimaryUnitGtinAuthority(input.envelope.identifiers);
+  return resolvedSkuProjectionSchema.parse({
+    contractVersion: RESOLVED_SKU_PROJECTION_VERSION,
+    ...input,
+  });
+}

package/src/catalog/sellableBundleHandler.ts

@@ -0,0 +1,133 @@
+import { allocateBundleTargetPrice } from "@openlup/core/pricing";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { BundleResponseSchema } from "./adminBindings.js";
+import type { SellableBundle } from "./contracts/bundleAvailability.js";
+import type { BundleAvailability } from "./bundleAvailability.js";
+import type { ActiveBundleComposition } from "./bundleCatalogReadPort.js";
+import type { BundleAvailabilityService } from "./bundleAvailabilityService.js";
+
+
+/**
+ * The public sellable-bundle feed handler, shaped after the reference catalog
+ * handler: GET-only, one
+ * port call, validate the body before sending, and never serve an unvalidated
+ * shape.
+ *
+ * It composes rather than computes twice: the availability service already folds
+ * one batched stock answer into the live compositions, and the pricing kernel
+ * turns the stored target price into per-component money. This module only decides
+ * what a storefront is allowed to see.
+ *
+ * A bundle whose money cannot be derived is DROPPED from the feed, not published
+ * with a guessed figure. Three cases reach that door — an unpriced component, an
+ * empty composition, and a target price the kernel refuses — and all three mean
+ * the same thing to a storefront: this is not sellable today. Publishing it with a
+ * partial price would put a number on a shelf that no order line could reproduce.
+ */
+
+export interface SellableBundleHandlerDeps {
+  availabilityService: BundleAvailabilityService;
+  /** Narrow the feed to one currency; omitted means every currency an operator priced. */
+  currency?: string;
+  enabled: boolean;
+}
+
+export function createSellableBundleHandlers({ responder, sellableBundleListResponseSchema, SELLABLE_BUNDLE_CONTRACT_VERSION }: { responder: BffResponder; sellableBundleListResponseSchema: BundleResponseSchema; SELLABLE_BUNDLE_CONTRACT_VERSION: "catalog.sellable-bundle.v1" }) {
+const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+function createSellableBundleHandler(deps: SellableBundleHandlerDeps) {
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+    if (!deps.enabled) {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Bundle reads are disabled", {
+        details: { reason: "feature_flag_disabled", featureFlag: "COMMERCE_BUNDLE_READ_ENABLED" },
+      });
+      return;
+    }
+
+    try {
+      const rows = await deps.availabilityService.describeActiveBundles(
+        deps.currency ? { currency: deps.currency } : {},
+      );
+      const response = sellableBundleListResponseSchema.safeParse({
+        contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION,
+        bundles: rows
+          .map((row) => toSellableBundle(row.composition, row.availability))
+          .filter((bundle): bundle is SellableBundle => bundle !== null),
+      });
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Sellable bundle feed returned an invalid shape");
+        return;
+      }
+      sendBffSuccess(
+        res,
+        response.data,
+        { contractVersion: SELLABLE_BUNDLE_CONTRACT_VERSION },
+        { cacheControl: "no-store" },
+      );
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Sellable bundles are unavailable");
+    }
+  };
+}
+
+return { createSellableBundleHandler };
+}
+
+/**
+ * Derive the row a storefront sees, or `null` when the money cannot be stated.
+ *
+ * The allocator emits TWO lines for a quantity whose subtotal does not divide
+ * evenly, which is exactly why the feed carries lines rather than a unit price per
+ * component: `unitPrice x quantity === lineSubtotal` holds on every line, and the
+ * lines sum to the bundle's price with no remainder.
+ */
+export function toSellableBundle(
+  composition: ActiveBundleComposition,
+  availability: BundleAvailability,
+): SellableBundle | null {
+  if (composition.components.length === 0) return null;
+  if (composition.components.some((component) => component.referenceUnitPriceMinor === null)) {
+    return null;
+  }
+
+  const allocation = allocateBundleTargetPrice({
+    components: composition.components.map((component) => ({
+      sku: component.sku,
+      quantity: component.quantity,
+      unitPriceMinor: component.referenceUnitPriceMinor as number,
+    })),
+    targetPriceMinor: composition.targetPriceMinor,
+  });
+  if (!allocation.ok) return null;
+
+  // Basis points come from the per-component allocation, so a component split
+  // across two lines reports the same discount on both halves rather than two
+  // rounded figures that disagree.
+  const discountBpsBySku = new Map(
+    allocation.components.map((component) => [component.sku, component.discountBps]),
+  );
+
+  return {
+    code: composition.code,
+    title: composition.title,
+    fulfillmentMode: composition.fulfillmentMode,
+    price: { amountMinor: composition.targetPriceMinor, currency: composition.currency },
+    components: allocation.lines.map((line) => ({
+      sku: line.sku,
+      quantity: line.quantity,
+      effectiveUnitPriceMinor: line.effectiveUnitPriceMinor,
+      lineSubtotalMinor: line.lineSubtotalMinor,
+      discountBps: discountBpsBySku.get(line.sku) ?? 0,
+    })),
+    availability: {
+      status: availability.status,
+      sellableNow: availability.sellableNow,
+      limitingSku: availability.limitingSku,
+      reasonCode: availability.reasonCode,
+    },
+  };
+}

package/src/catalog/sellableSchemas.ts

@@ -0,0 +1,33 @@
+import { z } from "./validation.js";
+import { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./contracts/sellable.js";
+export type { SellableCatalogItem, SellableCatalogProfile, SellableCatalogListResponse } from "./contracts/sellable.js";
+
+/** Minimal neutral storefront wire schema. */
+const sellableCatalogMoneySchema = z.object({
+  amountMinor: z.number().int().nonnegative(),
+  currency: z.string().regex(/^[A-Z]{3}$/),
+}).strict();
+
+export const sellableCatalogItemSchema = z.object({
+  sku: z.string().trim().min(1).max(128).regex(/^[a-zA-Z0-9._:-]+$/),
+  title: z.string().trim().min(1).max(160),
+  unitPrice: sellableCatalogMoneySchema,
+  permittedPurchaseModes: z.array(z.enum(["one_time", "subscription"])).min(1).max(2),
+}).strict();
+
+export const sellableCatalogProfileSchema = z.object({
+  id: z.string().trim().min(1).max(120),
+  brand: z.string().trim().min(1).max(160),
+  country: z.string().regex(/^[A-Z]{2}$/),
+  currency: z.string().regex(/^[A-Z]{3}$/),
+  locale: z.string().trim().min(2).max(35),
+  timezone: z.string().trim().min(1).max(80),
+}).strict();
+
+export const sellableCatalogListResponseSchema = z.object({
+  contractVersion: z.literal(SELLABLE_CATALOG_CONTRACT_VERSION),
+  profile: sellableCatalogProfileSchema,
+  items: z.array(sellableCatalogItemSchema).min(1),
+}).strict();
+

package/src/catalog/sql.ts

@@ -0,0 +1,14 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const BUNDLE_MIGRATIONS = [
+  { id: "20260812140000_sellable_bundle_catalog", catalogPath: "db/platform/migrations/20260812140000_sellable_bundle_catalog.sql", position: 16, sha256: "62fbf0910a3a7a2ee47e2d798933fe0a5a273fd1242cae7cc78ff237ba39e394", url: new URL("../../sql/20260812140000_sellable_bundle_catalog.sql", import.meta.url) },
+  { id: "20260812210000_bundle_operator_write_boundary", catalogPath: "db/platform/migrations/20260812210000_bundle_operator_write_boundary.sql", position: 19, sha256: "d0ec6674d7eedf4cd3ce0d8ccd7345ebe2f93da635316a68a6bd178ec55b2679", url: new URL("../../sql/20260812210000_bundle_operator_write_boundary.sql", import.meta.url) },
+] as const;
+
+/** Catalog foundation projections; install the complete canonical catalogue. */
+export const CATALOG_MIGRATIONS = [
+  { id: "20260807140000_read_parity_catalog", catalogPath: "db/platform/migrations/20260807140000_read_parity_catalog.sql", position: 1, sha256: "fcf3827028c1651ae42a7c7d7472153825a3121c936d58a3d105befc7dece9ea", url: new URL("../../sql/20260807140000_read_parity_catalog.sql", import.meta.url) },
+  { id: "20260810120000_storefront_catalog_attributes", catalogPath: "db/platform/migrations/20260810120000_storefront_catalog_attributes.sql", position: 8, sha256: "2bf938f5d0076193557bea834f86dbd9bcb7f3e2de00f99fb91cc1229b93a14b", url: new URL("../../sql/20260810120000_storefront_catalog_attributes.sql", import.meta.url) },
+  { id: "20260827220000_catalog_document_revision_foundation", catalogPath: "db/platform/migrations/20260827220000_catalog_document_revision_foundation.sql", position: 58, sha256: "715e74d655b76d35b8a49e0d2a5625594a6c4856863f369cd1eadcd1fb1ae90e", url: new URL("../../sql/20260827220000_catalog_document_revision_foundation.sql", import.meta.url) },
+  { id: "20260827220001_catalog_document_revision_foundation_validate", catalogPath: "db/platform/migrations/20260827220001_catalog_document_revision_foundation_validate.sql", position: 59, sha256: "f3cd7fb61dcebac1cf0468cf2d7c1f9dd036817ab0094c72864266e307b269de", url: new URL("../../sql/20260827220001_catalog_document_revision_foundation_validate.sql", import.meta.url) },
+  { id: "20260908100000_catalog_draft_foundation", catalogPath: "db/platform/migrations/20260908100000_catalog_draft_foundation.sql", position: 61, sha256: "ac0d614cdb2874df8fbdbbbda4f9455986ef95241fe1334b0b54a1fa6478ab2e", url: new URL("../../sql/20260908100000_catalog_draft_foundation.sql", import.meta.url) },
+] as const;

package/src/catalog/validation.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/src/communications/accountingDocumentDelivery.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+
+/**
+ * The sealed transport boundary for handing an accounting document to its recipient.
+ *
+ * The kernel exercises the whole capability up to this line: a document is owed, registered with
+ * whatever authority the market has, queued, claimed and settled against a receipt. What crosses
+ * the line is one opaque hand-off, and this adapter is the deliberately inert implementation of
+ * it -- deterministic, and leaving the installation by no route at all.
+ *
+ * It is FAIL CLOSED, and that is the whole design. An installation that has declared no delivery
+ * channel gets a refusal, never a silent success: a boundary whose default answer is "fine" is
+ * how a deployment discovers months later that nothing was ever handed to anyone.
+ */
+export type CapturedDocumentDeliveryCommand = {
+  readonly deliveryId: string;
+  readonly recipientReference: string;
+};
+
+export type CapturedDocumentDeliveryPort = {
+  deliver(command: CapturedDocumentDeliveryCommand): Promise<{ readonly receiptReference: string }>;
+};
+
+export type CapturedDocumentDeliveryResolution =
+  | { readonly port: CapturedDocumentDeliveryPort; readonly refused?: undefined }
+  | { readonly port?: undefined; readonly refused: string };
+
+/** The one marker that opens the boundary. Anything else, including its absence, is a refusal. */
+export const CAPTURED_DOCUMENT_DELIVERY_CHANNEL = "captured";
+const CHANNEL_KEY = "PLATFORM_DOCUMENT_DELIVERY_CHANNEL";
+
+const reference = (command: CapturedDocumentDeliveryCommand): string =>
+  `captured:${createHash("sha256")
+    .update(`${command.deliveryId}::${command.recipientReference}`)
+    .digest("hex")
+    .slice(0, 32)}`;
+
+/**
+ * Resolve the boundary for one installation. The environment is the only input, and every path
+ * that is not an explicit declaration of the captured channel ends in a named refusal.
+ */
+export function resolveCapturedDocumentDelivery(
+  env: Record<string, string | undefined>,
+): CapturedDocumentDeliveryResolution {
+  const declared = env[CHANNEL_KEY]?.trim().toLowerCase() ?? "";
+  if (declared === "") return { refused: "document_delivery_channel_undeclared" };
+  if (declared !== CAPTURED_DOCUMENT_DELIVERY_CHANNEL) {
+    return { refused: "document_delivery_channel_unsupported" };
+  }
+  return {
+    port: {
+      async deliver(command) {
+        if (typeof command.deliveryId !== "string" || command.deliveryId.trim() === "") {
+          throw new Error("document_delivery_command_invalid");
+        }
+        if (typeof command.recipientReference !== "string" || command.recipientReference.trim() === "") {
+          throw new Error("document_delivery_recipient_missing");
+        }
+        return { receiptReference: reference(command) };
+      },
+    },
+  };
+}

package/src/communications/authEmailError.ts

@@ -0,0 +1,10 @@
+/** Typed refusal used by public/default composition when product copy is absent. */
+export class AuthEmailContentUnavailableError extends Error {
+  readonly code = "auth_email_content_unavailable";
+
+  constructor() {
+    super("Auth email content unavailable");
+    this.name = "AuthEmailContentUnavailableError";
+  }
+}
+

package/src/communications/authEmailPorts.ts

@@ -0,0 +1,2 @@
+export type * from "./contracts/authEmail.js";
+export { AuthEmailContentUnavailableError } from "./authEmailError.js";