@ollaid/native-sso 2.8.2 → 2.8.4

package/docs/8_update_infos.md

@@ -0,0 +1,139 @@
+# Update Infos
+
+Version: `2.8.4`
+
+Ce document décrit le flux recommandé pour la modal profil `OnboardingModal` quand un SaaS veut synchroniser les informations utilisateur avec le package `@ollaid/native-sso`.
+
+## Objectif
+
+- IAM reste la source de vérité.
+- Le SaaS garde une copie locale de `user.user_infos`.
+- Quand le modal s’ouvre, il hydrate les champs depuis IAM.
+- Quand l’utilisateur enregistre, IAM est mis à jour en premier.
+- Après succès IAM, le SaaS est mis à jour immédiatement.
+
+## Flux recommandé
+
+### 1. Ouverture du modal
+
+Quand le SaaS ouvre la modal profil:
+
+- afficher `OnboardingModal`
+- passer le `user` courant
+- utiliser `variant="edit"` si l’utilisateur modifie son profil depuis le SaaS
+- garder `profileHydrating={true}` tant que les données ne sont pas encore chargées
+
+Si vous n’utilisez pas `NativeSSOPage`, la couche SaaS doit d’abord hydrater le profil depuis IAM, puis ouvrir la modal avec les données reçues.
+
+Pendant cette phase, la modal doit afficher un spinner de chargement.
+
+### 2. Hydratation depuis IAM
+
+Le package récupère les infos depuis IAM via son service profil:
+
+- `profileService.getProfile()`
+- endpoint IAM: `GET /backoffice/profile`
+
+Dans le flux autonome `NativeSSOPage`, cette hydratation est déjà gérée par le package.
+
+Les données récupérées doivent remplir les inputs du formulaire:
+
+- `name`
+- `image_url`
+- `ccphone`
+- `phone`
+- `email`
+- `address`
+- `town`
+- `country`
+
+Si IAM renvoie une donnée plus fraîche que celle du SaaS, la valeur IAM gagne.
+
+### 3. Mise à jour depuis la modal
+
+Quand l’utilisateur clique sur `Enregistrer`:
+
+- le package envoie l’update vers IAM via `profileService.updateProfile()`
+- endpoint IAM: `PUT /backoffice/profile`
+- IAM valide, normalise et renvoie la version finale du profil
+
+IAM reste prioritaire sur la validation et la normalisation des champs.
+
+### 4. Synchronisation immédiate vers le SaaS
+
+Après succès IAM:
+
+- le package appelle `onComplete`
+- `onComplete` contient les données finales sous forme `user_infos`
+- le SaaS doit persister immédiatement ces données dans son propre utilisateur
+
+Le SaaS peut:
+
+- mettre à jour son cache local
+- appeler son backend pour enregistrer `user.user_infos`
+- recharger la session utilisateur si besoin
+
+## Règle d’or
+
+La hiérarchie correcte est:
+
+1. IAM
+2. package SSO
+3. SaaS
+
+Donc:
+
+- lecture depuis IAM
+- écriture vers IAM
+- réplication immédiate vers le SaaS
+
+## Exemple d’intégration SaaS
+
+```tsx
+import { useState } from 'react';
+import { OnboardingModal } from '@ollaid/native-sso';
+
+export function ProfileSettings({ user, api }: { user: NativeUser; api: any }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button type="button" onClick={() => setOpen(true)}>
+        Modifier mon profil
+      </button>
+
+      <OnboardingModal
+        open={open}
+        onOpenChange={setOpen}
+        onDismiss={() => setOpen(false)}
+        user={user}
+        variant="edit"
+        profileHydrating={false}
+        onComplete={async (data) => {
+          await api.updateCurrentUser({
+            user_infos: data.user_infos,
+          });
+          setOpen(false);
+        }}
+        onSkip={() => setOpen(false)}
+      />
+    </>
+  );
+}
+```
+
+## Cas du mode automatique
+
+Quand `NativeSSOPage` gère l’auto-onboarding:
+
+- la modal s’ouvre si le profil est incomplet
+- le package hydrate les données depuis IAM
+- les champs manquants sont affichés
+- à la validation, IAM est mis à jour puis le SaaS est synchronisé
+
+## Ce que le SaaS doit retenir
+
+- N’inversez pas la priorité des sources.
+- Ne traitez pas le SaaS comme source de vérité du profil.
+- Ne contournez pas `onComplete`.
+- Si le SaaS modifie `user.user_infos` hors modal, il doit garder la même logique de miroir vers IAM au prochain refresh.

package/docs/9_password_magic_link.md

@@ -0,0 +1,84 @@
+# Password Magic Link Flow
+
+Version: `2.8.4`
+
+Ce document décrit le flux recommandé pour ouvrir le modal de changement de mot de passe sans faire d'appel direct du navigateur vers IAM.
+
+## Objectif
+
+- Le frontend SaaS ouvre la modal mot de passe.
+- Le package `@ollaid/native-sso` appelle le backend SaaS.
+- Le backend SaaS appelle IAM en server-to-server sur `POST /api/backoffice/auth/password-link`.
+- IAM renvoie un `magic_token` ou une URL de redirection.
+- Le backend SaaS renvoie au package une URL de redirection prête à ouvrir.
+- Le navigateur est redirigé vers IAM.
+
+## Pourquoi ce flux
+
+- Il évite le CORS entre navigateur et IAM pour cette action.
+- Il centralise l'authentification et la journalisation côté SaaS.
+- Il laisse IAM gérer la génération du lien magique.
+
+## Contrat attendu côté SaaS
+
+Endpoint conseillé:
+
+```http
+POST /api/native/password-link
+```
+
+Headers envoyés par le package:
+
+- `Authorization: Bearer <token>` si disponible
+- `X-App-Access-Token-Ref` si présent dans le storage
+- `X-IAM-Config-Prefix` si le package est configuré avec un préfixe multi-tenant
+- `X-Device-*` pour le contexte appareil
+
+Body:
+
+```json
+{}
+```
+
+Réponse recommandée:
+
+```json
+{
+  "success": true,
+  "redirect_url": "https://identityam.ollaid.com/auth/auto-connect?magic_token=xxx",
+  "magic_token": "xxx",
+  "expires_at": "2026-05-18T12:00:00+00:00"
+}
+```
+
+Le backend SaaS peut aussi renvoyer `sso_url` pour compatibilité, mais `redirect_url` est la forme à privilégier.
+
+## Contrat backend SaaS -> IAM
+
+Le backend SaaS doit appeler IAM en interne:
+
+```http
+POST https://identityam.ollaid.com/api/backoffice/auth/password-link
+```
+
+IAM répond avec:
+
+```json
+{
+  "success": true,
+  "magic_token": "xxx",
+  "sso_url": "https://identityam.ollaid.com/auth/auto-connect?magic_token=xxx",
+  "expires_at": "2026-05-18T12:00:00+00:00"
+}
+```
+
+Le backend SaaS doit ensuite:
+
+1. valider l'utilisateur courant
+2. relayer la requête vers IAM
+3. retourner au package une URL de redirection prête à ouvrir
+
+## Intégration package
+
+Le composant `PasswordRedirectModal` du package utilise `saasApiUrl`.
+`iamApiUrl` reste supporté temporairement pour compatibilité ascendante, mais il ne doit plus être utilisé pour ce flux.

package/docs/README.md

@@ -0,0 +1,66 @@
+# Native SSO Docs
+
+Version: `2.8.4`
+
+Docs courtes et pratiques pour `@ollaid/native-sso`.
+
+## Démarrage
+
+1. Lisez [Quick Start](./1_quick-start.md)
+2. Vérifiez le contrat backend dans [Backend Contract](./2_backend-contract.md)
+3. Vérifiez le stockage et la sécurité dans [Storage & Security](./3_storage-security.md)
+4. Vérifiez les webhooks dans [Webhooks](./4_webhooks.md)
+5. Si vous utilisez les APIs IAM Account server-to-server, lisez [IAM Account](./5_iam-account.md)
+6. Si vous utilisez les helpers avancés, lisez [Advanced Services](./6_advanced-services.md)
+7. Consultez les notes de migration dans [Migration Notes](./7_migration-notes.md)
+8. Pour la synchro bidirectionnelle des infos profil, lisez [Update Infos](./8_update_infos.md)
+9. Pour le flux de redirection mot de passe via backend SaaS, lisez [Password Magic Link](./9_password_magic_link.md)
+10. Pour la redirection après connexion et le flux `needs_access`, lisez [Login Redirect & Access Flow](./10_login-redirect.md)
+11. Pour la persistance des sessions, le refresh token et la résilience réseau, lisez [Session Refresh & Resilience](./11_session-refresh-resilience.md)
+12. Pour le détail du flux `needs_access` et du bypass `BYPASS=true`, lisez [Needs Access & Bypass](./12_login_mode.md)
+13. Pour la vérification finale des fonctionnalités critiques, lisez [Must Have Working](./13_must_have_working.md)
+14. Pour les variables d'environnement backend IAM SSO, lisez [Backend Env Key](./14_backend_env_key.md)
+
+## Principe
+
+- Le package chiffre les données de session au repos dans son storage.
+- Le frontend SaaS ne lit pas le storage directement.
+- Le frontend SaaS demande la session au package via `getSsoSessionSnapshot()`.
+- La déconnexion passe par `logout()`.
+- Les APIs IAM Account (`iamAccountService`) sont server-to-server uniquement.
+- Les helpers avancés (`mobilePasswordService`, `profileChangeService`, `profileMediaService`) sont documentés séparément.
+
+## Checklist SaaS
+
+- Fournir `redirectAfterLogin` sur `NativeSSOPage` si vous ne voulez pas rester sur la page SSO après connexion.
+- Fournir `redirectAfterLogout` si vous voulez une sortie vers une page métier.
+- Côté backend, renvoyer `needs_access` quand l'utilisateur est authentifié mais n'a pas encore accès à cette application.
+- Si le SaaS active `BYPASS=true`, le backend peut auto-créer l'accès et finaliser la connexion sans afficher le modal.
+- Ne pas appeler le callback final de redirection tant que `grantAccess()` n'a pas terminé, sauf si `BYPASS=true`.
+
+## Onboarding profil
+
+La modal `OnboardingModal` gère deux modes:
+
+- `missing`:
+  - `name`
+  - `image_url`
+  - `phone`
+  - `email`
+  - `address`
+  - `town`
+  - `country`
+- `edit`:
+  - nom complet
+  - photo de profil
+  - téléphone
+  - email
+  - adresse
+  - ville
+  - pays
+
+Le mode automatique piloté par `NativeSSOPage` ouvre la modal après le délai configuré si l’un de ces champs est manquant. Le modal reste scrollable à l’intérieur via le conteneur de contenu dédié.
+
+Quand vous ouvrez la modal depuis votre SaaS, utilisez `variant="edit"` pour afficher le formulaire complet éditable.
+
+Le changement de téléphone ou d’email ouvre un sous-flux OTP dans la même modal, avec une fermeture bloquée tant que le flux est en cours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ollaid/native-sso",
-  "version": "2.8.2",
+  "version": "2.8.4",
   "description": "Package NPM fullstack pour l'authentification Native SSO Ollaid - Frontend-First (Link APIs & Refresh support)",
   "type": "module",
   "main": "dist/index.cjs",
@@ -14,11 +14,14 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "scripts"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly --declaration --outDir dist",
-    "dev": "vite build --watch"
+    "dev": "vite build --watch",
+    "postinstall": "node ./scripts/copy-docs.mjs"
   },
   "peerDependencies": {
     "@capacitor/device": "^7.0.0 || ^8.0.0",

package/scripts/copy-docs.mjs

@@ -0,0 +1,36 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const docsSourceDir = path.resolve(packageRoot, '../docs');
+const projectRoot = process.env.INIT_CWD
+  ? path.resolve(process.env.INIT_CWD)
+  : process.cwd();
+const targetDir = path.resolve(projectRoot, 'docs/ollaid@sso_package');
+
+async function main() {
+  let entries;
+  try {
+    entries = await fs.readdir(docsSourceDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  await fs.rm(targetDir, { recursive: true, force: true });
+  await fs.mkdir(targetDir, { recursive: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+
+    const sourceFile = path.join(docsSourceDir, entry.name);
+    const targetFile = path.join(targetDir, entry.name);
+    await fs.copyFile(sourceFile, targetFile);
+  }
+}
+
+main().catch((error) => {
+  console.error('[ollaid-native-sso] doc copy failed:', error);
+  process.exitCode = 1;
+});