paybridge 0.1.0

package/dist/providers/softycomp.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * SoftyComp payment provider
+ * South African bill presentment and debit order platform
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoftyCompProvider = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const base_1 = require("./base");
+class SoftyCompProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'softycomp';
+        this.supportedCurrencies = ['ZAR'];
+        // Token cache
+        this.token = null;
+        this.tokenExpiry = 0;
+        this.apiKey = config.apiKey;
+        this.secretKey = config.secretKey;
+        this.sandbox = config.sandbox;
+        this.webhookSecret = config.webhookSecret;
+        // Base URL mapping
+        if (this.sandbox) {
+            this.baseUrl = 'https://sandbox.softycomp.co.za/SoftyCompBureauAPI';
+        }
+        else {
+            this.baseUrl = 'https://api.softycomp.co.za/SoftyCompBureauAPI';
+        }
+    }
+    // ==================== Authentication ====================
+    async authenticate() {
+        // Return cached token if still valid (with 60s buffer)
+        if (this.token && Date.now() < this.tokenExpiry - 60000) {
+            return this.token;
+        }
+        const response = await fetch(`${this.baseUrl}/api/auth/generatetoken`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                apiKey: this.apiKey,
+                apiSecret: this.secretKey,
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`SoftyComp authentication failed: ${response.status} - ${errorText}`);
+        }
+        const data = (await response.json());
+        this.token = data.token;
+        this.tokenExpiry = new Date(data.expiration).getTime();
+        return this.token;
+    }
+    async apiRequest(method, path, data) {
+        const token = await this.authenticate();
+        const url = `${this.baseUrl}${path}`;
+        const response = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`SoftyComp API error (${method} ${path}): ${response.status} - ${errorText}`);
+        }
+        const contentType = response.headers.get('content-type');
+        if (contentType && contentType.includes('application/json')) {
+            return (await response.json());
+        }
+        return (await response.text());
+    }
+    // ==================== Payment Methods ====================
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        // Build the bill item (once-off payment)
+        const item = {
+            Description: params.description || 'Payment',
+            Amount: parseFloat(params.amount.toFixed(2)),
+            FrequencyTypeID: 1, // Once-off
+            DisplayCompanyName: 'Your Company',
+            DisplayCompanyContactNo: '',
+            DisplayCompanyEmailAddress: params.customer.email,
+        };
+        // Build the bill request
+        const billData = {
+            Name: params.customer.name,
+            ModeTypeID: 4, // Plugin mode (returns payment URL)
+            Emailaddress: params.customer.email,
+            Cellno: params.customer.phone || '',
+            UserReference: params.reference,
+            Items: [item],
+            ScheduledDateTime: null,
+            CallbackUrl: params.urls.webhook,
+            SuccessURL: params.urls.success,
+            FailURL: params.urls.cancel,
+            NotifyURL: params.urls.webhook,
+            CancelURL: params.urls.cancel,
+        };
+        const result = await this.apiRequest('POST', '/api/paygatecontroller/requestbillpresentment', billData);
+        if (!result.success) {
+            throw new Error(`Failed to create payment: ${result.message}`);
+        }
+        return {
+            id: result.reference,
+            checkoutUrl: result.paymentURL,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency,
+            reference: params.reference,
+            provider: 'softycomp',
+            createdAt: new Date().toISOString(),
+            expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(),
+            raw: result,
+        };
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        // Map interval to SoftyComp frequency: 2=monthly, 7=yearly
+        let frequencyTypeID;
+        if (params.interval === 'monthly') {
+            frequencyTypeID = 2;
+        }
+        else if (params.interval === 'yearly') {
+            frequencyTypeID = 7;
+        }
+        else {
+            throw new Error(`SoftyComp does not support ${params.interval} subscriptions. Use monthly or yearly.`);
+        }
+        // Parse and validate start date
+        let startDate;
+        if (params.startDate) {
+            this.validateFutureDate(params.startDate, 'startDate');
+            startDate = new Date(params.startDate);
+        }
+        else {
+            // Default to tomorrow
+            startDate = new Date();
+            startDate.setDate(startDate.getDate() + 1);
+        }
+        // Build the bill item (recurring)
+        const item = {
+            Description: params.description || 'Subscription',
+            Amount: parseFloat(params.amount.toFixed(2)),
+            FrequencyTypeID: frequencyTypeID,
+            DisplayCompanyName: 'Your Company',
+            DisplayCompanyContactNo: '',
+            DisplayCompanyEmailAddress: params.customer.email,
+            CommencementDate: startDate.toISOString().split('T')[0],
+            RecurringDay: params.billingDay || startDate.getDate(),
+            RecurringMonth: params.interval === 'yearly' ? startDate.getMonth() + 1 : null,
+            DayOfWeek: null,
+            ExpiryDate: null,
+            InitialAmount: null,
+            ToCollectAmount: null,
+        };
+        // Build the bill request
+        const billData = {
+            Name: params.customer.name,
+            ModeTypeID: 4,
+            Emailaddress: params.customer.email,
+            Cellno: params.customer.phone || '',
+            UserReference: params.reference,
+            Items: [item],
+            ScheduledDateTime: null,
+            CallbackUrl: params.urls.webhook,
+            SuccessURL: params.urls.success,
+            FailURL: params.urls.cancel,
+            NotifyURL: params.urls.webhook,
+            CancelURL: params.urls.cancel,
+        };
+        const result = await this.apiRequest('POST', '/api/paygatecontroller/requestbillpresentment', billData);
+        if (!result.success) {
+            throw new Error(`Failed to create subscription: ${result.message}`);
+        }
+        return {
+            id: result.reference,
+            checkoutUrl: result.paymentURL,
+            status: 'pending',
+            amount: params.amount,
+            currency: params.currency,
+            interval: params.interval,
+            reference: params.reference,
+            provider: 'softycomp',
+            startsAt: startDate.toISOString(),
+            createdAt: new Date().toISOString(),
+            raw: result,
+        };
+    }
+    async getPayment(id) {
+        const result = await this.apiRequest('GET', `/api/paygatecontroller/listBillPresentmentDetails/${id}/${id}`);
+        // Map status: 1=pending, 2=completed, 3=failed, 4/5=cancelled
+        const statusTypeID = result?.statusTypeID || result?.status || 1;
+        const status = this.mapBillStatus(statusTypeID);
+        return {
+            id: result?.reference || id,
+            checkoutUrl: '', // Not available from status endpoint
+            status,
+            amount: parseFloat(result?.amount || '0'),
+            currency: 'ZAR',
+            reference: result?.userReference || id,
+            provider: 'softycomp',
+            createdAt: result?.createdDate || new Date().toISOString(),
+            raw: result,
+        };
+    }
+    async refund(params) {
+        const refundData = {
+            Reference: params.paymentId,
+            UserReference: params.paymentId,
+        };
+        if (params.amount !== undefined) {
+            refundData.Amount = parseFloat(params.amount.toFixed(2));
+        }
+        const result = await this.apiRequest('POST', '/api/paygatecontroller/requestCreditTransaction', refundData);
+        return {
+            id: result?.reference || `refund_${params.paymentId}_${Date.now()}`,
+            status: result?.success ? 'completed' : 'pending',
+            amount: params.amount || 0,
+            currency: 'ZAR',
+            paymentId: params.paymentId,
+            createdAt: new Date().toISOString(),
+            raw: result,
+        };
+    }
+    // ==================== Webhooks ====================
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        // activityTypeID mapping: 1=Pending, 2=Successful, 3=Failed, 4=Cancelled
+        let eventType = 'payment.pending';
+        let status = 'pending';
+        switch (event.activityTypeID) {
+            case 2:
+                eventType = 'payment.completed';
+                status = 'completed';
+                break;
+            case 3:
+                eventType = 'payment.failed';
+                status = 'failed';
+                break;
+            case 4:
+                eventType = 'payment.cancelled';
+                status = 'cancelled';
+                break;
+            default:
+                eventType = 'payment.pending';
+                status = 'pending';
+        }
+        return {
+            type: eventType,
+            payment: {
+                id: event.reference,
+                checkoutUrl: '',
+                status,
+                amount: event.amount,
+                currency: 'ZAR',
+                reference: event.userReference,
+                provider: 'softycomp',
+                createdAt: event.transactionDate,
+            },
+            raw: event,
+        };
+    }
+    verifyWebhook(body, headers) {
+        const signature = headers?.signature || headers?.['x-signature'];
+        if (!signature || !this.webhookSecret) {
+            // No signature validation configured
+            return true;
+        }
+        const expectedSignature = crypto_1.default
+            .createHmac('sha256', this.webhookSecret)
+            .update(body)
+            .digest('hex');
+        return signature === expectedSignature || signature === `sha256=${expectedSignature}`;
+    }
+    // ==================== Helpers ====================
+    mapBillStatus(statusTypeID) {
+        switch (Number(statusTypeID)) {
+            case 1: return 'pending'; // New
+            case 2: return 'completed'; // Paid
+            case 3: return 'failed'; // Failed
+            case 4: return 'cancelled'; // Expired
+            case 5: return 'cancelled'; // Cancelled
+            default: return 'pending';
+        }
+    }
+}
+exports.SoftyCompProvider = SoftyCompProvider;

package/dist/providers/yoco.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Yoco payment provider
+ * South African online payment gateway
+ * @see https://developer.yoco.com
+ */
+import { PaymentProvider } from './base';
+import { CreatePaymentParams, PaymentResult, CreateSubscriptionParams, SubscriptionResult, RefundParams, RefundResult, WebhookEvent } from '../types';
+interface YocoConfig {
+    apiKey: string;
+    sandbox: boolean;
+    webhookSecret?: string;
+}
+export declare class YocoProvider extends PaymentProvider {
+    readonly name = "yoco";
+    readonly supportedCurrencies: string[];
+    private apiKey;
+    private sandbox;
+    private baseUrl;
+    private webhookSecret?;
+    constructor(config: YocoConfig);
+    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 mapYocoStatus;
+    private mapYocoEventType;
+}
+export {};

package/dist/providers/yoco.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Yoco payment provider
+ * South African online payment gateway
+ * @see https://developer.yoco.com
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YocoProvider = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const base_1 = require("./base");
+const currency_1 = require("../utils/currency");
+class YocoProvider extends base_1.PaymentProvider {
+    constructor(config) {
+        super();
+        this.name = 'yoco';
+        this.supportedCurrencies = ['ZAR'];
+        this.apiKey = config.apiKey;
+        this.sandbox = config.sandbox;
+        this.webhookSecret = config.webhookSecret;
+        // Yoco uses same API for sandbox and production, differentiated by API keys
+        this.baseUrl = 'https://payments.yoco.com/api/v1';
+    }
+    // ==================== Payment Methods ====================
+    async createPayment(params) {
+        this.validateCurrency(params.currency);
+        // TODO: Implement Yoco checkout creation
+        // POST /v1/checkouts
+        // Amount must be in CENTS (minor unit)
+        // Auth: Bearer {secret_key}
+        // Body: {
+        //   amount: 29900, // cents
+        //   currency: "ZAR",
+        //   cancelUrl: "...",
+        //   successUrl: "...",
+        //   failureUrl: "...",
+        //   metadata: { ... }
+        // }
+        const amountInCents = (0, currency_1.toMinorUnit)(params.amount, params.currency);
+        const requestBody = {
+            amount: amountInCents,
+            currency: params.currency,
+            cancelUrl: params.urls.cancel,
+            successUrl: params.urls.success,
+            failureUrl: params.urls.cancel,
+            metadata: {
+                reference: params.reference,
+                description: params.description,
+                customerName: params.customer.name,
+                customerEmail: params.customer.email,
+                ...params.metadata,
+            },
+        };
+        // TODO: Make actual API request
+        console.warn('[PayBridge:Yoco] createPayment not yet implemented:', requestBody);
+        throw new Error('Yoco provider not yet fully implemented. Coming soon!');
+    }
+    async createSubscription(params) {
+        this.validateCurrency(params.currency);
+        // TODO: Implement Yoco subscription creation
+        // Yoco may not support subscriptions directly - need to check their API
+        // May need to implement via recurring charges or use Yoco recurring billing
+        console.warn('[PayBridge:Yoco] createSubscription not yet implemented');
+        throw new Error('Yoco subscriptions not yet implemented. Coming soon!');
+    }
+    async getPayment(id) {
+        // TODO: Implement Yoco payment status check
+        // GET /v1/checkouts/{id}
+        // Auth: Bearer {secret_key}
+        console.warn('[PayBridge:Yoco] getPayment not yet implemented:', id);
+        throw new Error('Yoco getPayment not yet implemented. Coming soon!');
+    }
+    async refund(params) {
+        // TODO: Implement Yoco refund
+        // POST /v1/refunds
+        // Amount in CENTS
+        // Auth: Bearer {secret_key}
+        // Body: {
+        //   paymentId: "...",
+        //   amount: 29900 // cents, optional for partial refund
+        // }
+        const amountInCents = params.amount ? (0, currency_1.toMinorUnit)(params.amount, 'ZAR') : undefined;
+        console.warn('[PayBridge:Yoco] refund not yet implemented:', { ...params, amountInCents });
+        throw new Error('Yoco refunds not yet implemented. Coming soon!');
+    }
+    // ==================== Webhooks ====================
+    parseWebhook(body, _headers) {
+        const event = typeof body === 'string' ? JSON.parse(body) : body;
+        // TODO: Map Yoco webhook structure to PayBridge WebhookEvent
+        // Yoco webhook payload structure:
+        // {
+        //   type: "payment.succeeded" | "payment.failed" | "payment.refunded",
+        //   payload: {
+        //     id: "...",
+        //     amount: 29900, // cents
+        //     currency: "ZAR",
+        //     status: "succeeded" | "failed" | "refunded",
+        //     metadata: { ... }
+        //   }
+        // }
+        const yocoStatus = event.payload?.status || event.status;
+        const status = this.mapYocoStatus(yocoStatus);
+        const eventType = this.mapYocoEventType(event.type);
+        return {
+            type: eventType,
+            payment: {
+                id: event.payload?.id || event.id,
+                checkoutUrl: '',
+                status,
+                amount: (0, currency_1.toMajorUnit)(event.payload?.amount || 0, 'ZAR'),
+                currency: 'ZAR',
+                reference: event.payload?.metadata?.reference || '',
+                provider: 'yoco',
+                createdAt: event.payload?.createdDate || new Date().toISOString(),
+            },
+            raw: event,
+        };
+    }
+    verifyWebhook(body, headers) {
+        const signature = headers?.['x-yoco-signature'] || headers?.signature;
+        if (!signature || !this.webhookSecret) {
+            // No signature validation configured
+            return true;
+        }
+        // TODO: Implement Yoco signature validation
+        // Yoco uses HMAC-SHA256 with X-Yoco-Signature header
+        const expectedSignature = crypto_1.default
+            .createHmac('sha256', this.webhookSecret)
+            .update(body)
+            .digest('hex');
+        return signature === expectedSignature;
+    }
+    // ==================== Helpers ====================
+    mapYocoStatus(yocoStatus) {
+        const statusMap = {
+            succeeded: 'completed',
+            successful: 'completed',
+            failed: 'failed',
+            cancelled: 'cancelled',
+            refunded: 'refunded',
+            pending: 'pending',
+        };
+        return statusMap[yocoStatus?.toLowerCase()] || 'pending';
+    }
+    mapYocoEventType(yocoType) {
+        const typeMap = {
+            'payment.succeeded': 'payment.completed',
+            'payment.successful': 'payment.completed',
+            'payment.failed': 'payment.failed',
+            'payment.cancelled': 'payment.cancelled',
+            'payment.refunded': 'refund.completed',
+        };
+        return typeMap[yocoType] || 'payment.pending';
+    }
+}
+exports.YocoProvider = YocoProvider;

package/dist/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * PayBridge — Unified payment SDK types
+ */
+export type Provider = 'softycomp' | 'yoco' | 'ozow' | 'payfast' | 'paystack' | 'stripe' | 'peach';
+export type PaymentStatus = 'pending' | 'completed' | 'failed' | 'cancelled' | 'refunded';
+export type SubscriptionInterval = 'weekly' | 'monthly' | 'yearly';
+export type Currency = 'ZAR' | 'USD' | 'EUR' | 'GBP' | 'NGN';
+export type WebhookEventType = 'payment.pending' | 'payment.completed' | 'payment.failed' | 'payment.cancelled' | 'subscription.created' | 'subscription.cancelled' | 'refund.completed';
+export interface PayBridgeConfig {
+    /** Payment provider to use */
+    provider: Provider;
+    /** Provider-specific credentials */
+    credentials: {
+        /** API key or merchant ID */
+        apiKey?: string;
+        /** Secret key or merchant key */
+        secretKey?: string;
+        /** Additional provider-specific credentials */
+        [key: string]: any;
+    };
+    /** Use sandbox/test environment */
+    sandbox?: boolean;
+    /** Optional webhook secret for signature validation */
+    webhookSecret?: string;
+}
+export interface Customer {
+    /** Customer full name */
+    name: string;
+    /** Customer email address */
+    email: string;
+    /** Customer phone number (e.g. "0825551234" or "+27825551234") */
+    phone?: string;
+    /** Customer ID in your system */
+    customerId?: string;
+}
+export interface CreatePaymentParams {
+    /** Amount in major currency unit (e.g. 299.00 for R299) */
+    amount: number;
+    /** Currency code (ISO 4217) */
+    currency: Currency;
+    /** Your internal reference/invoice number */
+    reference: string;
+    /** Payment description */
+    description?: string;
+    /** Customer details */
+    customer: Customer;
+    /** Redirect URLs */
+    urls: {
+        /** URL to redirect customer after successful payment */
+        success: string;
+        /** URL to redirect customer after cancelled payment */
+        cancel: string;
+        /** URL to receive webhook notifications */
+        webhook: string;
+    };
+    /** Additional metadata (up to 10 key-value pairs) */
+    metadata?: Record<string, any>;
+}
+export interface PaymentResult {
+    /** Unique payment ID from provider */
+    id: string;
+    /** Payment checkout URL (redirect customer here) */
+    checkoutUrl: string;
+    /** Payment status */
+    status: PaymentStatus;
+    /** Amount in major currency unit */
+    amount: number;
+    /** Currency code */
+    currency: Currency;
+    /** Your reference */
+    reference: string;
+    /** Provider name */
+    provider: Provider;
+    /** ISO 8601 timestamp when payment was created */
+    createdAt: string;
+    /** ISO 8601 timestamp when checkout URL expires (if applicable) */
+    expiresAt?: string;
+    /** Raw provider response */
+    raw?: any;
+}
+export interface CreateSubscriptionParams {
+    /** Amount in major currency unit (e.g. 299.00 for R299) */
+    amount: number;
+    /** Currency code (ISO 4217) */
+    currency: Currency;
+    /** Billing interval */
+    interval: SubscriptionInterval;
+    /** Your internal subscription reference */
+    reference: string;
+    /** Subscription description */
+    description?: string;
+    /** Customer details */
+    customer: Customer;
+    /** Redirect URLs */
+    urls: {
+        /** URL to redirect customer after successful setup */
+        success: string;
+        /** URL to redirect customer after cancelled setup */
+        cancel: string;
+        /** URL to receive webhook notifications */
+        webhook: string;
+    };
+    /** Subscription start date (ISO 8601). Must be future date. */
+    startDate?: string;
+    /** Day of month to charge (1-28). Only for monthly subscriptions. */
+    billingDay?: number;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+export interface SubscriptionResult {
+    /** Unique subscription ID from provider */
+    id: string;
+    /** Subscription setup URL (redirect customer here) */
+    checkoutUrl: string;
+    /** Subscription status */
+    status: 'pending' | 'active' | 'cancelled' | 'expired';
+    /** Amount in major currency unit */
+    amount: number;
+    /** Currency code */
+    currency: Currency;
+    /** Billing interval */
+    interval: SubscriptionInterval;
+    /** Your reference */
+    reference: string;
+    /** Provider name */
+    provider: Provider;
+    /** ISO 8601 timestamp when subscription starts */
+    startsAt?: string;
+    /** ISO 8601 timestamp when subscription was created */
+    createdAt: string;
+    /** Raw provider response */
+    raw?: any;
+}
+export interface RefundParams {
+    /** Original payment ID to refund */
+    paymentId: string;
+    /** Amount to refund in major currency unit. Omit for full refund. */
+    amount?: number;
+    /** Reason for refund */
+    reason?: string;
+}
+export interface RefundResult {
+    /** Refund ID */
+    id: string;
+    /** Refund status */
+    status: 'pending' | 'completed' | 'failed';
+    /** Amount refunded in major currency unit */
+    amount: number;
+    /** Currency code */
+    currency: Currency;
+    /** Original payment ID */
+    paymentId: string;
+    /** ISO 8601 timestamp when refund was created */
+    createdAt: string;
+    /** Raw provider response */
+    raw?: any;
+}
+export interface WebhookEvent {
+    /** Event type */
+    type: WebhookEventType;
+    /** Payment or subscription details */
+    payment?: PaymentResult;
+    subscription?: SubscriptionResult;
+    refund?: RefundResult;
+    /** Raw provider payload */
+    raw: any;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * PayBridge — Unified payment SDK types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/currency.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Currency conversion utilities
+ */
+import { Currency } from '../types';
+/**
+ * Convert major currency unit to minor unit (cents)
+ * @example toMinorUnit(299.00, 'ZAR') => 29900
+ */
+export declare function toMinorUnit(amount: number, currency: Currency): number;
+/**
+ * Convert minor unit (cents) to major currency unit
+ * @example toMajorUnit(29900, 'ZAR') => 299.00
+ */
+export declare function toMajorUnit(amount: number, currency: Currency): number;
+/**
+ * Get decimal places for currency
+ * Most currencies use 2 decimal places, some use 0
+ */
+export declare function getDecimalPlaces(currency: Currency): number;
+/**
+ * Format amount with currency symbol
+ * @example formatCurrency(299.00, 'ZAR') => "R299.00"
+ */
+export declare function formatCurrency(amount: number, currency: Currency): string;
+/**
+ * Validate amount is positive and has correct decimal places
+ */
+export declare function validateAmount(amount: number, currency: Currency): void;