@agence-zef/sdk 0.14.1 → 0.15.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigCollections, CustomValuesOf, Registry, ZefConfig } from "@agence-zef/schema";
-import type { ApiAccess, ApiAccount, ApiAccountSession, ApiAccountUpdate, ApiCart, ApiCheckout, ApiCheckoutInput, ApiGiftCardInput, ApiItem, ApiLayout, ApiLink, ApiList, ApiOrder, ApiPage, ApiPageEntry, ApiPlayback, ApiPreviewDocument, ApiRedirect, ApiRegisterInput, ApiSection, ApiServicePoint, ApiShippingOption, ApiSite, ApiSubscription, ApiSyncResult } from "./types.js";
+import type { ApiAccess, ApiAccount, ApiAccountSession, ApiAccountUpdate, ApiCart, ApiCategoryItem, ApiCharacteristic, ApiCheckout, ApiCheckoutInput, ApiGiftCardInput, ApiItem, ApiLayout, ApiLink, ApiList, ApiOrder, ApiPage, ApiPageEntry, ApiPlayback, ApiPreviewDocument, ApiProductList, ApiProductSort, ApiRedirect, ApiRegisterInput, ApiSection, ApiServicePoint, ApiShippingOption, ApiSite, ApiSubscription, ApiSyncResult } from "./types.js";
 export { businessJsonLd } from "./business.js";
 export type * from "./types.js";
 /** Erreur renvoyée par l'API (clé invalide, schéma refusé…). */
@@ -45,6 +45,22 @@ export declare function createClient<C extends ZefConfig = ZefConfig>(options: C
     item: <K extends keyof Collections<C> & string>(name: K, slug: string, opts?: LocaleOption & {
         visitor?: Visitor;
     }) => Promise<Collections<C>[K] | null>;
+    /**
+     * Produits de la boutique, filtrés et triés (M-13) : `category` (identifiant ou slug, avec ses
+     * sous-catégories sauf `direct`), `filters` (un paramètre par caractéristique :
+     * `{ couleur: ["noir"], contenance: "20-50", price: "0-30", inStock: "true" }`), `sort`. La
+     * réponse porte aussi les filtres à proposer avec leurs compteurs (`filters`).
+     */
+    products: (opts?: LocaleOption & {
+        category?: string;
+        direct?: boolean;
+        filters?: Record<string, string | string[] | undefined>;
+        sort?: ApiProductSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<ApiProductList>;
+    /** Catégories de la boutique, dans l'ordre de l'arbre (M-12). */
+    categories: (opts?: LocaleOption) => Promise<ApiCategoryItem[]>;
     /** Header et footer du site (sections partagées par toutes les pages). */
     layout: (opts?: LocaleOption) => Promise<ApiLayout>;
     /** Aperçu : header et footer en brouillon, champs marqués pour l'overlay. */
@@ -102,6 +118,8 @@ export declare function createClient<C extends ZefConfig = ZefConfig>(options: C
     };
     /** Boutique (module commerce) : panier, paiement et commandes du compte connecté. */
     shop: {
+        /** Caractéristiques de la boutique (filtres et fiche produit), dans l'ordre (M-13). */
+        characteristics: (opts?: LocaleOption) => Promise<ApiCharacteristic[]>;
         /**
          * Panier ; avec `promoCode`, la remise ou la raison du refus (`promoError`) ; avec `giftCard`,
          * le solde disponible de la carte (`giftCardError` sinon).

package/dist/index.js

@@ -74,6 +74,24 @@ export function createClient(options) {
             query: opts,
         }), `Collection « ${name} »`),
         item: (name, slug, opts = {}) => request(`/collections/${encodeURIComponent(name)}/${encodeURIComponent(slug)}`, { query: { locale: opts.locale }, headers: visitorHeaders(opts.visitor) }),
+        /**
+         * Produits de la boutique, filtrés et triés (M-13) : `category` (identifiant ou slug, avec ses
+         * sous-catégories sauf `direct`), `filters` (un paramètre par caractéristique :
+         * `{ couleur: ["noir"], contenance: "20-50", price: "0-30", inStock: "true" }`), `sort`. La
+         * réponse porte aussi les filtres à proposer avec leurs compteurs (`filters`).
+         */
+        products: async (opts = {}) => {
+            const { filters, ...rest } = opts;
+            const query = { ...rest };
+            for (const [key, value] of Object.entries(filters ?? {})) {
+                const text = Array.isArray(value) ? value.join(",") : value;
+                if (text)
+                    query[key] = text;
+            }
+            return required(await request("/collections/products", { query }), "Produits");
+        },
+        /** Catégories de la boutique, dans l'ordre de l'arbre (M-12). */
+        categories: async (opts = {}) => required(await request("/collections/product-categories", { query: opts }), "Catégories").items,
         /** Header et footer du site (sections partagées par toutes les pages). */
         layout: async (opts = {}) => required(await request("/layout", { query: opts }), "Header et footer"),
         /** Aperçu : header et footer en brouillon, champs marqués pour l'overlay. */
@@ -157,6 +175,10 @@ function shop(request, required) {
         headers: visitorHeaders(visitor),
     }), "Réponse");
     return {
+        /** Caractéristiques de la boutique (filtres et fiche produit), dans l'ordre (M-13). */
+        characteristics: async (opts = {}) => required(await request("/shop/characteristics", {
+            query: opts,
+        }), "Caractéristiques").characteristics,
         /**
          * Panier ; avec `promoCode`, la remise ou la raison du refus (`promoError`) ; avec `giftCard`,
          * le solde disponible de la carte (`giftCardError` sinon).

package/dist/types.d.ts

@@ -217,10 +217,17 @@ export type ApiProduct = {
     /** Taux de TVA en points de base (2000 = 20 %). */
     vatRate: number;
     available: boolean;
-    categories: {
-        id: string;
-        name: string;
-    }[];
+    /** Catégories du produit (M-12), chacune avec ses parentes (`path`). */
+    categories: ApiProductCategory[];
+    /** Catégorie principale : fil d'Ariane et données structurées ; `null` sans catégorie. */
+    mainCategory: ApiProductCategory | null;
+    /** Caractéristiques « Fiche » renseignées, dans l'ordre de la boutique (M-13). */
+    characteristics: ApiProductCharacteristic[];
+    /**
+     * Variante qui remplit les filtres sur les variantes (couleur, contenance, prix, stock) ;
+     * le prix affiché (`price`) est alors le sien. Absent sans filtre de variante.
+     */
+    matchedVariant?: string;
     media: ApiProductMedia[];
     thumbnail: ApiProductMedia | null;
     options: {
@@ -263,6 +270,110 @@ export type ApiProduct = {
         thumbnail: ApiProductMedia | null;
     }[];
 };
+/** Types de caractéristiques (M-13). */
+export type ApiCharacteristicType = "choice" | "multi" | "boolean" | "number" | "color" | "text";
+/** Caractéristique de la boutique (`GET /shop/characteristics`). */
+export type ApiCharacteristic = {
+    /** Nom technique, dans l'adresse des filtres (`couleur`). */
+    key: string;
+    label: string;
+    type: ApiCharacteristicType;
+    /** Où elle se remplit : sur le produit, ou sur chaque variante. */
+    appliesTo: "product" | "variants";
+    unit: string | null;
+    values: {
+        key: string;
+        label: string;
+        color?: string;
+    }[];
+    /** Catégories concernées (identifiants), vide : toutes. */
+    categories: string[];
+    /** Proposée comme filtre ; affichée sur la fiche produit. */
+    filter: boolean;
+    sheet: boolean;
+};
+/** Caractéristique renseignée d'un produit (tableau de la fiche). */
+export type ApiProductCharacteristic = {
+    key: string;
+    label: string;
+    type: ApiCharacteristicType;
+    /** Clé de valeur (liste, couleur), clés (liste multiple), `true`, nombre ou texte. */
+    value: string | string[] | boolean | number;
+    /** Texte affiché : « Noir, Blanc », « 75 cl », « Oui ». */
+    display: string;
+};
+/**
+ * Filtre d'une liste de produits (`filters` de `GET /collections/products`), dans l'ordre de la
+ * boutique ; seulement ceux qu'au moins un produit de la liste renseigne. Les compteurs suivent les
+ * autres filtres choisis ; une valeur à 0 est grisée.
+ */
+export type ApiFilter = {
+    key: string;
+    label: string;
+    type: "choice" | "multi" | "color";
+    values: {
+        key: string;
+        label: string;
+        color?: string;
+        count: number;
+        selected: boolean;
+    }[];
+} | {
+    key: string;
+    label: string;
+    type: "boolean" | "stock";
+    count: number;
+    selected: boolean;
+} | {
+    key: string;
+    label: string;
+    type: "number" | "price";
+    unit: string | null;
+    /** Bornes de la liste (prix en centimes) ; `selected` : fourchette choisie. */
+    min: number;
+    max: number;
+    selected: {
+        min: number | null;
+        max: number | null;
+    } | null;
+};
+/** Tri d'une liste de produits. */
+export type ApiProductSort = "position" | "price" | "-price" | "new";
+/** Liste de produits filtrée (`GET /collections/products`). */
+export type ApiProductList = ApiList<ApiItem & {
+    product: ApiProduct;
+}> & {
+    filters: ApiFilter[];
+};
+/** Catégorie vue depuis une autre (parent, fil d'Ariane) ; `url` : `null` sans page en ligne. */
+export type ApiCategoryRef = {
+    id: string;
+    slug: string;
+    title: string;
+    url: string | null;
+};
+/** Catégorie d'un produit : ses parentes du premier niveau au parent (`path`). */
+export type ApiProductCategory = ApiCategoryRef & {
+    /** Même valeur que `title` (forme du lot 14e1). */
+    name: string;
+    path: ApiCategoryRef[];
+};
+/**
+ * Élément de la collection `product-categories` (`GET /collections/product-categories`), servi
+ * dans l'ordre de l'arbre : ses champs, puis sa place dans l'arbre et son nombre de produits
+ * (sous-catégories comprises).
+ */
+export type ApiCategoryItem = ApiItem & {
+    /** Catégorie parente, `null` au premier niveau. */
+    parent: string | null;
+    /** Niveau : 0 au premier niveau. */
+    depth: number;
+    /** Catégories parentes, du premier niveau au parent. */
+    path: ApiCategoryRef[];
+    /** Sous-catégories servies, dans l'ordre. */
+    children: string[];
+    productCount: number;
+};
 /** Ligne du panier (montants TTC en centimes, recalculés par le CMS). */
 export type ApiCartLine = {
     /** Vide pour une carte cadeau (voir `giftCardLineId`). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agence-zef/sdk",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Client typé de l'API d'un CMS ZEF (client.agence-zef.fr/api/v1).",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agence-zef/schema": "0.19.0"
+    "@agence-zef/schema": "0.20.0"
   },
   "homepage": "https://agence-zef.fr",
   "scripts": {