@openlup/platform 0.17.0 → 0.18.0

package/dist/catalog/contracts/index.d.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";

package/dist/catalog/contracts/index.js

@@ -0,0 +1,6 @@
+export { CATALOG_DRAFT_MAX_BYTES, CATALOG_DRAFT_MAX_PAGE, canonicalCatalogDraftJson } from "./draft.js";
+export { CATALOG_FOUNDATION_CONTRACT_VERSION, CatalogSkuAuthorityError, isValidGtin, assertPrimaryUnitGtinAuthority, requireCurrentCatalogDocumentAuthority } from "./foundation.js";
+export { validateCatalogQuantity, canonicalCatalogOption } from "./productTypes.js";
+export { SELLABLE_CATALOG_CONTRACT_VERSION } from "./sellable.js";
+export * from "./productMediaContracts.js";
+export { resolveProductMedia } from "./resolveProductMedia.js";

package/dist/catalog/contracts/lifecycle.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Lifecycle observations are additive DTOs, not changes to existing wire status.
+ * SKU draft/active/archived and draft receipt open/abandoned remain unchanged.
+ * Map archived to withdrawn only where an authority establishes that meaning;
+ * abandoning a draft never implies withdrawing the active variant.
+ */
+export type CatalogVariantState = "draft" | "active" | "withdrawn";
+export interface CatalogHeadRef {
+    publicationId: string;
+    revision: number;
+    documentDigest: string;
+}
+export interface CatalogLifecycleObservation {
+    productId: string;
+    variantId: string;
+    sku: string;
+    state: CatalogVariantState;
+    variantRevision: number;
+    /** Null means known unpublished, never unknown publication lineage. */
+    publicationHead: CatalogHeadRef | null;
+    draftRef: {
+        draftId: string;
+        revision: number;
+    } | null;
+}
+export interface CatalogPublishCommand {
+    commandKey: string;
+    productId: string;
+    candidateRef: string;
+    candidateDigest: string;
+    expectedHead: CatalogHeadRef | null;
+    changes: readonly {
+        variantId: string;
+        expectedRevision: number;
+        state: "active" | "withdrawn";
+    }[];
+}
+export interface CatalogPublicationReceipt {
+    commandKey: string;
+    fingerprint: string;
+    actorId: string;
+    previousHead: CatalogHeadRef | null;
+    head: CatalogHeadRef;
+    changes: readonly CatalogLifecycleObservation[];
+}
+/** Named refusals contain no arbitrary provider diagnostics. */
+export interface CatalogPublicationRefusal {
+    outcome: "unauthorized" | "validation_issue" | "conflict" | "dependency_unavailable" | "unsupported";
+    reason: "publisher_not_authorized" | "candidate_invalid" | "head_conflict" | "publication_authority_unavailable" | "publication_not_supported";
+}
+/** Success requires coherent authoritative document and lifecycle facts. */
+export type CatalogPublicationReadResult = {
+    outcome: "found";
+    head: CatalogHeadRef;
+    documentRef: string;
+    observations: readonly CatalogLifecycleObservation[];
+} | {
+    outcome: "unpublished";
+} | CatalogPublicationRefusal;
+/** Absence is distinct from an unavailable or unsupported authority. */
+export type CatalogPublicationReceiptResult = {
+    outcome: "found";
+    receipt: CatalogPublicationReceipt;
+} | {
+    outcome: "absent";
+} | CatalogPublicationRefusal;
+/**
+ * Authority-owned history, newest publication revision first with stable ordering.
+ * Limit is an integer from 1 through 100; receipts never exceed limit.
+ * nextCursor is opaque, and null only when no further page exists.
+ */
+export type CatalogHistoryResult = {
+    outcome: "page";
+    receipts: readonly CatalogPublicationReceipt[];
+    limit: number;
+    nextCursor: string | null;
+} | CatalogPublicationRefusal;

package/dist/catalog/contracts/lifecycle.js

@@ -0,0 +1 @@
+export {};

package/dist/catalog/contracts/productMediaContracts.d.ts

@@ -0,0 +1,77 @@
+/** Provider-free source metadata. Delivery URLs are supplied projections. */
+export type ProductMediaRole = "primary" | "view" | "illustration";
+export interface ProductMediaAsset {
+    assetRef: string;
+    source: string;
+    contentType: "image/jpeg" | "image/png" | "image/webp";
+    byteLength: number;
+    sha256: string;
+    artworkLocale: string | null;
+}
+export interface ProductMediaProduct {
+    productId: string;
+    variantIds: readonly string[];
+    primaryVariantId: string;
+}
+export interface ProductMediaAssociation {
+    itemId: string;
+    assetRef: string;
+    productId: string;
+    scope: "product" | "variant";
+    variantId?: string;
+    locale: string | null;
+    role: ProductMediaRole;
+    viewKey?: string;
+    order: number;
+    label: string;
+}
+export interface ProductMediaManifest {
+    schemaVersion: 1;
+    assets: readonly ProductMediaAsset[];
+    products: readonly ProductMediaProduct[];
+    associations: readonly ProductMediaAssociation[];
+}
+export interface ProductMediaRequest {
+    productId: string;
+    variantId: string;
+    locale: string;
+}
+export interface ResolvedProductMediaItem {
+    id: string;
+    assetRef: string;
+    src: string;
+    label: string;
+    role: ProductMediaRole;
+}
+export interface ResolvedProductMedia {
+    key: string;
+    revision: string;
+    items: readonly ResolvedProductMediaItem[];
+    primaryItemId: string | null;
+}
+export interface StorefrontProductMedia {
+    productId: string;
+    locale: string;
+    primaryVariantId: string;
+    collections: Readonly<Record<string, ResolvedProductMedia>>;
+}
+export declare const PRODUCT_MEDIA_LIMITS: Readonly<{
+    assets: 512;
+    products: 256;
+    variants: 1024;
+    associations: 8192;
+    imageBytes: 358400;
+    totalBytes: number;
+    manifestBytes: number;
+    resolvedItems: 32;
+}>;
+export type ProductMediaValidationCode = "invalid_schema" | "duplicate_identity" | "unsafe_path" | "undeclared_variant" | "missing_resource" | "conflicting_primary" | "collection_limit_exceeded" | "pack_limit_exceeded";
+export declare class ProductMediaValidationError extends Error {
+    readonly code: ProductMediaValidationCode;
+    readonly reference: string;
+    constructor(code: ProductMediaValidationCode, reference: string);
+}
+/** Checks contained relative resource bindings; the resource owner also checks symlinks. */
+export declare function validateProductMediaSourcePath(value: unknown): string;
+/** Structural authoring/pack validation. Signatures and digests require the source bytes. */
+export declare function validateProductMediaManifest(value: unknown): ProductMediaManifest;

package/dist/catalog/contracts/productMediaContracts.js

@@ -0,0 +1,149 @@
+export const PRODUCT_MEDIA_LIMITS = Object.freeze({
+    assets: 512, products: 256, variants: 1024, associations: 8192,
+    imageBytes: 358400, totalBytes: 128 * 1024 * 1024,
+    manifestBytes: 2 * 1024 * 1024, resolvedItems: 32,
+});
+export class ProductMediaValidationError extends Error {
+    code;
+    reference;
+    constructor(code, reference) {
+        super(`${code}: ${reference}`);
+        this.code = code;
+        this.reference = reference;
+        this.name = "ProductMediaValidationError";
+    }
+}
+function refuse(code, reference) {
+    throw new ProductMediaValidationError(code, reference);
+}
+function record(value, reference) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        refuse("invalid_schema", reference);
+    return value;
+}
+function fields(value, allowed, reference) {
+    if (Object.keys(value).some((key) => !allowed.includes(key)))
+        refuse("invalid_schema", reference);
+}
+function text(value, reference, max = 256) {
+    if (typeof value !== "string" || !value.trim() || value.length > max || Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) {
+        refuse("invalid_schema", reference);
+    }
+    return value;
+}
+function locale(value, reference) {
+    if (value !== null)
+        text(value, reference, 64);
+}
+function array(value, reference, limit) {
+    if (!Array.isArray(value))
+        refuse("invalid_schema", reference);
+    if (value.length > limit)
+        refuse("pack_limit_exceeded", reference);
+    return value;
+}
+function unique(set, id) {
+    if (set.has(id))
+        refuse("duplicate_identity", id);
+    set.add(id);
+}
+/** Checks contained relative resource bindings; the resource owner also checks symlinks. */
+export function validateProductMediaSourcePath(value) {
+    const source = text(value, "source", 512);
+    if (source.startsWith("/") || /[:\\%?#]/u.test(source) || source.split("/").some((part) => !part || part === "." || part === "..")) {
+        refuse("unsafe_path", "source");
+    }
+    return source;
+}
+/** Structural authoring/pack validation. Signatures and digests require the source bytes. */
+export function validateProductMediaManifest(value) {
+    const manifest = record(value, "manifest");
+    fields(manifest, ["schemaVersion", "assets", "products", "associations"], "manifest");
+    if (manifest.schemaVersion !== 1)
+        refuse("invalid_schema", "schemaVersion");
+    const assets = array(manifest.assets, "assets", PRODUCT_MEDIA_LIMITS.assets);
+    const products = array(manifest.products, "products", PRODUCT_MEDIA_LIMITS.products);
+    const associations = array(manifest.associations, "associations", PRODUCT_MEDIA_LIMITS.associations);
+    const assetIds = new Set();
+    let totalBytes = 0;
+    for (const entry of assets) {
+        const asset = record(entry, "asset");
+        fields(asset, ["assetRef", "source", "contentType", "byteLength", "sha256", "artworkLocale"], "asset");
+        const id = text(asset.assetRef, "assetRef");
+        unique(assetIds, id);
+        validateProductMediaSourcePath(asset.source);
+        if (!["image/jpeg", "image/png", "image/webp"].includes(asset.contentType))
+            refuse("invalid_schema", id);
+        if (!Number.isSafeInteger(asset.byteLength) || asset.byteLength <= 0)
+            refuse("invalid_schema", id);
+        if (asset.byteLength > PRODUCT_MEDIA_LIMITS.imageBytes)
+            refuse("pack_limit_exceeded", id);
+        totalBytes += asset.byteLength;
+        if (totalBytes > PRODUCT_MEDIA_LIMITS.totalBytes)
+            refuse("pack_limit_exceeded", "totalBytes");
+        if (typeof asset.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(asset.sha256))
+            refuse("invalid_schema", id);
+        locale(asset.artworkLocale, id);
+    }
+    const productVariants = new Map();
+    let variantCount = 0;
+    for (const entry of products) {
+        const product = record(entry, "product");
+        fields(product, ["productId", "variantIds", "primaryVariantId"], "product");
+        const id = text(product.productId, "productId");
+        if (productVariants.has(id))
+            refuse("duplicate_identity", id);
+        const variants = new Set();
+        for (const variant of array(product.variantIds, id, PRODUCT_MEDIA_LIMITS.variants))
+            unique(variants, text(variant, id));
+        variantCount += variants.size;
+        if (variantCount > PRODUCT_MEDIA_LIMITS.variants)
+            refuse("pack_limit_exceeded", "variants");
+        const primary = text(product.primaryVariantId, id);
+        if (!variants.has(primary))
+            refuse("undeclared_variant", primary);
+        productVariants.set(id, variants);
+    }
+    const referencedAssets = new Set();
+    const identities = new Map();
+    const localizedIds = new Set();
+    for (const entry of associations) {
+        const item = record(entry, "association");
+        fields(item, ["itemId", "assetRef", "productId", "scope", "variantId", "locale", "role", "viewKey", "order", "label"], "association");
+        const id = text(item.itemId, "itemId");
+        const assetRef = text(item.assetRef, id);
+        if (!assetIds.has(assetRef))
+            refuse("missing_resource", assetRef);
+        referencedAssets.add(assetRef);
+        const productId = text(item.productId, id);
+        const variants = productVariants.get(productId);
+        if (!variants)
+            refuse("invalid_schema", productId);
+        if (item.scope !== "product" && item.scope !== "variant")
+            refuse("invalid_schema", id);
+        if (item.scope === "product" && item.variantId !== undefined)
+            refuse("invalid_schema", id);
+        if (item.scope === "variant") {
+            const variantId = text(item.variantId, id);
+            if (!variants.has(variantId))
+                refuse("undeclared_variant", variantId);
+        }
+        locale(item.locale, id);
+        if (!["primary", "view", "illustration"].includes(item.role))
+            refuse("invalid_schema", id);
+        if (item.viewKey !== undefined)
+            text(item.viewKey, id);
+        if (!Number.isSafeInteger(item.order))
+            refuse("invalid_schema", id);
+        text(item.label, id, 1024);
+        const identity = JSON.stringify([productId, item.scope, item.variantId, item.role, item.viewKey]);
+        if (identities.has(id) && identities.get(id) !== identity)
+            refuse("duplicate_identity", id);
+        identities.set(id, identity);
+        unique(localizedIds, JSON.stringify([id, item.locale]));
+    }
+    for (const id of assetIds)
+        if (!referencedAssets.has(id))
+            refuse("missing_resource", id);
+    return value;
+}

package/dist/catalog/contracts/productTypes.d.ts

@@ -0,0 +1,54 @@
+export type CatalogQuantityDimension = "mass" | "volume" | "count";
+export interface CatalogQuantity {
+    dimension: CatalogQuantityDimension;
+    unscaled: string;
+    scale: number;
+    unit: string;
+}
+export type CatalogOptionValue = {
+    kind: "choice";
+    value: string;
+} | {
+    kind: "quantity";
+    value: CatalogQuantity;
+} | {
+    kind: "boolean";
+    value: boolean;
+};
+export type CatalogDraftIssue = {
+    path: string;
+    code: string;
+};
+export interface CatalogProductTypeRef {
+    key: string;
+    version: number;
+}
+export interface CatalogProductTypeDefinition extends CatalogProductTypeRef {
+    units: {
+        code: string;
+        dimension: CatalogQuantityDimension;
+        integral: boolean;
+    }[];
+    netContentUnits: string[];
+    dimensions: ({
+        key: string;
+        kind: "choice";
+        values: string[];
+    } | {
+        key: string;
+        kind: "quantity";
+        dimension: CatalogQuantityDimension;
+        units: string[];
+        role?: "net_content";
+    } | {
+        key: string;
+        kind: "boolean";
+    })[];
+    validateContent: (content: unknown) => readonly CatalogDraftIssue[];
+}
+export interface CatalogProductTypeRegistry {
+    resolve(ref: CatalogProductTypeRef): CatalogProductTypeDefinition | undefined;
+}
+export declare function validateCatalogQuantity(quantity: CatalogQuantity, definition: CatalogProductTypeDefinition): boolean;
+/** Decimal spelling cannot make two equal option values distinct. No unit conversion is inferred. */
+export declare function canonicalCatalogOption(value: CatalogOptionValue): string;

package/dist/catalog/contracts/productTypes.js

@@ -0,0 +1,16 @@
+export function validateCatalogQuantity(quantity, definition) {
+    const unit = definition.units.find(({ code }) => code === quantity.unit);
+    return !!unit && unit.dimension === quantity.dimension
+        && (!unit.integral || BigInt(quantity.unscaled) % (10n ** BigInt(quantity.scale)) === 0n);
+}
+/** Decimal spelling cannot make two equal option values distinct. No unit conversion is inferred. */
+export function canonicalCatalogOption(value) {
+    if (value.kind !== "quantity")
+        return JSON.stringify(value);
+    let { unscaled, scale } = value.value;
+    while (scale > 0 && unscaled.endsWith("0")) {
+        unscaled = unscaled.slice(0, -1);
+        scale -= 1;
+    }
+    return JSON.stringify(["quantity", value.value.dimension, value.value.unit, unscaled, scale]);
+}

package/dist/catalog/contracts/resolveProductMedia.d.ts

@@ -0,0 +1,3 @@
+import { type ProductMediaManifest, type ProductMediaRequest, type ResolvedProductMedia } from "./productMediaContracts.js";
+/** Resolve only declared variant/product material; no filename, SKU or provider inference. */
+export declare function resolveProductMedia(value: ProductMediaManifest, request: ProductMediaRequest, assetUrls: Readonly<Record<string, string>>): ResolvedProductMedia;

package/dist/catalog/contracts/resolveProductMedia.js

@@ -0,0 +1,78 @@
+import { PRODUCT_MEDIA_LIMITS, ProductMediaValidationError, validateProductMediaManifest, } from "./productMediaContracts.js";
+const hasControls = (value) => Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127);
+const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const ordered = (a, b) => a.order - b.order || compareText(a.itemId, b.itemId);
+/** A deterministic browser-safe fingerprint, not a cryptographic integrity receipt. */
+function fingerprint(value) {
+    return [0x811c9dc5, 0x9e3779b9, 0x85ebca6b, 0xc2b2ae35].map((seed) => {
+        let hash = seed;
+        for (let index = 0; index < value.length; index++)
+            hash = Math.imul(hash ^ value.charCodeAt(index), 0x01000193);
+        return (hash >>> 0).toString(16).padStart(8, "0");
+    }).join("");
+}
+function revision(source, urls) {
+    const assets = [...source.assets].sort((a, b) => compareText(a.assetRef, b.assetRef)).map((a) => [a.assetRef, a.source, a.contentType, a.byteLength, a.sha256, a.artworkLocale, Object.prototype.hasOwnProperty.call(urls, a.assetRef) ? urls[a.assetRef] : null]);
+    const products = [...source.products].sort((a, b) => compareText(a.productId, b.productId)).map((p) => [p.productId, [...p.variantIds].sort(compareText), p.primaryVariantId]);
+    const associations = source.associations.map((a) => [a.itemId, a.assetRef, a.productId, a.scope, a.variantId ?? null, a.locale, a.role, a.viewKey ?? null, a.order, a.label]).sort((a, b) => compareText(JSON.stringify(a), JSON.stringify(b)));
+    return fingerprint(JSON.stringify([source.schemaVersion, assets, products, associations]));
+}
+function survives(a, b, locale) {
+    const ranks = (item) => [item.role === "primary" ? 1 : 0,
+        item.scope === "variant" ? 1 : 0, item.locale === locale ? 1 : 0];
+    const ar = ranks(a), br = ranks(b);
+    for (let index = 0; index < ar.length; index++)
+        if (ar[index] !== br[index])
+            return ar[index] > br[index];
+    return ordered(a, b) < 0;
+}
+/** Resolve only declared variant/product material; no filename, SKU or provider inference. */
+export function resolveProductMedia(value, request, assetUrls) {
+    const source = validateProductMediaManifest(value);
+    const product = source.products.find((p) => p.productId === request.productId);
+    if (!product || !product.variantIds.includes(request.variantId)) {
+        throw new ProductMediaValidationError("undeclared_variant", request.variantId);
+    }
+    if (typeof request.locale !== "string" || !request.locale.trim() || request.locale.length > 64 || hasControls(request.locale)) {
+        throw new ProductMediaValidationError("invalid_schema", "locale");
+    }
+    const logicalItems = new Map();
+    for (const item of source.associations) {
+        if (item.productId !== request.productId || (item.scope === "variant" && item.variantId !== request.variantId))
+            continue;
+        if (item.locale !== null && item.locale !== request.locale)
+            continue;
+        const current = logicalItems.get(item.itemId);
+        if (!current || item.locale === request.locale)
+            logicalItems.set(item.itemId, item);
+    }
+    const applicable = [...logicalItems.values()];
+    if (applicable.filter((item) => item.role === "primary").length > 1) {
+        throw new ProductMediaValidationError("conflicting_primary", request.productId);
+    }
+    const uniqueAssets = new Map();
+    for (const item of applicable) {
+        const current = uniqueAssets.get(item.assetRef);
+        if (!current || survives(item, current, request.locale))
+            uniqueAssets.set(item.assetRef, item);
+    }
+    if (uniqueAssets.size > PRODUCT_MEDIA_LIMITS.resolvedItems) {
+        throw new ProductMediaValidationError("collection_limit_exceeded", request.productId);
+    }
+    const items = [...uniqueAssets.values()].sort(ordered).map((item) => {
+        const src = Object.prototype.hasOwnProperty.call(assetUrls, item.assetRef) ? assetUrls[item.assetRef] : undefined;
+        if (typeof src !== "string" || !src.trim())
+            throw new ProductMediaValidationError("missing_resource", item.assetRef);
+        // The projection may contain opaque relative delivery paths or HTTP(S) URLs only.
+        if (/^[a-z][a-z\d+.-]*:/iu.test(src) && !/^https?:\/\//iu.test(src) || /^\s/u.test(src) || hasControls(src)) {
+            throw new ProductMediaValidationError("unsafe_path", item.assetRef);
+        }
+        return { id: item.itemId, assetRef: item.assetRef, src, label: item.label, role: item.role };
+    });
+    const mediaRevision = revision(source, assetUrls);
+    return {
+        key: JSON.stringify([request.productId, request.variantId, request.locale, mediaRevision]),
+        revision: mediaRevision, items,
+        primaryItemId: items.find((item) => item.role === "primary")?.id ?? null,
+    };
+}

package/dist/catalog/contracts/sellable.d.ts

@@ -0,0 +1,23 @@
+export declare const SELLABLE_CATALOG_CONTRACT_VERSION = "catalog.sellable.v1";
+export interface SellableCatalogItem {
+    sku: string;
+    title: string;
+    unitPrice: {
+        amountMinor: number;
+        currency: string;
+    };
+    permittedPurchaseModes: ("one_time" | "subscription")[];
+}
+export interface SellableCatalogProfile {
+    id: string;
+    brand: string;
+    country: string;
+    currency: string;
+    locale: string;
+    timezone: string;
+}
+export interface SellableCatalogListResponse {
+    contractVersion: typeof SELLABLE_CATALOG_CONTRACT_VERSION;
+    profile: SellableCatalogProfile;
+    items: SellableCatalogItem[];
+}

package/dist/catalog/contracts/sellable.js

@@ -0,0 +1 @@
+export const SELLABLE_CATALOG_CONTRACT_VERSION = "catalog.sellable.v1";

package/dist/catalog/draftHandler.d.ts

@@ -0,0 +1,25 @@
+import { type CatalogDraftApplyResult, type CatalogDraftPage, type CatalogDraftRecord, type CatalogDraftRefusal } from "./draftSchemas.js";
+import { type CatalogDraftOperator, type CatalogDraftStorePort } from "./draftPorts.js";
+import type { CatalogDraftIssue, CatalogProductTypeRegistry } from "./productTypeSchemas.js";
+import { type CatalogDraftReadiness } from "./draftValidation.js";
+export interface CatalogDraftHandlerDeps<Context> {
+    store: CatalogDraftStorePort;
+    registry: CatalogProductTypeRegistry;
+    authorizeOperator: (context: Context) => Promise<CatalogDraftOperator | null>;
+}
+export type CatalogDraftCommandResult = CatalogDraftApplyResult & {
+    issues?: readonly CatalogDraftIssue[];
+    readiness?: CatalogDraftReadiness;
+};
+/** Dark use case: mounting requires a verified operator authorizer at composition. */
+export declare function createCatalogDraftHandler<Context>(deps: CatalogDraftHandlerDeps<Context>): {
+    execute(input: unknown, context: Context): Promise<CatalogDraftCommandResult>;
+    get(input: unknown, context: Context): Promise<{
+        outcome: "found";
+        record: CatalogDraftRecord | null;
+    } | CatalogDraftRefusal>;
+    list(input: unknown, context: Context): Promise<{
+        outcome: "listed";
+        page: CatalogDraftPage;
+    } | CatalogDraftRefusal>;
+};

package/dist/catalog/draftHandler.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { canonicalCatalogDraftJson, catalogDraftApplyResultSchema, catalogDraftCommandSchema, catalogDraftGetQuerySchema, catalogDraftListQuerySchema, catalogDraftPageSchema, catalogDraftRecordSchema, catalogDraftRefusalSchema, } from "./draftSchemas.js";
+import { CatalogDraftStoreError, } from "./draftPorts.js";
+import { validateCatalogDraft } from "./draftValidation.js";
+const unavailable = () => ({ outcome: "dependency_unavailable", reason: "draft_dependency_unavailable" });
+const invalid = () => ({ outcome: "validation_issue", reason: "draft_input_invalid" });
+function failure(error) {
+    if (error instanceof CatalogDraftStoreError) {
+        const parsed = catalogDraftRefusalSchema.safeParse(error.refusal);
+        if (parsed.success)
+            return parsed.data;
+    }
+    return unavailable();
+}
+/** Dark use case: mounting requires a verified operator authorizer at composition. */
+export function createCatalogDraftHandler(deps) {
+    async function actor(context) {
+        try {
+            const operator = await deps.authorizeOperator(context);
+            if (!operator || !/^[^\s].{0,239}$/u.test(operator.actorId) || operator.actorId.trim() !== operator.actorId) {
+                return { outcome: "unauthorized", reason: "draft_operator_required" };
+            }
+            return operator;
+        }
+        catch {
+            return unavailable();
+        }
+    }
+    return {
+        async execute(input, context) {
+            const operator = await actor(context);
+            if ("outcome" in operator)
+                return operator;
+            let canonicalCommand;
+            try {
+                canonicalCommand = canonicalCatalogDraftJson(input);
+            }
+            catch {
+                return invalid();
+            }
+            const parsed = catalogDraftCommandSchema.safeParse(JSON.parse(canonicalCommand));
+            if (!parsed.success)
+                return invalid();
+            const command = parsed.data;
+            const fingerprint = createHash("sha256").update(canonicalCommand).digest("hex");
+            try {
+                // Read receipts first: changed registry, moved head or abandonment cannot erase a committed command.
+                const original = await deps.store.get({ draftId: command.draftId, commandKey: command.commandKey }, operator.actorId);
+                if (original !== null) {
+                    const record = catalogDraftRecordSchema.parse(original);
+                    if (record.draftId !== command.draftId || record.commandKey !== command.commandKey)
+                        return unavailable();
+                    if (record.actorId !== operator.actorId)
+                        return { outcome: "unauthorized", reason: "draft_command_actor_mismatch" };
+                    if (record.fingerprint !== fingerprint)
+                        return { outcome: "conflict", reason: "draft_command_key_reused" };
+                    return { outcome: "replayed", record };
+                }
+                let readiness;
+                if (command.payload) {
+                    const validation = validateCatalogDraft(command.payload, deps.registry);
+                    if (!validation.valid)
+                        return { outcome: "validation_issue", reason: "draft_payload_invalid", issues: validation.issues };
+                    readiness = validation.readiness;
+                }
+                const result = catalogDraftApplyResultSchema.parse(await deps.store.apply({ canonicalCommand, fingerprint, actorId: operator.actorId }));
+                if (result.outcome === "committed" || result.outcome === "replayed") {
+                    if (result.record.draftId !== command.draftId || result.record.commandKey !== command.commandKey
+                        || result.record.fingerprint !== fingerprint || result.record.actorId !== operator.actorId)
+                        return unavailable();
+                    return { ...result, ...(readiness ? { readiness } : {}) };
+                }
+                return result;
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+        async get(input, context) {
+            const operator = await actor(context);
+            if ("outcome" in operator)
+                return operator;
+            const parsed = catalogDraftGetQuerySchema.safeParse(input);
+            if (!parsed.success)
+                return invalid();
+            try {
+                const value = await deps.store.get(parsed.data, operator.actorId);
+                const record = value === null ? null : catalogDraftRecordSchema.parse(value);
+                if (record && (record.draftId !== parsed.data.draftId
+                    || (parsed.data.revision !== undefined && record.revision !== parsed.data.revision)
+                    || (parsed.data.commandKey !== undefined && record.commandKey !== parsed.data.commandKey)))
+                    return unavailable();
+                return { outcome: "found", record };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+        async list(input, context) {
+            const operator = await actor(context);
+            if ("outcome" in operator)
+                return operator;
+            const parsed = catalogDraftListQuerySchema.safeParse(input);
+            if (!parsed.success)
+                return invalid();
+            try {
+                const page = catalogDraftPageSchema.parse(await deps.store.list(parsed.data, operator.actorId));
+                if (page.items.length > parsed.data.limit || (parsed.data.afterDraftId
+                    && page.items.some(({ draftId }) => draftId <= parsed.data.afterDraftId)))
+                    return unavailable();
+                return { outcome: "listed", page };
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    };
+}