@communecter/cocolight-api-client 1.0.195 → 1.0.197

package/types/api/serverDataType/Ampli.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Types de l'**ampli** — l'espace de propositions d'un costum.
+ *
+ * Source de vérité : les actions legacy du module costum
+ * `controllers/actions/ampli/{CreateAmpliAction,RemoveAmpliAction}.php`, routées par
+ * `CostumizeController` sur `/costum/costumize/{createampli,removeampli}`.
+ *
+ * Un ampli n'est **pas une entité** : c'est une entrée de la carte `costum.ampli`, portée par
+ * l'élément hôte du costum (organisation, projet, citoyen ou événement) et indexée par son
+ * **slug**. D'où le placement des deux méthodes sur `BaseEntity` plutôt qu'une classe dédiée :
+ * elles s'appliquent à l'hôte, exactement comme `saveToolEnrichment`.
+ */
+/** Collections pouvant porter un costum, donc un ampli (`parentType` des deux actions). */
+export declare const AMPLI_PARENT_TYPES: readonly ["organizations", "projects", "citoyens", "events"];
+export type AmpliParentType = (typeof AMPLI_PARENT_TYPES)[number];
+/**
+ * Chemins des questions du formulaire de dépôt, forme `<idSousFormulaire>.<idQuestion>`
+ * (**sans** le préfixe `answers.`). Chaîne vide quand la question n'existe pas — `finder` l'est
+ * toujours pour un formulaire généré par le serveur.
+ */
+export interface AmpliPaths {
+    name: string;
+    description: string;
+    address: string;
+    tags: string;
+    image: string;
+    finder: string;
+}
+/**
+ * Une entrée de `costum.ampli`, telle que relue via `element/about` — quelle que soit son époque.
+ *
+ * Deux formes coexistent en base :
+ *  - les entrées écrites par `CreateAmpliAction` AVANT modules/costum@3ef97ef28 n'ont que
+ *    `{ name, description, tags, pages, home }`, et leur clé vient de `strtolower` + espace → tiret
+ *    (« Idées d'été » → `idées-d'été`) ;
+ *  - les entrées écrites depuis portent en plus `slug`, `coform` et `path` ({@link CreatedAmpliEntry}).
+ *
+ * La CLÉ de la carte `costum.ampli` reste la seule référence fiable d'un ampli existant.
+ */
+export interface AmpliEntry {
+    name: string;
+    /** Markdown, `""` si non fourni. */
+    description: string;
+    /** `null` sur une entrée ancienne créée avec des tags en tableau (`explode` d'un tableau). */
+    tags: string[] | null;
+    /** Pages Co de l'ampli (`#<page>`). Toujours vide pour une création depuis site-json. */
+    pages: string[];
+    /** Ancre de la page d'accueil Co. Toujours vide pour une création depuis site-json. */
+    home: string;
+    /** Clé de l'entrée dans `costum.ampli` — absente des entrées anciennes. */
+    slug?: string;
+    /** ObjectId du `Form` de dépôt — absent des entrées anciennes. */
+    coform?: string;
+    /** Chemins des questions du formulaire de dépôt — absents des entrées anciennes. */
+    path?: AmpliPaths;
+}
+/**
+ * L'entrée que {@link BaseEntity#createAmpli} vient d'écrire : la forme actuelle, complète.
+ */
+export interface CreatedAmpliEntry extends AmpliEntry {
+    slug: string;
+    tags: string[];
+    coform: string;
+    path: AmpliPaths;
+}
+/** Champs communs aux deux modes de {@link BaseEntity#createAmpli}. */
+interface CreateAmpliInputCommon {
+    /**
+     * Nom affiché. Le serveur en dérive la **clé** de l'entrée (`ampliSlug`) : « Idées d'été » donne
+     * `idees-d-ete`. Un nom qui ne produit aucun slug exploitable est refusé.
+     */
+    name: string;
+    /** Markdown, stocké tel quel. */
+    description?: string;
+    /** Vides et doublons sont retirés côté serveur. */
+    tags?: string[];
+}
+/**
+ * Mode A (défaut) — le **serveur crée le formulaire** : un `Form` et son sous-formulaire à cinq
+ * questions (titre, description, adresse, mots-clés, image), dont les chemins reviennent dans
+ * {@link CreatedAmpliEntry.path}. C'est le mode du parcours de création depuis site-json.
+ */
+export type CreateAmpliInputGeneratedForm = CreateAmpliInputCommon;
+/**
+ * Mode B — **rattachement à un formulaire existant** : `coform` désigne le `Form`, `namePath` et
+ * `addressPath` sont exigés par le serveur, les autres chemins sont facultatifs.
+ */
+export interface CreateAmpliInputExistingForm extends CreateAmpliInputCommon {
+    /** ObjectId du `Form` à rattacher. Sa présence bascule l'appel en mode B. */
+    coform: string;
+    namePath: string;
+    addressPath: string;
+    descriptionPath?: string;
+    tagsPath?: string;
+    imagePath?: string;
+    finderPath?: string;
+}
+/** Entrée de {@link BaseEntity#createAmpli} — le mode se lit à la présence de `coform`. */
+export type CreateAmpliInput = CreateAmpliInputGeneratedForm | CreateAmpliInputExistingForm;
+/**
+ * Retour de {@link BaseEntity#createAmpli}.
+ *
+ * `data`, `app` et `blockCms` ne servent qu'à l'interface Co (boutons de menu, carte des pages,
+ * blocs CMS) et arrivent **vides** pour un appel site-json. Ils restent au contrat pour garder une
+ * seule forme de réponse ; un appelant site-json les ignore.
+ */
+export interface CreateAmpliResult {
+    result: true;
+    /** Clé de l'entrée : permet de naviguer vers `/ampli/<slug>` sans attendre un rechargement. */
+    slug: string;
+    ampli: CreatedAmpliEntry;
+    data: unknown[];
+    app: unknown[];
+    blockCms: unknown[];
+}
+/** Retour de {@link BaseEntity#removeAmpli} — `msg` vaut `"Ampli removed"`. */
+export interface RemoveAmpliResult {
+    result: true;
+    msg: string;
+}
+export {};

package/types/costum/liveDigest.d.ts

@@ -63,6 +63,28 @@ interface FieldDef {
     /** Valeur FORCÉE par le costum — cf. collectValuePresets. */
     value?: unknown;
 }
+/** Clé de base d'une collection telle que la déclare un `typeObj` — cf. `findCostumBaseNode`. */
+export interface CostumBaseNode {
+    /** Clé `typeObj` retenue (ex. `organizations`, `event`). */
+    typeKey: string;
+    /** Le nœud déclare-t-il des champs (`beforeBuild.properties`) ? Sinon : variante de base VIDE. */
+    hasForm: boolean;
+    add: boolean;
+    createLabel: string | null;
+}
+/**
+ * Trouve la CLÉ DE BASE d'une collection dans le `typeObj` d'un costum — le formulaire que le site
+ * applique quand on « ajoute une organisation » sans rien préciser, même quand ce nœud ne déclare AUCUN
+ * champ (ex. federationDesCae : `organizations: {add:true}` à côté du sous-type `organizationsTls`).
+ *
+ * Une base est une clé de `BASE_TYPEKEYS[collection]` dont le nœud est un objet SANS `sameAs`, ou avec un
+ * `sameAs` RÉFLEXIF (`event: {sameAs:"event"}` — parent62, institutBleu, navigator) : ce `sameAs` ne
+ * rattache le nœud à rien d'autre que lui-même. Deux clés sœurs (`organization` ET `organizations`) : on
+ * préfère celle qui porte un formulaire, sinon la première dans l'ordre du `typeObj` — en pratique
+ * `costum/co/resolved` n'en livre qu'une (le dernier déclaré gagne à la fusion moteur ⊕ overlay).
+ * Null si le costum ne déclare pas de clé de base pour cette collection.
+ */
+export declare function findCostumBaseNode(data: CostumJsonData, collection: string): CostumBaseNode | null;
 /**
  * Digère `getcostumjson` → `CostumRuntimeContext` pour UNE collection (null si le costum ne couvre pas
  * cette collection). `meta` = identité de l'élément porteur (costumId/costumType, résolue par slug/getinfo).
@@ -86,6 +108,12 @@ export declare function listCostumFormNodes(data: CostumJsonData): Array<{
     createLabel: string | null;
     discriminator?: string;
 }>;
+/**
+ * `opts.typeKey` : ne digère que cette clé `typeObj` (énumération par sous-type).
+ * `opts.allowFormless` (avec `typeKey`) : digère AUSSI ce nœud s'il ne déclare aucun champ — sert à la
+ * variante de BASE vide (cf. `findCostumBaseNode`) : schéma vide, `fields` vide, mais `presetValue` et
+ * `hide` PROPRES du nœud conservés. Sans cette option, un nœud sans formulaire est ignoré (inchangé).
+ */
 export declare function digestCostumJson(data: CostumJsonData, collection: Collection, meta: {
     costumId: string;
     costumType: string;
@@ -93,5 +121,6 @@ export declare function digestCostumJson(data: CostumJsonData, collection: Colle
     baseFieldNames?: string[];
 }, opts?: {
     typeKey?: string;
+    allowFormless?: boolean;
 }): DigestedCostum | null;
 export {};

package/types/costum/runtime.d.ts

@@ -1,5 +1,9 @@
 import type { CostumExtensionModule, CostumExtensionField, KnownCostumSlug, Collection } from "./types.js";
 import type { BaseEntity } from "../api/BaseEntity.js";
+import type { Event } from "../api/Event.js";
+import type { Organization } from "../api/Organization.js";
+import type { Poi } from "../api/Poi.js";
+import type { Project } from "../api/Project.js";
 /** Active/désactive FORCE-LIVE (cf. `COSTUM_FORCE_LIVE`). */
 export declare function setCostumForceLive(actif: boolean): void;
 /** État courant de FORCE-LIVE. */
@@ -83,6 +87,33 @@ export interface CostumFormDescriptor {
     /** Valeur de `type` estampillée au save qui distingue le sous-type (= presetValue.type, sinon typeKey). */
     discriminator?: string;
 }
+/** Collections couvertes par les fabriques du scope (poi/organization/project/event). Identité entityType↔collection. */
+type ScopeCollection = "poi" | "organizations" | "projects" | "events";
+/** Entité rendue par chaque fabrique — même correspondance que `EntityTypeMap` (BaseEntity), qui n'est pas
+ *  exporté : `create` étant public, son type de retour doit être nommable dans les `.d.ts`. */
+type ScopeEntityMap = {
+    poi: Poi;
+    organizations: Organization;
+    projects: Project;
+    events: Event;
+};
+/**
+ * Options de création sous un costum (`CostumScope.create` et ses raccourcis). Jamais envoyées au serveur.
+ */
+export interface CostumCreateOptions {
+    /**
+     * Sous-type CIBLÉ : clé `typeObj` du costum (ex. `"organizationsTls"` pour le formulaire « Créer votre
+     * CAE »). Ses presets et champs s'appliquent, quel que soit `data.type`. Sans lui, un sous-type ne
+     * s'applique que si `data.type` est son discriminant ; sinon c'est la clé de base de la collection.
+     * Inconnu du costum → repli silencieux sur cette règle (trace `debug`).
+     */
+    subType?: string;
+}
+/** Options de `CostumScope.contextFor` : celles de la création, plus le mode de sélection. */
+export interface CostumContextOptions extends CostumCreateOptions {
+    /** Sélectionner comme une CRÉATION (défaut = clé de base) plutôt que comme une lecture (défaut historique). */
+    create?: boolean;
+}
 /**
  * Scope costum : fabrique des entités liées à un costum. Réutilise le `user` (parent, deps, auth)
  * et n'altère jamais l'état partagé — chaque entité reçoit son propre `_costumCtx`.
@@ -98,14 +129,38 @@ export declare class CostumScope {
      * Construit le `CostumRuntimeContext` pour une collection (null si non couverte). `type` (optionnel) = le
      * sous-type voulu (= `presetValue.type` de la variante) : sélectionne l'overlay de CE sous-type, sinon la
      * racine=union. Indispensable au CREATE d'un sous-type précis (bon `type`/presets/champs — cf. P0 write-safety).
+     *
+     * `opts` (optionnel) : `subType` cible un sous-type par sa clé `typeObj` (prime sur `type`) ; `create`
+     * sélectionne comme une création (défaut = clé de base du costum). Sans `opts` : sélection de LECTURE,
+     * inchangée (revive/édition).
+     */
+    contextFor(collection: Collection, type?: string | null, opts?: CostumContextOptions): CostumRuntimeContext | null;
+    /**
+     * Crée une entité de `collection` sous ce costum (presets appliqués, surchargeables par `data`).
+     *
+     * Formulaire costum appliqué (presets + champs) — dans l'ordre :
+     *  1. `opts.subType` : le sous-type CIBLÉ par sa clé `typeObj` (ex. `"organizationsTls"`) ;
+     *  2. `data.type` : le sous-type dont c'est le discriminant (ex. `poi({ type: "article" })`) ;
+     *  3. sinon la CLÉ DE BASE de la collection si le costum en déclare une (ex. `organizations`), MÊME SANS
+     *     champ : un sous-type n'est jamais appliqué par défaut ; sans clé de base, comportement historique.
+     * Un `subType` inconnu retombe sur 2→3 (trace `debug`, aucune exception). `opts` n'est JAMAIS envoyé au
+     * serveur. La whitelist d'écriture reste l'union racine ∪ variante (byte-safe).
+     *
+     *   const cae = await tl.organization({ name }, { subType: "organizationsTls" }); // formulaire « CAE »
+     *   const org = await tl.organization({ name });                                  // formulaire de base
+     */
+    create<T extends ScopeCollection>(collection: T, data?: Record<string, unknown>, opts?: CostumCreateOptions): Promise<ScopeEntityMap[T]>;
+    /**
+     * Trace (`debug`) un `subType` que ce scope ne sait pas cibler pour `collection` : collection non couverte,
+     * ou variantes dont aucune ne porte cette clé `typeObj`. Une collection à formulaire UNIQUE n'a pas de
+     * variantes à comparer : rien n'est tracé (la racine EST ce formulaire). Le repli lui-même est fait par
+     * `pickCostumOverlay` ; ceci ne fait que le rendre visible.
      */
-    contextFor(collection: Collection, type?: string | null): CostumRuntimeContext | null;
-    /** Crée une entité de `collection` sous ce costum (presets appliqués, surchargeables par `data`). */
-    private create;
-    poi(data?: Record<string, unknown>): Promise<import("../index.js").Poi>;
-    organization(data?: Record<string, unknown>): Promise<import("../index.js").Organization>;
-    project(data?: Record<string, unknown>): Promise<import("../index.js").Project>;
-    event(data?: Record<string, unknown>): Promise<import("../index.js").Event>;
+    private traceUnknownSubType;
+    poi(data?: Record<string, unknown>, opts?: CostumCreateOptions): Promise<Poi>;
+    organization(data?: Record<string, unknown>, opts?: CostumCreateOptions): Promise<Organization>;
+    project(data?: Record<string, unknown>, opts?: CostumCreateOptions): Promise<Project>;
+    event(data?: Record<string, unknown>, opts?: CostumCreateOptions): Promise<Event>;
     /**
      * Poste une news sous CE costum, sur le mur de `target` : `source.key` = costum du scope (le SITE,
      * comme poi/org — cf. `News::prepData`), `parent` = `target`. News n'est PAS une collection « élément »
@@ -159,3 +214,4 @@ export declare function resolveCostumScope(user: BaseEntity, slug: KnownCostumSl
  * No-op si le costum ne résout pas / ne couvre pas la collection (l'entité reste en scope d'identité).
  */
 export declare function loadCostumContext(user: BaseEntity, slug: string, collection: Collection): Promise<CostumRuntimeContext | null>;
+export {};

package/types/costum/widenSchema.d.ts

@@ -0,0 +1,22 @@
+/**
+ * UN COSTUM PEUT ÉLARGIR UN CHAMP NATIF, JAMAIS LE RESTREINDRE.
+ *
+ * Un costum legacy redéclare des champs que le contrat connaît déjà (`type`, `tags`, `openingHours`,
+ * `telephone`…). Son schéma ne vient pas du stockage mais du WIDGET déclaré (digest live, `inferType`)
+ * ou d'un préremplissage (`presetProps`, typé chaîne). Il sert à ÉLARGIR un champ contraint — les
+ * types d'événement d'institutBleu sont tous hors de l'énumération native, et la production en vit.
+ * Mais posé À LA PLACE du schéma natif, il refusait aussi la forme native. Mesuré le 2026-10-01 sur les
+ * 21 costums résolus des sites de site-json : 111 champs natifs redéclarés, dont 8 RESTREINTS — horaires
+ * en liste refusés (CAE, navigator, relief : création impossible dès qu'on les saisit), téléphone en
+ * objet legacy refusé, mots-clés préremplis refusés en liste — pour 27 élargissements légitimes.
+ *
+ * Règle : pour un champ défini des deux côtés, la requête accepte le natif OU le costum (`anyOf`).
+ * Elle est monotone — tout ce qui passait passe encore — et une valeur que les deux refusent reste
+ * refusée. Appliquée aux DEUX points de fusion : la création (`ApiClient.callEndpoint`, enveloppe
+ * costum) et la modification (`BaseEntity._saveCostumViaElementSave`), qui faisaient l'inverse l'une
+ * de l'autre (le costum primait à la création, le natif à la modification).
+ */
+/** Schéma d'un champ défini par le contrat (`natif`) ET par le costum : natif OU costum. */
+export declare function widenSchema(natif: unknown, costum: unknown): unknown;
+/** `widenSchema` clé par clé : chaque propriété du costum élargit celle du natif, les autres restent. */
+export declare function widenProperties(natives: Record<string, unknown>, costum: Record<string, unknown>): Record<string, unknown>;