@agence-zef/sdk 0.2.0 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { ConfigCollections, Registry, ZefConfig } from "@agence-zef/schema";
-import type { ApiItem, ApiLayout, ApiLink, ApiList, ApiPage, ApiPageEntry, ApiPreviewDocument, ApiRedirect, ApiSection, ApiSite, ApiSyncResult } from "./types.js";
+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";
 export type * from "./types.js";
 /** Erreur renvoyée par l'API (clé invalide, schéma refusé…). */
 export declare class ZefApiError extends Error {
@@ -27,13 +27,23 @@ export declare function createClient<C extends ZefConfig = ZefConfig>(options: C
     site: () => Promise<ApiSite>;
     /** Toutes les pages publiées et leurs adresses par langue. */
     pages: () => Promise<ApiPageEntry[]>;
-    /** Page par adresse (`/la-cave`, `/en/the-cellar`) ; `null` si elle n'existe pas. */
-    page: (url: string) => Promise<ApiPage | null>;
+    /**
+     * Page par adresse (`/la-cave`, `/en/the-cellar`) ; `null` si elle n'existe pas. Contenu
+     * réservé : avec la session du compte (`visitor`), les sections s'il en a le droit.
+     */
+    page: (url: string, visitor?: Visitor) => Promise<ApiPage | null>;
+    /**
+     * Page ou élément par adresse, avec la session du compte (contenu réservé rendu à la
+     * demande) ; `null` si rien n'est à cette adresse.
+     */
+    document: (url: string, visitor?: Visitor) => Promise<ApiPreviewDocument | null>;
     collection: <K extends keyof Collections<C> & string>(name: K, opts?: LocaleOption & {
         limit?: number;
         offset?: number;
     }) => Promise<ApiList<Collections<C>[K]>>;
-    item: <K extends keyof Collections<C> & string>(name: K, slug: string, opts?: LocaleOption) => Promise<Collections<C>[K] | null>;
+    item: <K extends keyof Collections<C> & string>(name: K, slug: string, opts?: LocaleOption & {
+        visitor?: Visitor;
+    }) => Promise<Collections<C>[K] | null>;
     /** 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. */
@@ -55,7 +65,89 @@ export declare function createClient<C extends ZefConfig = ZefConfig>(options: C
     }) => Promise<ApiSection>;
     /** Vérifie la clé et enregistre le lien du dépôt (`zef link`). */
     link: () => Promise<ApiLink>;
+    /**
+     * Module Comptes : comptes des personnes du site. `session` est le jeton gardé dans le cookie
+     * du site ; `ip` l'adresse du visiteur (limites de débit, anti-robot).
+     */
+    accounts: {
+        /** Inscription : ouvre aussi la session et envoie le lien de vérification. */
+        register: (input: ApiRegisterInput<CustomValuesOf<C, "accounts.account">>, visitor?: Visitor) => Promise<ApiAccountSession<CustomValuesOf<C, "accounts.account">>>;
+        /** Lien de vérification reçu par email. */
+        verify: (token: string) => Promise<{
+            account: ApiAccount<CustomValuesOf<C, "accounts.account">>;
+        }>;
+        resendVerification: (visitor: Visitor, verifyUrl?: string) => Promise<Record<string, never>>;
+        /** Connexion : `ZefApiError` `invalid_credentials` (401) ou `locked` (429) en cas d'échec. */
+        signIn: (email: string, password: string, visitor?: Visitor) => Promise<ApiAccountSession<CustomValuesOf<C, "accounts.account">>>;
+        signOut: (visitor: Visitor) => Promise<Record<string, never>>;
+        /** Envoie le lien de mot de passe oublié s'il existe un compte (réponse identique sinon). */
+        requestPasswordReset: (email: string, resetUrl?: string, visitor?: Visitor) => Promise<Record<string, never>>;
+        resetPassword: (token: string, password: string, visitor?: Visitor) => Promise<Record<string, never>>;
+        /** Compte de la session, ou `null` sans session valable. */
+        me: (visitor: Visitor) => Promise<ApiAccount<CustomValuesOf<C, "accounts.account">> | null>;
+        updateMe: (patch: ApiAccountUpdate<CustomValuesOf<C, "accounts.account">>, visitor: Visitor) => Promise<{
+            account: ApiAccount<CustomValuesOf<C, "accounts.account">>;
+        }>;
+        deleteMe: (password: string, visitor: Visitor) => Promise<Record<string, never>>;
+    };
+    /** Boutique (module commerce) : panier, paiement et commandes du compte connecté. */
+    shop: {
+        /**
+         * Panier ; avec `promoCode`, la remise ou la raison du refus (`promoError`) ; avec `giftCard`,
+         * le solde disponible de la carte (`giftCardError` sinon).
+         */
+        cart: (visitor: Visitor, locale?: string, codes?: {
+            promoCode?: string | null;
+            giftCard?: string | null;
+        }) => Promise<ApiCart>;
+        /** Ajoute une quantité ; `out_of_stock` (409) au-delà du stock disponible. */
+        addToCart: (variantId: string, quantity: number, visitor: Visitor, locale?: string) => Promise<ApiCart>;
+        /** Fixe la quantité d'une ligne (0 la retire). */
+        setCartLine: (variantId: string, quantity: number, visitor: Visitor, locale?: string) => Promise<ApiCart>;
+        /** Ajoute une carte cadeau (montant et destinataire). */
+        addGiftCard: (input: ApiGiftCardInput, visitor: Visitor, locale?: string) => Promise<ApiCart>;
+        removeGiftCard: (lineId: string, visitor: Visitor, locale?: string) => Promise<ApiCart>;
+        clearCart: (visitor: Visitor) => Promise<ApiCart>;
+        /** Modes de livraison proposés pour le panier, selon le pays (`FR` par défaut). */
+        shippingOptions: (visitor: Visitor, country?: string, promoCode?: string | null) => Promise<ApiShippingOption[]>;
+        /** Points relais proches pour un mode à point relais. */
+        servicePoints: (input: {
+            option: string;
+            country: string;
+            postalCode: string;
+        }, visitor: Visitor) => Promise<ApiServicePoint[]>;
+        /** Lance le paiement : commande en attente, stock réservé, facture Stripe. */
+        checkout: (input: ApiCheckoutInput, visitor: Visitor, locale?: string) => Promise<ApiCheckout>;
+        /** Accès du compte aux vidéos. */
+        access: (visitor: Visitor) => Promise<ApiAccess[]>;
+        /**
+         * Liens de lecture d'une vidéo (403 `no_access` sans droit). Une location pas encore
+         * commencée démarre ici : à n'appeler que sur une demande explicite du visiteur.
+         */
+        play: (videoId: string, visitor: Visitor) => Promise<ApiPlayback>;
+        /** Abonnements du compte (en cours et terminés). */
+        subscriptions: (visitor: Visitor) => Promise<ApiSubscription[]>;
+        /** Résilie à la fin de la période payée (accès gardés jusque-là). */
+        cancelSubscription: (id: string, visitor: Visitor) => Promise<{
+            endsAt: string | null;
+        }>;
+        /**
+         * « Changer de carte » : adresse du portail Stripe du client, qui revient sur `returnUrl`
+         * (`url: null` en paiement simulé).
+         */
+        paymentMethod: (id: string, returnUrl: string, visitor: Visitor) => Promise<{
+            url: string | null;
+        }>;
+        orders: (visitor: Visitor) => Promise<ApiOrder[]>;
+        order: (id: string, visitor: Visitor) => Promise<ApiOrder>;
+        /** Paiement simulé (`provider: "simulated"`, développement local seulement). */
+        simulatePayment: (orderId: string, visitor: Visitor) => Promise<Record<string, never>>;
+    };
     /** Envoie le registre du site (`zef sync`). */
     sync: (registry: Registry) => Promise<ApiSyncResult>;
 };
 export type ZefClient<C extends ZefConfig = ZefConfig> = ReturnType<typeof createClient<C>>;
+export type Visitor = {
+    session?: string | null;
+    ip?: string | null;
+};

package/dist/index.js

@@ -28,6 +28,7 @@ export function createClient(options) {
         const res = await doFetch(`${base}${path}${qs}`, {
             method: init.method ?? "GET",
             headers: {
+                ...init.headers,
                 authorization: `Bearer ${options.apiKey}`,
                 ...(init.body === undefined ? {} : { "content-type": "application/json" }),
             },
@@ -55,12 +56,23 @@ export function createClient(options) {
         site: async () => required(await request("/site"), "Site"),
         /** Toutes les pages publiées et leurs adresses par langue. */
         pages: async () => required(await request("/pages"), "Pages").pages,
-        /** Page par adresse (`/la-cave`, `/en/the-cellar`) ; `null` si elle n'existe pas. */
-        page: (url) => request("/pages", { query: { url } }),
+        /**
+         * Page par adresse (`/la-cave`, `/en/the-cellar`) ; `null` si elle n'existe pas. Contenu
+         * réservé : avec la session du compte (`visitor`), les sections s'il en a le droit.
+         */
+        page: (url, visitor) => request("/pages", { query: { url }, headers: visitorHeaders(visitor) }),
+        /**
+         * Page ou élément par adresse, avec la session du compte (contenu réservé rendu à la
+         * demande) ; `null` si rien n'est à cette adresse.
+         */
+        document: (url, visitor) => request("/documents", {
+            query: { url },
+            headers: visitorHeaders(visitor),
+        }),
         collection: async (name, opts = {}) => required(await request(`/collections/${encodeURIComponent(name)}`, {
             query: opts,
         }), `Collection « ${name} »`),
-        item: (name, slug, opts = {}) => request(`/collections/${encodeURIComponent(name)}/${encodeURIComponent(slug)}`, { query: opts }),
+        item: (name, slug, opts = {}) => request(`/collections/${encodeURIComponent(name)}/${encodeURIComponent(slug)}`, { query: { locale: opts.locale }, headers: visitorHeaders(opts.visitor) }),
         /** 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. */
@@ -83,7 +95,112 @@ export function createClient(options) {
         },
         /** Vérifie la clé et enregistre le lien du dépôt (`zef link`). */
         link: async () => required(await request("/link", { method: "POST" }), "Lien"),
+        /**
+         * Module Comptes : comptes des personnes du site. `session` est le jeton gardé dans le cookie
+         * du site ; `ip` l'adresse du visiteur (limites de débit, anti-robot).
+         */
+        accounts: accounts(request, required),
+        /** Boutique (module commerce) : panier, paiement et commandes du compte connecté. */
+        shop: shop(request, required),
         /** Envoie le registre du site (`zef sync`). */
         sync: async (registry) => required(await request("/schema", { method: "POST", body: registry }), "Registre"),
     };
 }
+const visitorHeaders = ({ session, ip } = {}) => ({
+    ...(session ? { "x-zef-account": session } : {}),
+    ...(ip ? { "x-zef-client-ip": ip } : {}),
+});
+function accounts(request, required) {
+    const post = async (path, body, visitor, method = "POST") => required(await request(path, { method, body, headers: visitorHeaders(visitor) }), "Réponse");
+    return {
+        /** Inscription : ouvre aussi la session et envoie le lien de vérification. */
+        register: (input, visitor) => post("/accounts", input, visitor),
+        /** Lien de vérification reçu par email. */
+        verify: (token) => post("/accounts/verify", { token }),
+        resendVerification: (visitor, verifyUrl) => post("/accounts/verify/resend", { verifyUrl }, visitor),
+        /** Connexion : `ZefApiError` `invalid_credentials` (401) ou `locked` (429) en cas d'échec. */
+        signIn: (email, password, visitor) => post("/sessions", { email, password }, visitor),
+        signOut: (visitor) => post("/sessions", undefined, visitor, "DELETE"),
+        /** Envoie le lien de mot de passe oublié s'il existe un compte (réponse identique sinon). */
+        requestPasswordReset: (email, resetUrl, visitor) => post("/password-reset", { email, resetUrl }, visitor),
+        resetPassword: (token, password, visitor) => post("/password-reset/confirm", { token, password }, visitor),
+        /** Compte de la session, ou `null` sans session valable. */
+        me: async (visitor) => {
+            if (!visitor.session)
+                return null;
+            try {
+                return (await post("/me", undefined, visitor, "GET")).account;
+            }
+            catch (error) {
+                if (error instanceof ZefApiError && error.status === 401)
+                    return null;
+                throw error;
+            }
+        },
+        updateMe: (patch, visitor) => post("/me", patch, visitor, "PATCH"),
+        deleteMe: (password, visitor) => post("/me", { password }, visitor, "DELETE"),
+    };
+}
+function shop(request, required) {
+    const call = async (path, visitor, method = "GET", body, locale) => required(await request(path, {
+        method,
+        body,
+        query: locale ? { locale } : undefined,
+        headers: visitorHeaders(visitor),
+    }), "Réponse");
+    return {
+        /**
+         * Panier ; avec `promoCode`, la remise ou la raison du refus (`promoError`) ; avec `giftCard`,
+         * le solde disponible de la carte (`giftCardError` sinon).
+         */
+        cart: async (visitor, locale, codes = {}) => required(await request("/shop/cart", {
+            query: {
+                locale,
+                promoCode: codes.promoCode || undefined,
+                giftCard: codes.giftCard || undefined,
+            },
+            headers: visitorHeaders(visitor),
+        }), "Réponse").cart,
+        /** Ajoute une quantité ; `out_of_stock` (409) au-delà du stock disponible. */
+        addToCart: async (variantId, quantity, visitor, locale) => (await call("/shop/cart", visitor, "POST", { variantId, quantity }, locale)).cart,
+        /** Fixe la quantité d'une ligne (0 la retire). */
+        setCartLine: async (variantId, quantity, visitor, locale) => (await call("/shop/cart", visitor, "PATCH", { variantId, quantity }, locale)).cart,
+        /** Ajoute une carte cadeau (montant et destinataire). */
+        addGiftCard: async (input, visitor, locale) => (await call("/shop/cart/gift-cards", visitor, "POST", input, locale)).cart,
+        removeGiftCard: async (lineId, visitor, locale) => (await call(`/shop/cart/gift-cards/${encodeURIComponent(lineId)}`, visitor, "DELETE", undefined, locale)).cart,
+        clearCart: async (visitor) => (await call("/shop/cart", visitor, "DELETE")).cart,
+        /** Modes de livraison proposés pour le panier, selon le pays (`FR` par défaut). */
+        shippingOptions: async (visitor, country = "FR", promoCode) => required(await request("/shop/shipping-options", {
+            query: { country, promoCode: promoCode || undefined },
+            headers: visitorHeaders(visitor),
+        }), "Réponse").options,
+        /** Points relais proches pour un mode à point relais. */
+        servicePoints: async (input, visitor) => required(await request("/shop/service-points", {
+            query: input,
+            headers: visitorHeaders(visitor),
+        }), "Réponse").points,
+        /** Lance le paiement : commande en attente, stock réservé, facture Stripe. */
+        checkout: (input, visitor, locale) => call("/shop/checkout", visitor, "POST", input, locale),
+        /** Accès du compte aux vidéos. */
+        access: async (visitor) => (await call("/shop/access", visitor)).access,
+        /**
+         * Liens de lecture d'une vidéo (403 `no_access` sans droit). Une location pas encore
+         * commencée démarre ici : à n'appeler que sur une demande explicite du visiteur.
+         */
+        play: async (videoId, visitor) => (await call(`/shop/access/${encodeURIComponent(videoId)}/play`, visitor, "POST", {})).playback,
+        /** Abonnements du compte (en cours et terminés). */
+        subscriptions: async (visitor) => (await call("/shop/subscriptions", visitor))
+            .subscriptions,
+        /** Résilie à la fin de la période payée (accès gardés jusque-là). */
+        cancelSubscription: async (id, visitor) => call(`/shop/subscriptions/${encodeURIComponent(id)}/cancel`, visitor, "POST", {}),
+        /**
+         * « Changer de carte » : adresse du portail Stripe du client, qui revient sur `returnUrl`
+         * (`url: null` en paiement simulé).
+         */
+        paymentMethod: async (id, returnUrl, visitor) => call(`/shop/subscriptions/${encodeURIComponent(id)}/payment-method`, visitor, "POST", { returnUrl }),
+        orders: async (visitor) => (await call("/shop/orders", visitor)).orders,
+        order: async (id, visitor) => (await call(`/shop/orders/${encodeURIComponent(id)}`, visitor)).order,
+        /** Paiement simulé (`provider: "simulated"`, développement local seulement). */
+        simulatePayment: (orderId, visitor) => call(`/shop/orders/${encodeURIComponent(orderId)}/simulate-payment`, visitor, "POST", {}),
+    };
+}

package/dist/types.d.ts

@@ -11,11 +11,37 @@ export type ApiSite = {
      * pose alors `noindex` sur toutes les pages et un `robots.txt` bloquant.
      */
     indexable: boolean;
+    /**
+     * Adresse publique du site (`https://cave-vivante.fr`), sans `/` final : base des URL absolues
+     * (canonique, Open Graph, sitemap). Domaine public du client, sinon son adresse de test
+     * Vercel ; `null` si aucune n'est connue.
+     */
+    url: string | null;
+    /** Image de partage par défaut (C-18), quand une page n'a pas la sienne. */
+    shareImage: Media | null;
+    /** Logo du client dans le CMS (adresse), repli du logo des données structurées. */
+    logo: string | null;
     /**
      * Identifiant de mesure Google Analytics 4 (`G-…`) choisi dans C-21, seulement une fois le
      * site en ligne : à passer à `<CookieBanner gaId>`, qui le charge après accord.
      */
     ga4: string | null;
+    /** Réglages publics du module Comptes (U-03), `null` s'il n'est pas activé. */
+    accounts: ApiAccountsSettings | null;
+};
+/** Ce que le site doit savoir pour ses formulaires de compte. */
+export type ApiAccountsSettings = {
+    /** Un compte doit cliquer sur le lien reçu avant de commander ou réserver. */
+    verifyEmail: boolean;
+    /** Téléphone à l'inscription : non demandé, facultatif ou obligatoire. */
+    phone: "none" | "optional" | "required";
+    /** Clé publique du widget Cloudflare Turnstile de l'inscription. */
+    turnstileSiteKey: string;
+    /** Pages du site qui reçoivent les liens des emails (chemins). */
+    pages: {
+        verification: string;
+        password: string;
+    };
 };
 export type ApiSection = {
     id: string;
@@ -49,11 +75,32 @@ export type ApiPage = {
     sections: ApiSection[];
     /** Adresse de la page dans chaque langue. */
     alternates: Record<string, string>;
+    /** Dernière publication (ISO), pour `lastmod` du sitemap ; `null` en aperçu d'un brouillon. */
+    updatedAt: string | null;
+    /** Contenu réservé : sections servies seulement au compte qui en a le droit. */
+    access?: ApiReserved;
+};
+/**
+ * Contenu réservé (lot 14e5c) : un produit d'accès l'ouvre. Sans droit (`granted: false`), les
+ * sections sont vides et `products` dit quoi acheter pour les débloquer.
+ */
+export type ApiReserved = {
+    reserved: true;
+    granted: boolean;
+    products: {
+        id: string;
+        name: string;
+        url: string | null;
+    }[];
 };
 /** Une page et ses adresses, pour générer les routes du site. */
 export type ApiPageEntry = {
     id: string;
     urls: Record<string, string>;
+    /** Page parente (fil d'Ariane), `null` à la racine. */
+    parentId: string | null;
+    /** Titre de la page dans chaque langue (fil d'Ariane, `llms.txt`). */
+    titles: Record<string, string>;
 };
 /** Élément de collection : ses champs, puis les sections ajoutées sous le gabarit (E-01). */
 export type ApiItem = Record<string, unknown> & {
@@ -61,6 +108,320 @@ export type ApiItem = Record<string, unknown> & {
     slug: string;
     url: string | null;
     sections: ApiSection[];
+    /** Onglet SEO de l'éditeur (E-04), comme pour une page. */
+    seo: ApiSeo;
+    /** Dernière publication (ISO), pour `lastmod` du sitemap. */
+    updatedAt: string | null;
+    /** Élément de la collection `products` : prix, variantes, médias (module Boutique). */
+    product?: ApiProduct;
+    /** Contenu réservé : sections servies seulement au compte qui en a le droit. */
+    access?: ApiReserved;
+};
+/** Média d'un produit (médiathèque). */
+export type ApiProductMedia = {
+    id: string;
+    url: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    mime: string;
+};
+/** Variante d'un produit physique : combinaison de valeurs d'options, prix, disponibilité. */
+export type ApiProductVariant = {
+    id: string;
+    /** `{ <id de l'option>: <id de la valeur> }` ; vide pour la variante unique. */
+    options: Record<string, string>;
+    /** Prix TTC en centimes ; `compareAt` : prix barré. */
+    price: number;
+    compareAt: number | null;
+    sku: string | null;
+    /** En stock (le stock exact n'est pas servi). */
+    available: boolean;
+    /** Stock sous le seuil de stock bas. */
+    lowStock: boolean;
+    media: ApiProductMedia | null;
+};
+/**
+ * Données de boutique d'un élément de la collection `products` (`item.product`). Prix en
+ * centimes, TTC. Un produit masqué ou réservé n'est pas servi.
+ */
+export type ApiProduct = {
+    /** Identifiant du produit (celui de l'élément de la collection `products`). */
+    id: string;
+    type: "physical" | "access" | "subscription" | "gift_card";
+    /** Prix le plus bas des variantes ; `priceFrom` : « à partir de ». */
+    price: number | null;
+    priceFrom: boolean;
+    compareAt: number | null;
+    /** Taux de TVA en points de base (2000 = 20 %). */
+    vatRate: number;
+    available: boolean;
+    categories: {
+        id: string;
+        name: string;
+    }[];
+    media: ApiProductMedia[];
+    thumbnail: ApiProductMedia | null;
+    options: {
+        id: string;
+        name: string;
+        values: {
+            id: string;
+            label: string;
+        }[];
+    }[];
+    variants: ApiProductVariant[];
+    /** Carte cadeau : montants proposés et montant libre (minimum, maximum), en centimes. */
+    giftCard: {
+        amounts: number[];
+        custom: {
+            min: number;
+            max: number;
+        } | null;
+    } | null;
+    /** Abonnement : période et essai gratuit (le prix est celui de la période). */
+    subscription: {
+        interval: "month" | "year";
+        trialDays: number | null;
+    } | null;
+    /** Accès : location (durée en heures, délai pour commencer) ou définitif, vidéos données. */
+    access: {
+        mode: "rental" | "lifetime";
+        durationHours: number | null;
+        startWithinDays: number | null;
+        videoIds: string[];
+    } | null;
+    /** Produits associés servis, dans l'ordre. */
+    related: {
+        id: string;
+        name: string;
+        slug: string;
+        url: string | null;
+        price: number | null;
+        priceFrom: boolean;
+        thumbnail: ApiProductMedia | null;
+    }[];
+};
+/** Ligne du panier (montants TTC en centimes, recalculés par le CMS). */
+export type ApiCartLine = {
+    /** Vide pour une carte cadeau (voir `giftCardLineId`). */
+    variantId: string;
+    productId: string;
+    name: string;
+    variantLabel: string | null;
+    quantity: number;
+    unitPrice: number;
+    total: number;
+    /** Quantité encore disponible : au-delà, la ligne ne peut pas être payée. */
+    available: number;
+    /** Produit toujours en vente pour ce compte. */
+    sellable: boolean;
+    /** Type du produit : un accès ou un abonnement se prend en un exemplaire. */
+    productType: "physical" | "access" | "subscription" | "gift_card";
+    /** Carte cadeau : ligne à retirer (`removeGiftCard`) et destinataire. */
+    giftCardLineId: string | null;
+    giftCard: {
+        recipientName: string;
+        recipientEmail: string;
+        message: string;
+        /** Envoi programmé (ISO) ; `null` : au paiement. */
+        sendAt: string | null;
+    } | null;
+};
+/** Carte cadeau à ajouter au panier : montant proposé (ou libre) et destinataire. */
+export type ApiGiftCardInput = {
+    productId: string;
+    amountCents: number;
+    recipientName: string;
+    recipientEmail: string;
+    message?: string;
+    /** `AAAA-MM-JJ` : envoi ce jour-là à 9 h (heure de Paris) ; absent : au paiement. */
+    sendOn?: string | null;
+};
+export type ApiCart = {
+    lines: ApiCartLine[];
+    count: number;
+    subtotal: number;
+    /** Code promo appliqué (`cart(visitor, locale, promoCode)`), ou `null`. */
+    promo: {
+        code: string;
+        label: string;
+        discount: number;
+        freeShipping: boolean;
+    } | null;
+    /** Pourquoi le code demandé ne s'applique pas (inconnu, expiré, minimum…). */
+    promoError: string | null;
+    /** Carte cadeau saisie : fin du code et solde disponible, déduit au paiement. */
+    giftCard: {
+        last4: string;
+        available: number;
+    } | null;
+    giftCardError: string | null;
+    /** Sous-total moins la remise, hors livraison. */
+    total: number;
+    /** Des articles sont à livrer ; sinon (cartes cadeaux, accès) ni adresse ni livraison. */
+    shippingRequired: boolean;
+};
+export type ApiAddress = {
+    name: string;
+    line1: string;
+    line2?: string | null;
+    postalCode: string;
+    city: string;
+    /** Code pays à deux lettres (`FR`). */
+    country: string;
+    phone?: string | null;
+};
+/** Mode de livraison proposé pour le panier (modes du compte Sendcloud, retrait sur place). */
+export type ApiShippingOption = {
+    /** `sc_<mode Sendcloud>` ou `pickup` : à renvoyer dans `checkout`. */
+    id: string;
+    kind: "sendcloud" | "pickup";
+    label: string;
+    /** Transporteur Sendcloud (`colissimo`, `mondial_relay`…). */
+    carrier: string | null;
+    /** Centimes TTC (0 si offerte). */
+    price: number;
+    free: boolean;
+    /** Un point relais est à choisir (`servicePoints`). */
+    servicePoint: boolean;
+    pickup: {
+        address: string;
+        hours: string;
+        instructions: string;
+    } | null;
+};
+/** Point relais proche (mode à point relais). */
+export type ApiServicePoint = {
+    id: number;
+    name: string;
+    carrier: string;
+    address: string;
+    postalCode: string;
+    city: string;
+    country: string;
+    /** Distance en mètres. */
+    distance: number | null;
+};
+/** Ce qu'envoie le site pour payer : adresse (sauf retrait), mode de livraison, CGV. */
+export type ApiCheckoutInput = {
+    shippingAddress?: ApiAddress | null;
+    /** Absente pour un panier de cartes cadeaux seulement. */
+    shipping?: {
+        option: string;
+        servicePoint?: number | null;
+    } | null;
+    /** Code promo (un par commande) ; refus `promo_invalid` (409) s'il ne s'applique plus. */
+    promoCode?: string | null;
+    /** Carte cadeau : son solde paie tout ou partie de la commande ; refus `gift_card_invalid`. */
+    giftCardCode?: string | null;
+    acceptTerms: true;
+};
+/** Paiement lancé : commande en attente (stock réservé 30 minutes) et facture à régler. */
+export type ApiCheckout = {
+    /** `due` : reste à payer par carte bancaire (total moins la carte cadeau). */
+    order: {
+        id: string;
+        number: string;
+        total: number;
+        due: number;
+    };
+    payment: {
+        /** `simulated` : développement local, sans Stripe (`simulatePayment`). */
+        provider: "stripe" | "simulated";
+        publishableKey: string | null;
+        /** Secret du Payment Element de Stripe. */
+        clientSecret: string | null;
+        test: boolean;
+        /** Tout est réglé par carte cadeau : la commande est déjà payée, aller à la confirmation. */
+        paid: boolean;
+    };
+};
+export type ApiOrder = {
+    id: string;
+    number: string;
+    payment: "pending" | "paid" | "failed" | "abandoned" | "refunded" | "partially_refunded";
+    fulfillment: "to_prepare" | "ready" | "shipped" | "delivered" | "picked_up" | "canceled" | "completed" | null;
+    total: number;
+    subtotal: number;
+    shipping: number;
+    /** Remise du code promo, et le code. */
+    discount: number;
+    promoCode: string | null;
+    /** Montant réglé par carte cadeau. */
+    giftCard: number;
+    /** Livraison choisie : mode, point relais ou retrait, suivi du colis. */
+    delivery: {
+        kind: "sendcloud" | "pickup";
+        label: string;
+        servicePoint: string | null;
+        pickup: {
+            address: string;
+            hours: string;
+        } | null;
+        tracking: {
+            number: string;
+            url: string | null;
+        } | null;
+    } | null;
+    vat: number;
+    /** Facture Stripe (PDF et page hébergée). */
+    invoiceUrl: string | null;
+    createdAt: string;
+    paidAt: string | null;
+    lines: {
+        name: string;
+        variantLabel: string | null;
+        quantity: number;
+        unitPrice: number;
+        total: number;
+    }[];
+};
+/** Accès du compte connecté à une vidéo (produit d'accès acheté ou accès donné). */
+export type ApiAccess = {
+    id: string;
+    /** `video`, ou `document` pour un contenu réservé. */
+    kind: "video" | "document";
+    videoId: string | null;
+    documentId: string | null;
+    title: string;
+    durationSeconds: number | null;
+    product: string | null;
+    mode: "rental" | "lifetime";
+    /** Location : durée à partir du premier visionnage. */
+    durationHours: number | null;
+    /** `not_started` : la location démarre au premier visionnage, avant `startBefore`. */
+    state: "not_started" | "active" | "ended" | "expired";
+    startBefore: string | null;
+    endsAt: string | null;
+};
+/** Abonnement du compte connecté (lot 14e6b). */
+export type ApiSubscription = {
+    id: string;
+    product: string;
+    /** Prix TTC de chaque période, en centimes. */
+    priceCents: number;
+    interval: "month" | "year";
+    /** `trialing`, `active`, `past_due` (paiement refusé, relance en cours), `canceled`… */
+    status: string;
+    /** Résilié : s'arrête à `currentPeriodEnd`, accès gardés jusque-là. */
+    cancelAtPeriodEnd: boolean;
+    currentPeriodEnd: string | null;
+    trialEnd: string | null;
+    /** Terminé (accès coupés) le… */
+    endedAt: string | null;
+};
+/** Liens de lecture signés, valables jusqu'à `expiresAt` (au plus 2 heures). */
+export type ApiPlayback = {
+    /** Lecteur Stream à intégrer en `<iframe>`. */
+    iframe: string | null;
+    hls: string | null;
+    /** Fichier direct (Stream simulé, développement local). */
+    mp4: string | null;
+    thumbnail: string | null;
+    expiresAt: string;
+    /** Fin du droit (location) ; `null` : définitif. */
+    endsAt: string | null;
 };
 /** Aperçu de l'éditeur : une page ou un élément de collection, brouillon compris. */
 export type ApiPreviewDocument = {
@@ -108,3 +469,51 @@ export type ApiErrorBody = {
         details?: string[];
     };
 };
+/** Compte d'une personne sur le site. */
+export type ApiAccount<X = Record<string, unknown>> = {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    phone: string | null;
+    /** Adresse confirmée par le lien reçu (requis pour commander quand le site le demande). */
+    emailVerified: boolean;
+    createdAt: string;
+    /** Champs personnalisés déclarés par le site (`defineFields`), `null` quand vides. */
+    custom: X;
+};
+/** Session ouverte : le jeton est à garder dans un cookie httpOnly du site. */
+export type ApiSession = {
+    token: string;
+    expiresAt: string;
+};
+export type ApiAccountSession<X = Record<string, unknown>> = {
+    account: ApiAccount<X>;
+    session: ApiSession;
+};
+export type ApiRegisterInput<X = Record<string, unknown>> = {
+    email: string;
+    password: string;
+    firstName: string;
+    lastName: string;
+    phone?: string | null;
+    /** Jeton Cloudflare Turnstile du formulaire d'inscription. */
+    turnstileToken: string;
+    /**
+     * Page du site qui reçoit le lien de vérification (`?token=…` ajouté) ; par défaut celle
+     * réglée dans U-03.
+     */
+    verifyUrl?: string;
+    /** Champs personnalisés (`defineFields`) ; les obligatoires doivent être remplis. */
+    custom?: Partial<X>;
+};
+export type ApiAccountUpdate<X = Record<string, unknown>> = {
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string | null;
+    /** Obligatoire si l'email change : la nouvelle adresse reçoit un lien de vérification. */
+    verifyUrl?: string;
+    /** Champs personnalisés à changer (les autres sont gardés). */
+    custom?: Partial<X>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agence-zef/sdk",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "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.2.0"
+    "@agence-zef/schema": "0.4.0"
   },
   "homepage": "https://agence-zef.fr",
   "scripts": {