@techfinityedge/koolbase-react-native 5.1.1 → 5.3.0

package/README.md

@@ -73,6 +73,8 @@ const unsubscribe = Koolbase.auth.onAuthStateChange((user) => {
 });
 ```
 
+---
+
 ### OAuth — Apple
 
 Apple Sign-In uses the native authentication flow via `@invertase/react-native-apple-authentication` as a peer dependency:
@@ -100,6 +102,8 @@ const session = await Koolbase.auth.signInWithApple({
 
 Configure Apple Sign-In for your environment with your iOS app's Bundle ID. Full setup guide at [docs.koolbase.com/auth/oauth](https://docs.koolbase.com/auth/oauth).
 
+---
+
 ### OAuth — Google
 
 Google Sign-In uses the native authentication flow via `@react-native-google-signin/google-signin` as a peer dependency:
@@ -121,6 +125,8 @@ const session = await Koolbase.auth.signInWithGoogle({
 
 Configure Google Sign-In for your environment with the OAuth client IDs from Google Cloud Console (typically one each for iOS, Android, and web). Full setup guide at [docs.koolbase.com/auth/oauth](https://docs.koolbase.com/auth/oauth).
 
+---
+
 ### Phone + OTP
 
 ```typescript
@@ -173,6 +179,8 @@ await Koolbase.db.update('record-id', { title: 'Updated' });
 await Koolbase.db.delete('record-id');
 ```
 
+---
+
 ### Handling unique-constraint conflicts
 
 A write that would violate a unique constraint throws `KoolbaseConflictError`:
@@ -187,6 +195,46 @@ try {
 }
 ```
 
+---
+
+### Public bucket URLs
+
+For files in public buckets, you can construct the stable CDN URL directly — no
+network call, no expiry, embeddable anywhere a browser fetches a URL.
+
+```typescript
+import { KoolbaseStorage } from '@techfinityedge/koolbase-react-native';
+
+// From a KoolbaseObject you already have (e.g. from upload() or another read)
+const { object } = await Koolbase.storage.upload({
+  bucket: 'avatars',
+  path: `user-${userId}.jpg`,
+  file: { uri: imageUri, name: 'avatar.jpg', type: 'image/jpeg' },
+});
+
+const url = KoolbaseStorage.publicUrlForObject(object, 'avatars');
+// url is null for private-bucket objects; the CDN URL for public-bucket ones.
+
+if (url) {
+  // Safe to use — file lives in the public R2 bucket
+  return <Image source={{ uri: url }} />;
+}
+
+// For build-time URL construction (no Object on hand)
+const url = KoolbaseStorage.publicUrl({
+  projectId: 'proj_abc',
+  bucket: 'avatars',
+  path: 'user-123.jpg',
+});
+// Always returns the URL pattern; caller is responsible for knowing
+// the file lives in a public bucket. For files in private buckets,
+// the resulting URL will 404.
+```
+
+URLs follow the pattern `https://cdn.koolbase.com/{project_id}/{bucket}/{path}` — long-lived, edge-cached, no authentication. For files in private buckets, use `getDownloadUrl` instead, which returns a 1-hour presigned URL.
+
+---
+
 ### Upsert
 
 Insert a record, or update the existing one matching a filter.
@@ -230,6 +278,8 @@ if (isFromCache) console.log('Served from local cache');
 await Koolbase.db.syncPendingWrites();
 ```
 
+---
+
 ### Atomic batch writes
 
 Run multiple writes in a single server-side transaction. All operations commit together or none are applied — any failure rolls back the entire batch.
@@ -309,6 +359,8 @@ const url = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg
 await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);
 ```
 
+---
+
 ### Handling upload conflicts
 
 For user-supplied filenames, prompt the user before overwriting:
@@ -622,6 +674,8 @@ try {
 > the background, so their conflicts surface via the sync engine, not as a
 > thrown error.
 
+---
+
 ### Storage errors
 
 All storage failures extend `KoolbaseStorageError` (which extends `Error`):

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,15 +23,90 @@ 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.
      */
     getDownloadUrl(bucket: string, path: string): Promise<string>;
+    /**
+     * Build the stable public CDN URL for a file in a public bucket.
+     *
+     * Returns the URL unconditionally — no check on whether the file
+     * exists or whether the bucket is actually public. Use when you
+     * know the file is in a public bucket and want the URL without a
+     * network round-trip (build-time URL generation, server-side
+     * rendering, batch image processing, etc.).
+     *
+     * For safer construction from an Object you already have, use
+     * {@link KoolbaseStorage.publicUrlForObject} — it checks the stored
+     * `r2Bucket` value and returns `null` when the object isn't in the
+     * public R2 bucket.
+     */
+    static publicUrl(args: {
+        projectId: string;
+        bucket: string;
+        path: string;
+    }): string;
+    /**
+     * Returns the stable CDN URL for an object when its bytes physically
+     * live in the public R2 bucket, `null` otherwise.
+     *
+     * Returns `null` for:
+     * - Files in private buckets (no public URL ever)
+     * - Legacy files in public buckets whose bytes still live in the
+     *   private R2 bucket from before Gap #2 (no permanent URL until
+     *   they're re-uploaded)
+     *
+     * The bucket name must be supplied because {@link KoolbaseObject}
+     * carries only the bucket ID, not its name. Typically the caller
+     * already knows which bucket they queried.
+     */
+    static publicUrlForObject(obj: KoolbaseObject, bucket: string): string | null;
     /**
      * Delete a file from a bucket.
      */

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.
      */
@@ -113,6 +176,45 @@ class KoolbaseStorage {
         const data = (await res.json());
         return data.url;
     }
+    /**
+     * Build the stable public CDN URL for a file in a public bucket.
+     *
+     * Returns the URL unconditionally — no check on whether the file
+     * exists or whether the bucket is actually public. Use when you
+     * know the file is in a public bucket and want the URL without a
+     * network round-trip (build-time URL generation, server-side
+     * rendering, batch image processing, etc.).
+     *
+     * For safer construction from an Object you already have, use
+     * {@link KoolbaseStorage.publicUrlForObject} — it checks the stored
+     * `r2Bucket` value and returns `null` when the object isn't in the
+     * public R2 bucket.
+     */
+    static publicUrl(args) {
+        // Encode each path segment individually so slashes are preserved
+        // while spaces, parens, hashes, and query characters are escaped.
+        const encoded = args.path.split('/').map(encodeURIComponent).join('/');
+        return `https://cdn.koolbase.com/${args.projectId}/${args.bucket}/${encoded}`;
+    }
+    /**
+     * Returns the stable CDN URL for an object when its bytes physically
+     * live in the public R2 bucket, `null` otherwise.
+     *
+     * Returns `null` for:
+     * - Files in private buckets (no public URL ever)
+     * - Legacy files in public buckets whose bytes still live in the
+     *   private R2 bucket from before Gap #2 (no permanent URL until
+     *   they're re-uploaded)
+     *
+     * The bucket name must be supplied because {@link KoolbaseObject}
+     * carries only the bucket ID, not its name. Typically the caller
+     * already knows which bucket they queried.
+     */
+    static publicUrlForObject(obj, bucket) {
+        if (obj.r2Bucket !== 'koolbase-storage-public')
+            return null;
+        return KoolbaseStorage.publicUrl({ projectId: obj.projectId, bucket, path: obj.path });
+    }
     /**
      * Delete a file from a bucket.
      */
@@ -135,6 +237,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 +250,8 @@ function mapObjectFromServer(raw) {
         path: raw.path,
         size: raw.size ?? 0,
         contentType: raw.content_type ?? null,
+        metadata: raw.metadata ?? {},
+        r2Bucket: raw.r2_bucket ?? 'koolbase-storage',
         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;
 }
 /**
@@ -171,10 +185,28 @@ export interface KoolbaseObject {
     id: string;
     projectId: string;
     bucketId: string;
+    /**
+     * Name of the physical R2 bucket holding this object's bytes
+     * (Gap #2). `'koolbase-storage-public'` means the object has a
+     * stable CDN URL — construct it with
+     * `KoolbaseStorage.publicUrlForObject(obj, bucket)`. Anything else
+     * (typically `'koolbase-storage'`) means the object is in private
+     * storage and reads go through {@link KoolbaseStorage.getDownloadUrl},
+     * which returns a 1-hour presigned URL.
+     */
+    r2Bucket: string;
     userId: string | null;
     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.3.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",
@@ -27,6 +27,8 @@
   },
   "devDependencies": {
     "@types/jszip": "^3.4.0",
+    "@types/node": "^25.9.1",
+    "react-native": "^0.85.3",
     "react-native-keychain": "^10.0.0",
     "typescript": "^5.0.0"
   },