@itzenata/efact-node 1.0.1

package/src/client.ts

@@ -0,0 +1,215 @@
+import type { AxiosInstance } from "axios";
+import { InvoicesApi } from "./_generated/api/invoices-api.js";
+import { EFactConfigError } from "./errors.js";
+import { createHttpInstance } from "./runtime.js";
+import { InvoicesResource, type ListInvoicesParams } from "./invoices.js";
+import type {
+  CreateInvoiceRequest,
+  InvoiceResponse,
+  InvoiceStatusResponse,
+  PageResponseInvoiceResponse,
+  UpdateInvoiceRequest,
+} from "./_generated/index.js";
+
+/**
+ * Environnements publics et leur URL de base (host uniquement — les chemins
+ * générés portent déjà le préfixe /v1). Seuls les environnements destinés aux
+ * clients sont nommés ; le dev local passe par l'option `baseUrl`
+ * (ex. baseUrl: "http://localhost:8080").
+ *
+ * NOTE : l'URL "production" pointe temporairement sur preview, qui fait office
+ * de prod tant que l'URL de prod définitive n'est pas déployée. La changer ici
+ * (et dans les serveurs OpenAPI) suffira — aucun changement côté clients.
+ */
+export const ENVIRONMENTS = {
+  production: "https://preview.efact-api.itzenata.com",
+} as const;
+
+export type EFactEnvironment = keyof typeof ENVIRONMENTS;
+
+const DEFAULT_ENVIRONMENT: EFactEnvironment = "production";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+
+export interface EFactOptions {
+  /** Environnement cible. Défaut "production". Ignoré si `baseUrl` est fourni. */
+  environment?: EFactEnvironment;
+  /** URL de base explicite (host), p.ex. "http://localhost:8080" en dev local. */
+  baseUrl?: string;
+  /** Délai max par requête, en ms (défaut 30000). */
+  timeout?: number;
+  /** Nombre max de nouveaux essais pour les requêtes sûres (défaut 2). */
+  maxRetries?: number;
+}
+
+/**
+ * Client EFact e-Facture.
+ *
+ * @example
+ * const efact = new EFact(process.env.EFACT_SECRET_KEY);
+ * const invoice = await efact.invoices.create({ ... });
+ */
+export class EFact {
+  private readonly http: AxiosInstance;
+  private readonly baseUrl: string;
+  private readonly maskedKey: string;
+
+  /** Opérations sur les factures : efact.invoices.create/list/retrieve/... */
+  public readonly invoices: InvoicesResource;
+
+  /**
+   * @param secretKey Clé secrète au format efact_sk_... (jamais loggée en clair).
+   * @param options   Options facultatives (environment, baseUrl, timeout, maxRetries).
+   */
+  constructor(secretKey: string, options: EFactOptions = {}) {
+    if (typeof secretKey !== "string" || secretKey.trim() === "") {
+      throw new EFactConfigError(
+        "[EFact] Erreur d'initialisation : la clé secrète est obligatoire.",
+      );
+    }
+    const key = secretKey.trim();
+
+    this.baseUrl = normalizeBaseUrl(resolveBaseUrl(options));
+    this.maskedKey = maskKey(key);
+    const timeoutMs = resolvePositiveInt(options.timeout, DEFAULT_TIMEOUT_MS, "timeout");
+    const maxRetries = resolveNonNegativeInt(options.maxRetries, DEFAULT_MAX_RETRIES, "maxRetries");
+
+    this.http = createHttpInstance(key, this.baseUrl, { timeoutMs, maxRetries });
+    // baseURL est porté par l'instance axios : InvoicesApi n'a besoin que d'elle.
+    this.invoices = new InvoicesResource(new InvoicesApi(undefined, undefined, this.http));
+  }
+
+  /** Configuration non sensible (la clé est toujours masquée). */
+  public getConfig(): { baseUrl: string; apiKeyMasked: string } {
+    return { baseUrl: this.baseUrl, apiKeyMasked: this.maskedKey };
+  }
+}
+
+// ============================================================================
+// Compatibilité : ancien client EFactClient({ apiKey, baseUrl }).
+// ============================================================================
+
+export interface EFactClientConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeout?: number;
+  maxRetries?: number;
+}
+
+/** @deprecated Utiliser `new EFact(secretKey, { baseUrl })`. */
+export class EFactClient extends EFact {
+  constructor(config: EFactClientConfig) {
+    const opts: EFactOptions = {};
+    if (config.baseUrl !== undefined) opts.baseUrl = config.baseUrl;
+    if (config.timeout !== undefined) opts.timeout = config.timeout;
+    if (config.maxRetries !== undefined) opts.maxRetries = config.maxRetries;
+    super(config.apiKey, opts);
+  }
+
+  /** @deprecated Utiliser efact.invoices.create(). */
+  createInvoice(data: CreateInvoiceRequest): Promise<InvoiceResponse> {
+    return this.invoices.create(data);
+  }
+
+  /** @deprecated Utiliser efact.invoices.list(). */
+  listInvoices(params?: ListInvoicesParams): Promise<PageResponseInvoiceResponse> {
+    return this.invoices.list(params);
+  }
+
+  /** @deprecated Utiliser efact.invoices.retrieve(). */
+  getInvoice(invoiceId: string): Promise<InvoiceResponse> {
+    return this.invoices.retrieve(invoiceId);
+  }
+
+  /** @deprecated Utiliser efact.invoices.retrieveStatus(). */
+  getInvoiceStatus(invoiceId: string): Promise<InvoiceStatusResponse> {
+    return this.invoices.retrieveStatus(invoiceId);
+  }
+
+  /** @deprecated Utiliser efact.invoices.update(). */
+  updateInvoice(invoiceId: string, data: UpdateInvoiceRequest): Promise<InvoiceResponse> {
+    return this.invoices.update(invoiceId, data);
+  }
+
+  /** @deprecated Utiliser efact.invoices.cancel(). */
+  cancelInvoice(invoiceId: string): Promise<InvoiceResponse> {
+    return this.invoices.cancel(invoiceId);
+  }
+}
+
+// ============================================================================
+// Validation des options de configuration.
+// ============================================================================
+
+function resolveBaseUrl(options: EFactOptions): string {
+  if (options.baseUrl !== undefined) {
+    return options.baseUrl;
+  }
+  const env = options.environment ?? DEFAULT_ENVIRONMENT;
+  const url = ENVIRONMENTS[env];
+  if (url === undefined) {
+    const known = Object.keys(ENVIRONMENTS).join(", ");
+    throw new EFactConfigError(
+      `[EFact] environment inconnu : "${env}". Valeurs valides : ${known}.`,
+    );
+  }
+  return url;
+}
+
+/** Valide la baseUrl (URL absolue http/https) et avertit si non-HTTPS hors localhost. */
+function normalizeBaseUrl(raw: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new EFactConfigError(
+      `[EFact] baseUrl invalide : "${raw}" n'est pas une URL absolue.`,
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new EFactConfigError(
+      `[EFact] baseUrl invalide : protocole "${parsed.protocol}" non supporté (http/https requis).`,
+    );
+  }
+  const isLocal =
+    parsed.hostname === "localhost" ||
+    parsed.hostname === "127.0.0.1" ||
+    parsed.hostname === "[::1]" ||
+    parsed.hostname === "::1";
+  if (parsed.protocol === "http:" && !isLocal) {
+    console.warn(
+      `[EFact] Attention : baseUrl utilise HTTP non chiffré (${parsed.origin}). ` +
+        "La clé secrète transiterait en clair. Utilisez HTTPS en production.",
+    );
+  }
+  return raw;
+}
+
+/**
+ * Version masquée de la clé : au plus 4 caractères de tête/queue, jamais plus
+ * de la moitié d'une clé courte. Pour le diagnostic.
+ */
+function maskKey(k: string): string {
+  if (k.length <= 8) return "****";
+  return `${k.slice(0, 4)}...${k.slice(-4)}`;
+}
+
+function resolvePositiveInt(value: number | undefined, fallback: number, name: string): number {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new EFactConfigError(
+      `[EFact] Option "${name}" invalide : un nombre positif est attendu.`,
+    );
+  }
+  return Math.floor(value);
+}
+
+function resolveNonNegativeInt(value: number | undefined, fallback: number, name: string): number {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value) || value < 0) {
+    throw new EFactConfigError(
+      `[EFact] Option "${name}" invalide : un entier >= 0 est attendu.`,
+    );
+  }
+  return Math.floor(value);
+}

package/src/errors.ts

@@ -0,0 +1,166 @@
+/**
+ * Détail d'erreur renvoyé dans le tableau "errors" de l'enveloppe backend
+ * (aligné sur le schéma généré `FieldError` : { field, message }).
+ * Forme permissive : le backend peut ajouter des clés.
+ */
+export interface ApiErrorDetail {
+  code?: string;
+  message?: string;
+  field?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Erreurs typées du SDK EFact.
+ *
+ * Toute réponse du backend est enveloppée ({ code, message, data, errors }).
+ * Le SDK transforme les réponses non-"OK" — et les statuts HTTP non-2xx — en
+ * erreurs typées portant le code applicatif, le statut HTTP et le détail des
+ * erreurs, pour que l'appelant puisse les distinguer proprement.
+ */
+
+/** Erreur de base de toutes les erreurs renvoyées par le SDK. */
+export class EFactError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+    // Maintient la chaîne de prototype correcte après transpilation.
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Erreur de configuration du SDK (clé manquante, baseUrl invalide, ...). Levée
+ * avant tout appel réseau.
+ */
+export class EFactConfigError extends EFactError {}
+
+/**
+ * Échec réseau : la requête n'a jamais abouti à une réponse HTTP (DNS, connexion
+ * refusée, TLS, coupure...). `cause` porte l'erreur sous-jacente.
+ */
+export class EFactConnectionError extends EFactError {
+  readonly cause: unknown;
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.cause = cause;
+  }
+}
+
+/**
+ * La requête a dépassé le délai configuré et a été interrompue avant réponse.
+ */
+export class EFactTimeoutError extends EFactError {
+  /** Délai dépassé, en millisecondes. */
+  readonly timeoutMs: number;
+  constructor(message: string, timeoutMs: number) {
+    super(message);
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Erreur renvoyée par l'API : statut HTTP non-2xx, ou enveloppe dont
+ * "code" !== "OK". Porte le code applicatif, le statut HTTP et les détails.
+ */
+export class EFactApiError extends EFactError {
+  /** Code applicatif issu de l'enveloppe ("code"), si disponible. */
+  readonly code: string | undefined;
+  /** Statut HTTP de la réponse, si une réponse HTTP a été reçue. */
+  readonly httpStatus: number | undefined;
+  /** Détails d'erreur issus de l'enveloppe ("errors"), si présents. */
+  readonly errors: ApiErrorDetail[] | undefined;
+
+  constructor(
+    message: string,
+    options: {
+      code?: string | undefined;
+      httpStatus?: number | undefined;
+      errors?: ApiErrorDetail[] | undefined;
+    } = {},
+  ) {
+    super(message);
+    this.code = options.code;
+    this.httpStatus = options.httpStatus;
+    this.errors = options.errors;
+  }
+}
+
+/**
+ * Erreur d'authentification / autorisation. Levée sur HTTP 401/403 ou sur les
+ * codes d'auth connus (API_KEY_MISSING / API_KEY_INVALID).
+ */
+export class EFactAuthError extends EFactApiError {}
+
+/** Erreur de validation de la requête (HTTP 400/422 / codes de validation). */
+export class EFactValidationError extends EFactApiError {}
+
+/** Ressource introuvable (HTTP 404). Inclut le cas cross-tenant. */
+export class EFactNotFoundError extends EFactApiError {}
+
+/**
+ * Conflit d'état (HTTP 409), p.ex. tentative de modifier/annuler une facture
+ * qui n'est plus PENDING (code INVOICE_NOT_EDITABLE).
+ */
+export class EFactConflictError extends EFactApiError {}
+
+/**
+ * Codes d'erreur applicatifs traités comme des erreurs d'authentification.
+ * API_KEY_MISSING / API_KEY_INVALID sont confirmés par le contrat ; les autres
+ * sont conservés par prudence. Le mapping HTTP 401/403 fonctionne aussi seul.
+ */
+export const AUTH_ERROR_CODES: ReadonlySet<string> = new Set([
+  "API_KEY_MISSING",
+  "API_KEY_INVALID",
+  "UNAUTHORIZED",
+  "UNAUTHENTICATED",
+  "INVALID_API_KEY",
+  "API_KEY_REQUIRED",
+  "FORBIDDEN",
+]);
+
+/** Codes applicatifs traités comme des conflits d'état (409). */
+export const CONFLICT_ERROR_CODES: ReadonlySet<string> = new Set([
+  "INVOICE_NOT_EDITABLE",
+]);
+
+/** Codes applicatifs traités comme des erreurs de validation. */
+export const VALIDATION_ERROR_CODES: ReadonlySet<string> = new Set([
+  "VALIDATION_ERROR",
+  "INVALID_REQUEST",
+]);
+
+/**
+ * Fabrique l'erreur API appropriée à partir du statut HTTP et/ou du code
+ * applicatif. Point central de classification des erreurs du backend.
+ */
+export function createApiError(
+  message: string,
+  options: {
+    code?: string | undefined;
+    httpStatus?: number | undefined;
+    errors?: ApiErrorDetail[] | undefined;
+  } = {},
+): EFactApiError {
+  const { code, httpStatus } = options;
+
+  if (httpStatus === 401 || httpStatus === 403 || (code && AUTH_ERROR_CODES.has(code))) {
+    return new EFactAuthError(message, options);
+  }
+  if (httpStatus === 404) {
+    return new EFactNotFoundError(message, options);
+  }
+  if (httpStatus === 409 || (code && CONFLICT_ERROR_CODES.has(code))) {
+    return new EFactConflictError(message, options);
+  }
+  // 400 (requête malformée) et 422 (échec de validation des champs côté
+  // backend) sont tous deux traités comme des erreurs de validation.
+  if (
+    httpStatus === 400 ||
+    httpStatus === 422 ||
+    (code && VALIDATION_ERROR_CODES.has(code))
+  ) {
+    return new EFactValidationError(message, options);
+  }
+  return new EFactApiError(message, options);
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Surface publique du SDK.
+export {
+  EFact,
+  ENVIRONMENTS,
+  type EFactEnvironment,
+  type EFactOptions,
+  EFactClient,
+  type EFactClientConfig,
+} from "./client.js";
+export { InvoicesResource, type ListInvoicesParams } from "./invoices.js";
+export * from "./errors.js";
+
+// Types du contrat, régénérés depuis l'OpenAPI (`src/_generated/`). Réexportés
+// tels quels : un changement de champ côté API se propage ici automatiquement.
+export {
+  type CreateInvoiceRequest,
+  type CreateInvoiceLineRequest,
+  type UpdateInvoiceRequest,
+  type InvoiceResponse,
+  type InvoiceStatusResponse,
+  type PageResponseInvoiceResponse,
+  type FieldError,
+  CreateInvoiceRequestPaymentMethodEnum,
+  InvoiceResponseStatusEnum,
+} from "./_generated/index.js";
+export { ListStatusEnum } from "./_generated/api/invoices-api.js";
+
+// Alias de compatibilité (ancien nommage). Préférer les types générés.
+export type {
+  InvoiceResponse as Invoice,
+  InvoiceStatusResponse as InvoiceStatusResult,
+  CreateInvoiceRequest as CreateInvoiceInput,
+  UpdateInvoiceRequest as UpdateInvoiceInput,
+  CreateInvoiceLineRequest as CreateInvoiceLineInput,
+} from "./_generated/index.js";

package/src/invoices.ts

@@ -0,0 +1,80 @@
+import { InvoicesApi, type ListStatusEnum } from "./_generated/api/invoices-api.js";
+import {
+  type CreateInvoiceRequest,
+  type InvoiceResponse,
+  type InvoiceStatusResponse,
+  type PageResponseInvoiceResponse,
+  type UpdateInvoiceRequest,
+} from "./_generated/index.js";
+import { unwrap, type Envelope } from "./runtime.js";
+import type { AxiosResponse } from "axios";
+
+/**
+ * Paramètres ergonomiques de liste. Aplatit le `Pageable` généré (page/size/sort)
+ * en options plates, façon Stripe.
+ */
+export interface ListInvoicesParams {
+  page?: number;
+  size?: number;
+  /** ex. "createdAt,desc" */
+  sort?: string;
+  status?: ListStatusEnum;
+}
+
+/**
+ * Ressource "invoices" — surface publique STABLE (efact.invoices.*). Chaque
+ * méthode délègue à l'opération générée correspondante et déballe l'enveloppe.
+ * Aucune logique d'endpoint ici : ajouter/retirer un champ sur une facture se
+ * répercute via la régénération des types, sans toucher ce fichier.
+ */
+export class InvoicesResource {
+  constructor(private readonly api: InvoicesApi) {}
+
+  /** POST /v1/invoices — crée une facture. */
+  create(input: CreateInvoiceRequest): Promise<InvoiceResponse> {
+    return unwrap(env(this.api.create({ createInvoiceRequest: input })));
+  }
+
+  /** GET /v1/invoices — liste paginée (filtre/pagination optionnels). */
+  list(params: ListInvoicesParams = {}): Promise<PageResponseInvoiceResponse> {
+    return unwrap(
+      env(
+        this.api.list({
+          ...(params.page !== undefined ? { page: params.page } : {}),
+          ...(params.size !== undefined ? { size: params.size } : {}),
+          ...(params.sort !== undefined ? { sort: [params.sort] } : {}),
+          ...(params.status !== undefined ? { status: params.status } : {}),
+        }),
+      ),
+    );
+  }
+
+  /** GET /v1/invoices/{id} — récupère une facture (404 si hors tenant). */
+  retrieve(invoiceId: string): Promise<InvoiceResponse> {
+    return unwrap(env(this.api.getById({ id: invoiceId })));
+  }
+
+  /** GET /v1/invoices/{id}/status — résultat de clairance DGI. */
+  retrieveStatus(invoiceId: string): Promise<InvoiceStatusResponse> {
+    return unwrap(env(this.api.getStatus({ id: invoiceId })));
+  }
+
+  /** PUT /v1/invoices/{id} — mise à jour partielle (PENDING uniquement). */
+  update(invoiceId: string, input: UpdateInvoiceRequest): Promise<InvoiceResponse> {
+    return unwrap(env(this.api.update({ id: invoiceId, updateInvoiceRequest: input })));
+  }
+
+  /** DELETE /v1/invoices/{id} — annule (PENDING uniquement). */
+  cancel(invoiceId: string): Promise<InvoiceResponse> {
+    return unwrap(env(this.api.cancel({ id: invoiceId })));
+  }
+}
+
+/**
+ * Recadre l'AxiosPromise générée (typée sur `ApiResponse*`) vers notre
+ * `Envelope<T>` unifié afin que `unwrap` en extraie `data`. Ne fait rien à
+ * l'exécution — simple pont de types.
+ */
+function env<T>(p: Promise<AxiosResponse<unknown>>): Promise<AxiosResponse<Envelope<T>>> {
+  return p as Promise<AxiosResponse<Envelope<T>>>;
+}

package/src/runtime.ts

@@ -0,0 +1,179 @@
+import axios, {
+  type AxiosError,
+  type AxiosInstance,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from "axios";
+import {
+  createApiError,
+  EFactApiError,
+  EFactConnectionError,
+  EFactTimeoutError,
+  type ApiErrorDetail,
+} from "./errors.js";
+
+/**
+ * Couche transport STABLE du SDK. Elle configure une instance axios partagée et
+ * y branche les préoccupations transversales — auth, nouveaux essais, mapping
+ * d'erreurs typées, déballage d'enveloppe — qui ne dépendent JAMAIS d'un
+ * endpoint particulier. Regénérer `_generated/` n'oblige donc jamais à toucher
+ * ce fichier.
+ */
+
+/** Enveloppe standard renvoyée par toutes les routes ({ code, data, ... }). */
+export interface Envelope<T> {
+  code?: string;
+  message?: string | null;
+  data?: T;
+  errors?: ApiErrorDetail[] | null;
+}
+
+export interface RuntimeOptions {
+  timeoutMs: number;
+  maxRetries: number;
+}
+
+/** Méthodes HTTP rejouables sans effet de bord (sûres/idempotentes). */
+const RETRYABLE_METHODS = new Set(["get", "head", "put", "delete"]);
+/** Statuts HTTP qui méritent un nouvel essai (surcharge / erreurs serveur). */
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+/** Config axios enrichie d'un compteur d'essais interne au SDK. */
+interface RetryConfig extends InternalAxiosRequestConfig {
+  __efactRetryCount?: number;
+}
+
+/**
+ * Construit l'instance axios utilisée par le client généré. C'est le SEUL
+ * endroit où l'on attache l'auth (Bearer), applique le timeout, rejoue les
+ * requêtes sûres et convertit les échecs en erreurs typées.
+ */
+export function createHttpInstance(
+  secretKey: string,
+  baseUrl: string,
+  options: RuntimeOptions,
+): AxiosInstance {
+  const instance = axios.create({
+    baseURL: baseUrl.replace(/\/+$/, ""),
+    timeout: options.timeoutMs,
+    headers: {
+      // Seul endroit où la clé est attachée. Le backend attend un Bearer token.
+      Authorization: `Bearer ${secretKey}`,
+      Accept: "application/json",
+    },
+    // On lit nous-mêmes le corps d'erreur (enveloppe) pour typer l'erreur.
+    validateStatus: (status) => status >= 200 && status < 300,
+  });
+
+  instance.interceptors.response.use(
+    (response) => response,
+    async (error: AxiosError) => {
+      const cfg = error.config as RetryConfig | undefined;
+      const method = (cfg?.method ?? "get").toLowerCase();
+      const attempt = cfg?.__efactRetryCount ?? 0;
+
+      // 1. Réponse HTTP reçue mais non-2xx.
+      if (error.response) {
+        if (
+          canRetryMethod(method) &&
+          attempt < options.maxRetries &&
+          RETRYABLE_STATUSES.has(error.response.status)
+        ) {
+          return replay(instance, cfg!, attempt, backoffMs(attempt, error.response));
+        }
+        throw toApiError(error.response);
+      }
+
+      // 2. Pas de réponse : timeout ou coupure réseau.
+      const isTimeout = error.code === "ECONNABORTED" || error.code === "ETIMEDOUT";
+      if (canRetryMethod(method) && attempt < options.maxRetries) {
+        return replay(instance, cfg!, attempt, backoffMs(attempt));
+      }
+      if (isTimeout) {
+        throw new EFactTimeoutError(
+          `[EFact] La requête a dépassé le délai de ${options.timeoutMs} ms.`,
+          options.timeoutMs,
+        );
+      }
+      throw new EFactConnectionError(
+        "[EFact] Échec de connexion à l'API (réseau indisponible).",
+        error,
+      );
+    },
+  );
+
+  return instance;
+}
+
+/**
+ * Attend une réponse enveloppée, vérifie `code === "OK"` et renvoie `data`.
+ * Point unique de déballage : les méthodes de ressource restent des one-liners
+ * qui ne connaissent que le type généré, donc un changement de champ passe
+ * sans toucher au code.
+ */
+export async function unwrap<T>(
+  call: Promise<AxiosResponse<Envelope<T>>>,
+): Promise<T> {
+  const response = await call;
+  const envelope = response.data;
+  if (!envelope || typeof envelope.code !== "string") {
+    throw createApiError(
+      `[EFact-API] Réponse inattendue (enveloppe absente) sur HTTP ${response.status}.`,
+      { httpStatus: response.status },
+    );
+  }
+  if (envelope.code !== "OK") {
+    throw createApiError(`[EFact-API] ${envelope.code}: ${envelope.message ?? "Erreur inconnue"}`, {
+      code: envelope.code,
+      httpStatus: response.status,
+      errors: envelope.errors ?? undefined,
+    });
+  }
+  return envelope.data as T;
+}
+
+function replay(
+  instance: AxiosInstance,
+  cfg: RetryConfig,
+  attempt: number,
+  waitMs: number,
+): Promise<AxiosResponse> {
+  cfg.__efactRetryCount = attempt + 1;
+  return delay(waitMs).then(() => instance.request(cfg));
+}
+
+function toApiError(response: AxiosResponse): EFactApiError {
+  const envelope = (response.data ?? {}) as Envelope<unknown>;
+  const code = envelope.code ?? `HTTP_${response.status}`;
+  const detail =
+    (typeof envelope.message === "string" && envelope.message) ||
+    response.statusText ||
+    "Erreur inconnue";
+  return createApiError(`[EFact-API] ${code}: ${detail}`, {
+    code: envelope.code ?? undefined,
+    httpStatus: response.status,
+    errors: envelope.errors ?? undefined,
+  });
+}
+
+function canRetryMethod(method: string): boolean {
+  return RETRYABLE_METHODS.has(method);
+}
+
+/** Back-off exponentiel plafonné, en respectant Retry-After si fourni. */
+function backoffMs(attempt: number, response?: AxiosResponse): number {
+  const retryAfter = response?.headers?.["retry-after"];
+  if (retryAfter !== undefined) {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+      return Math.min(seconds * 1000, 20_000);
+    }
+  }
+  const base = Math.min(500 * 2 ** attempt, 8_000);
+  const jitter = base * 0.2 * (Math.random() * 2 - 1);
+  return Math.round(base + jitter);
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}