@agence-zef/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agence ZEF
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @agence-zef/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client typé de l'API `/api/v1` du CMS de l'agence ZEF.
+
+Paquet du CMS de l'agence ZEF (dépôt privé). Licence MIT.

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+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";
+export type * from "./types.js";
+/** Erreur renvoyée par l'API (clé invalide, schéma refusé…). */
+export declare class ZefApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: string[];
+    constructor(status: number, code: string, message: string, details?: string[]);
+}
+export type ClientOptions = {
+    /** Adresse du CMS du client : `https://cave-vivante.agence-zef.fr`. */
+    url: string;
+    apiKey: string;
+    fetch?: typeof fetch;
+};
+type Collections<C extends ZefConfig> = ZefConfig extends C ? Record<string, ApiItem> : ConfigCollections<C>;
+type LocaleOption = {
+    locale?: string;
+};
+/**
+ * Client typé de l'API d'un site. Le type du registre (`typeof config`) donne
+ * les noms de collections et la forme de leurs données.
+ */
+export declare function createClient<C extends ZefConfig = ZefConfig>(options: ClientOptions): {
+    /** Nom du site, langues, version du registre. */
+    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>;
+    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>;
+    /** 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. */
+    previewLayout: (opts?: LocaleOption) => Promise<ApiLayout>;
+    /** Redirections à appliquer au build (anciennes adresses, liens externes). */
+    redirects: () => Promise<ApiRedirect[]>;
+    /** Aperçu (jeton de l'éditeur) : document par identifiant, champs marqués pour l'overlay. */
+    /** `version` : une version de l'historique à la place du brouillon (E-05). */
+    previewDocument: (id: string, opts?: LocaleOption & {
+        version?: string;
+    }) => Promise<ApiPreviewDocument | null>;
+    /** Aperçu : une section du brouillon, résolue pour être rendue seule. */
+    previewSection: (section: {
+        id: string;
+        type: string;
+    }, opts?: LocaleOption & {
+        /** Page d'un élément de collection : ses variables (`{{domaine}}`) sont remplacées. */
+        item?: string;
+    }) => Promise<ApiSection>;
+    /** Vérifie la clé et enregistre le lien du dépôt (`zef link`). */
+    link: () => Promise<ApiLink>;
+    /** Envoie le registre du site (`zef sync`). */
+    sync: (registry: Registry) => Promise<ApiSyncResult>;
+};
+export type ZefClient<C extends ZefConfig = ZefConfig> = ReturnType<typeof createClient<C>>;

package/dist/index.js

@@ -0,0 +1,89 @@
+/** Erreur renvoyée par l'API (clé invalide, schéma refusé…). */
+export class ZefApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details = []) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "ZefApiError";
+    }
+}
+/**
+ * Client typé de l'API d'un site. Le type du registre (`typeof config`) donne
+ * les noms de collections et la forme de leurs données.
+ */
+export function createClient(options) {
+    const base = `${options.url.replace(/\/$/, "")}/api/v1`;
+    const doFetch = options.fetch ?? fetch;
+    async function request(path, init = {}) {
+        const query = new URLSearchParams();
+        for (const [k, v] of Object.entries(init.query ?? {})) {
+            if (v !== undefined && v !== null)
+                query.set(k, String(v));
+        }
+        const qs = query.size ? `?${query}` : "";
+        const res = await doFetch(`${base}${path}${qs}`, {
+            method: init.method ?? "GET",
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+        if (res.status === 404 && (init.method ?? "GET") === "GET") {
+            const body = (await res.json().catch(() => null));
+            if (body?.error.code === "not_found")
+                return null;
+            throw new ZefApiError(404, body?.error.code ?? "not_found", body?.error.message ?? "");
+        }
+        if (!res.ok) {
+            const body = (await res.json().catch(() => null));
+            throw new ZefApiError(res.status, body?.error.code ?? "http_error", body?.error.message ?? `Réponse ${res.status} du CMS`, body?.error.details);
+        }
+        return (await res.json());
+    }
+    const required = (value, what) => {
+        if (value === null)
+            throw new ZefApiError(404, "not_found", `${what} introuvable`);
+        return value;
+    };
+    return {
+        /** Nom du site, langues, version du registre. */
+        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 } }),
+        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 }),
+        /** 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. */
+        previewLayout: async (opts = {}) => required(await request("/layout", { query: { ...opts, stega: 1 } }), "Header et footer"),
+        /** Redirections à appliquer au build (anciennes adresses, liens externes). */
+        redirects: async () => required(await request("/redirects"), "Redirections").redirects,
+        /** Aperçu (jeton de l'éditeur) : document par identifiant, champs marqués pour l'overlay. */
+        /** `version` : une version de l'historique à la place du brouillon (E-05). */
+        previewDocument: (id, opts = {}) => request(`/preview/document/${encodeURIComponent(id)}`, {
+            query: { ...opts, stega: 1 },
+        }),
+        /** Aperçu : une section du brouillon, résolue pour être rendue seule. */
+        previewSection: async (section, opts = {}) => {
+            const { item, ...query } = opts;
+            return required(await request("/preview/section", {
+                method: "POST",
+                body: item ? { section, item } : { section },
+                query: { ...query, stega: 1 },
+            }), "Section");
+        },
+        /** Vérifie la clé et enregistre le lien du dépôt (`zef link`). */
+        link: async () => required(await request("/link", { method: "POST" }), "Lien"),
+        /** Envoie le registre du site (`zef sync`). */
+        sync: async (registry) => required(await request("/schema", { method: "POST", body: registry }), "Registre"),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+import type { Media } from "@agence-zef/schema";
+export type ApiKeyType = "publiee" | "apercu";
+export type ApiSite = {
+    name: string;
+    locales: string[];
+    defaultLocale: string;
+    /** Version du registre reçu par `zef sync`, `null` avant le premier envoi. */
+    schemaVersion: number | null;
+    /**
+     * Le site peut être indexé : faux tant qu'il est en développement (§ 5.11) ; `@agence-zef/astro`
+     * pose alors `noindex` sur toutes les pages et un `robots.txt` bloquant.
+     */
+    indexable: boolean;
+    /**
+     * 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;
+};
+export type ApiSection = {
+    id: string;
+    /** Nom de la section dans le registre (`hero`). */
+    type: string;
+    variant: string | null;
+    anchor: string | null;
+    /** CSS personnalisé de l'agence (`&` désigne la section), sinon `null`. */
+    css: string | null;
+    /**
+     * Champs résolus dans la langue demandée. Bloc HTML (`type: "zef-html"`) :
+     * `{ name, html, css, js }`.
+     */
+    data: Record<string, unknown>;
+};
+export type ApiSeo = {
+    title: string | null;
+    description: string | null;
+    noindex: boolean;
+    /** URL canonique choisie par l'agence, sinon `null` (l'adresse de la page). */
+    canonical: string | null;
+    /** Image de partage (1200 × 630 conseillé), sinon `null` : celle du gabarit du site. */
+    image: Media | null;
+};
+export type ApiPage = {
+    id: string;
+    locale: string;
+    url: string;
+    title: string;
+    seo: ApiSeo;
+    sections: ApiSection[];
+    /** Adresse de la page dans chaque langue. */
+    alternates: Record<string, string>;
+};
+/** Une page et ses adresses, pour générer les routes du site. */
+export type ApiPageEntry = {
+    id: string;
+    urls: 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> & {
+    id: string;
+    slug: string;
+    url: string | null;
+    sections: ApiSection[];
+};
+/** Aperçu de l'éditeur : une page ou un élément de collection, brouillon compris. */
+export type ApiPreviewDocument = {
+    kind: "page";
+    page: ApiPage;
+} | {
+    kind: "item";
+    collection: string;
+    titleField: string;
+    item: ApiItem;
+};
+/** Header et footer du site : sections partagées par toutes les pages. */
+export type ApiLayout = {
+    header: ApiSection | null;
+    footer: ApiSection | null;
+};
+export type ApiList<T> = {
+    items: T[];
+    total: number;
+};
+export type ApiLink = {
+    site: string;
+    keyType: ApiKeyType;
+};
+/** Redirection du site (C-17), destination déjà traduite en adresse. */
+export type ApiRedirect = {
+    from: string;
+    to: string;
+    status: 301 | 302;
+};
+export type ApiSyncResult = {
+    version: number;
+    /** `false` si le registre est identique à la version précédente. */
+    changed: boolean;
+    /** Champs retirés du registre qui contiennent encore des données (§ 3.3 du plan technique). */
+    removed: {
+        path: string;
+        documents: number;
+    }[];
+};
+export type ApiErrorBody = {
+    error: {
+        code: string;
+        message: string;
+        details?: string[];
+    };
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@agence-zef/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Client typé de l'API d'un CMS ZEF (client.agence-zef.fr/api/v1).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agence-zef/schema": "0.2.0"
+  },
+  "homepage": "https://agence-zef.fr",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
 }