@endora-commerce/contracts 0.100.0

package/dist/catalog.js

@@ -0,0 +1,1543 @@
+import { z } from 'zod';
+import { isoDateTimeSchema, moneySchema, multilingualStringSchema, productVisibilitySchema, uuidSchema, } from './common.js';
+/**
+ * Catalog module contracts — Source of truth per Principle V.
+ * See specs/001-b2b-platform-foundation/contracts/catalog.contract.md.
+ */
+// --- Primitives --------------------------------------------------------------
+/**
+ * Product types. Foundation 001 used `simple | variant | grouped |
+ * virtual`; feature 002 (data-model.md §1.1) renames `variant` →
+ * `configurable` and adds `bundle`. The application enum is the only
+ * source of truth — the DB column is `varchar(16)` with no CHECK
+ * constraint (research.md R-1).
+ */
+export const productTypeSchema = z.enum([
+    'simple',
+    'configurable',
+    'grouped',
+    'bundle',
+    'virtual',
+]);
+export const productStatusSchema = z.enum(['draft', 'active', 'inactive']);
+/** Maps legacy `archived` writes to `inactive` (feature 032). */
+export function coerceProductStatusWrite(value) {
+    return value === 'archived' ? 'inactive' : value;
+}
+export const productStatusWriteSchema = z.preprocess(coerceProductStatusWrite, productStatusSchema);
+export const stockModeSchema = z.enum(['categorical', 'numeric']);
+export const stockIndicatorSchema = z.enum(['available', 'to_order', 'out_of_stock']);
+/**
+ * DB-level attribute value types. Foundation 001 introduced the original
+ * 5-element enum (`string | number | boolean | enum | date`). Feature 002
+ * adds `multiselect` and `price` per data-model.md §1.2.
+ *
+ * The API-facing presentation form (`apiAttributeTypeSchema` below)
+ * surfaces additional affordances (`input`, `select`, `slider`) that
+ * map to this DB enum + the sibling `displayAsSlider` flag — see
+ * research.md R-4 / R-7.
+ */
+export const attributeValueTypeSchema = z.enum([
+    'string',
+    'number',
+    'boolean',
+    'enum',
+    'date',
+    'multiselect',
+    'price',
+    'select',
+]);
+/**
+ * API-facing attribute type form for feature 002 contracts. Maps onto
+ * `attributeValueTypeSchema` + `displayAsSlider` in the service layer.
+ */
+export const apiAttributeTypeSchema = z.enum([
+    'input',
+    'number',
+    'select',
+    'multiselect',
+    'price',
+    'slider',
+]);
+/**
+ * The API-form type of a stored attribute, derived from the pair the catalogue
+ * persists (`valueType`, `displayAsSlider`). This is the single definition:
+ * the catalogue reports every attribute's `type` through it, and a connector
+ * that binds a source attribute to an existing one compares against it — two
+ * derivations of one rule drift, and a drift creates attributes the catalogue
+ * then reports as another kind.
+ *
+ * A slider flag only means something on a numeric type (`number`, `price`);
+ * elsewhere it is ignored. `string`, `boolean` and `date` have no richer API
+ * form and surface as `input`; `enum` and `select` share one affordance.
+ */
+export function apiAttributeTypeOf(valueType, displayAsSlider) {
+    if (displayAsSlider && (valueType === 'number' || valueType === 'price'))
+        return 'slider';
+    switch (valueType) {
+        case 'number':
+            return 'number';
+        case 'price':
+            return 'price';
+        case 'enum':
+        case 'select':
+            return 'select';
+        case 'multiselect':
+            return 'multiselect';
+        case 'string':
+        case 'boolean':
+        case 'date':
+            return 'input';
+    }
+}
+export const assetKindSchema = z.enum(['image', 'video', 'pdf', 'certificate', 'other']);
+// --- Feature 012 — Attribute options (rich per-option metadata) -------------
+const attributeOptionValueRegex = /^[a-z0-9_-]{1,200}$/;
+export const attributeOptionSchema = z.object({
+    id: uuidSchema,
+    attributeId: uuidSchema,
+    value: z.string().regex(attributeOptionValueRegex),
+    label: z.record(z.string().min(2), z.string().min(1).max(200)),
+    labelDefault: z.string().min(1).max(200),
+    isDefault: z.boolean(),
+    sortOrder: z.number().int().min(0),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const createAttributeOptionRequestSchema = z.object({
+    value: z.string().regex(attributeOptionValueRegex),
+    label: z.record(z.string().min(2), z.string().min(1).max(200)).optional(),
+    labelDefault: z.string().min(1).max(200),
+    isDefault: z.boolean().optional(),
+    sortOrder: z.number().int().min(0).optional(),
+});
+export const replaceAttributeOptionsRequestSchema = z.object({
+    options: z.array(createAttributeOptionRequestSchema),
+});
+export const patchAttributeOptionRequestSchema = z
+    .object({
+    label: z.record(z.string().min(2), z.string().min(1).max(200)).optional(),
+    labelDefault: z.string().min(1).max(200).optional(),
+    isDefault: z.boolean().optional(),
+    sortOrder: z.number().int().min(0).optional(),
+})
+    .strict();
+// --- Assets (linked from catalog) -------------------------------------------
+export const productAssetSchema = z.object({
+    id: uuidSchema,
+    kind: assetKindSchema,
+    url: z.string().url(),
+    altText: z.string().nullable(),
+});
+// --- Feature 062 — external (api-key) catalog read decorations ---------------
+/**
+ * Availability indication mirrored from the inventory display bands the
+ * storefront shows (`available` = stock not managed for the product).
+ */
+export const productAvailabilityBandSchema = z.enum([
+    'high',
+    'medium',
+    'low',
+    'out_of_stock',
+    'available',
+]);
+export const productAvailabilitySchema = z.object({
+    band: productAvailabilityBandSchema,
+    inStock: z.boolean(),
+});
+/**
+ * One rung of the bound Organization's resolved quantity-bracket price
+ * ladder (external product detail only).
+ */
+export const productPriceTierSchema = z.object({
+    minQuantity: z.number().int().min(1),
+    amount: z.number().finite(),
+    currency: z.string().length(3),
+    isSale: z.boolean(),
+});
+// --- Product summary (list response) ----------------------------------------
+export const productSummarySchema = z.object({
+    id: uuidSchema,
+    sku: z.string().min(1).max(255),
+    type: productTypeSchema,
+    name: z.string(),
+    slug: z.string(),
+    categorySlugs: z.array(z.string()),
+    primaryAssetUrl: z.string().url().nullable(),
+    price: moneySchema.nullable(),
+    stockIndicator: stockIndicatorSchema.nullable(),
+    stockLevel: z.number().int().nullable(),
+    /**
+     * Feature 062 — external namespace only (`/api/v1/external/catalog/*`):
+     * set to `true` for bound api-key callers when the Organization-effective
+     * price resolved to `null`. Never present on the public surface.
+     */
+    priceUnavailable: z.boolean().optional(),
+    /**
+     * Feature 062 — external namespace only: channel-public availability
+     * indication (band + in-stock flag), present for bound and unbound keys.
+     */
+    availability: productAvailabilitySchema.optional(),
+});
+// --- Product variant --------------------------------------------------------
+export const productVariantSchema = z.object({
+    id: uuidSchema,
+    sku: z.string().min(1).max(255),
+    variantAttributeValues: z.record(z.string(), z.unknown()),
+    priceOverride: z.number().finite().nullable(),
+    stockLevel: z.number().int().nullable(),
+});
+// --- Product detail (PDP response) ------------------------------------------
+export const seoMetaSchema = z.object({
+    metaTitle: z.string(),
+    metaDescription: z.string(),
+    openGraph: z.object({
+        title: z.string(),
+        description: z.string(),
+        imageUrl: z.string().url().nullable(),
+    }),
+});
+/**
+ * Forward declaration so productDetailSchema can reference link summaries.
+ * The exported `productLinkSummarySchema` below is the canonical name —
+ * this `*Inline` alias exists only to avoid a circular import.
+ */
+const productLinkSummarySchemaInline = z.object({
+    id: uuidSchema,
+    kind: z.enum(['related', 'up_sell', 'cross_sell']),
+    position: z.number().int().nonnegative(),
+    product: z.object({
+        id: uuidSchema,
+        sku: z.string(),
+        slug: z.string(),
+        name: z.string(),
+        primaryAssetUrl: z.string().nullable(),
+        price: moneySchema.nullable(),
+    }),
+});
+export const productDetailSchema = productSummarySchema.extend({
+    description: z.string(),
+    attributeValues: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+    assets: z.array(productAssetSchema),
+    variants: z.array(productVariantSchema),
+    categories: z.array(z.object({
+        id: uuidSchema,
+        name: z.string(),
+        slug: z.string(),
+    })),
+    seo: seoMetaSchema,
+    structuredDataJsonLd: z.record(z.string(), z.unknown()),
+    /**
+     * Feature 002 — the AttributeSet wired to this Product. Optional so
+     * foundation-era clients (and any storefront cache that hasn't been
+     * refreshed yet) keep parsing the response. Once admin UI + storefront
+     * consume this field everywhere, it can be tightened to required.
+     */
+    attributeSet: z
+        .object({
+        id: uuidSchema,
+        code: z.string(),
+        name: multilingualStringSchema,
+    })
+        .optional(),
+    /**
+     * Feature 002 US3 — gallery items with their assigned labels. Each
+     * item carries the Asset's resolved url + kind so storefront PDP
+     * doesn't need a follow-up fetch. Optional for the same backwards-
+     * compat reason as attributeSet.
+     */
+    gallery: z
+        .array(z.object({
+        id: uuidSchema,
+        position: z.number().int().nonnegative(),
+        labels: z.array(z.enum(['base_image', 'small_image', 'thumbnail'])),
+        asset: z.object({
+            id: uuidSchema,
+            kind: z.string(),
+            url: z.string(),
+        }),
+    }))
+        .optional(),
+    /**
+     * Feature 002 US5 — composite product payloads. Discriminated by
+     * `type`: only one of these is populated at a time. Optional so
+     * foundation-era simple/configurable products keep parsing.
+     *   - `groupedItems`: when type='grouped', children with quantities
+     *   - `bundleSlots`:  when type='bundle', slots with their options
+     *   - `virtual`:      when type='virtual', download asset/url
+     */
+    groupedItems: z
+        .array(z.object({
+        id: uuidSchema,
+        position: z.number().int().nonnegative(),
+        quantity: z.number().int().positive(),
+        product: z.object({
+            id: uuidSchema,
+            sku: z.string(),
+            slug: z.string(),
+            name: z.string(),
+            primaryAssetUrl: z.string().nullable(),
+            price: moneySchema.nullable(),
+        }),
+    }))
+        .optional(),
+    bundleSlots: z
+        .array(z.object({
+        id: uuidSchema,
+        name: multilingualStringSchema,
+        minQuantity: z.number().int().nonnegative(),
+        maxQuantity: z.number().int().positive(),
+        position: z.number().int().nonnegative(),
+        options: z.array(z.object({
+            id: uuidSchema,
+            defaultQuantity: z.number().int().positive(),
+            position: z.number().int().nonnegative(),
+            product: z.object({
+                id: uuidSchema,
+                sku: z.string(),
+                slug: z.string(),
+                name: z.string(),
+                primaryAssetUrl: z.string().nullable(),
+                price: moneySchema.nullable(),
+            }),
+        })),
+    }))
+        .optional(),
+    virtual: z
+        .object({
+        downloadAssetId: uuidSchema.nullable(),
+        downloadUrl: z.string().nullable(),
+    })
+        .optional(),
+    /**
+     * Feature 002 US4 — pre-grouped Product Links surfaced on the PDP.
+     * Optional for the same backwards-compat reason as the other US3/US4
+     * fields. Inactive targets and channel-restricted ones are pre-filtered
+     * by `ProductLinkService.listForStorefront`.
+     */
+    links: z
+        .object({
+        related: z.array(productLinkSummarySchemaInline),
+        upSell: z.array(productLinkSummarySchemaInline),
+        crossSell: z.array(productLinkSummarySchemaInline),
+    })
+        .optional(),
+    /**
+     * Feature 002 US3 — product attachments with their type + Asset.
+     * Optional like the rest.
+     */
+    attachments: z
+        .array(z.object({
+        id: uuidSchema,
+        position: z.number().int().nonnegative(),
+        name: z.string(),
+        description: z.string().nullable(),
+        type: z.object({
+            id: uuidSchema,
+            code: z.string(),
+            name: multilingualStringSchema,
+        }),
+        asset: z.object({
+            id: uuidSchema,
+            kind: z.string(),
+            url: z.string(),
+            filename: z.string(),
+            sizeBytes: z.number(),
+            mimeType: z.string(),
+        }),
+    }))
+        .optional(),
+    /**
+     * Feature 012 / FR-030 — every attribute that meets BOTH conditions:
+     *   1. attribute.isVisibleOnProductPage === true
+     *   2. product.attributeValues[attribute.key] is non-null + non-empty
+     * For select / enum / multiselect types, `valueRendered` is the
+     * resolved per-locale option label (with fallback to labelDefault).
+     * For other types it's a formatted string ('123.45', 'Yes', etc.).
+     * Optional for backwards-compat with foundation-era cached responses.
+     */
+    visibleAttributes: z
+        .array(z.object({
+        key: z.string(),
+        label: z.string(),
+        valueType: attributeValueTypeSchema,
+        valueRendered: z.string(),
+    }))
+        .optional(),
+    /**
+     * Feature 043 — named packaging units (e.g. "Paleta" = 480 pieces) the
+     * buyer can order by. Present only for eligible product types
+     * (simple / configurable); omitted or empty otherwise.
+     */
+    packagingUnits: z
+        .array(z.object({
+        id: uuidSchema,
+        name: z.string(),
+        baseQuantity: z.number().int().positive(),
+        position: z.number().int().nonnegative(),
+        isDefault: z.boolean(),
+    }))
+        .optional(),
+    /**
+     * Feature 062 — external namespace only: the bound Organization's resolved
+     * quantity-bracket price ladder. Never present on the public surface nor
+     * for unbound api-key callers.
+     */
+    priceTiers: z.array(productPriceTierSchema).optional(),
+});
+// --- Feature 062 — external bulk pricing (`POST /api/v1/external/catalog/prices`) ---
+export const catalogBulkPriceRequestSchema = z.object({
+    lines: z
+        .array(z.object({
+        sku: z.string().min(1),
+        quantity: z.number().int().min(1),
+    }))
+        .min(1)
+        .max(200),
+});
+export const catalogBulkPriceMissReasonSchema = z.enum([
+    'sku_not_in_assortment',
+    'price_unavailable',
+]);
+/**
+ * Per-line result, order-preserving. Misses are data, not errors — the
+ * partner needs a total answer for a basket. `amount` is the exact decimal
+ * string the pricing resolver charges the bound org on the bound channel at
+ * that quantity (SC-001 parity with cart pricing).
+ */
+export const catalogBulkPriceLineSchema = z.union([
+    z.object({
+        sku: z.string(),
+        quantity: z.number().int(),
+        price: z.object({
+            amount: z.string(),
+            currency: z.string().length(3),
+            isSale: z.boolean(),
+            bracketStartQuantity: z.number().int(),
+            priceListId: uuidSchema,
+        }),
+    }),
+    z.object({
+        sku: z.string(),
+        quantity: z.number().int(),
+        price: z.null(),
+        reason: catalogBulkPriceMissReasonSchema,
+    }),
+]);
+export const catalogBulkPriceResponseSchema = z.object({
+    data: z.array(catalogBulkPriceLineSchema),
+});
+export const categoryNodeSchema = z.lazy(() => z.object({
+    id: uuidSchema,
+    name: z.string(),
+    slug: z.string(),
+    sortOrder: z.number().int(),
+    productCount: z.number().int().nonnegative(),
+    children: z.array(categoryNodeSchema),
+}));
+// --- Filter definitions (for storefront filter panel) -----------------------
+export const filterOptionSchema = z.object({
+    value: z.string(),
+    label: z.string(),
+    count: z.number().int().nonnegative(),
+});
+export const filterRangeSchema = z.object({
+    min: z.number(),
+    max: z.number(),
+});
+export const filterDefinitionSchema = z.object({
+    attributeKey: z.string(),
+    label: z.string(),
+    valueType: attributeValueTypeSchema,
+    options: z.array(filterOptionSchema).optional(),
+    range: filterRangeSchema.optional(),
+    /**
+     * Feature 012 / FR-027 — ascending sort order on the storefront
+     * filter sidebar. Ties are broken alphabetically by `label`. The
+     * service pre-sorts the response so consumers don't need to.
+     */
+    filterPosition: z.number().int().min(0).default(0),
+});
+// --- Admin write-surface requests -------------------------------------------
+// Base shape (no cross-field refine) so updateProductRequestSchema can
+// `.partial()` it. The cross-field rule for virtual download fields is
+// applied as a separate refine on the create variant below.
+const baseProductRequestObject = z.object({
+    sku: z.string().min(1).max(255),
+    type: productTypeSchema,
+    name: multilingualStringSchema,
+    description: multilingualStringSchema,
+    categoryIds: z.array(uuidSchema),
+    attributeValues: z.record(z.string(), z.unknown()),
+    stockMode: stockModeSchema.optional(),
+    visibility: productVisibilitySchema,
+    // Feature 022 — accepted by the single-product PATCH and the bulk
+    // update endpoint. Cross-field rule on `archivedAt` is enforced in
+    // the service layer (CatalogAdminService.updateProduct).
+    // Feature 032 — `archived` write alias → `inactive`.
+    status: productStatusWriteSchema.optional(),
+    allowedOrganizationIds: z.array(uuidSchema).optional(),
+    assetIds: z.array(uuidSchema).optional(),
+    initialStock: z.number().int().nonnegative().optional(),
+    /**
+     * Feature 002 — Attribute Set the Product is wired to. Optional in the
+     * request: when omitted, the system Default Set is used.
+     */
+    attributeSetId: uuidSchema.optional(),
+    /**
+     * Feature 002 — virtual product download fields (data-model.md §1.1).
+     * Exactly one MUST be set when type='virtual'; both MUST be null on
+     * any other type. Refine below enforces the cross-field rule on the
+     * create-side; updates land it via service-layer guard (T047).
+     */
+    downloadAssetId: uuidSchema.nullable().optional(),
+    downloadUrl: z.string().url().max(2048).nullable().optional(),
+    /**
+     * Feature 010 — per-product stock-management flags.
+     * `manageStock=false` ⇒ storefront treats the product as always available.
+     * `backorderEnabled=true` ⇒ zero-stock checkout is accepted with the
+     * resulting allocation flagged `is_backorder = true`.
+     * `lowStockThreshold` is the cumulative on-hand at-or-below which an
+     * email alert fires. `fulfilmentStrategy` overrides the global strategy
+     * for this product; `fulfilmentStrategyWarehouseOrder` carries the walk
+     * order used when the strategy is `defined_order`.
+     */
+    manageStock: z.boolean().optional(),
+    backorderEnabled: z.boolean().optional(),
+    lowStockThreshold: z.number().int().nonnegative().nullable().optional(),
+    /**
+     * Determines how `lowStockThreshold` is interpreted.
+     *  - `'cumulative'`: one threshold against the cumulative on-hand.
+     *  - `'per_warehouse'`: per-(product, warehouse) thresholds maintained
+     *    via the inventory admin surface; the value of `lowStockThreshold`
+     *    is then unused.
+     */
+    lowStockThresholdMode: z.enum(['cumulative', 'per_warehouse']).optional(),
+    fulfilmentStrategy: z
+        .enum(['any', 'default_first', 'lowest_stock_first', 'highest_stock_first', 'defined_order'])
+        .nullable()
+        .optional(),
+    fulfilmentStrategyWarehouseOrder: z.array(uuidSchema).nullable().optional(),
+});
+export const createProductRequestSchema = baseProductRequestObject.refine((v) => {
+    const hasAsset = v.downloadAssetId != null;
+    const hasUrl = v.downloadUrl != null;
+    if (v.type === 'virtual')
+        return hasAsset !== hasUrl; // exactly one of
+    return !hasAsset && !hasUrl; // non-virtual must have neither
+}, {
+    message: 'virtual products require exactly one of `downloadAssetId` or `downloadUrl`; non-virtual products MUST have neither.',
+    path: ['downloadUrl'],
+});
+// `type` is immutable after creation (409 FIELD_IMMUTABLE if sent).
+// Feature 012 / FR-016 — `sku` is now editable. Collision with another
+// product's SKU is refused with 400 sku_in_use; snapshot tables on
+// orders / quote-requests / invoices keep displaying the SKU value
+// frozen at snapshot time.
+export const updateProductRequestSchema = baseProductRequestObject
+    .partial()
+    .omit({ type: true });
+// Admin batch-by-id lookup. The body carries the id set (deduped server-
+// side) plus optional pagination so callers can stream large lookups
+// across multiple requests. Hard cap of 500 ids per call mirrors the
+// service-layer `pageSize` ceiling and keeps a single request bounded.
+export const batchByIdProductsRequestSchema = z.object({
+    ids: z.array(z.string().uuid()).max(500),
+    page: z.number().int().min(0).optional(),
+    pageSize: z.number().int().min(1).max(500).optional(),
+});
+// ---------------------------------------------------------------------------
+// Feature 033 — Resolve product IDs by list filters (collection selection)
+// ---------------------------------------------------------------------------
+export const MAX_RESOLVE_SELECTION_SIZE = 10_000;
+export const resolveProductIdsRequestSchema = z.object({
+    status: productStatusSchema.optional(),
+    type: productTypeSchema.optional(),
+    q: z.string().trim().min(1).optional(),
+    includeArchived: z.boolean().optional(),
+});
+export const resolveProductIdsResponseSchema = z.object({
+    data: z.object({
+        productIds: z.array(uuidSchema),
+        total: z.number().int().nonnegative(),
+    }),
+});
+// ---------------------------------------------------------------------------
+// Feature 022 — Products Bulk Edit
+// ---------------------------------------------------------------------------
+const bulkEditModeSchema = z.enum(['add', 'replace']);
+// Categories also support `remove` (subtract the given categories from each
+// product's current memberships); sales channels keep the two-mode enum.
+const bulkEditCategoryModeSchema = z.enum(['add', 'replace', 'remove']);
+const bulkUpdateFieldsObject = z.object({
+    status: productStatusWriteSchema.optional(),
+    visibility: productVisibilitySchema.optional(),
+    salesChannels: z
+        .object({
+        mode: bulkEditModeSchema,
+        channelIds: z.array(uuidSchema),
+    })
+        .optional(),
+    categories: z
+        .object({
+        mode: bulkEditCategoryModeSchema,
+        categoryIds: z.array(uuidSchema),
+    })
+        .optional(),
+    // Feature 022 — assign (or clear, with null) the Attribute Set on every
+    // selected product.
+    attributeSetId: uuidSchema.nullable().optional(),
+    attributeValues: z.record(z.string(), z.unknown()).optional(),
+});
+export const bulkUpdateProductsRequestSchema = z.object({
+    // The non-empty constraint is part of the schema (a Zod-level
+    // validation failure). The 200-item soft cap is enforced inside the
+    // handler so the response carries the dedicated `BULK_TOO_LARGE`
+    // code along with `details.maxBatchSize` / `details.recommendedSplitInto`.
+    // An upper hard limit at 10_000 prevents pathological payloads from
+    // ever reaching the cap check.
+    productIds: z.array(uuidSchema).min(1).max(10_000),
+    fields: bulkUpdateFieldsObject.refine((f) => f.status !== undefined ||
+        f.visibility !== undefined ||
+        f.salesChannels !== undefined ||
+        f.categories !== undefined ||
+        f.attributeSetId !== undefined ||
+        (f.attributeValues !== undefined && Object.keys(f.attributeValues).length > 0), { message: 'at least one field must be present' }),
+});
+export const bulkUpdateProductResultSchema = z.object({
+    productId: z.string().uuid(),
+    status: z.enum(['succeeded', 'skipped', 'failed']),
+    reason: z
+        .enum([
+        'attribute_not_in_set',
+        'validation_failed',
+        'permission_denied',
+        'concurrent_modification',
+        'product_not_found',
+    ])
+        .optional(),
+    details: z
+        .object({
+        code: z.string().optional(),
+        message: z.string().optional(),
+        attribute: z.string().optional(),
+    })
+        .optional(),
+    changedFields: z.array(z.string()).optional(),
+});
+export const bulkUpdateProductsResponseSchema = z.object({
+    data: z.object({
+        bulkOperationId: z.string().uuid(),
+        summary: z.object({
+            succeeded: z.number().int().nonnegative(),
+            skipped: z.number().int().nonnegative(),
+            failed: z.number().int().nonnegative(),
+            total: z.number().int().nonnegative(),
+        }),
+        results: z.array(bulkUpdateProductResultSchema),
+    }),
+});
+// ---------------------------------------------------------------------------
+// Queued bulk operations
+//
+// Selections above the synchronous threshold are not applied inline.
+// Instead the handler enqueues a `BulkOperation` and returns the ack
+// below; the work is finished off-thread by the in-process sweeper, and
+// progress is observable through the bulk-operations list endpoints.
+// ---------------------------------------------------------------------------
+export const bulkUpdateQueuedResponseSchema = z.object({
+    data: z.object({
+        queued: z.literal(true),
+        bulkOperationId: z.string().uuid(),
+        total: z.number().int().nonnegative(),
+    }),
+});
+export const bulkOperationStatusSchema = z.enum([
+    'pending',
+    'running',
+    'completed',
+    'failed',
+]);
+/**
+ * One timestamped lifecycle event in a bulk operation's log trail, surfaced
+ * in the bulk-operations detail view next to the per-element results.
+ */
+export const bulkOperationLogEntrySchema = z.object({
+    ts: z.string(),
+    level: z.enum(['info', 'warn', 'error']),
+    message: z.string(),
+});
+/**
+ * Known bulk-operation kinds. `type` on the record is an open string (the
+ * queue is generic), but these are the kinds the platform ships:
+ *   - `product_bulk_update` — the queued large product bulk-edit (feature 022).
+ *   - `search_reindex`       — a full Meilisearch reindex (the `search:reindex`
+ *      CLI equivalent), enqueued when an attribute's `searchable` flag changes.
+ */
+export const BULK_OPERATION_TYPES = {
+    PRODUCT_BULK_UPDATE: 'product_bulk_update',
+    SEARCH_REINDEX: 'search_reindex',
+};
+export const bulkOperationSchema = z.object({
+    id: z.string().uuid(),
+    type: z.string(),
+    status: bulkOperationStatusSchema,
+    requestedByAdminUserId: z.string().uuid(),
+    total: z.number().int().nonnegative(),
+    processed: z.number().int().nonnegative(),
+    succeeded: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    touchedFields: z.array(z.string()),
+    results: z.array(bulkUpdateProductResultSchema).nullable(),
+    logs: z.array(bulkOperationLogEntrySchema).nullable(),
+    error: z.string().nullable(),
+    createdAt: z.string(),
+    startedAt: z.string().nullable(),
+    finishedAt: z.string().nullable(),
+    // Feature 054 — undo affordance.
+    reversible: z.boolean(),
+    undoStatus: z.enum(['none', 'reverted', 'partially_reverted']),
+    undoneAt: z.string().nullable(),
+});
+/** Response of POST /admin/catalog/bulk-operations/:id/undo. */
+export const bulkOperationUndoResponseSchema = z.object({
+    data: z.object({
+        undoStatus: z.enum(['none', 'reverted', 'partially_reverted']),
+        reverted: z.number().int().nonnegative(),
+        conflicts: z.array(z.object({ recordId: z.string(), reason: z.string() })),
+    }),
+});
+export const bulkOperationsListResponseSchema = z.object({
+    data: z.array(bulkOperationSchema),
+    pagination: z.object({
+        total: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+    }),
+});
+export const bulkOperationResponseSchema = z.object({ data: bulkOperationSchema });
+export const createVariantRequestSchema = z.object({
+    sku: z.string().min(1).max(255),
+    variantAttributeValues: z.record(z.string(), z.unknown()),
+    priceOverride: z.number().finite().optional(),
+    stockLevel: z.number().int().nonnegative().optional(),
+});
+export const updateVariantRequestSchema = createVariantRequestSchema
+    .partial()
+    .omit({ sku: true });
+/**
+ * Slider-numeric-kind discriminant (feature 002 T013/T021/T022). The API
+ * `type=slider` form needs an extra hint so the service knows whether the
+ * underlying DB `valueType` is `number` or `price`.
+ */
+export const numericKindSchema = z.enum(['number', 'price']);
+const baseCreateAttributeObject = z.object({
+    key: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z][a-z0-9_]*$/, 'must be snake_case, start with a letter'),
+    label: multilingualStringSchema,
+    /**
+     * Feature 002 — preferred API form. When `type` is present it wins over
+     * `valueType` (legacy form, kept for backward-compat). Service maps it
+     * onto the DB enum + `displayAsSlider` flag (research R-7):
+     *   input      → valueType=string
+     *   number     → valueType=number
+     *   select     → valueType=enum
+     *   multiselect→ valueType=multiselect (requires enumValues)
+     *   price      → valueType=price
+     *   slider     → valueType=number|price (per numericKind) + displayAsSlider=true
+     */
+    type: apiAttributeTypeSchema.optional(),
+    numericKind: numericKindSchema.optional(),
+    /** Legacy form. At least one of `type` or `valueType` MUST be set. */
+    valueType: attributeValueTypeSchema.optional(),
+    enumValues: z.array(z.string()).optional(),
+    isSearchable: z.boolean(),
+    isFilterable: z.boolean(),
+    isVariantAxis: z.boolean(),
+    /**
+     * Feature 002 — presentation hint. Honored only when the resolved
+     * underlying type is `number`/`price`. Implicitly `true` when
+     * `type=slider`. Service rejects with INVALID_DISPLAY_AS_SLIDER if
+     * supplied for an incompatible underlying type.
+     */
+    displayAsSlider: z.boolean().optional(),
+    /**
+     * Feature 007 — selects whether the attribute appears as a body row on
+     * the Compare module's comparison page. Independent of isSearchable /
+     * isFilterable. Defaults to false on create when omitted.
+     */
+    isComparable: z.boolean().optional(),
+    /**
+     * Feature 012 — fallback label used when the active locale is missing
+     * from `label`. Defaults server-side to the en-US label (or the first
+     * available label, or the attribute key) when omitted on create.
+     */
+    labelDefault: z.string().min(1).max(200).optional(),
+    /** Feature 012 — enforced at product save time when the attribute is in the assigned set. */
+    isRequired: z.boolean().optional(),
+    /** Feature 012 — surfaces the attribute in the Promotion Rule criterion picker. */
+    isPromoRule: z.boolean().optional(),
+    /** Feature 012 — ascending sort order on the storefront filter sidebar. Defaults 0. */
+    filterPosition: z.number().int().min(0).max(10000).optional(),
+    /** Feature 012 — gates inclusion in the storefront PDP "Parametry produktu" tab. */
+    isVisibleOnProductPage: z.boolean().optional(),
+    /**
+     * Feature 023 — when `true` the attribute may carry per-Sales-Channel
+     * overrides. Default `false` (global-only). Independent of
+     * `languageScoped`; the two flags compose into one of four effective
+     * scopes (`global` / `language` / `channel` / `channel+language`).
+     */
+    channelScoped: z.boolean().optional(),
+    /**
+     * Feature 023 — when `true` the attribute's value is keyed by
+     * language at every slot. For user-defined attributes the baseline
+     * is stored as `Record<lang, value>` in `products.attribute_values`;
+     * for the system Name / Description attributes this flag is pinned
+     * `true` by SYSTEM_ATTRIBUTE_SCOPES.
+     */
+    languageScoped: z.boolean().optional(),
+    /**
+     * Feature 022 (products bulk edit) — makes the attribute available in
+     * the Products Bulk Edit dialog's attribute field list. Default false;
+     * operators opt each attribute in explicitly.
+     */
+    massEditable: z.boolean().optional(),
+    /** Feature 039 — values participate in Quick Order search. Default false. */
+    quickSearchable: z.boolean().optional(),
+    /**
+     * Feature 012 — rich option list for select / enum / multiselect types.
+     * When supplied alongside the legacy `enumValues`, this wins. The
+     * service layer creates corresponding `custom_field_options` rows
+     * (feature 061; formerly the catalog-owned `attribute_options` table).
+     */
+    options: z.array(createAttributeOptionRequestSchema).optional(),
+});
+export const createAttributeRequestSchema = baseCreateAttributeObject
+    .refine((v) => v.type !== undefined || v.valueType !== undefined, {
+    message: 'either `type` (preferred) or `valueType` (legacy) is required',
+    path: ['type'],
+})
+    .refine((v) => {
+    // Select-style attributes need either the legacy `enumValues: string[]`
+    // shape OR the new feature-012 `options: AttributeOption[]` shape.
+    // The service maps either to `custom_field_options` rows (feature 061).
+    const wantsEnum = v.type === 'multiselect' ||
+        v.type === 'select' ||
+        v.valueType === 'enum' ||
+        v.valueType === 'multiselect' ||
+        v.valueType === 'select';
+    if (!wantsEnum)
+        return true;
+    const hasLegacy = Array.isArray(v.enumValues) && v.enumValues.length > 0;
+    const hasOptions = Array.isArray(v.options) && v.options.length > 0;
+    return hasLegacy || hasOptions;
+}, {
+    message: 'either enumValues (legacy) or options (feature 012) is required for select-style attributes',
+    path: ['options'],
+})
+    .refine((v) => (v.type === 'slider' ? v.numericKind !== undefined : true), {
+    message: 'numericKind is required when type=slider',
+    path: ['numericKind'],
+});
+export const updateAttributeRequestSchema = z
+    .object({
+    label: multilingualStringSchema.optional(),
+    /** Feature 002 — same API form as create. */
+    type: apiAttributeTypeSchema.optional(),
+    numericKind: numericKindSchema.optional(),
+    enumValues: z.array(z.string()).optional(),
+    isSearchable: z.boolean().optional(),
+    isFilterable: z.boolean().optional(),
+    isVariantAxis: z.boolean().optional(),
+    displayAsSlider: z.boolean().optional(),
+    /** Feature 007 — toggles the Compare-page row for this attribute. */
+    isComparable: z.boolean().optional(),
+    /** Feature 012 — fallback label used when the active locale is missing from `label`. */
+    labelDefault: z.string().min(1).max(200).optional(),
+    /** Feature 012 — enforced at product save time when the attribute is in the assigned set. */
+    isRequired: z.boolean().optional(),
+    /** Feature 012 — surfaces the attribute in the Promotion Rule criterion picker. */
+    isPromoRule: z.boolean().optional(),
+    /** Feature 012 — ascending sort order on the storefront filter sidebar. */
+    filterPosition: z.number().int().min(0).max(10000).optional(),
+    /** Feature 012 — gates inclusion in the storefront PDP "Parametry produktu" tab. */
+    isVisibleOnProductPage: z.boolean().optional(),
+    /** Feature 023 — see `baseCreateAttributeObject.channelScoped`. */
+    channelScoped: z.boolean().optional(),
+    /** Feature 023 — see `baseCreateAttributeObject.languageScoped`. */
+    languageScoped: z.boolean().optional(),
+    /** Feature 022 (products bulk edit) — toggles bulk-editability. */
+    massEditable: z.boolean().optional(),
+    /** Feature 039 — values participate in Quick Order search. */
+    quickSearchable: z.boolean().optional(),
+})
+    .strict()
+    .refine((v) => (v.type === 'slider' ? v.numericKind !== undefined : true), {
+    message: 'numericKind is required when type=slider',
+    path: ['numericKind'],
+});
+/**
+ * Feature 061 — admin attribute payload returned by
+ * `GET/POST/PATCH /api/v1/admin/catalog/attributes*`. Formalizes the shape
+ * `serializeAdminAttribute` has emitted since features 002/012/022/023/039 and
+ * adds the single additive field `customFieldDefinitionId` — the backing
+ * product-host Custom Field definition (contracts/attribute-admin-api.md).
+ * All request schemas above are byte-compatible and unchanged (FR-007, SC-003).
+ */
+export const adminAttributeResponseSchema = z.object({
+    id: uuidSchema,
+    key: z.string(),
+    label: multilingualStringSchema,
+    labelDefault: z.string(),
+    /** API-form type (feature 002) — emitted alongside the legacy `valueType`. */
+    type: apiAttributeTypeSchema,
+    /** Present only when `type === 'slider'`. */
+    numericKind: numericKindSchema.optional(),
+    valueType: attributeValueTypeSchema,
+    /** Legacy projection of the option values; `null` when not fetched or absent. */
+    enumValues: z.array(z.string()).nullable(),
+    isSearchable: z.boolean(),
+    isFilterable: z.boolean(),
+    isVariantAxis: z.boolean(),
+    displayAsSlider: z.boolean(),
+    isComparable: z.boolean(),
+    isRequired: z.boolean(),
+    isPromoRule: z.boolean(),
+    filterPosition: z.number().int(),
+    isVisibleOnProductPage: z.boolean(),
+    massEditable: z.boolean(),
+    quickSearchable: z.boolean(),
+    /** Feature 061 (additive) — id of the backing product-host Custom Field definition. */
+    customFieldDefinitionId: uuidSchema,
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const createCategoryRequestSchema = z.object({
+    parentCategoryId: uuidSchema.nullable().optional(),
+    name: multilingualStringSchema,
+    slug: z
+        .string()
+        .min(1)
+        .max(160)
+        .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'must be kebab-case'),
+    sortOrder: z.number().int().optional(),
+    /**
+     * Feature 068 — activation switch. Omitted means active: a category created
+     * by an administrator is visible unless they say otherwise. Integrations
+     * that discover categories (e.g. the Ergonode importer) pass `false` so a
+     * first import never exposes a source hierarchy to customers.
+     */
+    isActive: z.boolean().optional(),
+});
+export const updateCategoryRequestSchema = z
+    .object({
+    parentCategoryId: uuidSchema.nullable().optional(),
+    name: multilingualStringSchema.optional(),
+    slug: z
+        .string()
+        .min(1)
+        .max(160)
+        .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'must be kebab-case')
+        .optional(),
+    sortOrder: z.number().int().optional(),
+    /**
+     * Feature 068 — activation switch. `false` hides the category from every
+     * customer-facing read; the admin tree keeps listing it so it can be
+     * re-enabled.
+     */
+    isActive: z.boolean().optional(),
+    /** Feature 013 / US5 — Library Asset rendered as the category's main image. */
+    mainImageAssetId: uuidSchema.nullable().optional(),
+    /** Feature 055 — custom-field values for this category (validated on write). */
+    customFieldValues: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+// --- Storefront list/query ---------------------------------------------------
+/**
+ * The orderings the storefront listing accepts.
+ *
+ * Feature 086 adds `price` / `-price`, following the convention the two `name`
+ * members set: the bare member ascends, the `-` prefix descends. "Price" is the
+ * **viewer's own** resolved unit price at quantity 1 — the figure the card
+ * renders — never a stored base price, a channel price or anything a search
+ * index carries.
+ */
+export const productListSortSchema = z.enum([
+    'relevance',
+    '-createdAt',
+    'name',
+    '-name',
+    'price',
+    '-price',
+]);
+/** The two orderings feature 086 added, as a narrowing a consumer can reuse. */
+export function isPriceSort(sort) {
+    return sort === 'price' || sort === '-price';
+}
+export const productListQuerySchema = z
+    .object({
+    q: z.string().optional(),
+    limit: z.coerce.number().int().positive().max(200).default(50),
+    cursor: z.string().optional(),
+    sort: productListSortSchema.optional(),
+    changedSince: isoDateTimeSchema.optional(),
+    /**
+     * Feature 086 — inclusive bounds on the **viewer's own** resolved unit
+     * price, in the currency the response quotes. Both optional and
+     * independent, and both compose with every ordering rather than only with
+     * the two price ones (FR-009).
+     *
+     * Numbers on the wire, decimal strings by the time they reach the pricing
+     * relation: the comparison happens in `numeric`, never in a float.
+     */
+    minPrice: z.coerce.number().nonnegative().finite().optional(),
+    maxPrice: z.coerce.number().nonnegative().finite().optional(),
+})
+    .refine((v) => v.minPrice === undefined || v.maxPrice === undefined || v.minPrice <= v.maxPrice, {
+    // FR-008 — a minimum above a maximum is a 400, not an empty page. An
+    // empty page for a contradictory range is indistinguishable from an empty
+    // page for a genuine one, and a buyer who typed the bounds the wrong way
+    // round should be told which two they were.
+    message: 'minPrice must not exceed maxPrice',
+    path: ['minPrice'],
+});
+/**
+ * What the listing surface may offer this viewer on this page — feature 086 /
+ * FR-023.
+ *
+ * It rides on the listing response because the storefront has to decide whether
+ * to *render* the price controls, and the answer depends on the viewer and the
+ * channel: a non-public channel publishes no prices, and
+ * `pricing.unauthenticated_display_mode = none` hides them until login. A
+ * storefront that guessed would guess wrong on exactly the deployments that
+ * care, and a control that offers an ordering the API refuses is a worse defect
+ * than no control.
+ *
+ * It is **not** on the filter-definitions endpoint, which is anonymous and
+ * shared (FR-010): a per-viewer answer may not travel on a response whose cache
+ * key omits the viewer.
+ */
+export const productListCapabilitiesSchema = z.object({
+    /** May this page be ordered by price, and narrowed to a price range? */
+    priceOrdering: z.boolean(),
+});
+// --- Notify-when-available --------------------------------------------------
+export const notifyWhenAvailableRequestSchema = z.object({
+    variantId: uuidSchema.optional(),
+});
+export const notifyWhenAvailableResponseSchema = z.object({
+    subscriptionId: uuidSchema,
+    requestedAt: isoDateTimeSchema,
+});
+// --- Feature 002 — Attribute Sets -------------------------------------------
+// See specs/002-catalog-module/contracts/catalog-002.contract.md.
+const attributeSetCodeSchema = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z0-9_]+$/, 'must be snake_case');
+export const attributeSetSchema = z.object({
+    id: uuidSchema,
+    code: attributeSetCodeSchema,
+    name: multilingualStringSchema,
+    description: multilingualStringSchema.nullable(),
+    isSystem: z.boolean(),
+    attributeCount: z.number().int().nonnegative(),
+    productCount: z.number().int().nonnegative(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const attributeSetAssignedAttributeSchema = z.object({
+    id: uuidSchema,
+    key: z.string(),
+    label: multilingualStringSchema,
+    valueType: attributeValueTypeSchema,
+    position: z.number().int().nonnegative(),
+    /**
+     * Feature 023 — the attribute's value is keyed by language, so the product
+     * editor renders it (and anything scoped to it, such as feature 068's
+     * overwrite protection) per language rather than once for the attribute.
+     */
+    languageScoped: z.boolean(),
+});
+export const attributeSetDetailSchema = attributeSetSchema.extend({
+    attributes: z.array(attributeSetAssignedAttributeSchema),
+});
+export const createAttributeSetRequestSchema = z
+    .object({
+    code: attributeSetCodeSchema,
+    name: multilingualStringSchema,
+    description: multilingualStringSchema.optional(),
+    attributeIds: z.array(uuidSchema).optional(),
+})
+    .strict();
+export const updateAttributeSetRequestSchema = z
+    .object({
+    code: attributeSetCodeSchema.optional(),
+    name: multilingualStringSchema.optional(),
+    description: multilingualStringSchema.nullable().optional(),
+})
+    .strict();
+export const assignAttributesRequestSchema = z
+    .object({
+    assignments: z
+        .array(z.object({
+        attributeId: uuidSchema,
+        position: z.number().int().nonnegative().optional(),
+    }))
+        .min(1),
+})
+    .strict();
+// --- Feature 002 — Gallery (US3) --------------------------------------------
+export const galleryLabelSchema = z.enum(['base_image', 'small_image', 'thumbnail']);
+export const galleryItemSchema = z.object({
+    id: uuidSchema,
+    productId: uuidSchema,
+    assetId: uuidSchema,
+    position: z.number().int().nonnegative(),
+    labels: z.array(galleryLabelSchema),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const createGalleryItemRequestSchema = z
+    .object({
+    assetId: uuidSchema,
+    position: z.number().int().nonnegative().optional(),
+    labels: z.array(galleryLabelSchema).optional(),
+})
+    .strict();
+export const updateGalleryItemRequestSchema = z
+    .object({
+    position: z.number().int().nonnegative().optional(),
+    labels: z.array(galleryLabelSchema).optional(),
+})
+    .strict();
+export const reorderGalleryRequestSchema = z
+    .object({
+    orderedGalleryItemIds: z.array(uuidSchema).min(1),
+})
+    .strict();
+// --- Feature 002 — Attachments (US3) ----------------------------------------
+export const attachmentTypeSchema = z.object({
+    id: uuidSchema,
+    code: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z0-9_]+$/, 'must be snake_case'),
+    name: multilingualStringSchema,
+    position: z.number().int().nonnegative(),
+    usageCount: z.number().int().nonnegative(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const createAttachmentTypeRequestSchema = z
+    .object({
+    code: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z0-9_]+$/, 'must be snake_case'),
+    name: multilingualStringSchema,
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const updateAttachmentTypeRequestSchema = z
+    .object({
+    code: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z0-9_]+$/, 'must be snake_case')
+        .optional(),
+    name: multilingualStringSchema.optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const productAttachmentSchema = z.object({
+    id: uuidSchema,
+    productId: uuidSchema,
+    assetId: uuidSchema,
+    attachmentTypeId: uuidSchema,
+    name: z.string().min(1).max(160),
+    description: z.string().nullable(),
+    position: z.number().int().nonnegative(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const createAttachmentRequestSchema = z
+    .object({
+    assetId: uuidSchema,
+    attachmentTypeId: uuidSchema,
+    name: z.string().min(1).max(160),
+    description: z.string().nullable().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const updateAttachmentRequestSchema = z
+    .object({
+    attachmentTypeId: uuidSchema.optional(),
+    name: z.string().min(1).max(160).optional(),
+    description: z.string().nullable().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+// --- Packaging Units (Feature 043) ------------------------------------------
+/**
+ * A named ordering unit attached to a product (e.g. "Paleta" = 480 pieces).
+ * Managed in the Inventory section of the admin product card; surfaced on the
+ * storefront product page so buyers can order by the unit.
+ */
+export const packagingUnitSchema = z.object({
+    id: uuidSchema,
+    productId: uuidSchema,
+    name: z.string().min(1).max(160),
+    baseQuantity: z.number().int().positive(),
+    position: z.number().int().nonnegative(),
+    isDefault: z.boolean(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const createPackagingUnitRequestSchema = z
+    .object({
+    name: z.string().trim().min(1).max(160),
+    baseQuantity: z.number().int().positive(),
+    isDefault: z.boolean().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const updatePackagingUnitRequestSchema = z
+    .object({
+    name: z.string().trim().min(1).max(160).optional(),
+    baseQuantity: z.number().int().positive().optional(),
+    isDefault: z.boolean().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const reorderPackagingUnitsRequestSchema = z
+    .object({
+    orderedIds: z.array(uuidSchema).min(1),
+})
+    .strict();
+// --- Product Links (Feature 002 US4) ----------------------------------------
+export const productLinkKindSchema = z.enum(['related', 'up_sell', 'cross_sell']);
+export const productLinkSchema = z.object({
+    id: uuidSchema,
+    sourceProductId: uuidSchema,
+    targetProductId: uuidSchema,
+    kind: productLinkKindSchema,
+    position: z.number().int().nonnegative(),
+});
+/**
+ * Bulk-create payload (T104). One transaction, all-or-nothing —
+ * partial inserts on a duplicate or self-link MUST roll back the
+ * entire batch (FR + research). Each entry pins its kind so admins
+ * can submit a mixed batch in a single round trip.
+ */
+export const bulkCreateLinksRequestSchema = z.object({
+    links: z
+        .array(z.object({
+        targetProductId: uuidSchema,
+        kind: productLinkKindSchema,
+        position: z.number().int().nonnegative().optional(),
+    }))
+        .min(1),
+});
+export const reorderLinksRequestSchema = z.object({
+    /** Ordered list of link ids — index becomes `position` per (source, kind). */
+    linkIds: z.array(uuidSchema).min(1),
+});
+/**
+ * Storefront-shape link entry (T107) — the listing carries enough Product
+ * fields for a card render without a follow-up fetch. Inactive targets
+ * are filtered out by `listForStorefront` so the storefront never sees
+ * `status='archived'` rows.
+ */
+// --- Composite products (Feature 002 US5) -----------------------------------
+export const groupedItemSchema = z.object({
+    id: uuidSchema,
+    parentProductId: uuidSchema,
+    childProductId: uuidSchema,
+    quantity: z.number().int().positive(),
+    position: z.number().int().nonnegative(),
+});
+export const createGroupedItemRequestSchema = z
+    .object({
+    childProductId: uuidSchema,
+    quantity: z.number().int().positive(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const updateGroupedItemRequestSchema = z
+    .object({
+    quantity: z.number().int().positive().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const bundleSlotOptionSchema = z.object({
+    id: uuidSchema,
+    slotId: uuidSchema,
+    optionProductId: uuidSchema,
+    defaultQuantity: z.number().int().positive(),
+    position: z.number().int().nonnegative(),
+});
+export const bundleSlotSchema = z.object({
+    id: uuidSchema,
+    parentProductId: uuidSchema,
+    name: multilingualStringSchema,
+    minQuantity: z.number().int().nonnegative(),
+    maxQuantity: z.number().int().positive(),
+    position: z.number().int().nonnegative(),
+    options: z.array(bundleSlotOptionSchema),
+});
+export const createBundleSlotRequestSchema = z
+    .object({
+    name: multilingualStringSchema,
+    minQuantity: z.number().int().nonnegative().optional(),
+    maxQuantity: z.number().int().positive(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict()
+    .refine((v) => (v.minQuantity ?? 0) <= v.maxQuantity, {
+    message: 'minQuantity must be <= maxQuantity',
+    path: ['minQuantity'],
+});
+export const updateBundleSlotRequestSchema = z
+    .object({
+    name: multilingualStringSchema.optional(),
+    minQuantity: z.number().int().nonnegative().optional(),
+    maxQuantity: z.number().int().positive().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const createBundleSlotOptionRequestSchema = z
+    .object({
+    optionProductId: uuidSchema,
+    defaultQuantity: z.number().int().positive().optional(),
+    position: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/**
+ * Buyer's bundle configuration — what the storefront posts to the
+ * `/bundle-configuration/validate` endpoint. One selection per slot,
+ * referencing the chosen option's id and the buyer-picked quantity.
+ */
+export const bundleConfigurationSelectionSchema = z.object({
+    slotId: uuidSchema,
+    optionId: uuidSchema,
+    quantity: z.number().int().positive(),
+});
+export const validateBundleConfigurationRequestSchema = z
+    .object({
+    selections: z.array(bundleConfigurationSelectionSchema),
+})
+    .strict();
+export const bundleValidationErrorSchema = z.object({
+    code: z.enum(['MIN_NOT_MET', 'MAX_EXCEEDED', 'UNKNOWN_OPTION']),
+    slotId: uuidSchema.optional(),
+    message: z.string(),
+});
+export const bundleValidationResultSchema = z.object({
+    valid: z.boolean(),
+    errors: z.array(bundleValidationErrorSchema),
+    resolvedSelections: z.array(z.object({
+        slotId: uuidSchema,
+        optionId: uuidSchema,
+        optionProductId: uuidSchema,
+        quantity: z.number().int().positive(),
+    })),
+});
+export const productLinkSummarySchema = z.object({
+    id: uuidSchema,
+    kind: productLinkKindSchema,
+    position: z.number().int().nonnegative(),
+    product: z.object({
+        id: uuidSchema,
+        sku: z.string(),
+        slug: z.string(),
+        name: z.string(),
+        primaryAssetUrl: z.string().nullable(),
+        price: moneySchema.nullable(),
+    }),
+});
+/**
+ * The most restrictive audience there is. Anything it may see, every other
+ * audience may see too — which is what makes it the right default for a path
+ * that has not yet been taught to resolve its caller, and the right constant
+ * for a test that means "the public".
+ */
+export const ANONYMOUS_PRODUCT_AUDIENCE = {
+    organizationId: null,
+    authenticated: false,
+};
+/**
+ * Does this audience get to see this product?
+ *
+ * **This is the platform's one answer.** `Product.visibility` and
+ * `Product.allowedOrganizationIds` have been persisted, defaulted and
+ * operator-editable since the foundation migration, and until issue #227 a
+ * single read path out of two dozen enforced them — `catalog`'s quick-search,
+ * repaired for issue #174 after a buyer's type-ahead disclosed products
+ * restricted to other organisations. Every other surface answered the question
+ * its own way or not at all, so the repair starts by making the question have
+ * one answer that a listing, a PDP, a search hit, a cart line, a comparison and
+ * a feed row can all reach.
+ *
+ * It lives in `@endora-commerce/contracts` rather than in `catalog` because the record it
+ * reads is already published here: twenty modules hold a
+ * {@link CatalogProductRecord}, both columns are on it, and a predicate over a
+ * published shape needs no port, no manifest edge and no `catalog` on the other
+ * end of a call. A module that holds the row can enforce; a module that cannot
+ * hold the row has nothing to enforce over.
+ *
+ * The rule, in the order it is decided:
+ *
+ *  1. **A non-empty `allowedOrganizationIds` decides alone**, and it restricts
+ *     whatever `visibility` says — `public` included. `public` with an
+ *     allow-list naming three organisations is a state an operator can save
+ *     today, and reading it as "public wins" discloses exactly the rows the
+ *     operator named someone else on.
+ *  2. Otherwise the allow-list is empty and the answer is `visibility`'s alone:
+ *     `public` to everybody; `logged_in_only` to any authenticated caller;
+ *     `organization_restricted` **to nobody**. That last one is the reading
+ *     that surprises: the restriction was asked for and names no organisation,
+ *     so the permissive reading of it would disclose the row to the whole
+ *     world.
+ *
+ * ## The two SQL restatements of this rule, and how they differ
+ *
+ * A predicate over a record cannot be pushed into a query, and two read paths
+ * must filter in SQL rather than after it. So `catalog` states this rule twice
+ * more, in SQL, and the two statements are **not** copies of each other — they
+ * answer for different audiences and are meant to differ (issue #262):
+ *
+ *  - **`catalog-quick-search.service.ts`** answers for a **signed-in buyer**.
+ *    `CatalogQuickSearchParams.organizationId` is required and there is no
+ *    anonymous spelling, so the audience is
+ *    `{ organizationId, authenticated: true }` by construction. It is the
+ *    restatement where `@>` containment over the JSONB array does real work:
+ *    the buyer's id has to be an *element* of the allow-list rather than a
+ *    substring of the serialised bag. It is SQL because the statement carries
+ *    a `limit`, and a post-filter would hand a buyer a short page — or an
+ *    empty one — while visible rows waited behind the restricted ones.
+ *  - **`catalog-product-filter.service.ts`'s `sellableFloor`** answers for
+ *    {@link ANONYMOUS_PRODUCT_AUDIENCE}, because the port's only consumer is a
+ *    product feed and a feed is read by Google. With no organisation to
+ *    contain, the containment branch can never match, so that restatement
+ *    collapses to two equalities — `visibility = 'public'` and an empty
+ *    allow-list. It is SQL because `countSellable` is the number an operator
+ *    is shown before saving and `listSellable` is what the next run emits, and
+ *    the two must be one query's answer.
+ *
+ * Neither is licensed to drift toward the other: the containment clause would
+ * be dead weight in the feed floor, and the two equalities would hide from a
+ * buyer every row his own organisation is named on. What keeps both honest is
+ * that each has a parity test which **derives** its expectation from this
+ * function over `productVisibilitySchema.options`, so a fourth visibility value
+ * forces every side to be decided rather than letting one keep an accidental
+ * default — this predicate falls through to `return true`, both SQL sites fail
+ * closed:
+ *
+ *  - `backend/test/integration/catalog/quick-search-audience-parity.test.ts`
+ *    — visibility × (empty, own org, another org, several including own,
+ *    a near-miss string) × three viewers;
+ *  - `backend/test/integration/catalog/product-filter-port.test.ts`
+ *    — visibility × (empty, non-empty) for the anonymous audience, on
+ *    `listSellable` and `countSellable` alike.
+ *
+ * `backend/test/unit/catalog/product-visibility-predicate.test.ts` is the truth
+ * table all three are read against.
+ *
+ * Unifying the three into one shared SQL fragment was considered and refused:
+ * the builder would have to live here, and a fragment knows table and column
+ * names — the persistence shape. This package knows API shapes and depends on
+ * `zod` alone (FR-034). Keeping that line is worth more than removing the
+ * duplication, so the duplication is kept and pinned instead.
+ *
+ * What this predicate is **not** is the channel answer. Channel scoping is
+ * Principle XII's, travels through `sales_channel_products` and the sanctioned
+ * bridge accessors, and is a second filter every buyer-facing path owes on top
+ * of this one.
+ *
+ * That second filter has two spellings and neither is here, by an owner ruling
+ * of 2026-08-21 (issue #259): the channel is a property of the **request**, not
+ * of the viewer's relationship to the product, so folding it in would merge two
+ * questions and make this predicate asynchronous. The **view** side spells it
+ * as `CatalogQueryService.filterByChannel`; the **acquisition** side — cart
+ * add, comparison add, a quote line, a saved list, a pasted quick-order SKU —
+ * spells it as `productIdsInRequestChannel` in
+ * `backend/src/kernel/sales-channels/request-channel-assortment.ts`. Every one
+ * of those refuses out-of-assortment with the *same* answer it gives a
+ * restricted row and an absent one, so the pair cannot be used to enumerate an
+ * operator's private assortment.
+ *
+ * **Two re-acquisition paths are exempt, by the same ruling**: `orders`'
+ * reorder and `quote_requests`' `convertToOrder`. Neither names a product the
+ * caller supplied — each rebuilds a cart from lines the buyer already holds a
+ * commitment on, a placed order or a quote the seller approved at agreed
+ * prices — and refusing would strand a buyer holding an approved quote they
+ * cannot act on. Read that as decided, not as the two seams that were missed;
+ * each carries the reason at its own call site, including the second-order
+ * consequence that makes the obvious repair of the first one wrong. Two
+ * operator surfaces are exempt on the operator's-permission ground instead:
+ * `RfqAdminService.createOnBehalf` and `quick_order`'s `'unrestricted'` import
+ * arm, both of which say so where they stand.
+ */
+export function isProductVisibleTo(product, audience) {
+    const allowed = product.allowedOrganizationIds ?? [];
+    if (allowed.length > 0) {
+        return audience.organizationId !== null && allowed.includes(audience.organizationId);
+    }
+    if (product.visibility === 'organization_restricted')
+        return false;
+    if (product.visibility === 'logged_in_only')
+        return audience.authenticated;
+    return true;
+}
+/**
+ * Scope flags for the **system** product attributes — the ones that are not
+ * rows in `product_attributes` and therefore carry no DB-stored scope flags.
+ *
+ * Published as a **constant, not a port** (FR-013): `name` and `description`
+ * are channel- and language-scoped because the product table stores them as
+ * per-locale JSONB, which is a fact about the schema rather than about whether
+ * a module is switched on. `search`'s indexer reads it to decide which
+ * overrides to resolve.
+ *
+ * Adding another system attribute is a one-line change here plus a resolver
+ * consumer. The reserved keys MUST NOT collide with `product_attributes.key`
+ * — enforced at write time by the override-service validator.
+ */
+export const SYSTEM_ATTRIBUTE_SCOPES = {
+    name: { channelScoped: true, languageScoped: true },
+    description: { channelScoped: true, languageScoped: true },
+};
+export function isSystemAttributeKey(key) {
+    return Object.prototype.hasOwnProperty.call(SYSTEM_ATTRIBUTE_SCOPES, key);
+}
+/**
+ * Resolve the effective scope of an attribute given its key and (for
+ * user-defined attributes) its scope flags. Returns the system-pinned scope
+ * when the key is reserved; falls back to the row's flags otherwise; returns
+ * `{ false, false }` when neither applies (the caller should treat that as
+ * global-only).
+ */
+export function getAttributeScope(attributeKey, productAttributeRow) {
+    if (isSystemAttributeKey(attributeKey)) {
+        // Keyed by `SystemAttributeKey`, so the lookup is non-undefined here; TS'
+        // index signature still widens under `noUncheckedIndexedAccess`.
+        return SYSTEM_ATTRIBUTE_SCOPES[attributeKey];
+    }
+    if (productAttributeRow) {
+        return {
+            channelScoped: productAttributeRow.channelScoped,
+            languageScoped: productAttributeRow.languageScoped,
+        };
+    }
+    return { channelScoped: false, languageScoped: false };
+}
+//# sourceMappingURL=catalog.js.map