@techfinityedge/koolbase-react-native 5.1.1 → 5.2.0

package/dist/storage-errors.d.ts

@@ -103,6 +103,46 @@ export declare class KoolbaseStorageFileTooLargeError extends KoolbaseStorageErr
 export declare class KoolbaseStorageMimeTypeError extends KoolbaseStorageError {
     constructor(message?: string);
 }
+/**
+ * Thrown when an object metadata payload (either at upload-confirm time
+ * or via `updateMetadata`) fails server-side validation — the server
+ * responds with 400 and code `metadata_invalid`.
+ *
+ * The `detail` field carries the specific reason from the server — e.g.
+ * `'key "foo bar": must match [a-z0-9_]+'`, `'exceeds 50 keys (got 53)'`,
+ * or `'exceeds 8192 bytes total (sum of all key + value lengths)'`. The
+ * detail names the failing key and rule so callers can fix the offending
+ * entry without guessing what shape rule was violated.
+ *
+ * Validation rules (enforced server-side):
+ * - At most 50 keys per object.
+ * - At most 8KB total (sum of byte lengths across all keys + values).
+ * - Keys: 1–64 chars, must match `[a-z0-9_]+`.
+ * - Keys with a leading underscore are reserved for system use.
+ * - Values: at most 1024 chars each.
+ *
+ * @example
+ * try {
+ *   await Koolbase.storage.updateMetadata('photos', 'sunset.jpg', {
+ *     tag: 'sunset',
+ *     'BAD KEY': 'oops',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseStorageMetadataInvalidError) {
+ *     console.warn('Metadata rejected:', e.detail);
+ *     // -> 'Metadata rejected: key "BAD KEY": must match [a-z0-9_]+'
+ *   }
+ * }
+ */
+export declare class KoolbaseStorageMetadataInvalidError extends KoolbaseStorageError {
+    /**
+     * The specific validation failure reported by the server. Names the
+     * failing key (when applicable) and the rule that was violated.
+     * Surface this directly to developer logs or user-facing UI.
+     */
+    detail?: string;
+    constructor(message?: string, detail?: string);
+}
 /**
  * Maps a non-2xx storage-layer response to a typed
  * {@link KoolbaseStorageError}, preferring the server's stable `code` and

package/dist/storage-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
+exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
 exports.koolbaseStorageError = koolbaseStorageError;
 exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
 /**
@@ -148,6 +148,46 @@ class KoolbaseStorageMimeTypeError extends KoolbaseStorageError {
     }
 }
 exports.KoolbaseStorageMimeTypeError = KoolbaseStorageMimeTypeError;
+/**
+ * Thrown when an object metadata payload (either at upload-confirm time
+ * or via `updateMetadata`) fails server-side validation — the server
+ * responds with 400 and code `metadata_invalid`.
+ *
+ * The `detail` field carries the specific reason from the server — e.g.
+ * `'key "foo bar": must match [a-z0-9_]+'`, `'exceeds 50 keys (got 53)'`,
+ * or `'exceeds 8192 bytes total (sum of all key + value lengths)'`. The
+ * detail names the failing key and rule so callers can fix the offending
+ * entry without guessing what shape rule was violated.
+ *
+ * Validation rules (enforced server-side):
+ * - At most 50 keys per object.
+ * - At most 8KB total (sum of byte lengths across all keys + values).
+ * - Keys: 1–64 chars, must match `[a-z0-9_]+`.
+ * - Keys with a leading underscore are reserved for system use.
+ * - Values: at most 1024 chars each.
+ *
+ * @example
+ * try {
+ *   await Koolbase.storage.updateMetadata('photos', 'sunset.jpg', {
+ *     tag: 'sunset',
+ *     'BAD KEY': 'oops',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseStorageMetadataInvalidError) {
+ *     console.warn('Metadata rejected:', e.detail);
+ *     // -> 'Metadata rejected: key "BAD KEY": must match [a-z0-9_]+'
+ *   }
+ * }
+ */
+class KoolbaseStorageMetadataInvalidError extends KoolbaseStorageError {
+    constructor(message, detail) {
+        super(message ?? 'Metadata payload is invalid', 'metadata_invalid');
+        this.detail = detail;
+        this.name = 'KoolbaseStorageMetadataInvalidError';
+        Object.setPrototypeOf(this, KoolbaseStorageMetadataInvalidError.prototype);
+    }
+}
+exports.KoolbaseStorageMetadataInvalidError = KoolbaseStorageMetadataInvalidError;
 /**
  * Maps a non-2xx storage-layer response to a typed
  * {@link KoolbaseStorageError}, preferring the server's stable `code` and
@@ -173,6 +213,8 @@ function koolbaseStorageError(status, body, fallbackMessage = 'Storage request f
             return new KoolbaseStorageFileTooLargeError(message);
         case 'mime_not_allowed':
             return new KoolbaseStorageMimeTypeError(message);
+        case 'metadata_invalid':
+            return new KoolbaseStorageMetadataInvalidError(message, body?.detail);
     }
     // ─── status fallback (pre-code servers or uncoded paths) ───
     switch (status) {

package/dist/storage.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, UploadOptions, UploadResult } from './types';
+import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject } from './types';
 /**
  * Koolbase storage client — uploads, downloads, and deletes via presigned
  * Cloudflare R2 URLs.
@@ -23,11 +23,52 @@ export declare class KoolbaseStorage {
      * Set `overwrite: true` for true upsert semantics — silently replace any
      * existing object at this path.
      *
+     * Pass `options.metadata` to attach arbitrary user-defined key/value pairs
+     * to the object at confirm time. Subject to the limits documented on
+     * {@link KoolbaseObject.metadata}; violations throw
+     * `KoolbaseStorageMetadataInvalidError`. On the `overwrite: true` path the
+     * metadata REPLACES any prior metadata at this path (matches GCS semantics).
+     * Use {@link updateMetadata} for post-upload merge changes.
+     *
      * **Breaking change in v5.0.0**: the default flipped from silent overwrite
      * (legacy behavior) to safe-by-default. If you previously relied on uploads
      * overwriting silently, pass `overwrite: true` explicitly.
      */
     upload(options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Apply a partial metadata update to an existing object. Returns the
+     * post-update {@link KoolbaseObject} with the merged metadata.
+     *
+     * **Merge semantics** (mirrors the server's JSONB merge):
+     *
+     * - Keys with a non-null string value are SET — added if missing,
+     *   replacing any existing value at the key otherwise.
+     * - Keys with `null` are DELETED from the stored metadata.
+     * - Keys ABSENT from `metadata` are untouched — pre-existing entries
+     *   for those keys remain unchanged.
+     *
+     * Validation runs server-side against the same rules as upload-time
+     * metadata; violations throw `KoolbaseStorageMetadataInvalidError`,
+     * whose `detail` field names the failing key and rule. The check is
+     * performed against the projected post-merge state, so adding a key
+     * that would push the object past the 50-key or 8KB ceiling is
+     * rejected before the row is mutated.
+     *
+     * @example
+     * // Add a tag, update an existing key, and drop another in one call:
+     * const updated = await Koolbase.storage.updateMetadata(
+     *   'photos',
+     *   'sunset.jpg',
+     *   {
+     *     category: 'landscape',  // SET or UPDATE
+     *     tag:      'sunset',     // SET or UPDATE
+     *     owner:    null,         // DELETE
+     *   }
+     * );
+     * console.log(updated.metadata);
+     * // -> { category: 'landscape', tag: 'sunset' }
+     */
+    updateMetadata(bucket: string, path: string, metadata: Record<string, string | null>): Promise<KoolbaseObject>;
     /**
      * Get a signed download URL for a file.
      */

package/dist/storage.js

@@ -33,6 +33,13 @@ class KoolbaseStorage {
      * Set `overwrite: true` for true upsert semantics — silently replace any
      * existing object at this path.
      *
+     * Pass `options.metadata` to attach arbitrary user-defined key/value pairs
+     * to the object at confirm time. Subject to the limits documented on
+     * {@link KoolbaseObject.metadata}; violations throw
+     * `KoolbaseStorageMetadataInvalidError`. On the `overwrite: true` path the
+     * metadata REPLACES any prior metadata at this path (matches GCS semantics).
+     * Use {@link updateMetadata} for post-upload merge changes.
+     *
      * **Breaking change in v5.0.0**: the default flipped from silent overwrite
      * (legacy behavior) to safe-by-default. If you previously relied on uploads
      * overwriting silently, pass `overwrite: true` explicitly.
@@ -76,20 +83,28 @@ class KoolbaseStorage {
         }
         const etag = uploadRes.headers.get('etag') ?? '';
         // ─── Step 3: Confirm upload ───
+        // Build the body conditionally so the `metadata` field is only sent
+        // when the caller passed it — keeps the wire shape clean for callers
+        // that don't care, and lets the server's omitempty path treat absent
+        // as "no metadata."
+        const confirmBody = {
+            bucket: options.bucket,
+            path: options.path,
+            size: fileSize,
+            content_type: contentType,
+            etag,
+            overwrite,
+        };
+        if (options.metadata !== undefined) {
+            confirmBody.metadata = options.metadata;
+        }
         const confirmRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
             method: 'POST',
             headers: {
                 ...(await this.buildHeaders()),
                 'Content-Type': 'application/json',
             },
-            body: JSON.stringify({
-                bucket: options.bucket,
-                path: options.path,
-                size: fileSize,
-                content_type: contentType,
-                etag,
-                overwrite,
-            }),
+            body: JSON.stringify(confirmBody),
         });
         if (!confirmRes.ok) {
             throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(confirmRes, 'Failed to confirm upload');
@@ -100,6 +115,54 @@ class KoolbaseStorage {
         const downloadUrl = await this.getDownloadUrl(options.bucket, options.path);
         return { object, downloadUrl };
     }
+    /**
+     * Apply a partial metadata update to an existing object. Returns the
+     * post-update {@link KoolbaseObject} with the merged metadata.
+     *
+     * **Merge semantics** (mirrors the server's JSONB merge):
+     *
+     * - Keys with a non-null string value are SET — added if missing,
+     *   replacing any existing value at the key otherwise.
+     * - Keys with `null` are DELETED from the stored metadata.
+     * - Keys ABSENT from `metadata` are untouched — pre-existing entries
+     *   for those keys remain unchanged.
+     *
+     * Validation runs server-side against the same rules as upload-time
+     * metadata; violations throw `KoolbaseStorageMetadataInvalidError`,
+     * whose `detail` field names the failing key and rule. The check is
+     * performed against the projected post-merge state, so adding a key
+     * that would push the object past the 50-key or 8KB ceiling is
+     * rejected before the row is mutated.
+     *
+     * @example
+     * // Add a tag, update an existing key, and drop another in one call:
+     * const updated = await Koolbase.storage.updateMetadata(
+     *   'photos',
+     *   'sunset.jpg',
+     *   {
+     *     category: 'landscape',  // SET or UPDATE
+     *     tag:      'sunset',     // SET or UPDATE
+     *     owner:    null,         // DELETE
+     *   }
+     * );
+     * console.log(updated.metadata);
+     * // -> { category: 'landscape', tag: 'sunset' }
+     */
+    async updateMetadata(bucket, path, metadata) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
+            method: 'PATCH',
+            headers: {
+                ...(await this.buildHeaders()),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ bucket, path, metadata }),
+        });
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to update metadata');
+        }
+        const raw = await res.json();
+        return mapObjectFromServer(raw);
+    }
     /**
      * Get a signed download URL for a file.
      */
@@ -135,6 +198,9 @@ class KoolbaseStorage {
 exports.KoolbaseStorage = KoolbaseStorage;
 /**
  * Maps the snake_case server JSON to the camelCase {@link KoolbaseObject}.
+ * Defensive: missing or null `metadata` (older / non-Koolbase responses)
+ * is coerced to an empty object so callers always see a typed
+ * `Record<string, string>` rather than null.
  */
 function mapObjectFromServer(raw) {
     return {
@@ -145,6 +211,7 @@ function mapObjectFromServer(raw) {
         path: raw.path,
         size: raw.size ?? 0,
         contentType: raw.content_type ?? null,
+        metadata: raw.metadata ?? {},
         createdAt: raw.created_at,
         updatedAt: raw.updated_at,
     };

package/dist/types.d.ts

@@ -161,6 +161,20 @@ export interface UploadOptions {
      * `true` to silently replace the existing object.
      */
     overwrite?: boolean;
+    /**
+     * User-defined key/value metadata to attach to the object at confirm
+     * time. Optional — when omitted, the object stores empty metadata `{}`.
+     *
+     * Subject to server-side validation (≤50 keys, ≤8KB total, keys 1–64
+     * chars matching `[a-z0-9_]+`, values ≤1024 chars, leading underscore
+     * reserved); violations throw `KoolbaseStorageMetadataInvalidError`.
+     *
+     * On the `overwrite: true` path, metadata REPLACES any prior metadata
+     * at this path (matches GCS semantics — a new upload at a path
+     * produces a new object, not a patch of the old). Use `updateMetadata`
+     * for post-upload merge changes.
+     */
+    metadata?: Record<string, string>;
     onProgress?: (percent: number) => void;
 }
 /**
@@ -175,6 +189,14 @@ export interface KoolbaseObject {
     path: string;
     size: number;
     contentType: string | null;
+    /**
+     * User-defined key/value metadata attached to this object. Always
+     * non-null — empty object when no metadata has been set (the server
+     * returns `{}` rather than `null` so callers can treat it as a
+     * guaranteed object without null checks). Set on upload via
+     * `upload({ metadata })` or mutated post-upload via `updateMetadata`.
+     */
+    metadata: Record<string, string>;
     /** ISO 8601 timestamp from the server. */
     createdAt: string;
     /** ISO 8601 timestamp from the server. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",