@pi-spi/app 0.0.0-stage → 1.2.1

package/package.json

@@ -1,6 +1,165 @@
 {
   "name": "@pi-spi/app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.1",
+  "description": "SDK React Native permettant d'intégrer PI-SPI (transactions, demande d'annulation, retour de fond, demande de paiement, QR Code, gestion des alias, gestion des abonnements, notifications, profil, compte) dans une application mobile existante.",
+  "homepage": "https://github.com/pisfn-sandbox/mobile-app-react-native-sdk.git",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pisfn-sandbox/mobile-app-react-native-sdk.git"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "react-native": "./src/index.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "assets",
+    "example/App.tsx",
+    "example/app.json",
+    "!**/__tests__",
+    "!**/*.arb"
+  ],
+  "scripts": {
+    "gen-l10n": "node scripts/gen-l10n.js",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "prepare": "npm run gen-l10n && bob build"
+  },
+  "dependencies": {
+    "axios": "^1.20.0",
+    "crypto-js": "^4.2.0",
+    "qrcode": "^1.5.4",
+    "rn-emoji-keyboard": "^1.7.0"
+  },
+  "peerDependencies": {
+    "@expo/vector-icons": ">=15.0.0",
+    "@react-native-async-storage/async-storage": ">=2.0.0",
+    "@react-navigation/native": ">=7.0.0",
+    "@react-navigation/native-stack": ">=7.0.0",
+    "expo": ">=57.0.0",
+    "expo-asset": "*",
+    "expo-audio": "*",
+    "expo-camera": "*",
+    "expo-clipboard": "*",
+    "expo-contacts": "*",
+    "expo-crypto": "*",
+    "expo-file-system": "*",
+    "expo-font": "*",
+    "expo-image": "*",
+    "expo-image-picker": "*",
+    "expo-location": "*",
+    "expo-network": "*",
+    "expo-print": "*",
+    "expo-secure-store": "*",
+    "expo-sharing": "*",
+    "expo-video": "*",
+    "react": ">=19.0.0",
+    "react-native": ">=0.80.0",
+    "react-native-safe-area-context": ">=5.0.0",
+    "react-native-screens": ">=4.0.0",
+    "react-native-svg": ">=15.0.0",
+    "react-native-view-shot": "*",
+    "react-native-webview": "*"
+  },
+  "devDependencies": {
+    "@expo/vector-icons": "^15.0.2",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "@react-navigation/native": "^7.5.0",
+    "@react-navigation/native-stack": "^7.20.0",
+    "@types/crypto-js": "^4.2.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.20.5",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "~19.2.2",
+    "expo": "~57.0.27",
+    "expo-audio": "~57.0.5",
+    "expo-camera": "~57.0.6",
+    "expo-clipboard": "~57.0.2",
+    "expo-contacts": "~57.0.6",
+    "expo-crypto": "~57.0.3",
+    "expo-file-system": "~57.0.7",
+    "expo-image": "~57.0.5",
+    "expo-image-picker": "~57.0.20",
+    "expo-location": "~57.0.20",
+    "expo-network": "~57.0.2",
+    "expo-print": "~57.0.2",
+    "expo-secure-store": "~57.0.4",
+    "expo-sharing": "~57.0.22",
+    "expo-video": "~57.0.5",
+    "jest": "^29.7.0",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-builder-bob": "^0.43.1",
+    "react-native-safe-area-context": "~5.7.0",
+    "react-native-screens": "~4.26.0",
+    "react-native-svg": "15.15.4",
+    "react-native-view-shot": "^5.1.0",
+    "react-native-webview": "^13.16.1",
+    "ts-jest": "^29.2.5",
+    "typescript": "~6.0.3"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "roots": [
+      "<rootDir>/src"
+    ],
+    "testMatch": [
+      "**/__tests__/**/*.test.ts"
+    ],
+    "globals": {
+      "__DEV__": true
+    },
+    "moduleNameMapper": {
+      "^react-native$": "<rootDir>/test/stubs/react-native.ts",
+      "^@react-native-async-storage/async-storage$": "<rootDir>/test/stubs/async-storage.ts",
+      "^expo-secure-store$": "<rootDir>/test/stubs/expo-secure-store.ts",
+      "^expo-crypto$": "<rootDir>/test/stubs/expo-crypto.ts",
+      "^expo-network$": "<rootDir>/test/stubs/expo-network.ts",
+      "^@react-navigation/native$": "<rootDir>/test/stubs/react-navigation.ts",
+      "^(expo-contacts|expo-location)$": "<rootDir>/test/stubs/permissions.ts",
+      "\\.(mp4|mp3|png|jpe?g|gif)$": "<rootDir>/test/stubs/empty.ts",
+      "^rn-emoji-keyboard$": "<rootDir>/test/stubs/empty.ts",
+      "^(@expo/vector-icons|react-native-safe-area-context|expo-audio|expo-image|expo-video|expo-image-picker|expo-file-system|expo-print|expo-sharing|react-native-webview|expo-camera|react-native-view-shot)$": "<rootDir>/test/stubs/empty.ts"
+    },
+    "transform": {
+      "^.+\\.tsx?$": [
+        "ts-jest",
+        {
+          "tsconfig": {
+            "jsx": "react-jsx",
+            "esModuleInterop": true,
+            "isolatedModules": true
+          }
+        }
+      ]
+    }
+  }
+}

package/src/core/api.ts

@@ -0,0 +1,517 @@
+import axios, {
+  AxiosError,
+  type AxiosInstance,
+  type AxiosRequestConfig,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios';
+import * as Network from 'expo-network';
+import { Platform } from 'react-native';
+
+import { MockInterceptor } from './api_mock';
+import { AppEnv } from './env';
+import { Logger } from './logger';
+import type { PiSpiSdkConfig } from './pi_spi_sdk_config';
+
+/** Options d'une requête, équivalent des paramètres nommés de `Api.get/post/...` en Dart. */
+export type ApiRequestOptions = {
+  data?: unknown;
+  queryParameters?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  responseType?: string;
+  sendTimeout?: number;
+  extra?: Record<string, unknown>;
+};
+
+declare module 'axios' {
+  interface AxiosRequestConfig {
+    /** Équivalent de `Options.extra` (Dio) : données libres pour les intercepteurs. */
+    extra?: Record<string, unknown>;
+  }
+}
+
+/**
+ * Core Api Service pour effectuer les appels aux APIs.
+ * axios est utilisé pour les appels Http dans le SDK (Dio côté Flutter).
+ * Le SDK ne gère ni login ni refresh de token à proprement parler : c'est
+ * toujours l'hôte qui fournit et rafraîchit le token (voir
+ * `PiSpiApiConfig.accessToken` et `PiSpiApiConfig.onAccessTokenExpired`).
+ * Le SDK se contente de garder le token courant en mémoire pour la
+ * session ({@link Api.accessToken}) et d'orchestrer les tentatives de
+ * rafraîchissement quand une requête échoue en 401/403.
+ */
+export class Api {
+  static readonly logger = new Logger();
+
+  static url: string;
+
+  static client: AxiosInstance;
+
+  static config: PiSpiSdkConfig;
+
+  /**
+   * Token d'accès courant de la session, utilisé pour chaque requête.
+   * Initialisé depuis `PiSpiApiConfig.accessToken`, puis mis à jour par
+   * {@link TokenInterceptor} quand `PiSpiApiConfig.onAccessTokenExpired` en
+   * fournit un nouveau.
+   */
+  static accessToken: string;
+
+  /** Créer le client HTTP */
+  static initClient(config: PiSpiSdkConfig): void {
+    Api.config = config;
+    Api.accessToken = config.api.accessToken;
+    Api.updateClient();
+  }
+
+  static updateClient(): void {
+    const apiUrl = AppEnv.apiUrl;
+    Api.logger.i(`API URL ${apiUrl}`);
+    Api.url = apiUrl;
+
+    // Créer l'instance axios
+    Api.client = axios.create(Api.baseOptions());
+
+    // L'ordre des intercepteurs compte
+    if (isDebug()) new LoggingInterceptor().attach(Api.client);
+    if (Api.config.api.demoMode) {
+      // Mode démo : aucune requête réelle, réponses mockées depuis
+      // assets/json/. Ne jamais activer en production.
+      new MockInterceptor(Api.config).attach(Api.client);
+    } else {
+      new TokenInterceptor().attach(Api.client);
+    }
+    new ErrorInterceptor().attach(Api.client);
+  }
+
+  /** Options communes à toutes les instances axios du SDK. */
+  static baseOptions(): AxiosRequestConfig {
+    return {
+      baseURL: Api.url,
+      timeout: 60_000, // 60 seconds
+      // Les listes sont envoyées comme `sens=debit&sens=credit` (comme Dio).
+      paramsSerializer: { indexes: null },
+    };
+  }
+
+  /** Effectue un appel GET */
+  static async get<T = any>(path: string, options: ApiRequestOptions = {}): Promise<ApiResponse<T>> {
+    try {
+      const response = await Api.client.request<T>(Api.requestConfig('GET', path, options));
+      return new ApiResponse<T>(response.data, response.status);
+    } catch (e) {
+      throw toApiException(e);
+    }
+  }
+
+  static async delete<T = any>(path: string, options: ApiRequestOptions = {}): Promise<ApiResponse<T>> {
+    try {
+      const response = await Api.client.request<T>(Api.requestConfig('DELETE', path, options));
+      return new ApiResponse<T>(response.data, response.status);
+    } catch (e) {
+      throw toApiException(e);
+    }
+  }
+
+  static async post<T = any>(path: string, options: ApiRequestOptions = {}): Promise<ApiResponse<T>> {
+    let response: AxiosResponse<T>;
+    try {
+      response = await Api.client.request<T>(Api.requestConfig('POST', path, options));
+    } catch (e) {
+      throw toApiException(e);
+    }
+    ErrorInterceptor.checkErrors(response);
+    return new ApiResponse<T>(response.data, response.status);
+  }
+
+  static async put<T = any>(path: string, options: ApiRequestOptions = {}): Promise<ApiResponse<T>> {
+    let response: AxiosResponse<T>;
+    try {
+      response = await Api.client.request<T>(Api.requestConfig('PUT', path, { ...options, sendTimeout: undefined }));
+    } catch (e) {
+      throw toApiException(e);
+    }
+    ErrorInterceptor.checkErrors(response);
+    return new ApiResponse<T>(response.data, response.status);
+  }
+
+  private static requestConfig(method: string, path: string, options: ApiRequestOptions): AxiosRequestConfig {
+    const config: AxiosRequestConfig = {
+      method,
+      url: path,
+      data: options.data,
+      params: options.queryParameters,
+      headers: options.headers,
+      extra: options.extra,
+    };
+    if (options.sendTimeout != null) config.timeout = options.sendTimeout;
+    return config;
+  }
+
+  static async hasNetworkConnection(): Promise<boolean> {
+    // En mode démo, aucune requête réelle n'est faite (MockInterceptor) :
+    // ce check ne doit pas dépendre d'une vraie connexion internet.
+    if (Api.config.api.demoMode) return true;
+    if (Platform.OS === 'web') return true;
+    try {
+      const state = await withTimeout(Network.getNetworkStateAsync(), 3000);
+      return (state.isInternetReachable ?? state.isConnected) === true;
+    } catch {
+      return false;
+    }
+  }
+
+  static isTokenValid(token: string | null | undefined): boolean {
+    if (token == null) return false;
+    try {
+      const parts = token.split('.');
+      if (parts.length !== 3) return false; // Format JWT invalide
+
+      const payload = JSON.parse(base64UrlDecode(parts[1]));
+
+      if (!('exp' in payload)) return false;
+
+      const expiry = parseInt(String(payload.exp), 10);
+      if (Number.isNaN(expiry)) return false;
+
+      const currentTime = Math.floor(Date.now() / 1000);
+
+      return expiry >= currentTime;
+    } catch (e) {
+      Api.logger.e('Erreur lors de la vérification du token', { error: e });
+      return false;
+    }
+  }
+}
+
+/** Modèle de reponse de l'API */
+export class ApiResponse<T = any> {
+  constructor(
+    readonly data: T | undefined,
+    readonly statusCode: number | undefined,
+  ) {}
+}
+
+/** Codification des erreurs de retour de l'API */
+export enum ApiError {
+  /** The exception for an expired bearer token. */
+  tokenExpired = 'tokenExpired',
+
+  /** The exception for a failed connection attempt. */
+  timeOut = 'timeOut',
+
+  /** The exception for no internet connectivity. */
+  noInternetConnection = 'noInternetConnection',
+
+  /** The exception for an incorrect parameter in a request/response. */
+  badRequest = 'badRequest',
+
+  /** The exception for an unauthorizeed api call */
+  unauthorized = 'unauthorized',
+
+  /** The exception for a forbidden action (403) */
+  forbidden = 'forbidden',
+
+  /** Not found */
+  notFound = 'notFound',
+
+  /** Erreur api interne */
+  internalServerError = 'internalServerError',
+
+  /** The exception for an unknown exception from the api. */
+  unknowError = 'unknowError',
+
+  /** The exception for an unknown type of failure. */
+  unrecognizedError = 'unrecognizedError',
+
+  /**
+   * The exception for any parsing failure encountered during
+   * serialization/deserialization of a request.
+   */
+  serializationError = 'serializationError',
+}
+
+/** Modele de réponse de l'API en cas d'erreur */
+export class ApiProblem {
+  readonly type: string;
+  readonly title: string;
+  readonly status: number;
+  readonly detail: string;
+  readonly invalidParams?: Record<string, any>;
+  readonly object?: Record<string, any>;
+
+  constructor(params: {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    invalidParams?: Record<string, any>;
+    object?: Record<string, any>;
+  }) {
+    this.type = params.type;
+    this.title = params.title;
+    this.status = params.status;
+    this.detail = params.detail;
+    this.invalidParams = params.invalidParams;
+    this.object = params.object;
+  }
+
+  static fromJson(json: any): ApiProblem {
+    const map = json && typeof json === 'object' ? json : {};
+    return new ApiProblem({
+      type: map.type ?? '',
+      title: map.title ?? '',
+      status: map.status ?? 0,
+      detail: map.detail ?? '',
+      invalidParams: map['invalid-params'],
+      object: map.object,
+    });
+  }
+
+  toString(): string {
+    return (
+      `ApiProblem{type: ${this.type}, title: ${this.title}, status: ${this.status},` +
+      `detail: ${this.detail}, invalidParams: ${JSON.stringify(this.invalidParams)}, object: ${JSON.stringify(this.object)}}`
+    );
+  }
+}
+
+/** Classe d'exception custom pour les erreurs d'appels vers les APIs */
+export class ApiException extends Error {
+  readonly statusCode?: number;
+  readonly error: ApiError;
+  readonly problem?: ApiProblem;
+
+  constructor(params: {
+    statusCode?: number;
+    error: ApiError;
+    message?: string;
+    name?: string;
+    problem?: ApiProblem;
+  }) {
+    super(params.message ?? params.error);
+    this.name = params.name ?? 'ApiException';
+    this.statusCode = params.statusCode;
+    this.error = params.error;
+    this.problem = params.problem;
+  }
+}
+
+/** Ajoute le token courant avant chaque requête (voir {@link Api.accessToken}). */
+export class TokenInterceptor {
+  static readonly logger = new Logger();
+
+  /**
+   * Nombre maximum de tentatives de rafraîchissement du token avant
+   * d'appeler `PiSpiApiConfig.onSessionExpired`.
+   */
+  static readonly maxRefreshAttempts = 3;
+
+  attach(client: AxiosInstance): void {
+    client.interceptors.request.use((options) => this.onRequest(options));
+    client.interceptors.response.use(undefined, (error) => this.onError(error));
+  }
+
+  onRequest(options: InternalAxiosRequestConfig): InternalAxiosRequestConfig {
+    TokenInterceptor.logger.i(`Requete vers ${options.url}`);
+    options.headers.set('Authorization', `Bearer ${Api.accessToken}`);
+    return options;
+  }
+
+  /**
+   * Si la requête échoue en 401, ou en 403 alors que {@link Api.accessToken}
+   * est lui-même expiré (voir {@link Api.isTokenValid} — un 403 avec un
+   * token toujours valide est une interdiction métier, pas un problème de
+   * token, donc pas de refresh dans ce cas) : on demande à l'hôte un
+   * nouveau token via `PiSpiApiConfig.onAccessTokenExpired` et on rejoue
+   * la requête, jusqu'à {@link maxRefreshAttempts} fois. Si l'hôte ne peut
+   * pas fournir de token (retourne `null`), ou si toutes les tentatives
+   * sont épuisées, on l'informe que la session est terminée.
+   */
+  async onError(error: unknown): Promise<AxiosResponse> {
+    TokenInterceptor.logger.e('Error HTTP - dans Token interceptor', { error });
+    if (!axios.isAxiosError(error) || !error.config) throw error;
+
+    const status = error.response?.status;
+    if (status === 401 || (status === 403 && !Api.isTokenValid(Api.accessToken))) {
+      if (!(await Api.hasNetworkConnection())) throw error;
+
+      for (let attempt = 1; attempt <= TokenInterceptor.maxRefreshAttempts; attempt++) {
+        const newAccessToken = await Api.config.api.onAccessTokenExpired();
+        if (newAccessToken == null) {
+          TokenInterceptor.logger.w(
+            "L'hôte n'a pas pu fournir de nouveau token " +
+              `(tentative ${attempt}/${TokenInterceptor.maxRefreshAttempts})`,
+          );
+          break;
+        }
+        Api.accessToken = newAccessToken;
+        error.config.headers.set('Authorization', `Bearer ${newAccessToken}`);
+
+        try {
+          // Relancer la requête avec un client SANS INTERCEPTORS,
+          // pour eviter une boucle infinie
+          return await axios.create(Api.baseOptions()).request({
+            method: error.config.method,
+            url: error.config.url,
+            data: error.config.data,
+            params: error.config.params,
+            headers: error.config.headers,
+          });
+        } catch (e) {
+          TokenInterceptor.logger.e(
+            'Requête relancée avec le nouveau token a échoué ' +
+              `(tentative ${attempt}/${TokenInterceptor.maxRefreshAttempts})`,
+            { error: e },
+          );
+        }
+      }
+
+      await Api.config.api.onSessionExpired();
+    }
+    throw error;
+  }
+}
+
+/** Pour logger ce qui se passe */
+export class LoggingInterceptor {
+  static readonly logger = new Logger();
+
+  attach(client: AxiosInstance): void {
+    client.interceptors.request.use((options) => this.onRequest(options));
+    client.interceptors.response.use(
+      (response) => this.onResponse(response),
+      (error) => this.onError(error),
+    );
+  }
+
+  onRequest(options: InternalAxiosRequestConfig): InternalAxiosRequestConfig {
+    const logger = LoggingInterceptor.logger;
+    logger.i(`--> ${(options.method ?? 'get').toUpperCase()} ${options.baseURL} ${options.url}`);
+    Object.entries(options.headers ?? {}).forEach(([k, v]) => logger.i(`${k}: ${v}`));
+    Object.entries(options.params ?? {}).forEach(([k, v]) => logger.i(`${k}: ${v}`));
+    if (options.data != null) {
+      logger.i(`Request Body: ${JSON.stringify(options.data)}`);
+    }
+    return options;
+  }
+
+  onError(error: unknown): never {
+    const logger = LoggingInterceptor.logger;
+    if (axios.isAxiosError(error)) {
+      logger.i(`<-- ${error.message} ${error.config?.url}`);
+      logger.i(error.response != null ? JSON.stringify(error.response.data) : 'Unknown Error');
+    }
+    throw error;
+  }
+
+  onResponse(response: AxiosResponse): AxiosResponse {
+    const logger = LoggingInterceptor.logger;
+    logger.i(`<-- ${response.status} ${response.config.url}`);
+    Object.entries(response.headers ?? {}).forEach(([k, v]) => logger.i(`${k}: ${v}`));
+    return response;
+  }
+}
+
+/** Pour gérer des erreurs personnalisées détaillées spécifiques */
+export class ErrorInterceptor {
+  static readonly logger = new Logger();
+
+  attach(client: AxiosInstance): void {
+    client.interceptors.response.use(undefined, (error) => this.onError(error));
+  }
+
+  onError(err: unknown): never {
+    ErrorInterceptor.logger.e('Error HTTP - dans Error interceptor', { error: err });
+    if (err instanceof ApiException) throw err;
+    if (!axios.isAxiosError(err)) {
+      throw new ApiException({ error: ApiError.unknowError, message: String(err) });
+    }
+    const statusCode = err.response?.status;
+    if (err.code === AxiosError.ECONNABORTED || err.code === AxiosError.ETIMEDOUT) {
+      throw new ApiException({ error: ApiError.timeOut, statusCode, message: err.message });
+    }
+    if (err.response) {
+      ErrorInterceptor.checkErrors(err.response);
+    }
+    if (err.code === AxiosError.ERR_NETWORK || !err.response) {
+      throw new ApiException({ error: ApiError.noInternetConnection, statusCode, message: err.message });
+    }
+    throw new ApiException({ error: ApiError.unknowError, statusCode, message: err.message });
+  }
+
+  static checkErrors(response: Pick<AxiosResponse, 'status' | 'data'>): void {
+    const statusCode = response.status;
+    if (statusCode === 400) {
+      throw new ApiException({ error: ApiError.badRequest, statusCode, problem: ApiProblem.fromJson(response.data) });
+    } else if (statusCode === 401) {
+      throw new ApiException({ error: ApiError.unauthorized, statusCode });
+    } else if (statusCode === 403) {
+      throw new ApiException({ error: ApiError.forbidden, statusCode, problem: ApiProblem.fromJson(response.data) });
+    } else if (statusCode === 404) {
+      throw new ApiException({ error: ApiError.notFound, statusCode });
+    } else if (statusCode === 504) {
+      throw new ApiException({ error: ApiError.timeOut, statusCode });
+    } else if (statusCode === 500 || statusCode === 503) {
+      throw new ApiException({ error: ApiError.internalServerError, statusCode });
+    } else if (![200, 201, 202, 204, 206].includes(statusCode)) {
+      throw new ApiException({ error: ApiError.unknowError, statusCode });
+    }
+  }
+}
+
+/**
+ * Comme `on DioException catch (e) { throw e.error as ApiException; }` :
+ * toute erreur qui sort du client est déjà une {@link ApiException} (via
+ * {@link ErrorInterceptor}) ; par sécurité, on convertit le reste.
+ */
+function toApiException(e: unknown): ApiException {
+  if (e instanceof ApiException) return e;
+  try {
+    new ErrorInterceptor().onError(e);
+  } catch (converted) {
+    if (converted instanceof ApiException) return converted;
+  }
+  return new ApiException({ error: ApiError.unknowError, message: String(e) });
+}
+
+function isDebug(): boolean {
+  return typeof __DEV__ !== 'undefined' ? __DEV__ : false;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('timeout')), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      },
+    );
+  });
+}
+
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Décode une chaîne base64url (segment JWT) en texte UTF-8. */
+export function base64UrlDecode(input: string): string {
+  const base64 = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+  let bits = 0;
+  let value = 0;
+  let encoded = '';
+  for (const char of base64) {
+    const index = BASE64_ALPHABET.indexOf(char);
+    if (index < 0) throw new Error(`Caractère base64 invalide : ${char}`);
+    value = (value << 6) | index;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      encoded += '%' + ((value >> bits) & 0xff).toString(16).padStart(2, '0');
+    }
+  }
+  return decodeURIComponent(encoded);
+}