@sanghosdk/js 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,2559 @@
+/**
+ * Vérifie la signature HMAC-SHA256 d'un événement webhook Sangho.
+ *
+ * @example
+ * ```typescript
+ * // `constructEvent` est une méthode statique de `Sangho`, pas une méthode
+ * // d'instance sur `sangho.webhooks` — pas besoin d'avoir instancié le client.
+ * const event = await Sangho.constructEvent(
+ *   rawBody,
+ *   request.headers['sangho-signature'],
+ *   'whsec_xxxxx'
+ * )
+ * ```
+ */
+declare function constructEvent<T = unknown>(payload: string | Uint8Array, signature: string, secret: string, tolerance?: number): Promise<{
+    id: string;
+    type: string;
+    created: number;
+    data: T;
+}>;
+
+interface ListParams {
+    /** Numéro de page (défaut : 1) */
+    page?: number;
+    /** Nombre d'éléments par page (défaut : 20, max : 100) */
+    page_size?: number;
+    /** Tri ex: "-created_at" (préfixe - pour DESC) */
+    ordering?: string;
+    /** Recherche full-text */
+    search?: string;
+}
+interface ListResponse<T> {
+    count: number;
+    next: string | null;
+    previous: string | null;
+    data: T[];
+}
+interface Timestamps {
+    created_at: string;
+    updated_at: string;
+}
+/** Montant monétaire exprimé en centimes (integer). Ex: 5000 = 50.00 XAF */
+type AmountInCents = number;
+/**
+ * Codes ISO 4217 actifs acceptés au niveau du *type* par le SDK.
+ *
+ * Important : cette liste ne représente que la validité ISO 4217 générale,
+ * PAS ce qu'un marchand donné a le droit d'utiliser. Sangho facture/entitle
+ * les devises par plan — un marchand ne peut utiliser à l'exécution que le
+ * sous-ensemble de devises inclus dans son plan (ou activé en backoffice).
+ * Utiliser une devise valide ISO 4217 mais hors plan est un problème
+ * *runtime*, tranché par le backend, qui répond avec une `SanghoError` dont
+ * `.code` vaut `CURRENCY_NOT_IN_PLAN` (ou `INVALID_CURRENCY` si le code
+ * n'est même pas un ISO 4217 reconnu) — voir `core/errors.ts`. Le SDK ne
+ * peut pas connaître statiquement le plan d'un marchand donné : il n'essaie
+ * donc pas d'imposer cette restriction au niveau des types, seulement la
+ * validité ISO 4217 elle-même.
+ */
+declare const ISO_4217_CURRENCIES: readonly ["AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLE", "SOS", "SRD", "SSP", "STN", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL"];
+/**
+ * Devise ISO 4217 valide (union dérivée de `ISO_4217_CURRENCIES` — source
+ * de vérité unique). Ne préjuge pas de ce qu'un marchand a le droit
+ * d'utiliser : voir la note sur `ISO_4217_CURRENCIES` ci-dessus.
+ */
+type CurrencyCode = (typeof ISO_4217_CURRENCIES)[number];
+/** Dictionnaire clé/valeur libre, max 50 clés, valeurs string. */
+type Metadata = Record<string, string>;
+interface Address {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postal_code?: string;
+    country: string;
+}
+interface SanghoOptions {
+    /** Override URL de base (utile pour tests/staging) */
+    baseURL?: string;
+    /** Timeout en ms (défaut : 30 000) */
+    timeout?: number;
+    /** Nombre de retries auto (défaut : 3) */
+    maxRetries?: number;
+}
+/**
+ * A utility type for creating class property interfaces that don't overwrite
+ * actual implementation values when used as type definitions
+ */
+type InterfaceOnly<T> = {
+    [P in keyof T]?: T[P];
+};
+interface DRFOptions {
+    name: string;
+    description: string;
+    renders: string[];
+    parses: string[];
+    actions?: Record<string, unknown>;
+}
+type ForeignKey = string | number | null;
+
+type AppMode = "test" | "prod";
+type AppEnvironment = "sandbox" | "live";
+interface AppCriteria {
+    is_active?: boolean;
+    name?: string;
+    environment?: AppEnvironment;
+    mode?: AppMode;
+    [key: string]: string | number | boolean;
+}
+interface AppKey {
+    id: string;
+    value: string;
+    name: string;
+    is_active: boolean;
+    created_at: string;
+}
+interface AppKeys {
+    pk: AppKey;
+    sk: AppKey;
+}
+interface App extends Timestamps {
+    id: string;
+    object: "app";
+    name: string;
+    description?: string | null;
+    logo?: string | null;
+    mode: AppMode;
+    environment: AppEnvironment;
+    currency: string;
+    is_active: boolean;
+    is_verified: boolean;
+    allowed_hosts: string[];
+    allowed_ips: string[];
+    company?: ForeignKey;
+}
+interface Payloads$9 {
+    name?: string;
+    description?: string;
+    logo?: File | string;
+    allowed_hosts?: string[];
+    allowed_ips?: string[];
+    is_active?: boolean;
+}
+
+type AccountProperties = {
+    /**
+     * Retourne l'application liée à la clé secrète courante.
+     * Nécessite une clé secrète (`sk_prod_*` ou `sk_test_*`).
+     *
+     * @example
+     * const app = await sangho.account.retrieve()
+     * console.log(app.id, app.mode)
+     */
+    retrieve(): Promise<App>;
+};
+
+type AppsProperties = {
+    /**
+     * Liste toutes les applications de l'owner authentifié.
+     * Si `criteria` est fourni, filtre les apps par les champs indiqués
+     * (transmis en query params). Sans critères, retourne tout.
+     *
+     * @param criteria - Filtres optionnels ex: `{ is_active: true, mode: "prod" }`
+     * @returns Tableau des apps correspondant aux critères
+     *
+     * @example
+     * const all  = await sangho.apps.list()
+     * const prod = await sangho.apps.list({ mode: "prod", is_active: true })
+     */
+    list(criteria?: AppCriteria): Promise<App[]>;
+    /**
+     * Récupère une application par son identifiant.
+     *
+     * @param id - Identifiant de l'application (ex: `"app_xxx"`)
+     * @returns Les données de l'application
+     *
+     * @example
+     * const app = await sangho.apps.retrieve("app_xxx")
+     * console.log(app.mode) // "test" | "prod"
+     */
+    retrieve(id: string): Promise<App>;
+    /**
+     * Crée une nouvelle application.
+     * Si une app portant le même `name` existe déjà pour cet owner,
+     * le backend la retourne telle quelle (idempotent, HTTP 200).
+     *
+     * @param payloads - Champs de création (`name` recommandé)
+     * @returns L'application créée (HTTP 201) ou existante (HTTP 200)
+     *
+     * @example
+     * const app = await sangho.apps.create({ name: "Mon App" })
+     */
+    create(payloads: Payloads$9): Promise<App>;
+    /**
+     * Met à jour les paramètres de l'application (mise à jour partielle).
+     * La modification est propagée en sandbox et en live automatiquement.
+     *
+     * @param id      - Identifiant de l'application
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns L'application mise à jour
+     *
+     * @example
+     * const app = await sangho.apps.update("app_xxx", {
+     *   name: "Mon App v2",
+     *   allowed_hosts: ["mon-site.com"],
+     * })
+     */
+    update(id: string, payloads: Payloads$9): Promise<App>;
+    /**
+     * Suppression douce (soft-delete) de l'application.
+     * L'app est marquée `is_ready_to_delete` et purgée définitivement
+     * après un délai configuré côté backend.
+     *
+     * @param id - Identifiant de l'application
+     *
+     * @example
+     * await sangho.apps.delete("app_xxx")
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Récupère les clés publique et secrète de l'application.
+     * Les valeurs retournées sont partiellement obfusquées
+     * (13 caractères visibles, reste masqué).
+     *
+     * @param id - Identifiant de l'application
+     * @returns `{ pk: AppKey, sk: AppKey }`
+     *
+     * @example
+     * const { pk, sk } = await sangho.apps.keys("app_xxx")
+     * console.log(pk.value) // "apk_live_xxxxx..."
+     */
+    keys(id: string): Promise<AppKeys>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/apps/` :
+     * actions autorisées, schéma de champs, formats acceptés.
+     * N'exige pas d'authentification (découverte de schéma).
+     */
+    options(): Promise<DRFOptions>;
+};
+
+type AddressType = "main" | "branch" | "billing" | "shipping";
+interface CompanyAddress extends Timestamps {
+    id: string;
+    object: "address";
+    company: string;
+    type: AddressType;
+    line1: string;
+    line2?: string | null;
+    neighborhood?: string | null;
+    city: string;
+    state?: string | null;
+    province?: string | null;
+    postal_code: string;
+    country: string;
+    is_active: boolean;
+    full_address: string;
+}
+/** Champs requis à la création — alignés sur CreateAddressSerializer */
+interface CreatePayloads$9 {
+    type?: AddressType;
+    line1: string;
+    line2?: string;
+    neighborhood?: string;
+    city: string;
+    state?: string;
+    province?: string;
+    postal_code: string;
+    country: string;
+}
+/** Champs PATCH — tous optionnels, alignés sur AddressSerializer */
+interface Payloads$8 {
+    type?: AddressType;
+    line1?: string;
+    line2?: string;
+    neighborhood?: string;
+    city?: string;
+    state?: string;
+    province?: string;
+    postal_code?: string;
+    country?: string;
+    is_active?: boolean;
+}
+/** Filtres GET /addresses/ — alignés sur get_queryset() */
+interface AddressCriteria {
+    type?: AddressType;
+    is_active?: boolean;
+}
+
+type AddressesProperties = {
+    /**
+     * Liste toutes les adresses de l'entreprise liée à l'app.
+     * Filtre par `type` et/ou `is_active` si `criteria` est fourni,
+     * sinon retourne toutes les adresses.
+     *
+     * @param criteria - Filtres optionnels (type, is_active)
+     * @returns Tableau des adresses correspondantes
+     *
+     * @example
+     * const all     = await sangho.addresses.list()
+     * const billing = await sangho.addresses.list({ type: "billing" })
+     * const active  = await sangho.addresses.list({ is_active: true })
+     */
+    list(criteria?: AddressCriteria): Promise<CompanyAddress[]>;
+    /**
+     * Récupère une adresse par son identifiant.
+     *
+     * @param id - Identifiant de l'adresse
+     * @returns L'adresse correspondante
+     *
+     * @example
+     * const addr = await sangho.addresses.retrieve("123")
+     */
+    retrieve(id: string): Promise<CompanyAddress>;
+    /**
+     * Crée une nouvelle adresse pour l'entreprise liée à l'app.
+     * Si `type` vaut `"main"`, les autres adresses principales
+     * sont automatiquement reclassées en `"branch"` (backend).
+     *
+     * @param payloads - `line1`, `city`, `postal_code`, `country` requis
+     * @returns L'adresse créée
+     *
+     * @example
+     * const addr = await sangho.addresses.create({
+     *   type: "billing",
+     *   line1: "123 Avenue Léon MBA",
+     *   city: "Libreville",
+     *   postal_code: "00000",
+     *   country: "GA",
+     * })
+     */
+    create(payloads: CreatePayloads$9): Promise<CompanyAddress>;
+    /**
+     * Met à jour partiellement une adresse (PATCH).
+     * L'adresse principale (`type: "main"`) ne peut pas être désactivée
+     * via `delete` — mais ses autres champs restent modifiables ici.
+     *
+     * @param id      - Identifiant de l'adresse
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns L'adresse mise à jour
+     *
+     * @example
+     * await sangho.addresses.update("123", { city: "Port-Gentil" })
+     */
+    update(id: string, payloads: Payloads$8): Promise<CompanyAddress>;
+    /**
+     * Désactive une adresse (soft delete — `is_active: false`).
+     * Le backend retourne HTTP 204 sans corps.
+     * L'adresse principale (`type: "main"`) ne peut pas être supprimée.
+     *
+     * @param id - Identifiant de l'adresse
+     *
+     * @example
+     * await sangho.addresses.delete("123")
+     */
+    delete(id: string): Promise<void>;
+    /**
+      * Retourne les métadonnées DRF du endpoint `/addresses/` :
+      * actions autorisées, schéma de champs, formats acceptés.
+      * N'exige pas d'authentification (découverte de schéma).
+      */
+    options(): Promise<DRFOptions>;
+};
+
+type PaymentIntentStatus = "requires_payment_method" | "requires_confirmation" | "requires_action" | "pending" | "processing" | "requires_capture" | "canceled" | "succeeded";
+type CancellationReason = "duplicate" | "fraudulent" | "requested_by_customer" | "abandoned";
+/**
+ * Représente un PaymentIntent Sangho.
+ * Préfixe d'identifiant : `pi_xxx`
+ * Expand disponibles : `?expand=customer`, `?expand=payment_link`
+ */
+interface PaymentIntent extends Timestamps {
+    id: string;
+    object: "payment_intent";
+    reference: string;
+    customer_email?: string | null;
+    customer?: object | null;
+    currency: CurrencyCode;
+    amount: number;
+    status: PaymentIntentStatus;
+    description?: string | null;
+    payment_method?: string | null;
+    payment_method_types: string[];
+    category?: string | null;
+    url?: string | null;
+    payment_link?: string | null;
+    cancellation_reason?: string | null;
+    receipt_email?: string | null;
+    expires_at?: string | null;
+    metadata: Metadata;
+}
+/** Champs POST — alignés sur PaymentIntentSerializer + perform_create() */
+interface CreatePayloads$8 {
+    amount: AmountInCents;
+    currency: CurrencyCode;
+    customer?: string;
+    description?: string;
+    payment_method?: string;
+    payment_method_types?: string[];
+    category?: string;
+    receipt_email?: string;
+    metadata?: Metadata;
+    /**
+     * Si `true`, le PaymentIntent passe immédiatement en `"processing"`
+     * après création (géré via `metadata._confirm_on_create` backend).
+     */
+    confirm?: boolean;
+}
+/** Champs PATCH — tous optionnels */
+interface Payloads$7 {
+    amount?: AmountInCents;
+    currency?: CurrencyCode;
+    customer?: string;
+    description?: string;
+    payment_method?: string;
+    payment_method_types?: string[];
+    receipt_email?: string;
+    metadata?: Metadata;
+}
+/** Paramètres POST /payment-intents/:id/confirm/ */
+interface ConfirmPayloads {
+    payment_method?: string;
+}
+/** Paramètres POST /payment-intents/:id/capture/ */
+interface CapturePayloads {
+    /** Montant à capturer en centimes (≤ montant original) */
+    amount_to_capture?: AmountInCents;
+}
+/** Paramètres POST /payment-intents/:id/cancel/ */
+interface CancelPayloads {
+    cancellation_reason?: CancellationReason;
+}
+/** Filtres GET /payment-intents/ — alignés sur get_queryset() */
+interface PaymentIntentCriteria extends ListParams {
+    status?: PaymentIntentStatus;
+    currency?: CurrencyCode;
+    customer?: string;
+    created_after?: string;
+    created_before?: string;
+}
+
+type PaymentIntentsProperties = {
+    /**
+     * Liste les PaymentIntents avec filtres et pagination.
+     *
+     * @param criteria - Filtres optionnels (status, currency, customer, dates, pagination)
+     * @returns Liste paginée de PaymentIntents
+     *
+     * @example
+     * const all       = await sangho.paymentIntents.list()
+     * const succeeded = await sangho.paymentIntents.list({ status: "succeeded" })
+     * const byEmail   = await sangho.paymentIntents.list({ customer: "jean@example.com" })
+     */
+    list(criteria?: PaymentIntentCriteria): Promise<ListResponse<PaymentIntent>>;
+    /**
+     * Récupère un PaymentIntent par son identifiant.
+     * Ajouter `?expand=customer` ou `?expand=payment_link` pour les objets complets.
+     *
+     * @param id - Identifiant du PaymentIntent (format `pi_xxx`)
+     * @returns Le PaymentIntent correspondant
+     *
+     * @example
+     * const intent = await sangho.paymentIntents.retrieve("pi_xxx")
+     */
+    retrieve(id: string): Promise<PaymentIntent>;
+    /**
+     * Crée un nouveau PaymentIntent.
+     * Statut initial : `"requires_payment_method"`.
+     * Si `confirm: true`, passe immédiatement en `"processing"`.
+     *
+     * @param payloads - `amount` et `currency` requis
+     * @returns Le PaymentIntent créé
+     *
+     * @example
+     * const intent = await sangho.paymentIntents.create({
+     *   amount: 5000,
+     *   currency: "XAF",
+     *   description: "Commande #42",
+     * })
+     */
+    create(payloads: CreatePayloads$8): Promise<PaymentIntent>;
+    /**
+     * Met à jour un PaymentIntent avant sa confirmation (PATCH).
+     *
+     * @param id      - Identifiant du PaymentIntent (format `pi_xxx`)
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns Le PaymentIntent mis à jour
+     *
+     * @example
+     * await sangho.paymentIntents.update("pi_xxx", {
+     *   description: "Nouvelle description",
+     *   metadata: { order_id: "42" },
+     * })
+     */
+    update(id: string, payloads: Payloads$7): Promise<PaymentIntent>;
+    /**
+     * Annule un PaymentIntent via DELETE (alias de `cancel()`).
+     * Retourne le PaymentIntent avec `status: "canceled"` (HTTP 200).
+     * Ne fonctionne pas sur les statuts `"canceled"` ou `"succeeded"`.
+     *
+     * @param id - Identifiant du PaymentIntent (format `pi_xxx`)
+     * @returns Le PaymentIntent annulé
+     *
+     * @example
+     * const canceled = await sangho.paymentIntents.delete("pi_xxx")
+     */
+    delete(id: string): Promise<PaymentIntent>;
+    /**
+     * Confirme un PaymentIntent pour déclencher le paiement.
+     * Statuts acceptés : `"requires_payment_method"`, `"requires_confirmation"`.
+     * Passe en `"processing"` après confirmation.
+     *
+     * @param id      - Identifiant du PaymentIntent (format `pi_xxx`)
+     * @param payloads - Mode de paiement optionnel
+     * @returns Le PaymentIntent confirmé
+     *
+     * @example
+     * const intent = await sangho.paymentIntents.confirm("pi_xxx", {
+     *   payment_method: "meth_xxx",
+     * })
+     */
+    confirm(id: string, payloads?: ConfirmPayloads): Promise<PaymentIntent>;
+    /**
+     * Capture un PaymentIntent en mode de capture manuelle.
+     * Nécessite `status: "requires_capture"`.
+     * Passe en `"succeeded"` après capture.
+     *
+     * @param id      - Identifiant du PaymentIntent (format `pi_xxx`)
+     * @param payloads - Montant à capturer (≤ montant original, optionnel)
+     * @returns Le PaymentIntent capturé
+     *
+     * @example
+     * await sangho.paymentIntents.capture("pi_xxx", { amount_to_capture: 3000 })
+     */
+    capture(id: string, payloads?: CapturePayloads): Promise<PaymentIntent>;
+    /**
+     * Annule explicitement un PaymentIntent.
+     * Impossible si `status` vaut `"canceled"` ou `"succeeded"`.
+     *
+     * @param id      - Identifiant du PaymentIntent (format `pi_xxx`)
+     * @param payloads - Raison d'annulation (défaut: `"requested_by_customer"`)
+     * @returns Le PaymentIntent annulé avec `status: "canceled"`
+     *
+     * @example
+     * await sangho.paymentIntents.cancel("pi_xxx", {
+     *   cancellation_reason: "duplicate",
+     * })
+     */
+    cancel(id: string, payloads?: CancelPayloads): Promise<PaymentIntent>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/payment-intents/` :
+     * actions autorisées, schéma de champs, formats acceptés.
+     */
+    options(): Promise<DRFOptions>;
+};
+
+type CustomerStatus = "active" | "inactive" | "blocked";
+interface Customer extends Timestamps {
+    id: string;
+    object: "customer";
+    app: string;
+    email: string;
+    name: string;
+    phone?: string | null;
+    address?: Address | null;
+    status: CustomerStatus;
+    is_blacklisted: boolean;
+    transactions_count: number;
+    total_spent: number;
+    metadata: Record<string, unknown>;
+}
+/** Champs requis à la création */
+interface CreatePayloads$7 {
+    email: string;
+    name: string;
+    phone?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Champs PATCH — tous optionnels */
+interface Payloads$6 {
+    email?: string;
+    name?: string;
+    phone?: string;
+    status?: CustomerStatus;
+    metadata?: Record<string, unknown>;
+}
+/** Filtres GET /customers/ — alignés sur get_queryset() */
+interface CustomerCriteria {
+    search?: string;
+    status?: CustomerStatus;
+    ordering?: string;
+    page?: number;
+    page_size?: number;
+}
+/** Filtres GET /customers/:id/transactions/ */
+interface TransactionCriteria$1 {
+    page?: number;
+    page_size?: number;
+    ordering?: string;
+}
+
+type TransactionStatus = "approved" | "pending" | "completed" | "failed" | "refunded" | "disputed" | "canceled" | "cancelled";
+type TransactionType = "deposit" | "refund" | "payout" | "withdraw" | "transfer";
+/**
+ * Représente une transaction Sangho.
+ * Préfixe d'identifiant : `trans_xxx`
+ * Création impossible via API — résultat d'un PaymentIntent.
+ */
+interface Transaction extends Timestamps {
+    id: string;
+    object: "transaction";
+    amount: number;
+    fee: number;
+    commission: number;
+    commission_rate: number;
+    currency: "XAF";
+    status: TransactionStatus;
+    type: TransactionType;
+    description?: string | null;
+    payment_intent: string;
+    expiration_date?: string | null;
+    processed_at?: string | null;
+    metadata: Metadata;
+}
+/** Champs PATCH — uniquement description + metadata */
+interface Payloads$5 {
+    description?: string;
+    metadata?: Metadata;
+}
+/** Filtres GET /transactions/ — alignés sur get_queryset() */
+interface TransactionCriteria extends ListParams {
+    status?: TransactionStatus;
+    type?: TransactionType;
+    created_after?: string;
+    created_before?: string;
+    min_amount?: number;
+    max_amount?: number;
+}
+
+type PaymentMethodType$1 = "mobile_money" | "bank_card" | "paypal";
+type MobileMoneyProvider = "orange" | "mtn" | "wave" | "airtel" | "moovv";
+type CardBrand = "visa" | "mastercard" | "amex" | "discover" | "jcb" | "unionpay" | "local" | "unknown";
+interface MobileMoneyDetails {
+    provider: MobileMoneyProvider;
+    phone_masked: string;
+    country: string;
+}
+interface BankCardDetails {
+    brand: CardBrand;
+    last4: string;
+    exp_month: number;
+    exp_year: number;
+    cardholder_name?: string;
+    funding: "credit" | "debit" | "prepaid" | "unknown";
+    country?: string;
+}
+interface PayPalDetails {
+    payer_id?: string;
+}
+/** Représente un mode de paiement Sangho. Préfixe : `meth_xxx` */
+interface PaymentMethod extends Timestamps {
+    id: string;
+    object: "payment_method";
+    app: string;
+    customer?: string | null;
+    type: PaymentMethodType$1;
+    is_default: boolean;
+    mobile_money?: MobileMoneyDetails | null;
+    bank_card?: BankCardDetails | null;
+    paypal?: PayPalDetails | null;
+    metadata: Metadata;
+}
+interface AttachPayloads {
+    customer: string;
+}
+/** Filtres GET /payment-methods/ */
+interface PaymentMethodCriteria extends ListParams {
+    customer?: string;
+    type?: PaymentMethodType$1;
+}
+
+type CustomersProperties = {
+    /**
+     * Liste les clients de l'app avec filtres optionnels.
+     * Recherche sur email, prénom et nom via `search`.
+     *
+     * @param criteria - Filtres optionnels (search, status, ordering, pagination)
+     * @returns Liste paginée de clients
+     *
+     * @example
+     * const all    = await sangho.customers.list()
+     * const active = await sangho.customers.list({ status: "active" })
+     * const search = await sangho.customers.list({ search: "jean" })
+     */
+    list(criteria?: CustomerCriteria): Promise<ListResponse<Customer>>;
+    /**
+     * Récupère un client par son identifiant.
+     *
+     * @param id - Identifiant du client (ex: `"cust_xxx"`)
+     * @returns Le client correspondant
+     *
+     * @example
+     * const customer = await sangho.customers.retrieve("cust_xxx")
+     */
+    retrieve(id: string): Promise<Customer>;
+    /**
+     * Crée un nouveau client lié à l'app.
+     * Le champ `name` est automatiquement éclaté en `firstname`
+     * et `lastname` côté backend.
+     *
+     * @param payloads - `email` et `name` requis
+     * @returns Le client créé
+     *
+     * @example
+     * const customer = await sangho.customers.create({
+     *   email: "jean@example.com",
+     *   name: "Jean Ondo",
+     * })
+     */
+    create(payloads: CreatePayloads$7): Promise<Customer>;
+    /**
+     * Met à jour partiellement un client (PATCH).
+     *
+     * @param id      - Identifiant du client
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns Le client mis à jour
+     *
+     * @example
+     * await sangho.customers.update("cust_xxx", { phone: "+24177000000" })
+     */
+    update(id: string, payloads: Payloads$6): Promise<Customer>;
+    /**
+     * Supprime définitivement un client (hard delete).
+     * Le backend retourne HTTP 204 sans corps.
+     *
+     * @param id - Identifiant du client
+     *
+     * @example
+     * await sangho.customers.delete("cust_xxx")
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Liste les transactions associées à un client.
+     *
+     * @param id       - Identifiant du client
+     * @param criteria - Filtres de pagination optionnels
+     * @returns Liste paginée de transactions
+     *
+     * @example
+     * const txs = await sangho.customers.listTransactions("cust_xxx")
+     *
+     * @remarks Nécessite que l'action `GET /customers/:id/transactions/`
+     * soit déclarée côté backend (`@action` sur `CustomerViewSet`).
+     */
+    listTransactions(id: string, criteria?: TransactionCriteria$1): Promise<ListResponse<Transaction>>;
+    /**
+     * Liste les modes de paiement enregistrés d'un client.
+     *
+     * @param id - Identifiant du client
+     * @returns Liste des modes de paiement
+     *
+     * @example
+     * const methods = await sangho.customers.listPaymentMethods("cust_xxx")
+     *
+     * @remarks Nécessite que l'action `GET /customers/:id/payment-methods/`
+     * soit déclarée côté backend (`@action` sur `CustomerViewSet`).
+     */
+    listPaymentMethods(id: string): Promise<ListResponse<PaymentMethod>>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/customers/` :
+     * actions autorisées, schéma de champs, formats acceptés.
+     */
+    options(): Promise<DRFOptions>;
+};
+
+type ProductStatus = "active" | "inactive" | "draft" | "archived";
+/**
+ * Mappe `product_format` Django → type SDK via `get_type()`.
+ * `"physical"` et `"service"` sont les seuls choices Django natifs.
+ * `"digital"` est supporté par le mapping mais absent des choices.
+ */
+type ProductType = "physical" | "digital" | "service";
+/**
+ * Image d'un produit — mappée depuis `ProductImageSerializer`.
+ * Pas de timestamps (absents des `Meta.fields`).
+ */
+interface ProductImage {
+    id: string;
+    product: string;
+    url: string;
+    alt?: string;
+    position: number;
+    is_primary: boolean;
+}
+/**
+ * Représente un produit Sangho.
+ * Préfixe d'identifiant : `prod_xxx`
+ */
+interface Product extends Timestamps {
+    id: string;
+    object: "product";
+    app: string;
+    name: string;
+    description?: string | null;
+    type: ProductType;
+    status: ProductStatus;
+    unit_amount: number;
+    currency: CurrencyCode;
+    stock?: number | null;
+    sku?: string | null;
+    is_shippable: boolean;
+    images: ProductImage[];
+    metadata: Metadata;
+}
+/** Champs POST — `name`, `unit_amount`, `currency` requis */
+interface CreatePayloads$6 {
+    name: string;
+    description?: string;
+    type?: ProductType;
+    unit_amount: number;
+    currency: CurrencyCode;
+    stock?: number;
+    sku?: string;
+    is_shippable?: boolean;
+    metadata?: Metadata;
+}
+/** Champs PATCH — tous optionnels */
+interface Payloads$4 {
+    name?: string;
+    description?: string;
+    type?: ProductType;
+    unit_amount?: number;
+    stock?: number;
+    sku?: string;
+    status?: ProductStatus;
+    is_shippable?: boolean;
+    metadata?: Metadata;
+}
+/** Filtres GET /products/ — alignés sur get_queryset() */
+interface ProductCriteria extends ListParams {
+    status?: ProductStatus;
+    currency?: CurrencyCode;
+}
+
+type ProductsProperties = {
+    /**
+     * Liste les produits du catalogue avec filtres optionnels.
+     * Accessible avec clé publique ou secrète.
+     *
+     * @param criteria - Filtres (status, currency, search, ordering, pagination)
+     * @returns Liste paginée de produits
+     *
+     * @example
+     * const all    = await sangho.products.list()
+     * const active = await sangho.products.list({ status: "active" })
+     * const search = await sangho.products.list({ search: "premium" })
+     */
+    list(criteria?: ProductCriteria): Promise<ListResponse<Product>>;
+    /**
+     * Récupère un produit par son identifiant.
+     * Accessible avec clé publique ou secrète.
+     *
+     * @param id - Identifiant du produit (format `prod_xxx`)
+     * @returns Le produit correspondant
+     *
+     * @example
+     * const product = await sangho.products.retrieve("prod_xxx")
+     */
+    retrieve(id: string): Promise<Product>;
+    /**
+     * Crée un nouveau produit dans le catalogue.
+     * Nécessite une clé secrète.
+     *
+     * @param payloads - `name`, `unit_amount` et `currency` requis
+     * @returns Le produit créé
+     *
+     * @example
+     * const product = await sangho.products.create({
+     *   name: "Abonnement Premium",
+     *   unit_amount: 9900,
+     *   currency: "XAF",
+     *   type: "service",
+     * })
+     */
+    create(payloads: CreatePayloads$6): Promise<Product>;
+    /**
+     * Met à jour partiellement un produit (PATCH).
+     * Nécessite une clé secrète.
+     *
+     * @param id      - Identifiant du produit (format `prod_xxx`)
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns Le produit mis à jour
+     *
+     * @example
+     * await sangho.products.update("prod_xxx", { stock: 50 })
+     */
+    update(id: string, payloads: Payloads$4): Promise<Product>;
+    /**
+     * Archive un produit (soft delete — `status: "archived"`).
+     * Le backend retourne HTTP 204 sans corps.
+     * Le produit reste accessible en lecture.
+     * Nécessite une clé secrète.
+     *
+     * @param id - Identifiant du produit (format `prod_xxx`)
+     *
+     * @example
+     * await sangho.products.delete("prod_xxx")
+     *
+     * @remarks
+     * Les actions dédiées `archive()` et `unarchive()` n'existent pas
+     * encore côté backend. Pour restaurer un produit archivé,
+     * utilisez `update(id, { status: "active" })`.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/products/` :
+     * actions autorisées, schéma de champs, formats acceptés.
+     */
+    options(): Promise<DRFOptions>;
+};
+
+type TransactionsProperties = {
+    /**
+     * Liste les transactions avec filtres optionnels.
+     * Les transactions sont créées automatiquement par les PaymentIntents —
+     * elles ne peuvent pas être créées via l'API.
+     *
+     * @param criteria - Filtres (status, type, montants, dates, pagination)
+     */
+    list(criteria?: TransactionCriteria): Promise<ListResponse<Transaction>>;
+    /**
+     * Récupère une transaction par son identifiant.
+     * Ajouter `?expand=payment_intent` pour l'objet complet.
+     *
+     * @param id - Identifiant de la transaction (format `trans_xxx`)
+     */
+    retrieve(id: string): Promise<Transaction>;
+    /**
+     * Met à jour la description ou les métadonnées d'une transaction (PATCH).
+     * Seuls `description` et `metadata` sont modifiables.
+     * Impossible sur les transactions dans un état final.
+     *
+     * @param id      - Identifiant de la transaction
+     * @param payloads - `description` et/ou `metadata`
+     */
+    update(id: string, payloads: Payloads$5): Promise<Transaction>;
+    /**
+     * Annule une transaction en statut `pending` ou `processing`.
+     * Impossible sur les transactions `completed`, `failed`, ou `cancelled`.
+     *
+     * @param id - Identifiant de la transaction (format `trans_xxx`)
+     */
+    cancel(id: string): Promise<Transaction>;
+    /** Retourne les métadonnées DRF du endpoint `/transactions/`. */
+    options(): Promise<DRFOptions>;
+};
+
+type RefundStatus = "pending" | "processing" | "succeeded" | "failed" | "cancelled" | "expired";
+type RefundReason = "duplicate" | "fraudulent" | "customer_request" | "product_issue" | "service_not_rendered";
+/** Représente un remboursement Sangho. Préfixe : `refd_xxx` */
+interface Refund extends Timestamps {
+    id: string;
+    object: "refund";
+    transaction: string;
+    amount: number;
+    currency: "XAF";
+    status: RefundStatus;
+    reason?: RefundReason | null;
+    description?: string | null;
+    failure_reason?: string | null;
+    metadata: Metadata;
+}
+/** Champs POST */
+interface CreatePayloads$5 {
+    transaction: string;
+    amount?: number;
+    reason?: RefundReason;
+    description?: string;
+    metadata?: Metadata;
+}
+/** Filtres GET /refunds/ */
+interface RefundCriteria extends ListParams {
+    transaction?: string;
+    status?: RefundStatus;
+    reason?: RefundReason;
+}
+
+type RefundsProperties = {
+    list(criteria?: RefundCriteria): Promise<ListResponse<Refund>>;
+    retrieve(id: string): Promise<Refund>;
+    /**
+     * Crée un remboursement sur une transaction réussie.
+     * Si `amount` est inférieur au montant original, le remboursement est partiel.
+     * @param payloads - `transaction` requis (ID `trans_xxx`)
+     */
+    create(payloads: CreatePayloads$5): Promise<Refund>;
+    /**
+     * Annule un remboursement en statut `pending`.
+     * Impossible sur les remboursements `succeeded`, `failed` ou `expired`.
+     */
+    cancel(id: string): Promise<Refund>;
+    options(): Promise<DRFOptions>;
+};
+
+type InvoiceStatus = "draft" | "open" | "paid" | "uncollectible" | "void";
+interface InvoiceLineItem {
+    id?: string;
+    description: string;
+    quantity: number;
+    unit_amount: number;
+    amount: number;
+    product?: string;
+    metadata?: Metadata;
+}
+/** Ligne à fournir à la création */
+interface CreateLineItem {
+    description: string;
+    quantity: number;
+    unit_amount: number;
+    product?: string;
+    metadata?: Metadata;
+}
+/**
+ * Représente une facture Sangho.
+ * Préfixe d'identifiant : `inv_xxx`
+ * Devise fixe : XAF
+ */
+interface Invoice extends Timestamps {
+    id: string;
+    object: "invoice";
+    app: string;
+    customer: string;
+    number: string;
+    status: InvoiceStatus;
+    currency: "XAF";
+    subtotal: number;
+    tax: number;
+    tax_rate?: number | null;
+    total: number;
+    amount_paid: number;
+    amount_remaining: number;
+    description?: string | null;
+    footer?: string | null;
+    line_items: InvoiceLineItem[];
+    due_date?: string | null;
+    paid_at?: string | null;
+    voided_at?: string | null;
+    hosted_url?: string | null;
+    pdf_url?: string | null;
+    metadata: Metadata;
+}
+/** Champs POST */
+interface CreatePayloads$4 {
+    customer: string;
+    line_items: CreateLineItem[];
+    description?: string;
+    footer?: string;
+    due_date?: string;
+    tax_rate?: number;
+    metadata?: Metadata;
+    /** Si true, passe immédiatement en `"open"` et envoie par email */
+    send_immediately?: boolean;
+}
+/** Champs PATCH — uniquement sur factures `draft` */
+interface Payloads$3 {
+    description?: string;
+    footer?: string;
+    due_date?: string;
+    tax_rate?: number;
+    metadata?: Metadata;
+}
+/** Filtres GET /invoices/ */
+interface InvoiceCriteria extends ListParams {
+    customer?: string;
+    status?: InvoiceStatus;
+    currency?: string;
+    due_date_before?: string;
+    due_date_after?: string;
+}
+
+type InvoicesProperties = {
+    /**
+     * Liste les factures avec filtres optionnels.
+     *
+     * @param criteria - Filtres (customer, status, currency, due_date, pagination)
+     */
+    list(criteria?: InvoiceCriteria): Promise<ListResponse<Invoice>>;
+    /**
+     * Récupère une facture par son identifiant.
+     *
+     * @param id - Identifiant de la facture (format `inv_xxx`)
+     */
+    retrieve(id: string): Promise<Invoice>;
+    /**
+     * Crée une nouvelle facture en statut `draft`.
+     * Si `send_immediately: true`, passe directement en `open`.
+     *
+     * @param payloads - `customer` et `line_items` requis
+     */
+    create(payloads: CreatePayloads$4): Promise<Invoice>;
+    /**
+     * Met à jour une facture en statut `draft` (PATCH).
+     * Impossible sur les factures `open`, `paid`, `void` ou `uncollectible`.
+     *
+     * @param id      - Identifiant de la facture
+     * @param payloads - Champs modifiables (description, footer, due_date, tax_rate)
+     */
+    update(id: string, payloads: Payloads$3): Promise<Invoice>;
+    /**
+     * Supprime définitivement une facture.
+     * Uniquement possible si `status === "draft"`.
+     * Retourne HTTP 204 sans corps.
+     *
+     * @param id - Identifiant de la facture
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Finalise et envoie une facture draft.
+     * Passe en `status: "open"`.
+     *
+     * @param id - Identifiant de la facture
+     */
+    send(id: string): Promise<Invoice>;
+    /**
+     * Marque une facture ouverte comme payée manuellement.
+     * Passe en `status: "paid"`, peuple `paid_at` et `amount_paid`.
+     *
+     * @param id - Identifiant de la facture
+     */
+    pay(id: string): Promise<Invoice>;
+    /**
+     * Annule une facture ouverte.
+     * Passe en `status: "void"`, peuple `voided_at`.
+     * Impossible sur les factures `paid` ou déjà `void`.
+     *
+     * @param id - Identifiant de la facture
+     */
+    void(id: string): Promise<Invoice>;
+    /**
+     * Marque une facture ouverte comme irrécupérable.
+     * Passe en `status: "uncollectible"`.
+     *
+     * @param id - Identifiant de la facture
+     */
+    markUncollectible(id: string): Promise<Invoice>;
+    /**
+     * Retourne l'URL de téléchargement PDF d'une facture.
+     * L'URL expire après 1 heure.
+     *
+     * @param id - Identifiant de la facture
+     * @returns URL temporaire + date d'expiration ISO 8601
+     */
+    getPdfUrl(id: string): Promise<{
+        url: string;
+        expires_at: string;
+    }>;
+    /** Retourne les métadonnées DRF du endpoint `/invoices/`. */
+    options(): Promise<DRFOptions>;
+};
+
+type PaymentLinkStatus = "active" | "inactive" | "archived";
+type PaymentLinkType = "product" | "custom" | "donation";
+type PaymentLinkValidityType = "unlimited" | "limited" | "one_time";
+interface PaymentLinkRedirectUrl {
+    success?: string;
+    cancel?: string;
+}
+/**
+ * Représente un PaymentLink Sangho.
+ * `products` contient des IDs string par défaut,
+ * ou des objets Product complets si `?expand=products`.
+ */
+interface PaymentLink extends Timestamps {
+    id: string;
+    object: "payment_link";
+    name?: string | null;
+    description?: string | null;
+    url: string;
+    status: PaymentLinkStatus;
+    currency: CurrencyCode;
+    amount: number;
+    full_amount: string;
+    minimum_amount?: number | null;
+    maximum_amount?: number | null;
+    tax_amount?: number | null;
+    discount_amount?: number | null;
+    shipping_amount?: number | null;
+    payment_link_type: PaymentLinkType;
+    validity_type: PaymentLinkValidityType;
+    expires_at?: string | null;
+    max_usage?: number | null;
+    redirect_url: PaymentLinkRedirectUrl;
+    products: string[];
+    product_quantity_settings: Record<string, number>;
+    custom_fields: unknown[];
+    advanced_options: Record<string, unknown>;
+    metadata: Metadata;
+}
+/** Champs POST — alignés sur PaymentLinkSerializer + PaymentLinkValidator */
+interface CreatePayloads$3 {
+    name?: string;
+    description?: string;
+    currency: CurrencyCode;
+    payment_link_type?: PaymentLinkType;
+    products?: string[];
+    product_quantity_settings?: Record<string, number>;
+    amount?: AmountInCents;
+    minimum_amount?: AmountInCents;
+    maximum_amount?: AmountInCents;
+    redirect_url?: PaymentLinkRedirectUrl;
+    max_usage?: number;
+    validity_type?: PaymentLinkValidityType;
+    expires_at?: string;
+    custom_fields?: unknown[];
+    advanced_options?: Record<string, unknown>;
+    metadata?: Metadata;
+}
+/** Champs PATCH — tous optionnels */
+interface Payloads$2 {
+    name?: string;
+    description?: string;
+    currency?: CurrencyCode;
+    products?: string[];
+    product_quantity_settings?: Record<string, number>;
+    amount?: AmountInCents;
+    minimum_amount?: AmountInCents;
+    maximum_amount?: AmountInCents;
+    redirect_url?: PaymentLinkRedirectUrl;
+    max_usage?: number | null;
+    validity_type?: PaymentLinkValidityType;
+    expires_at?: string | null;
+    custom_fields?: unknown[];
+    advanced_options?: Record<string, unknown>;
+    metadata?: Metadata;
+}
+/** Filtres GET /payment-links/ — alignés sur get_queryset() */
+interface PaymentLinkCriteria extends ListParams {
+    status?: PaymentLinkStatus;
+    currency?: CurrencyCode;
+}
+
+type PaymentLinksProperties = {
+    /**
+     * Liste les liens de paiement avec filtres optionnels.
+     *
+     * @param criteria - Filtres (status, currency, search, ordering, pagination)
+     * @returns Liste paginée de liens de paiement
+     *
+     * @example
+     * const all      = await sangho.paymentLinks.list()
+     * const active   = await sangho.paymentLinks.list({ status: "active" })
+     * const search   = await sangho.paymentLinks.list({ search: "promo" })
+     */
+    list(criteria?: PaymentLinkCriteria): Promise<ListResponse<PaymentLink>>;
+    /**
+     * Récupère un lien de paiement par son identifiant.
+     * Ajouter `?expand=products` pour obtenir les objets Product complets.
+     *
+     * @param id - Identifiant du lien (ex: `"link_xxx"`)
+     * @returns Le lien de paiement correspondant
+     *
+     * @example
+     * const link = await sangho.paymentLinks.retrieve("link_xxx")
+     */
+    retrieve(id: string): Promise<PaymentLink>;
+    /**
+     * Crée un nouveau lien de paiement partageable.
+     * Si `payment_link_type` vaut `"product"`, le champ `products` est requis.
+     * Pour les autres types, `amount` et `currency` sont requis.
+     *
+     * @param payloads - Paramètres du lien (currency toujours requis)
+     * @returns Le lien de paiement créé
+     *
+     * @example
+     * const link = await sangho.paymentLinks.create({
+     *   currency: "XAF",
+     *   payment_link_type: "product",
+     *   products: ["prod_xxx"],
+     *   product_quantity_settings: { prod_xxx: 1 },
+     *   redirect_url: { success: "https://monsite.com/merci" },
+     * })
+     * console.log(link.url) // https://pay.sangho.ga/test/...
+     */
+    create(payloads: CreatePayloads$3): Promise<PaymentLink>;
+    /**
+     * Met à jour partiellement un lien de paiement (PATCH).
+     * PUT n'est pas supporté côté backend.
+     *
+     * @param id      - Identifiant du lien
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns Le lien mis à jour
+     *
+     * @example
+     * await sangho.paymentLinks.update("link_xxx", {
+     *   max_usage: 100,
+     *   redirect_url: { success: "https://monsite.com/merci" },
+     * })
+     */
+    update(id: string, payloads: Payloads$2): Promise<PaymentLink>;
+    /**
+     * Archive un lien de paiement (soft delete).
+     * Le backend ne supprime pas physiquement — l'historique est conservé.
+     * Équivalent à `DELETE /payment-links/:id/` côté API.
+     *
+     * @param id - Identifiant du lien
+     * @returns Le lien archivé (status: "archived")
+     *
+     * @example
+     * const archived = await sangho.paymentLinks.delete("link_xxx")
+     */
+    delete(id: string): Promise<PaymentLink>;
+    /**
+     * Archive explicitement un lien via `POST /payment-links/:id/archive/`.
+     * Retourne une erreur si le lien est déjà archivé.
+     *
+     * @param id - Identifiant du lien
+     * @returns Le lien archivé
+     *
+     * @example
+     * await sangho.paymentLinks.archive("link_xxx")
+     */
+    archive(id: string): Promise<PaymentLink>;
+    /**
+     * Restaure un lien archivé (`POST /payment-links/:id/restore/`).
+     * Le lien repasse au statut `"active"`.
+     * Retourne une erreur si le lien n'est pas archivé.
+     *
+     * @param id - Identifiant du lien
+     * @returns Le lien restauré
+     *
+     * @example
+     * await sangho.paymentLinks.restore("link_xxx")
+     */
+    restore(id: string): Promise<PaymentLink>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/payment-links/` :
+     * actions autorisées, schéma de champs, formats acceptés.
+     */
+    options(): Promise<DRFOptions>;
+};
+
+type CheckoutSessionStatus = "open" | "complete" | "expired" | "payment_failed" | "processing";
+type CheckoutMode = "payment" | "subscription" | "setup";
+/** Ligne de commande — type local, découplé de payment-links */
+interface LineItem {
+    product: string;
+    quantity: number;
+    unit_amount?: number;
+    name?: string;
+    currency?: CurrencyCode;
+}
+/**
+ * Représente une CheckoutSession Sangho.
+ * Préfixe d'identifiant : `sess_xxx`
+ */
+interface CheckoutSession extends Timestamps {
+    id: string;
+    object: "checkout_session";
+    app: string;
+    url: string;
+    status: CheckoutSessionStatus;
+    mode: CheckoutMode;
+    customer?: string | null;
+    customer_email?: string | null;
+    currency: CurrencyCode;
+    amount_total: AmountInCents;
+    shipping_amount?: number | null;
+    discount_amount?: number | null;
+    line_items: LineItem[];
+    success_url: string;
+    cancel_url?: string | null;
+    payment_intent?: string | null;
+    subscription?: string | null;
+    expires_at: string;
+    metadata: Metadata;
+}
+/** Champs POST — `success_url`, `line_items`, `currency` requis */
+interface CreatePayloads$2 {
+    success_url: string;
+    line_items: LineItem[];
+    currency: CurrencyCode;
+    mode?: CheckoutMode;
+    customer?: string;
+    customer_email?: string;
+    cancel_url?: string;
+    shipping_amount?: AmountInCents;
+    discount_amount?: AmountInCents;
+    payment_method_types?: string[];
+    /** Durée de validité en secondes (défaut: 1800, max: 86400) */
+    expires_in?: number;
+    metadata?: Metadata;
+}
+/** Filtres GET /checkout-sessions/ */
+interface CheckoutSessionCriteria extends ListParams {
+    status?: CheckoutSessionStatus;
+    mode?: CheckoutMode;
+    customer?: string;
+    created_after?: string;
+    created_before?: string;
+}
+
+type CheckoutSessionsProperties = {
+    /**
+     * Liste les sessions de checkout avec filtres optionnels.
+     *
+     * @param criteria - Filtres (status, mode, customer, dates, pagination)
+     * @returns Liste paginée de sessions
+     *
+     * @example
+     * const all    = await sangho.checkoutSessions.list()
+     * const open   = await sangho.checkoutSessions.list({ status: "open" })
+     * const subs   = await sangho.checkoutSessions.list({ mode: "subscription" })
+     */
+    list(criteria?: CheckoutSessionCriteria): Promise<ListResponse<CheckoutSession>>;
+    /**
+     * Récupère une session de checkout par son identifiant.
+     * Si la session est expirée mais encore marquée `"open"`,
+     * le backend la bascule automatiquement en `"expired"`.
+     * Accessible avec clé publique ou secrète.
+     *
+     * @param id - Identifiant de la session (format `sess_xxx`)
+     */
+    retrieve(id: string): Promise<CheckoutSession>;
+    /**
+     * Crée une session de checkout hébergée.
+     * En mode `"payment"`, un PaymentIntent est automatiquement créé.
+     * `success_url`, `line_items` et `currency` sont requis.
+     *
+     * @param payloads - Paramètres de la session
+     * @returns La session avec son URL de redirection
+     *
+     * @example
+     * const session = await sangho.checkoutSessions.create({
+     *   success_url: "https://monsite.com/merci",
+     *   cancel_url:  "https://monsite.com/annulation",
+     *   currency:    "XAF",
+     *   line_items:  [{ product: "prod_xxx", quantity: 1 }],
+     * })
+     * window.location.href = session.url
+     */
+    create(payloads: CreatePayloads$2): Promise<CheckoutSession>;
+    /**
+     * Expire manuellement une session ouverte
+     * (`POST /checkout-sessions/:id/expire/`).
+     * Retourne une erreur si la session n'est pas en statut `"open"`.
+     * Équivalent à `DELETE /checkout-sessions/:id/`.
+     *
+     * @param id - Identifiant de la session (format `sess_xxx`)
+     * @returns La session expirée
+     *
+     * @example
+     * await sangho.checkoutSessions.expire("sess_xxx")
+     */
+    expire(id: string): Promise<CheckoutSession>;
+    /**
+     * Alias de `expire()` — expire la session au lieu de la supprimer.
+     * Le backend ne supprime pas physiquement les sessions.
+     *
+     * @param id - Identifiant de la session (format `sess_xxx`)
+     */
+    delete(id: string): Promise<CheckoutSession>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/checkout-sessions/`.
+     */
+    options(): Promise<DRFOptions>;
+};
+
+type SubscriptionStatus = "trialing" | "active" | "past_due" | "paused" | "canceled" | "unpaid" | "expired";
+type BillingInterval = "day" | "week" | "month" | "year";
+type CollectionMethod = "charge_automatically" | "send_invoice";
+/**
+ * Représente un abonnement Sangho.
+ * Préfixe d'identifiant : `sub_xxx`
+ */
+interface Subscription extends Timestamps {
+    id: string;
+    object: "subscription";
+    app: string;
+    customer: string;
+    status: SubscriptionStatus;
+    currency: "XAF";
+    unit_amount: number;
+    interval: BillingInterval;
+    interval_count: number;
+    collection_method: CollectionMethod;
+    current_period_start: string;
+    current_period_end: string;
+    trial_start?: string | null;
+    trial_end?: string | null;
+    canceled_at?: string | null;
+    cancel_at_period_end: boolean;
+    product?: string | null;
+    payment_method?: string | null;
+    metadata: Metadata;
+}
+/** Champs POST */
+interface CreatePayloads$1 {
+    customer: string;
+    unit_amount: number;
+    interval: BillingInterval;
+    interval_count?: number;
+    product?: string;
+    payment_method?: string;
+    collection_method?: CollectionMethod;
+    trial_period_days?: number;
+    cancel_at_period_end?: boolean;
+    metadata?: Metadata;
+}
+/** Champs PATCH */
+interface Payloads$1 {
+    unit_amount?: number;
+    payment_method?: string;
+    collection_method?: CollectionMethod;
+    cancel_at_period_end?: boolean;
+    metadata?: Metadata;
+}
+/** Filtres GET /subscriptions/ */
+interface SubscriptionCriteria extends ListParams {
+    customer?: string;
+    status?: SubscriptionStatus;
+    currency?: string;
+}
+
+type SubscriptionsProperties = {
+    list(criteria?: SubscriptionCriteria): Promise<ListResponse<Subscription>>;
+    retrieve(id: string): Promise<Subscription>;
+    /**
+     * Crée un abonnement récurrent.
+     * Si `trial_period_days > 0`, démarre en statut `"trialing"`.
+     * @param payloads - `customer`, `unit_amount` et `interval` requis
+     */
+    create(payloads: CreatePayloads$1): Promise<Subscription>;
+    update(id: string, payloads: Payloads$1): Promise<Subscription>;
+    /**
+     * Annule un abonnement.
+     * `cancel_at_period_end: true` (défaut) → annulation à la fin de la période.
+     * `cancel_at_period_end: false` → annulation immédiate.
+     */
+    cancel(id: string, payloads?: {
+        cancel_at_period_end?: boolean;
+    }): Promise<Subscription>;
+    /** Réactive un abonnement `canceled`, `past_due` ou `unpaid`. */
+    reactivate(id: string): Promise<Subscription>;
+    /** Suspend un abonnement actif (passe en `"paused"`). */
+    pause(id: string): Promise<Subscription>;
+    /** Reprend un abonnement `"paused"`. */
+    resume(id: string): Promise<Subscription>;
+    options(): Promise<DRFOptions>;
+};
+
+type PaymentMethodsProperties = {
+    list(criteria?: PaymentMethodCriteria): Promise<ListResponse<PaymentMethod>>;
+    retrieve(id: string): Promise<PaymentMethod>;
+    /**
+     * Attache un mode de paiement à un client.
+     * @param id      - Identifiant du mode de paiement (`meth_xxx`)
+     * @param payloads - `customer` requis
+     */
+    attach(id: string, payloads: AttachPayloads): Promise<PaymentMethod>;
+    /** Détache un mode de paiement de son client. */
+    detach(id: string): Promise<PaymentMethod>;
+    /** Définit un mode de paiement comme défaut pour son client. */
+    setDefault(id: string): Promise<PaymentMethod>;
+    options(): Promise<DRFOptions>;
+};
+
+type ReceiptStatus = "draft" | "issued" | "voided" | "archived";
+type PaymentMethodType = "card" | "mobile_money" | "bank_transfer" | "e_wallet";
+interface ReceiptItem {
+    id: string;
+    description: string;
+    quantity: number;
+    unit_amount: number;
+    amount: number;
+    currency: "XAF";
+}
+/**
+ * Représente un reçu Sangho.
+ * Préfixe d'identifiant : `rec_xxx`
+ * Devise fixe : XAF — en lecture seule.
+ */
+interface Receipt extends Timestamps {
+    id: string;
+    object: "receipt";
+    app: string;
+    number: string;
+    customer: string;
+    transaction?: string | null;
+    status: ReceiptStatus;
+    payment_method: PaymentMethodType;
+    currency: "XAF";
+    subtotal: number;
+    tax: number;
+    total: number;
+    shipping_amount: number;
+    discount_amount: number;
+    items: ReceiptItem[];
+    pdf_url?: string | null;
+    issue_date: string;
+    metadata: Metadata;
+}
+/** Filtres GET /receipts/ */
+interface ReceiptCriteria extends ListParams {
+    customer?: string;
+    transaction?: string;
+    status?: ReceiptStatus;
+}
+
+type ReceiptsProperties = {
+    /**
+     * Liste les reçus de l'app avec filtres optionnels.
+     *
+     * @param criteria - Filtres (customer, transaction, status, pagination)
+     *
+     * @example
+     * const all  = await sangho.receipts.list()
+     * const paid = await sangho.receipts.list({ status: "issued" })
+     */
+    list(criteria?: ReceiptCriteria): Promise<ListResponse<Receipt>>;
+    /**
+     * Récupère un reçu par son identifiant.
+     *
+     * @param id - Identifiant du reçu (format `rec_xxx`)
+     */
+    retrieve(id: string): Promise<Receipt>;
+    /**
+     * Retourne l'URL de téléchargement PDF du reçu.
+     * L'URL expire après 1 heure.
+     *
+     * @param id - Identifiant du reçu
+     * @returns URL temporaire + date d'expiration ISO 8601
+     *
+     * @example
+     * const { url } = await sangho.receipts.getPdfUrl("rec_xxx")
+     * window.open(url)
+     */
+    getPdfUrl(id: string): Promise<{
+        url: string;
+        expires_at: string;
+    }>;
+    /** Retourne les métadonnées DRF du endpoint `/receipts/`. */
+    options(): Promise<DRFOptions>;
+};
+
+type WebhookEventType = "payment_intent.created" | "payment_intent.succeeded" | "payment_intent.payment_failed" | "payment_intent.canceled" | "payment_intent.requires_action" | "transaction.created" | "transaction.succeeded" | "transaction.failed" | "transaction.refunded" | "customer.created" | "customer.updated" | "customer.deleted" | "invoice.created" | "invoice.paid" | "invoice.payment_failed" | "invoice.voided" | "subscription.created" | "subscription.updated" | "subscription.canceled" | "subscription.trial_ending" | "refund.created" | "refund.updated" | "refund.failed" | "checkout.session.completed" | "checkout.session.expired" | "payout.created" | "payout.paid" | "payout.failed";
+type WebhookStatus = "ACTIVE" | "INACTIVE" | "DISABLED";
+type WebhookSecurityProfile = "HMAC_SHA256" | "JWT" | "BASIC";
+type DeliveryStatus = "pending" | "delivered" | "failed" | "retrying";
+interface WebhookRetryPolicy {
+    max_attempts: number;
+    backoff_type: "linear" | "exponential";
+    initial_delay_seconds: number;
+}
+/** Représente un webhook Sangho. Préfixe : `wh_xxx` */
+interface Webhook extends Timestamps {
+    id: string;
+    object: "webhook";
+    app: string;
+    name: string;
+    url: string;
+    status: WebhookStatus;
+    events: WebhookEventType[];
+    security_profile: WebhookSecurityProfile;
+    secret_preview: string;
+    ssl_verification: boolean;
+    retry_policy: WebhookRetryPolicy;
+    rate_limit: number;
+    timeout: number;
+    failure_count: number;
+    last_delivery_at?: string | null;
+    metadata: Metadata;
+}
+interface WebhookDelivery extends Timestamps {
+    id: string;
+    object: "webhook_delivery";
+    webhook: string;
+    event_type: WebhookEventType | "webhook.test";
+    url: string;
+    status: DeliveryStatus;
+    http_status?: number | null;
+    is_successful: boolean;
+    attempts: number;
+    next_retry_at?: string | null;
+    response_body?: string | null;
+    response_time_ms?: number | null;
+    delivered_at?: string | null;
+    metadata: Metadata;
+}
+/** Champs POST */
+interface CreatePayloads {
+    name: string;
+    url: string;
+    events: WebhookEventType[];
+    security_profile?: WebhookSecurityProfile;
+    ssl_verification?: boolean;
+    retry_policy?: Partial<WebhookRetryPolicy>;
+    rate_limit?: number;
+    timeout?: number;
+    metadata?: Metadata;
+}
+/** Champs PATCH */
+interface Payloads {
+    name?: string;
+    url?: string;
+    events?: WebhookEventType[];
+    status?: WebhookStatus;
+    security_profile?: WebhookSecurityProfile;
+    ssl_verification?: boolean;
+    retry_policy?: Partial<WebhookRetryPolicy>;
+    rate_limit?: number;
+    timeout?: number;
+    metadata?: Metadata;
+}
+/** Filtres GET /webhooks/ */
+interface WebhookCriteria extends ListParams {
+    status?: WebhookStatus;
+}
+/** Filtres GET /webhooks/:id/deliveries/ */
+interface DeliveryCriteria extends ListParams {
+    event_type?: WebhookEventType;
+    status?: DeliveryStatus;
+}
+
+type WebhooksProperties = {
+    list(criteria?: WebhookCriteria): Promise<ListResponse<Webhook>>;
+    retrieve(id: string): Promise<Webhook>;
+    /**
+     * Crée un endpoint webhook.
+     * Le secret de signature est retourné en clair une seule fois dans la réponse.
+     * Stockez-le immédiatement — il ne sera plus accessible ensuite.
+     */
+    create(payloads: CreatePayloads): Promise<Webhook & {
+        secret: string;
+    }>;
+    update(id: string, payloads: Payloads): Promise<Webhook>;
+    /** Supprime un webhook (HTTP 204). */
+    delete(id: string): Promise<void>;
+    /** Désactive un webhook sans le supprimer (passe en `"INACTIVE"`). */
+    disable(id: string): Promise<Webhook>;
+    /** Réactive un webhook désactivé (passe en `"ACTIVE"`). */
+    enable(id: string): Promise<Webhook>;
+    /**
+     * Régénère le secret HMAC du webhook.
+     * L'ancien secret est invalidé immédiatement.
+     * @returns Le nouveau secret en clair (une seule fois)
+     */
+    rollSecret(id: string): Promise<{
+        secret: string;
+    }>;
+    /** Envoie un événement test au webhook pour vérifier la connectivité. */
+    sendTestEvent(id: string): Promise<WebhookDelivery>;
+    listDeliveries(id: string, criteria?: DeliveryCriteria): Promise<ListResponse<WebhookDelivery>>;
+    retrieveDelivery(webhookId: string, deliveryId: string): Promise<WebhookDelivery>;
+    /** Rejoue une livraison échouée. */
+    retryDelivery(webhookId: string, deliveryId: string): Promise<WebhookDelivery>;
+    options(): Promise<DRFOptions>;
+};
+
+interface SecurityProfile extends Timestamps {
+    id: string;
+    app: string;
+    /** IPs autorisées — liste vide = toutes autorisées */
+    allowed_ips: string[];
+    /** Montant max par transaction en centimes */
+    max_transaction_amount?: AmountInCents;
+    /** Montant max par jour en centimes */
+    max_daily_amount?: AmountInCents;
+    /** Nombre max de transactions par heure */
+    max_hourly_transactions?: number;
+    require_cvv: boolean;
+    require_3ds: boolean;
+    block_vpn: boolean;
+    block_tor: boolean;
+    allowed_countries: string[];
+}
+interface UpdateSecurityProfileParams {
+    allowed_ips?: string[];
+    max_transaction_amount?: AmountInCents;
+    max_daily_amount?: AmountInCents;
+    max_hourly_transactions?: number;
+    require_cvv?: boolean;
+    require_3ds?: boolean;
+    block_vpn?: boolean;
+    block_tor?: boolean;
+    allowed_countries?: string[];
+}
+
+type SecurityProperties = {
+    /**
+     * Récupère le profil de sécurité de l'application.
+     *
+     * @example
+     * ```typescript
+     * const profile = await sangho.security.retrieve()
+     * console.log(profile.allowed_ips)
+     * ```
+     */
+    retrieve(): Promise<SecurityProfile>;
+    /** Met à jour les paramètres de sécurité. */
+    update(params: UpdateSecurityProfileParams): Promise<SecurityProfile>;
+    /**
+     * Ajoute des adresses IP à la liste blanche.
+     *
+     * @param ips - Liste d'IPs au format CIDR (ex: `["192.168.1.0/24"]`)
+     */
+    addAllowedIps(ips: string[]): Promise<SecurityProfile>;
+    /** Retire des adresses IP de la liste blanche. */
+    removeAllowedIps(ips: string[]): Promise<SecurityProfile>;
+};
+
+type PartnerStatus = "active" | "inactive";
+type PartnerService = "PAYMENT" | "FRAUD" | "KYC" | "SETTLEMENT";
+/** Représente un partenaire Sangho. Lecture seule. */
+interface Partner extends Timestamps {
+    id: string;
+    object: "partner";
+    name: string;
+    webhook_url: string;
+    services: PartnerService[];
+    status: PartnerStatus;
+    last_used?: string | null;
+}
+/** Filtres GET /partners/ */
+interface PartnerCriteria extends ListParams {
+    status?: PartnerStatus;
+}
+
+type PartnersProperties = {
+    /**
+     * Liste les partenaires actifs de la plateforme.
+     * Lecture seule — les partenaires ne peuvent pas être créés via l'API.
+     */
+    list(criteria?: PartnerCriteria): Promise<ListResponse<Partner>>;
+    /**
+     * Récupère un partenaire par son identifiant.
+     * @param id - Identifiant du partenaire
+     */
+    retrieve(id: string): Promise<Partner>;
+    options(): Promise<DRFOptions>;
+};
+
+type ReaderType = "android" | "firmware" | "virtual";
+type ReaderStatus = "online" | "offline" | "disabled";
+type TerminalSessionStatus = "pending" | "payment_method_presented" | "processing" | "succeeded" | "failed" | "canceled" | "timed_out";
+type TerminalPaymentMethodType = "card" | "mobile_money" | "qr_code";
+type OfflineSyncStatus = "pending" | "syncing" | "synced" | "conflict" | "failed";
+interface TerminalReader extends Timestamps {
+    id: string;
+    object: "terminal_reader";
+    app: string;
+    label: string;
+    serial_number: string;
+    reader_type: ReaderType;
+    location?: string | null;
+    status: ReaderStatus;
+    reader_token: string;
+    reader_token_expires: string;
+    last_seen_at?: string | null;
+    metadata: Metadata;
+}
+interface CreateReaderPayloads {
+    label: string;
+    serial_number: string;
+    reader_type?: ReaderType;
+    location?: string;
+    metadata?: Metadata;
+}
+interface ReaderCriteria extends ListParams {
+    status?: ReaderStatus;
+    reader_type?: ReaderType;
+}
+interface TerminalSession extends Timestamps {
+    id: string;
+    object: "terminal_session";
+    app: string;
+    reader_id: string;
+    payment_intent_id: string | null;
+    amount: number;
+    currency: "XAF";
+    status: TerminalSessionStatus;
+    payment_method_type?: TerminalPaymentMethodType | null;
+    failure_reason?: string | null;
+    processor_ref?: string | null;
+    client_secret: string;
+    expires_at: string;
+    metadata: Metadata;
+}
+interface CreateSessionPayloads {
+    reader: string;
+    amount: number;
+    description?: string;
+    category?: string;
+    metadata?: Metadata;
+}
+interface PresentPaymentPayloads {
+    payment_method_type: TerminalPaymentMethodType;
+    nonce: string;
+}
+interface SessionStatus {
+    id: string;
+    status: TerminalSessionStatus;
+    payment_intent_status: string | null;
+    failure_reason: string | null;
+}
+interface SessionCriteria extends ListParams {
+    status?: TerminalSessionStatus;
+    reader?: string;
+}
+interface OfflineTransactionPayload {
+    local_id: string;
+    amount: number;
+    payment_method_type: TerminalPaymentMethodType;
+    card_token?: string;
+    captured_at: string;
+    reader_id?: string;
+    metadata?: Metadata;
+}
+interface SyncPayloads {
+    transactions: OfflineTransactionPayload[];
+}
+interface SyncResult {
+    local_id: string;
+    sync_status: OfflineSyncStatus;
+    payment_intent?: string | null;
+    error?: string;
+}
+interface SyncResponse {
+    synced: number;
+    results: SyncResult[];
+}
+interface OfflineTransaction extends Timestamps {
+    id: string;
+    object: "offline_transaction";
+    app: string;
+    local_id: string;
+    amount: number;
+    currency: "XAF";
+    payment_method_type: TerminalPaymentMethodType;
+    captured_at: string;
+    sync_status: OfflineSyncStatus;
+    synced_at?: string | null;
+    payment_intent?: string | null;
+    sync_error?: string | null;
+    metadata: Metadata;
+}
+
+type ReadersProperties = {
+    /**
+     * Liste tous les terminaux enregistrés pour l'application authentifiée.
+     * Les résultats sont paginés et filtrables par statut ou type.
+     *
+     * @param criteria - Filtres optionnels
+     * @returns Liste paginée des terminaux
+     *
+     * @example
+     * // Tous les terminaux
+     * const all = await sangho.terminal.readers.list()
+     *
+     * // Seulement les terminaux Android en ligne
+     * const actifs = await sangho.terminal.readers.list({
+     *   reader_type: "android",
+     *   status:      "online",
+     * })
+     */
+    list(criteria?: ReaderCriteria): Promise<ListResponse<TerminalReader>>;
+    /**
+     * Récupère un terminal par son identifiant.
+     *
+     * @param id - Identifiant du terminal (préfixe `rdr_`)
+     * @returns Les données complètes du terminal
+     *
+     * @example
+     * const reader = await sangho.terminal.readers.retrieve("rdr_xxx")
+     * console.log(reader.status)        // "online" | "offline" | "disabled"
+     * console.log(reader.reader_type)   // "android" | "firmware" | "virtual"
+     */
+    retrieve(id: string): Promise<TerminalReader>;
+    /**
+     * Enregistre un nouveau terminal physique ou virtuel.
+     * À appeler **une seule fois** lors du provisionnement du device.
+     * Le `reader_token` retourné doit être stocké dans le keystore sécurisé
+     * de l'appareil (Android Keystore, HSM firmware, etc.).
+     *
+     * @param payloads - Données d'enregistrement
+     * @returns Le terminal créé avec son `reader_token` initial (valide 24h)
+     *
+     * @example
+     * // Provisionnement d'un terminal Android Sunmi T2
+     * const reader = await sangho.terminal.readers.create({
+     *   label:         "Caisse 1 — Libreville",
+     *   serial_number: "SN-SUNMI-T2-001",
+     *   reader_type:   "android",
+     *   location:      "Magasin Owendo, Libreville",
+     *   metadata:      { store_id: "store_owendo" },
+     * })
+     *
+     * // Stocker reader.reader_token dans le keystore Android sécurisé
+     * await secureStorage.set("reader_token", reader.reader_token)
+     */
+    create(payloads: CreateReaderPayloads): Promise<TerminalReader>;
+    /**
+     * Met à jour les informations d'un terminal (mise à jour partielle).
+     * Utile pour changer le label ou déplacer un terminal vers une autre localisation.
+     *
+     * @param id       - Identifiant du terminal
+     * @param payloads - Champs à modifier (tous optionnels)
+     * @returns Le terminal mis à jour
+     *
+     * @example
+     * const reader = await sangho.terminal.readers.update("rdr_xxx", {
+     *   label:    "Caisse 2 — Owendo",
+     *   location: "Magasin Port, Libreville",
+     * })
+     */
+    update(id: string, payloads: Partial<CreateReaderPayloads>): Promise<TerminalReader>;
+    /**
+     * Désactive définitivement un terminal.
+     * Un terminal désactivé ne peut plus créer de sessions ni signaler son heartbeat.
+     * Opération irréversible depuis le SDK — la réactivation se fait via le dashboard.
+     *
+     * @param id - Identifiant du terminal à désactiver
+     * @returns Le terminal avec `status: "disabled"`
+     *
+     * @example
+     * // Terminal volé ou hors service
+     * await sangho.terminal.readers.disable("rdr_xxx")
+     */
+    disable(id: string): Promise<TerminalReader>;
+    /**
+     * Renouvelle le `reader_token` d'un terminal.
+     * Le token a une durée de vie de **24h** ; à appeler automatiquement
+     * au démarrage de l'application POS si `reader_token_expires` est dépassé.
+     *
+     * @param id - Identifiant du terminal
+     * @returns Nouveau `reader_token` et sa date d'expiration `reader_token_expires`
+     *
+     * @example
+     * const { reader_token, reader_token_expires } = await sangho.terminal.readers.refreshToken("rdr_xxx")
+     * await secureStorage.set("reader_token", reader_token)
+     * await secureStorage.set("reader_token_expires", reader_token_expires)
+     */
+    refreshToken(id: string): Promise<{
+        reader_token: string;
+        reader_token_expires: string;
+    }>;
+    /**
+     * Signale que le terminal est actif (keep-alive).
+     * À appeler en tâche de fond **toutes les 30 secondes**.
+     * Met à jour `last_seen_at` et maintient le statut `"online"`.
+     * Un terminal sans heartbeat depuis > 2 min passe automatiquement en `"offline"`.
+     *
+     * @param id - Identifiant du terminal
+     * @returns Statut courant et timestamp de dernière activité
+     *
+     * @example
+     * // Background worker — toutes les 30s
+     * setInterval(async () => {
+     *   const { status, last_seen_at } = await sangho.terminal.readers.heartbeat("rdr_xxx")
+     *   if (status === "offline") reinitialiserConnexion()
+     * }, 30_000)
+     */
+    heartbeat(id: string): Promise<{
+        status: string;
+        last_seen_at: string;
+    }>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/terminal/readers/` :
+     * actions autorisées, schéma de champs, filtres disponibles.
+     */
+    options(): Promise<DRFOptions>;
+};
+type SessionsProperties = {
+    /**
+     * Liste les sessions de paiement terminal.
+     * Filtrables par statut ou par terminal.
+     *
+     * @param criteria - Filtres optionnels
+     * @returns Liste paginée des sessions
+     *
+     * @example
+     * // Sessions en attente sur un terminal donné
+     * const pending = await sangho.terminal.sessions.list({
+     *   reader: "rdr_xxx",
+     *   status: "pending",
+     * })
+     */
+    list(criteria?: SessionCriteria): Promise<ListResponse<TerminalSession>>;
+    /**
+     * Récupère une session de paiement terminal par son identifiant.
+     *
+     * @param id - Identifiant de la session (préfixe `tsess_`)
+     * @returns Les données complètes de la session
+     *
+     * @example
+     * const session = await sangho.terminal.sessions.retrieve("tsess_xxx")
+     * console.log(session.status)   // "pending" | "succeeded" | ...
+     * console.log(session.amount)   // montant en XAF
+     */
+    retrieve(id: string): Promise<TerminalSession>;
+    /**
+     * Crée une nouvelle session de paiement sur un terminal.
+     * Déclenche l'affichage du montant sur l'écran du terminal.
+     * La session expire automatiquement après le délai configuré (`expires_at`).
+     *
+     * @param payloads - Données de la session (reader, amount requis)
+     * @returns La session créée avec son `client_secret` (utilisé par le POS)
+     *
+     * @example
+     * const session = await sangho.terminal.sessions.create({
+     *   reader:      "rdr_xxx",
+     *   amount:      15_000,        // 15 000 XAF
+     *   description: "Vente caisse 1",
+     *   category:    "product",
+     *   metadata:    { order_id: "ORD-2024-001" },
+     * })
+     *
+     * // Afficher le montant sur le terminal
+     * afficherEcran(`Montant : ${session.amount} XAF — Présentez votre carte`)
+     */
+    create(payloads: CreateSessionPayloads): Promise<TerminalSession>;
+    /**
+     * Notifie le backend que le client a présenté un moyen de paiement.
+     * Le `nonce` est fourni par le SDK constructeur du terminal (Sunmi, PAX, Ingenico…)
+     * après lecture NFC/EMV — il ne doit **jamais** contenir le PAN brut.
+     *
+     * Authentification : accepte la `sk_xxx` **ou** le `reader_token` du terminal
+     * (permission `IsTerminalToken` côté backend).
+     *
+     * @param id       - Identifiant de la session
+     * @param payloads - Type de moyen de paiement et nonce constructeur
+     * @returns La session mise à jour (status → `"payment_method_presented"`)
+     *
+     * @example
+     * // Après lecture NFC depuis le SDK Sunmi
+     * const nonce = await sunmiSDK.readNFC()   // ex: "emv_nonce_xxx"
+     *
+     * await sangho.terminal.sessions.presentPaymentMethod("tsess_xxx", {
+     *   payment_method_type: "card",
+     *   nonce,
+     * })
+     *
+     * // Mobile Money (MTN, Airtel)
+     * await sangho.terminal.sessions.presentPaymentMethod("tsess_xxx", {
+     *   payment_method_type: "mobile_money",
+     *   nonce: "mm_nonce_yyy",
+     * })
+     */
+    presentPaymentMethod(id: string, payloads: PresentPaymentPayloads): Promise<TerminalSession>;
+    /**
+     * Interroge le statut courant d'une session (polling léger).
+     * À appeler en boucle (~1,5s d'intervalle) jusqu'à obtenir un statut terminal.
+     *
+     * **Statuts terminaux** : `succeeded` | `failed` | `canceled` | `timed_out`
+     * **Statuts transitoires** : `pending` | `payment_method_presented` | `processing`
+     *
+     * @param id - Identifiant de la session
+     * @returns Statut de la session + statut du PaymentIntent associé
+     *
+     * @example
+     * async function attendreResultat(sessionId: string): Promise<SessionStatus> {
+     *   const debut = Date.now()
+     *   while (Date.now() - debut < 30_000) {
+     *     const s = await sangho.terminal.sessions.pollStatus(sessionId)
+     *     if (["succeeded", "failed", "canceled", "timed_out"].includes(s.status)) {
+     *       return s
+     *     }
+     *     await sleep(1_500)
+     *   }
+     *   await sangho.terminal.sessions.cancel(sessionId)
+     *   throw new Error("Timeout dépassé")
+     * }
+     *
+     * const result = await attendreResultat("tsess_xxx")
+     * if (result.status === "succeeded") imprimerRecu(result)
+     * else afficherEcran(`Refusé : ${result.failure_reason}`)
+     */
+    pollStatus(id: string): Promise<SessionStatus>;
+    /**
+     * Annule une session de paiement en cours.
+     * Seules les sessions en statut `pending` ou `payment_method_presented`
+     * peuvent être annulées. Une session `processing` ou `succeeded` ne peut plus l'être.
+     *
+     * @param id - Identifiant de la session à annuler
+     * @returns La session avec `status: "canceled"`
+     *
+     * @example
+     * // Annulation par le caissier
+     * await sangho.terminal.sessions.cancel("tsess_xxx")
+     * afficherEcran("Paiement annulé")
+     */
+    cancel(id: string): Promise<TerminalSession>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/terminal/sessions/`.
+     */
+    options(): Promise<DRFOptions>;
+};
+type OfflineProperties = {
+    /**
+     * Synchronise un batch de transactions capturées hors-ligne avec le backend.
+     * À appeler dès que la connectivité réseau est rétablie.
+     *
+     * Chaque transaction est identifiée par son `local_id` (généré par le POS).
+     * Le backend retourne le résultat individuel de chaque transaction
+     * (`synced` | `conflict` | `failed`).
+     *
+     * ⚠️  Le `card_token` doit être un token constructeur — **jamais le PAN brut**.
+     *
+     * @param payloads - Tableau des transactions à synchroniser
+     * @returns Nombre de transactions synchronisées + détail par `local_id`
+     *
+     * @example
+     * const queue: OfflineTransactionPayload[] = [
+     *   {
+     *     local_id:             "LOCAL-001",
+     *     amount:               8_500,
+     *     payment_method_type:  "card",
+     *     card_token:           "tok_constructeur_xxx",
+     *     captured_at:          "2024-11-15T10:23:00Z",
+     *     reader_id:            "rdr_xxx",
+     *     metadata:             { order_id: "ORD-001" },
+     *   },
+     * ]
+     *
+     * const result = await sangho.terminal.offline.sync({ transactions: queue })
+     * console.log(`${result.synced} / ${queue.length} synchronisées`)
+     *
+     * result.results
+     *   .filter(r => r.sync_status === "failed")
+     *   .forEach(r => console.error(`Échec ${r.local_id} : ${r.error}`))
+     */
+    sync(payloads: SyncPayloads): Promise<SyncResponse>;
+    /**
+     * Liste les transactions offline enregistrées pour cette application.
+     * Filtrables par `sync_status` pour retrouver les transactions en échec.
+     *
+     * @param criteria - Filtres optionnels (`sync_status`, `page`)
+     * @returns Liste paginée des transactions offline
+     *
+     * @example
+     * // Transactions en conflit à résoudre manuellement
+     * const conflits = await sangho.terminal.offline.list({ sync_status: "conflict" })
+     *
+     * // Toutes les transactions non encore synchronisées
+     * const pending = await sangho.terminal.offline.list({ sync_status: "pending" })
+     */
+    list(criteria?: {
+        sync_status?: string;
+        page?: number;
+    }): Promise<ListResponse<OfflineTransaction>>;
+    /**
+     * Retourne les métadonnées DRF du endpoint `/terminal/offline/sync/`.
+     */
+    options(): Promise<DRFOptions>;
+};
+type TerminalProperties = {
+    /**
+     * Gestion des terminaux physiques (Android, firmware, virtuels).
+     *
+     * Un **terminal** représente un appareil de paiement enregistré :
+     * caisse Android (Sunmi, PAX), firmware embarqué (Ingenico, Verifone),
+     * ou terminal virtuel pour les tests.
+     *
+     * Cycle de vie d'un terminal :
+     * ```
+     * create() → heartbeat() (toutes 30s) → refreshToken() (toutes 24h) → disable()
+     * ```
+     *
+     * @example
+     * // Provisionnement initial
+     * const reader = await sangho.terminal.readers.create({
+     *   label:         "Caisse 1 — Libreville",
+     *   serial_number: "SN-SUNMI-T2-001",
+     *   reader_type:   "android",
+     * })
+     */
+    readers: ReadersProperties;
+    /**
+     * Gestion des sessions de paiement terminal.
+     *
+     * Une **session** représente une tentative de paiement initiée depuis
+     * un terminal physique. Elle orchestre le cycle :
+     * ```
+     * create() → presentPaymentMethod() → pollStatus() → [succeeded | failed | cancel()]
+     * ```
+     *
+     * @example
+     * // Flux complet de paiement terminal
+     * const session = await sangho.terminal.sessions.create({ reader: "rdr_xxx", amount: 15_000 })
+     * await sangho.terminal.sessions.presentPaymentMethod(session.id, { payment_method_type: "card", nonce })
+     * const result = await pollJusquaResultat(session.id)
+     */
+    sessions: SessionsProperties;
+    /**
+     * Synchronisation des transactions capturées hors-ligne.
+     *
+     * Quand la connexion réseau est indisponible (zone blanche, coupure),
+     * le terminal capture les paiements localement puis les synchronise
+     * avec `sync()` dès le retour du réseau.
+     *
+     * ```
+     * [réseau absent] capturer localement → stocker en queue locale
+     * [réseau rétabli] offline.sync({ transactions: queue })
+     * ```
+     *
+     * @example
+     * // Au retour du réseau
+     * const result = await sangho.terminal.offline.sync({ transactions: localQueue })
+     * console.log(`${result.synced} transactions synchronisées`)
+     */
+    offline: OfflineProperties;
+};
+
+/** Résultat de la purge des données sandbox — voir SandboxModule.reset(). */
+interface SandboxResetResult {
+    object: "sandbox.reset";
+    /** Nombre d'enregistrements supprimés par modèle (ex: `{ customer: 12, product: 5 }`) */
+    deleted: Record<string, number>;
+    total_deleted: number;
+    errors: string[];
+}
+
+type SandboxProperties = {
+    /**
+     * Purge toutes les données sandbox de l'application (clé test uniquement).
+     *
+     * @example
+     * await sangho.sandbox.reset()
+     */
+    reset(): Promise<SandboxResetResult>;
+};
+
+type ApiKeyType = "public" | "secret";
+interface HttpClientConfig {
+    baseURL: string;
+    timeout: number;
+    maxRetries: number;
+    sandbox: boolean;
+    apiKey: string;
+}
+declare class HttpClient {
+    readonly keyType: ApiKeyType;
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    assertSecretKey(methodName: string): void;
+    get<T, P extends object = object>(path: string, params?: P): Promise<T>;
+    post<T>(path: string, body: unknown, idempotencyKey?: string): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    delete<T = void>(path: string): Promise<T>;
+    options<T = unknown>(path: string): Promise<T>;
+    private buildURL;
+    private baseHeaders;
+    private request;
+    /**
+     * Détermine si une SanghoError est transitoire et mérite un retry :
+     * 429 (rate limit) ou 5xx (erreur serveur). Jamais les 4xx restants
+     * (400/401/403/404/409/422) — ce sont des erreurs permanentes côté client.
+     */
+    private isRetryable;
+    private handleResponse;
+    private sleep;
+}
+
+/**
+ * Classe de base dont héritent tous les modules Sangho.
+ *
+ * Pattern : composition via injection de `HttpClient`.
+ * Jamais d'héritage multiple — un seul HttpClient partagé par instance Sangho.
+ *
+ * @example
+ * ```typescript
+ * export class CustomersModule extends BaseModule {
+ *   async create(params: CreateCustomerParams): Promise<Customer> {
+ *     this.http.assertSecretKey("customers.create");
+ *     return this.http.post<Customer>("/customers/", params);
+ *   }
+ * }
+ * ```
+ */
+declare class BaseModule {
+    /** Client HTTP partagé — ne jamais exposer publiquement. */
+    protected readonly http: HttpClient;
+    constructor(http: HttpClient);
+}
+
+declare const Sangho_base: {
+    new (...args: any[]): {};
+} & typeof BaseModule;
+/**
+ * Client principal du SDK Sangho.
+ *
+ * @example
+ * ```typescript
+ * // Côté serveur — clé secrète
+ * const sangho = new Sangho("sk_prod_xxx")
+ * const intent = await sangho.paymentIntents.create({ amount: 5000, currency: "XAF" })
+ *
+ * // Côté navigateur — clé publique (checkout uniquement)
+ * const sangho = new Sangho("pk_prod_xxx")
+ * const session = await sangho.checkoutSessions.retrieve("cs_xxx")
+ * ```
+ */
+declare class Sangho extends Sangho_base {
+    readonly account: InterfaceOnly<AccountProperties>;
+    readonly apps: InterfaceOnly<AppsProperties>;
+    readonly addresses: InterfaceOnly<AddressesProperties>;
+    readonly customers: InterfaceOnly<CustomersProperties>;
+    readonly products: InterfaceOnly<ProductsProperties>;
+    readonly paymentIntents: InterfaceOnly<PaymentIntentsProperties>;
+    readonly transactions: InterfaceOnly<TransactionsProperties>;
+    readonly refunds: InterfaceOnly<RefundsProperties>;
+    readonly invoices: InterfaceOnly<InvoicesProperties>;
+    readonly paymentLinks: InterfaceOnly<PaymentLinksProperties>;
+    readonly checkoutSessions: InterfaceOnly<CheckoutSessionsProperties>;
+    readonly subscriptions: InterfaceOnly<SubscriptionsProperties>;
+    readonly paymentMethods: InterfaceOnly<PaymentMethodsProperties>;
+    readonly receipts: InterfaceOnly<ReceiptsProperties>;
+    readonly webhooks: InterfaceOnly<WebhooksProperties>;
+    readonly security: InterfaceOnly<SecurityProperties>;
+    readonly partners: InterfaceOnly<PartnersProperties>;
+    readonly terminal: InterfaceOnly<TerminalProperties>;
+    readonly sandbox: InterfaceOnly<SandboxProperties>;
+    constructor(apiKey: string, options?: SanghoOptions);
+    /**
+     * Vérifie et parse un événement webhook entrant.
+     * Valide la signature HMAC-SHA256 + protection anti-replay (5 min).
+     *
+     * @param payload   - Corps brut de la requête (Buffer ou string)
+     * @param signature - Header `Sangho-Signature` de la requête
+     * @param secret    - Secret du webhook (depuis le dashboard)
+     *
+     * @example
+     * ```typescript
+     * // Express
+     * app.post('/webhooks/sangho', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const event = Sangho.constructEvent(
+     *     req.body,
+     *     req.headers['sangho-signature'],
+     *     process.env.SANGHO_WEBHOOK_SECRET
+     *   )
+     *   if (event.type === 'payment_intent.succeeded') {
+     *     await fulfillOrder(event.data)
+     *   }
+     *   res.json({ received: true })
+     * })
+     * ```
+     */
+    static constructEvent: typeof constructEvent;
+}
+
+/**
+ * Catégorie large de l'erreur (`err.type`).
+ *
+ * Les 7 premières valeurs sont exactement le taxonomie `type` renvoyée par
+ * le backend (cf. `backend/api/exceptions.py`) sur toute réponse HTTP
+ * d'erreur. `NETWORK_ERROR` et `TIMEOUT_ERROR` sont deux catégories
+ * additionnelles, propres au SDK : elles ne correspondent à aucune réponse
+ * HTTP puisque la requête n'a justement jamais abouti côté serveur.
+ */
+type SanghoErrorType = "AUTHENTICATION_ERROR" | "PERMISSION_ERROR" | "NOT_FOUND_ERROR" | "CONFLICT_ERROR" | "VALIDATION_ERROR" | "RATE_LIMIT_ERROR" | "API_ERROR" | "NETWORK_ERROR" | "TIMEOUT_ERROR";
+interface SanghoErrorResponse {
+    message: string;
+    type?: string;
+    code?: string;
+    detail?: string | Record<string, string[]>;
+    errors?: Record<string, string[]>;
+    status?: number;
+    param?: string;
+}
+/**
+ * Classe de base — toutes les erreurs Sangho en héritent.
+ */
+declare class SanghoError extends Error {
+    /**
+     * Catégorie large de l'erreur, une des 9 valeurs `SanghoErrorType`
+     * (`VALIDATION_ERROR`, `RATE_LIMIT_ERROR`, `NETWORK_ERROR`, ...).
+     * Utile pour un `switch`/branchement générique.
+     */
+    readonly type: SanghoErrorType;
+    /**
+     * Code métier précis renvoyé par le backend (`raw.code`), ex :
+     * `AMOUNT_TOO_SMALL`, `INSUFFICIENT_FUNDS`, `CUSTOMER_NOT_FOUND`,
+     * `INVALID_API_KEY`, `CURRENCY_NOT_IN_PLAN`... Le catalogue de codes est
+     * possédé et versionné côté backend et continuera de grandir — c'est
+     * pourquoi ce champ est typé `string` plutôt qu'une union fermée.
+     *
+     * Quand l'erreur n'a jamais atteint le backend (`SanghoNetworkError`,
+     * `SanghoTimeoutError` — pas de corps de réponse à lire), `code` retombe
+     * sur la même valeur que `type`.
+     */
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly raw?: SanghoErrorResponse;
+    constructor(message: string, type?: SanghoErrorType, statusCode?: number, raw?: SanghoErrorResponse);
+}
+/**
+ * 401 — Clé API invalide, expirée ou absente.
+ */
+declare class SanghoAuthError extends SanghoError {
+    constructor(message?: string, raw?: SanghoErrorResponse);
+}
+/**
+ * 403 — Clé publique utilisée pour une opération réservée aux clés secrètes.
+ * Catégorie (`type`) : `PERMISSION_ERROR` — c'est bien un problème de
+ * permission ; `code` reste `PUBLIC_KEY_NOT_ALLOWED` (ou équivalent envoyé
+ * par le backend) pour distinguer précisément ce cas des autres 403.
+ */
+declare class SanghoPublicKeyError extends SanghoError {
+    constructor(message?: string, raw?: SanghoErrorResponse);
+}
+/**
+ * 403 — Permissions insuffisantes.
+ */
+declare class SanghoPermissionError extends SanghoError {
+    constructor(message?: string, raw?: SanghoErrorResponse);
+}
+/**
+ * 404 — Ressource introuvable.
+ */
+declare class SanghoNotFoundError extends SanghoError {
+    constructor(message?: string, raw?: SanghoErrorResponse);
+}
+/**
+ * 422 — Données invalides (erreurs de validation champ par champ).
+ */
+declare class SanghoValidationError extends SanghoError {
+    readonly fieldErrors: Record<string, string[]>;
+    readonly param?: string;
+    constructor(raw: SanghoErrorResponse);
+}
+/**
+ * 429 — Trop de requêtes. `retryAfter` indique le délai (secondes) avant retry.
+ */
+declare class SanghoRateLimitError extends SanghoError {
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number, raw?: SanghoErrorResponse);
+}
+/**
+ * 409 — Clé d'idempotence réutilisée avec un payload différent.
+ * Catégorie (`type`) : `CONFLICT_ERROR` — même famille que les autres 409.
+ */
+declare class SanghoIdempotencyError extends SanghoError {
+    constructor(raw?: SanghoErrorResponse);
+}
+/**
+ * Erreur réseau (pas de réponse du serveur). Catégorie SDK-only : la requête
+ * n'a jamais atteint le backend, donc pas de `raw`/`code` métier précis —
+ * `code` retombe sur `NETWORK_ERROR` (== `type`).
+ */
+declare class SanghoNetworkError extends SanghoError {
+    constructor(message?: string);
+}
+/**
+ * Timeout dépassé. Catégorie SDK-only, même raisonnement que
+ * `SanghoNetworkError` : `code` retombe sur `TIMEOUT_ERROR` (== `type`).
+ */
+declare class SanghoTimeoutError extends SanghoError {
+    constructor(timeout: number);
+}
+
+export { type Address, type AmountInCents, type App, type AppKey, type AppKeys, type CheckoutSession, type CurrencyCode, type Customer, type Invoice, type ListParams, type ListResponse, type Metadata, type Partner, type PaymentIntent, type PaymentLink, type PaymentMethod, type Product, type ProductImage, type Receipt, type Refund, type SandboxResetResult, Sangho, SanghoAuthError, SanghoError, type SanghoErrorResponse, type SanghoErrorType, SanghoIdempotencyError, SanghoNetworkError, SanghoNotFoundError, type SanghoOptions, SanghoPermissionError, SanghoPublicKeyError, SanghoRateLimitError, SanghoTimeoutError, SanghoValidationError, type SecurityProfile, type Subscription, type Timestamps, type Transaction, type UpdateSecurityProfileParams, type Webhook, type WebhookDelivery, constructEvent, Sangho as default };