@ollaid/native-sso 1.0.6 → 1.0.8

package/README.md

@@ -11,19 +11,22 @@ Package NPM Frontend-First pour l'authentification Native SSO Ollaid.
  2. [Intégration rapide (3 étapes)](#intégration-rapide-3-étapes)
  3. [Props de NativeSSOPage](#props-de-nativessopage)
  4. [Usage avancé (composants individuels)](#usage-avancé-composants-individuels)
- 5. [Backend SaaS — Endpoints requis](#backend-saas--endpoints-requis)
- 6. [APIs IAM Account (Server-to-Server)](#apis-iam-account-server-to-server)
- 7. [Avatar par application](#avatar-par-application)
- 8. [Réponses d'erreur](#réponses-derreur)
- 9. [Configuration .env Laravel](#configuration-env-laravel)
- 10. [Migration Laravel](#migration-laravel)
- 11. [Flux d'authentification](#flux-dauthentification)
- 12. [Session & localStorage](#session--localstorage)
- 13. [OnboardingModal](#onboardingmodal)
- 14. [useTokenHealthCheck](#usetokenhealthcheck)
- 15. [Sécurité](#sécurité)
- 16. [Exports](#exports)
- 17. [Publication & Installation npm](#publication--installation-npm)
+ 5. [Props des composants individuels](#props-des-composants-individuels)
+ 6. [Gestion des conflits d'inscription](#gestion-des-conflits-dinscription)
+ 7. [Hook useMobileRegistration](#hook-usemobileregistration)
+ 8. [Backend SaaS — Endpoints requis](#backend-saas--endpoints-requis)
+ 9. [APIs IAM Account (Server-to-Server)](#apis-iam-account-server-to-server)
+ 10. [Avatar par application](#avatar-par-application)
+ 11. [Réponses d'erreur](#réponses-derreur)
+ 12. [Configuration .env Laravel](#configuration-env-laravel)
+ 13. [Migration Laravel](#migration-laravel)
+ 14. [Flux d'authentification](#flux-dauthentification)
+ 15. [Session & localStorage](#session--localstorage)
+ 16. [OnboardingModal](#onboardingmodal)
+ 17. [useTokenHealthCheck](#usetokenhealthcheck)
+ 18. [Sécurité](#sécurité)
+ 19. [Exports](#exports)
+ 20. [Publication & Installation npm](#publication--installation-npm)
 
 ---
 
@@ -414,6 +417,7 @@ function MyCustomAuth() {
         onLoginSuccess={(token, user) => console.log('OK', user)}
         saasApiUrl="https://mon-saas.com/api"
         iamApiUrl="https://identityam.ollaid.com/api"
+        defaultAccountType="user"
       />
     </>
   );
@@ -422,6 +426,170 @@ function MyCustomAuth() {
 
 ---
 
+## Props des composants individuels
+
+### `SignupModal`
+
+| Prop | Type | Requis | Description |
+|------|------|--------|-------------|
+| `open` | `boolean` | ✅ | Contrôle l'ouverture du modal |
+| `onOpenChange` | `(open: boolean) => void` | ✅ | Callback de changement d'état |
+| `onSwitchToLogin` | `() => void` | ✅ | Callback pour basculer vers le login |
+| `onSignupSuccess` | `(token: string, user: UserInfos) => void` | ✅ | Callback après inscription réussie |
+| `saasApiUrl` | `string` | ✅ | URL du backend SaaS |
+| `iamApiUrl` | `string` | ✅ | URL du backend IAM |
+| `defaultAccountType` | `'user' \| 'client'` | ❌ | Hérité de `NativeSSOPage.accountType`. Type de compte à persister dans localStorage. Si non défini, la valeur par défaut est `'user'`. |
+| `onSwitchToLoginWithPhone` | `(phone: string) => void` | ❌ | Callback lors d'un conflit phone +221 — permet de basculer vers `LoginModal` avec le numéro pré-rempli |
+
+### `LoginModal`
+
+| Prop | Type | Requis | Description |
+|------|------|--------|-------------|
+| `open` | `boolean` | ✅ | Contrôle l'ouverture du modal |
+| `onOpenChange` | `(open: boolean) => void` | ✅ | Callback de changement d'état |
+| `onSwitchToSignup` | `() => void` | ✅ | Callback pour basculer vers l'inscription |
+| `onLoginSuccess` | `(token: string, user: UserInfos) => void` | ❌ | Callback après connexion réussie |
+| `saasApiUrl` | `string` | ✅ | URL du backend SaaS |
+| `iamApiUrl` | `string` | ✅ | URL du backend IAM |
+| `loading` | `boolean` | ❌ | État de chargement externe |
+| `showSwitchToSignup` | `boolean` | ❌ | Afficher le lien "Pas de compte ? S'inscrire" (défaut: `true`) |
+| `defaultAccountType` | `'user' \| 'client'` | ❌ | Hérité de `NativeSSOPage.accountType`. Type de compte à persister dans localStorage. Si non défini, la valeur par défaut est `'user'`. |
+| `initialPhone` | `string` | ❌ | Pré-remplit le numéro de téléphone et va directement à l'étape `phone-input`. Utilisé par le hand-off depuis `SignupModal` lors d'un conflit. |
+
+---
+
+## Gestion des conflits d'inscription
+
+Lorsqu'un utilisateur tente de s'inscrire avec un email ou un téléphone déjà associé à un compte existant, le backend retourne un **409 Conflict**. Le `SignupModal` gère automatiquement ce cas avec une vue dédiée (`ConflictView`).
+
+### Comportement automatique
+
+1. L'utilisateur remplit le formulaire d'inscription et soumet
+2. Le backend détecte un conflit (`email_exists` ou `phone_exists`) et retourne un objet `conflict`
+3. Le `SignupModal` affiche la `ConflictView` avec les options disponibles
+
+### Affichage intelligent des identifiants
+
+- **L'identifiant saisi par l'utilisateur** (email ou téléphone) est affiché **en clair** pour confirmer sa saisie
+- **L'identifiant lié au compte existant** (ex: l'email masqué associé à un numéro déjà enregistré) reste **masqué** pour la confidentialité (ex: `j***@gmail.com`)
+
+### Options proposées
+
+Selon le type de conflit et les capacités du compte existant, la vue propose :
+
+| Option | Condition | Action |
+|--------|-----------|--------|
+| Se connecter | `conflict.options.can_login === true` | Bascule vers `LoginModal` via `onSwitchToLogin` |
+| Se connecter par téléphone | Conflit phone + numéro +221 | Bascule vers `LoginModal` avec le numéro pré-rempli via `onSwitchToLoginWithPhone(phone)` |
+| Récupérer par email | `conflict.options.can_recover_by_email === true` | Ouvre le `PasswordRecoveryModal` |
+| Récupérer par SMS | `conflict.options.can_recover_by_sms === true` | Ouvre le `PasswordRecoveryModal` |
+| Modifier les informations | Toujours disponible | Retour au formulaire pour changer l'identifiant |
+
+### Exemple d'intégration avec hand-off téléphone
+
+```tsx
+function AuthPage() {
+  const [showSignup, setShowSignup] = useState(false);
+  const [showLogin, setShowLogin] = useState(false);
+  const [loginPhone, setLoginPhone] = useState<string | undefined>();
+
+  return (
+    <>
+      <SignupModal
+        open={showSignup}
+        onOpenChange={setShowSignup}
+        onSwitchToLogin={() => { setShowSignup(false); setShowLogin(true); }}
+        onSwitchToLoginWithPhone={(phone) => {
+          setLoginPhone(phone);
+          setShowSignup(false);
+          setShowLogin(true);
+        }}
+        onSignupSuccess={(token, user) => navigate('/dashboard')}
+        saasApiUrl="https://mon-saas.com/api"
+        iamApiUrl="https://identityam.ollaid.com/api"
+      />
+
+      <LoginModal
+        open={showLogin}
+        onOpenChange={setShowLogin}
+        onSwitchToSignup={() => { setShowLogin(false); setShowSignup(true); }}
+        initialPhone={loginPhone}
+        saasApiUrl="https://mon-saas.com/api"
+        iamApiUrl="https://identityam.ollaid.com/api"
+      />
+    </>
+  );
+}
+```
+
+### Type `RegistrationConflict`
+
+L'objet retourné par le backend lors d'un conflit :
+
+```typescript
+interface RegistrationConflict {
+  type: 'email' | 'phone';
+  masked_identifier: string;
+  options: {
+    can_login: boolean;
+    can_recover_by_email: boolean;
+    can_recover_by_sms: boolean;
+    masked_email?: string;
+    masked_phone?: string;
+  };
+}
+```
+
+---
+
+## Hook `useMobileRegistration`
+
+Hook React pour gérer le flow d'inscription mobile en 3 étapes : `init` → `verify-otp` → `complete`.
+
+### Import
+
+```tsx
+import { useMobileRegistration } from '@ollaid/native-sso';
+```
+
+### Propriétés retournées
+
+#### État
+
+| Propriété | Type | Description |
+|-----------|------|-------------|
+| `processToken` | `string \| null` | Token de processus d'inscription en cours |
+| `status` | `'idle' \| 'pending_otp' \| 'pending_password' \| 'pending_registration' \| 'completed'` | Étape actuelle du flow |
+| `formData` | `Partial<MobileRegistrationFormData>` | Données du formulaire stockées |
+| `loading` | `boolean` | Indique si une opération est en cours |
+| `error` | `string \| null` | Message d'erreur (français, user-friendly) |
+| `conflict` | `RegistrationConflict \| null` | Objet de conflit si l'identifiant existe déjà |
+| `isCompleted` | `boolean` | `true` si l'inscription est terminée |
+| `hasConflict` | `boolean` | `true` si un conflit est en cours |
+
+#### Type de compte (phone-only)
+
+| Propriété | Type | Description |
+|-----------|------|-------------|
+| `accountType` | `'email' \| 'phone-only'` | Type de compte sélectionné |
+| `setAccountType` | `(type: AccountType) => void` | Change le type de compte |
+| `isPhoneOnly` | `boolean` | `true` si `accountType === 'phone-only'` |
+
+#### Méthodes
+
+| Méthode | Signature | Description |
+|---------|-----------|-------------|
+| `updateFormData` | `(data: Partial<MobileRegistrationFormData>) => void` | Met à jour les données du formulaire |
+| `initRegistration` | `(data) => Promise<{ success, otp_code_dev?, otp_method?, otp_sent_to? }>` | Initialise l'inscription (envoi OTP). Peut retourner un conflit. |
+| `verifyOtp` | `(otpCode: string) => Promise<{ success, completed?, callback_token? }>` | Vérifie le code OTP |
+| `completeRegistration` | `(password: string) => Promise<{ success, callback_token? }>` | Finalise avec mot de passe (type `email`) |
+| `completePhoneOnlyRegistration` | `() => Promise<{ success, callback_token? }>` | Finalise sans mot de passe (type `phone-only`, Sénégal 🇸🇳) |
+| `resendOtp` | `() => Promise<{ success, cooldown?, otp_code_dev? }>` | Renvoie le code OTP |
+| `reset` | `() => void` | Réinitialise tout le hook |
+| `clearError` | `() => void` | Efface l'erreur et le conflit |
+
+---
+
 ## Backend SaaS — Endpoints requis
 
 Le backend SaaS (Laravel) doit exposer **4 endpoints**. Voici les spécifications exactes :
@@ -1883,6 +2051,10 @@ if (config('services.iam.debug')) {
 
 ### Types
 - `UserInfos`, `NativeAuthState`, `NativeAuthStatus`, `NativeCredentials`, etc.
+- `AccountType` — `'email' | 'phone-only'`
+- `MobilePasswordState`, `MobilePasswordStatus` — Types pour la récupération de mot de passe
+- `MobileRegistrationFormData` — Données du formulaire d'inscription
+- `RegistrationConflict` — Objet de conflit d'inscription (type interne, voir [Gestion des conflits](#gestion-des-conflits-dinscription))
 - `LinkPhoneRequest`, `LinkPhoneResponse` — Types pour l'API link-phone
 - `LinkEmailRequest`, `LinkEmailResponse` — Types pour l'API link-email
 - `RefreshUserInfoSingleRequest`, `RefreshUserInfoSingleResponse` — Types pour refresh single

package/dist/components/LoginModal.d.ts

@@ -16,6 +16,8 @@ export interface LoginModalProps {
     showSwitchToSignup?: boolean;
     /** Type de compte par défaut à persister dans localStorage */
     defaultAccountType?: 'user' | 'client';
+    /** Pre-fill phone number and go directly to phone-input step */
+    initialPhone?: string;
 }
-export declare function LoginModal({ open, onOpenChange, onSwitchToSignup, onLoginSuccess, saasApiUrl, iamApiUrl, loading, showSwitchToSignup, defaultAccountType, }: LoginModalProps): import("react/jsx-runtime").JSX.Element;
+export declare function LoginModal({ open, onOpenChange, onSwitchToSignup, onLoginSuccess, saasApiUrl, iamApiUrl, loading, showSwitchToSignup, defaultAccountType, initialPhone, }: LoginModalProps): import("react/jsx-runtime").JSX.Element;
 export default LoginModal;

package/dist/components/PhoneInput.d.ts

@@ -1,5 +1,6 @@
 /**
  * Phone Input component for @ollaid/native-sso
+ * Custom select overlay: dropdown shows ISO code, selected display shows only flag + dialCode
  */
 interface PhoneInputProps {
     value: string;

package/dist/components/SignupModal.d.ts

@@ -14,6 +14,8 @@ export interface SignupModalProps {
     iamApiUrl: string;
     /** Type de compte par défaut à persister dans localStorage */
     defaultAccountType?: 'user' | 'client';
+    /** Called when conflict resolution wants to switch to login with a pre-filled phone */
+    onSwitchToLoginWithPhone?: (phone: string) => void;
 }
-export declare function SignupModal({ open, onOpenChange, onSwitchToLogin, onSignupSuccess, saasApiUrl, iamApiUrl, defaultAccountType }: SignupModalProps): import("react/jsx-runtime").JSX.Element;
+export declare function SignupModal({ open, onOpenChange, onSwitchToLogin, onSignupSuccess, saasApiUrl, iamApiUrl, defaultAccountType, onSwitchToLoginWithPhone }: SignupModalProps): import("react/jsx-runtime").JSX.Element;
 export default SignupModal;

package/dist/components/ui.d.ts

@@ -34,6 +34,16 @@ export declare function DialogContent({ children, className }: {
     children: React.ReactNode;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;
+export declare function DialogBody({ children, className, style }: {
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function DialogFooter({ children, className, style }: {
+    children: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}): import("react/jsx-runtime").JSX.Element;
 export declare function DialogHeader({ children, className, style }: {
     children: React.ReactNode;
     className?: string;

package/dist/hooks/useMobileRegistration.d.ts

@@ -41,7 +41,7 @@ export declare function useMobileRegistration(options?: UseMobileRegistrationOpt
         error_type?: undefined;
     } | {
         success: boolean;
-        error_type: string | undefined;
+        error_type: any;
         otp_code_dev?: undefined;
         otp_method?: undefined;
         otp_sent_to?: undefined;