@communecter/cocolight-api-client 1.0.151 → 1.0.152

package/package.json

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

package/src/api/BaseEntity.ts

@@ -48,6 +48,7 @@ import type {
   ProfilBannerData,
   SearchMemberAutocompleteData,
   GetEventsData,
+  SearchEventsCostumData,
   CostumFilterCoformData,
   CostumFilterCoformByPathData,
   GetCountriesData,
@@ -261,6 +262,18 @@ export type CostumContextFields = {
 
 export type WithCostumContext<T> = T & CostumContextFields;
 
+/**
+ * Bornes d'agenda acceptant un `Date` (coercé en ISO par la méthode avant l'envoi — le fil reste
+ * `type:string`). Partagé par `searchEventsCostum` et `getEvents`.
+ */
+type AgendaDateInputs = { startDateUTC?: Date | string; endDateUTC?: Date | string };
+/** Entrée de `searchEventsCostum` : la request, mais les bornes acceptent un `Date`. */
+export type SearchEventsCostumInput =
+  Omit<Partial<SearchEventsCostumData>, keyof AgendaDateInputs> & AgendaDateInputs;
+/** Entrée de `getEvents` : la request, mais les bornes acceptent un `Date`. */
+export type GetEventsInput =
+  Omit<Partial<GetEventsData>, keyof AgendaDateInputs> & AgendaDateInputs;
+
 /**
  * Une valeur distincte d'une thématique CoForm (retournée par `coformFilterByPath`).
  */
@@ -2905,7 +2918,23 @@ export class BaseEntity<TServerData = any> {
    */
   async entity<T extends keyof EntityTypeMap>(entityType: T, entityData: object = {}, config: BaseEntityConfig = {}): Promise<EntityTypeMap[T]> {
     try {
-      const entity = this._entityInstanceData(entityType, entityData, config);
+      // Propagation du scope costum aux ENFANTS créés (chaîne `scope.org().project()` / parent-create
+      // `parent.poi()`) : si CE parent porte un `_costumCtx` et que l'appelant n'a PAS fourni de costumCtx
+      // explicite, l'enfant hérite de l'IDENTITÉ (slug/costumId/costumType = source.key) MAIS avec l'overlay
+      // de champs RE-RÉSOLU pour SA collection (un projet ne reçoit pas les champs d'une org). Création
+      // seulement (un load id/slug fait foi via _setData/source.key).
+      let effectiveConfig = config;
+      if (config.costumCtx === undefined && this._costumCtx && !this._hasAtLeastOne(entityData, ["id", "slug"])) {
+        const p = this._costumCtx;
+        const childCollection = entityType as unknown as Collection;
+        const childCtx: CostumRuntimeContext = resolveCostumCtxFromSource(p.slug, childCollection) ?? {
+          slug: p.slug, costumId: p.costumId, costumType: p.costumType, collection: childCollection,
+          schema: { type: "object", additionalProperties: true, properties: {} },
+          fields: [], presets: {}, hidden: [],
+        };
+        effectiveConfig = { ...config, costumCtx: childCtx };
+      }
+      const entity = this._entityInstanceData(entityType, entityData, effectiveConfig);
 
       const fetchKeysByEntity = {
         citoyens: ["id", "slug"],
@@ -4115,16 +4144,24 @@ export class BaseEntity<TServerData = any> {
   /**
    * Récupérer les événements d'une entitée : liste des événements de l'entité ou elle est "organizer" ou "attendee".
    * Constant : GET_EVENTS
+   * `startDateUTC`/`endDateUTC` acceptent un `Date` ou une string ISO (un `Date` est coercé en ISO).
+   * `recurrency` est typé `false` (garde parité, comme `searchEventsCostum`) : omettre (récurrents inclus
+   * en mode calendrier) ou passer `false` (exclure) ; jamais `true` (le legacy `=== true` l'exclurait → divergence).
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
   async getEvents(
-    data: Partial<GetEventsData> = {},
+    data: GetEventsInput = {},
     options?: { restoredState?: PaginatorState }
   ): Promise<PaginatorPage<EventEntity>> {
-    data.searchType = this._getDefaultFromEndpoint("GET_EVENTS", "searchType") as GetEventsData["searchType"];
+    // DX : `startDateUTC`/`endDateUTC` acceptent un `Date` → coercé en ISO (un Date brut échouerait l'AJV
+    // `type:string`). Cf. convention R0 de normalisation de champs.
+    const finalInput: Partial<GetEventsData> = { ...(data as Partial<GetEventsData>) };
+    if (data.startDateUTC instanceof Date) finalInput.startDateUTC = data.startDateUTC.toISOString();
+    if (data.endDateUTC instanceof Date) finalInput.endDateUTC = data.endDateUTC.toISOString();
+    finalInput.searchType = this._getDefaultFromEndpoint("GET_EVENTS", "searchType") as GetEventsData["searchType"];
     const paginator = this._createPaginatorEngine({
-      initialData: data,
+      initialData: finalInput,
       methodName: "getEvents",
       restoredState: options?.restoredState,
       finalizer: async (finalData) => {
@@ -5261,6 +5298,66 @@ export class BaseEntity<TServerData = any> {
     return page;
   }
 
+  /**
+   * Agenda costum-aware : events scopés au costum (`source.key`) — pendant de `searchCostum` pour les events.
+   * `_withCostumContext` injecte `costumSlug`/`contextId`/`contextType` + `sourceKey=[serverData.slug]` → les
+   * events DU site/hôte costum (au lieu du filtre attendees/organizer FORCÉ de `getEvents`). À appeler sur
+   * l'entité HÔTE du costum (ex. l'entité du déploiement). `sourceKey` surchargeable (agenda multi-sites / réseau).
+   *
+   * **Deux modes** (endpoint `/co2/search/agenda`), selon que tu passes une date ou non :
+   *
+   * 1. **CALENDRIER** — déclenché par `startDateUTC` et/ou `endDateUTC` (l'agenda d'une période) :
+   *    ramène **TOUT** ce qui matche la plage — ponctuels **+ récurrents** (`openingHours`, sauf `recurrency:false`) —
+   *    trié par **occurrence** (`startDateSort`/`startDateSortFormat` calculés côté serveur), résultat = **tableau**.
+   *    **Pas de pagination** serveur : une seule page (`next()`/`prev()` sans effet).
+   * 2. **LISTE** — déclenché par l'**absence** de date (flux paginé) :
+   *    **ponctuels uniquement** (récurrents exclus), triés par `startDate` **décroissant** (plus récents d'abord),
+   *    paginés via `indexMin`/`indexStep` (défaut 30) — `next()`/`prev()` fonctionnent. (Backend : objet keyé `_id`,
+   *    hydraté en tableau d'`Event` côté lib.)
+   *
+   * Le scope costum (`sourceKey`) s'applique dans les **deux** modes.
+   *
+   * `recurrency` est typé `false` (garde parité) : **omettre** (mode calendrier → récurrents inclus) ou passer
+   * `false` (exclure) ; **jamais `true`** — le legacy fait un test strict `=== true` qui exclurait les récurrents
+   * (divergence), valeur donc interdite au type **et** à l'AJV.
+   *
+   * `startDateUTC`/`endDateUTC` acceptent un **`Date` ou une string ISO** : un `Date` est coercé en ISO
+   * (`toISOString()`) avant l'envoi (le fil reste `type:string`). Évite le piège de l'ISO partielle
+   * (`"2026-06-01"` n'est pas un `date-time` AJV valide).
+   *
+  // Mode CALENDRIER — agenda du mois, avec de vrais Date
+   * const debut = new Date("2026-06-01T00:00:00Z");
+   * const page = await org.searchEventsCostum({ startDateUTC: debut, endDateUTC: new Date("2026-06-30T23:59:59Z") });
+   * page.results.forEach((e) => console.log(e.serverData.name, e.serverData.startDateSort));
+   *
+  // Mode LISTE — flux paginé (ponctuels, du plus récent)
+   * let p = await org.searchEventsCostum({ indexStep: 20 });
+   * if (p.hasNext) p = await p.next();
+   */
+  async searchEventsCostum(
+    data: SearchEventsCostumInput = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<EventEntity>> {
+    // DX : coerce les `Date` en ISO (un objet Date échouerait la validation AJV `type:string`) — suit
+    // la convention de normalisation de champs de la lib (R0 : `Date` → `toISOString()`).
+    const finalInput: Partial<SearchEventsCostumData> = { ...(data as Partial<SearchEventsCostumData>) };
+    if (data.startDateUTC instanceof Date) finalInput.startDateUTC = data.startDateUTC.toISOString();
+    if (data.endDateUTC instanceof Date) finalInput.endDateUTC = data.endDateUTC.toISOString();
+    finalInput.searchType = this._getDefaultFromEndpoint("SEARCH_EVENTS_COSTUM", "searchType") as SearchEventsCostumData["searchType"];
+    const paginator = this._createPaginatorEngine({
+      initialData: finalInput,
+      methodName: "searchEventsCostum",
+      restoredState: options?.restoredState,
+      finalizer: this._withCostumContext(
+        (finalData: SearchEventsCostumData) => {
+          delete (finalData as { pathParams?: unknown }).pathParams;
+          return this.endpointApi.searchEventsCostum(finalData);
+        }
+      ),
+    });
+    return paginator.next() as Promise<PaginatorPage<EventEntity>>;
+  }
+
   /**
    * @param data
    *        Paramètres de recherche (partiels — les valeurs manquantes sont complétées

package/src/api/EndpointApi.ts

@@ -2,7 +2,7 @@
 import { ApiAuthenticationError } from "../error.js";
 
 import type ApiClient from "../ApiClient.js";
-import type { DocumentListData, PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, ShareEventsData, InviteEventData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, CoformGetAnswerFilesData, GetCoformCatalogsData, SaveCoformAnswerData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, GetCoformCommontableContributorsData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData } from "./EndpointApi.types.js";
+import type { DocumentListData, PersonRegisterData, AuthenticateUrlData, RefreshTokenUrlData, PasswordRecoveryData, ServerExchangeTokenData, ChangePasswordData, DeleteAccountData, UpdateSettingsData, UpdateBlockDescriptionData, UpdateBlockInfoData, UpdateBlockSocialData, UpdateBlockLocalityData, UpdateBlockSlugData, CheckData, ProfilImageData, ProfilBannerData, GetElementsAboutData, MulticonnectData, GetNewsData, GetNewsByIdData, AddNewsData, AddImageNewsData, AddFileNewsData, DeleteNewsData, UpdateNewsData, ShareNewsData, GetCommentsData, AddCommentsData, DeleteCommentsData, UpdateCommentsData, SearchTagsData, ShowVoteData, GlobalAutocompleteData, CityAutocompleteData, CityAutocompleteByCountryData, SuggestionInputData, GetProjectsNoAdminData, GetProjectsAdminData, GetPoisNoAdminData, GetPoisAdminData, GetOrganizationsNoAdminData, GetOrganizationsAdminData, GetUserEligiblePlacesData, GetMembersNoAdminData, GetMembersAdminData, GetFriendsAdminData, GetSubscriptionsData, GetSubscriptionsAdminData, GetSubscribersData, GetSubscribersAdminData, GetContributorsNoAdminData, GetContributorsAdminData, GetBadgesData, GetBadgesFiltersData, ConnectData, DisconnectData, GetElementsKeyData, GetFavorisData, DeleteFavorisData, AddFavorisData, AddOrganizationData, AddProjectData, AddPoiData, AddEventData, DeleteElementData, AddImageElementData, LinkValidateData, SearchMemberAutocompleteData, GetNotificationsData, GetNotificationsCountData, NotificationUpdateData, MarkNotificationAsReadData, ActivitypubSearchData, ActivitypubLinkData, ActivitypubGetCommunityData, GetBadgeData, AddBadgesData, AssignBadgesData, GetEventsData, SearchEventsCostumData, ShareEventsData, InviteEventData, FollowData, GetCostumJsonData, GlobalAutocompleteCostumData, NavigatorGettlData, CostumEventRequestActorsData, CostumEventRequestSubeventsData, CostumEventRequestElementEventData, CostumEventRequestCategoriesData, CostumEventRequestDatesData, CostumEventRequestEventData, CostumEventRequestLinkTlToEventData, CostumEventRequestLoadContextTagData, GetGalleryData, GetAttendeesNoAdminData, GetAttendeesAdminData, CoformAnswersSearchData, CoformAnswersByIdData, GetCoformByIdData, CoformUploadAnswerFileData, CoformGetAnswerFilesData, GetCoformCatalogsData, SaveCoformAnswerData, GetCoformAnswerHistoryData, GetCoformMultievalDataData, GetCoformCommontableContributorsData, AddVoteData, AddReportAbuseData, UpdatePathValueData, DeleteDocumentByContextData, DeleteDocumentByIdData, DemoteAdminData, CostumFilterCoformData, CostumFilterCoformByPathData, GetCountriesData, SearchZonesData, CoformAnswersByFormsData, GenerateAnswerFromFormData, FundingEnvelopeData, CoremuOperationData, CostumProjectActionRequestNewData, CostumProjectActionRequestSetStatusData, CostumProjectActionRequestSetDateData, CostumProjectActionRequestSetContributorsData, CostumProjectActionRequestCancelData, CostumProjectActionRequestArchiveData, LinkDiscourseAccountData, UnlinkDiscourseAccountData, DiscourseProfileData, DiscourseCheckEmailData, DiscourseDismissLinkData, LinkMediawikiAccountData, UnlinkMediawikiAccountData, GetMediawikiContributionsData, AddClassifiedData, PersonActivateData } from "./EndpointApi.types.js";
 
 /**
  * Classe EndpointApi générée automatiquement depuis endpoints-copie.json
@@ -1366,6 +1366,21 @@ export class EndpointApi {
     return this.call("GET_EVENTS", data);
   }
 
+  /**
+   * Recherche d'events scopée costum (agenda) : Agenda costum-aware : events filtrés par sourceKey/costum + plage de dates. Même endpoint /co2/search/agenda que GET_EVENTS, mais surface costum (PAS le filtre attendees/organizer forcé de GET_EVENTS). Réponse = cible-co2-search-agenda.
+   * Constant : SEARCH_EVENTS_COSTUM
+   * @param data - Données envoyées à l'API
+   * @returns Les données de réponse.
+   * @throws {ApiResponseError} - En cas d'erreur détectée dans la réponse.
+   * @throws {Error} - En cas d'erreur inattendue.
+   */
+  async searchEventsCostum(data: SearchEventsCostumData): Promise<any> {
+    if (!data || typeof data !== "object") {
+      throw new TypeError("Le paramètre data doit être un objet.");
+    }
+    return this.call("SEARCH_EVENTS_COSTUM", data);
+  }
+
   /**
    * Partager un événement : Partage un événement avec d’autres utilisateurs ou entités.
    * Constant : SHARE_EVENTS

package/src/api/EndpointApi.types.ts

@@ -4092,9 +4092,9 @@ export interface GetEventsData {
   countType?: unknown[];
   fediverse: boolean;
   /**
-   * Filtrer les événements récurrents (true/false)
+   * GARDE PARITÉ legacy (identique à SEARCH_EVENTS_COSTUM) : seule valeur autorisée `false` (= exclure les récurrents) OU champ omis (= inclure, défaut). NE JAMAIS envoyer `true` — le legacy teste STRICTEMENT $recurrency === true (AgendaAction.php:65) qui échoue sur la string POST → exclut les récurrents, alors que notre backend les inclurait (divergence assumée). En interdisant `true`, omis→inclus et false→exclus se comportent pareil sur les 2 serveurs.
    */
-  recurrency?: boolean;
+  recurrency?: false;
   filters?: {
     $or?: Record<string, unknown>;
     /**
@@ -4107,6 +4107,99 @@ export interface GetEventsData {
 }
 
 
+export interface SearchEventsCostumData {
+  searchType: "events"[];
+  indexMin: number;
+  indexStep: number;
+  /**
+   * Date de début (UTC)
+   */
+  startDateUTC?: string;
+  /**
+   * Date de fin (UTC)
+   */
+  endDateUTC?: string;
+  /**
+   * Nom ou terme
+   */
+  name?: string;
+  /**
+   * Type d’événement
+   */
+  type?:
+    | "workshop"
+    | "competition"
+    | "concert"
+    | "contest"
+    | "conference"
+    | "debate"
+    | "exhibition"
+    | "festival"
+    | "crowdfunding"
+    | "fair"
+    | "course"
+    | "protest"
+    | "market"
+    | "film"
+    | "getTogether"
+    | "meeting"
+    | "spectacle"
+    | "internship"
+    | "stand"
+    | "others";
+  /**
+   * Liste des localités ciblées
+   */
+  locality?: {
+    /**
+     * This interface was referenced by `undefined`'s JSON-Schema definition
+     * via the `patternProperty` "^[^\s]+$".
+     */
+    [k: string]: {
+      [k: string]: unknown;
+    };
+  };
+  count?: boolean;
+  countType?: unknown[];
+  fediverse: boolean;
+  /**
+   * GARDE PARITÉ legacy : seule valeur autorisée `false` (= exclure les récurrents) OU champ omis (= inclure, défaut). NE JAMAIS envoyer `true` — le legacy teste STRICTEMENT $recurrency === true (AgendaAction.php:65) qui échoue sur la string POST → exclut les récurrents, alors que notre backend les inclurait (divergence assumée). En interdisant `true`, omis→inclus et false→exclus se comportent pareil sur les 2 serveurs.
+   */
+  recurrency?: false;
+  /**
+   * Filtres Mongo additionnels (buildFilters).
+   */
+  filters?: {
+    [k: string]: unknown;
+  };
+  /**
+   * Scope costum : events dont source.keys/reference.costum ∈ sourceKey (agenda multi-sites/réseau). Auto-injecté = [slug de l’entité] si absent.
+   */
+  sourceKey?: string[];
+  /**
+   * Filtre par tags ($in, ou $all via options.tags.verb).
+   */
+  searchTags?: string[];
+  /**
+   * Events liés (links.<type>.<id>).
+   */
+  links?: {
+    type: string;
+    id: string;
+    [k: string]: unknown;
+  }[];
+  subType?: string;
+  category?: string;
+  section?: string | string[];
+  contextId?: string;
+  contextType?: string;
+  costumSlug?: string;
+  costumId?: string;
+  costumType?: string;
+  [k: string]: unknown;
+}
+
+
 export interface ShareEventsData {
   /**
    * ID de l’événement à partager

package/src/api/User.ts

@@ -1,7 +1,7 @@
 import { ApiError } from "../error.js";
 import { BaseEntity } from "./BaseEntity.js";
 import { Notifications } from "./Notifications.js";
-import { resolveCostumScope, type CostumScope } from "../costum/runtime.js";
+import { resolveCostumScope, costumScopeFromEntity, type CostumScope } from "../costum/runtime.js";
 import { UserMixin } from "../mixin/UserMixin.js";
 import { createSocialTransform } from "../types/transforms.js";
 
@@ -733,10 +733,19 @@ export class User extends BaseEntity<UserItemNormalized> {
    * const org = await tl.organization({ name: "Mon TL", manageModel: "Association", buildingSurfaceArea: "120" });
    * await org.save();
    *
-   * @param slug - slug d'un costum connu (registry généré). Slug hors registry => erreur (live-fetch = inc2).
+   * Deux formes :
+   *  - `me.costum(slug)` : slug d'un costum du registry (autocomplété) OU n'importe quel slug (`string`) —
+   *    le backend reste l'autorité de validité (`found`). Slug hors registry sans champ → inc1b (résolution live).
+   *  - `me.costum(entity)` : ouvre un scope FIELDLESS depuis une entité DÉJÀ CHARGÉE (org/projet/event qui porte
+   *    un costum), zéro fetch — `source.key` = slug de l'entité. Cas « créer sous ce site nu ».
+   *
+   * @param arg - slug (`KnownCostumSlug | string`) OU une entité chargée porteuse d'un costum.
    */
-  async costum(slug: KnownCostumSlug): Promise<CostumScope> {
-    return resolveCostumScope(this, slug);
+  async costum(slug: KnownCostumSlug | (string & {})): Promise<CostumScope>;
+  async costum(entity: BaseEntity): Promise<CostumScope>;
+  async costum(arg: KnownCostumSlug | (string & {}) | BaseEntity): Promise<CostumScope> {
+    if (typeof arg === "string") return resolveCostumScope(this, arg);
+    return costumScopeFromEntity(this, arg);
   }
 
   /**

package/src/api/UserApi.ts

@@ -1,5 +1,4 @@
 import ApiClient from "../ApiClient.js";
-import { ApiError, ApiResponseError } from "../error.js";
 import { Action } from "./Action.js";
 import { Answer } from "./Answer.js";
 import { Badge } from "./Badge.js";
@@ -12,6 +11,8 @@ import { Organization } from "./Organization.js";
 import { Poi } from "./Poi.js";
 import { Project } from "./Project.js";
 import { User } from "./User.js";
+import { COSTUM_REQUEST_ENVELOPE } from "../costum/symbol.js";
+import { ApiError, ApiResponseError } from "../error.js";
 
 type AxiosResponse = import("axios").AxiosResponse;
 
@@ -105,14 +106,24 @@ export class UserApi {
    * @param params.username - Nom d'utilisateur.
    * @param params.email - Adresse email.
    * @param params.pwd - Mot de passe.
+   * @param params.costumSlug - (option) slug du costum de déploiement → estampille `source.key` du citoyen
+   *   côté backend (port Person::insert). `costumId`/`costumType` = entité porteuse (requis si le slug n'est
+   *   pas un doc `costum`, ex. un site porté par une org).
    * @returns Réponse brute de l'API.
    * @throws {ApiResponseError} Si l'API retourne un échec (`result === false`).
    */
-  async register({ name, username, email, pwd }: { name: string; username: string; email: string; pwd: string }): Promise<any> {
+  async register({ name, username, email, pwd, costumSlug, costumId, costumType }: { name: string; username: string; email: string; pwd: string; costumSlug?: string; costumId?: string; costumType?: string }): Promise<any> {
     return this.client.safeCall(async () => {
-      const response = await this.client.callEndpoint("PERSON_REGISTER", {
-        name, username, email, pwd
-      });
+      const data: Record<string, unknown> = { name, username, email, pwd };
+      // Contexte costum (déploiement) injecté via l'enveloppe (cf. element/save) : `callEndpoint` fusionne le
+      // `context` dans le body + relâche l'AJV. Le backend lit costumSlug/Id/Type → estampille `source` (origin/key/keys).
+      if (costumSlug) {
+        (data as Record<symbol, unknown>)[COSTUM_REQUEST_ENVELOPE] = {
+          properties: {},
+          context: { costumSlug, ...(costumId ? { costumId } : {}), ...(costumType ? { costumType } : {}) },
+        };
+      }
+      const response = await this.client.callEndpoint("PERSON_REGISTER", data);
 
       if (!isAxiosResponse(response)) {
         throw new ApiError("Requête mise en file (offline/circuit breaker)", 503, response);

package/src/costum/runtime.ts

@@ -19,6 +19,7 @@ import { COSTUM_RUNTIME } from "./runtime-map.js";
 
 import type { CostumExtensionModule, CostumExtensionField, KnownCostumSlug, Collection } from "./types.js";
 import type { BaseEntity } from "../api/BaseEntity.js";
+import type { GetElementsKeyResponse } from "../types/api-responses.js";
 
 /**
  * Contexte costum résolu, attaché à une instance d'entité via `config.costumCtx`.
@@ -99,13 +100,13 @@ type ScopeCollection = "poi" | "organizations" | "projects" | "events";
  * et n'altère jamais l'état partagé — chaque entité reçoit son propre `_costumCtx`.
  */
 export class CostumScope {
-  readonly slug: KnownCostumSlug;
+  readonly slug: KnownCostumSlug | (string & {});
   private readonly user: BaseEntity;
   private readonly module: CostumExtensionModule;
   private readonly costumId: string;
   private readonly costumType: string;
 
-  constructor(user: BaseEntity, slug: KnownCostumSlug, module: CostumExtensionModule, costumId: string, costumType: string) {
+  constructor(user: BaseEntity, slug: KnownCostumSlug | (string & {}), module: CostumExtensionModule, costumId: string, costumType: string) {
     this.user = user;
     this.slug = slug;
     this.module = module;
@@ -191,8 +192,23 @@ export class CostumScope {
 export function resolveCostumCtxFromSource(sourceKey: string | undefined | null, collection: Collection): CostumRuntimeContext | null {
   if (!sourceKey) return null;
   const entry = COSTUM_RUNTIME[sourceKey]?.[collection];
-  if (!entry) return null;
   const meta = COSTUM_META[sourceKey as KnownCostumSlug];
+  if (!entry) {
+    // Pas d'overlay de champs pour (sourceKey, collection). Si le costum est CONNU (meta présent), on
+    // reconnaît quand même le scope (source.key = identité) via un ctx NU (fields:[]) — l'élément est
+    // rattaché au costum sans champ spécifique. Costum hors registry → null (résolution live = inc1b).
+    if (!meta) return null;
+    return {
+      slug: sourceKey,
+      costumId: meta.costumId,
+      costumType: meta.costumType,
+      collection,
+      schema: { type: "object", additionalProperties: true, properties: {} },
+      fields: [],
+      presets: {},
+      hidden: [],
+    };
+  }
   const props = (entry.schema as { properties?: Record<string, unknown> }).properties ?? {};
   return {
     slug: sourceKey,
@@ -206,16 +222,53 @@ export function resolveCostumCtxFromSource(sourceKey: string | undefined | null,
   };
 }
 
+/** Module costum « nu » (scope d'IDENTITÉ sans overlay de champs) : `collections` vide → `create()` no-op. */
+function fieldlessModule(slug: string): CostumExtensionModule {
+  return { slug, collections: {} };
+}
+
+/**
+ * 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
+ * exact de `_withCostumContext` (BaseEntity), pour la voie « entité tenue » (un site nu sans form). Le
+ * backend re-gate `found` sur l'existence d'un costum sur l'entité → un site sans costum n'estampille rien.
+ */
+export function costumScopeFromEntity(user: BaseEntity, entity: BaseEntity): CostumScope {
+  const sd = entity.serverData as { slug?: string | null; id?: string | null } | undefined;
+  const slug = sd?.slug;
+  const id = sd?.id;
+  if (typeof slug !== "string" || slug.trim() === "") {
+    throw new ApiError("me.costum(entity) : l'entité n'a pas de slug (charge-la d'abord).", 400);
+  }
+  if (typeof id !== "string" || !id) {
+    throw new ApiError("me.costum(entity) : l'entité n'a pas d'id.", 400);
+  }
+  return new CostumScope(user, slug, fieldlessModule(slug), id, entity.getEntityType());
+}
+
 /**
- * Résout un `CostumScope` pour un user connecté. Known-only (inc1) : charge le module généré
- * (code-split via dynamic import) + le meta du registry. Slug inconnu => erreur explicite.
+ * Résout un `CostumScope` par SLUG pour un user connecté.
+ *  - slug à champs (meta + loader) → charge le module généré (code-split via dynamic import).
+ *  - slug CONNU sans loader (fieldless) → scope d'identité nu (`collections:{}`).
+ *  - slug HORS registry → résolution LIVE via `slug/getinfo` (contextId/contextType) → scope nu (tier 3b).
  */
-export async function resolveCostumScope(user: BaseEntity, slug: KnownCostumSlug): Promise<CostumScope> {
-  const meta = COSTUM_META[slug];
-  const loader = COSTUM_SCHEMAS[slug];
-  if (!meta || !loader) {
-    throw new ApiError(`Costum inconnu : "${slug}". (Le live-fetch d'un costum hors registry n'est pas encore supporté.)`, 404);
+export async function resolveCostumScope(user: BaseEntity, slug: KnownCostumSlug | (string & {})): Promise<CostumScope> {
+  const meta = COSTUM_META[slug as KnownCostumSlug];
+  const loader = COSTUM_SCHEMAS[slug as KnownCostumSlug];
+  if (meta && loader) {
+    const { default: module } = await loader();
+    return new CostumScope(user, slug, module, meta.costumId, meta.costumType);
+  }
+  if (meta) {
+    // Connu mais sans overlay de champs : scope d'identité pur (estampille source.key, aucun champ costum).
+    return new CostumScope(user, slug, fieldlessModule(slug), meta.costumId, meta.costumType);
+  }
+  // Tier 3b — slug HORS registry : résolution LIVE slug → {contextId, contextType} via la route `slug/getinfo`
+  // (GET_ELEMENTS_KEY, « none »). Couvre les sites fieldless/cold/futurs sans rien bundler. costumSlug = le slug
+  // demandé (slug ENTITÉ) ; le backend re-gate `found` sur l'existence d'un costum sur l'entité résolue.
+  const info = await user.endpointApi.getElementsKey({ pathParams: { slug } }) as GetElementsKeyResponse;
+  if (info?.contextId && info?.contextType) {
+    return new CostumScope(user, slug, fieldlessModule(slug), String(info.contextId), String(info.contextType));
   }
-  const { default: module } = await loader();
-  return new CostumScope(user, slug, module, meta.costumId, meta.costumType);
+  throw new ApiError(`Costum inconnu : "${slug}" — slug introuvable (résolution live slug/getinfo).`, 404);
 }