@applite/duticotac 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # @applite/duticotac
 
-A lightweight JavaScript SDK for interacting with Duticotac platform APIs.
+SDK JavaScript/TypeScript pour intégrer les paiements Duticotac (mobile money, offres, transactions).
 
 ## Installation
 
@@ -8,148 +8,169 @@ A lightweight JavaScript SDK for interacting with Duticotac platform APIs.
 pnpm add @applite/duticotac
 ```
 
-## Usage
-
-Each method accepts a **single object** that always includes `apiKey`, plus fields required by the specific route.
-
-### Instantiate the client
+## Démarrage rapide
 
 ```ts
 import { DuticotacSDK } from "@applite/duticotac";
 
 const duticotac = new DuticotacSDK({
-  baseUrl: "https://api.example.com", // optional, defaults to relative paths
+  apiKey: "your_api_key",
+  appId: "your_app_id", // optionnel
 });
 ```
 
-### Get balance
+Le SDK se connecte par défaut à `https://api.applite.freddydro.dev`. Vous pouvez passer un `baseUrl` personnalisé si nécessaire.
+
+## Modules
+
+### Balance
 
 ```ts
-await duticotac.balance.balance({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-});
+const { data: balance } = await duticotac.balance.balance();
 ```
 
-### Manage offers
+### Offres
 
 ```ts
-// Create an offer
+// Créer une offre
 await duticotac.offer.create({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-  name: "Offer Name",
-  ref: "offer-ref",
-  price: 1000,
+  name: "Forfait Premium",
+  ref: "premium-monthly",
+  price: 5000,
   platform: "DUTICOTAC",
-  type: "STATIC", // optional
-  description: "Offer description", // optional
+  type: "STATIC",
+  description: "Accès premium mensuel",
 });
 
-// List offers
-await duticotac.offer.list({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-});
+// Lister les offres
+const { data: offers } = await duticotac.offer.list();
 
-// Get offer by reference
-await duticotac.offer.get({
-  apiKey: "api_key_abc",
-  ref: "offer-ref",
-  appId: "app_123", // optional
-});
+// Récupérer une offre
+const { data: offer } = await duticotac.offer.get({ ref: "premium-monthly" });
 
-// Update offer
-await duticotac.offer.update({
-  apiKey: "api_key_abc",
-  ref: "offer-ref",
-  appId: "app_123", // optional
-  name: "Updated Name", // optional
-  price: 1500, // optional
-});
+// Modifier une offre
+await duticotac.offer.update({ ref: "premium-monthly", price: 7500 });
 
-// Delete offer
-await duticotac.offer.delete({
-  apiKey: "api_key_abc",
-  ref: "offer-ref",
-  appId: "app_123", // optional
-});
+// Supprimer une offre
+await duticotac.offer.delete({ ref: "premium-monthly" });
 ```
 
-### Mobile money operations
+### Paiements Mobile Money
 
 ```ts
-// Cash in
+// Encaissement (cash in)
 await duticotac.mobileMoney.cashin({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-  amount: 1000,
+  amount: 5000,
   phone: "+2250700000000",
   paymentMethod: "OM_CI",
   password: "password123",
 });
 
-// Cash out
+// Décaissement (cash out)
 await duticotac.mobileMoney.cashout({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
   transactionId: "txn_123",
   ref: "ref_123",
   phone: "+2250700000000",
-  name: "John Doe",
-  email: "john@example.com",
+  name: "Jean Dupont",
+  email: "jean@example.com",
   paymentMethod: "OM_CI",
-  amount: 1000, // optional
-  otp: "1234", // optional
+  otp: "1234", // requis pour Orange Money
 });
 ```
 
-### Payment methods
+**Providers supportés :** `OM_CI` (Orange Money), `MTN_CI`, `MOOV_CI`, `WAVE_CI`, `CREDIT_CARD`, `CASH`, `IAP`
+
+### Transactions
 
 ```ts
-// Get payment methods
-await duticotac.paymentMethod.get({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
+// Récupérer le statut d'une transaction
+const { data: tx } = await duticotac.transaction.get({ id: "transaction_id" });
+
+// Polling avec backoff exponentiel (idéal pour paiements asynchrones)
+const { data: confirmed } = await duticotac.transaction.poll("transaction_id", {
+  intervalMs: 2000,   // intervalle minimum (défaut: 2s)
+  timeoutMs: 90_000,  // timeout global (défaut: 90s)
+  onPoll: (attempt, elapsed) => {
+    console.log(`Tentative ${attempt} (${elapsed}ms)`);
+  },
+  signal: abortController.signal, // annulation externe
 });
+```
+
+Le polling utilise un backoff exponentiel (1s → 2s → 3s → 5s → 8s) et se termine quand la transaction passe en `CONFIRMED`, `CANCELLED` ou `FAILED`.
+
+### Méthodes de paiement
+
+```ts
+// Récupérer les méthodes configurées
+const { data: methods } = await duticotac.paymentMethod.get();
 
-// Set payment methods
+// Configurer les méthodes
 await duticotac.paymentMethod.set({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-  providers: ["OM_CI", "MTN_CI"],
+  providers: ["OM_CI", "MTN_CI", "WAVE_CI"],
 });
 ```
 
 ### Webhooks
 
 ```ts
-// Get webhook URL
-await duticotac.webhook.get({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-});
+// Récupérer l'URL du webhook
+const { data: url } = await duticotac.webhook.get();
 
-// Set webhook URL
-await duticotac.webhook.set({
-  apiKey: "api_key_abc",
-  appId: "app_123", // optional
-  url: "https://example.com/webhook",
-});
+// Configurer l'URL
+await duticotac.webhook.set({ url: "https://example.com/webhook" });
 ```
 
-### Transactions
+## Types exportés
 
 ```ts
-// Get transaction
-await duticotac.transaction.get({
-  id: "transaction_id",
-});
+import type {
+  // Enums
+  TransactionStatus,  // "PENDING" | "CONFIRMED" | "CANCELLED" | "FAILED"
+  PlatformType,       // "STORE" | "TRANSPORT" | "RESTAURATION" | ...
+  PaymentProvider,    // "OM_CI" | "MTN_CI" | "MOOV_CI" | "WAVE_CI" | ...
+  Currency,           // "USD" | "EUR" | "XOF" | "XAF"
+  CoreApp,            // "XORAIA" | "MONSMSPRO" | "FREE"
+  DuTicOTacOfferType, // "STATIC" | "DYNAMIC"
+
+  // Modèles
+  TransactionModel,
+  OfferModel,
+  OfferAppModel,
+  DuticotacSettingModel,
+  PaymentLinksCountModel,
+} from "@applite/duticotac";
 ```
 
-## Scripts
+## Gestion des erreurs
 
-- `pnpm build` – build CJS/ESM bundles with type declarations.
-- `pnpm dev` – watch mode for development.
-- `pnpm test` – run the build with declaration output to validate types.
+Le SDK lève des `DuticotacError` avec un `code` correspondant aux erreurs de l'API :
+
+```ts
+import { DuticotacError } from "@applite/duticotac";
+
+try {
+  await duticotac.mobileMoney.cashout({ ... });
+} catch (e) {
+  if (e instanceof DuticotacError) {
+    console.log(e.code);    // ex: "otp-required"
+    console.log(e.message); // ex: "Code OTP requis pour les paiements Orange Money"
+  }
+}
+```
+
+## Utilitaires
+
+```ts
+import {
+  getProviderName,  // "OM_CI" → "Orange Money"
+  getProviderLogo,  // "OM_CI" → URL du logo
+  getErrorMessage,  // "otp-required" → message en français
+  ERROR_MESSAGES,   // map code → message
+} from "@applite/duticotac";
+```
+
+## Scripts
 
+- `pnpm build` – build CJS/ESM avec déclarations de types
+- `pnpm dev` – mode watch pour le développement

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applite/duticotac",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,4 +30,3 @@
     "access": "public"
   }
 }
-