@applite/duticotac-react 0.0.1

package/README.md

@@ -0,0 +1,628 @@
+# @applite/duticotac-react
+
+Composants React pour integrer les paiements Duticotac dans vos applications. Construit avec Tailwind CSS et compatible avec les tokens Shadcn UI.
+
+Ce package fournit une experience de paiement complete : selection du provider, saisie du numero de telephone, code OTP, suivi en temps reel de la transaction, et affichage du resultat.
+
+---
+
+## Table des matieres
+
+- [Installation](#installation)
+- [Prerequis](#prerequis)
+- [Demarrage rapide](#demarrage-rapide)
+- [Flux de paiement](#flux-de-paiement)
+- [Composants](#composants)
+  - [DuticotacPaymentModal](#duticotacpaymentmodal)
+  - [ProviderSelector](#providerselector)
+  - [PhoneInput](#phoneinput)
+  - [OtpInput](#otpinput)
+  - [TransactionStatus](#transactionstatus)
+- [Utilitaires](#utilitaires)
+- [Integration avec Shadcn UI](#integration-avec-shadcn-ui)
+- [Providers supportes](#providers-supportes)
+- [Validation du telephone](#validation-du-telephone)
+- [Gestion des erreurs](#gestion-des-erreurs)
+- [Comportement du polling](#comportement-du-polling)
+- [API Reference complete](#api-reference-complete)
+- [Exemples avances](#exemples-avances)
+- [Scripts](#scripts)
+
+---
+
+## Installation
+
+```bash
+pnpm add @applite/duticotac @applite/duticotac-react
+```
+
+Les deux packages sont necessaires : `@applite/duticotac` contient le SDK (logique API, types, models) et `@applite/duticotac-react` contient les composants UI.
+
+## Prerequis
+
+- **React** >= 18
+- **Tailwind CSS** configure dans votre projet
+- Les composants utilisent les tokens de couleur Shadcn (`primary`, `muted-foreground`, `border`, `destructive`, etc.). Si vous utilisez Shadcn UI, tout fonctionne directement. Sinon, definissez ces variables CSS dans votre theme Tailwind.
+
+---
+
+## Demarrage rapide
+
+```tsx
+import { useState } from "react";
+import { DuticotacSDK } from "@applite/duticotac";
+import { DuticotacPaymentModal } from "@applite/duticotac-react";
+
+// Creez l'instance SDK une seule fois (en dehors du composant)
+const sdk = new DuticotacSDK({
+  apiKey: "your_api_key",
+  appId: "your_app_id", // optionnel
+});
+
+function CheckoutPage() {
+  const [paymentOpen, setPaymentOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setPaymentOpen(true)}>
+        Acheter — 5 000 FCFA
+      </button>
+
+      <DuticotacPaymentModal
+        open={paymentOpen}
+        onClose={() => setPaymentOpen(false)}
+        sdk={sdk}
+        amount={5000}
+        providers={["OM_CI", "MTN_CI", "MOOV_CI", "WAVE_CI"]}
+        getTransactionId={async () => {
+          // Appelez votre backend pour generer un ID unique
+          const res = await fetch("/api/create-transaction", { method: "POST" });
+          const data = await res.json();
+          return data.transactionId;
+        }}
+        productReference="premium-monthly"
+        name="Jean Dupont"
+        email="jean@example.com"
+        onSuccess={(transaction) => {
+          console.log("Paiement confirme :", transaction);
+          // Rafraichir le solde, rediriger, etc.
+        }}
+      />
+    </>
+  );
+}
+```
+
+---
+
+## Flux de paiement
+
+Le `DuticotacPaymentModal` gere automatiquement les 4 etapes du paiement :
+
+```
+1. FORMULAIRE          2. CONFIRMATION         3. SUCCES / ERREUR
+┌──────────────┐      ┌──────────────┐        ┌──────────────┐
+│ [OM] [MTN]   │      │   Spinner    │        │     [OK]     │
+│ [MOOV] [WAVE]│ ───> │              │ ────>  │   Paiement   │
+│              │      │ Confirmez    │        │   reussi !   │
+│ Tel: 07...   │      │ sur votre    │        │              │
+│ OTP: ____    │      │ telephone... │        │  [Fermer]    │
+│              │      │              │        │              │
+│ [Payer 5000] │      │ 42s...       │        │  — ou —      │
+└──────────────┘      └──────────────┘        │              │
+                                              │     [X]      │
+                                              │   Echec du   │
+                                              │   paiement   │
+                                              │ [Reessayer]  │
+                                              └──────────────┘
+```
+
+**Etape 1 — Formulaire** : L'utilisateur choisit un provider, entre son numero de telephone, et son code OTP (Orange Money uniquement).
+
+**Etape 2 — Confirmation** : Le SDK appelle `mobileMoney.cashout()` puis `transaction.poll()`. Si le provider retourne une `paymentUrl` (Wave), un nouvel onglet s'ouvre. Le polling est intelligent : il pause quand l'onglet est cache et reprend instantanement quand l'utilisateur revient.
+
+**Etape 3 — Resultat** : Succes (avec callback `onSuccess`) ou erreur (avec bouton "Reessayer").
+
+---
+
+## Composants
+
+### `DuticotacPaymentModal`
+
+Le composant principal qui orchestre tout le flux de paiement.
+
+```tsx
+import { DuticotacPaymentModal } from "@applite/duticotac-react";
+```
+
+#### Props
+
+| Prop | Type | Requis | Defaut | Description |
+|------|------|--------|--------|-------------|
+| `open` | `boolean` | Oui | — | Controle la visibilite du modal |
+| `onClose` | `() => void` | Oui | — | Appele quand le modal se ferme |
+| `sdk` | `DuticotacSDK` | Oui | — | Instance du SDK Duticotac |
+| `amount` | `number` | Oui | — | Montant du paiement en FCFA |
+| `getTransactionId` | `() => Promise<string>` | Oui | — | Fonction async retournant un ID de transaction unique |
+| `providers` | `PaymentProvider[]` | Non | `["OM_CI", "MTN_CI", "MOOV_CI", "WAVE_CI"]` | Providers de paiement disponibles |
+| `productReference` | `string` | Non | — | Reference du produit/offre |
+| `onSuccess` | `(tx: TransactionModel) => void` | Non | — | Appele quand le paiement est confirme |
+| `initialPhone` | `string` | Non | `""` | Pre-remplir le numero de telephone |
+| `name` | `string` | Non | `"Duticotac App"` | Nom du client |
+| `email` | `string` | Non | `""` | Email du client |
+| `customerId` | `string` | Non | — | ID du client |
+| `kolaboReference` | `string` | Non | — | Reference Kolabo partenaire |
+| `app` | `CoreApp` | Non | — | Application source (`"XORAIA"`, `"MONSMSPRO"`, `"FREE"`) |
+| `platform` | `PlatformType` | Non | — | Plateforme (`"STORE"`, `"DUTICOTAC"`, etc.) |
+| `title` | `string` | Non | `"Paiement"` | Titre du modal |
+| `successMessage` | `string` | Non | `"Le paiement a ete effectue avec succes."` | Message affiche apres succes |
+| `pollTimeout` | `number` | Non | `90000` | Timeout du polling en ms |
+| `className` | `string` | Non | — | Classes CSS additionnelles |
+| `renderModal` | `(props) => ReactNode` | Non | — | Render prop pour utiliser votre propre modal |
+
+---
+
+### `ProviderSelector`
+
+Grille de selection des providers de paiement avec logos et indicateur de selection.
+
+```tsx
+import { ProviderSelector } from "@applite/duticotac-react";
+
+function MyForm() {
+  const [provider, setProvider] = useState<PaymentProvider>("OM_CI");
+
+  return (
+    <ProviderSelector
+      providers={["OM_CI", "MTN_CI", "MOOV_CI", "WAVE_CI"]}
+      value={provider}
+      onChange={setProvider}
+      disabled={isLoading}
+      className="my-4"
+    />
+  );
+}
+```
+
+#### Props
+
+| Prop | Type | Requis | Description |
+|------|------|--------|-------------|
+| `providers` | `PaymentProvider[]` | Oui | Liste des providers a afficher |
+| `value` | `PaymentProvider` | Oui | Provider actuellement selectionne |
+| `onChange` | `(provider: PaymentProvider) => void` | Oui | Callback de changement |
+| `disabled` | `boolean` | Non | Desactiver la selection |
+| `className` | `string` | Non | Classes CSS additionnelles |
+
+---
+
+### `PhoneInput`
+
+Champ de saisie de numero de telephone avec prefixe `+225` (Cote d'Ivoire).
+
+```tsx
+import { PhoneInput } from "@applite/duticotac-react";
+
+<PhoneInput
+  value={phone}
+  onChange={setPhone}
+  label="Numero de telephone"
+  placeholder="07 01 02 03 04"
+  error={phoneError}
+  disabled={isLoading}
+  autoFocus
+/>
+```
+
+#### Props
+
+| Prop | Type | Requis | Defaut | Description |
+|------|------|--------|--------|-------------|
+| `value` | `string` | Oui | — | Valeur du champ (sans prefixe +225) |
+| `onChange` | `(value: string) => void` | Oui | — | Callback de changement |
+| `label` | `string` | Non | `"Numero de telephone"` | Label du champ |
+| `placeholder` | `string` | Non | `"07 01 02 03 04"` | Placeholder |
+| `error` | `string \| null` | Non | — | Message d'erreur a afficher |
+| `disabled` | `boolean` | Non | — | Desactiver le champ |
+| `autoFocus` | `boolean` | Non | — | Focus automatique |
+| `className` | `string` | Non | — | Classes CSS additionnelles |
+
+---
+
+### `OtpInput`
+
+Saisie de code OTP a 4 chiffres. Utilise pour Orange Money (`OM_CI`). Gere automatiquement le focus entre les champs, le collage, et la navigation au clavier.
+
+```tsx
+import { OtpInput } from "@applite/duticotac-react";
+
+<OtpInput
+  value={otp}
+  onChange={setOtp}
+  length={4}
+  disabled={isLoading}
+/>
+```
+
+#### Props
+
+| Prop | Type | Requis | Defaut | Description |
+|------|------|--------|--------|-------------|
+| `value` | `string` | Oui | — | Code OTP saisi |
+| `onChange` | `(value: string) => void` | Oui | — | Callback de changement |
+| `length` | `number` | Non | `4` | Nombre de chiffres |
+| `disabled` | `boolean` | Non | — | Desactiver la saisie |
+| `className` | `string` | Non | — | Classes CSS additionnelles |
+
+**Fonctionnalites :**
+- Auto-focus vers le champ suivant apres saisie d'un chiffre
+- Retour au champ precedent sur Backspace
+- Navigation avec les fleches gauche/droite
+- Support du copier-coller (colle automatiquement les 4 chiffres)
+- Instruction integree : "Faites **#144*82#** pour recevoir le code"
+
+---
+
+### `TransactionStatus`
+
+Affiche l'etat de la transaction : spinner de polling, succes, ou erreur. Utilise en interne par `DuticotacPaymentModal`, mais peut etre utilise independamment.
+
+```tsx
+import { TransactionStatus } from "@applite/duticotac-react";
+
+// Polling en cours
+<TransactionStatus
+  status="polling"
+  elapsedSeconds={42}
+  paymentUrl="https://wave.com/pay/..."
+  onOpenPaymentUrl={() => window.open(url, "_blank")}
+  onClose={handleClose}
+/>
+
+// Succes
+<TransactionStatus
+  status="success"
+  message="500 credits ajoutes a votre compte."
+  onClose={handleClose}
+/>
+
+// Erreur
+<TransactionStatus
+  status="error"
+  errorMessage="Le delai de confirmation a expire."
+  onRetry={handleRetry}
+  onClose={handleClose}
+/>
+```
+
+#### Props
+
+| Prop | Type | Requis | Description |
+|------|------|--------|-------------|
+| `status` | `"polling" \| "success" \| "error"` | Oui | Etat actuel |
+| `elapsedSeconds` | `number` | Non | Secondes ecoulees (affiche pendant le polling) |
+| `message` | `string` | Non | Message de succes |
+| `errorMessage` | `string` | Non | Message d'erreur |
+| `paymentUrl` | `string \| null` | Non | URL de paiement externe (Wave) |
+| `onRetry` | `() => void` | Non | Callback du bouton "Reessayer" |
+| `onClose` | `() => void` | Non | Callback du bouton "Fermer" |
+| `onOpenPaymentUrl` | `() => void` | Non | Callback pour ouvrir l'URL de paiement |
+| `className` | `string` | Non | Classes CSS additionnelles |
+
+---
+
+## Utilitaires
+
+### Validation du telephone
+
+```ts
+import { validatePhone, normalizePhone, getPhoneRegex, needsOtp } from "@applite/duticotac-react";
+
+// Valider un numero pour un provider specifique
+const error = validatePhone("0701020304", "OM_CI");
+// null si valide, message d'erreur sinon
+
+// Normaliser en format international
+normalizePhone("0701020304"); // "+2250701020304"
+
+// Obtenir la regex de validation
+getPhoneRegex("OM_CI");  // /^(\+225)(07)[0-9]{8}$/
+getPhoneRegex("MTN_CI"); // /^(\+225)(05)[0-9]{8}$/
+getPhoneRegex("MOOV_CI");// /^(\+225)(01)[0-9]{8}$/
+
+// Verifier si l'OTP est requis
+needsOtp("OM_CI");   // true
+needsOtp("MTN_CI");  // false
+needsOtp("WAVE_CI"); // false
+```
+
+### Formatage
+
+```ts
+import { formatCFA } from "@applite/duticotac-react";
+
+formatCFA(5000);    // "5 000"
+formatCFA(1500000); // "1 500 000"
+```
+
+### Classes CSS
+
+```ts
+import { cn } from "@applite/duticotac-react";
+
+cn("px-4 py-2", isActive && "bg-primary", className);
+// Merge intelligent des classes Tailwind (via clsx + tailwind-merge)
+```
+
+---
+
+## Integration avec Shadcn UI
+
+### Avec Shadcn Dialog
+
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { DuticotacPaymentModal } from "@applite/duticotac-react";
+
+<DuticotacPaymentModal
+  open={open}
+  onClose={() => setOpen(false)}
+  sdk={sdk}
+  amount={5000}
+  getTransactionId={getTransactionId}
+  renderModal={({ open, onClose, title, children }) => (
+    <Dialog open={open} onOpenChange={(v) => { if (!v) onClose(); }}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+        </DialogHeader>
+        {children}
+      </DialogContent>
+    </Dialog>
+  )}
+/>
+```
+
+### Avec Shadcn Drawer (mobile)
+
+```tsx
+import { Drawer, DrawerContent, DrawerHeader, DrawerTitle } from "@/components/ui/drawer";
+
+<DuticotacPaymentModal
+  open={open}
+  onClose={() => setOpen(false)}
+  sdk={sdk}
+  amount={5000}
+  getTransactionId={getTransactionId}
+  renderModal={({ open, onClose, title, children }) => (
+    <Drawer open={open} onOpenChange={(v) => { if (!v) onClose(); }}>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>{title}</DrawerTitle>
+        </DrawerHeader>
+        <div className="px-4 pb-6">{children}</div>
+      </DrawerContent>
+    </Drawer>
+  )}
+/>
+```
+
+### Sans Shadcn (modal integre)
+
+Si vous ne passez pas de `renderModal`, un modal overlay simple est utilise automatiquement. Aucune dependance externe requise.
+
+---
+
+## Providers supportes
+
+| Code | Nom | OTP requis | Prefixe telephone | Particularite |
+|------|-----|------------|-------------------|---------------|
+| `OM_CI` | Orange Money | Oui (4 chiffres) | `07` | L'utilisateur fait `#144*82#` pour obtenir le code OTP |
+| `MTN_CI` | MTN MoMo | Non | `05` | Confirmation sur le telephone |
+| `MOOV_CI` | Moov (Flooz) | Non | `01` | Confirmation sur le telephone |
+| `WAVE_CI` | Wave | Non | `07`, `05`, `01` | Ouvre un onglet navigateur pour le paiement |
+| `CREDIT_CARD` | Carte de credit | Non | — | A venir |
+| `CASH` | Especes | Non | — | Paiement en main propre |
+| `IAP` | Achat Integre | Non | — | In-App Purchase (mobile) |
+
+---
+
+## Validation du telephone
+
+Chaque provider a des regles de validation specifiques basees sur les prefixes telephoniques de Cote d'Ivoire :
+
+| Provider | Regex | Exemples valides |
+|----------|-------|------------------|
+| Orange Money (`OM_CI`) | `+225 07 XX XX XX XX` | +225 07 01 02 03 04 |
+| MTN (`MTN_CI`) | `+225 05 XX XX XX XX` | +225 05 01 02 03 04 |
+| Moov (`MOOV_CI`) | `+225 01 XX XX XX XX` | +225 01 01 02 03 04 |
+| Wave (`WAVE_CI`) | `+225 (07\|05\|01) XX XX XX XX` | Accepte tous les prefixes |
+
+---
+
+## Gestion des erreurs
+
+Le modal gere automatiquement les erreurs du SDK et affiche des messages en francais :
+
+| Code erreur | Message affiche |
+|-------------|-----------------|
+| `otp-required` | Code OTP requis pour les paiements Orange Money |
+| `ref-or-idFromClient-required` | Reference ou IDFromClient requis |
+| `payment-failed` | Echec du paiement |
+| `payment-cancelled` | Paiement annule |
+| `polling-timeout` | Temps d'attente de la transaction expire |
+| `phone-required` | Numero de telephone requis |
+| `no-api-key` | Cle API non fournie |
+| `app-not-found` | Application non trouvee dans AppLite UI |
+| `unknown-error` | Une erreur inconnue est survenue |
+
+En cas d'erreur, l'utilisateur peut cliquer sur **"Reessayer"** pour revenir au formulaire.
+
+---
+
+## Comportement du polling
+
+Apres l'appel `cashout`, le composant suit le statut de la transaction via `sdk.transaction.poll()` :
+
+- **Backoff exponentiel** : 1s → 2s → 3s → 5s → 8s (meme strategie que le SDK Dart)
+- **Timeout** : 90 secondes par defaut (configurable via `pollTimeout`)
+- **Tab-aware** : Le polling pause quand l'onglet est cache (utilisateur sur Wave ou sur son telephone) et reprend immediatement quand l'onglet redevient visible
+- **Compteur** : Un indicateur "Verification en cours... 42s" est affiche
+- **Wave** : Si le provider retourne une `paymentUrl`, un nouvel onglet s'ouvre automatiquement avec un bouton de fallback si le popup est bloque
+- **Etats terminaux** :
+  - `CONFIRMED` → ecran de succes + callback `onSuccess`
+  - `CANCELLED` → ecran d'erreur ("Paiement annule")
+  - `FAILED` → ecran d'erreur ("Echec du paiement")
+
+---
+
+## API Reference complete
+
+### Types reimportes de `@applite/duticotac`
+
+```ts
+import type {
+  PaymentProvider,    // "OM_CI" | "MTN_CI" | "MOOV_CI" | "WAVE_CI" | "CREDIT_CARD" | "CASH" | "IAP"
+  PlatformType,       // "STORE" | "TRANSPORT" | "RESTAURATION" | "MULTI_SERVICE" | "E_LEARNING" | "DUTICOTAC"
+  CoreApp,            // "XORAIA" | "MONSMSPRO" | "FREE"
+  TransactionModel,   // Objet transaction complet
+  TransactionStatus,  // "PENDING" | "CONFIRMED" | "CANCELLED" | "FAILED"
+} from "@applite/duticotac";
+```
+
+### Exports de `@applite/duticotac-react`
+
+```ts
+// Composants
+export { DuticotacPaymentModal } from "@applite/duticotac-react";
+export { ProviderSelector } from "@applite/duticotac-react";
+export { PhoneInput } from "@applite/duticotac-react";
+export { OtpInput } from "@applite/duticotac-react";
+export { TransactionStatus } from "@applite/duticotac-react";
+
+// Types des props
+export type { DuticotacPaymentModalProps } from "@applite/duticotac-react";
+export type { ProviderSelectorProps } from "@applite/duticotac-react";
+export type { PhoneInputProps } from "@applite/duticotac-react";
+export type { OtpInputProps } from "@applite/duticotac-react";
+export type { TransactionStatusProps } from "@applite/duticotac-react";
+
+// Utilitaires
+export { cn, formatCFA, validatePhone, normalizePhone, getPhoneRegex, needsOtp } from "@applite/duticotac-react";
+```
+
+---
+
+## Exemples avances
+
+### Avec un backend personnalise
+
+```tsx
+function PaymentPage({ offer, apiKey }: { offer: Offer; apiKey: string }) {
+  const [open, setOpen] = useState(false);
+  const sdk = useMemo(() => new DuticotacSDK({ apiKey }), [apiKey]);
+
+  const getTransactionId = async () => {
+    const res = await fetch("/api/payments/init", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ offerId: offer.id }),
+    });
+    const { transactionId } = await res.json();
+    return transactionId;
+  };
+
+  return (
+    <DuticotacPaymentModal
+      open={open}
+      onClose={() => setOpen(false)}
+      sdk={sdk}
+      amount={offer.price}
+      getTransactionId={getTransactionId}
+      productReference={offer.ref}
+      providers={["OM_CI", "MTN_CI", "WAVE_CI"]}
+      pollTimeout={120_000}
+      onSuccess={(tx) => {
+        toast.success(`Paiement confirme ! Ref: ${tx.ref}`);
+        router.push("/dashboard");
+      }}
+    />
+  );
+}
+```
+
+### Composants individuels (sans le modal)
+
+Vous pouvez utiliser les composants independamment pour construire votre propre flux :
+
+```tsx
+import {
+  ProviderSelector,
+  PhoneInput,
+  OtpInput,
+  TransactionStatus,
+  needsOtp,
+  validatePhone,
+} from "@applite/duticotac-react";
+
+function CustomPaymentForm() {
+  const [provider, setProvider] = useState<PaymentProvider>("OM_CI");
+  const [phone, setPhone] = useState("");
+  const [otp, setOtp] = useState("");
+
+  return (
+    <form>
+      <ProviderSelector
+        providers={["OM_CI", "MTN_CI", "WAVE_CI"]}
+        value={provider}
+        onChange={(p) => {
+          setProvider(p);
+          if (!needsOtp(p)) setOtp("");
+        }}
+      />
+
+      <PhoneInput
+        value={phone}
+        onChange={setPhone}
+        error={validatePhone(phone, provider)}
+      />
+
+      {needsOtp(provider) && (
+        <OtpInput value={otp} onChange={setOtp} />
+      )}
+
+      <button type="submit">Payer</button>
+    </form>
+  );
+}
+```
+
+### Personnalisation du style
+
+Tous les composants acceptent une prop `className` pour ajouter des classes Tailwind :
+
+```tsx
+<ProviderSelector
+  providers={providers}
+  value={selected}
+  onChange={setSelected}
+  className="gap-4 grid-cols-2" // Override la grille
+/>
+
+<PhoneInput
+  value={phone}
+  onChange={setPhone}
+  className="mb-6" // Espacement custom
+/>
+```
+
+---
+
+## Scripts
+
+| Commande | Description |
+|----------|-------------|
+| `pnpm build` | Build CJS + ESM avec declarations de types |
+| `pnpm dev` | Mode watch pour le developpement |
+| `pnpm type-check` | Verification des types TypeScript |
+| `pnpm lint` | Lint du code source |