@centrali-io/centrali-sdk 2.9.2 → 2.9.3

package/README.md

@@ -329,14 +329,26 @@ console.log('Job queued:', job.data);
 ### File Uploads
 
 ```typescript
-// Upload a file
-const uploadResult = await centrali.uploadFile(
-  file,
-  'folder-name',
-  true  // make publicly accessible
-);
+// Upload a file (defaults to /root/shared)
+const result = await centrali.uploadFile(file);
+const renderId = result.data;  // e.g., "kvHJ4ipZ3Q6EAoguKrWmU7KYyDHcU03C"
+
+// Upload to a specific folder (must exist, use full path)
+const result = await centrali.uploadFile(file, '/root/shared/images');
+
+// Upload as public file
+const result = await centrali.uploadFile(file, '/root/shared/public', true);
 
-console.log('File URL:', uploadResult.data);
+// Get URLs for the uploaded file
+const renderUrl = centrali.getFileRenderUrl(renderId);  // For inline display
+const downloadUrl = centrali.getFileDownloadUrl(renderId);  // For download
+
+// Get URL with image transformations
+const thumbnailUrl = centrali.getFileRenderUrl(renderId, {
+  width: 200,
+  quality: 80,
+  format: 'webp'
+});
 ```
 
 ### Data Validation

package/dist/index.js

@@ -1879,16 +1879,39 @@ class CentraliSDK {
         return this.request('POST', path, { field, value });
     }
     // ------------------ Storage API Methods ------------------
-    /** Upload a file to the storage service. */
+    /**
+     * Upload a file to the storage service.
+     *
+     * @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.
+     * @param isPublic - If true, the file will be publicly accessible without authentication. Defaults to false.
+     * @returns The file URL or render ID
+     *
+     * @example
+     * ```ts
+     * // Upload to default location (/root/shared)
+     * const result = await client.uploadFile(file);
+     *
+     * // Upload to specific folder
+     * const result = await client.uploadFile(file, '/root/shared/images');
+     *
+     * // Upload as public file
+     * const result = await client.uploadFile(file, '/root/shared/public', true);
+     * ```
+     */
     uploadFile(file_1, location_1) {
         return __awaiter(this, arguments, void 0, function* (file, location, isPublic = false) {
             const path = getFileUploadApiPath(this.options.workspaceId);
             const formData = new FormData();
             const fileName = this.options.workspaceId + Date.now() + file.name;
             formData.append('file', file);
-            formData.append('location', location);
             formData.append('fileName', fileName);
             formData.append('isPublic', isPublic ? 'true' : 'false');
+            // Only append location if specified; backend defaults to /root/shared
+            if (location) {
+                formData.append('location', location);
+            }
             return this.request('POST', path, formData, undefined, {
                 headers: {
                     'Content-Type': 'multipart/form-data',
@@ -1896,6 +1919,57 @@ class CentraliSDK {
             });
         });
     }
+    /**
+     * 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.
+     *
+     * @param renderId - The render ID returned from uploadFile()
+     * @param options - Optional image transformation parameters
+     * @returns The full render URL
+     *
+     * @example
+     * ```ts
+     * // Basic render URL
+     * const url = client.getFileRenderUrl('abc123');
+     * // => "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123"
+     *
+     * // With image transformations
+     * const thumbUrl = client.getFileRenderUrl('abc123', { width: 200 });
+     * const compressedUrl = client.getFileRenderUrl('abc123', { width: 800, quality: 60, format: 'webp' });
+     * ```
+     */
+    getFileRenderUrl(renderId, options) {
+        const baseUrl = `${this.options.baseUrl}/storage/ws/${this.options.workspaceId}/api/v1/render/${renderId}`;
+        if (!options) {
+            return baseUrl;
+        }
+        const params = new URLSearchParams();
+        if (options.width)
+            params.append('width', String(options.width));
+        if (options.height)
+            params.append('height', String(options.height));
+        if (options.quality)
+            params.append('quality', String(options.quality));
+        if (options.format)
+            params.append('format', options.format);
+        const queryString = params.toString();
+        return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+    }
+    /**
+     * Get the download URL for a file. Use this URL to download files as attachments.
+     *
+     * @param renderId - The render ID returned from uploadFile()
+     * @returns The full download URL
+     *
+     * @example
+     * ```ts
+     * const downloadUrl = client.getFileDownloadUrl('abc123');
+     * // => "https://api.centrali.io/storage/ws/my-workspace/api/v1/download/abc123"
+     * ```
+     */
+    getFileDownloadUrl(renderId) {
+        return `${this.options.baseUrl}/storage/ws/${this.options.workspaceId}/api/v1/download/${renderId}`;
+    }
     // ------------------ Search API Methods ------------------
     /**
      * Search records across the workspace using full-text search.

package/index.ts

@@ -3548,10 +3548,30 @@ export class CentraliSDK {
 
     // ------------------ Storage API Methods ------------------
 
-    /** Upload a file to the storage service. */
+    /**
+     * Upload a file to the storage service.
+     *
+     * @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.
+     * @param isPublic - If true, the file will be publicly accessible without authentication. Defaults to false.
+     * @returns The file URL or render ID
+     *
+     * @example
+     * ```ts
+     * // Upload to default location (/root/shared)
+     * const result = await client.uploadFile(file);
+     *
+     * // Upload to specific folder
+     * const result = await client.uploadFile(file, '/root/shared/images');
+     *
+     * // Upload as public file
+     * const result = await client.uploadFile(file, '/root/shared/public', true);
+     * ```
+     */
     public async uploadFile(
         file: File,
-        location: string,
+        location?: string,
         isPublic: boolean = false
     ): Promise<ApiResponse<string>> {
         const path = getFileUploadApiPath(this.options.workspaceId);
@@ -3559,10 +3579,14 @@ export class CentraliSDK {
         const fileName = this.options.workspaceId + Date.now() + file.name;
 
         formData.append('file', file);
-        formData.append('location', location);
         formData.append('fileName', fileName);
         formData.append('isPublic', isPublic ? 'true' : 'false');
 
+        // Only append location if specified; backend defaults to /root/shared
+        if (location) {
+            formData.append('location', location);
+        }
+
         return this.request<string>('POST', path, formData, undefined, {
             headers: {
                 'Content-Type': 'multipart/form-data',
@@ -3570,6 +3594,66 @@ export class CentraliSDK {
         });
     }
 
+    /**
+     * 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.
+     *
+     * @param renderId - The render ID returned from uploadFile()
+     * @param options - Optional image transformation parameters
+     * @returns The full render URL
+     *
+     * @example
+     * ```ts
+     * // Basic render URL
+     * const url = client.getFileRenderUrl('abc123');
+     * // => "https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123"
+     *
+     * // With image transformations
+     * const thumbUrl = client.getFileRenderUrl('abc123', { width: 200 });
+     * const compressedUrl = client.getFileRenderUrl('abc123', { width: 800, quality: 60, format: 'webp' });
+     * ```
+     */
+    public getFileRenderUrl(
+        renderId: string,
+        options?: {
+            width?: number;
+            height?: number;
+            quality?: number;
+            format?: 'jpeg' | 'png' | 'webp';
+        }
+    ): string {
+        const baseUrl = `${this.options.baseUrl}/storage/ws/${this.options.workspaceId}/api/v1/render/${renderId}`;
+
+        if (!options) {
+            return baseUrl;
+        }
+
+        const params = new URLSearchParams();
+        if (options.width) params.append('width', String(options.width));
+        if (options.height) params.append('height', String(options.height));
+        if (options.quality) params.append('quality', String(options.quality));
+        if (options.format) params.append('format', options.format);
+
+        const queryString = params.toString();
+        return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+    }
+
+    /**
+     * Get the download URL for a file. Use this URL to download files as attachments.
+     *
+     * @param renderId - The render ID returned from uploadFile()
+     * @returns The full download URL
+     *
+     * @example
+     * ```ts
+     * const downloadUrl = client.getFileDownloadUrl('abc123');
+     * // => "https://api.centrali.io/storage/ws/my-workspace/api/v1/download/abc123"
+     * ```
+     */
+    public getFileDownloadUrl(renderId: string): string {
+        return `${this.options.baseUrl}/storage/ws/${this.options.workspaceId}/api/v1/download/${renderId}`;
+    }
+
     // ------------------ Search API Methods ------------------
 
     /**

package/package.json

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