@communecter/cocolight-api-client 1.0.54 → 1.0.56

package/src/error.ts

@@ -0,0 +1,86 @@
+/**
+ * Type générique pour les détails d'erreur bruts
+ */
+export type GenericErrorDetails = Record<string, any>;
+
+/**
+ * Classe de base pour toutes les erreurs de l'API.
+ */
+export class ApiError extends Error {
+  public override readonly name: string = "ApiError";
+  public readonly status: number;
+  public readonly details?: GenericErrorDetails;
+
+  constructor(message: string, status: number, details?: GenericErrorDetails) {
+    super(message);
+    this.status = status;
+    this.details = details;
+  }
+}
+
+/**
+ * Erreur levée par le client API lorsqu'un appel échoue (réseau, config, etc.).
+ */
+export class ApiClientError extends ApiError {
+  public override readonly name: string = "ApiClientError";
+
+  constructor(message: string, status: number, details?: GenericErrorDetails) {
+    super(message, status, details);
+  }
+}
+
+/**
+ * Erreur de validation AJV (schemas de requête/réponse).
+ */
+export class ApiValidationError extends Error {
+  public override readonly name: string = "ApiValidationError";
+  public readonly status: number;
+  public readonly messages: string[];
+  public readonly details: any;
+
+  constructor(message: string, status: number, messages: string[], details: any = null) {
+    super(message);
+    this.status = status;
+    this.messages = messages;
+    this.details = details;
+  }
+}
+
+/**
+ * Levée lorsqu'on bloque l'accès à l'API (circuit breaker).
+ */
+export class CircuitBreakerError extends ApiError {
+  public override readonly name: string = "CircuitBreakerError";
+
+  constructor(message: string) {
+    super(message, 503);
+  }
+}
+
+/**
+ * Erreur "métier" retour de l'API (ex: result=false) même si HTTP=200.
+ */
+export class ApiResponseError extends Error {
+  public override readonly name: string = "ApiResponseError";
+  public readonly status: number;
+  public readonly responseData: object;
+  public readonly details: any;
+
+  constructor(message: string, status: number, responseData: object, details: any = null) {
+    super(message);
+    this.status = status;
+    this.responseData = responseData;
+    this.details = details;
+  }
+}
+
+/**
+ * Erreur d'authentification (ex: 401/403).
+ */
+export class ApiAuthenticationError extends ApiError {
+  public override readonly name: string = "ApiAuthenticationError";
+
+  constructor(message: string, status: number, details?: GenericErrorDetails) {
+    super(message, status, details);
+  }
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+import { fromEntityJSON } from "./api/EntityRegistry.js";
+import Api from "./Api.js";
+import ApiClient from "./ApiClient.js";
+import * as error from "./error.js";
+import { createDefaultMultiServerTokenStorageStrategy } from "./utils/createDefaultMultiServerTokenStorageStrategy.js";
+import { createDefaultTokenStorageStrategy } from "./utils/createDefaultTokenStorageStrategy.js";
+import { MultiServerTokenStorageStrategy } from "./utils/MultiServerTokenStorageStrategy.js";
+import OfflineClientManager from "./utils/OfflineClientManager.js";
+import * as reactive from "./utils/reactive.js";
+import { TokenStorageStrategy } from "./utils/TokenStorage.js";
+
+
+const cocolightApiClient = {
+  ApiClient,
+  Api,
+  error,
+  reactive,
+  effect: reactive.effect,
+  batch: reactive.batch,
+  isSignal: reactive.isSignal,
+  reactiveObject: reactive.reactive,
+  isReactive: reactive.isReactive,
+  computed: reactive.computed,
+  watch: reactive.watch,
+  getSignals: reactive.getSignals,
+  subscribeTo: reactive.subscribeTo,
+  tokenStorageStrategy: {
+    createDefaultTokenStorageStrategy,
+    TokenStorageStrategy,
+    createDefaultMultiServerTokenStorageStrategy,
+    MultiServerTokenStorageStrategy
+  },
+  helper: {
+    fromEntityJSON
+  },
+  OfflineClientManager
+};
+
+export default cocolightApiClient;
+
+// Export des types pour faciliter l'utilisation
+
+// Classes principales
+export type { default as Api } from "./Api.js";
+export type { default as ApiClient } from "./ApiClient.js";
+export type { default as EndpointApi } from "./api/EndpointApi.js";
+export type { UserApi } from "./api/UserApi.js";
+
+// Types ApiClient (configuration et résultats d'appels)
+export type {
+  ApiClientOptions,
+  CallEndpointData,
+  CallEndpointResult,
+  CallEndpointResponse,
+  ApiClientOfflineEnqueueResult
+} from "./ApiClient.js";
+
+// Stratégies de stockage
+export type { TokenStorageStrategy } from "./utils/TokenStorage.js";
+export type { MultiServerTokenStorageStrategy } from "./utils/MultiServerTokenStorageStrategy.js";
+export type { default as OfflineClientManager } from "./utils/OfflineClientManager.js";
+export type { OfflineAction } from "./utils/OfflineClientManager.js";
+
+// Classes d'entités
+export type { User } from "./api/User.js";
+export type { Organization } from "./api/Organization.js";
+export type { Project } from "./api/Project.js";
+export type { Event } from "./api/Event.js";
+export type { Poi } from "./api/Poi.js";
+export type { Badge } from "./api/Badge.js";
+export type { News } from "./api/News.js";
+
+// Types ServerData (données normalisées reçues du serveur)
+export type * from "./api/serverDataType/User.js";
+export type * from "./api/serverDataType/Organization.js";
+export type * from "./api/serverDataType/Project.js";
+export type * from "./api/serverDataType/common.js";
+
+// Types utilitaires
+export type { PaginatorPage } from "./api/BaseEntity.js";
+
+// Types de réponses, payloads, entités, et transforms
+export type * from "./types/index.js";
+
+// Export de tous les types générés depuis EndpointApi.types.ts
+export type * from "./api/EndpointApi.types.js";

package/src/mixin/UserMixin.ts

@@ -0,0 +1,4 @@
+export const UserMixin = {
+
+};
+  

package/src/types/api-responses.ts

@@ -0,0 +1,217 @@
+// types/api-responses.ts - Types pour les réponses API et amélioration du type safety
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+/* eslint-disable @typescript-eslint/no-namespace */
+
+import type { CollectionKey } from "../api/EntityRegistry.js";
+
+/**
+ * Interface de base pour toutes les réponses API
+ */
+export interface BaseApiResponse {
+  success?: boolean;
+  message?: string;
+  timestamp?: number;
+}
+
+/**
+ * Réponse avec données
+ */
+export interface ApiDataResponse<T = any> extends BaseApiResponse {
+  data: T;
+  map?: {
+    id?: string;
+    slug?: string;
+  };
+}
+
+/**
+ * Réponse d'erreur API
+ */
+export interface ApiErrorResponse extends BaseApiResponse {
+  error: {
+    code: number;
+    message: string;
+    details?: any;
+    stack?: string;
+  };
+  success: false;
+}
+
+/**
+ * Réponse paginée
+ */
+export interface PaginatedApiResponse<T = any> extends BaseApiResponse {
+  data: {
+    count: {
+      total: number;
+    };
+    results: T[];
+    pageIndex: number;
+    pageNumber: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+  };
+}
+
+/**
+ * Réponse pour les opérations de connexion/déconnexion
+ */
+export interface ConnectionResponse extends BaseApiResponse {
+  connection: {
+    established: boolean;
+    type: string;
+    childId: string;
+    parentId: string;
+    date: number;
+  };
+}
+
+/**
+ * Réponse pour l'authentification
+ */
+export interface AuthResponse extends BaseApiResponse {
+  user?: {
+    id: string;
+    username: string;
+    email: string;
+    roles: any;
+  };
+  accessToken?: string;
+  refreshToken?: string;
+  expiresIn?: number;
+}
+
+/**
+ * Réponse pour l'upload de fichiers
+ */
+export interface UploadResponse extends BaseApiResponse {
+  file: {
+    id: string;
+    filename: string;
+    originalName: string;
+    mimetype: string;
+    size: number;
+    url: string;
+    thumbnailUrl?: string;
+  };
+}
+
+/**
+ * Réponse pour les opérations CRUD simples
+ */
+export interface CrudResponse extends BaseApiResponse {
+  operation: "create" | "read" | "update" | "delete";
+  entityType: string;
+  entityId: string;
+  affected: number;
+}
+
+/**
+ * Types pour les endpoints spécifiques
+ */
+export interface GetElementsKeyResponse extends BaseApiResponse {
+  contextId?: string;
+  contextType?: CollectionKey;
+  [key: string]: unknown;
+}
+
+/**
+ * Union de tous les types de réponse
+ */
+export type ApiResponse =
+  | BaseApiResponse
+  | ApiDataResponse
+  | ApiErrorResponse
+  | PaginatedApiResponse
+  | ConnectionResponse
+  | AuthResponse
+  | UploadResponse
+  | CrudResponse
+  | GetElementsKeyResponse;
+
+/**
+ * Types pour les statuts HTTP
+ */
+export type HttpStatusCode =
+  | 200 | 201 | 202 | 204  // Success
+  | 400 | 401 | 403 | 404 | 409 | 422  // Client errors
+  | 500 | 501 | 502 | 503 | 504;  // Server errors
+
+/**
+ * Interface pour les détails d'erreur API
+ */
+export interface ApiErrorDetails {
+  code: HttpStatusCode;
+  message: string;
+  details?: any;
+  validationErrors?: Array<{
+    field: string;
+    message: string;
+    value?: any;
+  }>;
+}
+
+/**
+ * Types pour les réponses d'endpoint spécifiques
+ */
+export namespace EndpointResponses {
+  export interface AddUser extends ApiDataResponse<{
+    id: string;
+    username: string;
+    email: string;
+    created: number;
+  }> {}
+
+  export interface AddOrganization extends ApiDataResponse<{
+    id: string;
+    name: string;
+    created: number;
+  }> {}
+
+  export interface AddProject extends ApiDataResponse<{
+    id: string;
+    name: string;
+    created: number;
+  }> {}
+
+  export interface AddEvent extends ApiDataResponse<{
+    id: string;
+    name: string;
+    startDate?: number;
+    created: number;
+  }> {}
+
+  export interface AddPoi extends ApiDataResponse<{
+    id: string;
+    name: string;
+    created: number;
+  }> {}
+
+  export interface AddNews extends ApiDataResponse<{
+    id: string;
+    title: string;
+    publishDate?: number;
+    created: number;
+  }> {}
+
+  export interface AddBadges extends ApiDataResponse<{
+    id: string;
+    name: string;
+    created: number;
+  }> {}
+
+  export interface Connect extends ConnectionResponse {}
+  export interface Disconnect extends ConnectionResponse {}
+  export interface Follow extends ConnectionResponse {}
+  export interface LinkValidate extends ConnectionResponse {}
+}
+
+/**
+ * Type helper pour extraire le type de données d'une réponse API
+ */
+export type ExtractApiData<T> = T extends ApiDataResponse<infer U> ? U : never;
+
+/**
+ * Type helper pour les réponses qui peuvent être soit des données soit des erreurs
+ */
+export type ApiResult<T> = ApiDataResponse<T> | ApiErrorResponse;

package/src/types/entities.ts

@@ -0,0 +1,22 @@
+// types/entities.ts - Types partagés pour éviter les dépendances circulaires
+
+/**
+ * Types de collection possibles
+ */
+export type CollectionType = "citoyens" | "organizations" | "projects" | "events" | "poi" | "news" | "badges" | "comments";
+
+/**
+ * Types pour les références entre entités
+ */
+export interface EntityRef {
+  type: string;
+  name?: string;
+}
+
+export type EntityRefsMap = Record<string, EntityRef>;
+
+/**
+ * Types pour les transformations de données
+ */
+export type TransformFunction<TInput = any, TOutput = any> = (value: TInput, fullObject?: any) => TOutput;
+export type TransformsMap = Record<string, TransformFunction | undefined>;

package/src/types/error-guards.ts

@@ -0,0 +1,230 @@
+// types/error-guards.ts - Type guards et utilitaires pour la gestion d'erreurs
+
+import { ApiError, ApiClientError, ApiResponseError, ApiValidationError, ApiAuthenticationError, CircuitBreakerError } from "../error.js";
+
+import type { ApiErrorDetails, HttpStatusCode } from "./api-responses.js";
+
+/**
+ * Type guard pour vérifier si une valeur est une Error
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}
+
+/**
+ * Type guard pour vérifier si une valeur est une ApiError
+ */
+export function isApiError(value: unknown): value is ApiError {
+  return value instanceof ApiError;
+}
+
+/**
+ * Type guard pour vérifier si une valeur est une ApiClientError
+ */
+export function isApiClientError(value: unknown): value is ApiClientError {
+  return value instanceof ApiClientError;
+}
+
+/**
+ * Type guard pour vérifier si une valeur est une ApiResponseError
+ */
+export function isApiResponseError(value: unknown): value is ApiResponseError {
+  return value instanceof ApiResponseError;
+}
+
+/**
+ * Type guard pour vérifier si une valeur est une ApiValidationError
+ */
+export function isApiValidationError(value: unknown): value is ApiValidationError {
+  return value instanceof ApiValidationError;
+}
+
+/**
+ * Type guard pour vérifier si une valeur est une ApiAuthenticationError
+ */
+export function isApiAuthenticationError(value: unknown): value is ApiAuthenticationError {
+  return value instanceof ApiAuthenticationError;
+}
+
+/**
+ * Type guard pour vérifier si une valeur est une CircuitBreakerError
+ */
+export function isCircuitBreakerError(value: unknown): value is CircuitBreakerError {
+  return value instanceof CircuitBreakerError;
+}
+
+/**
+ * Type guard pour vérifier si une erreur a une propriété response (erreurs axios)
+ */
+export function hasResponse(error: unknown): error is Error & { response: { status: number; data: any } } {
+  return isError(error) && "response" in error &&
+         typeof (error as any).response === "object" &&
+         typeof (error as any).response.status === "number";
+}
+
+/**
+ * Type guard pour vérifier si une erreur a un code de statut HTTP
+ */
+export function hasStatusCode(error: unknown): error is Error & { status: HttpStatusCode } {
+  return isError(error) && "status" in error &&
+         typeof (error as any).status === "number";
+}
+
+/**
+ * Utilitaire pour extraire le message d'erreur de façon type-safe
+ */
+export function getErrorMessage(error: unknown): string {
+  if (isError(error)) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object" && "message" in error) {
+    return String((error as any).message);
+  }
+  return "Unknown error";
+}
+
+/**
+ * Utilitaire pour extraire le code de statut d'une erreur
+ */
+export function getErrorStatusCode(error: unknown): HttpStatusCode | undefined {
+  if (hasStatusCode(error)) {
+    return error.status as HttpStatusCode;
+  }
+  if (hasResponse(error)) {
+    return error.response.status as HttpStatusCode;
+  }
+  if (isApiError(error)) {
+    return error.status as HttpStatusCode;
+  }
+  return undefined;
+}
+
+/**
+ * Utilitaire pour extraire les détails d'erreur de façon type-safe
+ */
+export function getErrorDetails(error: unknown): ApiErrorDetails | undefined {
+  if (isApiError(error)) {
+    return {
+      code: error.status as HttpStatusCode,
+      message: error.message,
+      details: (error as any).responseData
+    };
+  }
+
+  if (hasResponse(error)) {
+    return {
+      code: error.response.status as HttpStatusCode,
+      message: getErrorMessage(error),
+      details: error.response.data
+    };
+  }
+
+  const status = getErrorStatusCode(error);
+  if (status) {
+    return {
+      code: status,
+      message: getErrorMessage(error)
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Utilitaire pour créer une erreur typée
+ */
+export function createTypedError(message: string, status: HttpStatusCode = 500, details?: any): ApiError {
+  return new ApiError(message, status, details);
+}
+
+/**
+ * Wrapper pour les fonctions qui peuvent lever des erreurs
+ */
+export async function safeCall<T>(
+  fn: () => Promise<T>,
+  fallback?: T
+): Promise<{ data: T; error: null } | { data: T | undefined; error: ApiErrorDetails }> {
+  try {
+    const data = await fn();
+    return { data, error: null };
+  } catch (error) {
+    const errorDetails = getErrorDetails(error);
+    return {
+      data: fallback,
+      error: errorDetails || {
+        code: 500,
+        message: getErrorMessage(error)
+      }
+    };
+  }
+}
+
+/**
+ * Type pour les résultats d'opérations sécurisées
+ */
+export type SafeResult<T> =
+  | { success: true; data: T; error: null }
+  | { success: false; data: undefined; error: ApiErrorDetails };
+
+/**
+ * Version améliorée de safeCall avec indicateur de succès
+ */
+export async function trySafe<T>(fn: () => Promise<T>): Promise<SafeResult<T>> {
+  try {
+    const data = await fn();
+    return { success: true, data, error: null };
+  } catch (error) {
+    const errorDetails = getErrorDetails(error);
+    return {
+      success: false,
+      data: undefined,
+      error: errorDetails || {
+        code: 500,
+        message: getErrorMessage(error)
+      }
+    };
+  }
+}
+
+/**
+ * Utilitaire pour valider et normaliser les erreurs
+ */
+export function normalizeError(error: unknown): ApiError {
+  if (isApiError(error)) {
+    return error;
+  }
+
+  const message = getErrorMessage(error);
+  const status = getErrorStatusCode(error) || 500;
+  const details = hasResponse(error) ? error.response.data : undefined;
+
+  return new ApiError(message, status, details);
+}
+
+/**
+ * Type helper pour les fonctions qui peuvent lever des erreurs typées
+ */
+export type ErrorProne<T> = () => Promise<T> | T;
+
+/**
+ * Décorateur de méthode pour capturer et normaliser les erreurs
+ */
+export function catchErrors<T extends any[], R>(
+  target: any,
+  propertyName: string,
+  descriptor: TypedPropertyDescriptor<(...args: T) => Promise<R>>
+) {
+  const method = descriptor.value;
+  if (!method) return;
+
+  descriptor.value = async function (...args: T): Promise<R> {
+    try {
+      return await method.apply(this, args);
+    } catch (error) {
+      throw normalizeError(error);
+    }
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,39 @@
+// types/index.ts - Point d'entrée central pour tous les types partagés
+
+// Entity types
+export type {
+  CollectionKey,
+  EntityTag
+} from "../api/EntityRegistry.js";
+
+export type {
+  TransformsMap,
+  TransformFunction,
+} from "./entities.js";
+
+// Payload types
+export type {
+  SocialNetworkPayload,
+} from "./payloads.js";
+
+// Transform types
+export type {
+  UserTransforms,
+  OrganizationTransforms,
+  ProjectTransforms,
+  EventTransforms
+} from "./transforms.js";
+
+// API Response types
+export type {
+  BaseApiResponse,
+  ApiDataResponse,
+  ApiErrorResponse,
+  PaginatedApiResponse,
+  GetElementsKeyResponse,
+  ApiResponse
+} from "./api-responses.js";
+
+// API Error types
+export type { ApiErrorDetails } from "./api-responses.js";
+export type { GenericErrorDetails } from "../error.js";

package/src/types/payloads.ts

@@ -0,0 +1,21 @@
+// types/payloads.ts - Types pour les payloads des méthodes _add et _update
+ 
+
+/**
+ * Types pour les réseaux sociaux
+ */
+export interface SocialNetworkPayload {
+  github?: string;
+  gitlab?: string;
+  facebook?: string;
+  twitter?: string;
+  instagram?: string;
+  linkedIn?: string;
+  youtube?: string;
+  website?: string;
+  diaspora?: string;
+  mastodon?: string;
+  telegram?: string;
+  signal?: string;
+}
+