@openlup/platform 0.17.0 → 0.19.0

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

@@ -0,0 +1,78 @@
+/** Portable, payload-free catalog references and identifier authority. */
+export declare 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 declare class CatalogSkuAuthorityError extends Error {
+    readonly code: CatalogSkuAuthorityRefusal;
+    constructor(code: CatalogSkuAuthorityRefusal);
+}
+/** Accepts only GS1 GTIN-8/12/13/14 values with a valid modulo-10 check digit. */
+export declare function isValidGtin(value: string): boolean;
+/**
+ * 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 declare function assertPrimaryUnitGtinAuthority(identifiers: readonly CatalogSkuIdentifier[]): void;
+/** Returns the product-scoped revision only when the declared current authority is sound. */
+export declare function requireCurrentCatalogDocumentAuthority<T extends {
+    id: string;
+    productId: string;
+}>(productId: string, currentDocumentRevisionId: string | null, revision: T | null | undefined): T;

package/dist/catalog/contracts/foundation.js

@@ -0,0 +1,53 @@
+/** Portable, payload-free catalog references and identifier authority. */
+export const CATALOG_FOUNDATION_CONTRACT_VERSION = "catalog.foundation.v1";
+export class CatalogSkuAuthorityError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "CatalogSkuAuthorityError";
+    }
+}
+/** Accepts only GS1 GTIN-8/12/13/14 values with a valid modulo-10 check digit. */
+export function isValidGtin(value) {
+    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) {
+    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(productId, currentDocumentRevisionId, revision) {
+    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/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";