@centrali-io/centrali-sdk 4.4.7 → 4.4.8

package/dist/index.js

@@ -3371,7 +3371,7 @@ class CentraliSDK {
      *
      * @param file - The file to upload
      * @param location - Target folder path (e.g., '/root/shared/images'). Defaults to '/root/shared' if not specified.
-     *                   Must be an absolute path starting with '/root/'. The folder must exist before uploading.
+     *                   /root/shared always exists. For custom subfolders, create them first with createFolder().
      * @param isPublic - If true, the file will be publicly accessible without authentication. Defaults to false.
      * @returns The file URL or render ID
      *
@@ -3406,6 +3406,93 @@ class CentraliSDK {
             });
         });
     }
+    // ------------------ Folder API Methods ------------------
+    /**
+     * Create a folder in the storage service.
+     * Use this to create subfolders under /root/shared (which always exists).
+     *
+     * @param name - The folder name (e.g., 'logos', 'avatars')
+     * @param location - Parent folder path (e.g., '/root/shared'). Defaults to '/root/shared'.
+     * @returns The created folder object
+     *
+     * @example
+     * ```ts
+     * // Create a folder under /root/shared
+     * const folder = await client.createFolder('logos', '/root/shared');
+     * // Result: folder at /root/shared/logos
+     *
+     * // Then upload to it
+     * const { data: renderId } = await client.uploadFile(file, '/root/shared/logos', true);
+     * ```
+     */
+    createFolder(name_1) {
+        return __awaiter(this, arguments, void 0, function* (name, location = '/root/shared') {
+            const path = `storage/ws/${this.options.workspaceId}/api/v1/folders`;
+            return this.request('POST', path, { name, location });
+        });
+    }
+    /**
+     * List folders in the workspace, optionally filtered by parent location.
+     *
+     * @param location - Parent folder path to list contents of (e.g., '/root/shared'). If omitted, lists top-level folders.
+     * @returns Array of folder objects
+     *
+     * @example
+     * ```ts
+     * // List all folders under /root/shared
+     * const folders = await client.listFolders('/root/shared');
+     *
+     * // Check if a folder exists before uploading
+     * const folders = await client.listFolders('/root/shared');
+     * const hasLogos = folders.data.some(f => f.name === 'logos');
+     * if (!hasLogos) {
+     *     await client.createFolder('logos', '/root/shared');
+     * }
+     * ```
+     */
+    listFolders(location) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const path = `storage/ws/${this.options.workspaceId}/api/v1/folders`;
+            const params = location ? { location } : undefined;
+            return this.request('GET', path, null, params);
+        });
+    }
+    /**
+     * Get a specific folder by ID.
+     *
+     * @param folderId - The folder ID (UUID)
+     * @returns The folder object
+     */
+    getFolder(folderId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}`;
+            return this.request('GET', path);
+        });
+    }
+    /**
+     * List sub-folders within a specific folder.
+     *
+     * @param folderId - The parent folder ID (UUID)
+     * @returns Array of sub-folder objects
+     */
+    listSubFolders(folderId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}/sub-folders`;
+            return this.request('GET', path);
+        });
+    }
+    /**
+     * Delete a folder by ID. System folders (/root, /root/shared, /root/users) cannot be deleted.
+     *
+     * @param folderId - The folder ID (UUID) to delete
+     */
+    deleteFolder(folderId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}`;
+            return this.request('DELETE', path);
+        });
+    }
+    // ------------------ File Render/Download URL Methods ------------------
     /**
      * Get the render URL for a file. Use this URL to display files inline (e.g., images in img tags).
      * Supports optional image transformation parameters.

package/index.ts

@@ -5886,7 +5886,7 @@ export class CentraliSDK {
      *
      * @param file - The file to upload
      * @param location - Target folder path (e.g., '/root/shared/images'). Defaults to '/root/shared' if not specified.
-     *                   Must be an absolute path starting with '/root/'. The folder must exist before uploading.
+     *                   /root/shared always exists. For custom subfolders, create them first with createFolder().
      * @param isPublic - If true, the file will be publicly accessible without authentication. Defaults to false.
      * @returns The file URL or render ID
      *
@@ -5927,6 +5927,93 @@ export class CentraliSDK {
         });
     }
 
+    // ------------------ Folder API Methods ------------------
+
+    /**
+     * Create a folder in the storage service.
+     * Use this to create subfolders under /root/shared (which always exists).
+     *
+     * @param name - The folder name (e.g., 'logos', 'avatars')
+     * @param location - Parent folder path (e.g., '/root/shared'). Defaults to '/root/shared'.
+     * @returns The created folder object
+     *
+     * @example
+     * ```ts
+     * // Create a folder under /root/shared
+     * const folder = await client.createFolder('logos', '/root/shared');
+     * // Result: folder at /root/shared/logos
+     *
+     * // Then upload to it
+     * const { data: renderId } = await client.uploadFile(file, '/root/shared/logos', true);
+     * ```
+     */
+    public async createFolder(
+        name: string,
+        location: string = '/root/shared'
+    ): Promise<ApiResponse<any>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders`;
+        return this.request<any>('POST', path, { name, location });
+    }
+
+    /**
+     * List folders in the workspace, optionally filtered by parent location.
+     *
+     * @param location - Parent folder path to list contents of (e.g., '/root/shared'). If omitted, lists top-level folders.
+     * @returns Array of folder objects
+     *
+     * @example
+     * ```ts
+     * // List all folders under /root/shared
+     * const folders = await client.listFolders('/root/shared');
+     *
+     * // Check if a folder exists before uploading
+     * const folders = await client.listFolders('/root/shared');
+     * const hasLogos = folders.data.some(f => f.name === 'logos');
+     * if (!hasLogos) {
+     *     await client.createFolder('logos', '/root/shared');
+     * }
+     * ```
+     */
+    public async listFolders(location?: string): Promise<ApiResponse<any[]>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders`;
+        const params = location ? { location } : undefined;
+        return this.request<any[]>('GET', path, null, params);
+    }
+
+    /**
+     * Get a specific folder by ID.
+     *
+     * @param folderId - The folder ID (UUID)
+     * @returns The folder object
+     */
+    public async getFolder(folderId: string): Promise<ApiResponse<any>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}`;
+        return this.request<any>('GET', path);
+    }
+
+    /**
+     * List sub-folders within a specific folder.
+     *
+     * @param folderId - The parent folder ID (UUID)
+     * @returns Array of sub-folder objects
+     */
+    public async listSubFolders(folderId: string): Promise<ApiResponse<any[]>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}/sub-folders`;
+        return this.request<any[]>('GET', path);
+    }
+
+    /**
+     * Delete a folder by ID. System folders (/root, /root/shared, /root/users) cannot be deleted.
+     *
+     * @param folderId - The folder ID (UUID) to delete
+     */
+    public async deleteFolder(folderId: string): Promise<ApiResponse<void>> {
+        const path = `storage/ws/${this.options.workspaceId}/api/v1/folders/${folderId}`;
+        return this.request<void>('DELETE', path);
+    }
+
+    // ------------------ File Render/Download URL Methods ------------------
+
     /**
      * Get the render URL for a file. Use this URL to display files inline (e.g., images in img tags).
      * Supports optional image transformation parameters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "4.4.7",
+  "version": "4.4.8",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",