pi-spi-sdk 0.1.0

package/dist/query-builder.js

@@ -0,0 +1,187 @@
+/**
+ * Query builder utility for constructing filter, pagination, and sorting parameters
+ */
+export class QueryBuilder {
+    constructor() {
+        this.params = {};
+        this.filters = new Map();
+        this.sortOrder = 'asc';
+    }
+    /**
+     * Add a filter condition
+     * @param field - Field name to filter on
+     * @param operator - Filter operator (default: 'eq')
+     * @param value - Filter value
+     */
+    filter(field, operatorOrValue, value) {
+        let operator;
+        let filterValue;
+        if (value === undefined) {
+            // If only two arguments, treat first as operator/value
+            if (typeof operatorOrValue === 'string' && this.isOperator(operatorOrValue)) {
+                throw new Error('Filter operator requires a value');
+            }
+            operator = 'eq';
+            filterValue = operatorOrValue;
+        }
+        else {
+            operator = operatorOrValue;
+            filterValue = value;
+        }
+        this.filters.set(field, { operator, value: filterValue });
+        return this;
+    }
+    /**
+     * Add an equality filter (shorthand)
+     */
+    eq(field, value) {
+        return this.filter(field, 'eq', value);
+    }
+    /**
+     * Add a "not equal" filter (shorthand)
+     */
+    ne(field, value) {
+        return this.filter(field, 'ne', value);
+    }
+    /**
+     * Add a "greater than" filter (shorthand)
+     */
+    gt(field, value) {
+        return this.filter(field, 'gt', value);
+    }
+    /**
+     * Add a "greater than or equal" filter (shorthand)
+     */
+    gte(field, value) {
+        return this.filter(field, 'gte', value);
+    }
+    /**
+     * Add a "less than" filter (shorthand)
+     */
+    lt(field, value) {
+        return this.filter(field, 'lt', value);
+    }
+    /**
+     * Add a "less than or equal" filter (shorthand)
+     */
+    lte(field, value) {
+        return this.filter(field, 'lte', value);
+    }
+    /**
+     * Add an "in" filter (shorthand)
+     */
+    in(field, values) {
+        return this.filter(field, 'in', values);
+    }
+    /**
+     * Add a "contains" filter (shorthand)
+     */
+    contains(field, value) {
+        return this.filter(field, 'contains', value);
+    }
+    /**
+     * Set sort field and order
+     * @param field - Field to sort by
+     * @param order - Sort order ('asc' or 'desc', default: 'asc')
+     */
+    sort(field, order = 'asc') {
+        this.sortField = field;
+        this.sortOrder = order;
+        return this;
+    }
+    /**
+     * Sort in descending order (shorthand)
+     */
+    sortDesc(field) {
+        return this.sort(field, 'desc');
+    }
+    /**
+     * Set page number
+     */
+    page(page) {
+        this.params.page = typeof page === 'string' ? page : page.toString();
+        return this;
+    }
+    /**
+     * Set page size
+     */
+    size(size) {
+        if (size < 1) {
+            throw new Error('Page size must be at least 1');
+        }
+        if (size > 100) {
+            throw new Error('Page size cannot exceed 100');
+        }
+        this.params.size = size;
+        return this;
+    }
+    /**
+     * Add a custom parameter
+     */
+    param(key, value) {
+        this.params[key] = value;
+        return this;
+    }
+    /**
+     * Build the query parameters object
+     */
+    build() {
+        const result = { ...this.params };
+        // Add filters
+        for (const [field, { operator, value }] of this.filters.entries()) {
+            if (operator === 'eq') {
+                // Simple equality filters don't need operator notation
+                result[field] = String(value);
+            }
+            else if (operator === 'exists') {
+                // Exists operator uses special syntax
+                result[`${field}[exists]`] = String(value);
+            }
+            else {
+                // Other operators use bracket notation
+                result[`${field}[${operator}]`] = Array.isArray(value) ? value.join(',') : String(value);
+            }
+        }
+        // Add sort
+        if (this.sortField) {
+            result.sort = this.sortOrder === 'desc' ? `-${this.sortField}` : this.sortField;
+        }
+        return result;
+    }
+    /**
+     * Build query string
+     */
+    buildQueryString() {
+        const params = this.build();
+        const pairs = Object.entries(params)
+            .filter(([_, value]) => value !== undefined)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        return pairs.length > 0 ? `?${pairs.join('&')}` : '';
+    }
+    /**
+     * Reset the builder
+     */
+    reset() {
+        this.params = {};
+        this.filters.clear();
+        this.sortField = undefined;
+        this.sortOrder = 'asc';
+        return this;
+    }
+    isOperator(value) {
+        return [
+            'eq',
+            'ne',
+            'gt',
+            'gte',
+            'lt',
+            'lte',
+            'in',
+            'contains',
+            'notContains',
+            'beginsWith',
+            'endsWith',
+            'exists',
+        ].includes(value);
+    }
+}

package/dist/sdk.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Main PI-SPI SDK class
+ *
+ * This is the entry point for interacting with the PI-SPI API.
+ * Provides organized access to all API services.
+ */
+import { handleApiError } from './error-handler';
+import type { PiSpiConfig } from './config';
+import { ComptesService } from './services/comptes';
+import { AliasService } from './services/alias';
+import { WebhooksService } from './services/webhooks';
+import { DemandesPaiementService } from './services/demandes-paiement';
+import { DemandesPaiementEnMasseService } from './services/demandes-paiement-en-masse';
+import { PaiementsService } from './services/paiements';
+import { PaiementsEnMasseService } from './services/paiements-en-masse';
+import { RetoursFondsService } from './services/retours-fonds';
+import { DemandesAnnulationService } from './services/demandes-annulation';
+export declare class PiSpiSDK {
+    /**
+     * Accounts service
+     * Handles account-related operations: balance, operations, transfers
+     */
+    readonly comptes: ComptesService;
+    /**
+     * Aliases service
+     * Handles account alias management
+     */
+    readonly alias: AliasService;
+    /**
+     * Webhooks service
+     * Handles webhook configuration and management
+     */
+    readonly webhooks: WebhooksService;
+    /**
+     * Payment requests service
+     * Handles payment request creation and management
+     */
+    readonly demandesPaiement: DemandesPaiementService;
+    /**
+     * Bulk payment requests service
+     * Handles bulk payment request operations
+     */
+    readonly demandesPaiementEnMasse: DemandesPaiementEnMasseService;
+    /**
+     * Payments service
+     * Handles immediate payment operations
+     */
+    readonly paiements: PaiementsService;
+    /**
+     * Bulk payments service
+     * Handles bulk payment operations
+     */
+    readonly paiementsEnMasse: PaiementsEnMasseService;
+    /**
+     * Fund returns service
+     * Handles fund return operations
+     */
+    readonly retoursFonds: RetoursFondsService;
+    /**
+     * Cancellation requests service
+     * Handles payment cancellation requests
+     */
+    readonly demandesAnnulation: DemandesAnnulationService;
+    /**
+     * Initialize the PI-SPI SDK
+     *
+     * @param config - SDK configuration
+     *
+     * @example
+     * ```typescript
+     * const sdk = new PiSpiSDK({
+     *   baseUrl: 'https://sandbox.api.pi-bceao.com/piz/v1',
+     *   accessToken: 'your-oauth2-token',
+     * });
+     * ```
+     */
+    constructor(config: PiSpiConfig);
+    /**
+     * Update the access token
+     * Useful when tokens are refreshed
+     */
+    setAccessToken(token: string): void;
+    /**
+     * Get the current base URL
+     */
+    getBaseUrl(): string;
+}
+export { handleApiError };

package/dist/sdk.js

@@ -0,0 +1,107 @@
+/**
+ * Main PI-SPI SDK class
+ *
+ * This is the entry point for interacting with the PI-SPI API.
+ * Provides organized access to all API services.
+ */
+import { handleApiError } from './error-handler';
+import { ComptesService } from './services/comptes';
+import { AliasService } from './services/alias';
+import { WebhooksService } from './services/webhooks';
+import { DemandesPaiementService } from './services/demandes-paiement';
+import { DemandesPaiementEnMasseService } from './services/demandes-paiement-en-masse';
+import { PaiementsService } from './services/paiements';
+import { PaiementsEnMasseService } from './services/paiements-en-masse';
+import { RetoursFondsService } from './services/retours-fonds';
+import { DemandesAnnulationService } from './services/demandes-annulation';
+// OpenAPI will be imported from generated code after running pnpm run generate
+// For now, we'll use a dynamic import approach
+let OpenAPI;
+// Try to import generated OpenAPI config
+async function loadOpenAPI() {
+    try {
+        const generated = await import('./generated');
+        return generated.OpenAPI;
+    }
+    catch {
+        // Return placeholder if not generated yet
+        return {
+            BASE: 'https://sandbox.api.pi-bceao.com/piz/v1',
+            TOKEN: undefined,
+            HEADERS: undefined,
+        };
+    }
+}
+export class PiSpiSDK {
+    /**
+     * Initialize the PI-SPI SDK
+     *
+     * @param config - SDK configuration
+     *
+     * @example
+     * ```typescript
+     * const sdk = new PiSpiSDK({
+     *   baseUrl: 'https://sandbox.api.pi-bceao.com/piz/v1',
+     *   accessToken: 'your-oauth2-token',
+     * });
+     * ```
+     */
+    constructor(config) {
+        // Initialize OpenAPI configuration synchronously
+        // Note: This will work better after code generation when OpenAPI is properly exported
+        try {
+            // In a real scenario, we'd import this properly
+            // For now, we'll set it up directly
+            OpenAPI = {
+                BASE: config.baseUrl || 'https://sandbox.api.pi-bceao.com/piz/v1',
+                TOKEN: config.accessToken,
+                HEADERS: {
+                    ...config.headers,
+                    Authorization: `Bearer ${config.accessToken}`,
+                },
+            };
+        }
+        catch {
+            // Fallback configuration
+            OpenAPI = {
+                BASE: config.baseUrl || 'https://sandbox.api.pi-bceao.com/piz/v1',
+                TOKEN: config.accessToken,
+                HEADERS: {
+                    ...config.headers,
+                    Authorization: `Bearer ${config.accessToken}`,
+                },
+            };
+        }
+        // Initialize services
+        this.comptes = new ComptesService();
+        this.alias = new AliasService();
+        this.webhooks = new WebhooksService();
+        this.demandesPaiement = new DemandesPaiementService();
+        this.demandesPaiementEnMasse = new DemandesPaiementEnMasseService();
+        this.paiements = new PaiementsService();
+        this.paiementsEnMasse = new PaiementsEnMasseService();
+        this.retoursFonds = new RetoursFondsService();
+        this.demandesAnnulation = new DemandesAnnulationService();
+    }
+    /**
+     * Update the access token
+     * Useful when tokens are refreshed
+     */
+    setAccessToken(token) {
+        if (OpenAPI) {
+            OpenAPI.TOKEN = token;
+            OpenAPI.HEADERS = {
+                ...OpenAPI.HEADERS,
+                Authorization: `Bearer ${token}`,
+            };
+        }
+    }
+    /**
+     * Get the current base URL
+     */
+    getBaseUrl() {
+        return OpenAPI?.BASE || 'https://sandbox.api.pi-bceao.com/piz/v1';
+    }
+}
+// Export error handler for advanced use cases
+export { handleApiError };

package/dist/services/alias.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Aliases service wrapper
+ *
+ * Provides methods for managing account aliases.
+ *
+ * @example
+ * ```typescript
+ * // Create a SHID alias (available for all client types)
+ * const alias = await sdk.alias.create({
+ *   compte: 'CIC2344256727788288822',
+ *   type: AliasType.SHID
+ * });
+ * // Returns: { cle: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f', type: 'SHID', ... }
+ *
+ * // Create an MCOD alias (business clients only)
+ * const merchantAlias = await sdk.alias.create({
+ *   compte: 'SNC2344256727788288822',
+ *   type: AliasType.MCOD
+ * });
+ * // Returns: { cle: 'SNF00_2E4TY', type: 'MCOD', ... }
+ * ```
+ */
+import { BaseService } from './base';
+import type { QueryParams } from '../query-builder';
+import type { AliasType } from '../types/alias';
+export declare class AliasService extends BaseService {
+    /**
+     * Create an account alias
+     *
+     * **Alias Types:**
+     * - `SHID`: System-generated unique payment address (UUID format, 36 chars). Available for all client types (P, C, B, G)
+     * - `MCOD`: Merchant code for USSD payments. Available for business clients only (C, B, G)
+     * - `MBNO`: Mobile phone number. Available for individuals only (P)
+     *
+     * **Limits:**
+     * - Default: 20 aliases per account
+     * - Limit can be increased based on client needs
+     *
+     * @param alias - Alias creation data
+     * @param alias.compte - Account number (e.g., 'CIC2344256727788288822')
+     * @param alias.type - Alias type: 'SHID', 'MCOD', or 'MBNO'
+     * @returns Created alias with generated `cle` (key) value
+     * @throws {PiSpiError} If account not found or limit exceeded
+     *
+     * @example
+     * ```typescript
+     * // For business clients (C, B, G)
+     * await sdk.alias.create({
+     *   compte: 'SNC2344256727788288822',
+     *   type: AliasType.SHID
+     * });
+     * ```
+     */
+    create(alias: {
+        compte: string;
+        type: AliasType;
+    }): Promise<never>;
+    /**
+     * List aliases for an account
+     *
+     * @param compte - Account number
+     * @param params - Query parameters for pagination
+     * @returns Paginated list of aliases
+     */
+    list(compte: string, params?: QueryParams): Promise<never>;
+    /**
+     * Delete an alias
+     *
+     * @param alias - Alias identifier
+     */
+    delete(alias: string): Promise<never>;
+}

package/dist/services/alias.js

@@ -0,0 +1,82 @@
+/**
+ * Aliases service wrapper
+ *
+ * Provides methods for managing account aliases.
+ *
+ * @example
+ * ```typescript
+ * // Create a SHID alias (available for all client types)
+ * const alias = await sdk.alias.create({
+ *   compte: 'CIC2344256727788288822',
+ *   type: AliasType.SHID
+ * });
+ * // Returns: { cle: '8b1b2499-3e50-435b-b757-ac7a83d8aa7f', type: 'SHID', ... }
+ *
+ * // Create an MCOD alias (business clients only)
+ * const merchantAlias = await sdk.alias.create({
+ *   compte: 'SNC2344256727788288822',
+ *   type: AliasType.MCOD
+ * });
+ * // Returns: { cle: 'SNF00_2E4TY', type: 'MCOD', ... }
+ * ```
+ */
+import { BaseService } from './base';
+export class AliasService extends BaseService {
+    /**
+     * Create an account alias
+     *
+     * **Alias Types:**
+     * - `SHID`: System-generated unique payment address (UUID format, 36 chars). Available for all client types (P, C, B, G)
+     * - `MCOD`: Merchant code for USSD payments. Available for business clients only (C, B, G)
+     * - `MBNO`: Mobile phone number. Available for individuals only (P)
+     *
+     * **Limits:**
+     * - Default: 20 aliases per account
+     * - Limit can be increased based on client needs
+     *
+     * @param alias - Alias creation data
+     * @param alias.compte - Account number (e.g., 'CIC2344256727788288822')
+     * @param alias.type - Alias type: 'SHID', 'MCOD', or 'MBNO'
+     * @returns Created alias with generated `cle` (key) value
+     * @throws {PiSpiError} If account not found or limit exceeded
+     *
+     * @example
+     * ```typescript
+     * // For business clients (C, B, G)
+     * await sdk.alias.create({
+     *   compte: 'SNC2344256727788288822',
+     *   type: AliasType.SHID
+     * });
+     * ```
+     */
+    async create(alias) {
+        return this.execute(async () => {
+            // This will call the generated service after codegen
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * List aliases for an account
+     *
+     * @param compte - Account number
+     * @param params - Query parameters for pagination
+     * @returns Paginated list of aliases
+     */
+    async list(compte, params) {
+        return this.execute(async () => {
+            // This will call the generated service after codegen
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+    /**
+     * Delete an alias
+     *
+     * @param alias - Alias identifier
+     */
+    async delete(alias) {
+        return this.execute(async () => {
+            // This will call the generated service after codegen
+            throw new Error('Service not yet generated. Run "pnpm run generate" first.');
+        });
+    }
+}

package/dist/services/base.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Base service class with common error handling
+ */
+export declare abstract class BaseService {
+    /**
+     * Wrap an async operation with error handling
+     */
+    protected execute<T>(operation: () => Promise<T>): Promise<T>;
+}

package/dist/services/base.js

@@ -0,0 +1,17 @@
+/**
+ * Base service class with common error handling
+ */
+import { handleApiError } from '../error-handler';
+export class BaseService {
+    /**
+     * Wrap an async operation with error handling
+     */
+    async execute(operation) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            handleApiError(error);
+        }
+    }
+}