pi-spi-sdk 0.1.0

package/dist/services/webhooks.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Webhooks (Notifications) service wrapper
+ *
+ * Provides methods for managing webhook configurations to receive real-time notifications
+ * about payment events, payment requests, and fund returns.
+ *
+ * **Supported Events:**
+ * - Payment events: `PAIEMENT_RECU`, `PAIEMENT_ENVOYE`, `PAIEMENT_REJETE`
+ * - Payment request events: `RTP_RECU`, `RTP_REJETE`
+ * - Fund return events: `RETOUR_ENVOYE`, `RETOUR_REJETE`, `RETOUR_RECU`
+ * - Cancellation events: `ANNULATION_DEMANDE`, `ANNULATION_REJETE`
+ *
+ * **Webhook Security:**
+ * - All communications must use SSL/TLS
+ * - mTLS authentication required (certificate from BCEAO CA)
+ * - Events are signed with HMAC for data integrity
+ *
+ * @example
+ * ```typescript
+ * // Create webhook for payment notifications
+ * const webhook = await sdk.webhooks.create({
+ *   callbackUrl: 'https://business.example.com/api/webhooks/pi-spi',
+ *   events: ['PAIEMENT_RECU', 'PAIEMENT_ENVOYE']
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+import type { QueryParams } from '../query-builder';
+export declare class WebhooksService extends BaseService {
+    /**
+     * Create a webhook configuration
+     *
+     * **Webhook Setup:**
+     * - URL must be HTTPS
+     * - Server must support mTLS with BCEAO-issued certificate
+     * - Server must validate HMAC signatures
+     * - Server must respond with 2xx status code
+     *
+     * **Event Types:**
+     * - `PAIEMENT_RECU`: Payment received
+     * - `PAIEMENT_ENVOYE`: Payment sent (irreversible)
+     * - `PAIEMENT_REJETE`: Payment rejected
+     * - `RTP_RECU`: Payment request received
+     * - `RTP_REJETE`: Payment request rejected
+     * - `RETOUR_ENVOYE`: Fund return sent
+     * - `RETOUR_REJETE`: Fund return rejected
+     * - `RETOUR_RECU`: Fund return received
+     * - `ANNULATION_DEMANDE`: Cancellation request received
+     * - `ANNULATION_REJETE`: Cancellation request rejected
+     *
+     * @param webhook - Webhook configuration
+     * @param webhook.callbackUrl - HTTPS URL to receive notifications (must support mTLS)
+     * @param webhook.events - Array of event types to subscribe to
+     * @param webhook.alias - Optional: Alias-specific webhook (only notifications for this alias)
+     * @returns Created webhook configuration
+     * @throws {PiSpiValidationError} If URL is invalid or events array is empty
+     *
+     * @example
+     * ```typescript
+     * // Webhook for all payment events
+     * await sdk.webhooks.create({
+     *   callbackUrl: 'https://business.example.com/api/webhooks/pi-spi',
+     *   events: ['PAIEMENT_RECU', 'PAIEMENT_ENVOYE', 'PAIEMENT_REJETE']
+     * });
+     *
+     * // Alias-specific webhook
+     * await sdk.webhooks.create({
+     *   callbackUrl: 'https://business.example.com/api/webhooks/pi-spi',
+     *   events: ['PAIEMENT_RECU'],
+     *   alias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f'
+     * });
+     * ```
+     */
+    create(webhook: {
+        callbackUrl: string;
+        events: string[];
+        alias?: string;
+    }): Promise<never>;
+    /**
+     * List all configured webhooks
+     *
+     * @param params - Query parameters for pagination
+     * @returns Paginated list of webhooks
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await sdk.webhooks.list({ page: 1, size: 20 });
+     * ```
+     */
+    list(params?: QueryParams): Promise<never>;
+    /**
+     * Get webhook details by ID
+     *
+     * @param id - Webhook ID
+     * @returns Webhook details
+     * @throws {PiSpiNotFoundError} If webhook not found
+     */
+    get(id: string): Promise<never>;
+    /**
+     * Update webhook configuration
+     *
+     * @param id - Webhook ID
+     * @param webhook - Updated webhook configuration
+     * @param webhook.callbackUrl - New callback URL (optional)
+     * @param webhook.events - New event subscriptions (optional)
+     * @param webhook.alias - New alias filter (optional)
+     * @returns Updated webhook configuration
+     * @throws {PiSpiNotFoundError} If webhook not found
+     * @throws {PiSpiValidationError} If update fails validation
+     *
+     * @example
+     * ```typescript
+     * await sdk.webhooks.update('webhook-001', {
+     *   callbackUrl: 'https://updated-url.com/webhooks/pi-spi',
+     *   events: ['PAIEMENT_RECU', 'RTP_RECU']
+     * });
+     * ```
+     */
+    update(id: string, webhook: {
+        callbackUrl?: string;
+        events?: string[];
+        alias?: string;
+    }): Promise<never>;
+    /**
+     * Delete a webhook configuration
+     *
+     * @param id - Webhook ID
+     * @throws {PiSpiNotFoundError} If webhook not found
+     */
+    delete(id: string): Promise<never>;
+}

package/dist/services/webhooks.js

@@ -0,0 +1,142 @@
+/**
+ * Webhooks (Notifications) service wrapper
+ *
+ * Provides methods for managing webhook configurations to receive real-time notifications
+ * about payment events, payment requests, and fund returns.
+ *
+ * **Supported Events:**
+ * - Payment events: `PAIEMENT_RECU`, `PAIEMENT_ENVOYE`, `PAIEMENT_REJETE`
+ * - Payment request events: `RTP_RECU`, `RTP_REJETE`
+ * - Fund return events: `RETOUR_ENVOYE`, `RETOUR_REJETE`, `RETOUR_RECU`
+ * - Cancellation events: `ANNULATION_DEMANDE`, `ANNULATION_REJETE`
+ *
+ * **Webhook Security:**
+ * - All communications must use SSL/TLS
+ * - mTLS authentication required (certificate from BCEAO CA)
+ * - Events are signed with HMAC for data integrity
+ *
+ * @example
+ * ```typescript
+ * // Create webhook for payment notifications
+ * const webhook = await sdk.webhooks.create({
+ *   callbackUrl: 'https://business.example.com/api/webhooks/pi-spi',
+ *   events: ['PAIEMENT_RECU', 'PAIEMENT_ENVOYE']
+ * });
+ * ```
+ */
+import { BaseService } from './base';
+export class WebhooksService extends BaseService {
+    /**
+     * Create a webhook configuration
+     *
+     * **Webhook Setup:**
+     * - URL must be HTTPS
+     * - Server must support mTLS with BCEAO-issued certificate
+     * - Server must validate HMAC signatures
+     * - Server must respond with 2xx status code
+     *
+     * **Event Types:**
+     * - `PAIEMENT_RECU`: Payment received
+     * - `PAIEMENT_ENVOYE`: Payment sent (irreversible)
+     * - `PAIEMENT_REJETE`: Payment rejected
+     * - `RTP_RECU`: Payment request received
+     * - `RTP_REJETE`: Payment request rejected
+     * - `RETOUR_ENVOYE`: Fund return sent
+     * - `RETOUR_REJETE`: Fund return rejected
+     * - `RETOUR_RECU`: Fund return received
+     * - `ANNULATION_DEMANDE`: Cancellation request received
+     * - `ANNULATION_REJETE`: Cancellation request rejected
+     *
+     * @param webhook - Webhook configuration
+     * @param webhook.callbackUrl - HTTPS URL to receive notifications (must support mTLS)
+     * @param webhook.events - Array of event types to subscribe to
+     * @param webhook.alias - Optional: Alias-specific webhook (only notifications for this alias)
+     * @returns Created webhook configuration
+     * @throws {PiSpiValidationError} If URL is invalid or events array is empty
+     *
+     * @example
+     * ```typescript
+     * // Webhook for all payment events
+     * await sdk.webhooks.create({
+     *   callbackUrl: 'https://business.example.com/api/webhooks/pi-spi',
+     *   events: ['PAIEMENT_RECU', 'PAIEMENT_ENVOYE', 'PAIEMENT_REJETE']
+     * });
+     *
+     * // Alias-specific webhook
+     * await sdk.webhooks.create({
+     *   callbackUrl: 'https://business.example.com/api/webhooks/pi-spi',
+     *   events: ['PAIEMENT_RECU'],
+     *   alias: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f'
+     * });
+     * ```
+     */
+    async create(webhook) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * List all configured webhooks
+     *
+     * @param params - Query parameters for pagination
+     * @returns Paginated list of webhooks
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await sdk.webhooks.list({ page: 1, size: 20 });
+     * ```
+     */
+    async list(params) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Get webhook details by ID
+     *
+     * @param id - Webhook ID
+     * @returns Webhook details
+     * @throws {PiSpiNotFoundError} If webhook not found
+     */
+    async get(id) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Update webhook configuration
+     *
+     * @param id - Webhook ID
+     * @param webhook - Updated webhook configuration
+     * @param webhook.callbackUrl - New callback URL (optional)
+     * @param webhook.events - New event subscriptions (optional)
+     * @param webhook.alias - New alias filter (optional)
+     * @returns Updated webhook configuration
+     * @throws {PiSpiNotFoundError} If webhook not found
+     * @throws {PiSpiValidationError} If update fails validation
+     *
+     * @example
+     * ```typescript
+     * await sdk.webhooks.update('webhook-001', {
+     *   callbackUrl: 'https://updated-url.com/webhooks/pi-spi',
+     *   events: ['PAIEMENT_RECU', 'RTP_RECU']
+     * });
+     * ```
+     */
+    async update(id, webhook) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Delete a webhook configuration
+     *
+     * @param id - Webhook ID
+     * @throws {PiSpiNotFoundError} If webhook not found
+     */
+    async delete(id) {
+        return this.execute(async () => {
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}

package/dist/types/alias.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Alias Types for PI-SPI
+ *
+ * The PI-SPI platform supports different types of account aliases:
+ *
+ * - **SHID**: A randomly generated 36-character unique payment address (UUID format).
+ *   Generated by the system when created. Available for all client types (P, C, B, G).
+ *   Example: `8b1b2499-3e50-435b-b757-ac7a83d8aa7f`
+ *
+ * - **MCOD**: Merchant code identifier for USSD payment support.
+ *   Available for business clients only (C, B, G). Format: alphanumeric code.
+ *   Example: `SNF00_2E4TY`
+ *
+ * - **MBNO**: Mobile phone number alias.
+ *   Available for individual clients (P) only. Format: phone number.
+ *   Example: `+221771234567`
+ *
+ * **Client Type Restrictions:**
+ * - Type P (Individuals): Can create MBNO and SHID aliases
+ * - Types C, B, G (Businesses): Can create SHID and MCOD aliases
+ *
+ * **Limits:**
+ * - Default limit: 20 aliases per account
+ * - Limit can be increased based on client needs
+ */
+/**
+ * Alias type values as defined in the PI-SPI API specification
+ */
+export declare const AliasType: {
+    /**
+     * SHID - System-generated unique payment address (UUID format, 36 characters)
+     * Available for all client types: P, C, B, G
+     */
+    readonly SHID: "SHID";
+    /**
+     * MCOD - Merchant code for USSD payment support
+     * Available for business clients only: C, B, G
+     */
+    readonly MCOD: "MCOD";
+    /**
+     * MBNO - Mobile phone number alias
+     * Available for individual clients only: P
+     */
+    readonly MBNO: "MBNO";
+};
+/**
+ * Type representing a valid alias type
+ */
+export type AliasType = (typeof AliasType)[keyof typeof AliasType];
+/**
+ * Valid alias types as a tuple for runtime validation
+ */
+export declare const ALIAS_TYPES: readonly ["SHID", "MCOD", "MBNO"];
+/**
+ * Check if a string is a valid alias type
+ */
+export declare function isValidAliasType(value: string): value is AliasType;
+/**
+ * Get available alias types for a client type
+ *
+ * @param clientType - Client type: 'P' (Individual), 'C' (Merchant), 'B' (Business), 'G' (Government)
+ * @returns Array of available alias types for the client type
+ */
+export declare function getAvailableAliasTypes(clientType: 'P' | 'C' | 'B' | 'G'): AliasType[];

package/dist/types/alias.js

@@ -0,0 +1,73 @@
+/**
+ * Alias Types for PI-SPI
+ *
+ * The PI-SPI platform supports different types of account aliases:
+ *
+ * - **SHID**: A randomly generated 36-character unique payment address (UUID format).
+ *   Generated by the system when created. Available for all client types (P, C, B, G).
+ *   Example: `8b1b2499-3e50-435b-b757-ac7a83d8aa7f`
+ *
+ * - **MCOD**: Merchant code identifier for USSD payment support.
+ *   Available for business clients only (C, B, G). Format: alphanumeric code.
+ *   Example: `SNF00_2E4TY`
+ *
+ * - **MBNO**: Mobile phone number alias.
+ *   Available for individual clients (P) only. Format: phone number.
+ *   Example: `+221771234567`
+ *
+ * **Client Type Restrictions:**
+ * - Type P (Individuals): Can create MBNO and SHID aliases
+ * - Types C, B, G (Businesses): Can create SHID and MCOD aliases
+ *
+ * **Limits:**
+ * - Default limit: 20 aliases per account
+ * - Limit can be increased based on client needs
+ */
+/**
+ * Alias type values as defined in the PI-SPI API specification
+ */
+export const AliasType = {
+    /**
+     * SHID - System-generated unique payment address (UUID format, 36 characters)
+     * Available for all client types: P, C, B, G
+     */
+    SHID: 'SHID',
+    /**
+     * MCOD - Merchant code for USSD payment support
+     * Available for business clients only: C, B, G
+     */
+    MCOD: 'MCOD',
+    /**
+     * MBNO - Mobile phone number alias
+     * Available for individual clients only: P
+     */
+    MBNO: 'MBNO',
+};
+/**
+ * Valid alias types as a tuple for runtime validation
+ */
+export const ALIAS_TYPES = [AliasType.SHID, AliasType.MCOD, AliasType.MBNO];
+/**
+ * Check if a string is a valid alias type
+ */
+export function isValidAliasType(value) {
+    return ALIAS_TYPES.includes(value);
+}
+/**
+ * Get available alias types for a client type
+ *
+ * @param clientType - Client type: 'P' (Individual), 'C' (Merchant), 'B' (Business), 'G' (Government)
+ * @returns Array of available alias types for the client type
+ */
+export function getAvailableAliasTypes(clientType) {
+    switch (clientType) {
+        case 'P':
+            return [AliasType.MBNO, AliasType.SHID];
+        case 'C':
+        case 'B':
+        case 'G':
+            return [AliasType.SHID, AliasType.MCOD];
+        default:
+            return [];
+    }
+}

package/dist/utils/constants.d.ts

@@ -0,0 +1,93 @@
+/**
+ * PI-SPI Constants
+ *
+ * Centralized constants for API endpoints, status codes, and configuration values
+ */
+export declare const PI_SPI_ENDPOINTS: {
+    /** Production API endpoint */
+    PRODUCTION: string;
+    /** Sandbox API endpoint */
+    SANDBOX: string;
+    /** Default endpoint (sandbox) */
+    DEFAULT: string;
+};
+export declare const PAYMENT_STATUS: {
+    /** Payment initiated (awaiting confirmation after alias lookup) */
+    INITIE: string;
+    /** Payment sent (validations passed, PSP has sent the request) */
+    ENVOYE: string;
+    /** Payment is confirmed/irreversible */
+    IRREVOCABLE: string;
+    /** Payment has been rejected */
+    REJETE: string;
+};
+export declare const ACCOUNT_STATUS: {
+    /** Account is open */
+    OPEN: string;
+    /** Account is blocked */
+    BLOCKED: string;
+    /** Account is closed */
+    CLOSED: string;
+};
+export declare const ACCOUNT_TYPE: {
+    /** Current account */
+    CURRENT: string;
+    /** Savings account */
+    SAVINGS: string;
+};
+export declare const CLIENT_TYPE: {
+    /** Individual person */
+    INDIVIDUAL: string;
+    /** Merchant */
+    MERCHANT: string;
+    /** Business */
+    BUSINESS: string;
+    /** Government */
+    GOVERNMENT: string;
+};
+export declare const UEMOA_COUNTRIES: {
+    BENIN: string;
+    BURKINA_FASO: string;
+    IVORY_COAST: string;
+    GUINEA_BISSAU: string;
+    MALI: string;
+    NIGER: string;
+    SENEGAL: string;
+    TOGO: string;
+};
+export declare const CURRENCY: {
+    /** West African CFA Franc */
+    XOF: string;
+    /** Amounts are specified in centimes (1 XOF = 100 centimes) */
+    CENTIMES_PER_XOF: number;
+};
+export declare const DEFAULT_LIMITS: {
+    /** Maximum page size for paginated requests */
+    MAX_PAGE_SIZE: number;
+    /** Default page size */
+    DEFAULT_PAGE_SIZE: number;
+    /** Default aliases per account */
+    DEFAULT_ALIASES_PER_ACCOUNT: number;
+};
+export declare const WEBHOOK_EVENTS: {
+    /** Payment received */
+    PAIEMENT_RECU: string;
+    /** Payment sent */
+    PAIEMENT_ENVOYE: string;
+    /** Payment rejected */
+    PAIEMENT_REJETE: string;
+    /** Payment request (RTP) received */
+    RTP_RECU: string;
+    /** Payment request (RTP) rejected */
+    RTP_REJETE: string;
+    /** Cancellation requested */
+    ANNULATION_DEMANDE: string;
+    /** Cancellation rejected */
+    ANNULATION_REJETE: string;
+    /** Fund return sent */
+    RETOUR_ENVOYE: string;
+    /** Fund return rejected */
+    RETOUR_REJETE: string;
+    /** Fund return received */
+    RETOUR_RECU: string;
+};

package/dist/utils/constants.js

@@ -0,0 +1,93 @@
+/**
+ * PI-SPI Constants
+ *
+ * Centralized constants for API endpoints, status codes, and configuration values
+ */
+export const PI_SPI_ENDPOINTS = {
+    /** Production API endpoint */
+    PRODUCTION: 'https://api.pi-bceao.com/piz/v1',
+    /** Sandbox API endpoint */
+    SANDBOX: 'https://sandbox.api.pi-bceao.com/piz/v1',
+    /** Default endpoint (sandbox) */
+    DEFAULT: 'https://sandbox.api.pi-bceao.com/piz/v1',
+};
+export const PAYMENT_STATUS = {
+    /** Payment initiated (awaiting confirmation after alias lookup) */
+    INITIE: 'INITIE',
+    /** Payment sent (validations passed, PSP has sent the request) */
+    ENVOYE: 'ENVOYE',
+    /** Payment is confirmed/irreversible */
+    IRREVOCABLE: 'IRREVOCABLE',
+    /** Payment has been rejected */
+    REJETE: 'REJETE',
+};
+export const ACCOUNT_STATUS = {
+    /** Account is open */
+    OPEN: 'OUVERT',
+    /** Account is blocked */
+    BLOCKED: 'BLOQUE',
+    /** Account is closed */
+    CLOSED: 'CLOTURE',
+};
+export const ACCOUNT_TYPE = {
+    /** Current account */
+    CURRENT: 'CACC',
+    /** Savings account */
+    SAVINGS: 'SVGS',
+};
+export const CLIENT_TYPE = {
+    /** Individual person */
+    INDIVIDUAL: 'P',
+    /** Merchant */
+    MERCHANT: 'C',
+    /** Business */
+    BUSINESS: 'B',
+    /** Government */
+    GOVERNMENT: 'G',
+};
+export const UEMOA_COUNTRIES = {
+    BENIN: 'BJ',
+    BURKINA_FASO: 'BF',
+    IVORY_COAST: 'CI',
+    GUINEA_BISSAU: 'GW',
+    MALI: 'ML',
+    NIGER: 'NE',
+    SENEGAL: 'SN',
+    TOGO: 'TG',
+};
+export const CURRENCY = {
+    /** West African CFA Franc */
+    XOF: 'XOF',
+    /** Amounts are specified in centimes (1 XOF = 100 centimes) */
+    CENTIMES_PER_XOF: 100,
+};
+export const DEFAULT_LIMITS = {
+    /** Maximum page size for paginated requests */
+    MAX_PAGE_SIZE: 100,
+    /** Default page size */
+    DEFAULT_PAGE_SIZE: 20,
+    /** Default aliases per account */
+    DEFAULT_ALIASES_PER_ACCOUNT: 20,
+};
+export const WEBHOOK_EVENTS = {
+    /** Payment received */
+    PAIEMENT_RECU: 'PAIEMENT_RECU',
+    /** Payment sent */
+    PAIEMENT_ENVOYE: 'PAIEMENT_ENVOYE',
+    /** Payment rejected */
+    PAIEMENT_REJETE: 'PAIEMENT_REJETE',
+    /** Payment request (RTP) received */
+    RTP_RECU: 'RTP_RECU',
+    /** Payment request (RTP) rejected */
+    RTP_REJETE: 'RTP_REJETE',
+    /** Cancellation requested */
+    ANNULATION_DEMANDE: 'ANNULATION_DEMANDE',
+    /** Cancellation rejected */
+    ANNULATION_REJETE: 'ANNULATION_REJETE',
+    /** Fund return sent */
+    RETOUR_ENVOYE: 'RETOUR_ENVOYE',
+    /** Fund return rejected */
+    RETOUR_REJETE: 'RETOUR_REJETE',
+    /** Fund return received */
+    RETOUR_RECU: 'RETOUR_RECU',
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Utility functions for PI-SPI operations
+ *
+ * Common helper functions for formatting amounts, validating inputs,
+ * and other utility operations.
+ */
+/**
+ * Format amount from centimes to XOF
+ * @param centimes - Amount in centimes
+ * @returns Formatted amount string (e.g., "1 500 XOF")
+ */
+export declare function formatAmount(centimes: number): string;
+/**
+ * Convert XOF to centimes
+ * @param xof - Amount in XOF
+ * @returns Amount in centimes
+ */
+export declare function xofToCentimes(xof: number): number;
+/**
+ * Convert centimes to XOF
+ * @param centimes - Amount in centimes
+ * @returns Amount in XOF
+ */
+export declare function centimesToXof(centimes: number): number;
+/**
+ * Validate account number format
+ * @param accountNumber - Account number to validate
+ * @returns True if valid format
+ */
+export declare function isValidAccountNumber(accountNumber: string): boolean;
+/**
+ * Validate SHID alias format (UUID)
+ * @param alias - Alias to validate
+ * @returns True if valid UUID format
+ */
+export declare function isValidShidAlias(alias: string): boolean;
+/**
+ * Validate phone number format (for MBNO alias)
+ * @param phoneNumber - Phone number to validate
+ * @returns True if valid format
+ */
+export declare function isValidPhoneNumber(phoneNumber: string): boolean;
+/**
+ * Extract country code from account number
+ * @param accountNumber - Account number
+ * @returns Country code or null
+ */
+export declare function getCountryFromAccount(accountNumber: string): string | null;
+/**
+ * Sleep/delay utility
+ * @param ms - Milliseconds to wait
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Retry a function with exponential backoff
+ * @param fn - Function to retry
+ * @param maxRetries - Maximum number of retries
+ * @param initialDelay - Initial delay in milliseconds
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries?: number, initialDelay?: number): Promise<T>;