spaark-payapi-sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,505 @@
+import { AxiosRequestConfig } from 'axios';
+import { D as DepositRequest, a as DepositResponse, P as PayoutRequest, b as PayoutResponse, c as PaymentPageRequest, d as PaymentPageResponse, R as RefundRequest, e as RefundResponse, T as TransactionStatusResponse, f as PollOptions, g as TransactionFilters, A as ActionResponse, C as Currency, h as Correspondent, i as TransactionLimits, j as CorrespondentInfo, F as FailureReason } from './react-pjDvSSJA.mjs';
+export { k as CORRESPONDENTS, l as CORRESPONDENT_INFO, m as CorrespondentFeature, n as DEFAULT_LIMITS, o as DepositFailureCode, p as FinancialAddress, M as MMOAccount, q as PawapayTestDashboard, r as PawapayTestDashboardProps, s as PayoutFailureCode, t as TransactionStatus } from './react-pjDvSSJA.mjs';
+import 'react/jsx-runtime';
+
+type Environment = 'sandbox' | 'production';
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+interface SpaarkPayApiSdkConfig {
+    apiKey: string;
+    environment: Environment;
+    baseUrl?: string;
+    callbackUrl?: string;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    logLevel?: LogLevel;
+}
+interface ResolvedConfig {
+    apiKey: string;
+    environment: Environment;
+    baseUrl: string;
+    callbackUrl?: string;
+    timeout: number;
+    retries: number;
+    retryDelay: number;
+    logLevel: LogLevel;
+}
+
+declare class Logger {
+    private readonly prefix;
+    private level;
+    constructor(prefix: string, level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    private formatMessage;
+    private sanitize;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, error?: Error | unknown): void;
+}
+
+interface HttpClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    retries: number;
+    retryDelay: number;
+    logger: Logger;
+}
+declare class HttpClient {
+    private readonly client;
+    private readonly logger;
+    private readonly retries;
+    private readonly retryDelay;
+    constructor(config: HttpClientConfig);
+    private setupInterceptors;
+    private handleError;
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T, D = unknown>(url: string, data?: D, config?: AxiosRequestConfig): Promise<T>;
+    put<T, D = unknown>(url: string, data?: D, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    static fromConfig(config: ResolvedConfig, logger: Logger): HttpClient;
+}
+
+declare class TransactionsModule {
+    private readonly httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient, logger: Logger);
+    /**
+     * Initiate a deposit (collect payment from mobile money user) - V2 API
+     */
+    initiateDeposit(request: DepositRequest): Promise<DepositResponse>;
+    /**
+     * Initiate a payout (send money to mobile money user) - V2 API
+     */
+    initiatePayout(request: PayoutRequest): Promise<PayoutResponse>;
+    /**
+     * Create a hosted payment page - V2 API
+     */
+    createPaymentPage(request: PaymentPageRequest): Promise<PaymentPageResponse>;
+    /**
+     * Refund a deposit
+     */
+    refund(request: RefundRequest): Promise<RefundResponse>;
+    /**
+     * Check deposit status - V2 API
+     */
+    checkDepositStatus(depositId: string): Promise<TransactionStatusResponse>;
+    /**
+     * Check payout status - V2 API
+     */
+    checkPayoutStatus(payoutId: string): Promise<TransactionStatusResponse>;
+    /**
+     * Check transaction status (tries deposit first, then payout) - V2 API
+     */
+    checkStatus(transactionId: string): Promise<TransactionStatusResponse>;
+    /**
+     * Poll until transaction reaches final status
+     */
+    pollUntilComplete(transactionId: string, options?: PollOptions): Promise<TransactionStatusResponse>;
+    /**
+     * List deposits with filters
+     */
+    listDeposits(filters?: TransactionFilters): Promise<DepositResponse[]>;
+    /**
+     * List payouts with filters
+     */
+    listPayouts(filters?: TransactionFilters): Promise<PayoutResponse[]>;
+    /**
+     * Resend deposit callback - V2 API
+     * Triggers a new callback for a deposit transaction
+     */
+    resendDepositCallback(depositId: string): Promise<ActionResponse>;
+    /**
+     * Resend payout callback - V2 API
+     * Triggers a new callback for a payout transaction
+     */
+    resendPayoutCallback(payoutId: string): Promise<ActionResponse>;
+    /**
+     * Cancel enqueued payout - V2 API
+     * Cancels a payout that is still in ENQUEUED status
+     */
+    cancelEnqueuedPayout(payoutId: string): Promise<ActionResponse>;
+}
+
+interface ProductCreateRequest {
+    name: string;
+    description?: string;
+    price: number;
+    currency: Currency;
+    metadata?: Record<string, unknown>;
+}
+interface Product {
+    id: string;
+    name: string;
+    description?: string;
+    price: number;
+    currency: string;
+    domains: string[];
+    created: string;
+    updated: string;
+}
+interface DomainAddRequest {
+    productId: string;
+    domain: string;
+}
+
+declare class ProductsModule {
+    private readonly logger;
+    private products;
+    constructor(logger: Logger);
+    create(request: ProductCreateRequest): Promise<Product>;
+    get(productId: string): Promise<Product>;
+    list(): Promise<Product[]>;
+    update(productId: string, updates: Partial<ProductCreateRequest>): Promise<Product>;
+    delete(productId: string): Promise<void>;
+    addDomain(request: DomainAddRequest): Promise<Product>;
+    removeDomain(productId: string, domain: string): Promise<Product>;
+    private toProduct;
+}
+
+type WebhookEventType = 'deposit.accepted' | 'deposit.completed' | 'deposit.failed' | 'payout.accepted' | 'payout.completed' | 'payout.failed' | 'refund.completed' | 'refund.failed';
+interface PawapayWebhookEvent<T = unknown> {
+    eventId: string;
+    eventType: WebhookEventType;
+    timestamp: string;
+    data: T;
+}
+interface DepositCallbackData {
+    depositId: string;
+    status: 'COMPLETED' | 'FAILED';
+    amount: string;
+    currency: string;
+    correspondent: string;
+    payer: {
+        type: string;
+        address: {
+            value: string;
+        };
+    };
+    customerTimestamp: string;
+    created: string;
+    receivedByPayer?: string;
+    failureReason?: {
+        failureCode: string;
+        failureMessage: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+interface PayoutCallbackData {
+    payoutId: string;
+    status: 'COMPLETED' | 'FAILED';
+    amount: string;
+    currency: string;
+    correspondent: string;
+    recipient: {
+        type: string;
+        address: {
+            value: string;
+        };
+    };
+    customerTimestamp: string;
+    created: string;
+    receivedByRecipient?: string;
+    failureReason?: {
+        failureCode: string;
+        failureMessage: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+
+interface WebhooksConfig {
+    webhookSecret?: string;
+}
+declare class WebhooksModule {
+    private readonly httpClient;
+    private readonly logger;
+    private webhookSecret?;
+    constructor(httpClient: HttpClient, logger: Logger, config?: WebhooksConfig);
+    setWebhookSecret(secret: string): void;
+    verifySignature(payload: string, signature: string): boolean;
+    parseEvent<T = unknown>(payload: string): PawapayWebhookEvent<T>;
+    constructEvent<T = unknown>(payload: string, signature: string): PawapayWebhookEvent<T>;
+    registerCallback(url: string): Promise<void>;
+    unregisterCallback(): Promise<void>;
+    isDepositEvent(eventType: WebhookEventType): boolean;
+    isPayoutEvent(eventType: WebhookEventType): boolean;
+    isRefundEvent(eventType: WebhookEventType): boolean;
+    isSuccessEvent(eventType: WebhookEventType): boolean;
+    isFailureEvent(eventType: WebhookEventType): boolean;
+}
+
+type OperationType = 'DEPOSIT' | 'PAYOUT' | 'REFUND' | 'REMITTANCE';
+type OperationStatus = 'OPERATIONAL' | 'DELAYED' | 'CLOSED';
+interface ProviderOperationStatus {
+    operationType: OperationType;
+    status: OperationStatus;
+}
+interface ProviderAvailability {
+    provider: string;
+    operationTypes: ProviderOperationStatus[];
+}
+interface CountryAvailability {
+    country: string;
+    providers: ProviderAvailability[];
+}
+interface PredictProviderRequest {
+    phoneNumber: string;
+}
+interface PredictProviderResponse {
+    country: string;
+    provider: string;
+    phoneNumber: string;
+}
+interface ActiveConfigResponse {
+    companyName: string;
+    signatureConfiguration: {
+        signedRequestsOnly?: boolean;
+        signedCallbacks?: boolean;
+    };
+    countries: CountryConfig[];
+}
+interface CountryConfig {
+    country: string;
+    displayName: Record<string, string>;
+    prefix: string;
+    flag: string;
+    providers: ProviderConfig[];
+}
+interface ProviderConfig {
+    provider: string;
+    displayName: string;
+    nameDisplayedToCustomer: string;
+    currencies: CurrencyConfig[];
+}
+interface CurrencyConfig {
+    currency: string;
+    displayName: string;
+    operationTypes: {
+        DEPOSIT?: OperationTypeConfig;
+        PAYOUT?: OperationTypeConfig;
+        REFUND?: OperationTypeConfig;
+        REMITTANCE?: OperationTypeConfig;
+        USSD_DEPOSIT?: {
+            callbackUrl?: string;
+        };
+    };
+}
+interface OperationTypeConfig {
+    minAmount?: string;
+    maxAmount?: string;
+    decimalsInAmount?: 'TWO_PLACES' | 'NONE';
+    status?: OperationStatus;
+    callbackUrl?: string;
+    authorisationType?: string;
+    authorisationInstructions?: Record<string, string>;
+}
+interface PublicKeyResponse {
+    id: string;
+    key: string;
+}
+
+interface MMOAvailability {
+    correspondent: Correspondent;
+    available: boolean;
+    degraded: boolean;
+    estimatedRecovery?: string;
+    message?: string;
+}
+declare class UtilsModule {
+    private readonly httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient, logger: Logger);
+    generateTransactionId(): string;
+    validateTransactionId(id: string): boolean;
+    /**
+     * Get active configuration - V2 API
+     * Returns your account configuration including countries, providers, and limits
+     */
+    getActiveConfiguration(options?: {
+        country?: string;
+        operationType?: OperationType;
+    }): Promise<ActiveConfigResponse>;
+    /**
+     * Get provider availability - V2 API
+     * Returns current processing status for all providers
+     */
+    getProviderAvailability(options?: {
+        country?: string;
+        operationType?: OperationType;
+    }): Promise<CountryAvailability[]>;
+    /**
+     * Predict provider from phone number - V2 API
+     * Returns the predicted provider and sanitized phone number
+     */
+    predictProvider(phoneNumber: string): Promise<PredictProviderResponse>;
+    /**
+     * Get public keys for callback verification - V2 API
+     */
+    getPublicKeys(): Promise<PublicKeyResponse[]>;
+    getTransactionLimits(correspondent: Correspondent): Promise<TransactionLimits>;
+    checkMMOAvailability(correspondent: Correspondent): Promise<MMOAvailability>;
+    formatPhoneNumber(phone: string, countryCode: string): string;
+    validatePhoneNumber(phone: string, correspondent: Correspondent): boolean;
+    getSupportedCorrespondents(): readonly Correspondent[];
+    getCorrespondentInfo(correspondent: Correspondent): CorrespondentInfo;
+    getAllCorrespondentsInfo(): CorrespondentInfo[];
+    detectCorrespondent(phone: string): Correspondent | null;
+}
+
+interface WalletBalance {
+    country: string;
+    balance: string;
+    currency: string;
+    provider?: string;
+}
+interface WalletBalancesResponse {
+    balances: WalletBalance[];
+}
+interface StatementWallet {
+    country: string;
+    currency: string;
+    provider?: string;
+}
+interface StatementRequest {
+    wallet: StatementWallet;
+    callbackUrl: string;
+    startDate: string;
+    endDate: string;
+    compressed?: boolean;
+}
+type StatementStatus = 'PROCESSING' | 'COMPLETED' | 'FAILED';
+interface StatementResponse {
+    status: 'ACCEPTED' | 'REJECTED';
+    statementId?: string;
+    created?: string;
+    failureReason?: {
+        failureCode: StatementFailureCode;
+        failureMessage?: string;
+    };
+}
+type StatementFailureCode = 'NO_AUTHENTICATION' | 'AUTHENTICATION_ERROR' | 'AUTHORISATION_ERROR' | 'INVALID_INPUT' | 'MISSING_PARAMETER' | 'UNSUPPORTED_PARAMETER' | 'INVALID_PARAMETER' | 'INVALID_CALLBACK_URL' | 'INVALID_DATE_RANGE' | 'WALLET_NOT_FOUND' | 'UNKNOWN_ERROR';
+interface StatementStatusResponse {
+    status: 'FOUND' | 'NOT_FOUND';
+    data?: StatementData;
+}
+interface StatementData {
+    statementId: string;
+    status: StatementStatus;
+    wallet: StatementWallet;
+    created: string;
+    startDate: string;
+    endDate: string;
+    fileSize?: number;
+    downloadUrl?: string;
+    downloadUrlExpiresAt?: string;
+    completedAt?: string;
+    failedAt?: string;
+    failureReason?: {
+        failureCode: 'UNKNOWN_ERROR';
+        failureMessage?: string;
+    };
+}
+interface StatementCallbackData {
+    statementId: string;
+    status: StatementStatus;
+    wallet: StatementWallet;
+    created: string;
+    startDate: string;
+    endDate: string;
+    fileSize?: number;
+    downloadUrl?: string;
+    downloadUrlExpiresAt?: string;
+    completedAt?: string;
+    failedAt?: string;
+    failureReason?: {
+        failureCode: 'UNKNOWN_ERROR';
+        failureMessage?: string;
+    };
+}
+
+declare class FinancesModule {
+    private readonly httpClient;
+    private readonly logger;
+    constructor(httpClient: HttpClient, logger: Logger);
+    /**
+     * Get wallet balances - V2 API
+     * Returns balances for all wallets configured on your account
+     */
+    getWalletBalances(): Promise<WalletBalance[]>;
+    /**
+     * Generate a statement for a wallet - V2 API
+     * The statement can be downloaded from the callback URL or checked via status endpoint
+     */
+    generateStatement(request: StatementRequest): Promise<StatementResponse>;
+    /**
+     * Check statement status - V2 API
+     */
+    checkStatementStatus(statementId: string): Promise<StatementData>;
+    /**
+     * Poll until statement is ready
+     */
+    pollStatementUntilComplete(statementId: string, options?: {
+        interval?: number;
+        maxAttempts?: number;
+    }): Promise<StatementData>;
+}
+
+declare class SpaarkPayApiSdk {
+    private readonly config;
+    private readonly logger;
+    private readonly httpClient;
+    readonly transactions: TransactionsModule;
+    readonly products: ProductsModule;
+    readonly webhooks: WebhooksModule;
+    readonly utils: UtilsModule;
+    readonly finances: FinancesModule;
+    constructor(config: SpaarkPayApiSdkConfig);
+    private getWebhookSecretFromEnv;
+    getConfig(): Readonly<ResolvedConfig>;
+    setLogLevel(level: LogLevel): void;
+    setWebhookSecret(secret: string): void;
+}
+
+declare const ERROR_CODES: {
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly INVALID_PHONE: "INVALID_PHONE";
+    readonly INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS";
+    readonly AMOUNT_TOO_LOW: "AMOUNT_TOO_LOW";
+    readonly AMOUNT_TOO_HIGH: "AMOUNT_TOO_HIGH";
+    readonly LIMIT_EXCEEDED: "LIMIT_EXCEEDED";
+    readonly DUPLICATE: "DUPLICATE";
+    readonly MMO_UNAVAILABLE: "MMO_UNAVAILABLE";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly REFUND_NOT_ALLOWED: "REFUND_NOT_ALLOWED";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+declare class PawapayError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    readonly failureReason?: FailureReason;
+    readonly retryable: boolean;
+    readonly originalError?: Error;
+    constructor(message: string, code: ErrorCode, statusCode: number, options?: {
+        failureReason?: FailureReason;
+        retryable?: boolean;
+        originalError?: Error;
+    });
+    static fromPawapayResponse(pawapayCode: string, message?: string, originalError?: Error): PawapayError;
+    static validation(message: string): PawapayError;
+    static network(message: string, originalError?: Error): PawapayError;
+    static timeout(message?: string): PawapayError;
+    static unauthorized(message?: string): PawapayError;
+    static notFound(message?: string): PawapayError;
+    toJSON(): Record<string, unknown>;
+}
+
+export { ActionResponse, type ActiveConfigResponse, Correspondent, CorrespondentInfo, type CountryAvailability, type CountryConfig, Currency, type CurrencyConfig, type DepositCallbackData, DepositRequest, DepositResponse, type DomainAddRequest, ERROR_CODES, type Environment, type ErrorCode, FailureReason, type LogLevel, Logger, type MMOAvailability, type OperationStatus, type OperationType, type OperationTypeConfig, PawapayError, type PawapayWebhookEvent, PaymentPageRequest, PaymentPageResponse, type PayoutCallbackData, PayoutRequest, PayoutResponse, PollOptions, type PredictProviderRequest, type PredictProviderResponse, type Product, type ProductCreateRequest, type ProviderAvailability, type ProviderConfig, type ProviderOperationStatus, type PublicKeyResponse, RefundRequest, RefundResponse, type ResolvedConfig, SpaarkPayApiSdk, type SpaarkPayApiSdkConfig, type StatementCallbackData, type StatementData, type StatementFailureCode, type StatementRequest, type StatementResponse, type StatementStatus, type StatementStatusResponse, type StatementWallet, TransactionFilters, TransactionLimits, TransactionStatusResponse, type WalletBalance, type WalletBalancesResponse, type WebhookEventType };