@communecter/cocolight-api-client 1.0.194 → 1.0.196

package/types/api/User.d.ts

@@ -14,7 +14,7 @@ export declare class User extends BaseEntity<UserItemNormalized> {
     static entityType: "citoyens";
     static entityTag: string;
     static SCHEMA_CONSTANTS: string[];
-    static UPDATE_BLOCKS: Map<"UPDATE_BLOCK_DESCRIPTION" | "UPDATE_BLOCK_INFO" | "UPDATE_BLOCK_SOCIAL" | "UPDATE_BLOCK_LOCALITY" | "UPDATE_BLOCK_SLUG" | "PROFIL_IMAGE", "updateImageProfil" | "updateDescription" | "updateSocial" | "updateLocality" | "updateInfo" | "updateSlug">;
+    static UPDATE_BLOCKS: Map<"UPDATE_BLOCK_SLUG" | "PROFIL_IMAGE" | "UPDATE_BLOCK_DESCRIPTION" | "UPDATE_BLOCK_INFO" | "UPDATE_BLOCK_LOCALITY" | "UPDATE_BLOCK_SOCIAL", "updateImageProfil" | "updateSlug" | "updateDescription" | "updateLocality" | "updateInfo" | "updateSocial">;
     defaultFields: Record<string, any>;
     removeFields: string[];
     transforms: Record<string, (val: any, full: any) => any>;
@@ -742,6 +742,9 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      *
      * @param {Object} [options] - Options de la méthode
      * @param {boolean} [options.admin=false] - Si true, utilise "admin" comme connectType au lieu du type par défaut (connectTypeConnect)
+     * @param {string[]} [options.roles] - Rôles à poser sur le lien CRÉÉ (transmis à `CONNECT`, écrits des deux
+     *   côtés). Omis ou vide → corps inchangé. Ne sert qu'à la création : pour corriger les rôles d'un lien
+     *   déjà établi, utiliser {@link User.setRoles}.
      * @returns {Promise<unknown>} La réponse de l'API après création de la demande
      * @throws {ApiError} Si l'utilisateur n'est pas connecté, pas admin, ou si le parent n'est pas défini
      * @throws {ApiError} Si l'utilisateur est déjà en attente de validation
@@ -757,10 +760,14 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      *
      * // Avec le type admin explicite
      * await user.sendRequestToJoinParent({ admin: true });
+     *
+     * // Avec des rôles posés dès l'invitation
+     * await user.sendRequestToJoinParent({ roles: ["Coordonnatrice parentalité Arrageois"] });
      * ```
      */
-    sendRequestToJoinParent({ admin }?: {
-        admin: boolean;
+    sendRequestToJoinParent({ admin, roles }?: {
+        admin?: boolean;
+        roles?: string[];
     }): Promise<unknown>;
     /**
      * Valide une demande de membre en attente de validation.
@@ -845,6 +852,35 @@ export declare class User extends BaseEntity<UserItemNormalized> {
      * ```
      */
     promoteToAdmin(): Promise<unknown>;
+    /**
+     * Définit les rôles de cet utilisateur sur son lien avec l'entité parente (`LINK_SET_ROLES`).
+     *
+     * ⚠️ REMPLACEMENT INTÉGRAL, pas un ajout/retrait : le tableau envoyé devient la liste des rôles du lien,
+     * des deux côtés (contexte et citoyen). Pour ajouter un rôle, envoyer les rôles actuels + le nouveau ;
+     * pour en retirer un, les rôles actuels privés de celui-ci. **`setRoles([])` efface TOUS les rôles**
+     * (`$unset` côté backend).
+     *
+     * Réservé aux admins de l'entité parente (organisation, projet ou événement). Le lien doit exister.
+     * Le backend répond HTTP 200 avec `{result:false}` en cas de refus : l'erreur est levée en `ApiResponseError`.
+     * Le contexte costum du PARENT est transmis (droit d'admin du costum, comme les autres actions de lien).
+     *
+     * @param roles - Liste COMPLÈTE des rôles voulus (vide = tout effacer).
+     * @returns La réponse de l'API (`{result, msg, memberOfid, memberid, roles}`).
+     * @throws {ApiError} Si le parent n'est pas défini, si l'appelant n'en est pas admin, ou si l'utilisateur
+     *   n'a aucun lien avec le parent.
+     * @throws {ApiResponseError} Si le backend refuse (ex. non admin côté serveur).
+     *
+     * @example
+     * ```typescript
+     * const org = await me.organization({ slug: "parent62" });
+     * const { results } = await org.getMembers();
+     * const membre = results[0];
+     * // Source fiable des rôles actuels : le lien côté ORGANISATION (links.members.<id>.roles).
+     * const actuels = org.serverData.links?.members?.[membre.id!]?.roles ?? [];
+     * await membre.setRoles([...actuels, "Coordonnatrice parentalité Arrageois"]);
+     * ```
+     */
+    setRoles(roles: string[]): Promise<unknown>;
     /**
      * Rétrograde un admin au statut de membre ordinaire.
      *

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>;