@aitlabs/namkwong 0.0.92

package/dist/file-storage/errors/index.d.ts

@@ -0,0 +1,19 @@
+export * from './locales/zh';
+export declare const FileStorageErrorCodes: {
+    readonly FILE_SIZE_EXCEEDED: 'FILE_SIZE_EXCEEDED';
+    readonly FILE_TYPE_NOT_ALLOWED: 'FILE_TYPE_NOT_ALLOWED';
+    readonly FILE_CREATE_FAILED: 'FILE_CREATE_FAILED';
+    readonly FILE_NOT_FOUND: 'FILE_NOT_FOUND';
+    readonly FILE_ALREADY_CONFIRMED: 'FILE_ALREADY_CONFIRMED';
+    readonly FILE_UPLOAD_NOT_COMPLETED: 'FILE_UPLOAD_NOT_COMPLETED';
+    readonly FILE_ACCESS_DENIED: 'FILE_ACCESS_DENIED';
+    readonly FILE_NOT_ACTIVE: 'FILE_NOT_ACTIVE';
+    readonly FILE_DELETE_FAILED: 'FILE_DELETE_FAILED';
+    readonly FILE_UPDATE_FAILED: 'FILE_UPDATE_FAILED';
+};
+type FileStorageErrorCodesType = typeof FileStorageErrorCodes;
+export type FileStorageErrorCode = keyof FileStorageErrorCodesType;
+declare module '../../error/errorcode' {
+    interface ErrorCodeRegistry extends FileStorageErrorCodesType {
+    }
+}

package/dist/file-storage/errors/locales/zh.d.ts

@@ -0,0 +1,18 @@
+export declare const zh: {
+    FILE_SIZE_EXCEEDED: string;
+    FILE_TYPE_NOT_ALLOWED: string;
+    FILE_CREATE_FAILED: string;
+    FILE_NOT_FOUND: string;
+    FILE_ALREADY_CONFIRMED: string;
+    FILE_UPLOAD_NOT_COMPLETED: string;
+    FILE_ACCESS_DENIED: string;
+    FILE_NOT_ACTIVE: string;
+    FILE_DELETE_FAILED: string;
+    FILE_UPDATE_FAILED: string;
+};
+type ZHType = typeof zh;
+declare module '../../../error/messages' {
+    interface ErrorMessageRegistry extends ZHType {
+    }
+}
+export {};

package/dist/file-storage/index.d.ts

@@ -0,0 +1,7 @@
+export * from './admin/service';
+export * from './internal/service';
+export * from './permissions';
+export * from './schema';
+export * from './share/router';
+export * from './user/router';
+export * from './user/service';

package/dist/file-storage/internal/service.d.ts

@@ -0,0 +1,66 @@
+import type { ConfirmUploadInput, GenerateAccessUrlInput, GenerateBatchAccessUrlsInput, GenerateUploadUrlInput } from '../share/dto.schemas';
+export declare abstract class BaseFileStorageService {
+    protected static ensureFileExists<T>(file: T | undefined | null): asserts file is T;
+    protected static ensurePrivateOwnership(file: {
+        accessControl: string | null;
+        ownerId: string;
+    }, userId: string): void;
+}
+export declare abstract class InternalFileStorageService extends BaseFileStorageService {
+    static generateUploadUrl(input: GenerateUploadUrlInput, userId: string): Promise<{
+        readonly fileId: string;
+        readonly uploadUrl: string;
+        readonly method: 'PUT';
+        readonly headers: {
+            readonly 'Content-Type': string;
+        };
+        readonly publicUrl: string | undefined;
+        readonly mimeType: string;
+        readonly expiresIn: number;
+        readonly expiresAt: number;
+    }>;
+    static confirmUpload(input: ConfirmUploadInput, userId: string): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        deletedAt: Date | null;
+        id: string;
+        fileName: string | null;
+        fileSize: number | null;
+        mimeType: string | null;
+        fileExtension: string | null;
+        fileHash: string | null;
+        s3Bucket: string;
+        s3Key: string;
+        s3Region: string;
+        s3ETag: string | null;
+        businessType: "avatar" | "bank_verification" | "contract" | "cover_image" | "export_report" | "financial_report" | "kyc_document" | "ledger_account_import" | "news_attachment" | "notification_attachment" | "other" | "transaction_receipt";
+        businessId: string | null;
+        businessMetadata: string | null;
+        ownerId: string;
+        accessControl: "private" | "public" | "restricted" | null;
+        status: "active" | "archived" | "pending_deletion" | "uploading" | null;
+        publicUrl: string | null;
+        thumbnailUrl: string | null;
+        archivedAt: Date | null;
+        uploadCompletedAt: Date | null;
+        uploadIpAddress: string | null;
+        downloadCount: number | null;
+        lastDownloadedAt: Date | null;
+        isVerified: boolean | null;
+        verifiedBy: string | null;
+        verifiedAt: Date | null;
+        verificationNote: string | null;
+    } | undefined>;
+    static generateAccessUrl(input: GenerateAccessUrlInput, userId: string): Promise<{
+        id: string;
+        url: string;
+        fileName: string | null;
+        expiresAt?: number | undefined;
+    }>;
+    static generateBatchAccessUrls(input: GenerateBatchAccessUrlsInput, userId: string): Promise<{
+        id: string;
+        url: string;
+        fileName: string | null;
+        expiresAt?: number | undefined;
+    }[]>;
+}

package/dist/file-storage/permissions.d.ts

@@ -0,0 +1,5 @@
+export declare const fileStoragePermissions: {
+    readonly 'file_storage:file': readonly ['create', 'read', 'update', 'delete', 'list'];
+    readonly 'file_storage:admin': readonly ['verify', 'list_all', 'permanent_delete'];
+};
+export type FileStoragePermission = keyof typeof fileStoragePermissions;

package/dist/file-storage/s3.client.d.ts

@@ -0,0 +1,284 @@
+import { S3Client, type S3File } from 'bun';
+import type { FileStorageSelectSchemaType } from './db.schemas';
+export declare const privateS3Client: S3Client;
+export declare const publicS3Client: S3Client;
+type AccessControlType = FileStorageSelectSchemaType['accessControl'];
+export declare function getS3ClientCredentialsByAccessControl(accessControl?: AccessControlType): {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    bucket: string;
+    endpoint: string | undefined;
+    sessionToken: string | undefined;
+};
+/**
+ * 根据访问控制类型获取对应的 S3 客户端
+ */
+export declare function getS3ClientByAccessControl(accessControl?: AccessControlType): S3Client;
+/**
+ * 根据访问控制类型获取对应的桶名
+ */
+export declare function getBucketByAccessControl(accessControl?: AccessControlType): string;
+/**
+ *
+ * @param key S3 Key
+ * @param accessControl 访问控制类型
+ * @returns s3ProtocolPath s3://{bucket}/{businessType}/{YYYY}/{MM}/{DD}/{fileId}.{ext}
+ */
+export declare function getS3ProtocolPath(key: string, accessControl?: AccessControlType): string;
+export declare function getS3File(key: string, accessControl?: AccessControlType): S3File;
+export declare function getS3File(path: string, accessControl?: AccessControlType): S3File;
+export declare function getFileExtension(fileName: string): string;
+/**
+ * 获取文件的 MIME 类型
+ */
+export declare function getFileMimeType(fileName: string): string;
+/**
+ * S3 文件路径生成策略
+ * 按业务类型和日期分目录，避免单目录文件过多
+ * S3 对象键（Bun SDK 中称为 path）
+ * @returns 格式：{businessType}/{YYYY}/{MM}/{DD}/{fileId}.{ext}
+ */
+export declare function generateS3Key(businessType: string, fileId: string, fileName: string): string;
+/**
+ * 检查文件是否存在
+ * Bun 的 file.exists() 方法
+ */
+export declare function checkFileExists(key: string, accessControl?: AccessControlType): Promise<boolean>;
+/**
+ * 获取文件元数据
+ * 使用 Bun 的 file 对象属性
+ */
+export declare function getFileMetadata(key: string, accessControl?: AccessControlType): Promise<{
+    size: number;
+    contentType: string;
+}>;
+/**
+ * 删除文件
+ * 使用 Bun 的 file.delete() 方法
+ */
+export declare function deleteFile(key: string, accessControl?: AccessControlType): Promise<void>;
+/**
+ * 批量删除文件
+ */
+export declare function deleteFiles(keys: string[]): Promise<void>;
+/**
+ * 上传文件
+ * 使用 Bun 的 write 方法
+ */
+export declare function uploadFile(key: string, data: string | Buffer | Blob): Promise<void>;
+/**
+ * 下载文件为文本
+ */
+export declare function downloadFileAsText(key: string): Promise<string>;
+/**
+ * 下载文件为 JSON
+ */
+export declare function downloadFileAsJson<T = unknown>(key: string): Promise<T>;
+/**
+ * 下载文件为 ArrayBuffer
+ */
+export declare function downloadFileAsArrayBuffer(key: string): Promise<ArrayBuffer>;
+/**
+ * 生成公开访问 URL
+ * 注意：仅用于 public 文件，会使用公开桶
+ */
+export declare function getPublicUrl(key: string): string;
+/**
+ * 验证文件大小
+ */
+export declare function validateFileSize(size: number, maxSize: number): boolean;
+/**
+ * 根据业务类型和 MIME 类型验证文件大小
+ * 优先使用 mimeTypeLimits 中的特殊限制，否则使用 maxSize
+ */
+export declare function validateFileSizeByMimeType(size: number, businessType: BusinessType, mimeType: string): boolean;
+/**
+ * 获取业务类型和 MIME 类型对应的大小限制
+ */
+export declare function getMaxSizeForMimeType(businessType: BusinessType, mimeType: string): number;
+/**
+ * 验证 MIME 类型
+ */
+export declare function validateMimeType(mimeType: string, allowedTypes: readonly string[]): boolean;
+/**
+ * 业务类型配置
+ * 统一管理每个业务类型的大小限制和允许的 MIME 类型
+ *
+ * defaultAccessControl: 默认访问控制级别
+ * maxSize: 默认文件大小限制
+ * allowedMimeTypes: 允许的 MIME 类型列表
+ * mimeTypeLimits: 针对特定 MIME 类型的大小限制（可选，优先级高于 maxSize）
+ */
+export declare const BUSINESS_TYPE_CONFIG: {
+    readonly kyc_document: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png", "image/jpg"];
+        readonly mimeTypeLimits: {
+            readonly 'image/jpeg': number;
+            readonly 'image/png': number;
+            readonly 'image/jpg': number;
+        };
+        readonly description: 'KYC \u6587\u6863\uFF08\u8EAB\u4EFD\u8BC1\u660E\u3001\u5730\u5740\u8BC1\u660E\u7B49\uFF09';
+    };
+    readonly contract: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf"];
+        readonly description: '\u5408\u540C\u6587\u4EF6';
+    };
+    readonly financial_report: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"];
+        readonly description: '\u8D22\u52A1\u62A5\u8868';
+    };
+    readonly ledger_account_import: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"];
+        readonly description: '\u7528\u6237\u8D26\u6237\u5BFC\u5165\u6587\u4EF6';
+    };
+    readonly avatar: {
+        readonly defaultAccessControl: 'public';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["image/jpeg", "image/png", "image/jpg", "image/webp"];
+        readonly mimeTypeLimits: {
+            readonly 'image/webp': number;
+        };
+        readonly description: '\u7528\u6237\u5934\u50CF';
+    };
+    readonly cover_image: {
+        readonly defaultAccessControl: 'public';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["image/jpeg", "image/png", "image/jpg", "image/webp"];
+        readonly description: '\u5C01\u9762\u56FE\u7247';
+    };
+    readonly notification_attachment: {
+        readonly defaultAccessControl: 'restricted';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/*", "application/zip"];
+        readonly description: '\u901A\u77E5\u9644\u4EF6';
+    };
+    readonly transaction_receipt: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png"];
+        readonly description: '\u4EA4\u6613\u56DE\u6267';
+    };
+    readonly export_report: {
+        readonly defaultAccessControl: 'restricted';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "text/csv"];
+        readonly description: '\u5BFC\u51FA\u7684\u62A5\u8868';
+    };
+    readonly bank_verification: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png"];
+        readonly description: '\u94F6\u884C\u9A8C\u8BC1\u6587\u4EF6';
+    };
+    readonly news_attachment: {
+        readonly defaultAccessControl: 'public';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png"];
+        readonly description: '\u65B0\u95FB\u9644\u4EF6';
+    };
+    readonly other: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["*/*"];
+        readonly description: '\u5176\u4ED6';
+    };
+};
+/**
+ * 业务类型
+ */
+export type BusinessType = keyof typeof BUSINESS_TYPE_CONFIG;
+/**
+ * 获取业务类型配置
+ */
+export declare function getBusinessTypeConfig<T extends BusinessType>(businessType: T): {
+    readonly kyc_document: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png", "image/jpg"];
+        readonly mimeTypeLimits: {
+            readonly 'image/jpeg': number;
+            readonly 'image/png': number;
+            readonly 'image/jpg': number;
+        };
+        readonly description: 'KYC \u6587\u6863\uFF08\u8EAB\u4EFD\u8BC1\u660E\u3001\u5730\u5740\u8BC1\u660E\u7B49\uFF09';
+    };
+    readonly contract: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf"];
+        readonly description: '\u5408\u540C\u6587\u4EF6';
+    };
+    readonly financial_report: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"];
+        readonly description: '\u8D22\u52A1\u62A5\u8868';
+    };
+    readonly ledger_account_import: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"];
+        readonly description: '\u7528\u6237\u8D26\u6237\u5BFC\u5165\u6587\u4EF6';
+    };
+    readonly avatar: {
+        readonly defaultAccessControl: 'public';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["image/jpeg", "image/png", "image/jpg", "image/webp"];
+        readonly mimeTypeLimits: {
+            readonly 'image/webp': number;
+        };
+        readonly description: '\u7528\u6237\u5934\u50CF';
+    };
+    readonly cover_image: {
+        readonly defaultAccessControl: 'public';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["image/jpeg", "image/png", "image/jpg", "image/webp"];
+        readonly description: '\u5C01\u9762\u56FE\u7247';
+    };
+    readonly notification_attachment: {
+        readonly defaultAccessControl: 'restricted';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/*", "application/zip"];
+        readonly description: '\u901A\u77E5\u9644\u4EF6';
+    };
+    readonly transaction_receipt: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png"];
+        readonly description: '\u4EA4\u6613\u56DE\u6267';
+    };
+    readonly export_report: {
+        readonly defaultAccessControl: 'restricted';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "text/csv"];
+        readonly description: '\u5BFC\u51FA\u7684\u62A5\u8868';
+    };
+    readonly bank_verification: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png"];
+        readonly description: '\u94F6\u884C\u9A8C\u8BC1\u6587\u4EF6';
+    };
+    readonly news_attachment: {
+        readonly defaultAccessControl: 'public';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["application/pdf", "image/jpeg", "image/png"];
+        readonly description: '\u65B0\u95FB\u9644\u4EF6';
+    };
+    readonly other: {
+        readonly defaultAccessControl: 'private';
+        readonly maxSize: number;
+        readonly allowedMimeTypes: readonly ["*/*"];
+        readonly description: '\u5176\u4ED6';
+    };
+}[T];
+export {};