cynx-lib 1.3.34 → 1.3.36

package/utils/utils/storage.js

@@ -1,393 +1,393 @@
-/**
- * cynx/utils — Storage Server Client & Connector (storage.js)
- *
- * Universal client SDK to interact with cynx-storage-server:
- *  - Upload files (Browser File/Blob or Node.js Buffer/Stream/Blob)
- *  - Query file metadata & entity attachments
- *  - Delete files or whole entity file groups
- *  - Generate public CDN URLs and stream content
- *
- * Works in Browser, Node.js (18+), Next.js / SSR, and Web Workers.
- * Zero external dependencies.
- */
-
-// ─── UTILITIES & HELPERS ────────────────────────────────────────────────────────
-
-const isNode = typeof process !== 'undefined' && Boolean(process.versions?.node);
-
-function getDefaultBaseUrl() {
-  if (isNode && process.env?.STORAGE_SERVER_URL) {
-    return process.env.STORAGE_SERVER_URL;
-  }
-  if (typeof window !== 'undefined' && window.location?.origin) {
-    return window.location.origin;
-  }
-  return '';
-}
-
-function getDefaultApiKey() {
-  if (isNode && (process.env?.STORAGE_SERVER_API_KEY || process.env?.STORAGE_API_KEY)) {
-    return process.env.STORAGE_SERVER_API_KEY || process.env.STORAGE_API_KEY;
-  }
-  return '';
-}
-
-/**
- * Format raw byte numbers into human-readable strings.
- * @param {number|string} bytes 
- * @returns {string} e.g. "12.5 MB"
- */
-export function formatBytes(bytes) {
-  const num = Number(bytes) || 0;
-  if (num === 0) return '0 B';
-  const k = 1024;
-  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
-  const i = Math.floor(Math.log(num) / Math.log(k));
-  const val = (num / Math.pow(k, i)).toFixed(2);
-  return `${val} ${sizes[i]}`;
-}
-
-/**
- * Categorize mimeType and filename into categories.
- * @param {string} [mimeType=''] 
- * @param {string} [filename=''] 
- * @returns {'image'|'pdf'|'video'|'audio'|'document'|'archive'|'other'}
- */
-export function getFileTypeCategory(mimeType = '', filename = '') {
-  const mt = (mimeType || '').toLowerCase();
-  const fn = (filename || '').toLowerCase();
-
-  if (mt.startsWith('image/') || /\.(jpg|jpeg|png|gif|webp|bmp|svg|avif|ico)$/i.test(fn)) {
-    return 'image';
-  }
-  if (mt === 'application/pdf' || /\.pdf$/i.test(fn)) {
-    return 'pdf';
-  }
-  if (mt.startsWith('video/') || /\.(mp4|webm|mkv|mov|avi|flv|wmv|m4v)$/i.test(fn)) {
-    return 'video';
-  }
-  if (mt.startsWith('audio/') || /\.(mp3|wav|ogg|m4a|aac|flac)$/i.test(fn)) {
-    return 'audio';
-  }
-  if (
-    mt.includes('word') ||
-    mt.includes('excel') ||
-    mt.includes('spreadsheet') ||
-    mt.includes('presentation') ||
-    mt.includes('csv') ||
-    /\.(doc|docx|xls|xlsx|csv|ppt|pptx|txt|rtf|md)$/i.test(fn)
-  ) {
-    return 'document';
-  }
-  if (mt.includes('zip') || mt.includes('tar') || mt.includes('compressed') || /\.(zip|tar|gz|7z|rar)$/i.test(fn)) {
-    return 'archive';
-  }
-  return 'other';
-}
-
-/**
- * Build a public CDN URL for a given file ID.
- * @param {string} fileId e.g. "sf_abc123"
- * @param {string} [filename] Optional filename suffix for cleaner download names
- * @param {string} [baseUrl] Storage server base URL
- * @returns {string} CDN URL
- */
-export function getCdnUrl(fileId, filename = '', baseUrl = '') {
-  if (!fileId) return '';
-  const base = (baseUrl || getDefaultBaseUrl() || '').replace(/\/+$/, '');
-  const cleanId = String(fileId).trim();
-  const suffix = filename ? `/${encodeURIComponent(filename)}` : '';
-  return `${base}/cdn/${encodeURIComponent(cleanId)}${suffix}`;
-}
-
-// ─── STORAGE CLIENT CLASS ───────────────────────────────────────────────────────
-
-export class StorageClient {
-  /**
-   * @param {object} [options={}]
-   * @param {string} [options.baseUrl] Base URL of the storage server (e.g. "https://storage.domain.com" or "http://localhost:5000")
-   * @param {string} [options.apiKey] API Key with upload/read/delete permissions
-   * @param {number} [options.timeout=30000] Request timeout in milliseconds
-   * @param {Function} [options.fetch] Custom fetch implementation (optional)
-   */
-  constructor(options = {}) {
-    this.baseUrl = (options.baseUrl || getDefaultBaseUrl() || '').replace(/\/+$/, '');
-    this.apiKey = options.apiKey || getDefaultApiKey() || '';
-    this.timeout = options.timeout || 30000;
-    this.fetchFn = options.fetch || (typeof globalThis !== 'undefined' ? globalThis.fetch?.bind(globalThis) : null);
-  }
-
-  /**
-   * Update configuration options.
-   * @param {object} options 
-   */
-  configure(options = {}) {
-    if (options.baseUrl !== undefined) this.baseUrl = String(options.baseUrl || '').replace(/\/+$/, '');
-    if (options.apiKey !== undefined) this.apiKey = String(options.apiKey || '');
-    if (options.timeout !== undefined) this.timeout = Number(options.timeout) || 30000;
-    if (options.fetch !== undefined) this.fetchFn = options.fetch;
-    return this;
-  }
-
-  /**
-   * Internal HTTP request helper.
-   * @private
-   */
-  async _request(path, { method = 'GET', headers = {}, body, apiKey, signal, timeout } = {}) {
-    if (!this.fetchFn) {
-      throw new Error('[cynx/storage] No fetch implementation available in current environment.');
-    }
-
-    const url = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-    const key = apiKey !== undefined ? apiKey : this.apiKey;
-    const reqHeaders = { ...headers };
-
-    if (key) {
-      reqHeaders['x-api-key'] = key;
-    }
-
-    const abortCtrl = typeof AbortController !== 'undefined' ? new AbortController() : null;
-    const reqTimeout = timeout || this.timeout;
-    let timer = null;
-
-    if (abortCtrl && reqTimeout > 0) {
-      timer = setTimeout(() => abortCtrl.abort(new Error(`Storage request timeout after ${reqTimeout}ms`)), reqTimeout);
-    }
-
-    const activeSignal = signal || abortCtrl?.signal;
-
-    try {
-      const response = await this.fetchFn(url, {
-        method,
-        headers: reqHeaders,
-        body,
-        signal: activeSignal,
-      });
-
-      if (timer) clearTimeout(timer);
-
-      if (!response.ok) {
-        let errData = null;
-        try {
-          errData = await response.json();
-        } catch {
-          errData = { error: response.statusText || `HTTP ${response.status}` };
-        }
-        const error = new Error(errData.error || errData.message || `Storage Error: ${response.status}`);
-        error.status = response.status;
-        error.response = errData;
-        throw error;
-      }
-
-      return await response.json();
-    } catch (err) {
-      if (timer) clearTimeout(timer);
-      throw err;
-    }
-  }
-
-  /**
-   * Upload one or multiple files to the storage server.
-   * 
-   * @param {object} params
-   * @param {File|Blob|Buffer|ArrayBuffer|Array<File|Blob|Buffer|object>} [params.files] File or array of files to upload
-   * @param {File|Blob|Buffer|ArrayBuffer} [params.file] Single file alias
-   * @param {string} [params.folder] Target subfolder in cloud storage
-   * @param {string} [params.entityType] Associated entity type (e.g. 'company', 'employee', 'inspection')
-   * @param {string|number} [params.entityId] Associated entity ID
-   * @param {string} [params.apiKey] Override API Key for this upload
-   * @param {AbortSignal} [params.signal] AbortSignal for cancellation
-   * @returns {Promise<{ files: Array<object>, file: object|null }>} Formatted upload result
-   */
-  async upload({
-    files,
-    file,
-    folder,
-    entityType,
-    entityId,
-    entity_type,
-    entity_id,
-    apiKey,
-    signal,
-  } = {}) {
-    if (typeof FormData === 'undefined') {
-      throw new Error('[cynx/storage] FormData is not available in the current environment.');
-    }
-
-    const formData = new FormData();
-    const rawFiles = files ? (Array.isArray(files) ? files : [files]) : file ? [file] : [];
-
-    if (rawFiles.length === 0) {
-      throw new Error('[cynx/storage] No file provided for upload.');
-    }
-
-    for (let i = 0; i < rawFiles.length; i++) {
-      const item = rawFiles[i];
-      if (!item) continue;
-
-      if (typeof File !== 'undefined' && item instanceof File) {
-        formData.append('files', item, item.name);
-      } else if (typeof Blob !== 'undefined' && item instanceof Blob) {
-        const name = item.name || `file_${Date.now()}_${i}`;
-        formData.append('files', item, name);
-      } else if (isNode && (Buffer.isBuffer(item) || item instanceof Uint8Array || item instanceof ArrayBuffer)) {
-        const name = item.name || item.filename || `file_${Date.now()}_${i}`;
-        const blob = new Blob([item], { type: item.type || item.mimeType || 'application/octet-stream' });
-        formData.append('files', blob, name);
-      } else if (item && typeof item === 'object' && item.data) {
-        // Wrapped object format: { data, name, type }
-        const name = item.name || item.filename || `file_${Date.now()}_${i}`;
-        const blob = item.data instanceof Blob ? item.data : new Blob([item.data], { type: item.type || item.mimeType || 'application/octet-stream' });
-        formData.append('files', blob, name);
-      } else {
-        formData.append('files', item);
-      }
-    }
-
-    if (folder) formData.append('folder', folder);
-    const resolvedEntityType = entityType || entity_type;
-    const resolvedEntityId = entityId || entity_id;
-
-    if (resolvedEntityType) formData.append('entityType', resolvedEntityType);
-    if (resolvedEntityId) formData.append('entityId', String(resolvedEntityId));
-
-    const res = await this._request('/api/v1/upload', {
-      method: 'POST',
-      body: formData,
-      apiKey,
-      signal,
-    });
-
-    const fileList = res?.files ? res.files : Array.isArray(res) ? res : res ? [res] : [];
-    return {
-      files: fileList,
-      file: fileList[0] || null,
-      ...res,
-    };
-  }
-
-  /**
-   * Get metadata and CDN URLs for a specific file by its ID.
-   * 
-   * @param {string} fileId ID of the file (e.g. "sf_abc123")
-   * @param {object} [options]
-   * @param {string} [options.apiKey] Override API Key
-   * @param {AbortSignal} [options.signal] AbortSignal
-   * @returns {Promise<object>} File metadata record
-   */
-  async getFile(fileId, options = {}) {
-    if (!fileId) throw new Error('[cynx/storage] fileId is required.');
-    const cleanId = String(fileId).trim().replace(/\.[^/.]+$/, ''); // strip any extension if present
-    return this._request(`/api/v1/files/${encodeURIComponent(cleanId)}`, {
-      method: 'GET',
-      ...options,
-    });
-  }
-
-  /**
-   * Get all files attached to a specific entity.
-   * 
-   * @param {string} entityType Entity type (e.g. "company", "employee")
-   * @param {string|number} entityId Entity identifier
-   * @param {object} [options]
-   * @param {string} [options.apiKey] Override API Key
-   * @param {AbortSignal} [options.signal] AbortSignal
-   * @returns {Promise<Array<object>>} List of file metadata records
-   */
-  async getEntityFiles(entityType, entityId, options = {}) {
-    if (!entityType || entityId === undefined || entityId === null) {
-      throw new Error('[cynx/storage] entityType and entityId are required.');
-    }
-    const res = await this._request(
-      `/api/v1/entity/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`,
-      { method: 'GET', ...options }
-    );
-    return Array.isArray(res) ? res : [];
-  }
-
-  /**
-   * Delete a single file by ID.
-   * 
-   * @param {string} fileId ID of the file to delete
-   * @param {object} [options]
-   * @param {string} [options.apiKey] Override API Key
-   * @returns {Promise<{ message: string, fileId: string }>}
-   */
-  async deleteFile(fileId, options = {}) {
-    if (!fileId) throw new Error('[cynx/storage] fileId is required.');
-    const cleanId = String(fileId).trim().replace(/\.[^/.]+$/, '');
-    return this._request(`/api/v1/files/${encodeURIComponent(cleanId)}`, {
-      method: 'DELETE',
-      ...options,
-    });
-  }
-
-  /**
-   * Delete all files belonging to a specific entity.
-   * 
-   * @param {string} entityType Entity type
-   * @param {string|number} entityId Entity identifier
-   * @param {object} [options]
-   * @param {string} [options.apiKey] Override API Key
-   * @returns {Promise<{ message: string, deletedCount: number }>}
-   */
-  async deleteEntityFiles(entityType, entityId, options = {}) {
-    if (!entityType || entityId === undefined || entityId === null) {
-      throw new Error('[cynx/storage] entityType and entityId are required.');
-    }
-    return this._request(
-      `/api/v1/entity/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`,
-      { method: 'DELETE', ...options }
-    );
-  }
-
-  /**
-   * Generate a public CDN streaming/viewing URL for a file.
-   * 
-   * @param {string} fileId File ID
-   * @param {string} [filename] Optional clean filename for browser save/view
-   * @returns {string} Complete CDN URL
-   */
-  getCdnUrl(fileId, filename = '') {
-    return getCdnUrl(fileId, filename, this.baseUrl);
-  }
-
-  /**
-   * Download a file from CDN as a standard Fetch Response.
-   * 
-   * @param {string} fileId File ID
-   * @param {object} [options]
-   * @param {string} [options.filename]
-   * @param {AbortSignal} [options.signal]
-   * @returns {Promise<Response>}
-   */
-  async download(fileId, options = {}) {
-    if (!this.fetchFn) {
-      throw new Error('[cynx/storage] No fetch implementation available.');
-    }
-    const url = this.getCdnUrl(fileId, options.filename);
-    const res = await this.fetchFn(url, { signal: options.signal });
-    if (!res.ok) {
-      throw new Error(`Failed to download file: HTTP ${res.status} ${res.statusText}`);
-    }
-    return res;
-  }
-}
-
-/**
- * Factory function to create a new StorageClient instance.
- * 
- * @param {object} [options]
- * @returns {StorageClient}
- */
-export function createStorageClient(options = {}) {
-  return new StorageClient(options);
-}
-
-export default {
-  StorageClient,
-  createStorageClient,
-  getCdnUrl,
-  getFileTypeCategory,
-  formatBytes,
-};
+/**
+ * cynx/utils — Storage Server Client & Connector (storage.js)
+ *
+ * Universal client SDK to interact with cynx-storage-server:
+ *  - Upload files (Browser File/Blob or Node.js Buffer/Stream/Blob)
+ *  - Query file metadata & entity attachments
+ *  - Delete files or whole entity file groups
+ *  - Generate public CDN URLs and stream content
+ *
+ * Works in Browser, Node.js (18+), Next.js / SSR, and Web Workers.
+ * Zero external dependencies.
+ */
+
+// ─── UTILITIES & HELPERS ────────────────────────────────────────────────────────
+
+const isNode = typeof process !== 'undefined' && Boolean(process.versions?.node);
+
+function getDefaultBaseUrl() {
+  if (isNode && process.env?.STORAGE_SERVER_URL) {
+    return process.env.STORAGE_SERVER_URL;
+  }
+  if (typeof window !== 'undefined' && window.location?.origin) {
+    return window.location.origin;
+  }
+  return '';
+}
+
+function getDefaultApiKey() {
+  if (isNode && (process.env?.STORAGE_SERVER_API_KEY || process.env?.STORAGE_API_KEY)) {
+    return process.env.STORAGE_SERVER_API_KEY || process.env.STORAGE_API_KEY;
+  }
+  return '';
+}
+
+/**
+ * Format raw byte numbers into human-readable strings.
+ * @param {number|string} bytes 
+ * @returns {string} e.g. "12.5 MB"
+ */
+export function formatBytes(bytes) {
+  const num = Number(bytes) || 0;
+  if (num === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(num) / Math.log(k));
+  const val = (num / Math.pow(k, i)).toFixed(2);
+  return `${val} ${sizes[i]}`;
+}
+
+/**
+ * Categorize mimeType and filename into categories.
+ * @param {string} [mimeType=''] 
+ * @param {string} [filename=''] 
+ * @returns {'image'|'pdf'|'video'|'audio'|'document'|'archive'|'other'}
+ */
+export function getFileTypeCategory(mimeType = '', filename = '') {
+  const mt = (mimeType || '').toLowerCase();
+  const fn = (filename || '').toLowerCase();
+
+  if (mt.startsWith('image/') || /\.(jpg|jpeg|png|gif|webp|bmp|svg|avif|ico)$/i.test(fn)) {
+    return 'image';
+  }
+  if (mt === 'application/pdf' || /\.pdf$/i.test(fn)) {
+    return 'pdf';
+  }
+  if (mt.startsWith('video/') || /\.(mp4|webm|mkv|mov|avi|flv|wmv|m4v)$/i.test(fn)) {
+    return 'video';
+  }
+  if (mt.startsWith('audio/') || /\.(mp3|wav|ogg|m4a|aac|flac)$/i.test(fn)) {
+    return 'audio';
+  }
+  if (
+    mt.includes('word') ||
+    mt.includes('excel') ||
+    mt.includes('spreadsheet') ||
+    mt.includes('presentation') ||
+    mt.includes('csv') ||
+    /\.(doc|docx|xls|xlsx|csv|ppt|pptx|txt|rtf|md)$/i.test(fn)
+  ) {
+    return 'document';
+  }
+  if (mt.includes('zip') || mt.includes('tar') || mt.includes('compressed') || /\.(zip|tar|gz|7z|rar)$/i.test(fn)) {
+    return 'archive';
+  }
+  return 'other';
+}
+
+/**
+ * Build a public CDN URL for a given file ID.
+ * @param {string} fileId e.g. "sf_abc123"
+ * @param {string} [filename] Optional filename suffix for cleaner download names
+ * @param {string} [baseUrl] Storage server base URL
+ * @returns {string} CDN URL
+ */
+export function getCdnUrl(fileId, filename = '', baseUrl = '') {
+  if (!fileId) return '';
+  const base = (baseUrl || getDefaultBaseUrl() || '').replace(/\/+$/, '');
+  const cleanId = String(fileId).trim();
+  const suffix = filename ? `/${encodeURIComponent(filename)}` : '';
+  return `${base}/cdn/${encodeURIComponent(cleanId)}${suffix}`;
+}
+
+// ─── STORAGE CLIENT CLASS ───────────────────────────────────────────────────────
+
+export class StorageClient {
+  /**
+   * @param {object} [options={}]
+   * @param {string} [options.baseUrl] Base URL of the storage server (e.g. "https://storage.domain.com" or "http://localhost:5000")
+   * @param {string} [options.apiKey] API Key with upload/read/delete permissions
+   * @param {number} [options.timeout=30000] Request timeout in milliseconds
+   * @param {Function} [options.fetch] Custom fetch implementation (optional)
+   */
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl || getDefaultBaseUrl() || '').replace(/\/+$/, '');
+    this.apiKey = options.apiKey || getDefaultApiKey() || '';
+    this.timeout = options.timeout || 30000;
+    this.fetchFn = options.fetch || (typeof globalThis !== 'undefined' ? globalThis.fetch?.bind(globalThis) : null);
+  }
+
+  /**
+   * Update configuration options.
+   * @param {object} options 
+   */
+  configure(options = {}) {
+    if (options.baseUrl !== undefined) this.baseUrl = String(options.baseUrl || '').replace(/\/+$/, '');
+    if (options.apiKey !== undefined) this.apiKey = String(options.apiKey || '');
+    if (options.timeout !== undefined) this.timeout = Number(options.timeout) || 30000;
+    if (options.fetch !== undefined) this.fetchFn = options.fetch;
+    return this;
+  }
+
+  /**
+   * Internal HTTP request helper.
+   * @private
+   */
+  async _request(path, { method = 'GET', headers = {}, body, apiKey, signal, timeout } = {}) {
+    if (!this.fetchFn) {
+      throw new Error('[cynx/storage] No fetch implementation available in current environment.');
+    }
+
+    const url = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    const key = apiKey !== undefined ? apiKey : this.apiKey;
+    const reqHeaders = { ...headers };
+
+    if (key) {
+      reqHeaders['x-api-key'] = key;
+    }
+
+    const abortCtrl = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    const reqTimeout = timeout || this.timeout;
+    let timer = null;
+
+    if (abortCtrl && reqTimeout > 0) {
+      timer = setTimeout(() => abortCtrl.abort(new Error(`Storage request timeout after ${reqTimeout}ms`)), reqTimeout);
+    }
+
+    const activeSignal = signal || abortCtrl?.signal;
+
+    try {
+      const response = await this.fetchFn(url, {
+        method,
+        headers: reqHeaders,
+        body,
+        signal: activeSignal,
+      });
+
+      if (timer) clearTimeout(timer);
+
+      if (!response.ok) {
+        let errData = null;
+        try {
+          errData = await response.json();
+        } catch {
+          errData = { error: response.statusText || `HTTP ${response.status}` };
+        }
+        const error = new Error(errData.error || errData.message || `Storage Error: ${response.status}`);
+        error.status = response.status;
+        error.response = errData;
+        throw error;
+      }
+
+      return await response.json();
+    } catch (err) {
+      if (timer) clearTimeout(timer);
+      throw err;
+    }
+  }
+
+  /**
+   * Upload one or multiple files to the storage server.
+   * 
+   * @param {object} params
+   * @param {File|Blob|Buffer|ArrayBuffer|Array<File|Blob|Buffer|object>} [params.files] File or array of files to upload
+   * @param {File|Blob|Buffer|ArrayBuffer} [params.file] Single file alias
+   * @param {string} [params.folder] Target subfolder in cloud storage
+   * @param {string} [params.entityType] Associated entity type (e.g. 'company', 'employee', 'inspection')
+   * @param {string|number} [params.entityId] Associated entity ID
+   * @param {string} [params.apiKey] Override API Key for this upload
+   * @param {AbortSignal} [params.signal] AbortSignal for cancellation
+   * @returns {Promise<{ files: Array<object>, file: object|null }>} Formatted upload result
+   */
+  async upload({
+    files,
+    file,
+    folder,
+    entityType,
+    entityId,
+    entity_type,
+    entity_id,
+    apiKey,
+    signal,
+  } = {}) {
+    if (typeof FormData === 'undefined') {
+      throw new Error('[cynx/storage] FormData is not available in the current environment.');
+    }
+
+    const formData = new FormData();
+    const rawFiles = files ? (Array.isArray(files) ? files : [files]) : file ? [file] : [];
+
+    if (rawFiles.length === 0) {
+      throw new Error('[cynx/storage] No file provided for upload.');
+    }
+
+    for (let i = 0; i < rawFiles.length; i++) {
+      const item = rawFiles[i];
+      if (!item) continue;
+
+      if (typeof File !== 'undefined' && item instanceof File) {
+        formData.append('files', item, item.name);
+      } else if (typeof Blob !== 'undefined' && item instanceof Blob) {
+        const name = item.name || `file_${Date.now()}_${i}`;
+        formData.append('files', item, name);
+      } else if (isNode && (Buffer.isBuffer(item) || item instanceof Uint8Array || item instanceof ArrayBuffer)) {
+        const name = item.name || item.filename || `file_${Date.now()}_${i}`;
+        const blob = new Blob([item], { type: item.type || item.mimeType || 'application/octet-stream' });
+        formData.append('files', blob, name);
+      } else if (item && typeof item === 'object' && item.data) {
+        // Wrapped object format: { data, name, type }
+        const name = item.name || item.filename || `file_${Date.now()}_${i}`;
+        const blob = item.data instanceof Blob ? item.data : new Blob([item.data], { type: item.type || item.mimeType || 'application/octet-stream' });
+        formData.append('files', blob, name);
+      } else {
+        formData.append('files', item);
+      }
+    }
+
+    if (folder) formData.append('folder', folder);
+    const resolvedEntityType = entityType || entity_type;
+    const resolvedEntityId = entityId || entity_id;
+
+    if (resolvedEntityType) formData.append('entityType', resolvedEntityType);
+    if (resolvedEntityId) formData.append('entityId', String(resolvedEntityId));
+
+    const res = await this._request('/api/v1/upload', {
+      method: 'POST',
+      body: formData,
+      apiKey,
+      signal,
+    });
+
+    const fileList = res?.files ? res.files : Array.isArray(res) ? res : res ? [res] : [];
+    return {
+      files: fileList,
+      file: fileList[0] || null,
+      ...res,
+    };
+  }
+
+  /**
+   * Get metadata and CDN URLs for a specific file by its ID.
+   * 
+   * @param {string} fileId ID of the file (e.g. "sf_abc123")
+   * @param {object} [options]
+   * @param {string} [options.apiKey] Override API Key
+   * @param {AbortSignal} [options.signal] AbortSignal
+   * @returns {Promise<object>} File metadata record
+   */
+  async getFile(fileId, options = {}) {
+    if (!fileId) throw new Error('[cynx/storage] fileId is required.');
+    const cleanId = String(fileId).trim().replace(/\.[^/.]+$/, ''); // strip any extension if present
+    return this._request(`/api/v1/files/${encodeURIComponent(cleanId)}`, {
+      method: 'GET',
+      ...options,
+    });
+  }
+
+  /**
+   * Get all files attached to a specific entity.
+   * 
+   * @param {string} entityType Entity type (e.g. "company", "employee")
+   * @param {string|number} entityId Entity identifier
+   * @param {object} [options]
+   * @param {string} [options.apiKey] Override API Key
+   * @param {AbortSignal} [options.signal] AbortSignal
+   * @returns {Promise<Array<object>>} List of file metadata records
+   */
+  async getEntityFiles(entityType, entityId, options = {}) {
+    if (!entityType || entityId === undefined || entityId === null) {
+      throw new Error('[cynx/storage] entityType and entityId are required.');
+    }
+    const res = await this._request(
+      `/api/v1/entity/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`,
+      { method: 'GET', ...options }
+    );
+    return Array.isArray(res) ? res : [];
+  }
+
+  /**
+   * Delete a single file by ID.
+   * 
+   * @param {string} fileId ID of the file to delete
+   * @param {object} [options]
+   * @param {string} [options.apiKey] Override API Key
+   * @returns {Promise<{ message: string, fileId: string }>}
+   */
+  async deleteFile(fileId, options = {}) {
+    if (!fileId) throw new Error('[cynx/storage] fileId is required.');
+    const cleanId = String(fileId).trim().replace(/\.[^/.]+$/, '');
+    return this._request(`/api/v1/files/${encodeURIComponent(cleanId)}`, {
+      method: 'DELETE',
+      ...options,
+    });
+  }
+
+  /**
+   * Delete all files belonging to a specific entity.
+   * 
+   * @param {string} entityType Entity type
+   * @param {string|number} entityId Entity identifier
+   * @param {object} [options]
+   * @param {string} [options.apiKey] Override API Key
+   * @returns {Promise<{ message: string, deletedCount: number }>}
+   */
+  async deleteEntityFiles(entityType, entityId, options = {}) {
+    if (!entityType || entityId === undefined || entityId === null) {
+      throw new Error('[cynx/storage] entityType and entityId are required.');
+    }
+    return this._request(
+      `/api/v1/entity/${encodeURIComponent(entityType)}/${encodeURIComponent(entityId)}`,
+      { method: 'DELETE', ...options }
+    );
+  }
+
+  /**
+   * Generate a public CDN streaming/viewing URL for a file.
+   * 
+   * @param {string} fileId File ID
+   * @param {string} [filename] Optional clean filename for browser save/view
+   * @returns {string} Complete CDN URL
+   */
+  getCdnUrl(fileId, filename = '') {
+    return getCdnUrl(fileId, filename, this.baseUrl);
+  }
+
+  /**
+   * Download a file from CDN as a standard Fetch Response.
+   * 
+   * @param {string} fileId File ID
+   * @param {object} [options]
+   * @param {string} [options.filename]
+   * @param {AbortSignal} [options.signal]
+   * @returns {Promise<Response>}
+   */
+  async download(fileId, options = {}) {
+    if (!this.fetchFn) {
+      throw new Error('[cynx/storage] No fetch implementation available.');
+    }
+    const url = this.getCdnUrl(fileId, options.filename);
+    const res = await this.fetchFn(url, { signal: options.signal });
+    if (!res.ok) {
+      throw new Error(`Failed to download file: HTTP ${res.status} ${res.statusText}`);
+    }
+    return res;
+  }
+}
+
+/**
+ * Factory function to create a new StorageClient instance.
+ * 
+ * @param {object} [options]
+ * @returns {StorageClient}
+ */
+export function createStorageClient(options = {}) {
+  return new StorageClient(options);
+}
+
+export default {
+  StorageClient,
+  createStorageClient,
+  getCdnUrl,
+  getFileTypeCategory,
+  formatBytes,
+};