@plolink/sdk 0.0.4

package/dist/client-CwNikk7i.d.ts

@@ -0,0 +1,193 @@
+import { b as LoggerFunction, S as SDKConfig } from './core-77EbLgbp.js';
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+/**
+ * SDK 内部日志器
+ *
+ * @description
+ * 提供统一的日志接口，支持用户自定义日志钩子。
+ * 默认使用 console 输出，用户可以通过配置自定义 logger 函数来集成 Sentry 等监控系统。
+ *
+ * @example
+ * ```typescript
+ * const logger = new InternalLogger((level, message, data) => {
+ *   // 自定义日志处理，例如发送到 Sentry
+ *   console.log(`[${level}] ${message}`, data);
+ * });
+ *
+ * logger.info('Operation started', { userId: '123' });
+ * logger.error('Operation failed', { error: 'Network timeout' });
+ * ```
+ */
+declare class InternalLogger {
+    /**
+     * 用户自定义的日志钩子函数
+     */
+    private readonly userLogger?;
+    /**
+     * 是否启用日志输出
+     * 可以通过环境变量 PLOLINK_SDK_DEBUG 控制
+     */
+    private readonly isDebugEnabled;
+    /**
+     * 创建一个 InternalLogger 实例
+     *
+     * @param userLogger - 用户自定义的日志钩子函数
+     */
+    constructor(userLogger?: LoggerFunction);
+    /**
+     * 记录信息级别日志
+     *
+     * @param message - 日志消息
+     * @param context - 附加上下文数据
+     */
+    info(message: string, context?: unknown): void;
+    /**
+     * 记录警告级别日志
+     *
+     * @param message - 日志消息
+     * @param context - 附加上下文数据
+     */
+    warn(message: string, context?: unknown): void;
+    /**
+     * 记录错误级别日志
+     *
+     * @param message - 日志消息
+     * @param context - 附加上下文数据
+     */
+    error(message: string, context?: unknown): void;
+    /**
+     * 记录调试级别日志
+     * 只有在 debug 模式下才会输出
+     *
+     * @param message - 日志消息
+     * @param context - 附加上下文数据
+     */
+    debug(message: string, context?: unknown): void;
+    /**
+     * 内部日志记录方法
+     *
+     * @param level - 日志级别
+     * @param message - 日志消息
+     * @param context - 附加上下文数据
+     */
+    private log;
+    /**
+     * 创建一个带有固定上下文的子 logger
+     *
+     * @param context - 固定的上下文数据
+     * @returns 新的 logger 实例
+     *
+     * @example
+     * ```typescript
+     * const logger = new InternalLogger();
+     * const moduleLogger = logger.withContext({ module: 'billing' });
+     * moduleLogger.info('Payment processed'); // 日志会自动带上 module: 'billing'
+     * ```
+     */
+    withContext(context: Record<string, unknown>): InternalLogger;
+}
+
+/**
+ * 为 Axios 实例添加类型安全的请求方法
+ *
+ * @description
+ * 这些方法封装了 Axios 的原始方法，提供更好的类型推断。
+ */
+interface TypedAxiosInstance extends AxiosInstance {
+    get<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    put<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    patch<T = unknown>(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    delete<T = unknown>(url: string, config?: AxiosRequestConfig): Promise<T>;
+}
+
+/**
+ * Plolink SDK 客户端主类
+ *
+ * @description
+ * PlolinkClient 是 SDK 的核心类，负责：
+ * - 管理 SDK 配置（认证 Token、API 地址等）
+ * - 初始化 Axios 实例并配置拦截器
+ * - 提供统一的日志接口
+ * - 作为所有业务模块的基础依赖
+ *
+ * @example
+ * ```typescript
+ * // 使用 ApiKey
+ * const client = new PlolinkClient({
+ *   token: 'sk-123456789',
+ *   logger: (level, msg, data) => {
+ *     console.log(`[${level}] ${msg}`, data);
+ *   }
+ * });
+ *
+ * // 使用 SessionId (登录后获取)
+ * const client = new PlolinkClient({
+ *   token: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+ *   baseUrl: 'https://api.plolink.com'
+ * });
+ * ```
+ */
+declare class PlolinkClient {
+    /**
+     * SDK 配置对象（已填充默认值）
+     */
+    readonly config: Required<SDKConfig>;
+    /**
+     * Axios 实例，用于发起 HTTP 请求
+     */
+    readonly axiosInstance: TypedAxiosInstance;
+    /**
+     * 内部日志记录器
+     */
+    readonly logger: InternalLogger;
+    /**
+     * 创建一个 PlolinkClient 实例
+     *
+     * @param config - SDK 配置对象
+     * @throws {PlolinkError} 当配置验证失败时抛出
+     *
+     * @example
+     * ```typescript
+     * const client = new PlolinkClient({
+     *   token: 'sk-your-api-key'
+     * });
+     * ```
+     */
+    constructor(config: SDKConfig);
+    /**
+     * 验证 SDK 配置
+     *
+     * @param config - SDK 配置对象
+     * @throws {PlolinkError} 当配置不合法时抛出
+     * @private
+     */
+    private validateConfig;
+    /**
+     * 获取当前 SDK 版本
+     *
+     * @returns SDK 版本号
+     */
+    getVersion(): string;
+    /**
+     * 检查客户端健康状态
+     *
+     * @returns 健康状态信息
+     *
+     * @example
+     * ```typescript
+     * const health = client.healthCheck();
+     * console.log(health);
+     * // { status: 'ok', baseUrl: '...', version: '...' }
+     * ```
+     */
+    healthCheck(): {
+        status: 'ok';
+        baseUrl: string;
+        version: string;
+        hasToken: boolean;
+    };
+}
+
+export { InternalLogger as I, PlolinkClient as P };

package/dist/common/index.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+var chunkNS3DJP2O_cjs = require('../chunk-NS3DJP2O.cjs');
+var chunkJR4HYYQI_cjs = require('../chunk-JR4HYYQI.cjs');
+
+
+
+Object.defineProperty(exports, "EventEmitter", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.EventEmitter; }
+});
+Object.defineProperty(exports, "TypedEventEmitter", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.TypedEventEmitter; }
+});
+Object.defineProperty(exports, "assertEnvironment", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.assertEnvironment; }
+});
+Object.defineProperty(exports, "environmentInfo", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.environmentInfo; }
+});
+Object.defineProperty(exports, "features", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.features; }
+});
+Object.defineProperty(exports, "getEnvironment", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.getEnvironment; }
+});
+Object.defineProperty(exports, "getFileName", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.getFileName; }
+});
+Object.defineProperty(exports, "getFileSize", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.getFileSize; }
+});
+Object.defineProperty(exports, "isBrowser", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.isBrowser; }
+});
+Object.defineProperty(exports, "isNode", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.isNode; }
+});
+Object.defineProperty(exports, "isValidFileInput", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.isValidFileInput; }
+});
+Object.defineProperty(exports, "isWebWorker", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.isWebWorker; }
+});
+Object.defineProperty(exports, "safeDynamicImport", {
+  enumerable: true,
+  get: function () { return chunkNS3DJP2O_cjs.safeDynamicImport; }
+});
+Object.defineProperty(exports, "Poller", {
+  enumerable: true,
+  get: function () { return chunkJR4HYYQI_cjs.Poller; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/common/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/common/index.d.cts

@@ -0,0 +1,422 @@
+export { P as Poller } from '../poller-BlIRbwL4.cjs';
+import '../core-77EbLgbp.cjs';
+
+/**
+ * 事件处理函数类型
+ */
+type EventHandler<T = unknown> = (data: T) => void;
+/**
+ * 事件发射器基础类
+ *
+ * @description
+ * 提供简单的事件订阅/发布机制，用于业务模块的状态变化通知。
+ * 支持类型安全的事件处理，适用于状态变化、进度更新等场景。
+ *
+ * @example
+ * ```typescript
+ * // 创建事件发射器
+ * const emitter = new EventEmitter();
+ *
+ * // 订阅事件
+ * const unsubscribe = emitter.on('status-change', (data) => {
+ *   console.log('Status changed:', data);
+ * });
+ *
+ * // 触发事件
+ * emitter.emit('status-change', { status: 'completed' });
+ *
+ * // 取消订阅
+ * unsubscribe();
+ *
+ * // 一次性事件
+ * emitter.once('complete', (data) => {
+ *   console.log('Completed:', data);
+ * });
+ * ```
+ */
+declare class EventEmitter {
+    /**
+     * 事件处理器映射表
+     */
+    private handlers;
+    /**
+     * 一次性事件处理器集合
+     */
+    private onceHandlers;
+    /**
+     * 订阅事件
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理函数
+     * @returns 取消订阅的函数
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = emitter.on('data', (payload) => {
+     *   console.log('Received:', payload);
+     * });
+     *
+     * // 不再需要时取消订阅
+     * unsubscribe();
+     * ```
+     */
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * 订阅一次性事件
+     *
+     * @description
+     * 事件处理函数只会执行一次，执行后自动取消订阅。
+     *
+     * @param event - 事件名称
+     * @param handler - 事件处理函数
+     * @returns 取消订阅的函数
+     *
+     * @example
+     * ```typescript
+     * emitter.once('complete', (result) => {
+     *   console.log('Task completed:', result);
+     * });
+     * ```
+     */
+    once<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    /**
+     * 触发事件
+     *
+     * @param event - 事件名称
+     * @param data - 传递给处理函数的数据
+     *
+     * @example
+     * ```typescript
+     * emitter.emit('status-change', {
+     *   from: 'pending',
+     *   to: 'completed'
+     * });
+     * ```
+     */
+    emit<T = unknown>(event: string, data: T): void;
+    /**
+     * 取消订阅指定事件的处理器
+     *
+     * @param event - 事件名称
+     * @param handler - 可选，要取消的事件处理函数。如果不提供，则取消所有处理器
+     *
+     * @example
+     * ```typescript
+     * // 取消所有处理器
+     * emitter.off('status-change');
+     *
+     * // 取消特定处理器
+     * const handler = (data) => console.log(data);
+     * emitter.on('data', handler);
+     * emitter.off('data', handler);
+     * ```
+     */
+    off<T = unknown>(event: string, handler?: EventHandler<T>): void;
+    /**
+     * 清除所有事件处理器
+     *
+     * @example
+     * ```typescript
+     * emitter.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * 获取指定事件的处理器数量
+     *
+     * @param event - 事件名称
+     * @returns 处理器数量
+     *
+     * @example
+     * ```typescript
+     * const count = emitter.listenerCount('status-change');
+     * console.log(`${count} listeners registered`);
+     * ```
+     */
+    listenerCount(event: string): number;
+    /**
+     * 获取所有已注册的事件名称
+     *
+     * @returns 事件名称数组
+     *
+     * @example
+     * ```typescript
+     * const events = emitter.eventNames();
+     * console.log('Registered events:', events);
+     * ```
+     */
+    eventNames(): string[];
+}
+/**
+ * 类型安全的事件发射器
+ *
+ * @description
+ * 提供类型约束的事件发射器，确保事件名称和数据类型的正确性。
+ *
+ * @template TEvents - 事件映射类型
+ *
+ * @example
+ * ```typescript
+ * // 定义事件类型
+ * interface TaskEvents {
+ *   'status-change': { status: string };
+ *   'progress': { percent: number };
+ *   'error': { message: string };
+ * }
+ *
+ * // 创建类型安全的发射器
+ * const emitter = new TypedEventEmitter<TaskEvents>();
+ *
+ * // TypeScript 会检查事件名称和数据类型
+ * emitter.on('status-change', (data) => {
+ *   console.log(data.status); // TypeScript 知道 data 有 status 属性
+ * });
+ *
+ * emitter.emit('status-change', { status: 'completed' }); // OK
+ * emitter.emit('status-change', { wrong: 'data' }); // TypeScript 报错
+ * ```
+ */
+declare class TypedEventEmitter<TEvents extends Record<string, unknown>> {
+    private emitter;
+    /**
+     * 订阅事件（类型安全）
+     */
+    on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void;
+    /**
+     * 订阅一次性事件（类型安全）
+     */
+    once<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void;
+    /**
+     * 触发事件（类型安全）
+     */
+    emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void;
+    /**
+     * 取消订阅（类型安全）
+     */
+    off<K extends keyof TEvents>(event: K, handler?: EventHandler<TEvents[K]>): void;
+    /**
+     * 清除所有事件处理器
+     */
+    clear(): void;
+    /**
+     * 获取指定事件的处理器数量
+     */
+    listenerCount<K extends keyof TEvents>(event: K): number;
+    /**
+     * 获取所有已注册的事件名称
+     */
+    eventNames(): Array<keyof TEvents>;
+}
+
+/**
+ * 环境适配工具
+ *
+ * @description
+ * 提供跨环境（Node.js / 浏览器）的工具函数和类型检测。
+ * 用于处理文件上传、网络请求等在不同环境下有差异的功能。
+ */
+/**
+ * 检测当前是否运行在 Node.js 环境
+ *
+ * @returns 如果在 Node.js 环境返回 true，否则返回 false
+ *
+ * @example
+ * ```typescript
+ * if (isNode) {
+ *   // 使用 Node.js 特有的 API
+ *   const fs = require('fs');
+ * }
+ * ```
+ */
+declare const isNode: boolean;
+/**
+ * 检测当前是否运行在浏览器环境
+ *
+ * @returns 如果在浏览器环境返回 true，否则返回 false
+ *
+ * @example
+ * ```typescript
+ * if (isBrowser) {
+ *   // 使用浏览器 API
+ *   const file = new File(['content'], 'file.txt');
+ * }
+ * ```
+ */
+declare const isBrowser: boolean;
+/**
+ * 检测当前是否支持 Web Worker
+ *
+ * @returns 如果支持 Web Worker 返回 true，否则返回 false
+ */
+declare const isWebWorker: boolean;
+/**
+ * 获取运行环境类型
+ *
+ * @returns 环境类型字符串
+ *
+ * @example
+ * ```typescript
+ * const env = getEnvironment();
+ * console.log(`Running in ${env}`); // "node" 或 "browser" 或 "worker"
+ * ```
+ */
+declare function getEnvironment(): 'node' | 'browser' | 'worker' | 'unknown';
+/**
+ * 文件类型联合类型
+ * 在 Node.js 中是 Buffer，在浏览器中是 Blob 或 File
+ */
+type FileInput = Buffer | Blob | File;
+/**
+ * 检测是否为有效的文件输入
+ *
+ * @param input - 待检测的输入
+ * @returns 如果是有效的文件输入返回 true
+ *
+ * @example
+ * ```typescript
+ * const file = new File(['content'], 'test.txt');
+ * if (isValidFileInput(file)) {
+ *   // 处理文件
+ * }
+ * ```
+ */
+declare function isValidFileInput(input: unknown): input is FileInput;
+/**
+ * 获取文件输入的大小（字节）
+ *
+ * @param input - 文件输入
+ * @returns 文件大小（字节）
+ * @throws {Error} 如果输入类型不支持
+ *
+ * @example
+ * ```typescript
+ * const file = new File(['content'], 'test.txt');
+ * const size = getFileSize(file);
+ * console.log(`File size: ${size} bytes`);
+ * ```
+ */
+declare function getFileSize(input: FileInput): number;
+/**
+ * 获取文件名（仅适用于 File 对象）
+ *
+ * @param input - 文件输入
+ * @returns 文件名，如果无法获取则返回 undefined
+ *
+ * @example
+ * ```typescript
+ * const file = new File(['content'], 'test.txt');
+ * const name = getFileName(file);
+ * console.log(name); // "test.txt"
+ * ```
+ */
+declare function getFileName(input: FileInput): string | undefined;
+/**
+ * 环境特定功能检测
+ */
+declare const features: {
+    /**
+     * 是否支持 FormData
+     */
+    readonly hasFormData: boolean;
+    /**
+     * 是否支持 Blob
+     */
+    readonly hasBlob: boolean;
+    /**
+     * 是否支持 File
+     */
+    readonly hasFile: boolean;
+    /**
+     * 是否支持 FileReader
+     */
+    readonly hasFileReader: boolean;
+    /**
+     * 是否支持 fetch API
+     */
+    readonly hasFetch: boolean;
+    /**
+     * 是否支持 Stream API
+     */
+    readonly hasStream: boolean;
+};
+/**
+ * 环境信息对象
+ *
+ * @example
+ * ```typescript
+ * console.log(environmentInfo);
+ * // {
+ * //   type: 'browser',
+ * //   isNode: false,
+ * //   isBrowser: true,
+ * //   features: { ... }
+ * // }
+ * ```
+ */
+declare const environmentInfo: {
+    readonly type: "node" | "browser" | "worker" | "unknown";
+    readonly isNode: boolean;
+    readonly isBrowser: boolean;
+    readonly isWebWorker: boolean;
+    readonly features: {
+        /**
+         * 是否支持 FormData
+         */
+        readonly hasFormData: boolean;
+        /**
+         * 是否支持 Blob
+         */
+        readonly hasBlob: boolean;
+        /**
+         * 是否支持 File
+         */
+        readonly hasFile: boolean;
+        /**
+         * 是否支持 FileReader
+         */
+        readonly hasFileReader: boolean;
+        /**
+         * 是否支持 fetch API
+         */
+        readonly hasFetch: boolean;
+        /**
+         * 是否支持 Stream API
+         */
+        readonly hasStream: boolean;
+    };
+};
+/**
+ * 断言当前环境
+ *
+ * @param expectedEnv - 期望的环境类型
+ * @param message - 自定义错误消息
+ * @throws {Error} 如果当前环境不符合预期
+ *
+ * @example
+ * ```typescript
+ * // 确保在 Node.js 环境中运行
+ * assertEnvironment('node', 'This feature requires Node.js');
+ * ```
+ */
+declare function assertEnvironment(expectedEnv: 'node' | 'browser' | 'worker', message?: string): void;
+/**
+ * 安全地动态导入模块（仅 Node.js）
+ *
+ * @description
+ * 在 Node.js 环境中动态导入模块，避免在浏览器环境中引起错误。
+ *
+ * @param moduleName - 模块名称
+ * @returns Promise，resolve 为模块对象
+ * @throws {Error} 如果不在 Node.js 环境或模块加载失败
+ *
+ * @example
+ * ```typescript
+ * if (isNode) {
+ *   const fs = await safeDynamicImport('fs');
+ *   const content = fs.readFileSync('file.txt', 'utf-8');
+ * }
+ * ```
+ */
+declare function safeDynamicImport<T = unknown>(moduleName: string): Promise<T>;
+
+export { EventEmitter, type FileInput, TypedEventEmitter, assertEnvironment, environmentInfo, features, getEnvironment, getFileName, getFileSize, isBrowser, isNode, isValidFileInput, isWebWorker, safeDynamicImport };