sa2kit 1.0.0

package/dist/universalFile/index.d.ts

@@ -0,0 +1,310 @@
+import { U as UploadFileInfo, a as UploadProgress, F as FileMetadata, b as FileQueryOptions, P as PaginatedResult, B as BatchOperationResult } from '../types-CoGG1rNV.js';
+export { A as AccessPermission, k as AudioProcessingOptions, C as CDNProviderError, g as CDNType, n as FileEvent, o as FileEventListener, m as FileEventType, e as FileProcessingError, c as FileServiceError, d as FileUploadError, I as ImageProcessingOptions, j as ProcessingOptions, h as ProcessorType, S as StorageProviderError, f as StorageType, l as UploadResult, i as UploadStatus, V as VideoProcessingOptions } from '../types-CoGG1rNV.js';
+
+/**
+ * 通用文件服务客户端SDK
+ *
+ * 提供文件上传、下载、查询等功能的客户端接口
+ */
+
+interface UniversalFileClientConfig {
+    /** API基础URL */
+    baseUrl?: string;
+    /** 请求超时时间(毫秒) */
+    timeout?: number;
+    /** 上传超时时间(毫秒) */
+    uploadTimeout?: number;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+}
+/**
+ * 通用文件服务客户端
+ */
+declare class UniversalFileClient {
+    private config;
+    constructor(config?: UniversalFileClientConfig);
+    /**
+     * 上传文件
+     */
+    uploadFile(fileInfo: UploadFileInfo, onProgress?: (progress: UploadProgress) => void): Promise<FileMetadata>;
+    /**
+     * 获取文件访问URL
+     */
+    getFileUrl(fileId: string, expiresIn?: number): Promise<string>;
+    /**
+     * 获取文件元数据
+     */
+    getFileMetadata(fileId: string): Promise<FileMetadata>;
+    /**
+     * 查询文件列表
+     */
+    queryFiles(options: FileQueryOptions): Promise<PaginatedResult<FileMetadata>>;
+    /**
+     * 删除文件
+     */
+    deleteFile(fileId: string): Promise<void>;
+    /**
+     * 批量删除文件
+     */
+    batchDeleteFiles(fileIds: string[]): Promise<BatchOperationResult>;
+    /**
+     * 获取上传进度
+     */
+    getUploadProgress(fileId: string): Promise<UploadProgress>;
+    /**
+     * 获取请求头
+     */
+    private getHeaders;
+    /**
+     * 带超时的fetch请求
+     */
+    private fetchWithTimeout;
+    /**
+     * 转换API返回的文件元数据
+     */
+    private transformFileMetadataFromAPI;
+}
+/**
+ * 默认客户端实例
+ */
+declare const universalFileClient: UniversalFileClient;
+/**
+ * 创建自定义客户端实例
+ */
+declare function createFileClient(config?: UniversalFileClientConfig): UniversalFileClient;
+
+/**
+ * 通用文件服务常量定义
+ */
+/** 模块版本 */
+declare const UNIVERSAL_FILE_VERSION = "1.0.0";
+/** 模块名称 */
+declare const UNIVERSAL_FILE_NAME = "@qhr123/sa2kit/universalFile";
+/** 默认最大文件大小(字节) - 100MB */
+declare const DEFAULT_MAX_FILE_SIZE: number;
+/** 默认最大图片大小(字节) - 10MB */
+declare const DEFAULT_MAX_IMAGE_SIZE: number;
+/** 默认最大视频大小(字节) - 500MB */
+declare const DEFAULT_MAX_VIDEO_SIZE: number;
+/** 默认最大音频大小(字节) - 50MB */
+declare const DEFAULT_MAX_AUDIO_SIZE: number;
+/** 默认最大文档大小(字节) - 20MB */
+declare const DEFAULT_MAX_DOCUMENT_SIZE: number;
+/** 图片MIME类型 */
+declare const IMAGE_MIME_TYPES: string[];
+/** 视频MIME类型 */
+declare const VIDEO_MIME_TYPES: string[];
+/** 音频MIME类型 */
+declare const AUDIO_MIME_TYPES: string[];
+/** 文档MIME类型 */
+declare const DOCUMENT_MIME_TYPES: string[];
+/** 所有支持的MIME类型 */
+declare const ALL_SUPPORTED_MIME_TYPES: string[];
+/** 图片扩展名 */
+declare const IMAGE_EXTENSIONS: string[];
+/** 视频扩展名 */
+declare const VIDEO_EXTENSIONS: string[];
+/** 音频扩展名 */
+declare const AUDIO_EXTENSIONS: string[];
+/** 文档扩展名 */
+declare const DOCUMENT_EXTENSIONS: string[];
+/** API基础路径 */
+declare const API_BASE_PATH = "/api/universal-file";
+/** API端点 */
+declare const API_ENDPOINTS: {
+    /** 上传文件 */
+    readonly UPLOAD: "/api/universal-file/upload";
+    /** 获取文件URL */
+    readonly GET_URL: (fileId: string) => string;
+    /** 获取文件元数据 */
+    readonly GET_METADATA: (fileId: string) => string;
+    /** 删除文件 */
+    readonly DELETE: (fileId: string) => string;
+    /** 查询文件列表 */
+    readonly QUERY: "/api/universal-file/files";
+    /** 批量删除 */
+    readonly BATCH_DELETE: "/api/universal-file/files/batch-delete";
+    /** 获取上传进度 */
+    readonly GET_PROGRESS: (fileId: string) => string;
+};
+/** 错误代码 */
+declare const ERROR_CODES: {
+    /** 文件上传错误 */
+    readonly FILE_UPLOAD_ERROR: "FILE_UPLOAD_ERROR";
+    /** 文件大小超限 */
+    readonly FILE_SIZE_EXCEEDED: "FILE_SIZE_EXCEEDED";
+    /** 文件类型不支持 */
+    readonly FILE_TYPE_NOT_SUPPORTED: "FILE_TYPE_NOT_SUPPORTED";
+    /** 文件不存在 */
+    readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+    /** 文件处理错误 */
+    readonly FILE_PROCESSING_ERROR: "FILE_PROCESSING_ERROR";
+    /** 存储提供者错误 */
+    readonly STORAGE_PROVIDER_ERROR: "STORAGE_PROVIDER_ERROR";
+    /** CDN提供者错误 */
+    readonly CDN_PROVIDER_ERROR: "CDN_PROVIDER_ERROR";
+    /** 网络错误 */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** 超时错误 */
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    /** 未授权 */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    /** 权限不足 */
+    readonly FORBIDDEN: "FORBIDDEN";
+    /** 服务器错误 */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+};
+/** 默认分页大小 */
+declare const DEFAULT_PAGE_SIZE = 20;
+/** 默认请求超时时间(毫秒) - 30秒 */
+declare const DEFAULT_REQUEST_TIMEOUT = 30000;
+/** 默认上传超时时间(毫秒) - 5分钟 */
+declare const DEFAULT_UPLOAD_TIMEOUT = 300000;
+/** 默认分片上传大小(字节) - 5MB */
+declare const DEFAULT_CHUNK_SIZE: number;
+
+/**
+ * 通用文件服务工具函数
+ */
+/**
+ * 格式化文件大小
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * 解析文件大小字符串
+ */
+declare function parseFileSize(sizeStr: string): number;
+/**
+ * 获取文件扩展名
+ */
+declare function getFileExtension(fileName: string): string;
+/**
+ * 根据文件名获取MIME类型
+ */
+declare function getMimeTypeFromFileName(fileName: string): string;
+/**
+ * 检查MIME类型是否支持
+ */
+declare function isMimeTypeSupported(mimeType: string, allowedTypes?: string[]): boolean;
+/**
+ * 判断是否为图片类型
+ */
+declare function isImageFile(mimeType: string): boolean;
+/**
+ * 判断是否为视频类型
+ */
+declare function isVideoFile(mimeType: string): boolean;
+/**
+ * 判断是否为音频类型
+ */
+declare function isAudioFile(mimeType: string): boolean;
+/**
+ * 判断是否为文档类型
+ */
+declare function isDocumentFile(mimeType: string): boolean;
+/**
+ * 获取文件类型类别
+ */
+declare function getFileCategory(mimeType: string): 'image' | 'video' | 'audio' | 'document' | 'other';
+/**
+ * 验证文件名是否合法
+ */
+declare function validateFileName(fileName: string): boolean;
+/**
+ * 清理文件名，移除非法字符
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * 生成唯一文件名
+ */
+declare function generateUniqueFileName(originalName: string, fileId: string): string;
+/**
+ * 生成存储路径
+ */
+declare function generateStoragePath(moduleId: string, fileName: string, options?: {
+    businessId?: string;
+    useDate?: boolean;
+    customPrefix?: string;
+}): string;
+/**
+ * 解析存储路径
+ */
+declare function parseStoragePath(path: string): {
+    moduleId?: string;
+    businessId?: string;
+    year?: string;
+    month?: string;
+    day?: string;
+    fileName: string;
+};
+/**
+ * 验证文件大小
+ */
+declare function validateFileSize(file: File, maxSize: number): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 验证文件类型
+ */
+declare function validateFileType(file: File, allowedTypes?: string[]): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * 验证文件
+ */
+declare function validateFile(file: File, options?: {
+    maxSize?: number;
+    allowedTypes?: string[];
+}): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 构建查询字符串
+ */
+declare function buildQueryString(params: Record<string, any>): string;
+/**
+ * 解析URL查询参数
+ */
+declare function parseQueryString(url: string): Record<string, string>;
+/**
+ * 计算上传进度
+ */
+declare function calculateProgress(uploadedBytes: number, totalBytes: number): number;
+/**
+ * 计算上传速度
+ */
+declare function calculateSpeed(uploadedBytes: number, elapsedTime: number): number;
+/**
+ * 计算剩余时间
+ */
+declare function calculateRemainingTime(uploadedBytes: number, totalBytes: number, speed: number): number;
+/**
+ * 创建文件错误对象
+ */
+declare function createFileError(code: string, message: string, details?: Record<string, any>): {
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+    timestamp: Date;
+};
+/**
+ * 格式化错误消息
+ */
+declare function formatErrorMessage(error: unknown): string;
+/**
+ * 读取文件为Base64
+ */
+declare function readFileAsBase64(file: File): Promise<string>;
+/**
+ * 读取文件为ArrayBuffer
+ */
+declare function readFileAsArrayBuffer(file: File): Promise<ArrayBuffer>;
+/**
+ * 读取文件为文本
+ */
+declare function readFileAsText(file: File, encoding?: string): Promise<string>;
+
+export { ALL_SUPPORTED_MIME_TYPES, API_BASE_PATH, API_ENDPOINTS, AUDIO_EXTENSIONS, AUDIO_MIME_TYPES, BatchOperationResult, DEFAULT_CHUNK_SIZE, DEFAULT_MAX_AUDIO_SIZE, DEFAULT_MAX_DOCUMENT_SIZE, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_IMAGE_SIZE, DEFAULT_MAX_VIDEO_SIZE, DEFAULT_PAGE_SIZE, DEFAULT_REQUEST_TIMEOUT, DEFAULT_UPLOAD_TIMEOUT, DOCUMENT_EXTENSIONS, DOCUMENT_MIME_TYPES, ERROR_CODES, FileMetadata, FileQueryOptions, IMAGE_EXTENSIONS, IMAGE_MIME_TYPES, PaginatedResult, UNIVERSAL_FILE_NAME, UNIVERSAL_FILE_VERSION, UniversalFileClient, type UniversalFileClientConfig, UploadFileInfo, UploadProgress, VIDEO_EXTENSIONS, VIDEO_MIME_TYPES, buildQueryString, calculateProgress, calculateRemainingTime, calculateSpeed, createFileClient, createFileError, formatErrorMessage, formatFileSize, generateStoragePath, generateUniqueFileName, getFileCategory, getFileExtension, getMimeTypeFromFileName, isAudioFile, isDocumentFile, isImageFile, isMimeTypeSupported, isVideoFile, parseFileSize, parseQueryString, parseStoragePath, readFileAsArrayBuffer, readFileAsBase64, readFileAsText, sanitizeFileName, universalFileClient, validateFile, validateFileName, validateFileSize, validateFileType };