pi-spi-sdk 0.1.0

package/dist/utils/index.js

@@ -0,0 +1,115 @@
+/**
+ * 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 function formatAmount(centimes) {
+    const xof = centimes / 100;
+    return new Intl.NumberFormat('fr-FR', {
+        style: 'currency',
+        currency: 'XOF',
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0,
+    }).format(xof);
+}
+/**
+ * Convert XOF to centimes
+ * @param xof - Amount in XOF
+ * @returns Amount in centimes
+ */
+export function xofToCentimes(xof) {
+    return Math.round(xof * 100);
+}
+/**
+ * Convert centimes to XOF
+ * @param centimes - Amount in centimes
+ * @returns Amount in XOF
+ */
+export function centimesToXof(centimes) {
+    return centimes / 100;
+}
+/**
+ * Validate account number format
+ * @param accountNumber - Account number to validate
+ * @returns True if valid format
+ */
+export function isValidAccountNumber(accountNumber) {
+    // PI-SPI account numbers are typically 22 characters
+    // Format: [Country Code][Bank Code][Account Number]
+    // Example: CIC2344256727788288822 (Côte d'Ivoire)
+    return /^[A-Z]{2,3}\d{19,22}$/.test(accountNumber);
+}
+/**
+ * Validate SHID alias format (UUID)
+ * @param alias - Alias to validate
+ * @returns True if valid UUID format
+ */
+export function isValidShidAlias(alias) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(alias);
+}
+/**
+ * Validate phone number format (for MBNO alias)
+ * @param phoneNumber - Phone number to validate
+ * @returns True if valid format
+ */
+export function isValidPhoneNumber(phoneNumber) {
+    // Basic validation for West African phone numbers
+    // Format: +[country code][number] or [country code][number]
+    const phoneRegex = /^\+?[1-9]\d{8,12}$/;
+    return phoneRegex.test(phoneNumber.replace(/[\s-]/g, ''));
+}
+/**
+ * Extract country code from account number
+ * @param accountNumber - Account number
+ * @returns Country code or null
+ */
+export function getCountryFromAccount(accountNumber) {
+    const countryMap = {
+        CI: "Côte d'Ivoire",
+        SN: 'Senegal',
+        BJ: 'Benin',
+        BF: 'Burkina Faso',
+        ML: 'Mali',
+        NE: 'Niger',
+        TG: 'Togo',
+        GW: 'Guinea-Bissau',
+    };
+    const countryCode = accountNumber.substring(0, 2);
+    return countryMap[countryCode] || null;
+}
+/**
+ * Sleep/delay utility
+ * @param ms - Milliseconds to wait
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry a function with exponential backoff
+ * @param fn - Function to retry
+ * @param maxRetries - Maximum number of retries
+ * @param initialDelay - Initial delay in milliseconds
+ */
+export async function retryWithBackoff(fn, maxRetries = 3, initialDelay = 1000) {
+    let lastError;
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (i < maxRetries - 1) {
+                const delay = initialDelay * Math.pow(2, i);
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError ?? new Error('Retry failed with unknown error');
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "pi-spi-sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for PI-SPI Business API - Built by lomi. for the West African fintech community",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "pi-spi",
+    "spi",
+    "bceao",
+    "west-africa",
+    "uemoa",
+    "payment",
+    "interoperability",
+    "mobile-money",
+    "xof",
+    "fcfa",
+    "cfa-franc",
+    "fintech",
+    "sdk",
+    "typescript",
+    "api-client",
+    "benin",
+    "burkina-faso",
+    "ivory-coast",
+    "mali",
+    "niger",
+    "senegal",
+    "togo",
+    "guinea-bissau"
+  ],
+  "author": "lomi. <hello@lomi.africa> (https://lomi.africa)",
+  "license": "MIT",
+  "homepage": "https://github.com/lomiafrica/pi-spi-sdk",
+  "bugs": {
+    "url": "https://github.com/lomiafrica/pi-spi-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lomiafrica/pi-spi-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.8.4",
+    "dotenv": "^16.4.5",
+    "form-data": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/form-data": "^2.5.2",
+    "@types/node": "^20.10.6",
+    "openapi-typescript-codegen": "^0.29.0",
+    "prettier": "^3.2.5",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\" \"*.{json,md}\" \"scripts/**/*.{js,ts}\"",
+    "prepublish": "pnpm run generate && pnpm run build",
+    "generate": "node scripts/pre-generate.js && openapi --input ./openapi.json --output ./src/generated --client axios --useOptions && node scripts/post-generate.js"
+  }
+}

package/scripts/post-generate.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Post-generation script
+ *
+ * This script runs after OpenAPI code generation to set up the SDK properly.
+ * It updates the OpenAPI base URL, fixes empty types, and ensures proper exports.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const rootDir = join(__dirname, '..');
+const generatedOpenAPIPath = join(rootDir, 'src/generated/core/OpenAPI.ts');
+const modelsDir = join(rootDir, 'src/generated/models');
+
+// Known empty types and their proper definitions
+const emptyTypeFixes = {
+  CompteTransfertIntraRequest: `{
+    txId: string;
+    montant: number;
+    motif?: string;
+    payeurNumero?: string;
+    payeNumero?: string;
+    payeurAlias?: string;
+    payeAlias?: string;
+}`,
+  WebhookModificationRequest: `{
+    callbackUrl?: string;
+    alias?: string;
+}`,
+  remise: `{
+    montant?: number;
+    taux?: number;
+}`,
+};
+
+/**
+ * Fix empty type definitions in generated files
+ */
+function fixEmptyTypes() {
+  try {
+    const files = readdirSync(modelsDir);
+    let fixedCount = 0;
+
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue;
+
+      const filePath = join(modelsDir, file);
+      let content = readFileSync(filePath, 'utf-8');
+
+      // Fix empty type definitions
+      // Pattern: export type TypeName = ;
+      const emptyTypePattern = /export type (\w+) = \s*;/g;
+      let match;
+      let modified = false;
+
+      while ((match = emptyTypePattern.exec(content)) !== null) {
+        const typeName = match[1];
+
+        // Check if we have a fix for this type
+        if (emptyTypeFixes[typeName]) {
+          content = content.replace(
+            `export type ${typeName} = ;`,
+            `export type ${typeName} = ${emptyTypeFixes[typeName]};`
+          );
+          fixedCount++;
+          modified = true;
+          console.log(`  ✅ Fixed empty type: ${typeName}`);
+        }
+      }
+
+      // Fix inline empty remise types
+      // Pattern: remise?: ; or remise: ;
+      const remisePattern = /(\s+)(remise)\??:\s*;/g;
+      if (remisePattern.test(content)) {
+        content = content.replace(remisePattern, `$1$2?: ${emptyTypeFixes['remise']}`);
+        fixedCount++;
+        modified = true;
+        console.log(`  ✅ Fixed remise type in: ${file}`);
+      }
+
+      // Fix standalone remise type definitions
+      if (content.includes('remise: ;')) {
+        content = content.replace(/remise:\s*;/g, `remise: ${emptyTypeFixes['remise']}`);
+        fixedCount++;
+        modified = true;
+        console.log(`  ✅ Fixed remise type definition in: ${file}`);
+      }
+
+      if (modified) {
+        writeFileSync(filePath, content, 'utf-8');
+      }
+    }
+
+    if (fixedCount > 0) {
+      console.log(`✅ Fixed ${fixedCount} empty type definition(s)`);
+    } else {
+      console.log('✅ No empty types found to fix');
+    }
+  } catch (error) {
+    console.warn('⚠️  Could not fix empty types:', error.message);
+  }
+}
+
+try {
+  let content = readFileSync(generatedOpenAPIPath, 'utf-8');
+
+  // Update the default BASE URL to match PI-SPI sandbox
+  content = content.replace(/BASE: '.*'/, "BASE: 'https://sandbox.api.pi-bceao.com/piz/v1'");
+
+  // Update VERSION if needed
+  content = content.replace(/VERSION: '.*'/, "VERSION: '1.0.0'");
+
+  writeFileSync(generatedOpenAPIPath, content, 'utf-8');
+  console.log('✅ Updated OpenAPI configuration');
+} catch (error) {
+  console.warn('⚠️  Could not update OpenAPI.ts:', error.message);
+  console.log("   This is okay if the file doesn't exist yet.");
+}
+
+// Fix empty types
+console.log('🔧 Fixing empty type definitions...');
+fixEmptyTypes();
+
+console.log('✅ Post-generation setup complete');

package/scripts/pre-generate.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Pre-generation validation and fix script
+ *
+ * This script validates the OpenAPI spec and fixes common issues
+ * before running the code generator.
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const specPath = join(__dirname, '../openapi.json');
+
+try {
+  console.log('📋 Validating OpenAPI specification...');
+
+  const specContent = readFileSync(specPath, 'utf-8');
+  const spec = JSON.parse(specContent);
+
+  if (!spec.openapi) {
+    throw new Error('Missing "openapi" field');
+  }
+
+  if (!spec.info) {
+    throw new Error('Missing "info" field');
+  }
+
+  if (!spec.paths || typeof spec.paths !== 'object') {
+    throw new Error('Missing or invalid "paths" field');
+  }
+
+  if (!spec.components || typeof spec.components !== 'object') {
+    throw new Error('Missing or invalid "components" field');
+  }
+
+  // Ensure tags array exists (even if empty)
+  if (!spec.tags || !Array.isArray(spec.tags)) {
+    console.log('⚠️  Tags array missing or invalid, creating empty array...');
+    spec.tags = [];
+  }
+
+  // Ensure each path operation has tags and remove null operations
+  let fixedPaths = 0;
+  let removedNullOps = 0;
+  const httpMethods = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head'];
+
+  for (const [path, pathItem] of Object.entries(spec.paths)) {
+    if (pathItem && typeof pathItem === 'object') {
+      for (const [key, value] of Object.entries(pathItem)) {
+        // Check if this is an HTTP method
+        if (httpMethods.includes(key.toLowerCase())) {
+          // Remove null operations (sometimes used to indicate method not available)
+          if (value === null || value === undefined) {
+            console.log(`⚠️  Removing null operation ${key.toUpperCase()} ${path}`);
+            delete pathItem[key];
+            removedNullOps++;
+            continue;
+          }
+
+          // Ensure the operation object exists and has tags
+          if (typeof value !== 'object') {
+            console.log(`⚠️  Skipping invalid operation ${key.toUpperCase()} ${path}`);
+            continue;
+          }
+
+          // Ensure tags array exists
+          if (!value.tags || !Array.isArray(value.tags) || value.tags.length === 0) {
+            console.log(`⚠️  Adding default tag to ${key.toUpperCase()} ${path}`);
+            value.tags = ['Default'];
+            fixedPaths++;
+          }
+
+          // Ensure operationId exists (required by some generators)
+          if (!value.operationId) {
+            // Generate a default operationId from method and path
+            const pathParts = path.split('/').filter((p) => p && !p.startsWith('{'));
+            const operationId =
+              key.toLowerCase() +
+              pathParts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+            value.operationId = operationId;
+            console.log(`⚠️  Added operationId "${operationId}" to ${key.toUpperCase()} ${path}`);
+          }
+        }
+      }
+    }
+  }
+
+  if (removedNullOps > 0) {
+    console.log(`✅ Removed ${removedNullOps} null operations`);
+  }
+
+  if (fixedPaths > 0) {
+    console.log(`✅ Fixed ${fixedPaths} path operations`);
+  }
+
+  // Write back the fixed spec
+  writeFileSync(specPath, JSON.stringify(spec, null, 2), 'utf-8');
+  console.log('✅ OpenAPI specification validated and fixed');
+} catch (error) {
+  console.error('❌ Error validating OpenAPI spec:', error);
+  process.exit(1);
+}