@plolink/sdk 0.0.4

package/dist/modules/billing/index.d.cts

@@ -0,0 +1,538 @@
+import { P as PlolinkClient } from '../../client-CAjIQKPm.cjs';
+import { P as Poller } from '../../poller-BlIRbwL4.cjs';
+import '../../core-77EbLgbp.cjs';
+import 'axios';
+
+/**
+ * Billing 模块类型
+ */
+/**
+ * 余额信息
+ */
+interface BalanceInfo {
+    /** 可用余额(字符串,保留精度) */
+    balance: string;
+    /** 可开票金额 */
+    invoiceableAmount: string;
+}
+/**
+ * 创建充值请求参数
+ */
+interface CreateRechargeParams {
+    /** 充值金额(单位:元) */
+    amount: number;
+    /** 充值描述 */
+    description?: string;
+    /** 是否需要二维码图片CDN URL */
+    needQrCodeImage?: boolean;
+}
+/**
+ * 微信充值响应
+ */
+interface WechatRechargeResult {
+    /** 订单号 */
+    orderNo: string;
+    /** 二维码URL(weixin://协议) */
+    qrCodeUrl: string;
+    /** 二维码图片URL(CDN地址,仅当请求时needQrCodeImage=true时返回) */
+    qrCodeImageUrl?: string;
+    /** 充值记录ID */
+    rechargeRecordId: string;
+}
+/**
+ * 订单状态
+ */
+type OrderStatus = 'pending' | 'success' | 'failed' | 'closed';
+/**
+ * 订单查询结果
+ */
+interface OrderStatusResult {
+    /** 订单号 */
+    orderNo: string;
+    /** 订单状态 */
+    status: OrderStatus;
+    /** 充值金额 */
+    amount: string;
+    /** 创建时间 */
+    createdAt: string;
+}
+/**
+ * 消耗统计
+ */
+interface ConsumptionStats {
+    /** 今日消耗 */
+    today: string;
+    /** 最近7天消耗 */
+    last7Days: string;
+    /** 最近30天消耗 */
+    last30Days: string;
+}
+/**
+ * 分页查询参数
+ */
+interface PaginationParams {
+    /** 页码,从1开始 */
+    page?: number;
+    /** 每页条数 */
+    pageSize?: number;
+}
+/**
+ * 分页查询结果
+ */
+interface PaginatedResult<T> {
+    /** 数据列表 */
+    list: T[];
+    /** 总条数 */
+    total: number;
+}
+/**
+ * 消费记录
+ */
+interface ConsumptionRecord {
+    id: string;
+    teamId: string;
+    userId: string;
+    amount: string;
+    purpose: string;
+    remark: string;
+    createdAt: string;
+}
+/**
+ * 充值记录
+ */
+interface RechargeRecord {
+    id: string;
+    teamId: string;
+    userId: string;
+    amount: string;
+    paymentMethod: string;
+    orderId?: string;
+    remark: string;
+    status: OrderStatus;
+    createdAt: string;
+}
+/**
+ * 开票记录
+ */
+interface InvoiceRecord {
+    id: string;
+    teamId: string;
+    amount: string;
+    invoiceNumber: string;
+    invoiceType: string;
+    invoiceTitle: string;
+    taxNumber: string;
+    fileKey: string;
+    remark: string;
+    operatorId: string;
+    createdAt: string;
+}
+/**
+ * 退费记录
+ */
+interface RefundRecord {
+    id: string;
+    teamId: string;
+    amount: string;
+    remark: string;
+    operatorId: string;
+    createdAt: string;
+}
+/**
+ * 对公账户信息
+ */
+interface CompanyAccount {
+    accountName: string;
+    accountNumber: string;
+    bankName: string;
+    currency: string;
+}
+/**
+ * 跨团队查询参数
+ */
+interface CrossTeamQueryParams {
+    /** 开始日期（ISO格式，必填） */
+    startDate: string;
+    /** 结束日期（ISO格式，必填） */
+    endDate: string;
+    /** 页码，从1开始，默认1 */
+    page?: number;
+    /** 每页条数，默认20，最大100 */
+    pageSize?: number;
+}
+/**
+ * 跨团队分页结果
+ */
+interface CrossTeamPaginatedResult<T> {
+    /** 数据列表 */
+    list: T[];
+    /** 总条数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页条数 */
+    pageSize: number;
+}
+/**
+ * 跨团队开票记录（包含团队名称）
+ */
+interface InvoiceRecordCrossTeam extends InvoiceRecord {
+    /** 团队名称 */
+    teamName: string;
+}
+/**
+ * 跨团队充值记录（包含团队名称）
+ */
+interface RechargeRecordCrossTeam extends RechargeRecord {
+    /** 团队名称 */
+    teamName: string;
+}
+/**
+ * 跨团队消费记录（包含团队名称）
+ */
+interface ConsumptionRecordCrossTeam extends ConsumptionRecord {
+    /** 团队名称 */
+    teamName: string;
+}
+/**
+ * 跨团队退费记录（包含团队名称）
+ */
+interface RefundRecordCrossTeam extends RefundRecord {
+    /** 团队名称 */
+    teamName: string;
+}
+
+/**
+ * 充值消费模块
+ *
+ * @description
+ * 提供完整的充值消费相关功能,包括:
+ * - 余额查询
+ * - 微信扫码充值(支持可选生成二维码图片)
+ * - 订单状态查询和轮询
+ * - 消费/充值/开票/退费记录查询
+ * - 消耗统计
+ * - 对公账户信息
+ *
+ * @example
+ * ```typescript
+ * import { PlolinkClient } from '@plolink/sdk';
+ * import { Billing } from '@plolink/sdk/billing';
+ *
+ * const client = new PlolinkClient({
+ *   mode: 'apiKey',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * const billing = new Billing(client);
+ *
+ * // 查询余额
+ * const balance = await billing.getBalance();
+ * console.log(`当前余额: ${balance.balance}`);
+ *
+ * // 发起充值(含二维码图片)
+ * const result = await billing.createRecharge({
+ *   amount: 100,
+ *   needQrCodeImage: true
+ * });
+ * console.log(`请扫码支付: ${result.qrCodeImageUrl}`);
+ *
+ * // 轮询订单状态
+ * const poller = billing.watchOrderStatus(result.orderNo, (status) => {
+ *   console.log(`订单状态: ${status.status}`);
+ *   if (status.status === 'success') {
+ *     console.log('支付成功!');
+ *   }
+ * });
+ * ```
+ *
+ * @module billing
+ */
+
+/**
+ * 充值消费模块
+ */
+declare class Billing {
+    private client;
+    constructor(client: PlolinkClient);
+    /**
+     * 获取团队余额信息
+     *
+     * @returns 余额信息,包括可用余额和可开票金额
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const balance = await billing.getBalance();
+     * console.log(`余额: ${balance.balance}, 可开票: ${balance.invoiceableAmount}`);
+     * ```
+     */
+    getBalance(): Promise<BalanceInfo>;
+    /**
+     * 创建微信充值订单
+     *
+     * @param params - 充值参数
+     * @returns 充值订单信息,包含二维码URL和订单号
+     * @throws {PlolinkError} 当金额无效或创建失败时抛出
+     *
+     * @example
+     * ```typescript
+     * // 基础充值(仅返回二维码URL)
+     * const result = await billing.createRecharge({
+     *   amount: 100,
+     *   description: '充值100元'
+     * });
+     * console.log(`请使用微信扫描: ${result.qrCodeUrl}`);
+     *
+     * // 充值并获取二维码图片
+     * const result = await billing.createRecharge({
+     *   amount: 100,
+     *   needQrCodeImage: true
+     * });
+     * console.log(`二维码图片地址: ${result.qrCodeImageUrl}`);
+     * ```
+     */
+    createRecharge(params: CreateRechargeParams): Promise<WechatRechargeResult>;
+    /**
+     * 查询订单状态
+     *
+     * @param orderNo - 订单号
+     * @returns 订单状态信息
+     * @throws {PlolinkError} 当订单不存在时抛出
+     *
+     * @example
+     * ```typescript
+     * const status = await billing.getOrderStatus('ORDER_123');
+     * console.log(`订单状态: ${status.status}`);
+     * ```
+     */
+    getOrderStatus(orderNo: string): Promise<OrderStatusResult>;
+    /**
+     * 轮询订单状态
+     *
+     * @description
+     * 创建一个轮询器持续监听订单状态变化,直到订单达到终态(success/failed/closed)。
+     * 使用指数退避策略,初始间隔1秒,最大间隔30秒。
+     *
+     * @param orderNo - 订单号
+     * @param onStatusChange - 状态变化回调函数
+     * @returns Poller实例,可用于手动停止轮询
+     *
+     * @example
+     * ```typescript
+     * const poller = billing.watchOrderStatus('ORDER_123', (status) => {
+     *   console.log(`状态更新: ${status.status}`);
+     *
+     *   if (status.status === 'success') {
+     *     console.log('支付成功!');
+     *   } else if (status.status === 'failed') {
+     *     console.error('支付失败!');
+     *   }
+     * });
+     *
+     * // 开始轮询
+     * poller.start();
+     *
+     * // 需要时可以手动停止
+     * // poller.stop();
+     * ```
+     */
+    watchOrderStatus(orderNo: string, onStatusChange: (status: OrderStatusResult) => void): Poller<OrderStatusResult>;
+    /**
+     * 获取消耗统计
+     *
+     * @returns 消耗统计信息(今日/7天/30天)
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const stats = await billing.getConsumptionStats();
+     * console.log(`今日消耗: ${stats.today}`);
+     * console.log(`7天消耗: ${stats.last7Days}`);
+     * console.log(`30天消耗: ${stats.last30Days}`);
+     * ```
+     */
+    getConsumptionStats(): Promise<ConsumptionStats>;
+    /**
+     * 获取消费记录(分页)
+     *
+     * @param params - 分页参数
+     * @returns 消费记录列表和总数
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await billing.getConsumptionRecords({
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     * console.log(`共 ${result.total} 条记录`);
+     * result.list.forEach(record => {
+     *   console.log(`消费: ${record.amount}, 用途: ${record.purpose}`);
+     * });
+     * ```
+     */
+    getConsumptionRecords(params?: PaginationParams): Promise<PaginatedResult<ConsumptionRecord>>;
+    /**
+     * 获取充值记录
+     *
+     * @returns 充值记录列表
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const records = await billing.getRechargeRecords();
+     * records.forEach(record => {
+     *   console.log(`${record.createdAt}: ${record.amount}, 状态: ${record.status}`);
+     * });
+     * ```
+     */
+    getRechargeRecords(): Promise<RechargeRecord[]>;
+    /**
+     * 获取开票记录
+     *
+     * @returns 开票记录列表
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const records = await billing.getInvoiceRecords();
+     * records.forEach(record => {
+     *   console.log(`发票: ${record.invoiceNumber}, 金额: ${record.amount}`);
+     * });
+     * ```
+     */
+    getInvoiceRecords(): Promise<InvoiceRecord[]>;
+    /**
+     * 获取退费记录
+     *
+     * @returns 退费记录列表
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const records = await billing.getRefundRecords();
+     * records.forEach(record => {
+     *   console.log(`退费: ${record.amount}, 备注: ${record.remark}`);
+     * });
+     * ```
+     */
+    getRefundRecords(): Promise<RefundRecord[]>;
+    /**
+     * 获取对公账户信息
+     *
+     * @returns 对公账户信息
+     * @throws {PlolinkError} 当请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const account = await billing.getCompanyAccount();
+     * console.log(`账户名: ${account.accountName}`);
+     * console.log(`账号: ${account.accountNumber}`);
+     * console.log(`开户行: ${account.bankName}`);
+     * ```
+     */
+    getCompanyAccount(): Promise<CompanyAccount>;
+    /**
+     * 获取跨团队开票记录
+     *
+     * 用于财务人员在多个团队中拥有财务权限时查询所有可管理团队的开票记录
+     *
+     * @param params - 查询参数
+     * @returns 分页结果（包含团队名称）
+     * @throws {PlolinkError} 当参数无效或请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await billing.getInvoiceRecordsCrossTeam({
+     *   startDate: '2025-01-01T00:00:00.000Z',
+     *   endDate: '2025-01-31T23:59:59.999Z',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     *
+     * console.log(`共查询到 ${result.total} 条记录`);
+     * result.list.forEach(record => {
+     *   console.log(`团队: ${record.teamName}, 发票号: ${record.invoiceNumber}, 金额: ${record.amount}`);
+     * });
+     * ```
+     */
+    getInvoiceRecordsCrossTeam(params: CrossTeamQueryParams): Promise<CrossTeamPaginatedResult<InvoiceRecordCrossTeam>>;
+    /**
+     * 获取跨团队充值记录
+     *
+     * 用于财务人员在多个团队中拥有财务权限时查询所有可管理团队的充值记录
+     *
+     * @param params - 查询参数
+     * @returns 分页结果（包含团队名称）
+     * @throws {PlolinkError} 当参数无效或请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await billing.getRechargeRecordsCrossTeam({
+     *   startDate: '2025-01-01T00:00:00.000Z',
+     *   endDate: '2025-01-31T23:59:59.999Z',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     *
+     * console.log(`共查询到 ${result.total} 条记录`);
+     * result.list.forEach(record => {
+     *   console.log(`团队: ${record.teamName}, 金额: ${record.amount}, 状态: ${record.status}`);
+     * });
+     * ```
+     */
+    getRechargeRecordsCrossTeam(params: CrossTeamQueryParams): Promise<CrossTeamPaginatedResult<RechargeRecordCrossTeam>>;
+    /**
+     * 获取跨团队消费记录
+     *
+     * 用于财务人员在多个团队中拥有财务权限时查询所有可管理团队的消费记录
+     *
+     * @param params - 查询参数
+     * @returns 分页结果（包含团队名称）
+     * @throws {PlolinkError} 当参数无效或请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await billing.getConsumptionRecordsCrossTeam({
+     *   startDate: '2025-01-01T00:00:00.000Z',
+     *   endDate: '2025-01-31T23:59:59.999Z',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     *
+     * console.log(`共查询到 ${result.total} 条记录`);
+     * result.list.forEach(record => {
+     *   console.log(`团队: ${record.teamName}, 金额: ${record.amount}, 用途: ${record.purpose}`);
+     * });
+     * ```
+     */
+    getConsumptionRecordsCrossTeam(params: CrossTeamQueryParams): Promise<CrossTeamPaginatedResult<ConsumptionRecordCrossTeam>>;
+    /**
+     * 获取跨团队退费记录
+     *
+     * 用于财务人员在多个团队中拥有财务权限时查询所有可管理团队的退费记录
+     *
+     * @param params - 查询参数
+     * @returns 分页结果（包含团队名称）
+     * @throws {PlolinkError} 当参数无效或请求失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const result = await billing.getRefundRecordsCrossTeam({
+     *   startDate: '2025-01-01T00:00:00.000Z',
+     *   endDate: '2025-01-31T23:59:59.999Z',
+     *   page: 1,
+     *   pageSize: 20
+     * });
+     *
+     * console.log(`共查询到 ${result.total} 条记录`);
+     * result.list.forEach(record => {
+     *   console.log(`团队: ${record.teamName}, 金额: ${record.amount}, 备注: ${record.remark}`);
+     * });
+     * ```
+     */
+    getRefundRecordsCrossTeam(params: CrossTeamQueryParams): Promise<CrossTeamPaginatedResult<RefundRecordCrossTeam>>;
+}
+
+export { type BalanceInfo, Billing, type CompanyAccount, type ConsumptionRecord, type ConsumptionRecordCrossTeam, type ConsumptionStats, type CreateRechargeParams, type CrossTeamPaginatedResult, type CrossTeamQueryParams, type InvoiceRecord, type InvoiceRecordCrossTeam, type OrderStatus, type OrderStatusResult, type PaginatedResult, type PaginationParams, type RechargeRecord, type RechargeRecordCrossTeam, type RefundRecord, type RefundRecordCrossTeam, type WechatRechargeResult };