@communecter/cocolight-api-client 1.0.162 → 1.0.166

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@communecter/cocolight-api-client",
-    "version": "1.0.162",
+    "version": "1.0.166",
     "description": "Client Axios simplifié pour l'API cocolight",
     "repository": {
         "type": "git",

package/types/api/BaseEntity.d.ts

@@ -742,6 +742,20 @@ export declare class BaseEntity<TServerData = any> {
      * @protected
      */
     protected _markDeletedLocally(): void;
+    /** Droit d'ADMIN DE COSTUM pré-résolu par l'appelant (ex. site-json /admin via `me.isCostumAdmin(slug)`). */
+    protected _costumAdminAuthorized: boolean;
+    /**
+     * Marque cette instance comme éditable/supprimable au titre du droit-parapluie COSTUM. À poser par
+     * l'appelant qui a DÉJÀ résolu `me.isCostumAdmin(slug)` (async) — les gardes client d'édition (`_update`)
+     * et de suppression (`_deleteViaElement`) le respectent alors. Le backend reste la source de vérité
+     * (canEditItem/canDeleteElement portent isCostumAdmin), ceci n'ouvre QUE le pré-check client.
+     */
+    setCostumAdminAuthorized(v?: boolean): this;
+    /**
+     * Droit de gestion « élevé » côté client : super-admin (via userContext) OU admin de costum pré-résolu.
+     * Utilisé par les gardes `_update`/`_deleteViaElement` pour ne pas bloquer une action que le backend autorise.
+     */
+    protected _hasElevatedManageRight(): boolean;
     /**
      * Suppression générique d'un élément via `DELETE_ELEMENT`
      * (`/co2/element/delete/type/{type}/id/{id}`).
@@ -1735,6 +1749,43 @@ export declare class BaseEntity<TServerData = any> {
         isAdmin?: "" | "admin";
         roles?: string[];
     }>): Promise<unknown>;
+    /**
+     * L'entité porte-t-elle un contexte costum COMPLET (slug + costumId + costumType) ?
+     * Vrai pour une entité chargée avec un `source.key` connu, ou après `setCostumScope()`.
+     */
+    hasCostumScope(): boolean;
+    /**
+     * Pose EXPLICITEMENT le scope costum de l'entité — l'API OFFICIELLE pour rattacher une entité
+     * HÔTE de costum (qui n'a pas de `source.key` : c'est elle la source, la lib ne lui auto-dérive
+     * donc aucun `_costumCtx`) aux méthodes qui l'exigent (`_requireCostumCtx` : `previewImport`,
+     * `importElements`, `exportElements`, `addReference`…).
+     *
+     * Résolution (`resolveCostumCtxFromSource`, LIVE-FIRST) :
+     *  1. cache costum LIVE frais (via un `prefetchCostums`/`loadCostumScope` préalable) — champs inclus ;
+     *  2. sinon le REGISTRE bundlé (warm-start) ;
+     *  3. sinon un contexte NU construit depuis `opts` (costum hors cache/registre — schema vide, fields:[]) ;
+     *  4. sinon throw (identité costum introuvable). NB : pour un costum hors registre AVEC ses champs,
+     *     préférer `loadCostumScope(slug)` (async) qui fetche `getcostumjson`.
+     *
+     * Remplace la mutation externe de `_costumCtx` pratiquée par les fronts (champ INTERNE non
+     * contractuel) — cf. site-json `ensureCostumScope`, à migrer sur cette méthode.
+     *
+     * @param slug - Slug du costum (ex. `"equipementsSportifs974"`).
+     * @param opts.costumId / opts.costumType - Identité de l'élément hôte, requise si le costum
+     *   n'est pas dans le registre bundlé (résolue par le front via slug/getinfo).
+     */
+    setCostumScope(slug: string, opts?: {
+        costumId?: string;
+        costumType?: string;
+    }): void;
+    /**
+     * Charge EN LIVE (via `getcostumjson`) le scope costum d'un slug HORS registre bundlé et pose le
+     * contexte COMPLET (champs/presets/hidden) sur cette entité — pour l'ÉDITER avec ses champs costum
+     * sans re-publier la lib (RFC fil C / option 3bis, comble l'édition vide). Contrairement à
+     * `setCostumScope` (sync, registre/ctx nu), digère le typeObj du costum. No-op si le costum ne
+     * couvre pas la collection de l'entité. Idempotent (cache session par slug).
+     */
+    loadCostumScope(slug: string): Promise<boolean>;
     /**
      * Contexte costum de CETTE entité (résolu de son `source.key`) — requis par l'import/export admin.
      * @throws {ApiError} si l'entité n'est pas rattachée à un costum.

package/types/api/User.d.ts

@@ -70,15 +70,26 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      */
     isSuperAdmin(): boolean;
     /**
-     * Admin de plateforme (`roles.adminPlatform === true`). NB : rôle hors-legacy (absent du PHP) mais
-     * HONORÉ par le backend comme super-admin (cf. isUserSuperAdmin/deleteElement) ; posé en base, pas par le code.
+     * Admin de plateforme (`roles.adminPlatform === true`). Rôle hors-legacy (absent du PHP), posé en base.
+     * NB : le backend NE le traite PLUS comme super-admin (retiré de `isUserSuperAdmin` pour byte-fidélité) —
+     * ne l'utiliser que pour des features plateforme dédiées, pas pour gater une action que le backend refusera.
      */
     isAdminPlatform(): boolean;
     /**
-     * Accès admin plateforme large : `superAdmin || adminPlatform` (= `isUserSuperAdmin` backend général,
-     * celui de la suppression). Pour gater l'UI ; l'export reste sur `isSuperAdmin()` strict.
+     * Accès admin plateforme large : `superAdmin || adminPlatform`. Pour gater l'UI d'outils plateforme.
+     * ⚠ Le backend n'accorde l'édition/suppression qu'au `superAdmin` strict (+ droits costum) — un
+     * `adminPlatform` pur verra l'UI mais sera refusé au save/delete.
      */
     canPlatformAdmin(): boolean;
+    /**
+     * L'utilisateur connecté est-il ADMIN DU COSTUM `slug` (droit-parapluie back-office) ? = admin (lien
+     * `isAdmin` validé) de l'élément HÔTE du costum. Pendant client de `Authorisation::isCostumAdmin` :
+     * résout le host via `getElementsKey` (slug → contextId/contextType) puis lit
+     * `me.links.<memberOf|projects|events>[hostId].isAdmin`.
+     * ⚠ ASYNC (1 requête) : à résoudre UNE fois par contexte /admin, PAS par ligne de liste.
+     * NB : ne couvre pas le fallback `costum.admins` (rare) — seul le chemin admin-du-host est vérifié client-side.
+     */
+    isCostumAdmin(slug: string): Promise<boolean>;
     /**
        * Récupère le profil complet de l'utilisateur.
        * Si l'utilisateur est connecté, on appelle le endpoint ME_INFO_URL,

package/types/costum/liveDigest.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Digestion RUNTIME d'un costum servi par `getcostumjson` (format legacy brut) en
+ * `CostumRuntimeContext` par collection — permet de résoudre un costum HORS du registre bundlé sans
+ * re-publication (RFC doc/31 fil C, option 3bis). Port fidèle de `tools/parity/scripts/costum-fields.mjs`
+ * (backend), SANS l'inférence de type par valeurs stockées (pas d'accès base côté client ; en pratique
+ * inutile — `setType` BSON natif ne concerne aucun costum déployé). Le type reste DÉCLARÉ (inputType/
+ * rules), l'enum vient de `lists`, la multiplicité de la config.
+ */
+import type { CostumRuntimeContext } from "./runtime.js";
+import type { Collection } from "./types.js";
+/** Sous-objet `costum` renvoyé par `getcostumjson` (data). Champs utiles à la digestion. */
+export interface CostumJsonData {
+    slug?: string;
+    typeObj?: Record<string, TypeObjNode>;
+    lists?: Record<string, unknown>;
+}
+interface TypeObjNode {
+    sameAs?: string;
+    add?: boolean;
+    createLabel?: string;
+    dynFormCostum?: {
+        beforeBuild?: {
+            properties?: Record<string, FieldDef>;
+        };
+        onload?: {
+            actions?: OnloadActions;
+        };
+        onLoads?: {
+            onload?: {
+                actions?: OnloadActions;
+            };
+        };
+    };
+}
+interface OnloadActions {
+    presetValue?: Record<string, unknown>;
+    hide?: Record<string, unknown>;
+}
+interface FieldDef {
+    inputType?: string;
+    label?: string;
+    multiple?: boolean;
+    select2?: {
+        multiple?: boolean;
+    };
+    maximumSelectionLength?: number | string;
+    rules?: {
+        number?: unknown;
+    };
+    list?: string;
+    tagsList?: string;
+    savePath?: string;
+}
+/**
+ * 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).
+ */
+/** Contexte digéré + capacités de création (add/createLabel) + clé `typeObj` (sous-type) du node. */
+export type DigestedCostum = CostumRuntimeContext & {
+    add: boolean;
+    createLabel: string | null;
+    typeKey: string;
+};
+/**
+ * Énumère les FORMULAIRES d'un costum (une entrée par clé `typeObj` portant un `dynFormCostum`) — permet à
+ * l'assistant de générer un CostumFormSchema PAR SOUS-TYPE (ex. poi → `recoveryCenter` ET `article`), là où
+ * `digestCostumJson(collection)` n'en renvoie qu'un. `discriminator` = valeur de `presetValue.type` (le type
+ * estampillé au save qui distingue le sous-type), sinon la clé elle-même.
+ */
+export declare function listCostumFormNodes(data: CostumJsonData): Array<{
+    typeKey: string;
+    collection: string;
+    add: boolean;
+    createLabel: string | null;
+    discriminator?: string;
+}>;
+export declare function digestCostumJson(data: CostumJsonData, collection: Collection, meta: {
+    costumId: string;
+    costumType: string;
+    slug?: string;
+    baseFieldNames?: string[];
+}, opts?: {
+    typeKey?: string;
+}): DigestedCostum | null;
+export {};

package/types/costum/runtime-map.d.ts

@@ -1,3 +1,13 @@
-import type { Collection, CostumCollectionExt } from "./types.js";
-export type CostumRuntimeEntry = Pick<CostumCollectionExt, "schema" | "fields" | "presets" | "hidden">;
+import type { Collection, CostumCollectionExt, CostumExtensionField } from "./types.js";
+/** Variante runtime SYNC (subtype-aware) : sélectionnée par `discriminator` (= serverData.type). */
+export interface CostumRuntimeVariant {
+    discriminator: string | null;
+    schema: object;
+    fields: CostumExtensionField[];
+    presets: Record<string, unknown>;
+    hidden: string[];
+}
+export type CostumRuntimeEntry = Pick<CostumCollectionExt, "schema" | "fields" | "presets" | "hidden"> & {
+    variants?: CostumRuntimeVariant[];
+};
 export declare const COSTUM_RUNTIME: Record<string, Partial<Record<Collection, CostumRuntimeEntry>>>;

package/types/costum/runtime.d.ts

@@ -1,5 +1,23 @@
 import type { CostumExtensionModule, CostumExtensionField, KnownCostumSlug, Collection } from "./types.js";
 import type { BaseEntity } from "../api/BaseEntity.js";
+/**
+ * Invalide le cache costum live — d'UN slug (ex. après avoir modifié ce costum en base), ou de TOUT
+ * (`invalidateCostumCache()`). Le prochain accès refetchera `getcostumjson` (C2e). Sans effet sur le bundle.
+ */
+export declare function invalidateCostumCache(slug?: string): void;
+/**
+ * Énumère TOUS les formulaires costum d'un slug (UN descripteur PAR SOUS-TYPE = clé `typeObj`) via
+ * getcostumjson — pour l'assistant config (génération multi-form + routage `editModalMatch`). Distinct de
+ * `CostumScope.describeForm(collection)` qui n'en renvoie qu'UN par collection. Seuls les sous-types dont la
+ * collection de base est gérée par les fabriques (poi/organizations/projects/events) sont retournés.
+ */
+export declare function describeCostumForms(user: BaseEntity, slug: string): Promise<CostumFormDescriptor[]>;
+/**
+ * Pré-charge EN BATCH les costums (par slug) manquants/périmés du cache live, AVANT un revive synchrone
+ * (finalizer de `searchCostum`, `get()`, `entitySlug`). Dédup + TTL : un slug déjà frais est ignoré.
+ * Chaque fetch qui échoue est avalé (offline → le revive retombera sur le bundle). Concurrence bornée.
+ */
+export declare function prefetchCostums(user: BaseEntity, sourceKeys: (string | null | undefined)[]): Promise<void>;
 /**
  * Contexte costum résolu, attaché à une instance d'entité via `config.costumCtx`.
  * Porté tel quel par `BaseEntity._costumCtx` et consommé par les 3 couches de filtrage.
@@ -56,6 +74,10 @@ export interface CostumFormDescriptor {
      *  Le consommateur les exclut du formulaire (les champs costum portent aussi `hidden` par champ). */
     hidden: string[];
     fields: CostumFieldDescriptor[];
+    /** Clé `typeObj` (sous-type) d'où vient ce form — présent quand issu de `describeCostumForms` (énumération). */
+    typeKey?: string;
+    /** Valeur de `type` estampillée au save qui distingue le sous-type (= presetValue.type, sinon typeKey). */
+    discriminator?: string;
 }
 /**
  * Scope costum : fabrique des entités liées à un costum. Réutilise le `user` (parent, deps, auth)
@@ -68,8 +90,12 @@ export declare class CostumScope {
     private readonly costumId;
     private readonly costumType;
     constructor(user: BaseEntity, slug: KnownCostumSlug | (string & {}), module: CostumExtensionModule, costumId: string, costumType: string);
-    /** Construit le `CostumRuntimeContext` pour une collection donnée (null si le costum ne la couvre pas). */
-    contextFor(collection: Collection): CostumRuntimeContext | null;
+    /**
+     * 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).
+     */
+    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>;
@@ -85,13 +111,15 @@ export declare class CostumScope {
     describeForm(collection: Collection): CostumFormDescriptor | null;
 }
 /**
- * Dérive un `CostumRuntimeContext` SYNCHRONE depuis le `source.key` d'un élément CHARGÉ + sa collection
- * (inc2). Permet aux entités revifiées hors scope (`fromServerData` des résultats `searchCostum`,
- * `me.poi({id})`) de retrouver leurs champs costum (writable + dispatch) sans `me.costum(slug)`.
- * Utilise la map bundlée `COSTUM_RUNTIME` (sync) + `COSTUM_META`. Renvoie null si le costum/collection est
- * inconnu (costum hors registry → résolution live = inc2b).
+ * Dérive un `CostumRuntimeContext` SYNCHRONE depuis le `source.key` d'un élément CHARGÉ + sa collection.
+ * Permet aux entités revifiées (`fromServerData` des résultats `searchCostum`, `me.poi({id})`) de retrouver
+ * leurs champs costum (writable + dispatch) sans `me.costum(slug)`.
+ *
+ * **LIVE-FIRST** (RFC fil C / cadrage C2) : le cache live FRAIS prime (un costum modifié en base est reflété
+ * sans republier), sinon la map bundlée `COSTUM_RUNTIME` (warm-start / offline), sinon ctx nu / null. Le
+ * cache est peuplé par `prefetchCostums` (async, AVANT le revive) ou `me.costum`/`loadCostumScope`.
  */
-export declare function resolveCostumCtxFromSource(sourceKey: string | undefined | null, collection: Collection): CostumRuntimeContext | null;
+export declare function resolveCostumCtxFromSource(sourceKey: string | undefined | null, collection: Collection, type?: string | null): CostumRuntimeContext | null;
 /**
  * Ouvre un scope costum FIELDLESS depuis une entité DÉJÀ CHARGÉE (zéro fetch) : `costumSlug` = slug de
  * l'entité (= `source.key` posé par le backend), `costumId/costumType` = l'entité porteuse. Pendant runtime
@@ -106,3 +134,10 @@ export declare function costumScopeFromEntity(user: BaseEntity, entity: BaseEnti
  *  - slug HORS registry → résolution LIVE via `slug/getinfo` (contextId/contextType) → scope nu (tier 3b).
  */
 export declare function resolveCostumScope(user: BaseEntity, slug: KnownCostumSlug | (string & {})): Promise<CostumScope>;
+/**
+ * Charge EN LIVE le scope costum d'un slug hors registre (getcostumjson) et pose le `CostumRuntimeContext`
+ * de la collection donnée sur l'entité — pour ÉDITER un élément d'un costum non bundlé avec ses champs
+ * (comble l'édition vide L4). Idempotent : ne refetch pas si le cache live couvre déjà (slug, collection).
+ * 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>;

package/types/costum/types.d.ts

@@ -11,6 +11,17 @@ export interface CostumExtensionField {
     enum?: string[];
     multiple?: boolean;
 }
+/** Sous-type (subtype-aware) d'une collection : overlay create/édition résolu par `discriminator` (= presetValue.type). */
+export interface CostumCollectionVariant {
+    typeKey: string;
+    discriminator: string | null;
+    add: boolean;
+    createLabel: string | null;
+    presets: Record<string, unknown>;
+    hidden: string[];
+    schema: object;
+    fields: CostumExtensionField[];
+}
 export interface CostumCollectionExt {
     schema: object;
     fields: CostumExtensionField[];
@@ -18,6 +29,8 @@ export interface CostumCollectionExt {
     hidden: string[];
     add: boolean;
     createLabel: string | null;
+    /** Sous-types : émis SSI >1 form/collection. La racine (schema/fields) reste l'UNION pour la LECTURE. */
+    variants?: CostumCollectionVariant[];
 }
 export interface CostumExtensionModule {
     slug: string;

package/types/index.d.ts

@@ -86,6 +86,7 @@ export type { PaginatorPage, PaginatorState, FundingEnvelopeResult, FundingEnvel
 export { UPDATE_PATH_MAGIC } from "./api/BaseEntity.js";
 export type { CostumScope, CostumRuntimeContext, CostumFormDescriptor, CostumFieldDescriptor, CostumFieldType, } from "./costum/runtime.js";
 export type { Collection, KnownCostumSlug } from "./costum/types.js";
+export { describeCostumForms } from "./costum/runtime.js";
 export { describeEntityForm } from "./forms/entityForm.js";
 export type { EntityFormDescriptor, BaseFieldDescriptor, EntityFieldType, EntityFieldFormat } from "./forms/entityForm.js";
 export type { AllStepsData, PendingUploadValue, PendingUpload, ProcessUploadsOptions, AnswerGetOptions, UploadAnswerFileOptions, UploadAnswerFileResult, GetFilesOptions, AnswerFileItem, } from "./api/Answer.js";