pi-spi-sdk 0.1.0

package/dist/services/paiements-en-masse.js

@@ -0,0 +1,153 @@
+/**
+ * Bulk Payments (Paiements en Masse) service wrapper
+ *
+ * Provides methods for creating and managing bulk payment operations.
+ *
+ * **Bulk Payment Features:**
+ * - Process multiple payments in a single request
+ * - Linked by unique `instructionId`
+ * - Can retry failed payments
+ * - Supports up to 10,000 transactions per bulk (recommended: 500-5,000)
+ *
+ * **Transaction Size:**
+ * - Max size per transaction: ~310 bytes
+ * - Max bulk size: ~3.1 MB for 10,000 transactions
+ * - Recommended: 500-5,000 transactions per bulk
+ *
+ * **Use Cases:**
+ * - Salary payments
+ * - Vendor payments
+ * - Bulk disbursements
+ * - Mass refunds
+ *
+ * @example
+ * ```typescript
+ * // Create bulk payment
+ * const bulkPayment = await sdk.paiementsEnMasse.createBulk({
+ *   comptePayeur: 'CIC2344256727788288822',
+ *   instructionId: 'BULK-2023-001',
+ *   transactions: [
+ *     { txId: 'TX001', payeAlias: 'alias1', montant: 100000, motif: 'Salaire' },
+ *     { txId: 'TX002', payeAlias: 'alias2', montant: 150000, motif: 'Salaire' }
+ *   ]
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export class PaiementsEnMasseService extends BaseService {
+    /**
+     * Create bulk payments
+     *
+     * **Bulk Processing:**
+     * - All transactions share the same `instructionId`
+     * - Each transaction needs unique `txId`
+     * - Transactions are processed in parallel
+     * - Failed transactions can be retried
+     *
+     * **Performance Considerations:**
+     * - Larger bulks take longer to process
+     * - May hit HTTP timeout for very large bulks
+     * - Recommended: 500-5,000 transactions per bulk
+     * - For >10,000 transactions, split into multiple bulks
+     *
+     * **Response Status:**
+     * - `INITIE`: Bulk created, awaiting confirmation
+     * - `ENVOYE`: Bulk sent, transactions processing
+     * - `IRREVOCABLE`: All transactions completed
+     * - `PARTIEL`: Some transactions succeeded, some failed
+     * - `REJETE`: Bulk rejected (validation failed)
+     *
+     * @param payment - Bulk payment creation data
+     * @param payment.comptePayeur - Payer account number
+     * @param payment.instructionId - Unique bulk instruction ID
+     * @param payment.transactions - Array of payment transactions
+     * @param payment.transactions[].txId - Unique transaction ID (must be unique within bulk)
+     * @param payment.transactions[].payeAlias - Payee alias (SHID, MCOD, or MBNO)
+     * @param payment.transactions[].montant - Amount in centimes
+     * @param payment.transactions[].motif - Payment reason/description
+     * @param payment.transactions[].refDocType - Reference document type (optional)
+     * @param payment.transactions[].refDocNumero - Reference document number (optional)
+     * @returns Bulk payment response with status and summary
+     * @throws {PiSpiValidationError} If bulk fails validation (e.g., duplicate txId, invalid alias)
+     * @throws {PiSpiError} If account blocked or insufficient funds
+     *
+     * @example
+     * ```typescript
+     * // Create bulk payment for salary disbursement
+     * await sdk.paiementsEnMasse.createBulk({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   instructionId: 'SALARY-2023-03',
+     *   transactions: [
+     *     {
+     *       txId: 'SAL-001',
+     *       payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+     *       montant: 500000, // 5,000 XOF
+     *       motif: 'Salaire mars 2023'
+     *     },
+     *     {
+     *       txId: 'SAL-002',
+     *       payeAlias: '4r5ty499-3e50-435b-b757-ac7a83d67juio',
+     *       montant: 750000, // 7,500 XOF
+     *       motif: 'Salaire mars 2023'
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    async createBulk(payment) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Get bulk payment details and status
+     *
+     * **Response Includes:**
+     * - Overall bulk status
+     * - Transaction counts (total, succeeded, failed)
+     * - Individual transaction statuses
+     * - Failed transaction details
+     *
+     * @param instructionId - Bulk instruction ID
+     * @returns Bulk payment details with transaction statuses
+     * @throws {PiSpiNotFoundError} If bulk payment not found
+     *
+     * @example
+     * ```typescript
+     * const bulk = await sdk.paiementsEnMasse.get('SALARY-2023-03');
+     * console.log('Status:', bulk.statut); // 'IRREVOCABLE'
+     * console.log('Succeeded:', bulk.nombreSuccess); // 98
+     * console.log('Failed:', bulk.nombreEchec); // 2
+     * ```
+     */
+    async get(instructionId) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Retry failed payments in a bulk payment
+     *
+     * **Retry Process:**
+     * - Only failed transactions are retried
+     * - Successful transactions are not affected
+     * - Uses same `instructionId`
+     * - Can retry multiple times if needed
+     *
+     * @param instructionId - Bulk instruction ID
+     * @returns Retry response with updated status
+     * @throws {PiSpiNotFoundError} If bulk payment not found
+     * @throws {PiSpiError} If no failed transactions to retry
+     *
+     * @example
+     * ```typescript
+     * // Retry failed transactions
+     * await sdk.paiementsEnMasse.retry('SALARY-2023-03');
+     * ```
+     */
+    async retry(instructionId) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}

package/dist/services/paiements.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Payments (Paiements) service wrapper
+ *
+ * Provides methods for creating and managing immediate payments.
+ *
+ * **Payment Types Supported:**
+ * - **Bank-to-Bank**: Payments between bank accounts via API (`categorie: 733`)
+ * - **Bank-to-Wallet**: Payments from bank accounts to mobile wallets
+ * - **Wallet-to-Wallet**: Payments between mobile wallets
+ * - **Wallet-to-Bank**: Payments from mobile wallets to bank accounts
+ *
+ * All payment types are interoperable across the UEMOA region (8 countries).
+ *
+ * @example
+ * ```typescript
+ * // Create immediate payment
+ * const payment = await sdk.paiements.create({
+ *   comptePayeur: 'CIC2344256727788288822',
+ *   payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+ *   montant: 150000, // 1,500 XOF
+ *   motif: 'Paiement de services'
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+import type { QueryParams } from '../query-builder';
+export declare class PaiementsService extends BaseService {
+    /**
+     * Create an immediate payment
+     *
+     * **Payment Flow:**
+     * - If `confirmation: false`: Payment is sent immediately (default)
+     * - If `confirmation: true`: Payment is initiated, returns payee info for confirmation
+     *
+     * **Supported Transaction Types:**
+     * - Bank-to-Bank (`categorie: 733`)
+     * - Bank-to-Wallet (via alias lookup)
+     * - Wallet-to-Wallet (via alias lookup)
+     * - Wallet-to-Bank (via alias lookup)
+     *
+     * **Status Values:**
+     * - `INITIE`: Waiting for confirmation (if confirmation: true)
+     * - `ENVOYE`: Payment sent successfully
+     * - `IRREVOCABLE`: Payment confirmed and cannot be reversed
+     * - `REJETE`: Payment rejected (check `statutRaison` for error code)
+     *
+     * @param payment - Payment creation data
+     * @param payment.comptePayeur - Payer account number (e.g., 'CIC2344256727788288822')
+     * @param payment.payeAlias - Payee alias (SHID, MCOD, or MBNO format)
+     * @param payment.montant - Amount in centimes (e.g., 150000 = 1,500 XOF)
+     * @param payment.motif - Payment reason/description
+     * @param payment.txId - Unique transaction ID (optional, auto-generated if not provided)
+     * @param payment.confirmation - Whether to require confirmation before sending (default: false)
+     * @param payment.categorie - Payment category/canal (default: 733 for API Business)
+     * @returns Payment response with status
+     * @throws {PiSpiValidationError} If payment fails validation (e.g., invalid alias, duplicate txId)
+     * @throws {PiSpiError} If account blocked or insufficient funds
+     *
+     * @example
+     * ```typescript
+     * // Immediate payment (no confirmation)
+     * const payment = await sdk.paiements.create({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f', // SHID alias
+     *   montant: 150000, // 1,500 XOF
+     *   motif: 'Paiement de services',
+     *   txId: '23552722'
+     * });
+     *
+     * // Payment with confirmation (returns payee info)
+     * const paymentWithConfirmation = await sdk.paiements.create({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+     *   montant: 3000000, // 30,000 XOF
+     *   confirmation: true
+     * });
+     * ```
+     */
+    create(payment: {
+        comptePayeur: string;
+        payeAlias: string;
+        montant: number;
+        motif: string;
+        txId?: string;
+        confirmation?: boolean;
+        categorie?: string;
+    }): Promise<never>;
+    /**
+     * Get payment details by transaction ID
+     *
+     * @param txId - Transaction ID
+     * @returns Payment details including status and history
+     * @throws {PiSpiNotFoundError} If payment not found
+     *
+     * @example
+     * ```typescript
+     * const payment = await sdk.paiements.get('23552722');
+     * console.log('Status:', payment.statut); // 'IRREVOCABLE'
+     * console.log('Amount:', payment.montant); // 150000
+     * ```
+     */
+    get(txId: string): Promise<never>;
+    /**
+     * List payments with filtering and pagination
+     *
+     * **Filter Options:**
+     * - Filter by account: `comptePayeur`
+     * - Filter by status: `statut` (INITIE, ENVOYE, IRREVOCABLE, REJETE)
+     * - Filter by dates: `dateEnvoi`, `dateIrrevocabilite`
+     * - Use QueryBuilder for advanced filtering
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of payments
+     *
+     * @example
+     * ```typescript
+     * // List all payments for an account
+     * const payments = await sdk.paiements.list({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   page: 1,
+     *   size: 20
+     * });
+     *
+     * // Filter by status
+     * const completed = await sdk.paiements.list({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   statut: 'IRREVOCABLE'
+     * });
+     * ```
+     */
+    list(params?: QueryParams & {
+        comptePayeur?: string;
+        statut?: string;
+    }): Promise<never>;
+}

package/dist/services/paiements.js

@@ -0,0 +1,135 @@
+/**
+ * Payments (Paiements) service wrapper
+ *
+ * Provides methods for creating and managing immediate payments.
+ *
+ * **Payment Types Supported:**
+ * - **Bank-to-Bank**: Payments between bank accounts via API (`categorie: 733`)
+ * - **Bank-to-Wallet**: Payments from bank accounts to mobile wallets
+ * - **Wallet-to-Wallet**: Payments between mobile wallets
+ * - **Wallet-to-Bank**: Payments from mobile wallets to bank accounts
+ *
+ * All payment types are interoperable across the UEMOA region (8 countries).
+ *
+ * @example
+ * ```typescript
+ * // Create immediate payment
+ * const payment = await sdk.paiements.create({
+ *   comptePayeur: 'CIC2344256727788288822',
+ *   payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+ *   montant: 150000, // 1,500 XOF
+ *   motif: 'Paiement de services'
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export class PaiementsService extends BaseService {
+    /**
+     * Create an immediate payment
+     *
+     * **Payment Flow:**
+     * - If `confirmation: false`: Payment is sent immediately (default)
+     * - If `confirmation: true`: Payment is initiated, returns payee info for confirmation
+     *
+     * **Supported Transaction Types:**
+     * - Bank-to-Bank (`categorie: 733`)
+     * - Bank-to-Wallet (via alias lookup)
+     * - Wallet-to-Wallet (via alias lookup)
+     * - Wallet-to-Bank (via alias lookup)
+     *
+     * **Status Values:**
+     * - `INITIE`: Waiting for confirmation (if confirmation: true)
+     * - `ENVOYE`: Payment sent successfully
+     * - `IRREVOCABLE`: Payment confirmed and cannot be reversed
+     * - `REJETE`: Payment rejected (check `statutRaison` for error code)
+     *
+     * @param payment - Payment creation data
+     * @param payment.comptePayeur - Payer account number (e.g., 'CIC2344256727788288822')
+     * @param payment.payeAlias - Payee alias (SHID, MCOD, or MBNO format)
+     * @param payment.montant - Amount in centimes (e.g., 150000 = 1,500 XOF)
+     * @param payment.motif - Payment reason/description
+     * @param payment.txId - Unique transaction ID (optional, auto-generated if not provided)
+     * @param payment.confirmation - Whether to require confirmation before sending (default: false)
+     * @param payment.categorie - Payment category/canal (default: 733 for API Business)
+     * @returns Payment response with status
+     * @throws {PiSpiValidationError} If payment fails validation (e.g., invalid alias, duplicate txId)
+     * @throws {PiSpiError} If account blocked or insufficient funds
+     *
+     * @example
+     * ```typescript
+     * // Immediate payment (no confirmation)
+     * const payment = await sdk.paiements.create({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f', // SHID alias
+     *   montant: 150000, // 1,500 XOF
+     *   motif: 'Paiement de services',
+     *   txId: '23552722'
+     * });
+     *
+     * // Payment with confirmation (returns payee info)
+     * const paymentWithConfirmation = await sdk.paiements.create({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   payeAlias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f',
+     *   montant: 3000000, // 30,000 XOF
+     *   confirmation: true
+     * });
+     * ```
+     */
+    async create(payment) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Get payment details by transaction ID
+     *
+     * @param txId - Transaction ID
+     * @returns Payment details including status and history
+     * @throws {PiSpiNotFoundError} If payment not found
+     *
+     * @example
+     * ```typescript
+     * const payment = await sdk.paiements.get('23552722');
+     * console.log('Status:', payment.statut); // 'IRREVOCABLE'
+     * console.log('Amount:', payment.montant); // 150000
+     * ```
+     */
+    async get(txId) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * List payments with filtering and pagination
+     *
+     * **Filter Options:**
+     * - Filter by account: `comptePayeur`
+     * - Filter by status: `statut` (INITIE, ENVOYE, IRREVOCABLE, REJETE)
+     * - Filter by dates: `dateEnvoi`, `dateIrrevocabilite`
+     * - Use QueryBuilder for advanced filtering
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of payments
+     *
+     * @example
+     * ```typescript
+     * // List all payments for an account
+     * const payments = await sdk.paiements.list({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   page: 1,
+     *   size: 20
+     * });
+     *
+     * // Filter by status
+     * const completed = await sdk.paiements.list({
+     *   comptePayeur: 'CIC2344256727788288822',
+     *   statut: 'IRREVOCABLE'
+     * });
+     * ```
+     */
+    async list(params) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}

package/dist/services/retours-fonds.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Fund Returns (Retours de Fonds) service wrapper
+ *
+ * Provides methods for returning funds from received payments.
+ *
+ * **Return Rules:**
+ * - Can only return funds from payments received
+ * - Must be initiated within 90 days of original payment
+ * - After 90 days, returns are no longer possible
+ * - Returns are processed instantly when sent
+ *
+ * **Use Cases:**
+ * - Refunds for returned goods
+ * - Cancellation of services
+ * - Error corrections
+ * - Customer disputes
+ *
+ * @example
+ * ```typescript
+ * // Return funds from a received payment
+ * const returnFunds = await sdk.retoursFonds.create({
+ *   comptePaye: 'CIC2344256727788288822',
+ *   txId: '23552722', // Original payment transaction ID
+ *   montant: 150000, // Amount to return (1,500 XOF)
+ *   motif: 'CUST' // Customer request reason code
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+import type { QueryParams } from '../query-builder';
+export declare class RetoursFondsService extends BaseService {
+    /**
+     * Create a fund return
+     *
+     * **Return Process:**
+     * 1. Business identifies original payment transaction
+     * 2. Creates return request (must be within 90 days)
+     * 3. Return is processed immediately
+     * 4. Funds are returned to original payer
+     *
+     * **Status Values:**
+     * - `ENVOYE`: Return sent successfully
+     * - `IRREVOCABLE`: Return confirmed and cannot be reversed
+     * - `REJETE`: Return rejected (check `statutRaison` for error code)
+     *
+     * **Rejection Reasons:**
+     * - `AM04`: Insufficient guarantee funds
+     * - `AM09`: Wrong amount
+     * - `AC06`: Blocked account
+     * - `FR01`: Fraud suspicion
+     * - `RR04`: Regulatory reason
+     *
+     * @param returnRequest - Fund return request data
+     * @param returnRequest.comptePaye - Business account number (original payee)
+     * @param returnRequest.txId - Original payment transaction ID
+     * @param returnRequest.montant - Amount to return in centimes (e.g., 150000 = 1,500 XOF)
+     * @param returnRequest.motif - Return reason code (e.g., 'CUST' for customer request)
+     * @returns Fund return response
+     * @throws {PiSpiValidationError} If return fails validation (e.g., > 90 days, invalid txId)
+     * @throws {PiSpiError} If account blocked or insufficient funds
+     *
+     * @example
+     * ```typescript
+     * // Return full payment amount
+     * await sdk.retoursFonds.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   txId: '23552722', // Original payment ID
+     *   montant: 150000, // 1,500 XOF
+     *   motif: 'CUST' // Customer request
+     * });
+     * ```
+     */
+    create(returnRequest: {
+        comptePaye: string;
+        txId: string;
+        montant: number;
+        motif: string;
+    }): Promise<never>;
+    /**
+     * Get fund return details by transaction ID
+     *
+     * @param id - Fund return transaction ID
+     * @returns Fund return details
+     * @throws {PiSpiNotFoundError} If return not found
+     */
+    get(id: string): Promise<never>;
+    /**
+     * List fund returns with filtering and pagination
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of fund returns
+     */
+    list(params?: QueryParams): Promise<never>;
+}

package/dist/services/retours-fonds.js

@@ -0,0 +1,100 @@
+/**
+ * Fund Returns (Retours de Fonds) service wrapper
+ *
+ * Provides methods for returning funds from received payments.
+ *
+ * **Return Rules:**
+ * - Can only return funds from payments received
+ * - Must be initiated within 90 days of original payment
+ * - After 90 days, returns are no longer possible
+ * - Returns are processed instantly when sent
+ *
+ * **Use Cases:**
+ * - Refunds for returned goods
+ * - Cancellation of services
+ * - Error corrections
+ * - Customer disputes
+ *
+ * @example
+ * ```typescript
+ * // Return funds from a received payment
+ * const returnFunds = await sdk.retoursFonds.create({
+ *   comptePaye: 'CIC2344256727788288822',
+ *   txId: '23552722', // Original payment transaction ID
+ *   montant: 150000, // Amount to return (1,500 XOF)
+ *   motif: 'CUST' // Customer request reason code
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export class RetoursFondsService extends BaseService {
+    /**
+     * Create a fund return
+     *
+     * **Return Process:**
+     * 1. Business identifies original payment transaction
+     * 2. Creates return request (must be within 90 days)
+     * 3. Return is processed immediately
+     * 4. Funds are returned to original payer
+     *
+     * **Status Values:**
+     * - `ENVOYE`: Return sent successfully
+     * - `IRREVOCABLE`: Return confirmed and cannot be reversed
+     * - `REJETE`: Return rejected (check `statutRaison` for error code)
+     *
+     * **Rejection Reasons:**
+     * - `AM04`: Insufficient guarantee funds
+     * - `AM09`: Wrong amount
+     * - `AC06`: Blocked account
+     * - `FR01`: Fraud suspicion
+     * - `RR04`: Regulatory reason
+     *
+     * @param returnRequest - Fund return request data
+     * @param returnRequest.comptePaye - Business account number (original payee)
+     * @param returnRequest.txId - Original payment transaction ID
+     * @param returnRequest.montant - Amount to return in centimes (e.g., 150000 = 1,500 XOF)
+     * @param returnRequest.motif - Return reason code (e.g., 'CUST' for customer request)
+     * @returns Fund return response
+     * @throws {PiSpiValidationError} If return fails validation (e.g., > 90 days, invalid txId)
+     * @throws {PiSpiError} If account blocked or insufficient funds
+     *
+     * @example
+     * ```typescript
+     * // Return full payment amount
+     * await sdk.retoursFonds.create({
+     *   comptePaye: 'CIC2344256727788288822',
+     *   txId: '23552722', // Original payment ID
+     *   montant: 150000, // 1,500 XOF
+     *   motif: 'CUST' // Customer request
+     * });
+     * ```
+     */
+    async create(returnRequest) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Get fund return details by transaction ID
+     *
+     * @param id - Fund return transaction ID
+     * @returns Fund return details
+     * @throws {PiSpiNotFoundError} If return not found
+     */
+    async get(id) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * List fund returns with filtering and pagination
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of fund returns
+     */
+    async list(params) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}