ihm_client/docs/API.md

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.