@withvlibe/storage-sdk 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+/**
+ * Vlibe Storage SDK Types
+ */
+interface VlibeStorageConfig {
+    /** Your Vlibe App ID */
+    appId: string;
+    /** Your Vlibe App Secret */
+    appSecret: string;
+    /** Base URL for the Vlibe API (defaults to production) */
+    baseUrl?: string;
+}
+interface StorageFile {
+    id: string;
+    key: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    isPublic: boolean;
+    folder: string | null;
+    url?: string;
+    createdAt: string;
+}
+interface UploadOptions {
+    /** Folder/category for the file */
+    folder?: string;
+    /** Custom filename (auto-generated if not provided) */
+    filename?: string;
+    /** Make file publicly accessible */
+    isPublic?: boolean;
+    /** Progress callback (0-100) */
+    onProgress?: (progress: number) => void;
+}
+interface UploadResult {
+    id: string;
+    key: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    url: string;
+    isPublic: boolean;
+}
+interface ListOptions {
+    /** Filter by folder */
+    folder?: string;
+    /** Maximum files to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+interface ListResult {
+    files: StorageFile[];
+    total: number;
+    hasMore: boolean;
+}
+interface StorageStats {
+    bytesUsed: number;
+    bytesUsedFormatted: string;
+    fileCount: number;
+    storageLimit: number;
+    storageLimitFormatted: string;
+    usagePercent: number;
+    month: string;
+    monthlyStats: {
+        bytesUploaded: number;
+        bytesUploadedFormatted: string;
+        bytesDeleted: number;
+        bytesDeletedFormatted: string;
+    };
+    ownerType: 'platform_user' | 'creator';
+}
+interface CanUploadResult {
+    allowed: boolean;
+    reason?: string;
+}
+interface PresignedUpload {
+    uploadUrl: string;
+    key: string;
+    expiresIn: number;
+}
+interface Folder {
+    id: string;
+    name: string;
+    parentId: string | null;
+    projectId: string | null;
+    isProjectRoot: boolean;
+    fileCount: number;
+    createdAt: string;
+}
+interface CreateFolderOptions {
+    /** Parent folder ID (null for root level) */
+    parentId?: string;
+    /** Associate folder with a project */
+    projectId?: string;
+    /** Mark as project root folder */
+    isProjectRoot?: boolean;
+}
+interface ListFoldersOptions {
+    /** Filter by parent folder ID (null for root level) */
+    parentId?: string | null;
+    /** Filter by project ID */
+    projectId?: string;
+}
+interface FileReference {
+    id: string;
+    sourceFileId: string;
+    targetProjectId: string;
+    createdAt: string;
+}
+interface FileCopyResult {
+    id: string;
+    key: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    url: string;
+    isPublic: boolean;
+}
+type StorageProviderType = 'r2' | 'wasabi';
+interface StorageConfig {
+    provider: StorageProviderType;
+    publicUrlBase: string;
+}
+
+/**
+ * VlibeStorage - Main SDK class
+ */
+
+declare class VlibeStorage {
+    private appId;
+    private appSecret;
+    private baseUrl;
+    private authToken;
+    private storageConfig;
+    constructor(config: VlibeStorageConfig);
+    /**
+     * Set the user's auth token (required for authenticated requests)
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Clear the auth token
+     */
+    clearAuthToken(): void;
+    /**
+     * Get storage configuration from the server
+     * This fetches the current storage provider and public URL base
+     */
+    getStorageConfig(): Promise<StorageConfig>;
+    /**
+     * Clear cached storage config (call if config might have changed)
+     */
+    clearStorageConfigCache(): void;
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+    /**
+     * Upload a file directly
+     */
+    upload(file: File | Blob, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Get a presigned URL for direct upload to storage
+     * Useful for large files or when you want upload progress
+     */
+    getUploadUrl(filename: string, mimeType: string, size: number, options?: Omit<UploadOptions, 'onProgress'>): Promise<PresignedUpload>;
+    /**
+     * Upload a file using presigned URL (for progress tracking)
+     */
+    uploadWithProgress(file: File, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Get a signed download URL for a file
+     */
+    getDownloadUrl(fileId: string, expiresIn?: number): Promise<string>;
+    /**
+     * Get a public URL for a file (only works for public files in the public path)
+     * Returns the direct URL based on the configured storage provider
+     *
+     * Note: This is a sync method that uses cached config. Call getStorageConfig()
+     * first to ensure the config is loaded, or use getPublicUrlAsync() for a
+     * guaranteed fresh URL.
+     */
+    getPublicUrl(key: string): string;
+    /**
+     * Get a public URL for a file (async version that ensures fresh config)
+     * Returns the direct URL based on the configured storage provider
+     */
+    getPublicUrlAsync(key: string): Promise<string>;
+    /**
+     * Check if a storage key is in the public path
+     */
+    isPublicKey(key: string): boolean;
+    /**
+     * List files
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /**
+     * Get a single file's metadata
+     */
+    get(fileId: string): Promise<StorageFile | null>;
+    /**
+     * Delete a file
+     */
+    delete(fileId: string): Promise<boolean>;
+    /**
+     * Delete multiple files
+     */
+    deleteMany(fileIds: string[]): Promise<{
+        deleted: string[];
+        failed: string[];
+    }>;
+    /**
+     * Get storage usage statistics
+     */
+    getUsage(): Promise<StorageStats>;
+    /**
+     * Check if a file of given size can be uploaded
+     */
+    canUpload(size: number): Promise<CanUploadResult>;
+    /**
+     * List folders
+     */
+    listFolders(options?: ListFoldersOptions): Promise<Folder[]>;
+    /**
+     * Create a folder
+     */
+    createFolder(name: string, options?: CreateFolderOptions): Promise<Folder>;
+    /**
+     * Rename a folder
+     */
+    renameFolder(folderId: string, name: string): Promise<Folder>;
+    /**
+     * Delete a folder (must be empty)
+     */
+    deleteFolder(folderId: string): Promise<boolean>;
+    /**
+     * Copy a file to another project
+     * Creates a new database record pointing to the same S3 object
+     */
+    copyFileToProject(fileId: string, targetProjectId: string): Promise<FileCopyResult>;
+    /**
+     * Create a file reference (link file to another project without copying)
+     * Does not count against storage quota
+     */
+    createFileReference(fileId: string, targetProjectId: string): Promise<FileReference>;
+}
+
+export { type CanUploadResult, type CreateFolderOptions, type FileCopyResult, type FileReference, type Folder, type ListFoldersOptions, type ListOptions, type ListResult, type PresignedUpload, type StorageConfig, type StorageFile, type StorageProviderType, type StorageStats, type UploadOptions, type UploadResult, VlibeStorage, type VlibeStorageConfig };

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Vlibe Storage SDK Types
+ */
+interface VlibeStorageConfig {
+    /** Your Vlibe App ID */
+    appId: string;
+    /** Your Vlibe App Secret */
+    appSecret: string;
+    /** Base URL for the Vlibe API (defaults to production) */
+    baseUrl?: string;
+}
+interface StorageFile {
+    id: string;
+    key: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    isPublic: boolean;
+    folder: string | null;
+    url?: string;
+    createdAt: string;
+}
+interface UploadOptions {
+    /** Folder/category for the file */
+    folder?: string;
+    /** Custom filename (auto-generated if not provided) */
+    filename?: string;
+    /** Make file publicly accessible */
+    isPublic?: boolean;
+    /** Progress callback (0-100) */
+    onProgress?: (progress: number) => void;
+}
+interface UploadResult {
+    id: string;
+    key: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    url: string;
+    isPublic: boolean;
+}
+interface ListOptions {
+    /** Filter by folder */
+    folder?: string;
+    /** Maximum files to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+interface ListResult {
+    files: StorageFile[];
+    total: number;
+    hasMore: boolean;
+}
+interface StorageStats {
+    bytesUsed: number;
+    bytesUsedFormatted: string;
+    fileCount: number;
+    storageLimit: number;
+    storageLimitFormatted: string;
+    usagePercent: number;
+    month: string;
+    monthlyStats: {
+        bytesUploaded: number;
+        bytesUploadedFormatted: string;
+        bytesDeleted: number;
+        bytesDeletedFormatted: string;
+    };
+    ownerType: 'platform_user' | 'creator';
+}
+interface CanUploadResult {
+    allowed: boolean;
+    reason?: string;
+}
+interface PresignedUpload {
+    uploadUrl: string;
+    key: string;
+    expiresIn: number;
+}
+interface Folder {
+    id: string;
+    name: string;
+    parentId: string | null;
+    projectId: string | null;
+    isProjectRoot: boolean;
+    fileCount: number;
+    createdAt: string;
+}
+interface CreateFolderOptions {
+    /** Parent folder ID (null for root level) */
+    parentId?: string;
+    /** Associate folder with a project */
+    projectId?: string;
+    /** Mark as project root folder */
+    isProjectRoot?: boolean;
+}
+interface ListFoldersOptions {
+    /** Filter by parent folder ID (null for root level) */
+    parentId?: string | null;
+    /** Filter by project ID */
+    projectId?: string;
+}
+interface FileReference {
+    id: string;
+    sourceFileId: string;
+    targetProjectId: string;
+    createdAt: string;
+}
+interface FileCopyResult {
+    id: string;
+    key: string;
+    filename: string;
+    size: number;
+    mimeType: string;
+    url: string;
+    isPublic: boolean;
+}
+type StorageProviderType = 'r2' | 'wasabi';
+interface StorageConfig {
+    provider: StorageProviderType;
+    publicUrlBase: string;
+}
+
+/**
+ * VlibeStorage - Main SDK class
+ */
+
+declare class VlibeStorage {
+    private appId;
+    private appSecret;
+    private baseUrl;
+    private authToken;
+    private storageConfig;
+    constructor(config: VlibeStorageConfig);
+    /**
+     * Set the user's auth token (required for authenticated requests)
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Clear the auth token
+     */
+    clearAuthToken(): void;
+    /**
+     * Get storage configuration from the server
+     * This fetches the current storage provider and public URL base
+     */
+    getStorageConfig(): Promise<StorageConfig>;
+    /**
+     * Clear cached storage config (call if config might have changed)
+     */
+    clearStorageConfigCache(): void;
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+    /**
+     * Upload a file directly
+     */
+    upload(file: File | Blob, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Get a presigned URL for direct upload to storage
+     * Useful for large files or when you want upload progress
+     */
+    getUploadUrl(filename: string, mimeType: string, size: number, options?: Omit<UploadOptions, 'onProgress'>): Promise<PresignedUpload>;
+    /**
+     * Upload a file using presigned URL (for progress tracking)
+     */
+    uploadWithProgress(file: File, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Get a signed download URL for a file
+     */
+    getDownloadUrl(fileId: string, expiresIn?: number): Promise<string>;
+    /**
+     * Get a public URL for a file (only works for public files in the public path)
+     * Returns the direct URL based on the configured storage provider
+     *
+     * Note: This is a sync method that uses cached config. Call getStorageConfig()
+     * first to ensure the config is loaded, or use getPublicUrlAsync() for a
+     * guaranteed fresh URL.
+     */
+    getPublicUrl(key: string): string;
+    /**
+     * Get a public URL for a file (async version that ensures fresh config)
+     * Returns the direct URL based on the configured storage provider
+     */
+    getPublicUrlAsync(key: string): Promise<string>;
+    /**
+     * Check if a storage key is in the public path
+     */
+    isPublicKey(key: string): boolean;
+    /**
+     * List files
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /**
+     * Get a single file's metadata
+     */
+    get(fileId: string): Promise<StorageFile | null>;
+    /**
+     * Delete a file
+     */
+    delete(fileId: string): Promise<boolean>;
+    /**
+     * Delete multiple files
+     */
+    deleteMany(fileIds: string[]): Promise<{
+        deleted: string[];
+        failed: string[];
+    }>;
+    /**
+     * Get storage usage statistics
+     */
+    getUsage(): Promise<StorageStats>;
+    /**
+     * Check if a file of given size can be uploaded
+     */
+    canUpload(size: number): Promise<CanUploadResult>;
+    /**
+     * List folders
+     */
+    listFolders(options?: ListFoldersOptions): Promise<Folder[]>;
+    /**
+     * Create a folder
+     */
+    createFolder(name: string, options?: CreateFolderOptions): Promise<Folder>;
+    /**
+     * Rename a folder
+     */
+    renameFolder(folderId: string, name: string): Promise<Folder>;
+    /**
+     * Delete a folder (must be empty)
+     */
+    deleteFolder(folderId: string): Promise<boolean>;
+    /**
+     * Copy a file to another project
+     * Creates a new database record pointing to the same S3 object
+     */
+    copyFileToProject(fileId: string, targetProjectId: string): Promise<FileCopyResult>;
+    /**
+     * Create a file reference (link file to another project without copying)
+     * Does not count against storage quota
+     */
+    createFileReference(fileId: string, targetProjectId: string): Promise<FileReference>;
+}
+
+export { type CanUploadResult, type CreateFolderOptions, type FileCopyResult, type FileReference, type Folder, type ListFoldersOptions, type ListOptions, type ListResult, type PresignedUpload, type StorageConfig, type StorageFile, type StorageProviderType, type StorageStats, type UploadOptions, type UploadResult, VlibeStorage, type VlibeStorageConfig };