paybridge 0.1.0

package/dist/index.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * PayBridge — Unified payment SDK for Node.js
+ * One API. Every payment provider.
+ *
+ * @see https://github.com/kobie3717/paybridge
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayBridge = void 0;
+const softycomp_1 = require("./providers/softycomp");
+const yoco_1 = require("./providers/yoco");
+const ozow_1 = require("./providers/ozow");
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils/currency"), exports);
+class PayBridge {
+    constructor(config) {
+        this.provider = this.createProvider(config);
+    }
+    /**
+     * Create provider instance based on config
+     */
+    createProvider(config) {
+        const { provider, credentials, sandbox = true, webhookSecret } = config;
+        switch (provider) {
+            case 'softycomp':
+                if (!credentials.apiKey || !credentials.secretKey) {
+                    throw new Error('SoftyComp requires apiKey and secretKey');
+                }
+                return new softycomp_1.SoftyCompProvider({
+                    apiKey: credentials.apiKey,
+                    secretKey: credentials.secretKey,
+                    sandbox,
+                    webhookSecret,
+                });
+            case 'yoco':
+                if (!credentials.apiKey) {
+                    throw new Error('Yoco requires apiKey (secret key)');
+                }
+                return new yoco_1.YocoProvider({
+                    apiKey: credentials.apiKey,
+                    sandbox,
+                    webhookSecret,
+                });
+            case 'ozow':
+                if (!credentials.apiKey || !credentials.siteCode || !credentials.privateKey) {
+                    throw new Error('Ozow requires apiKey, siteCode, and privateKey');
+                }
+                return new ozow_1.OzowProvider({
+                    apiKey: credentials.apiKey,
+                    siteCode: credentials.siteCode,
+                    privateKey: credentials.privateKey,
+                    sandbox,
+                });
+            case 'payfast':
+            case 'paystack':
+            case 'stripe':
+            case 'peach':
+                throw new Error(`Provider ${provider} not yet implemented. Coming soon!`);
+            default:
+                throw new Error(`Unknown provider: ${provider}`);
+        }
+    }
+    // ==================== Payment Methods ====================
+    /**
+     * Create a one-time payment
+     *
+     * @example
+     * ```typescript
+     * const payment = await pay.createPayment({
+     *   amount: 299.00,
+     *   currency: 'ZAR',
+     *   reference: 'INV-001',
+     *   customer: {
+     *     name: 'John Doe',
+     *     email: 'john@example.com',
+     *     phone: '0825551234'
+     *   },
+     *   urls: {
+     *     success: 'https://myapp.com/success',
+     *     cancel: 'https://myapp.com/cancel',
+     *     webhook: 'https://myapp.com/webhook'
+     *   }
+     * });
+     *
+     * // Redirect customer to payment page
+     * res.redirect(payment.checkoutUrl);
+     * ```
+     */
+    async createPayment(params) {
+        return this.provider.createPayment(params);
+    }
+    /**
+     * Create a recurring subscription
+     *
+     * @example
+     * ```typescript
+     * const subscription = await pay.createSubscription({
+     *   amount: 299.00,
+     *   currency: 'ZAR',
+     *   interval: 'monthly',
+     *   reference: 'SUB-001',
+     *   customer: {
+     *     name: 'John Doe',
+     *     email: 'john@example.com'
+     *   },
+     *   urls: {
+     *     success: 'https://myapp.com/success',
+     *     cancel: 'https://myapp.com/cancel',
+     *     webhook: 'https://myapp.com/webhook'
+     *   },
+     *   startDate: '2026-04-01'
+     * });
+     * ```
+     */
+    async createSubscription(params) {
+        return this.provider.createSubscription(params);
+    }
+    /**
+     * Get payment status
+     *
+     * @example
+     * ```typescript
+     * const payment = await pay.getPayment('pay_123');
+     * if (payment.status === 'completed') {
+     *   console.log('Payment received!');
+     * }
+     * ```
+     */
+    async getPayment(id) {
+        return this.provider.getPayment(id);
+    }
+    /**
+     * Process a refund (full or partial)
+     *
+     * @example
+     * ```typescript
+     * // Full refund
+     * const refund = await pay.refund({
+     *   paymentId: 'pay_123'
+     * });
+     *
+     * // Partial refund
+     * const refund = await pay.refund({
+     *   paymentId: 'pay_123',
+     *   amount: 100.00,
+     *   reason: 'Customer request'
+     * });
+     * ```
+     */
+    async refund(params) {
+        return this.provider.refund(params);
+    }
+    // ==================== Webhooks ====================
+    /**
+     * Parse webhook payload into unified event format
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', express.json(), (req, res) => {
+     *   const event = pay.parseWebhook(req.body, req.headers);
+     *
+     *   switch (event.type) {
+     *     case 'payment.completed':
+     *       console.log('Payment completed:', event.payment);
+     *       break;
+     *     case 'payment.failed':
+     *       console.log('Payment failed:', event.payment);
+     *       break;
+     *   }
+     *
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    parseWebhook(body, headers) {
+        return this.provider.parseWebhook(body, headers);
+    }
+    /**
+     * Verify webhook signature
+     *
+     * @example
+     * ```typescript
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   if (!pay.verifyWebhook(req.body, req.headers)) {
+     *     return res.status(400).send('Invalid signature');
+     *   }
+     *
+     *   const event = pay.parseWebhook(req.body, req.headers);
+     *   // Process event...
+     *
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifyWebhook(body, headers) {
+        return this.provider.verifyWebhook(body, headers);
+    }
+    // ==================== Helpers ====================
+    /**
+     * Get provider name
+     */
+    getProviderName() {
+        return this.provider.name;
+    }
+    /**
+     * Get supported currencies for current provider
+     */
+    getSupportedCurrencies() {
+        return this.provider.supportedCurrencies;
+    }
+}
+exports.PayBridge = PayBridge;
+exports.default = PayBridge;

package/dist/providers/base.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Base payment provider abstract class
+ * All payment providers must extend this class
+ */
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+export declare abstract class PaymentProvider {
+    /**
+     * Provider name (e.g. 'softycomp', 'yoco', 'ozow')
+     */
+    abstract readonly name: string;
+    /**
+     * Supported currencies
+     */
+    abstract readonly supportedCurrencies: string[];
+    /**
+     * Create a one-time payment
+     */
+    abstract createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    /**
+     * Create a recurring subscription
+     */
+    abstract createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    /**
+     * Get payment status
+     */
+    abstract getPayment(id: string): Promise<PaymentResult>;
+    /**
+     * Process a refund (full or partial)
+     */
+    abstract refund(params: RefundParams): Promise<RefundResult>;
+    /**
+     * Parse webhook payload into unified event format
+     */
+    abstract parseWebhook(body: any, headers?: any): WebhookEvent;
+    /**
+     * Verify webhook signature
+     * @returns true if signature is valid, false otherwise
+     */
+    abstract verifyWebhook(body: any, headers?: any): boolean;
+    /**
+     * Validate currency is supported
+     */
+    protected validateCurrency(currency: string): void;
+    /**
+     * Validate future date
+     */
+    protected validateFutureDate(dateStr: string, fieldName: string): void;
+}

package/dist/providers/base.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Base payment provider abstract class
+ * All payment providers must extend this class
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentProvider = void 0;
+class PaymentProvider {
+    /**
+     * Validate currency is supported
+     */
+    validateCurrency(currency) {
+        if (!this.supportedCurrencies.includes(currency)) {
+            throw new Error(`Currency ${currency} not supported by ${this.name}. Supported: ${this.supportedCurrencies.join(', ')}`);
+        }
+    }
+    /**
+     * Validate future date
+     */
+    validateFutureDate(dateStr, fieldName) {
+        const date = new Date(dateStr);
+        const now = new Date();
+        now.setHours(0, 0, 0, 0);
+        if (date <= now) {
+            throw new Error(`${fieldName} must be a future date (minimum tomorrow)`);
+        }
+    }
+}
+exports.PaymentProvider = PaymentProvider;

package/dist/providers/ozow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Ozow payment provider
+ * South African instant EFT payment gateway
+ * @see https://hub.ozow.com
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+interface OzowConfig {
+    apiKey: string;
+    siteCode: string;
+    privateKey: string;
+    sandbox: boolean;
+}
+export declare class OzowProvider extends PaymentProvider {
+    readonly name = "ozow";
+    readonly supportedCurrencies: string[];
+    private apiKey;
+    private siteCode;
+    private privateKey;
+    private sandbox;
+    private baseUrl;
+    constructor(config: OzowConfig);
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    verifyWebhook(body: any, _headers?: any): boolean;
+    private mapOzowStatus;
+    private mapOzowEventType;
+    private generateWebhookHash;
+}
+export {};

package/dist/providers/ozow.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * Ozow payment provider
+ * South African instant EFT payment gateway
+ * @see https://hub.ozow.com
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OzowProvider = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const base_1 = require("./base");
+class OzowProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'ozow';
+        this.supportedCurrencies = ['ZAR'];
+        this.apiKey = config.apiKey;
+        this.siteCode = config.siteCode;
+        this.privateKey = config.privateKey;
+        this.sandbox = config.sandbox;
+        // Ozow API endpoints
+        if (this.sandbox) {
+            this.baseUrl = 'https://stagingapi.ozow.com';
+        }
+        else {
+            this.baseUrl = 'https://api.ozow.com';
+        }
+    }
+    // ==================== Payment Methods ====================
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        // TODO: Implement Ozow payment creation
+        // POST /api/payments
+        // Amount in RANDS (not cents)
+        // Requires SHA512 hash of concatenated fields
+        // Auth: API key in header
+        // Body: {
+        //   SiteCode: "...",
+        //   CountryCode: "ZA",
+        //   CurrencyCode: "ZAR",
+        //   Amount: "299.00",
+        //   TransactionReference: "...",
+        //   BankReference: "...",
+        //   Customer: "John Doe",
+        //   Optional1: "email@example.com",
+        //   Optional2: "0825551234",
+        //   Optional3: "...",
+        //   Optional4: "...",
+        //   Optional5: "...",
+        //   CancelUrl: "...",
+        //   ErrorUrl: "...",
+        //   SuccessUrl: "...",
+        //   NotifyUrl: "...",
+        //   IsTest: true/false,
+        //   HashCheck: "sha512_hash"
+        // }
+        const requestData = {
+            SiteCode: this.siteCode,
+            CountryCode: 'ZA',
+            CurrencyCode: params.currency,
+            Amount: params.amount.toFixed(2),
+            TransactionReference: params.reference,
+            BankReference: params.reference,
+            Customer: params.customer.name,
+            Optional1: params.customer.email,
+            Optional2: params.customer.phone || '',
+            Optional3: params.description || '',
+            CancelUrl: params.urls.cancel,
+            ErrorUrl: params.urls.cancel,
+            SuccessUrl: params.urls.success,
+            NotifyUrl: params.urls.webhook,
+            IsTest: this.sandbox,
+            // HashCheck: this.generateHash(...) // TODO: Implement hash generation
+        };
+        // TODO: Generate SHA512 hash
+        // Hash = SHA512(SiteCode + CountryCode + CurrencyCode + Amount + TransactionReference + BankReference + Optional1 + Optional2 + Optional3 + Optional4 + Optional5 + CancelUrl + ErrorUrl + SuccessUrl + NotifyUrl + IsTest + PrivateKey)
+        console.warn('[PayBridge:Ozow] createPayment not yet implemented:', requestData);
+        throw new Error('Ozow provider not yet fully implemented. Coming soon!');
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        // TODO: Implement Ozow recurring payments
+        // Ozow supports recurring payments via their recurring payment API
+        // Different endpoint and structure from one-time payments
+        console.warn('[PayBridge:Ozow] createSubscription not yet implemented');
+        throw new Error('Ozow subscriptions not yet implemented. Coming soon!');
+    }
+    async getPayment(id) {
+        // TODO: Implement Ozow payment status check
+        // GET /api/payments/{transactionReference}
+        // Auth: API key in header
+        console.warn('[PayBridge:Ozow] getPayment not yet implemented:', id);
+        throw new Error('Ozow getPayment not yet implemented. Coming soon!');
+    }
+    async refund(params) {
+        // TODO: Implement Ozow refund
+        // POST /api/refunds
+        // Auth: API key in header
+        // Body: {
+        //   SiteCode: "...",
+        //   TransactionReference: "...",
+        //   Amount: "299.00", // optional for partial
+        //   HashCheck: "..."
+        // }
+        console.warn('[PayBridge:Ozow] refund not yet implemented:', params);
+        throw new Error('Ozow refunds not yet implemented. Coming soon!');
+    }
+    // ==================== Webhooks ====================
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        // TODO: Map Ozow webhook structure to PayBridge WebhookEvent
+        // Ozow webhook payload structure (form data):
+        // {
+        //   SiteCode: "...",
+        //   TransactionId: "...",
+        //   TransactionReference: "...",
+        //   Amount: "299.00",
+        //   Status: "Complete" | "Cancelled" | "Error" | "Abandoned",
+        //   Optional1: "...",
+        //   Optional2: "...",
+        //   Optional3: "...",
+        //   Optional4: "...",
+        //   Optional5: "...",
+        //   CurrencyCode: "ZAR",
+        //   IsTest: "true" | "false",
+        //   StatusMessage: "...",
+        //   Hash: "sha512_hash"
+        // }
+        const ozowStatus = event.Status;
+        const status = this.mapOzowStatus(ozowStatus);
+        const eventType = this.mapOzowEventType(ozowStatus);
+        return {
+            type: eventType,
+            payment: {
+                id: event.TransactionId || event.TransactionReference,
+                checkoutUrl: '',
+                status,
+                amount: parseFloat(event.Amount || '0'),
+                currency: event.CurrencyCode || 'ZAR',
+                reference: event.TransactionReference,
+                provider: 'ozow',
+                createdAt: new Date().toISOString(),
+            },
+            raw: event,
+        };
+    }
+    verifyWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        const receivedHash = event.Hash;
+        if (!receivedHash) {
+            // No hash provided
+            return true;
+        }
+        // TODO: Verify Ozow SHA512 hash
+        // expectedHash = SHA512(SiteCode + TransactionId + TransactionReference + Amount + Status + Optional1 + Optional2 + Optional3 + Optional4 + Optional5 + CurrencyCode + IsTest + StatusMessage + PrivateKey)
+        const expectedHash = this.generateWebhookHash(event);
+        return receivedHash === expectedHash;
+    }
+    // ==================== Helpers ====================
+    mapOzowStatus(ozowStatus) {
+        const statusMap = {
+            Complete: 'completed',
+            Cancelled: 'cancelled',
+            Error: 'failed',
+            Abandoned: 'cancelled',
+            PendingInvestigation: 'pending',
+        };
+        return statusMap[ozowStatus] || 'pending';
+    }
+    mapOzowEventType(ozowStatus) {
+        const typeMap = {
+            Complete: 'payment.completed',
+            Cancelled: 'payment.cancelled',
+            Error: 'payment.failed',
+            Abandoned: 'payment.cancelled',
+        };
+        return typeMap[ozowStatus] || 'payment.pending';
+    }
+    generateWebhookHash(event) {
+        // TODO: Implement SHA512 hash generation for webhook verification
+        const fields = [
+            event.SiteCode,
+            event.TransactionId,
+            event.TransactionReference,
+            event.Amount,
+            event.Status,
+            event.Optional1 || '',
+            event.Optional2 || '',
+            event.Optional3 || '',
+            event.Optional4 || '',
+            event.Optional5 || '',
+            event.CurrencyCode,
+            event.IsTest,
+            event.StatusMessage || '',
+            this.privateKey,
+        ];
+        const concatenated = fields.join('');
+        return crypto_1.default.createHash('sha512').update(concatenated, 'utf8').digest('hex').toLowerCase();
+    }
+}
+exports.OzowProvider = OzowProvider;

package/dist/providers/softycomp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SoftyComp payment provider
+ * South African bill presentment and debit order platform
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+interface SoftyCompConfig {
+    apiKey: string;
+    secretKey: string;
+    sandbox: boolean;
+    webhookSecret?: string;
+}
+export declare class SoftyCompProvider extends PaymentProvider {
+    readonly name = "softycomp";
+    readonly supportedCurrencies: string[];
+    private apiKey;
+    private secretKey;
+    private sandbox;
+    private baseUrl;
+    private webhookSecret?;
+    private token;
+    private tokenExpiry;
+    constructor(config: SoftyCompConfig);
+    private authenticate;
+    private apiRequest;
+    createPayment(params: CreatePaymentParams): Promise<PaymentResult>;
+    createSubscription(params: CreateSubscriptionParams): Promise<SubscriptionResult>;
+    getPayment(id: string): Promise<PaymentResult>;
+    refund(params: RefundParams): Promise<RefundResult>;
+    parseWebhook(body: any, _headers?: any): WebhookEvent;
+    verifyWebhook(body: string | Buffer, headers?: any): boolean;
+    private mapBillStatus;
+}
+export {};