@techfinityedge/koolbase-react-native 4.2.0 → 5.0.0

package/README.md

@@ -16,24 +16,24 @@ Auth, database, storage, realtime, functions, feature flags, remote config, vers
 3. Add the SDK:
 
 ```bash
-npm install @techfinityedge/koolbase-react-native
-# or
-yarn add @techfinityedge/koolbase-react-native
-# or
-pnpm add @techfinityedge/koolbase-react-native
-# or
-bun add @techfinityedge/koolbase-react-native
+   npm install @techfinityedge/koolbase-react-native
+   # or
+   yarn add @techfinityedge/koolbase-react-native
+   # or
+   pnpm add @techfinityedge/koolbase-react-native
+   # or
+   bun add @techfinityedge/koolbase-react-native
 ```
 
-**4. Initialize at app startup:**
+4. Initialize at app startup:
 
 ```typescript
-import { Koolbase } from '@techfinityedge/koolbase-react-native';
+   import { Koolbase } from '@techfinityedge/koolbase-react-native';
 
-await Koolbase.initialize({
-  publicKey: 'pk_live_xxxx',
-  baseUrl: 'https://api.koolbase.com',
-});
+   await Koolbase.initialize({
+     publicKey: 'pk_live_xxxx',
+     baseUrl: 'https://api.koolbase.com',
+   });
 ```
 
 That's it. Every feature below is now available via `Koolbase.*`.
@@ -125,17 +125,17 @@ Configure Google Sign-In for your environment with the OAuth client IDs from Goo
 
 ```typescript
 // Send a one-time code
-await Koolbase.auth.sendOtp({ phoneE164: '+233200000000' });
+await Koolbase.auth.sendOtp({ phoneNumber: '+233200000000' });
 
 // Verify and sign in
 await Koolbase.auth.verifyOtp({
-  phoneE164: '+233200000000',
+  phoneNumber: '+233200000000',
   code: '123456',
 });
 
 // Or link a phone to an existing account
 await Koolbase.auth.linkPhone({
-  phoneE164: '+233200000000',
+  phoneNumber: '+233200000000',
   code: '123456',
 });
 ```
@@ -175,23 +175,23 @@ await Koolbase.db.delete('record-id');
 
 ### Handling unique-constraint conflicts
 
-  A write that would violate a unique constraint throws `KoolbaseConflictError`:
+A write that would violate a unique constraint throws `KoolbaseConflictError`:
 
-  \`\`\`ts
-  try {
-    await koolbase.db.upsert('users', { email }, { name });
-  } catch (e) {
-    if (e instanceof KoolbaseConflictError) {
-      showError('That email is already registered.');
-    }
+```ts
+try {
+  await Koolbase.db.upsert('users', { email }, { name });
+} catch (e) {
+  if (e instanceof KoolbaseConflictError) {
+    showError('That email is already registered.');
   }
-  \`\`\`
+}
+```
 
 ### Upsert
 
 Insert a record, or update the existing one matching a filter.
 
-\`\`\`ts
+```ts
 const result = await Koolbase.db.upsert(
   'profiles',
   { user_id: userId },
@@ -200,7 +200,7 @@ const result = await Koolbase.db.upsert(
 
 console.log(result.created); // true if inserted, false if updated
 console.log(result.record.id);
-\`\`\`
+```
 
 > Online-only: needs the server's view to decide insert vs update, so unlike
 > `insert` it isn't queued offline and throws on network failure.
@@ -209,12 +209,12 @@ console.log(result.record.id);
 
 Bulk-delete every record matching a filter. Returns the number deleted.
 
-\`\`\`ts
+```ts
 const deleted = await Koolbase.db.deleteWhere('sessions', {
   user_id: userId,
   status: 'expired',
 });
-\`\`\`
+```
 
 > A non-empty filter is required. The collection's delete rule applies; for
 > `owner`/`scoped` rules the delete is scoped to your own records. Online-only.
@@ -253,7 +253,7 @@ const results = await Koolbase.db.batch([
 //   - delete:          { type, deleted: true }
 ```
 
-**Online-only by design.** Atomicity needs the server's authoritative view, so `batch()` is never queued offline — it throws on network failure (like `upsert` and `deleteWhere`). A server-side rejection throws a `KoolbaseDataException` with the failing operation's details; nothing was persisted.
+**Online-only by design.** Atomicity needs the server's authoritative view, so `batch()` is never queued offline — it throws on network failure (like `upsert` and `deleteWhere`). A server-side rejection throws a `KoolbaseDataError` with the failing operation's details; nothing was persisted.
 
 ---
 
@@ -281,42 +281,89 @@ When the device is offline, these writes are queued and synced automatically whe
 
 ## Storage
 
+Upload and serve files via presigned URLs to Cloudflare R2. Uploads are
+**safe-by-default** (v5+) — uploading to a path that's already taken throws
+`KoolbaseStorageConflictError` instead of silently replacing the existing
+file. Pass `overwrite: true` for true upsert semantics.
+
 ```typescript
-const { url } = await Koolbase.storage.upload({
+// Upload — rejects if `user-${userId}.jpg` already exists
+const { object, downloadUrl } = await Koolbase.storage.upload({
+  bucket: 'avatars',
+  path: `user-${userId}.jpg`,
+  file: { uri: imageUri, name: 'avatar.jpg', type: 'image/jpeg' },
+});
+
+// Upload — silently replaces any existing object at this path
+await Koolbase.storage.upload({
   bucket: 'avatars',
   path: `user-${userId}.jpg`,
   file: { uri: imageUri, name: 'avatar.jpg', type: 'image/jpeg' },
+  overwrite: true,
 });
 
-const downloadUrl = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg`);
+// Get download URL
+const url = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg`);
 
+// Delete
 await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);
 ```
 
+### Handling upload conflicts
+
+For user-supplied filenames, prompt the user before overwriting:
+
+```typescript
+import { KoolbaseStorageConflictError } from '@techfinityedge/koolbase-react-native';
+
+try {
+  await Koolbase.storage.upload({
+    bucket: 'documents',
+    path: filename,
+    file: { uri, name: filename, type: mimeType },
+  });
+} catch (e) {
+  if (e instanceof KoolbaseStorageConflictError) {
+    const ok = await confirm(`${e.path} already exists. Overwrite?`);
+    if (ok) {
+      await Koolbase.storage.upload({
+        bucket: 'documents',
+        path: filename,
+        file: { uri, name: filename, type: mimeType },
+        overwrite: true,
+      });
+    }
+  } else {
+    throw e;
+  }
+}
+```
+
+See [Error handling](#error-handling) for the full set of storage errors.
+
 ---
 
 ## Realtime
 
-Subscribe to live changes on a collection. Realtime uses the signed-in user's
-session, so subscribe after login. It streams `created` and `updated` events for
+Subscribe to live changes on a collection. Uses the signed-in user's session, so
+subscribe after login. Streams `created`, `updated`, and `deleted` events for
 collections whose read rule is `public` or `authenticated`.
 
 ```ts
-import { Koolbase } from '@techfinityedge/koolbase-react-native';
-
 const unsubscribe = Koolbase.realtime.subscribe('messages', (event) => {
-  // event.type       -> 'created' | 'updated'
-  // event.collection -> 'messages'
-  // event.record     -> KoolbaseRecord
-  console.log(event.type, event.record.data);
+  // event.type -> 'created' | 'updated' | 'deleted'
+  if (event.type === 'deleted') {
+    console.log('deleted', event.recordId);   // recordId on deletes
+  } else {
+    console.log(event.type, event.record!.data); // record on created/updated
+  }
 });
 
-unsubscribe(); // stop listening
+unsubscribe();
 ```
 
-The socket opens lazily on first `subscribe`, is shared across all subscriptions,
-and reconnects automatically. The project is taken from the user's session — you
-don't pass it.
+The socket opens lazily, is shared, and reconnects automatically. The project is
+taken from the user's session.
 
 ---
 
@@ -519,7 +566,7 @@ All data-layer failures extend `KoolbaseDataError` (which extends `Error`):
 import { KoolbaseConflictError, KoolbaseDataError } from '@techfinityedge/koolbase-react-native';
 
 try {
-  await koolbase.db.upsert('users', { email }, { name });
+  await Koolbase.db.upsert('users', { email }, { name });
 } catch (e) {
   if (e instanceof KoolbaseConflictError) {
     showError(`That ${e.field ?? 'value'} is already taken.`);
@@ -534,13 +581,52 @@ 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`):
+
+| Error | When |
+|---|---|
+| `KoolbaseStorageConflictError` | An upload targets a path that's already taken and `overwrite: false` (409, code `PATH_CONFLICT`). Exposes `.path` — the colliding path. |
+| `KoolbaseStorageNotFoundError` | The bucket or object doesn't exist (404). |
+| `KoolbaseStorageValidationError` | The request was rejected as invalid — bad path, missing field (400). |
+| `KoolbaseStoragePermissionError` | The caller is not allowed to perform the operation (403). |
+
+```ts
+import {
+  KoolbaseStorageConflictError,
+  KoolbaseStorageError,
+  KoolbaseStoragePermissionError,
+} from '@techfinityedge/koolbase-react-native';
+
+try {
+  await Koolbase.storage.upload({
+    bucket: 'avatars',
+    path: 'me.png',
+    file: { uri, name: 'me.png', type: 'image/png' },
+  });
+} catch (e) {
+  if (e instanceof KoolbaseStorageConflictError) {
+    // Already exists — prompt user to confirm overwrite
+    promptOverwrite(e.path);
+  } else if (e instanceof KoolbaseStoragePermissionError) {
+    showError('You do not have permission to upload here.');
+  } else if (e instanceof KoolbaseStorageError) {
+    // Catch-all for any other storage error
+    showError(e.message);
+  } else {
+    throw e;
+  }
+}
+```
+
 ---
 
 ## What's included
 
 - Authentication: email + password, Apple Sign-In, Google Sign-In, phone + OTP
 - Database with offline-first cache, realtime subscriptions, and populate
-- Storage with download URLs
+- Storage with presigned uploads and downloads, safe-by-default conflict handling
 - Realtime subscriptions over WebSocket
 - Authenticated functions (`ctx.auth` exposes the caller automatically)
 - Feature flags and remote config

package/dist/index.d.ts

@@ -19,6 +19,7 @@ import { KoolbaseConfig, VersionCheckResult } from './types';
 export * from './types';
 export * from './auth-errors';
 export * from './database-errors';
+export * from './storage-errors';
 export { KoolbaseAuth, KoolbaseDatabase, KoolbaseFlags, KoolbaseFunctions, KoolbaseRealtime, KoolbaseStorage };
 export declare const Koolbase: {
     initialize(config: KoolbaseConfig): Promise<void>;

package/dist/index.js

@@ -46,6 +46,7 @@ Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: funct
 __exportStar(require("./types"), exports);
 __exportStar(require("./auth-errors"), exports);
 __exportStar(require("./database-errors"), exports);
+__exportStar(require("./storage-errors"), exports);
 let _auth = null;
 let _db = null;
 let _storage = null;

package/dist/realtime.js

@@ -94,13 +94,18 @@ class KoolbaseRealtime {
             if (!mapped)
                 return; // ignore subscribed / unsubscribed / error / unknown
             const payload = raw.payload;
-            if (!payload || !payload.collection || !payload.record)
-                return; // created/updated carry a record
-            const msg = {
-                type: mapped,
-                collection: payload.collection,
-                record: (0, record_1.recordFromWire)(payload.record),
-            };
+            if (!payload || !payload.collection)
+                return;
+            let msg;
+            if (mapped === 'deleted') {
+                msg = { type: 'deleted', collection: payload.collection, recordId: payload.record_id };
+            }
+            else if (payload.record) {
+                msg = { type: mapped, collection: payload.collection, record: (0, record_1.recordFromWire)(payload.record) };
+            }
+            else {
+                return;
+            }
             (this.listeners.get(payload.collection) ?? []).forEach((cb) => cb(msg));
         };
         ws.onclose = () => {

package/dist/storage-errors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Base error type for all Koolbase storage errors. Catchable via
+ * `instanceof KoolbaseStorageError` to handle any storage-related failure
+ * generically; subclasses let you handle specific cases.
+ */
+export declare class KoolbaseStorageError extends Error {
+    code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Thrown when an upload is rejected because an object already exists at
+ * the requested path — the server responds with 409 Conflict and code
+ * `PATH_CONFLICT`. Catch it to give the user an "overwrite this file?"
+ * prompt, then retry the upload with `overwrite: true`.
+ *
+ * `path` is the colliding path the server rejected, surfaced from the
+ * response body for diagnostics and UI.
+ *
+ * @example
+ * try {
+ *   await Koolbase.storage.upload({
+ *     bucket: 'avatars',
+ *     path: 'me.png',
+ *     file: { uri, name, type: 'image/png' },
+ *   });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseStorageConflictError) {
+ *     const ok = await confirm(`${e.path} already exists. Overwrite?`);
+ *     if (ok) {
+ *       await Koolbase.storage.upload({
+ *         bucket: 'avatars',
+ *         path: 'me.png',
+ *         file: { uri, name, type: 'image/png' },
+ *         overwrite: true,
+ *       });
+ *     }
+ *   }
+ * }
+ */
+export declare class KoolbaseStorageConflictError extends KoolbaseStorageError {
+    path?: string;
+    constructor(message?: string, path?: string);
+}
+/**
+ * Thrown when the requested bucket or object does not exist — the server
+ * responds with 404. Also surfaced for cross-tenant access attempts
+ * (Koolbase's 404-over-403 convention prevents enumeration in
+ * multi-tenant contexts).
+ */
+export declare class KoolbaseStorageNotFoundError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the request is rejected as invalid — the server responds
+ * with 400 (e.g. a malformed path, missing field, invalid bucket name).
+ */
+export declare class KoolbaseStorageValidationError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the caller is authenticated but not allowed to perform the
+ * storage operation — the server responds with 403.
+ */
+export declare class KoolbaseStoragePermissionError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * Maps a non-2xx storage-layer response to a typed
+ * {@link KoolbaseStorageError}, preferring the server's stable `code` and
+ * falling back to the HTTP status for older or uncoded responses. Always
+ * returns an error to throw.
+ */
+export declare function koolbaseStorageError(status: number, body: any, fallbackMessage?: string): KoolbaseStorageError;
+/**
+ * Convenience wrapper over {@link koolbaseStorageError} that decodes the
+ * response body for you. Use at call sites that have the raw `Response`.
+ */
+export declare function koolbaseStorageErrorFromResponse(res: Response, fallbackMessage?: string): Promise<KoolbaseStorageError>;

package/dist/storage-errors.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
+exports.koolbaseStorageError = koolbaseStorageError;
+exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
+/**
+ * Base error type for all Koolbase storage errors. Catchable via
+ * `instanceof KoolbaseStorageError` to handle any storage-related failure
+ * generically; subclasses let you handle specific cases.
+ */
+class KoolbaseStorageError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'KoolbaseStorageError';
+        Object.setPrototypeOf(this, KoolbaseStorageError.prototype);
+    }
+}
+exports.KoolbaseStorageError = KoolbaseStorageError;
+/**
+ * Thrown when an upload is rejected because an object already exists at
+ * the requested path — the server responds with 409 Conflict and code
+ * `PATH_CONFLICT`. Catch it to give the user an "overwrite this file?"
+ * prompt, then retry the upload with `overwrite: true`.
+ *
+ * `path` is the colliding path the server rejected, surfaced from the
+ * response body for diagnostics and UI.
+ *
+ * @example
+ * try {
+ *   await Koolbase.storage.upload({
+ *     bucket: 'avatars',
+ *     path: 'me.png',
+ *     file: { uri, name, type: 'image/png' },
+ *   });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseStorageConflictError) {
+ *     const ok = await confirm(`${e.path} already exists. Overwrite?`);
+ *     if (ok) {
+ *       await Koolbase.storage.upload({
+ *         bucket: 'avatars',
+ *         path: 'me.png',
+ *         file: { uri, name, type: 'image/png' },
+ *         overwrite: true,
+ *       });
+ *     }
+ *   }
+ * }
+ */
+class KoolbaseStorageConflictError extends KoolbaseStorageError {
+    constructor(message, path) {
+        super(message ?? 'An object already exists at this path', 'PATH_CONFLICT');
+        this.path = path;
+        this.name = 'KoolbaseStorageConflictError';
+        Object.setPrototypeOf(this, KoolbaseStorageConflictError.prototype);
+    }
+}
+exports.KoolbaseStorageConflictError = KoolbaseStorageConflictError;
+/**
+ * Thrown when the requested bucket or object does not exist — the server
+ * responds with 404. Also surfaced for cross-tenant access attempts
+ * (Koolbase's 404-over-403 convention prevents enumeration in
+ * multi-tenant contexts).
+ */
+class KoolbaseStorageNotFoundError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The requested bucket or object was not found', 'not_found');
+        this.name = 'KoolbaseStorageNotFoundError';
+        Object.setPrototypeOf(this, KoolbaseStorageNotFoundError.prototype);
+    }
+}
+exports.KoolbaseStorageNotFoundError = KoolbaseStorageNotFoundError;
+/**
+ * Thrown when the request is rejected as invalid — the server responds
+ * with 400 (e.g. a malformed path, missing field, invalid bucket name).
+ */
+class KoolbaseStorageValidationError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The storage request was invalid', 'validation_error');
+        this.name = 'KoolbaseStorageValidationError';
+        Object.setPrototypeOf(this, KoolbaseStorageValidationError.prototype);
+    }
+}
+exports.KoolbaseStorageValidationError = KoolbaseStorageValidationError;
+/**
+ * Thrown when the caller is authenticated but not allowed to perform the
+ * storage operation — the server responds with 403.
+ */
+class KoolbaseStoragePermissionError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'You do not have permission to perform this storage action', 'permission_denied');
+        this.name = 'KoolbaseStoragePermissionError';
+        Object.setPrototypeOf(this, KoolbaseStoragePermissionError.prototype);
+    }
+}
+exports.KoolbaseStoragePermissionError = KoolbaseStoragePermissionError;
+/**
+ * Maps a non-2xx storage-layer response to a typed
+ * {@link KoolbaseStorageError}, preferring the server's stable `code` and
+ * falling back to the HTTP status for older or uncoded responses. Always
+ * returns an error to throw.
+ */
+function koolbaseStorageError(status, body, fallbackMessage = 'Storage request failed') {
+    const code = body?.code;
+    const message = body?.error ?? fallbackMessage;
+    // ─── code-first ───
+    switch (code) {
+        case 'PATH_CONFLICT':
+            return new KoolbaseStorageConflictError(message, body?.path);
+    }
+    // ─── status fallback (pre-code servers or uncoded paths) ───
+    switch (status) {
+        case 409:
+            return new KoolbaseStorageConflictError(message);
+        case 404:
+            return new KoolbaseStorageNotFoundError(message);
+        case 403:
+            return new KoolbaseStoragePermissionError(message);
+        case 400:
+            return new KoolbaseStorageValidationError(message);
+    }
+    return new KoolbaseStorageError(message, code);
+}
+/**
+ * Convenience wrapper over {@link koolbaseStorageError} that decodes the
+ * response body for you. Use at call sites that have the raw `Response`.
+ */
+async function koolbaseStorageErrorFromResponse(res, fallbackMessage = 'Storage request failed') {
+    let body = {};
+    try {
+        body = await res.json();
+    }
+    catch (_) {
+        // body wasn't JSON — fall through with empty object
+    }
+    return koolbaseStorageError(res.status, body, fallbackMessage);
+}

package/dist/storage.d.ts

@@ -1,12 +1,39 @@
-import { KoolbaseConfig, UploadOptions } from './types';
+import { KoolbaseConfig, UploadOptions, UploadResult } from './types';
+/**
+ * Koolbase storage client — uploads, downloads, and deletes via presigned
+ * Cloudflare R2 URLs.
+ *
+ * Uploads are **safe-by-default** (v5+): an upload to a path where an object
+ * already exists is rejected with {@link KoolbaseStorageConflictError} unless
+ * `overwrite: true` is passed.
+ */
 export declare class KoolbaseStorage {
     private config;
     private getToken;
     constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>);
     private buildHeaders;
-    upload(options: UploadOptions): Promise<{
-        url: string;
-    }>;
+    /**
+     * Upload a file to a bucket. Returns the object metadata and a download URL.
+     *
+     * By default (`overwrite: false`), uploads to a path where an object
+     * already exists are **rejected** with a {@link KoolbaseStorageConflictError}.
+     * Catch it to prompt the user, then retry with `overwrite: true` to replace
+     * the existing object — or with a different `path`.
+     *
+     * Set `overwrite: true` for true upsert semantics — silently replace any
+     * existing object at this path.
+     *
+     * **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>;
+    /**
+     * Get a signed download URL for a file.
+     */
     getDownloadUrl(bucket: string, path: string): Promise<string>;
+    /**
+     * Delete a file from a bucket.
+     */
     delete(bucket: string, path: string): Promise<void>;
 }

package/dist/storage.js

@@ -1,6 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseStorage = void 0;
+const storage_errors_1 = require("./storage-errors");
+/**
+ * Koolbase storage client — uploads, downloads, and deletes via presigned
+ * Cloudflare R2 URLs.
+ *
+ * Uploads are **safe-by-default** (v5+): an upload to a path where an object
+ * already exists is rejected with {@link KoolbaseStorageConflictError} unless
+ * `overwrite: true` is passed.
+ */
 class KoolbaseStorage {
     constructor(config, getToken) {
         this.config = config;
@@ -13,50 +22,130 @@ class KoolbaseStorage {
             ...(token ? { Authorization: `Bearer ${token}` } : {}),
         };
     }
+    /**
+     * Upload a file to a bucket. Returns the object metadata and a download URL.
+     *
+     * By default (`overwrite: false`), uploads to a path where an object
+     * already exists are **rejected** with a {@link KoolbaseStorageConflictError}.
+     * Catch it to prompt the user, then retry with `overwrite: true` to replace
+     * the existing object — or with a different `path`.
+     *
+     * Set `overwrite: true` for true upsert semantics — silently replace any
+     * existing object at this path.
+     *
+     * **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.
+     */
     async upload(options) {
-        // Get presigned upload URL
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/${options.bucket}/upload`, {
+        const overwrite = options.overwrite ?? false;
+        const contentType = options.file.type;
+        // ─── Step 1: Get presigned upload URL ───
+        const urlRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
-            headers: { ...(await this.buildHeaders()), 'Content-Type': 'application/json' },
+            headers: {
+                ...(await this.buildHeaders()),
+                'Content-Type': 'application/json',
+            },
             body: JSON.stringify({
+                bucket: options.bucket,
                 path: options.path,
-                content_type: options.file.type,
+                content_type: contentType,
+                overwrite,
             }),
         });
-        if (!res.ok) {
-            const data = await res.json();
-            throw new Error(data.error ?? 'Failed to get upload URL');
+        if (!urlRes.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(urlRes, 'Failed to get upload URL');
+        }
+        const { upload_url } = (await urlRes.json());
+        // ─── Step 2: Upload directly to R2 ───
+        // RN's fetch resolves local file URIs and Blob bodies on a raw PUT.
+        // R2 presigned URLs expect raw binary, NOT multipart/form-data.
+        const fileResp = await fetch(options.file.uri);
+        const fileBlob = await fileResp.blob();
+        const fileSize = fileBlob.size;
+        const uploadRes = await fetch(upload_url, {
+            method: 'PUT',
+            headers: { 'Content-Type': contentType },
+            body: fileBlob,
+        });
+        if (!uploadRes.ok) {
+            // R2 PUT errors don't follow the Koolbase error shape — surface as a
+            // generic storage error rather than trying to decode a Koolbase body.
+            throw new storage_errors_1.KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
         }
-        const { upload_url, public_url } = await res.json();
-        // Upload to presigned URL
-        const formData = new FormData();
-        formData.append('file', {
-            uri: options.file.uri,
-            name: options.file.name,
-            type: options.file.type,
+        const etag = uploadRes.headers.get('etag') ?? '';
+        // ─── Step 3: Confirm upload ───
+        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,
+            }),
         });
-        await fetch(upload_url, { method: 'PUT', body: formData });
-        return { url: public_url };
+        if (!confirmRes.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(confirmRes, 'Failed to confirm upload');
+        }
+        const raw = await confirmRes.json();
+        const object = mapObjectFromServer(raw);
+        // ─── Step 4: Get download URL ───
+        const downloadUrl = await this.getDownloadUrl(options.bucket, options.path);
+        return { object, downloadUrl };
     }
+    /**
+     * Get a signed download URL for a file.
+     */
     async getDownloadUrl(bucket, path) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/${bucket}/download?path=${encodeURIComponent(path)}`, { headers: await this.buildHeaders() });
+        const url = `${this.config.baseUrl}/v1/sdk/storage/download-url` +
+            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
+        const res = await fetch(url, { headers: await this.buildHeaders() });
         if (!res.ok) {
-            const data = await res.json();
-            throw new Error(data.error ?? 'Failed to get download URL');
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to get download URL');
         }
-        const { url } = await res.json();
-        return url;
+        const data = (await res.json());
+        return data.url;
     }
+    /**
+     * Delete a file from a bucket.
+     */
     async delete(bucket, path) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/${bucket}/delete`, {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/object`, {
             method: 'DELETE',
-            headers: { ...(await this.buildHeaders()), 'Content-Type': 'application/json' },
-            body: JSON.stringify({ path }),
+            headers: {
+                ...(await this.buildHeaders()),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ bucket, path }),
         });
-        if (!res.ok && res.status !== 204) {
-            const data = await res.json();
-            throw new Error(data.error ?? 'Delete failed');
+        if (res.status === 204)
+            return;
+        if (!res.ok) {
+            throw await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, 'Failed to delete file');
         }
     }
 }
 exports.KoolbaseStorage = KoolbaseStorage;
+/**
+ * Maps the snake_case server JSON to the camelCase {@link KoolbaseObject}.
+ */
+function mapObjectFromServer(raw) {
+    return {
+        id: raw.id,
+        projectId: raw.project_id,
+        bucketId: raw.bucket_id,
+        userId: raw.user_id ?? null,
+        path: raw.path,
+        size: raw.size ?? 0,
+        contentType: raw.content_type ?? null,
+        createdAt: raw.created_at,
+        updatedAt: raw.updated_at,
+    };
+}

package/dist/types.d.ts

@@ -155,12 +155,43 @@ export interface UploadOptions {
         name: string;
         type: string;
     };
+    /**
+     * If `false` (default in v5+), an upload to a path where an object
+     * already exists is rejected with `KoolbaseStorageConflictError`. Pass
+     * `true` to silently replace the existing object.
+     */
+    overwrite?: boolean;
     onProgress?: (percent: number) => void;
 }
+/**
+ * A stored object's server-side metadata. Field names are camelCase here
+ * even though the wire format is snake_case — the SDK maps for you.
+ */
+export interface KoolbaseObject {
+    id: string;
+    projectId: string;
+    bucketId: string;
+    userId: string | null;
+    path: string;
+    size: number;
+    contentType: string | null;
+    /** ISO 8601 timestamp from the server. */
+    createdAt: string;
+    /** ISO 8601 timestamp from the server. */
+    updatedAt: string;
+}
+/**
+ * Result of a successful `KoolbaseStorage.upload()` call.
+ */
+export interface UploadResult {
+    object: KoolbaseObject;
+    downloadUrl: string;
+}
 export interface RealtimeEvent {
     type: 'created' | 'updated' | 'deleted';
     collection: string;
-    record: KoolbaseRecord;
+    record?: KoolbaseRecord;
+    recordId?: string;
 }
 export type RealtimeCallback = (event: RealtimeEvent) => void;
 export interface BootstrapPayload {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "4.2.0",
+  "version": "5.0.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",