## API - ihm_client

Ce document décrit les interfaces publiques significatives exposées par l’interface `ihm_client`. Il ne contient aucun exemple d’usage exécutable et sert de référence de contrat.

## Types et modules principaux

- Services applicatifs
  - `src/services/service.ts` (classe `Services`) : opérations d’app, gestion des relays, pairing, processus, stockage, conversions hex/blob.
  - `src/services/token.ts` (classe `TokenService`) : génération/validation/refresh de jetons de session.
- Utilitaires
  - `src/utils/sp-address.utils.ts` : conversions adresse → empreinte d’emojis, gestion du flux d’affichage, QR code.
  - `src/utils/html.utils.ts` : résolution du DOM racine ou `shadowRoot`.

## Contrats clés

- `Services.getInstance(): Promise<Services>`: retour singleton initialisé.
- Pairing et processus
  - `createPairingProcess(userName: string, pairWith: string[]): Promise<ApiReturn>`
  - `confirmPairing(): Promise<void>`
  - `createProcess(...)`, `updateProcess(...)` : gestion des états/processus.
- Données chiffrées
  - `getHashForFile(commitedIn: string, label: string, fileBlob: { type: string; data: Uint8Array }): string`
  - `getMerkleProofForFile(processState, attributeName): MerkleProofResult`
  - `validateMerkleProof(proof, hash): boolean`
- Conversion binaire
  - `hexToBlob(hex: string): Blob`
  - `hexToUInt8Array(hex: string): Uint8Array`
  - `blobToHex(blob: Blob): Promise<string>`
- Tokens
  - `TokenService.getInstance(): Promise<TokenService>`
  - `generateSessionToken(origin: string): Promise<{ accessToken: string; refreshToken: string }>`
  - `validateToken(token: string, origin: string): Promise<boolean>`
  - `refreshAccessToken(refreshToken: string, origin: string): Promise<string | null>`

## Invariants

- Les méthodes de `Services` supposent l’initialisation du module WASM (`pkg/sdk_client`) lors du `init()`.
- `TokenService` requiert une clé de signature via `VITE_JWT_SECRET_KEY` (Vite ou environnement Node en test).
- Les conversions hex/binaire doivent préserver l’intégrité des octets (longueur paire pour l’hex).

## Erreurs et retours

- Les méthodes renvoient des erreurs typées via `throw new Error(message)` si un invariant n’est pas respecté (ex. adresse manquante, état introuvable).
- Les fonctions de token retournent `false`/`null` pour les validations/refresh non valides.

## Compatibilité

- Environnement navigateur moderne (WebCrypto, `Blob`, `TextEncoder`).
- Tests sous Jest avec polyfills contrôlés dans `tests/setup.ts`.