@pi-spi/app 0.0.0-stage → 1.2.1

package/LICENSE

@@ -0,0 +1,31 @@
+PI-SPI SDK Source-Available License
+
+Copyright (c) 2026 BCEAO. All rights reserved.
+
+1. Grant of Use. Subject to the terms of this license, BCEAO grants you a
+   worldwide, royalty-free, non-exclusive, non-transferable license to
+   download, view, and use this software (the "Software") solely to
+   integrate it, unmodified or modified, into your own application(s) as a
+   participant of the PI-SPI ecosystem.
+
+2. Restrictions. Except as expressly permitted above, you may not:
+   (a) redistribute, publish, or sublicense the Software, in source or
+       compiled form, whether unmodified or modified, as a standalone
+       product or package (e.g., on pub.dev, GitHub, npm, or any other
+       distribution channel) separate from your own application;
+   (b) sell, rent, or lease the Software itself, independently of your own
+       application;
+   (c) remove or alter any copyright, trademark, or other proprietary
+       notices contained in the Software.
+
+3. No Other Rights. All rights not expressly granted in this license are
+   reserved by BCEAO. This license does not grant you any rights to BCEAO's
+   trademarks, service marks, or logos.
+
+4. Disclaimer of Warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT
+   WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+   THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL BCEAO BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+   THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,560 @@
-# Temporary Holding Version
+# @pi-spi/app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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, sans reprendre dans son ensemble
+[l'app de référence](https://developers.pi-bceao.com/sandbox/pages/sandbox-guides-mobile-codesource)
+dont le code source a été partagé avec tous les participants.
+
+## Aperçu
+
+![Démo du SDK PI-SPI dans l'app d'exemple](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/demo.gif)
+
+## Documentation de l'API
+
+Le SDK n'expose que le sous-ensemble de l'API PI-SPI dont il a réellement
+besoin (voir [« Ce que le SDK ne fait pas »](#ce-que-le-sdk-ne-fait-pas)
+ci-dessous pour ce qui est volontairement hors périmètre). La référence
+complète — tous les endpoints, schémas de requête/réponse, exemples — est
+disponible ici :
+
+**[developers.pi-bceao.com/api-reference/mob-sdk](https://developers.pi-bceao.com/api-reference/mob-sdk/index.html)**
+
+## Ce que le SDK ne fait pas
+
+Contrairement à l'app de référence du code source partagé, ce SDK
+**n'implémente aucune authentification** :
+
+- Pas de login, pas de Keycloak/PKCE
+- Pas de vérification PIN/biométrique avant confirmation d'une transaction
+- Pas de refresh de token (le SDK ne parle jamais à un IDP)
+- Pas de fournisseur de notifications push (Firebase, APNs, ...) — voir
+  la section [Notifications push](#notifications-push) pour le point
+  d'intégration fourni
+
+Tout cela reste entièrement à la charge de l'application hôte. Le SDK fait
+confiance à l'appelant : si l'hôte affiche l'écran du SDK, c'est que
+l'utilisateur est authentifié et autorisé.
+
+Le SDK ne stocke et ne vérifie **aucun secret** (ni PIN, ni empreinte) —
+mais il garantit que la vérification a bien lieu : avant chaque action
+sensible (confirmer une transaction, supprimer un alias...), il appelle
+`PiSpiIdentificationConfig.requireStepUpIdentification`, qui délègue la
+vérification à l'hôte et ne renvoie qu'un booléen. Voir la section
+[`requireStepUpIdentification`](#requirestepupidentification) plus bas.
+
+## Installation
+
+```sh
+npm install @pi-spi/app
+npx expo install @react-navigation/native @react-navigation/native-stack \
+  react-native-screens react-native-safe-area-context \
+  @react-native-async-storage/async-storage @expo/vector-icons \
+  expo-secure-store expo-crypto expo-network expo-audio expo-image \
+  expo-font expo-asset expo-video expo-contacts expo-location \
+  expo-clipboard react-native-svg expo-image-picker expo-file-system \
+  expo-print expo-sharing expo-camera react-native-view-shot \
+  react-native-webview
+```
+
+Le SDK s'appuie sur des modules Expo, déclarés en `peerDependencies` : il
+fonctionne dans une app Expo (development build, pas Expo Go) comme dans
+une app React Native « bare » où les modules Expo sont installés
+(`npx install-expo-modules@latest`). `npx expo install` choisit les
+versions compatibles avec votre SDK Expo (testé avec Expo 57 /
+React Native 0.86).
+
+## Intégration
+
+`PiSpiSdkConfig` regroupe ses champs par thème : `api`
+(backend/authentification), `appConfig` (identité/préférences de l'app
+hôte), `identification` (step-up) et `log` (journalisation, optionnel).
+`user` et `onClose` restent au niveau racine. Chaque classe et chaque
+champ sont documentés dans
+[`src/core/pi_spi_sdk_config.ts`](src/core/pi_spi_sdk_config.ts).
+
+```tsx
+import {
+  PiSpiApiConfig, PiSpiAppConfig, PiSpiCompte, PiSpiIdentificationConfig,
+  PiSpiSdkConfig, PiSpiSdkEntry, PiSpiUserIdentity,
+} from '@pi-spi/app';
+
+const config = new PiSpiSdkConfig({
+  user: new PiSpiUserIdentity({
+    firstName: user.firstName,
+    lastName: user.lastName,
+    fullName: user.fullName,
+    // Pays de domiciliation du compte : code UEMOA (voir
+    // PiSpiUserIdentity.supportedPaysCodes).
+    pays: user.pays,
+    avatar: user.avatarUrl,
+    // La liste des comptes du client — jamais vide, voir la section
+    // "Comptes multiples" plus bas. Un seul élément si le client n'a
+    // qu'un compte.
+    comptes: [new PiSpiCompte({ numero: user.accountNumber, libelle: 'Courant', solde: user.solde })],
+  }),
+  api: new PiSpiApiConfig({
+    apiBaseUrl: 'https://api.exemple-participant.com',
+    // Token valide au moment de l'ouverture du SDK.
+    accessToken: monAuthService.currentAccessToken,
+    // Appelé quand une requête échoue en 401/403 avec le token courant :
+    // l'hôte le rafraîchit et retourne le nouveau token (ou null s'il n'y
+    // parvient pas). Après 3 échecs, le SDK appelle onSessionExpired.
+    onAccessTokenExpired: async () => monAuthService.refreshAccessToken(),
+    // Appelé si onAccessTokenExpired ne parvient plus à fournir de token
+    // valide après 3 tentatives : une vraie erreur de session.
+    onSessionExpired: async () => {
+      closeSdk();
+      monAuthService.redirectToLogin();
+    },
+  }),
+  appConfig: new PiSpiAppConfig({
+    pspCodeMembre: 'SNB000',
+    // Langue d'affichage du SDK (fr/en/pt) : l'hôte gère son propre
+    // paramétrage de langue, le SDK n'en a pas. Voir "Localisation" plus bas.
+    defaultLocale: monAuthService.langueActuelle, // ex. 'fr'
+  }),
+  identification: new PiSpiIdentificationConfig({
+    // Appelé avant chaque action sensible : à vous de vérifier PIN/biométrie
+    // et de renvoyer true/false. Voir la section dédiée plus bas.
+    requireStepUpIdentification: async () => monAuthService.demanderConfirmation(),
+  }),
+  // Optionnel : appelé pour une fermeture volontaire du SDK (bouton retour
+  // sans écran derrière, bouton de fermeture de l'accueil...) — pas une
+  // erreur. Si omis, api.onSessionExpired est utilisé à la place. Voir
+  // "onClose vs onSessionExpired" plus bas.
+  onClose: async () => closeSdk(),
+});
+
+// Une fois l'utilisateur authentifié, affichez le SDK en plein écran :
+{sdkOpen && <PiSpiSdkEntry config={config} />}
+```
+
+Le SDK embarque sa propre navigation (un `NavigationContainer`
+indépendant : il ne perturbe pas celui de l'hôte, même si l'hôte utilise
+lui aussi React Navigation), son propre thème et ses propres traductions :
+l'hôte n'a rien d'autre à déclarer.
+
+### Exemple d'intégration
+
+Le package publié contient l'app hôte d'exemple, consultable depuis
+l'onglet **Code** de la page npm (ou dans `node_modules/@pi-spi/app/example/`
+une fois le package installé) :
+
+- [`example/App.tsx`](example/App.tsx) : une app hôte factice qui ouvre le
+  SDK en mode démo, avec un ou plusieurs comptes, dans chacun des thèmes,
+  qui simule un push (`PiSpiPush.handleIncoming`), un écran de
+  vérification renforcée (`requireStepUpIdentification`), et qui gère le
+  bouton retour Android ;
+- [`example/app.json`](example/app.json) : la configuration Expo, avec les
+  plugins et les messages des permissions natives.
+
+Les logos π et PI-SPI utilisés sur les boutons de l'exemple, dans toutes
+leurs variantes de couleurs, sont disponibles dans
+[mobile-app-flutter-sdk-assets/variante_logo_pi_et_pispi](https://github.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/tree/main/variante_logo_pi_et_pispi).
+
+### `PiSpiUserIdentity`
+
+Identité de l'utilisateur connecté côté hôte. Le SDK ne gère aucune
+authentification lui-même : ces informations sont uniquement affichées
+(nom, avatar) ou utilisées pour construire les requêtes (numéro de
+compte). Aucune n'est vérifiée ni stockée par le SDK au-delà de la
+session en cours.
+
+| Champ | Type | Requis | Description |
+| --- | --- | --- | --- |
+| `firstName` | `string` | oui | Prénom du client. |
+| `lastName` | `string` | oui | Nom du client. |
+| `fullName` | `string` | oui | Nom complet affiché dans l'UI du SDK (voir `nomComplet()`, qui se replie sur `firstName` + `lastName` si vide). |
+| `pays` | `string` | oui | Code pays UEMOA de domiciliation du **compte** (pas nécessairement celui du client) : `BJ`, `BF`, `CI`, `GW`, `ML`, `NE`, `SN` ou `TG` (voir `PiSpiUserIdentity.supportedPaysCodes`). Toute autre valeur lève une erreur en développement. |
+| `comptes` | `PiSpiCompte[]` | oui | Comptes du client, **jamais vide** — voir [« Comptes multiples »](#comptes-multiples-pispiuseridentitycomptes) plus bas. |
+| `avatar` | `string` | non | URL de la photo de profil du client, affichée dans l'UI du SDK. |
+| `currentAccount` | `string` | non | Compte actif par défaut avant toute sélection — voir [« Comptes multiples »](#comptes-multiples-pispiuseridentitycomptes) plus bas. |
+
+`PiSpiCompte` (élément de `comptes`) :
+
+| Champ | Type | Description |
+| --- | --- | --- |
+| `numero` | `string` | Numéro du compte (ex. numéro de compte bancaire, numéro de téléphone EME ou tout autre identifiant de compte du client). |
+| `libelle` | `string` | Libellé affiché à l'utilisateur (ex. `"Courant"`, `"Épargne"`). |
+| `solde` | `number` | Solde du compte, affiché dans l'écran de sélection. |
+
+### Comptes multiples (`PiSpiUserIdentity.comptes`)
+
+`comptes` **ne doit jamais être vide** : c'est la liste des comptes
+bancaires du client.
+
+```ts
+new PiSpiUserIdentity({
+  // ...
+  comptes: [
+    new PiSpiCompte({ numero: 'SN0011...431', libelle: 'Courant', solde: 9240320 }),
+    new PiSpiCompte({ numero: 'SN0011...432', libelle: 'Chèque', solde: 240000 }),
+    new PiSpiCompte({ numero: 'SN0011...430', libelle: 'Épargne', solde: 32240320 }),
+  ],
+});
+```
+
+**Un seul compte** : rien à faire de plus, il est utilisé directement —
+pas d'écran de sélection, pas de carrousel.
+
+**Plusieurs comptes** : à chaque ouverture du SDK, un écran « Sélectionner
+un compte » s'affiche (juste après l'introduction/permissions au premier
+lancement, sinon directement) — le client choisit celui à utiliser pour
+cette session. Ce choix devient ensuite **le compte actif de toute la
+session** (alias PI-SPI recherché/créé pour lui, QR partagé, transactions
+envoyées...) jusqu'à la fermeture du SDK. Le compte actif peut aussi être
+changé sans rouvrir le SDK, via un carrousel horizontal sur la carte
+compte de l'accueil : swiper d'un compte à l'autre re-sélectionne
+immédiatement le compte actif ; si le compte affiché n'a pas encore
+d'alias PI-SPI, l'écran de création s'ouvre automatiquement pour lui
+(directement sur le choix du type d'alias — le compte est déjà connu, il
+n'est jamais redemandé).
+
+`currentAccount` reste disponible, optionnel : c'est la valeur par défaut
+avant que le client n'ait choisi un compte (non fourni, `comptes[0].numero`
+est utilisé) — l'écran de sélection s'affiche tout de même à chaque
+ouverture dès que `comptes` en contient plusieurs, quelle que soit la
+valeur de `currentAccount`.
+
+### Localisation
+
+**Contrainte : le SDK ne peut être utilisé qu'en français, anglais ou
+portugais** (`'fr'`, `'en'`, `'pt'`). Passer une autre langue à
+`defaultLocale` lève une erreur en développement
+(`PiSpiAppConfig.supportedLocaleCodes`).
+
+Le SDK n'a pas son propre sélecteur de langue dans ses écrans de
+paramètres : c'est `PiSpiAppConfig.defaultLocale` qui détermine la langue
+affichée (`'fr'` par défaut), indépendamment de la langue du téléphone.
+C'est à l'hôte de gérer son propre paramétrage de langue et de transmettre
+la valeur actuelle :
+
+```ts
+new PiSpiSdkConfig({
+  // ...
+  appConfig: new PiSpiAppConfig({
+    // ...
+    defaultLocale: monAuthService.langueActuelle, // 'fr', 'en' ou 'pt' uniquement
+  }),
+});
+```
+
+Si votre app hôte supporte d'autres langues, mappez-les vers la langue la
+plus proche parmi `fr`/`en`/`pt` avant de les transmettre au SDK.
+
+### `defaultTheme`
+
+Champ optionnel (`PiSpiAppConfig.defaultTheme`) : si vous le fournissez,
+**il est appliqué immédiatement et persisté comme nouveau thème par
+défaut à chaque ouverture du SDK** — y compris si le client avait
+lui-même changé de thème depuis les écrans de paramètres du SDK lors
+d'une session précédente. Si vous ne le fournissez pas, la préférence
+locale actuelle est conservée telle quelle (ou `Themes.light` si aucune
+n'existe encore).
+
+```ts
+import { Themes } from '@pi-spi/app';
+
+new PiSpiSdkConfig({
+  // ...
+  appConfig: new PiSpiAppConfig({
+    // ...
+    defaultTheme: Themes.dark, // optionnel ; omettre pour ne rien imposer
+  }),
+});
+```
+
+Une fois le SDK ouvert, l'utilisateur reste libre de changer de thème
+depuis ses écrans de paramètres — **si vous l'y autorisez**, voir
+[`canChangeTheme`](#canchangetheme) ci-dessous ; ce choix persiste
+jusqu'à la prochaine ouverture où l'hôte fournit lui-même une valeur.
+
+### `canChangeTheme`
+
+Champ optionnel (`PiSpiAppConfig.canChangeTheme`) : autorise le client à
+changer lui-même de thème depuis les écrans de paramètres du SDK. Tant
+qu'il vaut `false`, l'entrée « Thème » est masquée dans les paramètres,
+et le thème reste celui fixé par [`defaultTheme`](#defaulttheme) (ou la
+préférence déjà persistée) pour toute la session.
+
+**Non fourni, sa valeur par défaut dépend de `defaultTheme`** : `false`
+si vous fournissez un `defaultTheme` (vous l'imposez alors pour la
+session, cohérent avec `defaultLocale`), `true` sinon (vous n'avez
+exprimé aucun avis sur le thème, donc autant laisser le client choisir).
+Passez `canChangeTheme` explicitement pour découpler ce comportement de
+`defaultTheme`.
+
+```ts
+new PiSpiSdkConfig({
+  // ...
+  appConfig: new PiSpiAppConfig({
+    // ...
+    defaultTheme: Themes.dark,
+    canChangeTheme: true, // sinon, comme defaultTheme est fourni, l'entrée « Thème » resterait masquée
+  }),
+});
+```
+
+La page d'accueil du SDK affiche toujours la variante avec QR code — il
+n'y a pas de choix de mise en page à configurer.
+
+### Thèmes disponibles
+
+Le SDK propose 10 thèmes (`Themes.system`, `.light`, `.dark`, `.yellow`,
+`.green`, `.blue`, `.red`, `.orange`, `.purple`, `.pink`) — voir
+[`defaultTheme`](#defaulttheme) et [`canChangeTheme`](#canchangetheme)
+ci-dessus pour les imposer ou laisser le client choisir depuis les écrans
+de paramètres du SDK.
+
+| Aperçu | Valeur | Description |
+| --- | --- | --- |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_system_thumb.png) | `Themes.system` | Suit le thème clair/sombre de l'appareil. Défaut si aucun thème n'est fourni ni déjà persisté. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_thumb.jpeg) | `Themes.light` | Thème clair. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_dark_thumb.jpeg) | `Themes.dark` | Thème sombre. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_yellow_thumb.jpeg) | `Themes.yellow` | Thème clair, accent jaune. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_green_thumb.jpeg) | `Themes.green` | Thème clair, accent vert. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_blue_thumb.jpeg) | `Themes.blue` | Thème clair, accent bleu. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_red_thumb.jpeg) | `Themes.red` | Thème clair, accent rouge. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_orange_thumb.jpeg) | `Themes.orange` | Thème clair, accent orange. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_purple_thumb.jpeg) | `Themes.purple` | Thème clair, accent violet. |
+| ![](https://raw.githubusercontent.com/pisfn-sandbox/mobile-app-flutter-sdk-assets/main/theme_light_pink_thumb.jpeg) | `Themes.pink` | Thème clair, accent rose. |
+
+### Permissions natives (Android / iOS)
+
+Le SDK ne déclare pas lui-même les permissions natives qu'il utilise :
+**c'est à chaque application hôte de les ajouter, avec ses propres
+messages**, sinon les fonctionnalités correspondantes (scan QR, contacts,
+géolocalisation...) seront refusées par l'OS.
+
+**App Expo** — via les config plugins dans `app.json` :
+
+```json
+"plugins": [
+  ["expo-contacts", { "contactsPermission": "…pour envoyer de l'argent à un contact" }],
+  ["expo-location", { "locationWhenInUsePermission": "…pour vérifier vos transactions et prévenir la fraude" }],
+  "expo-sharing",
+  ["expo-camera", { "cameraPermission": "…pour scanner un QR code PI-SPI" }],
+  ["expo-image-picker", {
+    "photosPermission": "…pour joindre un ticket de caisse ou importer un QR code",
+    "cameraPermission": "…pour photographier un ticket de caisse"
+  }]
+]
+```
+
+Voir `example/app.json` pour une version prête à copier.
+
+**App React Native « bare »** — **Android**, dans
+`android/app/src/main/AndroidManifest.xml` :
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.READ_CONTACTS" />
+<uses-permission android:name="android.permission.WRITE_CONTACTS" />
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+<uses-permission android:name="android.permission.VIBRATE" />
+```
+
+**iOS**, dans `ios/<App>/Info.plist` :
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>...pour scanner les QR codes</string>
+<key>NSContactsUsageDescription</key>
+<string>...pour envoyer de l'argent à un contact</string>
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>...pour vérifier vos transactions et prévenir la fraude</string>
+<key>NSPhotoLibraryUsageDescription</key>
+<string>...pour importer un QR code depuis la galerie</string>
+```
+
+`VIBRATE` sert aux notifications reçues pendant que le SDK est ouvert
+(option « Vibrations » des paramètres) ; Expo l'ajoute par défaut.
+
+La permission notification n'est demandée par aucun écran du SDK. Si
+l'hôte a installé `expo-notifications`, le SDK s'en sert pour lire son
+état ; sinon, il la considère simplement comme non accordée.
+
+### Bouton retour Android
+
+Le SDK gère le bouton retour dans sa propre pile d'écrans. Quand il n'a
+plus d'écran à dépiler, l'événement remonte à l'hôte : écoutez-le
+(`BackHandler`) pour refermer le SDK, comme le fait `example/App.tsx`.
+Évitez d'afficher le SDK dans un `<Modal>` React Native sur Android : le
+bouton retour y déclenche `onRequestClose` au lieu de la navigation
+interne du SDK.
+
+### `requireStepUpIdentification`
+
+Le SDK appelle ce callback juste avant de dispatcher une action sensible
+(confirmer une transaction, un envoi programmé, une demande de paiement
+acceptée, un paiement partagé, un retour de fonds, une annulation,
+supprimer un alias). Si le callback renvoie `false`, l'action est
+simplement annulée.
+
+```ts
+requireStepUpIdentification: async () => {
+  // Remplacez par votre propre vérification (écran PIN,
+  // expo-local-authentication...).
+  const ok = await monAuthService.demanderPinOuBiometrie();
+  return ok;
+},
+```
+
+Le SDK ne connaît jamais le PIN ni la méthode utilisée : c'est
+volontaire, pour ne pas dupliquer un mécanisme de sécurité que l'app hôte
+possède déjà (voir [`confirmationMethodLabel`](#confirmationmethodlabel)
+pour indiquer a posteriori la méthode employée). Ce callback est ce qui
+garantit qu'aucune action sensible ne peut être confirmée sans step-up,
+même si un développeur oublie de le faire lui-même avant d'appeler le SDK.
+
+### Notifications push
+
+Le SDK n'embarque aucun fournisseur de push, ni la logique d'enregistrement
+du token auprès du backend : c'est l'application hôte qui gère sa propre
+configuration de push de bout en bout (Firebase, APNs,
+`expo-notifications`, OneSignal...) — y compris l'enregistrement du token
+auprès du backend PI-SPI. `PiSpiPush` ne fait qu'un pont entre un message
+push déjà reçu par l'hôte et l'UI du SDK :
+
+```ts
+import { PiSpiPush } from '@pi-spi/app';
+
+// Dans le handler de message push de l'hôte (ex. messaging().onMessage) :
+messaging().onMessage(async (remoteMessage) => {
+  PiSpiPush.handleIncoming(
+    remoteMessage.data ?? {}, // notificationId, idObject, type, montant, clientAlias, ...
+    { title: remoteMessage.notification?.title, body: remoteMessage.notification?.body },
+  );
+});
+```
+
+`handleIncoming` republie l'événement dans le bus interne du SDK, ce qui
+déclenche le même comportement (bannière ou boîte dans l'app, son,
+vibration, rafraîchissement de la liste, badge) que dans l'app de
+référence — sans que le SDK ait besoin de savoir comment le push a été
+reçu. Le contenu exact de `data` dépend du type de notification à
+l'origine du push : voir le schéma
+[`NotificationPushData`](https://developers.pi-bceao.com/api-reference/mob-sdk/index.html#schema-notificationpushdata)
+de l'openapi du SDK.
+
+### Première utilisation (introduction + permission contacts)
+
+Comme dans l'app de référence, la toute première fois que l'utilisateur
+ouvre le SDK (tant qu'il n'a jamais atteint la fin de l'introduction),
+`PiSpiSdkEntry` affiche automatiquement, avant l'accueil :
+
+1. **L'introduction** (6 écrans vidéo swipeables) — le dernier écran a un
+   bouton « Continuer » (au lieu du bouton de connexion de l'app de
+   référence, puisque le SDK n'a pas de login) qui marque
+   `ConfigKey.introductionPassed` et enchaîne directement sur l'étape
+   suivante.
+2. **La demande de permission contacts** — explique pourquoi le SDK
+   demande l'accès aux contacts avant de la solliciter réellement.
+   Contrairement à l'app de référence, cette étape ne redemande pas la
+   permission notification (le SDK n'a pas de fournisseur de push, voir
+   [Notifications push](#notifications-push)).
+
+Cet état est persisté localement par le SDK lui-même : il n'y a rien à
+configurer côté hôte, et ce flow ne s'affiche plus jamais une fois passé.
+
+### Mode démo
+
+`PiSpiApiConfig.demoMode: true` remplace tous les appels réseau par les
+réponses de `assets/json/` (les mêmes que le SDK Flutter). Utile pour
+visualiser le SDK sans backend PI-SPI ; ne jamais l'activer en production.
+
+## `confirmationMethodLabel`
+
+L'API persiste la méthode de confirmation utilisée pour une transaction
+(`"pin"`, `"fingerprint"`, ... dans l'app de référence). Le SDK n'ayant pas
+connaissance de la politique de sécurité de l'hôte, il envoie la valeur de
+`PiSpiIdentificationConfig.confirmationMethodLabel` (par défaut
+`"external"`). **Vérifiez avec l'équipe backend PI-SPI si ce champ a une
+contrainte d'énumération avant mise en production.**
+
+## `logLevel`
+
+Niveau de journalisation du SDK, configurable via
+`PiSpiLogConfig.logLevel` : `"debug"` (défaut), `"trace"`, `"info"`,
+`"warning"`, `"error"`, `"fatal"` ou `"off"`. Une valeur inconnue équivaut
+à tout journaliser.
+
+```ts
+new PiSpiSdkConfig({
+  // ...
+  log: new PiSpiLogConfig({
+    logLevel: 'warning', // à réduire en production
+  }),
+});
+```
+
+Le SDK n'installe pas de crash reporting lui-même (voir
+[« Ce que le SDK ne fait pas »](#ce-que-le-sdk-ne-fait-pas)) : ces logs
+sont uniquement destinés au débogage pendant l'intégration.
+
+## `onError`
+
+Optionnel (équivalent de `onFlutterError` dans le SDK Flutter) : callback
+appelé pour chaque erreur JS interceptée pendant que le SDK est affiché
+(erreur de rendu d'un écran du SDK, ou erreur globale), pour que l'hôte la
+remonte à son propre outil de crash reporting (Crashlytics, Sentry...).
+
+```ts
+new PiSpiSdkConfig({
+  // ...
+  log: new PiSpiLogConfig({
+    onError: (error, isFatal) => {
+      MyCrashReporter.recordError(error, isFatal);
+    },
+  }),
+});
+```
+
+Ce callback ne fait que **transmettre** l'erreur : il n'écrase jamais un
+gestionnaire global déjà défini par l'hôte (celui-ci continue d'être
+appelé juste après), et le SDK ne quitte jamais l'application à sa place —
+cela reste entièrement la décision de l'hôte.
+
+## `onClose` vs `onSessionExpired`
+
+Le SDK rend la main à l'hôte dans deux situations bien différentes :
+
+- **`api.onSessionExpired`** (obligatoire) : une vraie erreur —
+  `api.onAccessTokenExpired` ne parvient plus à fournir de token valide
+  après 3 tentatives (401/403 persistant). L'hôte voudra probablement
+  rediriger vers sa propre connexion.
+- **`onClose`** (optionnel, au niveau racine de `PiSpiSdkConfig`) : une
+  fermeture volontaire, sans erreur — le client a fermé le SDK depuis un
+  bouton retour ou de fermeture. Il n'y a simplement plus rien à afficher.
+
+Si `onClose` n'est pas fourni, le SDK utilise `api.onSessionExpired` à sa
+place. Ne fournissez `onClose` que si vous voulez réagir différemment à
+ces deux situations (typiquement : ne pas afficher un message « session
+expirée » lors d'une fermeture volontaire).
+
+## Développement
+
+```sh
+npm install
+npm run gen-l10n   # régénère src/l10n/*.ts depuis src/l10n/intl_*.arb
+npm run typecheck
+npm test
+
+cd example
+npm install
+npx expo run:android   # ou run:ios (development build)
+```
+
+Les traductions sont écrites dans les mêmes fichiers `.arb` que le SDK
+Flutter (`src/l10n/intl_fr.arb`, `intl_en.arb`, `intl_pt.arb`) ; le script
+`scripts/gen-l10n.js` en génère les fichiers TypeScript (ne pas les
+modifier à la main).
+
+Le dossier `example/` contient une application hôte factice qui ouvre le
+SDK en mode démo, avec un ou plusieurs comptes, dans chacun des thèmes, et
+qui sait simuler un push, pour valider l'intégration de bout en bout. Elle
+consomme directement les sources du SDK (`../src`, voir
+`example/metro.config.js`).