@communecter/cocolight-api-client 1.0.106 → 1.0.108

package/package.json

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

package/src/api/BaseEntity.ts

@@ -124,6 +124,29 @@ type ReadableWithMeta = import("stream").Readable & { path?: string, mimeType?:
 type UploadInput = File | Blob | Buffer | import("stream").Readable;
 type ValidatedUpload = File | Buffer | ReadableWithMeta;
 
+// Type pour le curseur de pagination utilisé dans _createPaginatorEngine
+type PaginationCursor = {
+  searchType?: string[];
+  searchBy?: string;
+  countType?: string[];
+  ranges?: Record<string, { indexMin: number; indexMax: number }>;
+  indexMin?: number;
+  indexMax?: number;
+  indexStep?: number;
+  [key: string]: unknown;  // Pour les propriétés additionnelles dynamiques
+};
+
+/**
+ * État interne du paginateur, utilisé pour la restauration.
+ */
+export type PaginatorState = {
+  cursor: PaginationCursor | null;
+  count: number;
+  index: number;
+  history: PaginationCursor[];
+  sizes: number[];
+};
+
 // PaginatorPage interface pour les résultats paginés
 export interface PaginatorPage<T> {
   count: {
@@ -136,6 +159,11 @@ export interface PaginatorPage<T> {
   hasPrev: boolean;
   next?: () => Promise<PaginatorPage<T>>;
   prev?: () => Promise<PaginatorPage<T>>;
+  // Métadonnées pour la sérialisation/restauration
+  _initialData?: Record<string, any>;
+  _state?: PaginatorState;
+  _entity?: BaseEntity<any>;
+  _methodName?: string;
 }
 
 /**
@@ -207,18 +235,6 @@ type JsonSchemaProperty = Record<string, unknown> & {
   const?: unknown;
 };
 
-// Type pour le curseur de pagination utilisé dans _createPaginatorEngine
-type PaginationCursor = {
-  searchType?: string[];
-  searchBy?: string;
-  countType?: string[];
-  ranges?: Record<string, { indexMin: number; indexMax: number }>;
-  indexMin?: number;
-  indexMax?: number;
-  indexStep?: number;
-  [key: string]: unknown;  // Pour les propriétés additionnelles dynamiques
-};
-
 interface FilterValueCombined {
   $in: string[];
   $exists: boolean;
@@ -742,7 +758,7 @@ export class BaseEntity<TServerData = any> {
         ...(this.parent.serverData.links && { links: this.parent.serverData.links })
       };
     }
-    
+
     return {
       __entityTag: this.__entityTag,
       __isSerializedEntity: true,
@@ -912,9 +928,7 @@ export class BaseEntity<TServerData = any> {
     }
     const { serverData } = json as { serverData: object };
 
-    const instance = this.fromServerData(this._revive(serverData, parent), parent as ApiClient | ParentLike, deps || {});
-
-    return instance;
+    return this.fromServerData(this._revive(serverData, parent), parent as ApiClient | ParentLike, deps || {});
   }
 
   /**
@@ -3185,12 +3199,17 @@ export class BaseEntity<TServerData = any> {
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
-  async getOrganizations(data: Partial<GetOrganizationsAdminData | GetOrganizationsNoAdminData> = {}): Promise<PaginatorPage<Organization>> {
+  async getOrganizations(
+    data: Partial<GetOrganizationsAdminData | GetOrganizationsNoAdminData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<Organization>> {
     data.searchType = this._getDefaultFromEndpoint("GET_ORGANIZATIONS_NO_ADMIN", "searchType") as GetOrganizationsNoAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getOrganizations",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         if(this.isMe){
           finalData.pathParams = { type: this.getEntityType(), id: this.id };
@@ -3226,12 +3245,17 @@ export class BaseEntity<TServerData = any> {
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
-  async getProjects(data: Partial<GetProjectsAdminData | GetProjectsNoAdminData> = {}): Promise<PaginatorPage<Project>> {
+  async getProjects(
+    data: Partial<GetProjectsAdminData | GetProjectsNoAdminData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<Project>> {
     data.searchType = this._getDefaultFromEndpoint("GET_PROJECTS_ADMIN", "searchType") as GetProjectsAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getProjects",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         if(this.isMe){
           finalData.pathParams = { type: this.getEntityType(), id: this.id };
@@ -3271,10 +3295,15 @@ export class BaseEntity<TServerData = any> {
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
-  async getEvents(data: Partial<GetEventsData> = {}): Promise<PaginatorPage<EventEntity>> {
+  async getEvents(
+    data: Partial<GetEventsData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<EventEntity>> {
     data.searchType = this._getDefaultFromEndpoint("GET_EVENTS", "searchType") as GetEventsData["searchType"];
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getEvents",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         delete finalData?.pathParams;
         finalData.filters = {
@@ -3297,12 +3326,17 @@ export class BaseEntity<TServerData = any> {
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
-  async getPois(data: Partial<GetPoisAdminData | GetPoisNoAdminData> = {}): Promise<PaginatorPage<Poi>> {
+  async getPois(
+    data: Partial<GetPoisAdminData | GetPoisNoAdminData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<Poi>> {
     data.searchType = this._getDefaultFromEndpoint("GET_POIS_ADMIN", "searchType") as GetPoisAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getPois",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         if(this.isMe){
           finalData.pathParams = { type: this.getEntityType(), id: this.id };
@@ -3334,12 +3368,17 @@ export class BaseEntity<TServerData = any> {
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
-  async getSubscribers(data: Partial<GetSubscribersData> = {}): Promise<PaginatorPage<User>> {
+  async getSubscribers(
+    data: Partial<GetSubscribersData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<User>> {
     data.searchType = this._getDefaultFromEndpoint("GET_SUBSCRIBERS", "searchType") as GetSubscribersData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getSubscribers",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         delete finalData?.pathParams;
 
@@ -3362,12 +3401,17 @@ export class BaseEntity<TServerData = any> {
    * @param data - Paramètres (partiels) de recherche/pagination.
    * @returns - Les données de réponse.
    */
-  async getBadgesIssuer(data: Partial<GetBadgesData> = {}): Promise<PaginatorPage<Badge>> {
+  async getBadgesIssuer(
+    data: Partial<GetBadgesData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<Badge>> {
     data.searchType = this._getDefaultFromEndpoint("GET_BADGES", "searchType") as GetBadgesData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getBadgesIssuer",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         delete finalData?.pathParams;
   
@@ -3917,14 +3961,18 @@ export class BaseEntity<TServerData = any> {
   /**
    * Coeur de pagination stateless et réutilisable.
    */
-  _createPaginatorEngine<TData extends Record<string, any>, TOut>({ initialData, finalizer }: {
+  _createPaginatorEngine<TData extends Record<string, any>, TOut>({ initialData, finalizer, methodName, restoredState }: {
     initialData: Partial<TData>,
-    finalizer: (data: TData) => Promise<FinalizerResult<TOut>>
+    finalizer: (data: TData) => Promise<FinalizerResult<TOut>>,
+    methodName: string,
+    restoredState?: PaginatorState
   }): { next: () => Promise<PaginatorPage<TOut>> } {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const Entity = this;
 
-    const state: { cursor: PaginationCursor | null; count: number; index: number; history: PaginationCursor[]; sizes: number[] } = { cursor: null, count: 0, index: 0, history: [], sizes: [] };
+    const state: PaginatorState = restoredState
+      ? { ...restoredState }
+      : { cursor: null, count: 0, index: 0, history: [], sizes: [] };
 
     const hasStep = (d: PaginationCursor | null | undefined) => Boolean(d?.indexStep && d.indexStep > 0);
 
@@ -4018,7 +4066,12 @@ export class BaseEntity<TServerData = any> {
             state.cursor = { ...previous };
             return getPage(false);
           }
-          : undefined
+          : undefined,
+        // Métadonnées pour la restauration
+        _initialData: { ...initialData },
+        _state: state,
+        _entity: Entity,
+        _methodName: methodName
       };
     }
 
@@ -4107,9 +4160,14 @@ export class BaseEntity<TServerData = any> {
    *   console.log(nextPage.pageNumber, nextPage.results.length);
    * }
    */
-  async searchCostum(data: Partial<GlobalAutocompleteCostumData> = {}): Promise<PaginatorPage<any>> {
+  async searchCostum(
+    data: Partial<GlobalAutocompleteCostumData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<any>> {
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "searchCostum",
+      restoredState: options?.restoredState,
       finalizer: this._withCostumContext(
         (finalData: GlobalAutocompleteCostumData) => this.endpointApi.globalAutocompleteCostum(finalData)
       ),
@@ -4387,9 +4445,14 @@ export class BaseEntity<TServerData = any> {
   }
 
   
-  async coformAnswersSearch(data: Partial<CoformAnswersSearchData> = {}): Promise<PaginatorPage<any>> {
+  async coformAnswersSearch(
+    data: Partial<CoformAnswersSearchData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<any>> {
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "coformAnswersSearch",
+      restoredState: options?.restoredState,
       finalizer: this._withCostumContext(
         (finalData: CoformAnswersSearchData) => this.endpointApi.coformAnswersSearch(finalData)
       ),
@@ -4397,6 +4460,96 @@ export class BaseEntity<TServerData = any> {
     return paginator.next() as Promise<PaginatorPage<any>>;
   }
 
+  /**
+   * ───────────────────────────────
+   * Pagination restoration methods
+   * ───────────────────────────────
+   */
+
+  /**
+   * Restaure une pagination depuis des données JSON sérialisées.
+   * Ne fait PAS d'appel API - utilise les results déjà présents.
+   * Les fonctions next() et prev() font des appels API quand appelées.
+   *
+   * @param paginationJson - Les données JSON sérialisées d'une pagination
+   * @param apiClientOrEntity - ApiClient ou entité parente pour la reconstruction des entités
+   * @returns Une page de pagination hydratée avec next() et prev() fonctionnels
+   *
+   * @example
+   * // Sérialiser une pagination
+   * const firstPage = await user.getPois();
+   * const json = JSON.stringify(firstPage);
+   *
+   * // Restaurer la pagination (sans appel API) - passer l'ApiClient
+   * const restored = BaseEntity.restorePaginationFromJSON(JSON.parse(json), api.getClientInstance());
+   *
+   * // next() fait un appel API pour récupérer la page suivante
+   * const secondPage = await restored.next?.();
+   */
+  static restorePaginationFromJSON<T>(
+    paginationJson: any,
+    apiClientOrEntity: ApiClient | BaseEntity<any>
+  ): PaginatorPage<T> {
+    // 1. Déterminer l'entité parent
+    // Si c'est déjà une entité, l'utiliser directement
+    // Sinon (ApiClient), restaurer depuis le JSON
+    const entity = apiClientOrEntity instanceof BaseEntity
+      ? apiClientOrEntity
+      : fromEntityJSON(paginationJson._entity, apiClientOrEntity) as BaseEntity<any>;
+
+    // 2. Restaurer les results (sans appel API)
+    const results = paginationJson.results.map((r: any) =>
+      fromEntityJSON(r, entity)
+    ) as T[];
+
+    // 3. Récupérer les métadonnées
+    const methodName = paginationJson._methodName;
+    const initialData = paginationJson._initialData;
+    const savedState: PaginatorState = paginationJson._state;
+
+    // 4. Construire l'objet pagination restauré
+    return {
+      results,
+      count: paginationJson.count,
+      hasNext: paginationJson.hasNext,
+      hasPrev: paginationJson.hasPrev,
+      pageIndex: paginationJson.pageIndex,
+      pageNumber: paginationJson.pageNumber,
+      next: paginationJson.hasNext
+        ? async () => {
+          const method = (entity as any)[methodName];
+          if (typeof method !== "function") {
+            throw new Error(`Méthode ${methodName} non trouvée sur l'entité`);
+          }
+          // Appeler la méthode avec restoredState pour recréer le paginateur
+          // puis appeler next() pour obtenir la page suivante
+          const paginator = await method.call(entity, initialData, {
+            restoredState: savedState
+          });
+          return paginator.next?.() ?? paginator;
+        }
+        : undefined,
+      prev: paginationJson.hasPrev
+        ? async () => {
+          const method = (entity as any)[methodName];
+          if (typeof method !== "function") {
+            throw new Error(`Méthode ${methodName} non trouvée sur l'entité`);
+          }
+          // Appeler la méthode avec restoredState pour recréer le paginateur
+          // puis appeler prev() pour obtenir la page précédente
+          const paginator = await method.call(entity, initialData, {
+            restoredState: savedState
+          });
+          return paginator.prev?.() ?? paginator;
+        }
+        : undefined,
+      _initialData: initialData,
+      _state: savedState,
+      _entity: entity,
+      _methodName: methodName
+    };
+  }
+
 }
 
 export default BaseEntity;

package/src/api/Event.ts

@@ -1,5 +1,5 @@
 import { ApiError } from "../error.js";
-import { BaseEntity, PaginatorPage } from "./BaseEntity.js";
+import { BaseEntity, PaginatorPage, PaginatorState } from "./BaseEntity.js";
 import { transformEntityRefs } from "../types/transforms.js";
 
 import type { AddEventData, GetAttendeesAdminData, GetAttendeesNoAdminData } from "./EndpointApi.types.js";
@@ -210,6 +210,7 @@ export class Event extends BaseEntity<EventItemNormalized> {
       isAdminPending?: boolean;
       isInviting?: boolean;
       roles?: any[];
+      restoredState?: PaginatorState;
     } = {}
   ): Promise<PaginatorPage<User>> {
     data.searchType = this._getDefaultFromEndpoint("GET_ATTENDEES_NO_ADMIN", "searchType") as GetAttendeesNoAdminData["searchType"];
@@ -217,6 +218,8 @@ export class Event extends BaseEntity<EventItemNormalized> {
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getAttendees",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
 
         const { toBeValidated, isAdmin, isInviting, isAdminPending, roles = [] } = options;

package/src/api/Organization.ts

@@ -2,7 +2,7 @@ import { ApiError } from "../error.js";
 import { BaseEntity } from "./BaseEntity.js";
 import { createSocialTransform } from "../types/transforms.js";
 
-import type { PaginatorPage } from "./BaseEntity.js";
+import type { PaginatorPage, PaginatorState } from "./BaseEntity.js";
 import type {
   AddOrganizationData,
   GetMembersAdminData,
@@ -320,6 +320,7 @@ export class Organization extends BaseEntity<OrganizationItemNormalized> {
       isAdminPending?: boolean;
       isInviting?: boolean;
       roles?: any[];
+      restoredState?: PaginatorState;
     } = {}
   ): Promise<PaginatorPage<User | Organization>> {
 
@@ -335,6 +336,8 @@ export class Organization extends BaseEntity<OrganizationItemNormalized> {
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getMembers",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
 
         const { toBeValidated, isAdmin, isAdminPending, isInviting, roles = [] } = options;

package/src/api/Project.ts

@@ -3,7 +3,7 @@ import { BaseEntity } from "./BaseEntity.js";
 import { createSocialTransform, transformEntityRefs } from "../types/transforms.js";
 
 
-import type { PaginatorPage } from "./BaseEntity.js";
+import type { PaginatorPage, PaginatorState } from "./BaseEntity.js";
 import type { AddProjectData, GetContributorsAdminData, GetContributorsNoAdminData } from "./EndpointApi.types.js";
 import type { Organization } from "./Organization.js";
 import type { User } from "./User.js";
@@ -235,6 +235,7 @@ export class Project extends BaseEntity<ProjectItemNormalized> {
       isAdminPending?: boolean;
       isInviting?: boolean;
       roles?: any[];
+      restoredState?: PaginatorState;
     } = {}
   ): Promise<PaginatorPage<User | Organization>> {
     data.searchType = this._getDefaultFromEndpoint("GET_CONTRIBUTORS_ADMIN", "searchType") as GetContributorsAdminData["searchType"];
@@ -242,6 +243,8 @@ export class Project extends BaseEntity<ProjectItemNormalized> {
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getContributors",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
 
         const { toBeValidated, isAdmin, isInviting, isAdminPending, roles = [] } = options;

package/src/api/User.ts

@@ -4,7 +4,7 @@ import { UserMixin } from "../mixin/UserMixin.js";
 import { createSocialTransform } from "../types/transforms.js";
 
 import type { Badge } from "./Badge.js";
-import type { PaginatorPage } from "./BaseEntity.js";
+import type { PaginatorPage, PaginatorState } from "./BaseEntity.js";
 import type {
   ConnectData,
   DisconnectData,
@@ -366,12 +366,17 @@ export class User extends BaseEntity<UserItemNormalized> {
    * Récupérer les organisations d'un utilisateur : Récupère la liste des organisations auxquelles l'utilisateur appartient.
    * Constant : GET_ORGANIZATIONS_ADMIN | GET_ORGANIZATIONS_NO_ADMIN
    */
-  override async getOrganizations(data: Partial<GetOrganizationsAdminData | GetOrganizationsNoAdminData> = {}) {
+  override async getOrganizations(
+    data: Partial<GetOrganizationsAdminData | GetOrganizationsNoAdminData> = {},
+    options?: { restoredState?: PaginatorState }
+  ) {
     data.searchType = this._getDefaultFromEndpoint("GET_ORGANIZATIONS_NO_ADMIN", "searchType") as GetOrganizationsNoAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getOrganizations",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
         delete finalData?.pathParams;
 
@@ -436,12 +441,17 @@ export class User extends BaseEntity<UserItemNormalized> {
    * question : qui peut voir la liste d'amis, seulement l'utilisateur connecté ? ou tous les utilisateurs connectés ?
    * actuellement, c'est tous les utilisateurs connectés
    */
-  async getFriends(data: Partial<GetFriendsAdminData> = {}): Promise<PaginatorPage<User>> {
+  async getFriends(
+    data: Partial<GetFriendsAdminData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<User>> {
     data.searchType = this._getDefaultFromEndpoint("GET_FRIENDS_ADMIN", "searchType") as GetFriendsAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getFriends",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
 
         delete finalData?.pathParams;
@@ -462,12 +472,17 @@ export class User extends BaseEntity<UserItemNormalized> {
    * Récupérer les suivis
    * Constant : GET_SUBSCRIPTIONS / GET_SUBSCRIPTIONS_ADMIN
    */
-  async getSubscriptions(data: Partial<GetSubscriptionsAdminData | GetSubscriptionsData> = {}): Promise<PaginatorPage<BaseEntity<any>>> {
+  async getSubscriptions(
+    data: Partial<GetSubscriptionsAdminData | GetSubscriptionsData> = {},
+    options?: { restoredState?: PaginatorState }
+  ): Promise<PaginatorPage<BaseEntity<any>>> {
     data.searchType = this._getDefaultFromEndpoint("GET_SUBSCRIPTIONS", "searchType") as GetSubscriptionsAdminData["searchType"];
     // data.searchBy = "ALL";
 
     const paginator = this._createPaginatorEngine({
       initialData: data,
+      methodName: "getSubscriptions",
+      restoredState: options?.restoredState,
       finalizer: async (finalData) => {
 
         delete finalData?.pathParams;

package/src/index.ts

@@ -1,3 +1,4 @@
+import { BaseEntity } from "./api/BaseEntity.js";
 import { fromEntityJSON } from "./api/EntityRegistry.js";
 import Api from "./Api.js";
 import ApiClient from "./ApiClient.js";
@@ -31,7 +32,8 @@ const cocolightApiClient = {
     MultiServerTokenStorageStrategy
   },
   helper: {
-    fromEntityJSON
+    fromEntityJSON,
+    restorePaginationFromJSON: BaseEntity.restorePaginationFromJSON
   },
   OfflineClientManager
 };
@@ -90,7 +92,7 @@ export type * from "./api/serverDataType/Answer.js";
 export type * from "./api/serverDataType/common.js";
 
 // Types utilitaires
-export type { PaginatorPage } from "./api/BaseEntity.js";
+export type { PaginatorPage, PaginatorState } from "./api/BaseEntity.js";
 
 // Types de réponses, payloads, entités, et transforms
 export type * from "./types/index.js";

package/src/types/transforms.ts

@@ -103,8 +103,8 @@ export function transformEntityRefs(val: ParentData | OrganizerData | null): Ent
       {
         type: obj?.type ?? "",
         name: obj?.name,
-        id: obj?.id,
-        slug: obj?.slug
+        // id: obj?.id,
+        // slug: obj?.slug
         // _id exclu volontairement
       }
     ])