@pddo/exchange-rate-sdk/dist/index.d.mts

TypeScript SDK for Exchange Rate API - 汇率API的TypeScript SDK

/**
 * 汇率API响应的基础接口
 */
interface BaseResponse {
    message: string;
}
/**
 * 错误响应接口
 */
interface ErrorResponse {
    error: string;
}
/**
 * 货币转换响应接口（带金额）
 */
interface ConversionResponse extends BaseResponse {
    data: number;
    rate: number;
    base_code: string;
    target_code: string;
}
/**
 * 汇率查询响应接口（仅汇率）
 */
interface RateResponse extends BaseResponse {
    data: number;
    base_code: string;
    target_code: string;
}
/**
 * 获取特定基准货币汇率响应接口
 */
interface CurrencyRatesResponse extends BaseResponse {
    data: Record<string, number>;
}
/**
 * 更新汇率响应接口
 */
interface UpdateResponse extends BaseResponse {
    data: {
        result: string;
        conversion_rates: Record<string, number>;
        time_last_updated_unix: number;
        time_last_updated_utc: string;
        base_code: string;
    };
}
/**
 * SDK配置选项
 */
interface ExchangeRateSDKOptions {
    /**
     * API基础URL
     * @default "https://exchange-api.pd.do"
     */
    baseURL?: string;
    /**
     * 请求超时时间（毫秒）
     * @default 10000
     */
    timeout?: number;
    /**
     * 自定义请求头
     */
    headers?: Record<string, string>;
    /**
     * 是否启用调试模式
     * @default false
     */
    debug?: boolean;
}
/**
 * 货币代码类型（ISO 4217）
 */
type CurrencyCode = string;
/**
 * HTTP方法类型
 */
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
/**
 * 请求配置接口
 */
interface RequestConfig {
    method: HttpMethod;
    url: string;
    headers?: Record<string, string>;
    timeout?: number;
}
/**
 * API错误类
 */
declare class ExchangeRateAPIError extends Error {
    readonly status?: number;
    readonly code?: string;
    constructor(message: string, status?: number, code?: string);
}

/**
 * 汇率API SDK主类
 */
declare class ExchangeRateSDK {
    private client;
    /**
     * 创建ExchangeRateSDK实例
     * @param options SDK配置选项
     */
    constructor(options?: ExchangeRateSDKOptions);
    /**
     * 获取特定基准货币的所有汇率
     * @param currency 基准货币代码（如：USD, EUR, CNY）
     * @returns 以指定货币为基准的所有汇率
     *
     * @example
     * ```typescript
     * const rates = await sdk.getCurrencyRates('USD');
     * console.log(rates.data.EUR); // 美元对欧元的汇率
     * ```
     */
    getCurrencyRates(currency: CurrencyCode): Promise<CurrencyRatesResponse>;
    /**
     * 获取两种货币之间的汇率
     * @param baseCurrency 基准货币代码
     * @param targetCurrency 目标货币代码
     * @returns 汇率信息
     *
     * @example
     * ```typescript
     * const rate = await sdk.getExchangeRate('USD', 'EUR');
     * console.log(rate.data); // 美元对欧元的汇率
     * ```
     */
    getExchangeRate(baseCurrency: CurrencyCode, targetCurrency: CurrencyCode): Promise<RateResponse>;
    /**
     * 进行货币转换
     * @param baseCurrency 基准货币代码
     * @param targetCurrency 目标货币代码
     * @param amount 转换金额
     * @returns 转换结果，包含转换后的金额和汇率
     *
     * @example
     * ```typescript
     * const result = await sdk.convertCurrency('USD', 'EUR', 100);
     * console.log(result.data); // 100美元转换为欧元的金额
     * console.log(result.rate); // 使用的汇率
     * ```
     */
    convertCurrency(baseCurrency: CurrencyCode, targetCurrency: CurrencyCode, amount: number): Promise<ConversionResponse>;
    /**
     * 手动更新汇率数据（需要密码）
     * @param password 更新密码
     * @returns 更新结果
     *
     * @example
     * ```typescript
     * const result = await sdk.updateRates('your-password');
     * console.log(result.message); // 更新状态消息
     * ```
     */
    updateRates(password: string): Promise<UpdateResponse>;
    /**
     * 批量获取多个货币对的汇率
     * @param pairs 货币对数组，每个元素为 [基准货币, 目标货币]
     * @returns 所有货币对的汇率
     *
     * @example
     * ```typescript
     * const rates = await sdk.getBatchRates([
     *   ['USD', 'EUR'],
     *   ['USD', 'CNY'],
     *   ['EUR', 'JPY']
     * ]);
     * ```
     */
    getBatchRates(pairs: Array<[CurrencyCode, CurrencyCode]>): Promise<Array<RateResponse>>;
    /**
     * 批量进行货币转换
     * @param conversions 转换配置数组
     * @returns 所有转换结果
     *
     * @example
     * ```typescript
     * const results = await sdk.batchConvert([
     *   { from: 'USD', to: 'EUR', amount: 100 },
     *   { from: 'EUR', to: 'CNY', amount: 50 },
     * ]);
     * ```
     */
    batchConvert(conversions: Array<{
        from: CurrencyCode;
        to: CurrencyCode;
        amount: number;
    }>): Promise<Array<ConversionResponse>>;
    /**
     * 获取支持的货币列表（常用货币）
     * @returns 常用货币代码数组
     */
    getCommonCurrencies(): CurrencyCode[];
    /**
     * 验证货币代码格式
     * @param currency 货币代码
     * @returns 是否为有效格式
     */
    isValidCurrencyFormat(currency: string): boolean;
    /**
     * 格式化货币代码
     * @param currency 货币代码
     * @returns 格式化后的货币代码
     */
    formatCurrency(currency: string): CurrencyCode;
    /**
     * 更新SDK配置
     * @param options 新的配置选项
     */
    updateConfig(options: Partial<ExchangeRateSDKOptions>): void;
}

/**
 * HTTP客户端类，处理所有API请求
 */
declare class HttpClient {
    private baseURL;
    private timeout;
    private headers;
    private debug;
    constructor(options?: ExchangeRateSDKOptions);
    /**
     * 发送HTTP请求
     */
    request<T>(config: RequestConfig): Promise<T>;
    /**
     * 发送GET请求
     */
    get<T>(url: string, headers?: Record<string, string>): Promise<T>;
    /**
     * 更新基础URL
     */
    setBaseURL(baseURL: string): void;
    /**
     * 更新请求头
     */
    setHeaders(headers: Record<string, string>): void;
    /**
     * 设置调试模式
     */
    setDebug(debug: boolean): void;
}

/**
 * @pddo/exchange-rate-sdk
 *
 * TypeScript SDK for Exchange Rate API
 * 汇率API的TypeScript SDK
 *
 * @author PDDO <pub@pd.do>
 * @license MIT
 */

/**
 * 创建SDK实例的便捷函数
 * @param options SDK配置选项
 * @returns ExchangeRateSDK实例
 *
 * @example
 * ```typescript
 * import { createExchangeRateSDK } from '@pddo/exchange-rate-sdk';
 *
 * const sdk = createExchangeRateSDK({
 *   baseURL: 'https://your-api.com',
 *   timeout: 5000,
 *   debug: true
 * });
 * ```
 */
declare function createExchangeRateSDK(options?: ExchangeRateSDKOptions): ExchangeRateSDK;

export { type BaseResponse, type ConversionResponse, type CurrencyCode, type CurrencyRatesResponse, type ErrorResponse, ExchangeRateAPIError, ExchangeRateSDK, type ExchangeRateSDKOptions, HttpClient, type HttpMethod, type RateResponse, type RequestConfig, type UpdateResponse, createExchangeRateSDK, ExchangeRateSDK as default };