pesafy 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,416 @@
+/**
+ * OAuth token manager for Daraja API
+ * Token validity: 3600 seconds (1 hour)
+ */
+declare class TokenManager {
+    private consumerKey;
+    private consumerSecret;
+    private baseUrl;
+    private cachedToken;
+    private tokenExpiresAt;
+    constructor(consumerKey: string, consumerSecret: string, baseUrl: string);
+    private getAuthHeader;
+    getAccessToken(): Promise<string>;
+    clearCache(): void;
+}
+
+/**
+ * Security credential encryption for B2C, B2B, Reversal APIs
+ * Uses RSA with PKCS#1.5 padding per Daraja API spec
+ * Download certificates from: https://developer.safaricom.co.ke/APIs
+ */
+/** Encrypt initiator password with M-Pesa public certificate (PEM format) */
+declare function encryptSecurityCredential(initiatorPassword: string, certificatePem: string): string;
+
+/** B2B (Business to Business) types */
+type B2BCommandId = "BusinessPayBill" | "BusinessBuyGoods" | "DisburseFundsToBusiness" | "BusinessToBusinessTransfer";
+interface B2BRequest {
+    amount: number;
+    shortCode: string;
+    receiverShortCode: string;
+    resultUrl: string;
+    timeoutUrl: string;
+    commandId?: B2BCommandId;
+    senderIdentifierType?: number;
+    receiverIdentifierType?: number;
+    remarks?: string;
+    accountReference?: string;
+}
+
+/**
+ * B2B - Business to Business payments
+ * API: POST /mpesa/b2b/v1/paymentrequest
+ */
+
+interface B2BResponse {
+    OriginatorConversationID: string;
+    ConversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/** B2C (Business to Customer) types */
+type B2CCommandId = "BusinessPayment" | "SalaryPayment" | "PromotionPayment";
+interface B2CRequest {
+    amount: number;
+    phoneNumber: string;
+    shortCode: string;
+    resultUrl: string;
+    timeoutUrl: string;
+    commandId?: B2CCommandId;
+    remarks?: string;
+    occasion?: string;
+}
+
+/**
+ * B2C - Business to Customer payments
+ * API: POST /mpesa/b2c/v3/paymentrequest
+ */
+
+interface B2CResponse {
+    OriginatorConversationID: string;
+    ConversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/** C2B (Customer to Business) types */
+interface C2BRegisterUrlRequest {
+    shortCode: string;
+    confirmationUrl: string;
+    validationUrl: string;
+    responseType?: "Completed" | "Cancelled";
+}
+interface C2BSimulateRequest {
+    shortCode: string;
+    amount: number;
+    phoneNumber: string;
+    billRefNumber?: string;
+}
+
+/**
+ * C2B Register URLs - Register validation and confirmation URLs
+ * API: POST /mpesa/c2b/v2/registerurl
+ */
+
+interface C2BRegisterUrlResponse {
+    ConversationID: string;
+    OriginatorCoversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/**
+ * C2B Simulate - Simulate C2B payment (sandbox only)
+ * API: POST /mpesa/c2b/v2/simulate
+ */
+
+interface C2BSimulateResponse {
+    ConversationID: string;
+    OriginatorCoversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/** Transaction Reversal types */
+interface ReversalRequest {
+    transactionId: string;
+    amount: number;
+    shortCode: string;
+    resultUrl: string;
+    timeoutUrl: string;
+    remarks?: string;
+    occasion?: string;
+}
+
+/**
+ * Transaction Reversal
+ * API: POST /mpesa/reversal/v1/request
+ */
+
+interface ReversalResponse {
+    OriginatorConversationID: string;
+    ConversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/** Transaction Status Query types */
+interface TransactionStatusRequest {
+    shortCode: string;
+    transactionId: string;
+    resultUrl: string;
+    timeoutUrl: string;
+    identifierType?: number;
+}
+
+/**
+ * Transaction Status Query
+ * API: POST /mpesa/transactionstatus/v1/query
+ */
+
+interface TransactionStatusResponse {
+    OriginatorConversationID: string;
+    ConversationID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+}
+
+/** Dynamic QR Code types - LIPA NA M-PESA */
+type TrxCode = "BG" | "WA" | "PB" | "SM" | "SB";
+interface DynamicQRRequest {
+    merchantName: string;
+    refNo: string;
+    amount: number;
+    trxCode: TrxCode;
+    cpi: string;
+    size?: string;
+}
+
+/**
+ * Dynamic QR Code - Generate LIPA NA M-PESA QR codes
+ * API: POST /mpesa/qrcode/v1/generate
+ */
+
+interface DynamicQRResponse {
+    ResponseCode: string;
+    RequestID: string;
+    ResponseDescription: string;
+    QRCode: string;
+}
+
+/** STK Push (M-Pesa Express) types */
+type TransactionType = "CustomerPayBillOnline" | "CustomerBuyGoodsOnline";
+interface StkPushRequest {
+    amount: number;
+    phoneNumber: string;
+    callbackUrl: string;
+    accountReference: string;
+    transactionDesc: string;
+    /** Business shortcode - Paybill or Till number */
+    shortCode: string;
+    passKey: string;
+    transactionType?: TransactionType;
+}
+interface StkPushResponse {
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    ResponseCode: string;
+    ResponseDescription: string;
+    CustomerMessage: string;
+}
+interface StkQueryRequest {
+    checkoutRequestId: string;
+    shortCode: string;
+    passKey: string;
+}
+interface StkQueryResponse {
+    ResponseCode: string;
+    ResponseDescription: string;
+    MerchantRequestID: string;
+    CheckoutRequestID: string;
+    ResultCode: string;
+    ResultDesc: string;
+}
+
+type Environment = "sandbox" | "production";
+declare const DARAJA_BASE_URLS: {
+    readonly sandbox: "https://sandbox.safaricom.co.ke";
+    readonly production: "https://api.safaricom.co.ke";
+};
+interface MpesaConfig {
+    consumerKey: string;
+    consumerSecret: string;
+    environment: Environment;
+    /** Required for STK Push - Lipa Na M-Pesa passkey from Daraja portal */
+    lipaNaMpesaShortCode?: string;
+    lipaNaMpesaPassKey?: string;
+    /** Required for B2C, B2B, Reversal - initiator name and password */
+    initiatorName?: string;
+    initiatorPassword?: string;
+    /** PEM certificate for encrypting initiator password. Download from Daraja portal */
+    certificatePath?: string;
+    /** PEM certificate string (alternative to certificatePath) */
+    certificatePem?: string;
+    /** Pre-encrypted security credential (alternative to initiatorPassword + certificate) */
+    securityCredential?: string;
+}
+
+declare class Mpesa {
+    private config;
+    private tokenManager;
+    private baseUrl;
+    constructor(config: MpesaConfig);
+    private getToken;
+    private getSecurityCredential;
+    /** STK Push (M-Pesa Express) - Initiate payment on customer phone */
+    stkPush(request: Omit<StkPushRequest, "shortCode" | "passKey">): Promise<StkPushResponse>;
+    /** STK Query - Check STK Push transaction status */
+    stkQuery(request: Omit<StkQueryRequest, "shortCode" | "passKey">): Promise<StkQueryResponse>;
+    /** B2C - Send money to customer */
+    b2c(request: B2CRequest): Promise<B2CResponse>;
+    /** B2B - Send money to business */
+    b2b(request: B2BRequest): Promise<B2BResponse>;
+    /** C2B - Register validation/confirmation URLs */
+    c2bRegisterUrls(request: C2BRegisterUrlRequest): Promise<C2BRegisterUrlResponse>;
+    /** C2B - Simulate payment (sandbox only) */
+    c2bSimulate(request: C2BSimulateRequest): Promise<C2BSimulateResponse>;
+    /** Dynamic QR - Generate LIPA NA M-PESA QR code */
+    qrCode(request: DynamicQRRequest): Promise<DynamicQRResponse>;
+    /** Transaction Status - Query transaction status */
+    transactionStatus(request: TransactionStatusRequest): Promise<TransactionStatusResponse>;
+    /** Reversal - Reverse a transaction */
+    reversal(request: ReversalRequest): Promise<ReversalResponse>;
+}
+
+/**
+ * Webhook retry mechanism with exponential backoff
+ * For at-least-once delivery guarantee
+ */
+interface RetryOptions {
+    maxRetries?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    maxRetryDuration?: number;
+}
+interface RetryResult<T> {
+    success: boolean;
+    data?: T;
+    attempts: number;
+    error?: Error;
+}
+declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+
+/**
+ * Webhook event types from Daraja API
+ */
+type WebhookEventType = "stk_push" | "b2c" | "b2b" | "c2b" | "transaction_status" | "reversal";
+interface WebhookEvent {
+    eventType: WebhookEventType;
+    timestamp: string;
+    data: unknown;
+}
+/** STK Push webhook payload */
+interface StkPushWebhook {
+    Body: {
+        stkCallback: {
+            MerchantRequestID: string;
+            CheckoutRequestID: string;
+            ResultCode: number;
+            ResultDesc: string;
+            CallbackMetadata?: {
+                Item: Array<{
+                    Name: string;
+                    Value: string | number;
+                }>;
+            };
+        };
+    };
+}
+/** B2C webhook payload */
+interface B2CWebhook {
+    Result: {
+        ResultType: number;
+        ResultCode: number;
+        ResultDesc: string;
+        OriginatorConversationID: string;
+        ConversationID: string;
+        TransactionID: string;
+        ResultParameters: {
+            ResultParameter: Array<{
+                Key: string;
+                Value: string | number;
+            }>;
+        };
+        ReferenceData: {
+            ReferenceItem: Array<{
+                Key: string;
+                Value: string;
+            }>;
+        };
+    };
+}
+/** C2B webhook payload */
+interface C2BWebhook {
+    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;
+}
+
+/**
+ * Webhook signature verification
+ * Note: Daraja API doesn't provide webhook signatures in the same way as Stripe
+ * Instead, verify by whitelisting IPs: 196.201.214.200, 196.201.214.206, etc.
+ * This utility helps parse and validate webhook payloads
+ */
+
+declare function verifyWebhookIP(requestIP: string, allowedIPs?: string[]): boolean;
+
+/**
+ * Webhook event handler utilities
+ */
+
+interface WebhookHandlerOptions {
+    /** IP address of incoming request */
+    requestIP?: string;
+    /** Custom IP whitelist */
+    allowedIPs?: string[];
+    /** Skip IP verification (for testing) */
+    skipIPCheck?: boolean;
+}
+interface WebhookHandlerResult<T = unknown> {
+    success: boolean;
+    eventType: WebhookEventType | null;
+    data: T | null;
+    error?: string;
+}
+declare function handleWebhook(body: unknown, options?: WebhookHandlerOptions): WebhookHandlerResult;
+declare function extractTransactionId(webhook: StkPushWebhook | B2CWebhook | C2BWebhook): string | null;
+declare function extractAmount(webhook: StkPushWebhook | B2CWebhook | C2BWebhook): number | null;
+
+/**
+ * Error types for Pesafy library
+ */
+type ErrorCode = "AUTH_FAILED" | "INVALID_CREDENTIALS" | "ENCRYPTION_FAILED" | "API_ERROR" | "NETWORK_ERROR" | "VALIDATION_ERROR" | "INVALID_RESPONSE" | "REQUEST_FAILED" | "TIMEOUT";
+interface PesafyErrorOptions {
+    code: ErrorCode;
+    message: string;
+    cause?: unknown;
+    statusCode?: number;
+    response?: unknown;
+    requestId?: string;
+}
+
+/**
+ * Error creation utilities for Pesafy
+ */
+
+declare class PesafyError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    readonly requestId?: string;
+    readonly cause?: unknown;
+    constructor(options: PesafyErrorOptions);
+    toJSON(): {
+        name: string;
+        code: ErrorCode;
+        message: string;
+        statusCode: number | undefined;
+        requestId: string | undefined;
+    };
+}
+declare function createError(options: PesafyErrorOptions): PesafyError;
+
+export { type B2BRequest, type B2BResponse, type B2CRequest, type B2CResponse, type B2CWebhook, type C2BRegisterUrlRequest, type C2BRegisterUrlResponse, type C2BSimulateRequest, type C2BSimulateResponse, type C2BWebhook, DARAJA_BASE_URLS, type DynamicQRRequest, type DynamicQRResponse, type ErrorCode, Mpesa, type MpesaConfig, PesafyError, type RetryOptions, type RetryResult, type ReversalRequest, type ReversalResponse, type StkPushRequest, type StkPushResponse, type StkPushWebhook, type StkQueryRequest, type StkQueryResponse, TokenManager, type TransactionStatusRequest, type TransactionStatusResponse, type WebhookEvent, type WebhookEventType, type WebhookHandlerOptions, type WebhookHandlerResult, createError, encryptSecurityCredential, extractAmount, extractTransactionId, handleWebhook, retryWithBackoff, verifyWebhookIP };