@singularity-payments/core 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,369 @@
+type Environment = "sandbox" | "production";
+interface MpesaConfig {
+    consumerKey: string;
+    consumerSecret: string;
+    passkey: string;
+    shortcode: string;
+    environment: Environment;
+    callbackUrl?: string;
+    timeoutUrl?: string;
+    resultUrl?: string;
+}
+interface MpesaPlugin {
+    name: string;
+    init: (client: any) => void;
+}
+
+interface STKPushRequest {
+    amount: number;
+    phoneNumber: string;
+    accountReference: string;
+    transactionDesc: string;
+    callbackUrl?: string;
+}
+interface STKPushResponse {
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+    CustomerMessage: string;
+}
+interface TransactionStatusRequest {
+    CheckoutRequestID: string;
+}
+interface TransactionStatusResponse {
+    ResponseCode: string;
+    ResponseDescription: string;
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    ResultCode: string;
+    ResultDesc: string;
+}
+interface C2BRegisterRequest {
+    shortCode: string;
+    responseType: "Completed" | "Cancelled";
+    confirmationURL: string;
+    validationURL: string;
+}
+interface CallbackMetadata {
+    Item: Array<{
+        Name: string;
+        Value: string | number;
+    }>;
+}
+interface STKCallback {
+    Body: {
+        stkCallback: {
+            MerchantRequestID: string;
+            CheckoutRequestID: string;
+            ResultCode: number;
+            ResultDesc: string;
+            CallbackMetadata?: CallbackMetadata;
+        };
+    };
+}
+interface C2BCallback {
+    TransactionType: string;
+    TransID: string;
+    TransTime: string;
+    TransAmount: string;
+    BusinessShortCode: string;
+    BillRefNumber: string;
+    InvoiceNumber?: string;
+    OrgAccountBalance?: string;
+    ThirdPartyTransID?: string;
+    MSISDN: string;
+    FirstName?: string;
+    MiddleName?: string;
+    LastName?: string;
+}
+interface C2BRegisterResponse {
+    OriginatorCoversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+interface ParsedCallbackData {
+    merchantRequestId: string;
+    CheckoutRequestID: string;
+    resultCode: number;
+    resultDescription: string;
+    amount?: number;
+    mpesaReceiptNumber?: string;
+    transactionDate?: string;
+    phoneNumber?: string;
+    isSuccess: boolean;
+    errorMessage?: string;
+}
+interface ParsedC2BCallback {
+    transactionType: string;
+    transactionId: string;
+    transactionTime: string;
+    amount: number;
+    businessShortCode: string;
+    billRefNumber: string;
+    invoiceNumber?: string;
+    msisdn: string;
+    firstName?: string;
+    middleName?: string;
+    lastName?: string;
+}
+interface CallbackHandlerOptions {
+    onSuccess?: (data: ParsedCallbackData) => void | Promise<void>;
+    onFailure?: (data: ParsedCallbackData) => void | Promise<void>;
+    onCallback?: (data: ParsedCallbackData) => void | Promise<void>;
+    onC2BConfirmation?: (data: ParsedC2BCallback) => void | Promise<void>;
+    onC2BValidation?: (data: ParsedC2BCallback) => Promise<boolean>;
+    validateIp?: boolean;
+    allowedIps?: string[];
+    isDuplicate?: (CheckoutRequestID: string) => boolean | Promise<boolean>;
+    logger?: {
+        info: (message: string, data?: any) => void;
+        error: (message: string, data?: any) => void;
+        warn: (message: string, data?: any) => void;
+    };
+}
+declare class MpesaCallbackHandler {
+    private options;
+    private readonly SAFARICOM_IPS;
+    constructor(options?: CallbackHandlerOptions);
+    /**
+     * Validate that the callback is from a trusted IP
+     */
+    validateCallbackIp(ipAddress: string): boolean;
+    /**
+     * Parse STK Push callback data from M-Pesa
+     */
+    parseCallback(callback: STKCallback): ParsedCallbackData;
+    /**
+     * Parse C2B callback data
+     */
+    parseC2BCallback(callback: C2BCallback): ParsedC2BCallback;
+    /**
+     * Extract metadata from STK callback
+     */
+    private extractMetadata;
+    /**
+     * Format transaction date from M-Pesa format (YYYYMMDDHHmmss) to ISO
+     */
+    private formatTransactionDate;
+    /**
+     * Check if callback indicates success
+     */
+    isSuccess(data: ParsedCallbackData): boolean;
+    /**
+     * Check if callback indicates failure
+     */
+    isFailure(data: ParsedCallbackData): boolean;
+    /**
+     * Get a readable error message based on the code
+     */
+    getErrorMessage(resultCode: number): string;
+    /**
+     * Handle STK Push callback and invoke appropriate handlers
+     */
+    handleCallback(callback: STKCallback, ipAddress?: string): Promise<void>;
+    /**
+     * Handle C2B validation request
+     * Returns true if validation passes, false otherwise
+     */
+    handleC2BValidation(callback: C2BCallback): Promise<boolean>;
+    /**
+     * Handle C2B confirmation
+     */
+    handleC2BConfirmation(callback: C2BCallback): Promise<void>;
+    /**
+     * Create a standard callback response for M-Pesa
+     */
+    createCallbackResponse(success?: boolean, message?: string): object;
+    /**
+     * Internal logging helper
+     */
+    private log;
+}
+
+interface RetryOptions {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    retryableStatusCodes?: number[];
+    onRetry?: (error: Error, attempt: number) => void;
+}
+/**
+ * Retry a function with exponential backoff
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+interface RateLimiterOptions {
+    maxRequests: number;
+    windowMs: number;
+    keyPrefix?: string;
+}
+declare class RateLimiter {
+    private store;
+    private options;
+    private cleanupInterval;
+    constructor(options: RateLimiterOptions);
+    /**
+     * Check if request is allowed
+     */
+    checkLimit(key: string): Promise<void>;
+    /**
+     * Get current usage for a key
+     */
+    getUsage(key: string): {
+        count: number;
+        remaining: number;
+        resetAt: number;
+    };
+    /**
+     * Reset rate limit for a key
+     */
+    reset(key: string): void;
+    /**
+     * Clear all rate limits
+     */
+    resetAll(): void;
+    /**
+     * Start cleanup interval
+     */
+    private startCleanup;
+    /**
+     * Stop cleanup interval
+     */
+    destroy(): void;
+}
+/**
+ * Create a Redis-backed rate limiter (for distributed systems)
+ */
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, mode: string, duration: number): Promise<void>;
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<void>;
+}
+declare class RedisRateLimiter {
+    private options;
+    private redis;
+    constructor(redis: RedisLike, options: RateLimiterOptions);
+    checkLimit(key: string): Promise<void>;
+    reset(key: string): Promise<void>;
+}
+
+interface MpesaClientOptions {
+    callbackOptions?: CallbackHandlerOptions;
+    retryOptions?: RetryOptions;
+    rateLimitOptions?: {
+        enabled?: boolean;
+        maxRequests?: number;
+        windowMs?: number;
+        redis?: RedisLike;
+    };
+    requestTimeout?: number;
+}
+declare class MpesaClient {
+    private config;
+    private auth;
+    private plugins;
+    private callbackHandler;
+    private retryOptions;
+    private rateLimiter;
+    private readonly REQUEST_TIMEOUT;
+    constructor(config: MpesaConfig, options?: MpesaClientOptions);
+    /**
+     * Make HTTP request with error handling
+     */
+    private makeRequest;
+    /**
+     * Validate phone number format
+     */
+    private validateAndFormatPhone;
+    /**
+     * Add a plugin to extend functionality
+     */
+    use(plugin: MpesaPlugin): this;
+    /**
+     * Initiate STK Push (Lipa Na M-Pesa Online)
+     */
+    stkPush(request: STKPushRequest): Promise<STKPushResponse>;
+    /**
+     * Query STK Push transaction status
+     */
+    stkQuery(request: TransactionStatusRequest): Promise<TransactionStatusResponse>;
+    /**
+     * Register C2B URLs for validation and confirmation
+     */
+    registerC2BUrl(request: C2BRegisterRequest): Promise<C2BRegisterResponse>;
+    /**
+     * Get the callback handler instance
+     */
+    getCallbackHandler(): MpesaCallbackHandler;
+    /**
+     * Handle an incoming STK Push callback
+     * Returns M-Pesa compliant response
+     */
+    handleSTKCallback(callback: STKCallback, ipAddress?: string): Promise<object>;
+    /**
+     * Handle C2B validation request
+     */
+    handleC2BValidation(callback: C2BCallback): Promise<object>;
+    /**
+     * Handle C2B confirmation
+     */
+    handleC2BConfirmation(callback: C2BCallback): Promise<object>;
+    /**
+     * Parse STK callback without handling (for testing)
+     */
+    parseSTKCallback(callback: STKCallback): ParsedCallbackData;
+    /**
+     * Parse C2B callback without handling (for testing)
+     */
+    parseC2BCallback(callback: C2BCallback): ParsedC2BCallback;
+    /**
+     * Get configuration (for plugins)
+     */
+    getConfig(): MpesaConfig;
+    /**
+     * Get rate limiter usage for a key
+     */
+    getRateLimitUsage(key: string): {
+        count: number;
+        remaining: number;
+        resetAt: number;
+    } | null;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+
+declare class MpesaError extends Error {
+    code?: string | undefined;
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, details?: any | undefined);
+}
+declare class MpesaAuthError extends MpesaError {
+    constructor(message: string, details?: any);
+}
+declare class MpesaValidationError extends MpesaError {
+    constructor(message: string, details?: any);
+}
+declare class MpesaNetworkError extends MpesaError {
+    isRetryable: boolean;
+    constructor(message: string, isRetryable: boolean, details?: any);
+}
+declare class MpesaTimeoutError extends MpesaError {
+    constructor(message: string, details?: any);
+}
+declare class MpesaRateLimitError extends MpesaError {
+    retryAfter?: number | undefined;
+    constructor(message: string, retryAfter?: number | undefined, details?: any);
+}
+declare class MpesaApiError extends MpesaError {
+    responseBody?: any | undefined;
+    constructor(message: string, code: string, statusCode: number, responseBody?: any | undefined);
+}
+
+export { type C2BCallback, type C2BRegisterRequest, type C2BRegisterResponse, type CallbackHandlerOptions, type Environment, MpesaApiError, MpesaAuthError, MpesaCallbackHandler, MpesaClient, type MpesaClientOptions, type MpesaConfig, MpesaError, MpesaNetworkError, type MpesaPlugin, MpesaRateLimitError, MpesaTimeoutError, MpesaValidationError, type ParsedC2BCallback, type ParsedCallbackData, RateLimiter, type RateLimiterOptions, type RedisLike, RedisRateLimiter, type RetryOptions, type STKCallback, type STKPushRequest, type STKPushResponse, type TransactionStatusRequest, type TransactionStatusResponse, retryWithBackoff };