@openlup/platform 0.17.0 → 0.19.0

package/src/catalog/catalogSkuEnvelope.ts

@@ -0,0 +1,214 @@
+import {
+  CatalogSkuAuthorityError,
+  catalogSkuEnvelopeSelectorSchema,
+  type CatalogSkuEnvelopeSelector,
+  type NeutralSkuEnvelopeV1,
+} from "./foundationSchemas.js";
+import { parseCatalogActiveSkuSelection } from "./activeSkuSelection.js";
+import type {
+  CatalogActiveSkuEnvelopeListQuery,
+  CatalogSkuEnvelopeListQuery,
+  CatalogSkuEnvelopePage,
+  PublicCatalogSkuEnvelopeReadPort,
+} from "./readPorts.js";
+import type { PgQueryExecutor } from "../data/index.js";
+import {
+  mapPostgresCatalogSkuEnvelope,
+  readPostgresCatalogSkuIdentifiers,
+  requirePostgresCatalogSkuEnvelopeRow,
+  type PostgresCatalogSkuEnvelopeRow,
+} from "./catalogSkuEnvelopeMapper.js";
+
+const ENVELOPE_COLUMNS_SQL = `
+    product.id AS product_id,
+    product.slug AS product_slug,
+    product.primary_sku_id,
+    product.current_document_revision_id,
+    sku.id AS sku_id,
+    sku.product_id AS sku_product_id,
+    sku.sku AS sku_code,
+    sku.net_weight_g AS net_content_unscaled,
+    sku.status AS sku_status,
+    sku.sellable_standalone AS sellable_one_time,
+    sku.sellable_in_subscription AS sellable_subscription,
+    sku.is_addon,
+    sku.asset_ref,
+    revision.id AS document_revision_id,
+    revision.product_id AS document_product_id,
+    revision.revision_no AS document_revision_no,
+    revision.schema_id AS document_schema_id,
+    revision.document_ref AS document_ref,
+    revision.source_ref AS document_source_ref,
+    revision.digest AS document_digest`;
+
+const SKU_ENVELOPE_FROM_SQL = `
+  SELECT ${ENVELOPE_COLUMNS_SQL}
+  FROM public.catalog_skus AS sku
+  JOIN public.catalog_products AS product
+    ON product.id = sku.product_id
+  LEFT JOIN public.catalog_product_document_revisions AS revision
+    ON revision.id = product.current_document_revision_id`;
+
+const LIST_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE ($1::uuid IS NULL OR sku.id > $1::uuid)
+  ORDER BY sku.id
+  LIMIT $2::integer`;
+
+const LIST_ACTIVE_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.status = 'active'
+    AND (sku.sellable_standalone OR sku.sellable_in_subscription)
+    AND ($3::text[] IS NULL OR sku.sku = ANY($3::text[]))
+    AND ($1::uuid IS NULL OR sku.id > $1::uuid)
+  ORDER BY sku.id
+  LIMIT $2::integer`;
+
+const LIST_PUBLIC_ACTIVE_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.status = 'active'
+    AND ($1::uuid IS NULL OR sku.id > $1::uuid)
+  ORDER BY sku.id
+  LIMIT $2::integer`;
+
+const LIST_PUBLIC_ACTIVE_PRODUCT_ENVELOPES_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.product_id = $1::uuid
+    AND sku.status = 'active'
+    AND ($2::uuid IS NULL OR sku.id > $2::uuid)
+  ORDER BY sku.id
+  LIMIT $3::integer`;
+
+const DETAIL_ENVELOPE_BY_ID_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.id = $1::uuid`;
+
+const DETAIL_ENVELOPE_BY_SKU_CODE_SQL = `${SKU_ENVELOPE_FROM_SQL}
+  WHERE sku.sku = $1
+  LIMIT 2`;
+
+const DETAIL_ENVELOPE_BY_PRIMARY_PRODUCT_SLUG_SQL = `
+  SELECT ${ENVELOPE_COLUMNS_SQL}
+  FROM public.catalog_products AS product
+  LEFT JOIN public.catalog_skus AS sku
+    ON sku.id = product.primary_sku_id
+  LEFT JOIN public.catalog_product_document_revisions AS revision
+    ON revision.id = product.current_document_revision_id
+  WHERE product.slug = $1
+  LIMIT 2`;
+
+/**
+ * Portable W2a envelope reader. It reads only product/SKU/revision references
+ * and neutral identifiers; application document content never crosses this seam.
+ */
+export function createPostgresCatalogSkuEnvelopeReadPort(
+  executor: PgQueryExecutor,
+): PublicCatalogSkuEnvelopeReadPort {
+  return {
+    async listSkuEnvelopes(query: CatalogSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage> {
+      return listEnvelopes(executor, query, LIST_ENVELOPES_SQL);
+    },
+
+    async listActiveSkuEnvelopes(query: CatalogActiveSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage> {
+      const skuCodes = parseCatalogActiveSkuSelection(query.skuCodes);
+      return listEnvelopes(executor, query, LIST_ACTIVE_ENVELOPES_SQL, [], [skuCodes ?? null]);
+    },
+
+    async listPublicActiveSkuEnvelopes(query: CatalogSkuEnvelopeListQuery): Promise<CatalogSkuEnvelopePage> {
+      return listEnvelopes(executor, query, LIST_PUBLIC_ACTIVE_ENVELOPES_SQL);
+    },
+
+    async listPublicActiveProductSkuEnvelopes(
+      productId: string,
+      query: CatalogSkuEnvelopeListQuery,
+    ): Promise<CatalogSkuEnvelopePage> {
+      return listEnvelopes(executor, query, LIST_PUBLIC_ACTIVE_PRODUCT_ENVELOPES_SQL, [productId]);
+    },
+
+    async getSkuEnvelope(selector: CatalogSkuEnvelopeSelector): Promise<NeutralSkuEnvelopeV1 | null> {
+      const parsed = catalogSkuEnvelopeSelectorSchema.parse(selector);
+      const rows = await readRows(
+        executor,
+        parsed.kind === "sku_code"
+          ? DETAIL_ENVELOPE_BY_SKU_CODE_SQL
+          : DETAIL_ENVELOPE_BY_PRIMARY_PRODUCT_SLUG_SQL,
+        [parsed.kind === "sku_code" ? parsed.skuCode : parsed.productSlug],
+      );
+      const row = uniqueDetailRow(
+        rows,
+        parsed.kind === "sku_code"
+          ? "catalog_sku_authority_sku_absent"
+          : "catalog_sku_authority_product_absent",
+      );
+      requirePostgresCatalogSkuEnvelopeRow(
+        row,
+        parsed.kind === "primary_product_slug"
+          ? "catalog_sku_authority_primary_sku_invalid"
+          : "catalog_sku_authority_current_document_invalid",
+      );
+      if (
+        parsed.kind === "primary_product_slug"
+        && (row.primary_sku_id !== row.sku_id || row.product_id !== row.sku_product_id)
+      ) {
+        throw new CatalogSkuAuthorityError("catalog_sku_authority_primary_sku_invalid");
+      }
+      const identifiers = await readPostgresCatalogSkuIdentifiers(executor, [row.sku_id]);
+      return mapPostgresCatalogSkuEnvelope(row, identifiers.get(row.sku_id) ?? []);
+    },
+
+    async getSkuEnvelopeById(skuId: string): Promise<NeutralSkuEnvelopeV1 | null> {
+      const row = uniqueDetailRow(
+        await readRows(executor, DETAIL_ENVELOPE_BY_ID_SQL, [skuId]),
+        "catalog_sku_authority_sku_absent",
+      );
+      requirePostgresCatalogSkuEnvelopeRow(row, "catalog_sku_authority_current_document_invalid");
+      const identifiers = await readPostgresCatalogSkuIdentifiers(executor, [row.sku_id]);
+      return mapPostgresCatalogSkuEnvelope(row, identifiers.get(row.sku_id) ?? []);
+    },
+  };
+}
+
+async function listEnvelopes(
+  executor: PgQueryExecutor,
+  query: CatalogSkuEnvelopeListQuery,
+  sql: string,
+  prefixValues: unknown[] = [],
+  suffixValues: unknown[] = [],
+): Promise<CatalogSkuEnvelopePage> {
+  const rows = await readRows(
+    executor,
+    sql,
+    [...prefixValues, query.cursor, checkedLimit(query.limit) + 1, ...suffixValues],
+  );
+  const pageRows = rows.slice(0, query.limit).map((row) => {
+    requirePostgresCatalogSkuEnvelopeRow(row, "catalog_sku_authority_current_document_invalid");
+    return row;
+  });
+  const identifiers = await readPostgresCatalogSkuIdentifiers(executor, pageRows.map((row) => row.sku_id));
+  return {
+    items: pageRows.map((row) => mapPostgresCatalogSkuEnvelope(row, identifiers.get(row.sku_id) ?? [])),
+    nextCursor: rows.length > query.limit ? pageRows[pageRows.length - 1]?.sku_id ?? null : null,
+  };
+}
+
+function uniqueDetailRow(
+  rows: readonly PostgresCatalogSkuEnvelopeRow[],
+  absent: CatalogSkuAuthorityError["code"],
+): PostgresCatalogSkuEnvelopeRow {
+  if (rows.length === 0) throw new CatalogSkuAuthorityError(absent);
+  if (rows.length !== 1) {
+    throw new CatalogSkuAuthorityError("catalog_sku_authority_selector_ambiguous");
+  }
+  return rows[0]!;
+}
+
+async function readRows(
+  executor: PgQueryExecutor,
+  sql: string,
+  values: unknown[],
+): Promise<PostgresCatalogSkuEnvelopeRow[]> {
+  const { rows } = await executor.query(sql, values);
+  return rows as unknown as PostgresCatalogSkuEnvelopeRow[];
+}
+
+function checkedLimit(limit: number): number {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500) {
+    throw new RangeError("catalog_sku_envelope_invalid_limit");
+  }
+  return limit;
+}

package/src/catalog/catalogSkuEnvelopeMapper.ts

@@ -0,0 +1,160 @@
+import {
+  CATALOG_FOUNDATION_CONTRACT_VERSION,
+  CatalogSkuAuthorityError,
+  assertPrimaryUnitGtinAuthority,
+  neutralSkuEnvelopeV1Schema,
+  requireCurrentCatalogDocumentAuthority,
+  type CatalogSkuIdentifier,
+  type NeutralSkuEnvelopeV1,
+} from "./foundationSchemas.js";
+import type { PgQueryExecutor } from "../data/index.js";
+
+const IDENTIFIERS_SQL = `
+  SELECT catalog_sku_id, issuer, identifier_kind, normalized_value,
+    pack_kind, quantity, is_primary
+  FROM public.catalog_sku_identifiers
+  WHERE catalog_sku_id = ANY($1::uuid[])
+  ORDER BY catalog_sku_id, identifier_kind, is_primary DESC, issuer, normalized_value`;
+
+export interface PostgresCatalogSkuEnvelopeRow {
+  product_id: string;
+  product_slug: string;
+  primary_sku_id: string | null;
+  current_document_revision_id: string | null;
+  sku_id: string | null;
+  sku_product_id: string | null;
+  sku_code: string | null;
+  net_content_unscaled: number | null;
+  sku_status: "draft" | "active" | "archived" | null;
+  sellable_one_time: boolean | null;
+  sellable_subscription: boolean | null;
+  is_addon: boolean | null;
+  asset_ref: string | null;
+  document_revision_id: string | null;
+  document_product_id: string | null;
+  document_revision_no: number | null;
+  document_schema_id: string | null;
+  document_ref: string | null;
+  document_source_ref: string | null;
+  document_digest: string | null;
+}
+
+interface IdentifierRow {
+  catalog_sku_id: string;
+  issuer: string;
+  identifier_kind: "gtin" | "other";
+  normalized_value: string;
+  pack_kind: "unit" | "collective";
+  quantity: number;
+  is_primary: boolean;
+}
+
+export type CompletePostgresCatalogSkuEnvelopeRow = PostgresCatalogSkuEnvelopeRow & {
+  primary_sku_id: string;
+  sku_id: string;
+  sku_product_id: string;
+  sku_code: string;
+  net_content_unscaled: number;
+  sku_status: "draft" | "active" | "archived";
+  sellable_one_time: boolean;
+  sellable_subscription: boolean;
+  is_addon: boolean;
+};
+
+export function requirePostgresCatalogSkuEnvelopeRow(
+  row: PostgresCatalogSkuEnvelopeRow,
+  refusal: CatalogSkuAuthorityError["code"],
+): asserts row is CompletePostgresCatalogSkuEnvelopeRow {
+  if (!row.primary_sku_id) {
+    throw new CatalogSkuAuthorityError("catalog_sku_authority_primary_sku_invalid");
+  }
+  if (
+    !row.sku_id
+    || !row.sku_product_id
+    || !row.sku_code
+    || row.net_content_unscaled === null
+    || row.sku_status === null
+    || row.sellable_one_time === null
+    || row.sellable_subscription === null
+    || row.is_addon === null
+  ) {
+    throw new CatalogSkuAuthorityError(refusal);
+  }
+}
+
+export async function readPostgresCatalogSkuIdentifiers(
+  executor: PgQueryExecutor,
+  skuIds: string[],
+): Promise<Map<string, CatalogSkuIdentifier[]>> {
+  if (skuIds.length === 0) return new Map();
+  const { rows } = await executor.query(IDENTIFIERS_SQL, [skuIds]);
+  const grouped = new Map<string, CatalogSkuIdentifier[]>();
+  for (const row of rows as unknown as IdentifierRow[]) {
+    const identifiers = grouped.get(row.catalog_sku_id) ?? [];
+    identifiers.push({
+      issuer: row.issuer,
+      normalizedValue: row.normalized_value,
+      kind: row.identifier_kind,
+      packKind: row.pack_kind,
+      packQuantity: row.quantity,
+      isPrimary: row.is_primary,
+    });
+    grouped.set(row.catalog_sku_id, identifiers);
+  }
+  return grouped;
+}
+
+export function mapPostgresCatalogSkuEnvelope(
+  row: CompletePostgresCatalogSkuEnvelopeRow,
+  identifiers: CatalogSkuIdentifier[],
+): NeutralSkuEnvelopeV1 {
+  assertPrimaryUnitGtinAuthority(identifiers);
+  const revision = requireCurrentCatalogDocumentAuthority(
+    row.product_id,
+    row.current_document_revision_id,
+    row.document_revision_id
+      && row.document_product_id
+      && row.document_revision_no !== null
+      && row.document_schema_id
+      && row.document_ref
+      && row.document_source_ref
+      && row.document_digest
+      ? {
+        id: row.document_revision_id,
+        productId: row.document_product_id,
+        revisionNo: row.document_revision_no,
+        schemaId: row.document_schema_id,
+        documentRef: row.document_ref,
+        sourceRef: row.document_source_ref,
+        digest: row.document_digest,
+      }
+      : null,
+  );
+  return neutralSkuEnvelopeV1Schema.parse({
+    contractVersion: CATALOG_FOUNDATION_CONTRACT_VERSION,
+    product: { id: row.product_id, slug: row.product_slug, primarySkuId: row.primary_sku_id },
+    sku: {
+      id: row.sku_id,
+      productId: row.sku_product_id,
+      code: row.sku_code,
+      netContent: { unscaled: row.net_content_unscaled, scale: 0, unit: "GRAM" },
+      sellability: {
+        status: row.sku_status,
+        oneTime: row.sellable_one_time,
+        subscription: row.sellable_subscription,
+      },
+      isAddon: row.is_addon,
+      assetRef: row.asset_ref,
+    },
+    documentRevision: {
+      id: revision.id,
+      productId: revision.productId,
+      revisionNo: revision.revisionNo,
+      schemaId: revision.schemaId,
+      documentRef: revision.documentRef,
+      sourceRef: revision.sourceRef,
+      digest: revision.digest,
+    },
+    identifiers,
+  });
+}

package/src/catalog/contracts/bundleAdmin.ts

@@ -0,0 +1,20 @@
+/** Plain bundle transport DTOs. The host owns parsing, defaults and wire-version values. */
+export type CreateBundleDraftRequest = { bundle: { code: string; title: string; fulfillmentMode: "virtual" | "kitted"; compositionConstraint?: { kind: string; version: number; data: Record<string, unknown>; } | undefined; metadata?: Record<string, unknown> | undefined; }; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type CreateBundleDraftResponse = { code: string; bundleId: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type UpdateBundleDraftRequest = { code: string; updates: { title?: string | undefined; fulfillmentMode?: "virtual" | "kitted" | undefined; compositionConstraint?: { kind: string; version: number; data: Record<string, unknown>; } | undefined; metadata?: Record<string, unknown> | undefined; }; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type UpdateBundleDraftResponse = { code: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type BundleComponent = { sku: string; quantity: number; isAddon: boolean; sortOrder: number; };
+export type SetBundleCompositionRequest = { code: string; components: { sku: string; quantity: number; isAddon: boolean; sortOrder: number; }[]; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type SetBundleCompositionResponse = { code: string; componentCount: number; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type SetBundleTargetPriceRequest = { code: string; price: { mode: "any" | "one_time" | "subscription"; targetPriceMinor: number; currency: string; amountKind: "gross" | "net"; }; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type SetBundleTargetPriceResponse = { code: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type ArchiveBundleRequest = { code: string; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type ArchiveBundleResponse = { code: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type RestoreBundleRequest = { code: string; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type RestoreBundleResponse = { code: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type CloneBundleDraftRequest = { sourceCode: string; code: string; mode: "commit" | "dry_run"; title?: string | undefined; idempotencyKey?: string | undefined; };
+export type CloneBundleDraftResponse = { code: string; bundleId: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type ActivateBundleRequest = { code: string; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type ActivateBundleResponse = { code: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };
+export type DeactivateBundleRequest = { code: string; mode: "commit" | "dry_run"; idempotencyKey?: string | undefined; };
+export type DeactivateBundleResponse = { code: string; contractVersion: "commerce.v0"; dryRun: boolean; idempotent: boolean; };

package/src/catalog/contracts/bundleAvailability.ts

@@ -0,0 +1,5 @@
+/** Plain bundle transport DTOs. The host owns parsing, defaults and wire-version values. */
+export type SellableBundle = { code: string; title: string; fulfillmentMode: string; price: { amountMinor: number; currency: string; }; components: { sku: string; quantity: number; effectiveUnitPriceMinor: number; lineSubtotalMinor: number; discountBps: number; }[]; availability: { status: "unknown" | "available" | "low_stock" | "out_of_stock"; sellableNow: number | null; limitingSku: string | null; reasonCode: string; }; };
+export type SellableBundleComponent = { sku: string; quantity: number; effectiveUnitPriceMinor: number; lineSubtotalMinor: number; discountBps: number; };
+export type SellableBundleAvailability = { status: "unknown" | "available" | "low_stock" | "out_of_stock"; sellableNow: number | null; limitingSku: string | null; reasonCode: string; };
+export type SellableBundleListResponse = { contractVersion: "catalog.sellable-bundle.v1"; bundles: { code: string; title: string; fulfillmentMode: string; price: { amountMinor: number; currency: string; }; components: { sku: string; quantity: number; effectiveUnitPriceMinor: number; lineSubtotalMinor: number; discountBps: number; }[]; availability: { status: "unknown" | "available" | "low_stock" | "out_of_stock"; sellableNow: number | null; limitingSku: string | null; reasonCode: string; }; }[]; };

package/src/catalog/contracts/bundleRead.ts

@@ -0,0 +1,13 @@
+/** Plain bundle transport DTOs. The host owns parsing, defaults and wire-version values. */
+export type ListBundlesRequest = { limit: number; offset: number; status: "draft" | "active" | "archived" | "all"; query?: string | undefined; };
+export type ListBundlesResponse = { bundles: { code: string; title: string; status: string; fulfillmentMode: string; componentCount: number; hasActiveTargetPrice: boolean; updatedAt: string; }[]; total: number; contractVersion: "commerce.v0"; };
+export type BundleSummaryView = { code: string; title: string; status: string; fulfillmentMode: string; componentCount: number; hasActiveTargetPrice: boolean; updatedAt: string; };
+export type GetBundleRequest = { code: string; currency?: string | undefined; mode?: "any" | "one_time" | "subscription" | undefined; };
+export type GetBundleResponse = { bundle: { code: string; title: string; status: string; fulfillmentMode: string; componentCount: number; hasActiveTargetPrice: boolean; updatedAt: string; compositionConstraint: { kind: string; version: number; data: Record<string, unknown>; } | null; metadata: Record<string, unknown>; components: { sku: string; title: string | null; productSlug: string; quantity: number; isAddon: boolean; sortOrder: number; referenceUnitPriceMinor: number | null; }[]; prices: { mode: string; targetPriceMinor: number; currency: string; amountKind: string; active: boolean; validFrom: string; validTo: string | null; }[]; resolvedTargetPrice?: { mode: string; targetPriceMinor: number; currency: string; amountKind: string; active: boolean; validFrom: string; validTo: string | null; } | null; resolvedCurrency: string | null; availability: { sellableNow: number | null; status: string; reasonCode: string; limitingSku: string | null; components: { sku: string; quantity: number; isAddon: boolean; sellableNow: number | null; }[]; } | null; }; contractVersion: "commerce.v0"; };
+export type BundleDetailView = { code: string; title: string; status: string; fulfillmentMode: string; componentCount: number; hasActiveTargetPrice: boolean; updatedAt: string; compositionConstraint: { kind: string; version: number; data: Record<string, unknown>; } | null; metadata: Record<string, unknown>; components: { sku: string; title: string | null; productSlug: string; quantity: number; isAddon: boolean; sortOrder: number; referenceUnitPriceMinor: number | null; }[]; prices: { mode: string; targetPriceMinor: number; currency: string; amountKind: string; active: boolean; validFrom: string; validTo: string | null; }[]; resolvedTargetPrice?: { mode: string; targetPriceMinor: number; currency: string; amountKind: string; active: boolean; validFrom: string; validTo: string | null; } | null; resolvedCurrency: string | null; availability: { sellableNow: number | null; status: string; reasonCode: string; limitingSku: string | null; components: { sku: string; quantity: number; isAddon: boolean; sellableNow: number | null; }[]; } | null; };
+export type BundleAvailabilityView = { sellableNow: number | null; status: string; reasonCode: string; limitingSku: string | null; components: { sku: string; quantity: number; isAddon: boolean; sellableNow: number | null; }[]; };
+export type BundleHistoryRequest = { limit: number; offset: number; code: string; };
+export type BundleHistoryResponse = { events: { id: string; action: string; actorKind: string | null; actorEmail: string | null; entityId: string | null; oldValue: unknown; newValue: unknown; occurredAt: string; }[]; total: number; contractVersion: "commerce.v0"; };
+export type PreviewBundlePriceRequest = { code: string; currency?: string | undefined; mode?: "any" | "one_time" | "subscription" | undefined; targetPriceMinor?: number | undefined; };
+export type PreviewBundlePriceResponse = { preview: { bundleCode: string; priceListId: string; mode: string; currency: string; referenceTotalMinor: number; targetPriceMinor: number; discountTotalMinor: number; discountBps: number; floorApplied: boolean; componentTargets: { sku: string; quantity: number; referenceUnitPriceMinor: number; referenceSubtotalMinor: number; targetSubtotalMinor: number; discountAllocatedMinor: number; discountBps: number; hasSplitPricing: boolean; }[]; allocatedLines: { sku: string; quantity: number; effectiveUnitPriceMinor: number; lineSubtotalMinor: number; }[]; }; contractVersion: "commerce.v0"; };
+export type BundlePricePreview = { bundleCode: string; priceListId: string; mode: string; currency: string; referenceTotalMinor: number; targetPriceMinor: number; discountTotalMinor: number; discountBps: number; floorApplied: boolean; componentTargets: { sku: string; quantity: number; referenceUnitPriceMinor: number; referenceSubtotalMinor: number; targetSubtotalMinor: number; discountAllocatedMinor: number; discountBps: number; hasSplitPricing: boolean; }[]; allocatedLines: { sku: string; quantity: number; effectiveUnitPriceMinor: number; lineSubtotalMinor: number; }[]; };

package/src/catalog/contracts/draft.ts

@@ -0,0 +1,69 @@
+import type { CatalogDocumentRevisionRef } from "./foundation.js";
+import type { CatalogProductTypeRef, CatalogOptionValue, CatalogQuantity } from "./productTypes.js";
+export const CATALOG_DRAFT_MAX_BYTES = 1_048_576;
+export const CATALOG_DRAFT_MAX_PAGE = 100;
+export interface CatalogDraftPayload {
+  schemaVersion: 1;
+  product: {
+    id: string; type: CatalogProductTypeRef; slug?: string; primarySkuId?: string;
+    dimensions: string[]; sharedContent?: unknown; documentRevision?: CatalogDocumentRevisionRef;
+  };
+  skus: {
+    id: string; productId: string; code?: string; options: Record<string, CatalogOptionValue>;
+    netContent?: CatalogQuantity;
+    identifiers?: { scheme: string; issuer: string; value: string; packagingLevel: "unit" | "case"; quantity?: number }[];
+    assetRefs?: string[]; grossMass?: CatalogQuantity; priceRef?: string; logisticsRef?: string;
+  }[];
+}
+export interface CatalogDraftCommand {
+  schemaVersion: 1; action: "create" | "revise" | "abandon";
+  draftId: string; commandKey: string; expectedRevision: number; payload?: CatalogDraftPayload;
+}
+export interface CatalogDraftSummary {
+  draftId: string; productId: string; revision: number; status: "open" | "abandoned";
+  commandKey: string; fingerprint: string; actorId: string; createdAt: string;
+}
+export interface CatalogDraftRecord extends CatalogDraftSummary { payload: CatalogDraftPayload }
+export interface CatalogDraftPage { items: CatalogDraftSummary[]; nextCursor: string | null }
+export interface CatalogDraftRefusal {
+  outcome: "conflict" | "validation_issue" | "unauthorized" | "dependency_unavailable";
+  reason: string; currentRevision?: number;
+}
+export type CatalogDraftApplyResult = { outcome: "committed" | "replayed"; record: CatalogDraftRecord } | CatalogDraftRefusal;
+export interface CatalogDraftGetQuery { draftId: string; revision?: number; commandKey?: string }
+export interface CatalogDraftListQuery { afterDraftId?: string; limit: number }
+
+/** Reject lossy JSON inputs, prototype keys and excessive recursion before validation or hashing. */
+export function canonicalCatalogDraftJson(input: unknown): string {
+  const ancestors = new Set<object>();
+  function visit(value: unknown, depth: number): unknown {
+    if (depth > 48) throw new Error("draft_json_depth");
+    if (typeof value === "string") {
+      if (value.includes("\u0000") || /[\uD800-\uDFFF]/u.test(value)) throw new Error("draft_json_invalid");
+      return value;
+    }
+    if (value === null || typeof value === "boolean") return value;
+    if (typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0)) return value;
+    if (typeof value !== "object" || ancestors.has(value)) throw new Error("draft_json_invalid");
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new Error("draft_json_invalid");
+    ancestors.add(value);
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== "string" || ["__proto__", "constructor", "prototype"].includes(key))) throw new Error("draft_json_invalid");
+    for (const key of keys) {
+      visit(key, depth + 1);
+      if (Object.getOwnPropertyDescriptor(value, key)?.get || Object.getOwnPropertyDescriptor(value, key)?.set) throw new Error("draft_json_invalid");
+    }
+    let result: unknown;
+    if (Array.isArray(value)) {
+      if (keys.length !== value.length + 1) throw new Error("draft_json_invalid");
+      result = Array.from(value, (item) => visit(item, depth + 1));
+    } else {
+      result = Object.fromEntries((keys as string[]).sort().map((key) => [key, visit((value as Record<string, unknown>)[key], depth + 1)]));
+    }
+    ancestors.delete(value);
+    return result;
+  }
+  const text = JSON.stringify(visit(input, 0));
+  if (new TextEncoder().encode(text).byteLength > CATALOG_DRAFT_MAX_BYTES) throw new Error("draft_payload_too_large");
+  return text;
+}

package/src/catalog/contracts/foundation.ts

@@ -0,0 +1,104 @@
+/** Portable, payload-free catalog references and identifier authority. */
+export const CATALOG_FOUNDATION_CONTRACT_VERSION = "catalog.foundation.v1";
+export interface CatalogDocumentRevisionRef {
+  id: string; productId: string; revisionNo: number; schemaId: string;
+  documentRef: string; sourceRef: string; digest: string;
+}
+export interface CatalogSkuIdentifier {
+  issuer: string; normalizedValue: string; kind: "gtin" | "other";
+  packKind: "unit" | "collective"; packQuantity: number; isPrimary: boolean;
+}
+export type CatalogSkuEnvelopeSelector =
+  | { kind: "sku_code"; skuCode: string }
+  | { kind: "primary_product_slug"; productSlug: string };
+export interface NeutralSkuEnvelopeV1 {
+  contractVersion: typeof CATALOG_FOUNDATION_CONTRACT_VERSION;
+  product: { id: string; slug: string; primarySkuId: string };
+  sku: {
+    id: string; productId: string; code: string;
+    netContent: { unscaled: number; scale: number; unit: string };
+    sellability: { status: "draft" | "active" | "archived"; oneTime: boolean; subscription: boolean };
+    isAddon: boolean; assetRef: string | null;
+  };
+  documentRevision: CatalogDocumentRevisionRef; identifiers: CatalogSkuIdentifier[];
+}
+export interface CatalogPriceContext {
+  priceListId: string; regionCode: string; currency: string; channel: string; atTime: string;
+}
+
+/** Refusal vocabulary shared by managed and portable catalog readers. */
+export type CatalogSkuAuthorityRefusal =
+  | "catalog_sku_authority_sku_absent"
+  | "catalog_sku_authority_product_absent"
+  | "catalog_sku_authority_primary_sku_invalid"
+  | "catalog_sku_authority_selector_ambiguous"
+  | "catalog_sku_authority_current_document_absent"
+  | "catalog_sku_authority_current_document_invalid"
+  | "catalog_sku_identifier_authority_absent"
+  | "catalog_sku_identifier_authority_ambiguous"
+  | "catalog_sku_identifier_authority_invalid";
+
+export class CatalogSkuAuthorityError extends Error {
+  constructor(readonly code: CatalogSkuAuthorityRefusal) {
+    super(code);
+    this.name = "CatalogSkuAuthorityError";
+  }
+}
+
+/** Accepts only GS1 GTIN-8/12/13/14 values with a valid modulo-10 check digit. */
+export function isValidGtin(value: string): boolean {
+  if (!/^\d{8}$|^\d{12}$|^\d{13}$|^\d{14}$/u.test(value)) return false;
+  const digits = [...value].map(Number);
+  const checkDigit = digits.pop();
+  if (checkDigit === undefined) return false;
+  const weighted = digits.reverse().reduce(
+    (sum, digit, index) => sum + digit * (index % 2 === 0 ? 3 : 1),
+    0,
+  );
+  return (weighted + checkDigit) % 10 === 0;
+}
+
+/**
+ * Makes a read adapter fail closed when source rows cannot state one valid,
+ * primary unit GTIN. The neutral envelope itself remains payload and DB agnostic.
+ */
+export function assertPrimaryUnitGtinAuthority(
+  identifiers: readonly CatalogSkuIdentifier[],
+): void {
+  const primary = identifiers.filter((identifier) => identifier.isPrimary);
+  if (primary.length === 0) {
+    throw new CatalogSkuAuthorityError("catalog_sku_identifier_authority_absent");
+  }
+  if (primary.length !== 1) {
+    throw new CatalogSkuAuthorityError("catalog_sku_identifier_authority_ambiguous");
+  }
+  const [identifier] = primary;
+  if (
+    identifier.kind !== "gtin"
+    || identifier.packKind !== "unit"
+    || identifier.packQuantity !== 1
+    || !isValidGtin(identifier.normalizedValue)
+  ) {
+    throw new CatalogSkuAuthorityError("catalog_sku_identifier_authority_invalid");
+  }
+}
+
+/** Returns the product-scoped revision only when the declared current authority is sound. */
+export function requireCurrentCatalogDocumentAuthority<T extends { id: string; productId: string }>(
+  productId: string,
+  currentDocumentRevisionId: string | null,
+  revision: T | null | undefined,
+): T {
+  if (currentDocumentRevisionId === null) {
+    throw new CatalogSkuAuthorityError("catalog_sku_authority_current_document_absent");
+  }
+  if (
+    !revision
+    || revision.id !== currentDocumentRevisionId
+    || revision.productId !== productId
+  ) {
+    throw new CatalogSkuAuthorityError("catalog_sku_authority_current_document_invalid");
+  }
+  return revision;
+}
+

package/src/catalog/contracts/index.ts

@@ -0,0 +1,14 @@
+export { CATALOG_DRAFT_MAX_BYTES, CATALOG_DRAFT_MAX_PAGE, canonicalCatalogDraftJson } from "./draft.js";
+export type { CatalogDraftPayload, CatalogDraftCommand, CatalogDraftSummary, CatalogDraftRecord, CatalogDraftPage, CatalogDraftRefusal, CatalogDraftApplyResult, CatalogDraftGetQuery, CatalogDraftListQuery } from "./draft.js";
+export { CATALOG_FOUNDATION_CONTRACT_VERSION, CatalogSkuAuthorityError, isValidGtin, assertPrimaryUnitGtinAuthority, requireCurrentCatalogDocumentAuthority } from "./foundation.js";
+export type { CatalogDocumentRevisionRef, CatalogSkuIdentifier, CatalogSkuEnvelopeSelector, NeutralSkuEnvelopeV1, CatalogPriceContext, CatalogSkuAuthorityRefusal } from "./foundation.js";
+export { validateCatalogQuantity, canonicalCatalogOption } from "./productTypes.js";
+export type { CatalogQuantityDimension, CatalogQuantity, CatalogOptionValue, CatalogDraftIssue, CatalogProductTypeRef, CatalogProductTypeDefinition, CatalogProductTypeRegistry } from "./productTypes.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./sellable.js";
+export type { SellableCatalogItem, SellableCatalogProfile, SellableCatalogListResponse } from "./sellable.js";
+export * from "./productMediaContracts.js";
+export { resolveProductMedia } from "./resolveProductMedia.js";
+export type { CatalogVariantState, CatalogHeadRef, CatalogLifecycleObservation, CatalogPublishCommand, CatalogPublicationReceipt, CatalogPublicationRefusal, CatalogPublicationReadResult, CatalogPublicationReceiptResult, CatalogHistoryResult } from "./lifecycle.js";
+export type { CreateBundleDraftRequest, CreateBundleDraftResponse, UpdateBundleDraftRequest, UpdateBundleDraftResponse, BundleComponent, SetBundleCompositionRequest, SetBundleCompositionResponse, SetBundleTargetPriceRequest, SetBundleTargetPriceResponse, ArchiveBundleRequest, ArchiveBundleResponse, RestoreBundleRequest, RestoreBundleResponse, CloneBundleDraftRequest, CloneBundleDraftResponse, ActivateBundleRequest, ActivateBundleResponse, DeactivateBundleRequest, DeactivateBundleResponse } from "./bundleAdmin.js";
+export type { ListBundlesRequest, ListBundlesResponse, BundleSummaryView, GetBundleRequest, GetBundleResponse, BundleDetailView, BundleAvailabilityView, BundleHistoryRequest, BundleHistoryResponse, PreviewBundlePriceRequest, PreviewBundlePriceResponse, BundlePricePreview } from "./bundleRead.js";
+export type { SellableBundle, SellableBundleComponent, SellableBundleAvailability, SellableBundleListResponse } from "./bundleAvailability.js";