@sonatel-os/juf/dist/core/index.d.ts

The community SDK for Orange Money, SMS, Email & Sonatel APIs on the Orange Developer Platform.

import * as axios from 'axios';
export { A as AuthenticationError, E as ExternalServiceError, J as JufError, V as ValidationError, f as fromAxiosError } from '../errors-UO7u5lEE.js';
import * as superstruct from 'superstruct';
export { C as Cache, a as CachingSystem } from '../cache-Bxhh3lYR.js';

/** @type {Logger} Singleton logger instance for internal JUF use. */
declare const logger: Logger;

/**
 * @class Logger
 * @classdesc Minimal structured logger for library-internal use.
 * Not intended for application-level logging — consumers should use their own logger.
 *
 * @example
 * import { logger } from './utils/logger.js';
 *
 * logger.info('Payment checkout prepared', { reference: 'INV001' });
 * logger.error('QR code generation failed', { reference: 'INV001', status: 500 });
 */
declare class Logger {
    /**
     * @param {object} options - Logger configuration.
     * @param {string} [options.prefix='juf'] - Log line prefix / service identifier.
     * @param {string} [options.level='info'] - Minimum log level to output.
     */
    constructor({ prefix, level }?: {
        prefix?: string | undefined;
        level?: string | undefined;
    });
    /**
     * Creates a child logger with a scoped prefix.
     * @param {string} scope - The scope name (e.g. 'payment', 'auth').
     * @returns {Logger} A new Logger instance with the scoped prefix.
     */
    child(scope: string): Logger;
    /**
     * @param {string} message - Log message.
     * @param {object} [context] - Structured context metadata.
     */
    error(message: string, context?: object | undefined): void;
    /**
     * @param {string} message - Log message.
     * @param {object} [context] - Structured context metadata.
     */
    warn(message: string, context?: object | undefined): void;
    /**
     * @param {string} message - Log message.
     * @param {object} [context] - Structured context metadata.
     */
    info(message: string, context?: object | undefined): void;
    /**
     * @param {string} message - Log message.
     * @param {object} [context] - Structured context metadata.
     */
    debug(message: string, context?: object | undefined): void;
    #private;
}

/**
 * @class Requester
 * @classdesc Utility class to create and configure Axios instances dynamically.
 * Each instance gets its own retry configuration instead of polluting the global axios.
 */
declare class Requester {
    /**
     * Creates a new Axios instance with custom configuration and per-instance retry.
     *
     * @static
     * @method bootstrap
     * @memberof Shared
     * @param {object} config - Custom configuration for Axios.
     * @param {string} config.baseURL - Base URL for requests.
     * @param {object} [config.agentParams] - HTTPS agent parameters.
     * @param {object|false} [config.retry] - Retry configuration, or false to disable.
     * @param {number} [config.retry.retries] - Number of retries (default: 2).
     * @param {number} [config.retry.baseDelay] - Base delay in ms for exponential backoff (default: 2000).
     * @returns {import('axios').AxiosInstance} A configured Axios instance.
     */
    static bootstrap(config: {
        baseURL: string;
        agentParams?: object | undefined;
        retry?: false | object | undefined;
    }): axios.AxiosInstance;
}

declare function validate(data: object, structure: superstruct.Struct, context: string): void;
declare function validateUrl(url: string, fieldName: string): void;
declare function validateUrls(urls: object): void;

declare function getApiUrl(): string;
declare function getApiEnv(): {
    onProd: boolean;
    onPProd: boolean;
};

declare function capitalizeTokenType(tokenType: string): string;
declare function buildAuthHeader(accessToken: string, tokenType: string): {
    Authorization: string;
};

/**
 * @namespace Constants
 * @description Centralized constants for the JUF library.
 * No magic values — every threshold, timeout, and config lives here.
 */
/** @type {number} Cache time-to-live for auth tokens in seconds. */
declare const AUTH_CACHE_TTL_SECONDS: number;
/** @type {number} Maximum number of retry attempts for failed HTTP requests. */
declare const MAX_RETRY_ATTEMPTS: number;
/** @type {number} Base delay between retries in milliseconds. */
declare const RETRY_BASE_DELAY_MS: number;
/** @type {number} HTTP status code that triggers automatic retry. */
declare const RETRYABLE_STATUS_CODE: number;
/** @type {string} Currency unit for payment amounts. */
declare const CURRENCY_UNIT: string;
/** @type {string} Default channel for SMS delivery. */
declare const SMS_CHANNEL: string;
/** @type {string} Content type for OAuth token requests. */
declare const OAUTH_CONTENT_TYPE: string;
/** @type {string} OAuth grant type used for machine-to-machine auth. */
declare const OAUTH_GRANT_TYPE: string;
/** @type {string} OAuth token endpoint path. */
declare const OAUTH_TOKEN_PATH: string;
/** @type {number} HTTP status for bad request / validation errors. */
declare const HTTP_BAD_REQUEST: number;
/** @type {number} HTTP status for authentication failures. */
declare const HTTP_UNAUTHORIZED: number;
/** @type {number} HTTP status for internal server errors. */
declare const HTTP_INTERNAL_SERVER_ERROR: number;
/** @type {number} HTTP status for bad gateway / upstream failures. */
declare const HTTP_BAD_GATEWAY: number;

declare const EMAIL_URI: "/api/communication/v1/emails";
declare const SMS_URI: "/api/communication/v1/messages";
declare const GENERATE_QR_URI: "/api/eWallet/v4/qrcode";
declare const GENERATE_PAYMENT_LINK_URI: "/api/v1/onlinePayment/prepare";
declare const DECODE_QR_URI: "/api/services/internal/v2/qrcodes/:id";

export { AUTH_CACHE_TTL_SECONDS, CURRENCY_UNIT, DECODE_QR_URI, EMAIL_URI, GENERATE_PAYMENT_LINK_URI, GENERATE_QR_URI, HTTP_BAD_GATEWAY, HTTP_BAD_REQUEST, HTTP_INTERNAL_SERVER_ERROR, HTTP_UNAUTHORIZED, MAX_RETRY_ATTEMPTS, OAUTH_CONTENT_TYPE, OAUTH_GRANT_TYPE, OAUTH_TOKEN_PATH, RETRYABLE_STATUS_CODE, RETRY_BASE_DELAY_MS, Requester, SMS_CHANNEL, SMS_URI, buildAuthHeader, capitalizeTokenType, getApiEnv, getApiUrl, logger, validate, validateUrl, validateUrls };