Catalog & pricing

interface Brand {
  id: Uuid;
  name: string;                 // unique: "HOCO", "ACEFAST", "BOROFONE"
  slug: string;                 // "hoco"
  logo?: FileRef;               // BRAND_LOGO, public
  description?: string;
  status: "ACTIVE" | "ARCHIVED";
  sortOrder: number;
  productCount: number;         // non-archived products
  createdAt: Iso; updatedAt: Iso; version: number;
}

interface Category {
  id: Uuid;
  name: string;                 // unique among siblings
  slug: string;
  parentId: Uuid | null;        // null = top-level category; set = sub-category (max depth 2)
  path: { id: Uuid; name: string }[];   // from the root, this category included
  icon?: FileRef;
  sortOrder: number;
  status: "ACTIVE" | "ARCHIVED";
  productCount: number;         // including sub-categories
  attributeIds: Uuid[];         // attribute definitions that apply here (own + inherited from the parent)
  children?: Category[];        // tree format only
  createdAt: Iso; updatedAt: Iso; version: number;
}

interface AttributeDefinition {
  id: Uuid;
  key: string;                  // snake_case, unique, immutable: "power_w", "connector"
  label: { fr: string; ar?: string; en?: string };
  type: "NUMBER" | "ENUM" | "BOOLEAN" | "TEXT";     // AttributeType
  unit?: string;                // NUMBER: "W", "mAh", "m"
  decimals?: number;            // NUMBER: 0–2
  values?: { code: string; label: { fr: string; ar?: string; en?: string }; sortOrder: number; active: boolean }[];   // ENUM
  multiValue: boolean;          // ENUM: a variant may carry several values (e.g. connectors of a 3-in-1 cable)
  categoryIds: Uuid[];          // applies to these categories and their sub-categories
  filterable: boolean;          // shown as a filter in the reseller apps
  filterWidget: "CHECKBOX" | "RANGE" | "TOGGLE" | "NONE";   // FilterWidget: ENUM → CHECKBOX, NUMBER → RANGE or CHECKBOX, BOOLEAN → TOGGLE
  requiredToPublish: boolean;   // every active variant needs a value before the product can be published
  minValue?: number;            // NUMBER: lowest accepted value (contract 1.1.0)
  maxValue?: number;            // NUMBER: highest accepted value (contract 1.1.0)
  showOnProductSheet: boolean;  // listed in the product sheet's specifications (contract 1.1.0); filters and variant choice keep it either way
  sortOrder: number;
  status: "ACTIVE" | "ARCHIVED";
  variantCount: number;         // variants carrying a value
  createdAt: Iso; updatedAt: Iso; version: number;
}

interface AdminVariant {
  id: Uuid;
  sku: string;                  // unique, immutable once ordered: "HC-X14-CC-1M-BK"
  barcode?: string;             // EAN-13 / UPC, unique
  name: string;                 // "Noir · 1 m"
  attributes: Record<string, string | number | boolean | string[]>;   // VariantAttributeValue by attribute key
  priceSuperGros: Money;        // HT — price of SUPER_GROS resellers
  priceDemiGros: Money;         // HT — DEMI_GROS
  priceDetail: Money;           // HT — DETAIL
  pricesTtc: { superGros: Money; demiGros: Money; detail: Money };    // computed with vatRate
  vatRate: BasisPoints;
  recommendedPrice?: Money;     // prix conseillé public, TTC
  purchasePrice?: Money;        // HT — only with pricing.view
  marginsBps?: { superGros: number; demiGros: number; detail: number };   // (price − purchase) ÷ price — only with pricing.view
  minQty: number;               // ≥ 1
  qtyStep: number;              // ≥ 1; quantities must be minQty + k × qtyStep
  maxQtyPerOrder?: number;
  weightGrams?: number;
  status: "ACTIVE" | "HIDDEN" | "ARCHIVED";   // ProductStatus subset
  isDefault: boolean;
  stock: { physical: number; reserved: number; available: number; alertLevel: "OK" | "LOW" | "OUT" };   // all warehouses
  availability: "IN_STOCK" | "OUT_OF_STOCK";  // what resellers see
  createdAt: Iso; updatedAt: Iso; version: number;
}

interface AdminProduct {
  id: Uuid;
  reference: string;            // unique per brand: "HC-X14"
  name: string;
  slug: string;
  brand: { id: Uuid; name: string };
  category: { id: Uuid; name: string; parentId: Uuid | null; path: { id: Uuid; name: string }[] };
  description: string;          // plain text with line breaks, ≤ 5 000
  specs: { label: string; value: string }[];   // free technical characteristics (cahier §15.4)
  warranty?: { months: number; text?: string };
  status: ProductStatus;        // DRAFT, ACTIVE, HIDDEN, OUT_OF_STOCK, ARCHIVED
  publishedAt?: Iso;
  isNew: boolean;               // publishedAt within catalog.newProductDays
  images: { id: Uuid; file: FileRef; sortOrder: number; alt?: string; variantId?: Uuid }[];
  variants: AdminVariant[];
  defaultVariantId: Uuid;
  visibility: { mode: "EVERYONE" | "INCLUDE_ONLY" | "EXCLUDE"; segments: { id: Uuid; name: string }[]; resellers: ResellerSummary[] };
  completeness: { publishable: boolean; missing: string[] };   // e.g. ["images", "variants[0].attributes.power_w"]
  activePromotions: { id: Uuid; name: string; endsAt: Iso }[];
  createdAt: Iso; updatedAt: Iso; version: number;
}

{
  "items": [
    { "id": "01928a01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "name": "HOCO", "slug": "hoco", "logo": { "id": "01928a02-1a2b-7c3d-8e4f-5a6b7c8d9e02", "url": "https://cdn.hoco.dz/brands/hoco.svg", "mimeType": "image/svg+xml", "size": 4211, "purpose": "BRAND_LOGO" }, "status": "ACTIVE", "sortOrder": 1, "productCount": 412, "createdAt": "2026-10-20T08:00:00Z", "updatedAt": "2026-10-20T08:00:00Z", "version": 1 },
    { "id": "01928a01-2b3c-7d4e-9f5a-6b7c8d9e0f12", "name": "ACEFAST", "slug": "acefast", "status": "ACTIVE", "sortOrder": 2, "productCount": 138, "createdAt": "2026-10-20T08:00:00Z", "updatedAt": "2026-10-20T08:00:00Z", "version": 1 }
  ],
  "total": 3,
  "page": 1,
  "pageSize": 25
}

interface CreateBrandBody { name: string; logoFileId?: Uuid; description?: string; sortOrder?: number }

{ "name": "BOROFONE", "logoFileId": "01928a02-3c4d-7e5f-8a6b-7c8d9e0f1a2b", "sortOrder": 3 }

interface UpdateBrandBody { name?: string; logoFileId?: Uuid | null; description?: string | null; sortOrder?: number; status?: "ACTIVE" | "ARCHIVED"; version: number }

{ "sortOrder": 1, "version": 1 }

{ "id": "01928a01-9f0a-7b1c-8d2e-3f4a5b6c7d8e", "result": "ARCHIVED", "references": [{ "entityType": "Product", "count": 3 }] }

{
  "items": [
    {
      "id": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "name": "Câbles", "slug": "cables", "parentId": null,
      "path": [{ "id": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "name": "Câbles" }],
      "sortOrder": 2, "status": "ACTIVE", "productCount": 186,
      "attributeIds": ["0192b100-3c4d-7e5f-9a6b-7c8d9e0f1a2b", "0192b100-4d5e-7f6a-8b7c-8d9e0f1a2b3c", "0192b100-5e6f-7a7b-9c8d-9e0f1a2b3c4d"],
      "createdAt": "2026-10-20T08:10:00Z", "updatedAt": "2026-10-20T08:10:00Z", "version": 1,
      "children": [
        {
          "id": "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12", "name": "Câbles USB-C", "slug": "cables-usb-c", "parentId": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01",
          "path": [{ "id": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "name": "Câbles" }, { "id": "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12", "name": "Câbles USB-C" }],
          "sortOrder": 1, "status": "ACTIVE", "productCount": 74,
          "attributeIds": ["0192b100-3c4d-7e5f-9a6b-7c8d9e0f1a2b", "0192b100-4d5e-7f6a-8b7c-8d9e0f1a2b3c", "0192b100-5e6f-7a7b-9c8d-9e0f1a2b3c4d", "0192b100-1a2b-7c3d-9e4f-5a6b7c8d9e01"],
          "createdAt": "2026-10-20T08:11:00Z", "updatedAt": "2026-10-20T08:11:00Z", "version": 1, "children": []
        }
      ]
    }
  ],
  "total": 31
}

interface CreateCategoryBody { name: string; parentId?: Uuid | null; iconFileId?: Uuid; sortOrder?: number }

{ "name": "Câbles Lightning", "parentId": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "sortOrder": 2 }

interface UpdateCategoryBody { name?: string; iconFileId?: Uuid | null; sortOrder?: number; status?: "ACTIVE" | "ARCHIVED"; version: number }

{ "name": "Câbles USB-C et Thunderbolt", "version": 1 }

interface ReorderCategoriesBody {
  items: { id: Uuid; parentId: Uuid | null; sortOrder: number }[];   // the whole tree
}

{
  "items": [
    { "id": "01928b01-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "parentId": null, "sortOrder": 1 },
    { "id": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "parentId": null, "sortOrder": 2 },
    { "id": "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12", "parentId": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "sortOrder": 1 }
  ]
}

{
  "items": [
    {
      "id": "0192b215-6f70-7a81-9b2c-3d4e5f6a7b80",
      "reference": "AF-A29",
      "name": "Chargeur GaN 50 W 2 ports",
      "brand": { "id": "01928a01-2b3c-7d4e-9f5a-6b7c8d9e0f12", "name": "ACEFAST" },
      "category": { "id": "01928b01-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "name": "Chargeurs", "parentId": null },
      "status": "ACTIVE",
      "imageUrl": "https://cdn.hoco.dz/p/af-a29/main-400.webp",
      "variantsCount": 2,
      "defaultVariant": { "id": "0192b215-7a8b-7c9d-8e0f-1a2b3c4d5e6f", "sku": "AF-A29-50W-WH", "priceSuperGros": 195000, "priceDemiGros": 210000, "priceDetail": 230000, "vatRate": 1900 },
      "stock": { "physical": 46, "reserved": 40, "available": 6, "alertLevel": "LOW" },
      "availability": "IN_STOCK",
      "visibilityMode": "EVERYONE",
      "isNew": true,
      "hasPromotion": true,
      "completeness": { "publishable": true, "missing": [] },
      "publishedAt": "2026-10-22T09:00:00Z",
      "updatedAt": "2026-11-02T14:31:00Z"
    }
  ],
  "total": 583,
  "page": 1,
  "pageSize": 25
}

interface CreateProductBody {
  reference: string;                 // unique per brand, 2–40, uppercase letters, digits and "-"
  name: string;                      // 3–150
  brandId: Uuid;
  categoryId: Uuid;                  // a sub-category when the category has children
  description?: string;
  specs?: { label: string; value: string }[];
  warranty?: { months: number; text?: string };
  defaultVariant: {
    sku: string; barcode?: string; name?: string;
    attributes?: Record<string, string | number | boolean | string[]>;
    priceSuperGros?: Money; priceDemiGros?: Money; priceDetail?: Money;   // HT; need pricing.update
    vatRate?: BasisPoints;           // default pricing.defaultVatRate
    recommendedPrice?: Money; purchasePrice?: Money;
    minQty?: number; qtyStep?: number; maxQtyPerOrder?: number; weightGrams?: number;
  };
}

{
  "reference": "HC-X14",
  "name": "Câble USB-C vers USB-C 60 W 1 m",
  "brandId": "01928a01-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "categoryId": "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12",
  "description": "Câble tressé nylon, charge rapide PD jusqu'à 60 W, transfert de données 480 Mb/s.",
  "specs": [{ "label": "Gaine", "value": "Nylon tressé" }, { "label": "Débit", "value": "480 Mb/s" }],
  "warranty": { "months": 6 },
  "defaultVariant": {
    "sku": "HC-X14-CC-1M-BK", "barcode": "6931474761234", "name": "Noir · 1 m",
    "attributes": { "connector": ["USB_C"], "cable_length_m": 1, "power_w": 60, "color": "BLACK" },
    "priceSuperGros": 32000, "priceDemiGros": 35000, "priceDetail": 39000, "vatRate": 1900,
    "recommendedPrice": 55000, "purchasePrice": 21000, "minQty": 5, "qtyStep": 5, "maxQtyPerOrder": 500, "weightGrams": 38
  }
}

{
  "id": "0192b210-4d5e-7f60-8a1b-2c3d4e5f6a70",
  "reference": "HC-X14",
  "name": "Câble USB-C vers USB-C 60 W 1 m",
  "slug": "hoco-hc-x14-cable-usb-c-60w-1m",
  "brand": { "id": "01928a01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "name": "HOCO" },
  "category": { "id": "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12", "name": "Câbles USB-C", "parentId": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "path": [{ "id": "01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01", "name": "Câbles" }, { "id": "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12", "name": "Câbles USB-C" }] },
  "description": "Câble tressé nylon, charge rapide PD jusqu'à 60 W, transfert de données 480 Mb/s.",
  "specs": [{ "label": "Gaine", "value": "Nylon tressé" }, { "label": "Débit", "value": "480 Mb/s" }],
  "warranty": { "months": 6 },
  "status": "ACTIVE",
  "publishedAt": "2026-10-21T10:00:00Z",
  "isNew": true,
  "images": [
    { "id": "0192b210-6a7b-7c8d-9e0f-1a2b3c4d5e6f", "file": { "id": "0192b210-7b8c-7d9e-8f0a-1b2c3d4e5f60", "url": "https://cdn.hoco.dz/p/hc-x14/main.webp", "thumbnailUrl": "https://cdn.hoco.dz/p/hc-x14/main-400.webp", "mimeType": "image/webp", "size": 186410, "purpose": "PRODUCT_IMAGE" }, "sortOrder": 1, "alt": "Câble HOCO X14 noir" }
  ],
  "variants": [
    {
      "id": "0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "sku": "HC-X14-CC-1M-BK",
      "barcode": "6931474761234",
      "name": "Noir · 1 m",
      "attributes": { "connector": ["USB_C"], "cable_length_m": 1, "power_w": 60, "color": "BLACK" },
      "priceSuperGros": 32000,
      "priceDemiGros": 35000,
      "priceDetail": 39000,
      "pricesTtc": { "superGros": 38080, "demiGros": 41650, "detail": 46410 },
      "vatRate": 1900,
      "recommendedPrice": 55000,
      "purchasePrice": 21000,
      "marginsBps": { "superGros": 3438, "demiGros": 4000, "detail": 4615 },
      "minQty": 5,
      "qtyStep": 5,
      "maxQtyPerOrder": 500,
      "weightGrams": 38,
      "status": "ACTIVE",
      "isDefault": true,
      "stock": { "physical": 1240, "reserved": 160, "available": 1080, "alertLevel": "OK" },
      "availability": "IN_STOCK",
      "createdAt": "2026-10-21T09:40:00Z",
      "updatedAt": "2026-10-28T11:02:00Z",
      "version": 3
    }
  ],
  "defaultVariantId": "0192b210-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "visibility": { "mode": "EVERYONE", "segments": [], "resellers": [] },
  "completeness": { "publishable": true, "missing": [] },
  "activePromotions": [],
  "createdAt": "2026-10-21T09:40:00Z",
  "updatedAt": "2026-10-28T11:02:00Z",
  "version": 5
}

interface UpdateProductBody {
  name?: string;
  reference?: string;                // only while no variant has been ordered
  brandId?: Uuid;
  categoryId?: Uuid;
  description?: string;
  specs?: { label: string; value: string }[];   // replaces the list
  warranty?: { months: number; text?: string } | null;
  images?: { id?: Uuid; fileId?: Uuid; sortOrder: number; alt?: string; variantId?: Uuid | null }[];   // full ordered gallery: keep by id, add by fileId; omitted ids are removed
  defaultVariantId?: Uuid;
  version: number;
}

{
  "images": [
    { "id": "0192b210-6a7b-7c8d-9e0f-1a2b3c4d5e6f", "sortOrder": 2 },
    { "fileId": "0193020a-1b2c-7d3e-8f4a-5b6c7d8e9f01", "sortOrder": 1, "alt": "Câble HOCO X14 enroulé" }
  ],
  "version": 5
}

interface SetProductStatusBody { to: "ACTIVE" | "HIDDEN" | "ARCHIVED"; reason?: string; version: number }

{ "to": "ACTIVE", "version": 1 }

interface ProductVisibilityBody {
  mode: "EVERYONE" | "INCLUDE_ONLY" | "EXCLUDE";
  segmentIds: Uuid[];                // ≤ 50
  resellerIds: Uuid[];               // ≤ 500
  version: number;
}

{ "mode": "INCLUDE_ONLY", "segmentIds": ["01929a10-1b2c-7d3e-8f4a-5b6c7d8e9f01"], "resellerIds": [], "version": 6 }

interface CreateVariantBody {
  sku: string;                       // 3–60, uppercase, digits, "-"
  barcode?: string;
  name: string;
  attributes: Record<string, string | number | boolean | string[]>;
  priceSuperGros: Money; priceDemiGros: Money; priceDetail: Money;   // HT
  vatRate?: BasisPoints;
  recommendedPrice?: Money;          // TTC
  purchasePrice?: Money;             // HT
  minQty?: number;                   // default 1
  qtyStep?: number;                  // default 1
  maxQtyPerOrder?: number;
  weightGrams?: number;
  status?: "ACTIVE" | "HIDDEN";      // default ACTIVE
  alertThreshold?: number;           // initial stock alert threshold (default stock.lowThresholdDefault)
  priceChangeReason?: string;
}

{
  "sku": "HC-X14-CC-2M-BK", "barcode": "6931474761241", "name": "Noir · 2 m",
  "attributes": { "connector": ["USB_C"], "cable_length_m": 2, "power_w": 60, "color": "BLACK" },
  "priceSuperGros": 38000, "priceDemiGros": 41000, "priceDetail": 45000, "vatRate": 1900,
  "recommendedPrice": 65000, "purchasePrice": 25000, "minQty": 5, "qtyStep": 5
}

interface UpdateVariantBody extends Partial<Omit<CreateVariantBody, "alertThreshold">> {
  status?: "ACTIVE" | "HIDDEN" | "ARCHIVED";
  isDefault?: boolean;
  priceChangeReason?: string;        // stored on the PriceChange rows (recommended for price changes)
  version: number;
}

{ "priceDemiGros": 36000, "priceDetail": 40000, "priceChangeReason": "Hausse fournisseur de 5 % au 1er novembre.", "version": 3 }

{
  "items": [
    { "id": "01930212-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "field": "PRICE_DETAIL", "before": 39000, "after": 40000, "changedAt": "2026-11-01T07:30:00Z", "changedBy": { "id": "01929e55-2c3d-7e4f-9a1b-2c3d4e5f6a7b", "displayName": "Nadia Belkacem" }, "reason": "Hausse fournisseur de 5 % au 1er novembre.", "source": "MANUAL" },
    { "id": "01930212-2b3c-7d4e-9f5a-6b7c8d9e0f1a", "field": "PRICE_DEMI_GROS", "before": 35000, "after": 36000, "changedAt": "2026-11-01T07:30:00Z", "changedBy": { "id": "01929e55-2c3d-7e4f-9a1b-2c3d4e5f6a7b", "displayName": "Nadia Belkacem" }, "reason": "Hausse fournisseur de 5 % au 1er novembre.", "source": "MANUAL" }
  ],
  "total": 8,
  "page": 1,
  "pageSize": 25
}

{
  "items": [
    {
      "variantId": "0192e0b1-6a7b-7c8d-9e0f-1a2b3c4d5e6f", "productId": "0192e0b1-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
      "productName": "Chargeur rapide 20 W USB-C", "productReference": "ACF-A21", "productStatus": "ACTIVE",
      "variantName": "Noir", "sku": "ACF-A21-BK", "status": "ACTIVE",
      "brand": { "id": "0192d001-…", "name": "ACEFAST" }, "category": { "id": "0192d101-…", "name": "Chargeurs secteur" },
      "priceSuperGros": 38000, "priceDemiGros": 42000, "priceDetail": 48000, "vatRate": 1900, "recommendedPrice": 69000,
      "purchasePrice": 30000, "marginsBps": { "superGros": 2105, "demiGros": 2857, "detail": 3750 },
      "lastChange": { "changedAt": "2026-11-01T07:30:00Z", "changedBy": { "id": "01929e55-…", "displayName": "Nadia Belkacem" } },
      "updatedAt": "2026-11-01T07:30:00Z", "version": 1793518200000
    }
  ],
  "total": 412, "page": 1, "pageSize": 25
}

{
  "reason": "Hausse fournisseur de 5 % au 1er novembre.",
  "items": [
    { "variantId": "0192e0b1-6a7b-7c8d-9e0f-1a2b3c4d5e6f", "version": 1793518200000, "priceDemiGros": 44100, "priceDetail": 50400 },
    { "variantId": "0192e0b1-7b8c-7d9e-8f0a-1b2c3d4e5f60", "version": 1793518200000, "priceSuperGros": 39900 }
  ]
}

{
  "updated": 1,
  "priceChanges": 2,
  "items": [ { "variantId": "0192e0b1-6a7b-7c8d-9e0f-1a2b3c4d5e6f", "priceDemiGros": 44100, "priceDetail": 50400, "…": "a VariantPriceRow, re-read" } ],
  "failed": [ { "variantId": "0192e0b1-7b8c-7d9e-8f0a-1b2c3d4e5f60", "sku": "ACF-A21-WH", "code": "PRICE_ORDER_INVALID", "message": "Prices must be ordered super-gros ≤ demi-gros ≤ détail" } ]
}

{
  "items": [
    {
      "id": "0192b100-1a2b-7c3d-9e4f-5a6b7c8d9e01", "key": "power_w", "label": { "fr": "Puissance", "ar": "القدرة", "en": "Power" },
      "type": "NUMBER", "unit": "W", "decimals": 0, "multiValue": false,
      "categoryIds": ["01928b01-0a1b-7c2d-8e3f-4a5b6c7d8e9f", "01928b02-2b3c-7d4e-9f5a-6b7c8d9e0f12"],
      "filterable": true, "filterWidget": "RANGE", "requiredToPublish": true, "sortOrder": 1, "status": "ACTIVE",
      "variantCount": 311, "createdAt": "2026-10-23T08:00:00Z", "updatedAt": "2026-10-23T08:00:00Z", "version": 1
    },
    {
      "id": "0192b100-3c4d-7e5f-9a6b-7c8d9e0f1a2b", "key": "connector", "label": { "fr": "Connecteur", "en": "Connector" },
      "type": "ENUM", "multiValue": true,
      "values": [
        { "code": "USB_C", "label": { "fr": "USB-C" }, "sortOrder": 1, "active": true },
        { "code": "LIGHTNING", "label": { "fr": "Lightning" }, "sortOrder": 2, "active": true },
        { "code": "MICRO_USB", "label": { "fr": "Micro-USB" }, "sortOrder": 3, "active": true },
        { "code": "USB_A", "label": { "fr": "USB-A" }, "sortOrder": 4, "active": true }
      ],
      "categoryIds": ["01928b01-1a2b-7c3d-8e4f-5a6b7c8d9e01"],
      "filterable": true, "filterWidget": "CHECKBOX", "requiredToPublish": true, "sortOrder": 2, "status": "ACTIVE",
      "variantCount": 402, "createdAt": "2026-10-23T08:05:00Z", "updatedAt": "2026-10-24T10:12:00Z", "version": 2
    }
  ],
  "total": 9,
  "page": 1,
  "pageSize": 50
}

interface CreateAttributeBody {
  key: string;                       // ^[a-z][a-z0-9_]{1,39}$, unique
  label: { fr: string; ar?: string; en?: string };
  type: "NUMBER" | "ENUM" | "BOOLEAN" | "TEXT";
  unit?: string; decimals?: number;
  values?: { code: string; label: { fr: string; ar?: string; en?: string }; sortOrder?: number }[];   // ENUM: 1–100 values, codes UPPER_SNAKE_CASE
  multiValue?: boolean;              // ENUM only
  categoryIds: Uuid[];               // ≥ 1
  filterable?: boolean;              // default true (TEXT: always false)
  filterWidget?: "CHECKBOX" | "RANGE" | "TOGGLE" | "NONE";
  requiredToPublish?: boolean;       // default false
  minValue?: number; maxValue?: number;   // NUMBER only, min ≤ max (contract 1.1.0)
  showOnProductSheet?: boolean;      // default true (contract 1.1.0)
  sortOrder?: number;
}

{
  "key": "capacity_mah", "label": { "fr": "Capacité", "en": "Capacity" }, "type": "NUMBER", "unit": "mAh", "decimals": 0,
  "minValue": 1000, "maxValue": 50000, "showOnProductSheet": true,
  "categoryIds": ["01928b01-3c4d-7e5f-9a6b-7c8d9e0f1a2b"], "filterable": true, "filterWidget": "RANGE", "requiredToPublish": true
}

interface UpdateAttributeBody {
  label?: { fr: string; ar?: string; en?: string };
  unit?: string | null; decimals?: number;
  values?: { code: string; label: { fr: string; ar?: string; en?: string }; sortOrder?: number; active?: boolean }[];   // full list; codes cannot be removed while used — deactivate them
  categoryIds?: Uuid[];
  filterable?: boolean; filterWidget?: "CHECKBOX" | "RANGE" | "TOGGLE" | "NONE";
  requiredToPublish?: boolean; sortOrder?: number;
  status?: "ACTIVE" | "ARCHIVED";
  version: number;
}

{ "values": [
  { "code": "USB_C", "label": { "fr": "USB-C" }, "sortOrder": 1 },
  { "code": "LIGHTNING", "label": { "fr": "Lightning" }, "sortOrder": 2 },
  { "code": "MICRO_USB", "label": { "fr": "Micro-USB" }, "sortOrder": 3 },
  { "code": "USB_A", "label": { "fr": "USB-A" }, "sortOrder": 4 },
  { "code": "MAGSAFE", "label": { "fr": "MagSafe" }, "sortOrder": 5 }
], "version": 2 }

interface PriceList {                       // V2
  id: Uuid;
  name: string;
  type: "AGREEMENT" | "LEVEL";              // V2: per-reseller agreement, or a loyalty-level list
  resellers: ResellerSummary[];             // AGREEMENT
  loyaltyLevels?: LoyaltyLevel[];           // LEVEL
  validFrom?: string; validTo?: string;     // YYYY-MM-DD, inclusive
  priority: number;                         // higher wins when several apply
  status: "ACTIVE" | "INACTIVE";
  itemCount: number;
  createdAt: Iso; updatedAt: Iso; version: number;
}

interface ProductImportBody {
  mode: "DRY_RUN" | "APPLY";
  fileId?: Uuid;                     // DRY_RUN: completed upload, purpose IMPORT_FILE
  dryRunId?: Uuid;                   // APPLY: the successful dry run to apply
  options?: {
    updateExisting?: boolean;        // default true — rows whose SKU exists update the variant (and its product)
    createMissingBrands?: boolean;   // default false
    createMissingCategories?: boolean;   // default false
    targetStatus?: "DRAFT" | "ACTIVE";   // default DRAFT for new products; ACTIVE only when complete
    images?: "URLS" | "NONE";        // default URLS: download image_urls (https, ≤ 5 MB each)
  };
}

{ "mode": "DRY_RUN", "fileId": "01930300-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "options": { "updateExisting": true, "targetStatus": "DRAFT" } }

{
  "id": "01930300-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
  "type": "PRODUCTS",
  "mode": "DRY_RUN",
  "status": "QUEUED",
  "file": { "id": "01930300-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "url": "https://files.hoco.dz/s/catalogue-hoco-nov.xlsx?sig=…", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "size": 812400, "purpose": "IMPORT_FILE" },
  "options": { "updateExisting": true, "createMissingBrands": false, "createMissingCategories": false, "targetStatus": "DRAFT", "images": "URLS" },
  "createdBy": { "id": "01929e66-3d4e-7f5a-8b6c-7d8e9f0a1b2c", "displayName": "Sofiane Hamdi" },
  "createdAt": "2026-11-04T07:30:00Z"
}

interface ExportProductsBody {
  format: "XLSX" | "CSV" | "PDF";    // PDF = printable price catalogue (no purchase price)
  filters: Record<string, unknown>;  // GET /admin/products query
  columns?: string[];                // default: the import template columns the caller may see
  includeStock?: boolean;            // adds physical / reserved / available per warehouse
}

{ "format": "XLSX", "filters": { "brandId": ["01928a01-2b3c-7d4e-9f5a-6b7c8d9e0f12"], "status": ["ACTIVE", "OUT_OF_STOCK"] }, "includeStock": true }