@techfinityedge/koolbase-react-native 4.2.1 → 5.1.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,18 +281,106 @@ 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' },
 });
 
-const downloadUrl = await Koolbase.storage.getDownloadUrl('avatars', `user-${userId}.jpg`);
+// 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,
+});
 
+// 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) 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.
+
+---
+
+### Handling bucket limits
+
+Buckets can be configured at creation time with a total size cap
+(`max_size_bytes`), a per-file cap (`max_file_size_bytes`), and a
+content-type allowlist (`allowed_mime_types`, supports `image/*`-style
+wildcards). The server surfaces violations as typed errors:
+
+````typescript
+import {
+  KoolbaseStorageQuotaError,
+  KoolbaseStorageFileTooLargeError,
+  KoolbaseStorageMimeTypeError,
+} from '@techfinityedge/koolbase-react-native';
+
+try {
+  await Koolbase.storage.upload({
+    bucket: 'user-photos',
+    path: filename,
+    file: { uri, name: filename, type: mimeType },
+  });
+} catch (e) {
+  if (e instanceof KoolbaseStorageMimeTypeError) {
+    showError('That file type is not allowed in this bucket.');
+  } else if (e instanceof KoolbaseStorageFileTooLargeError) {
+    showError('That file is too big — pick a smaller one.');
+  } else if (e instanceof KoolbaseStorageQuotaError) {
+    showError('This bucket is full — delete some files and try again.');
+  } else {
+    throw e;
+  }
+}
+````
+
+MIME enforcement runs at presign time — no bytes are transferred before
+rejection. File-size and quota enforcement run at confirm time; the
+server cleans up the underlying R2 object before returning the error,
+so nothing leaks.
+
 ---
 
 ## Realtime
@@ -315,7 +403,7 @@ unsubscribe();
 ```
 
 The socket opens lazily, is shared, and reconnects automatically. The project is
-taken from the user's session..
+taken from the user's session.
 
 ---
 
@@ -507,18 +595,19 @@ handling doesn't depend on message text.
 All data-layer failures extend `KoolbaseDataError` (which extends `Error`):
 
 | Error | When |
-|---|---|
-| `KoolbaseConflictError` | A write violates a unique constraint (409). Exposes `.field`. |
-| `KoolbaseNotFoundError` | The record or collection doesn't exist (404). |
-| `KoolbaseValidationError` | The request was rejected as invalid (400). |
-| `KoolbasePermissionError` | An access rule denied the operation (403). |
-| `KoolbaseRateLimitError` | The caller is being rate-limited (429). |
+| `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). |
+| `KoolbaseStorageQuotaError` | An upload would push the bucket past its `max_size_bytes` cap (409, code `QUOTA_EXCEEDED`). |
+| `KoolbaseStorageFileTooLargeError` | A single file exceeds the bucket's `max_file_size_bytes` cap (413, code `FILE_TOO_LARGE`). |
+| `KoolbaseStorageMimeTypeError` | The upload's content-type isn't in the bucket's `allowed_mime_types` allowlist (415, code `MIME_NOT_ALLOWED`). |
 
 ```ts
 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.`);
@@ -533,13 +622,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/storage-errors.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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);
+}
+/**
+ * Thrown when an upload would push the bucket past its configured
+ * `max_size_bytes` quota — the server responds with 409 Conflict and code
+ * `QUOTA_EXCEEDED`. The server cleans up the underlying R2 object before
+ * returning; nothing leaks. Catch this to surface a "bucket is full"
+ * message or prompt the caller to delete older files. The per-bucket
+ * quota is set at bucket creation time and is currently immutable.
+ *
+ * Distinct from {@link KoolbaseStorageConflictError} (which also uses
+ * 409 but means "path collides"); branch on the error type via
+ * `instanceof`, not on status.
+ */
+export declare class KoolbaseStorageQuotaError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a single file exceeds the bucket's configured
+ * `max_file_size_bytes` — the server responds with 413 Payload Too Large
+ * and code `FILE_TOO_LARGE`. The server cleans up the underlying R2
+ * object before returning. The configured per-file limit lives on the
+ * bucket record; check `Bucket.maxFileSizeBytes` to surface a clear
+ * "files must be under X MB" message at the call site.
+ */
+export declare class KoolbaseStorageFileTooLargeError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when an upload's content-type isn't in the bucket's configured
+ * `allowed_mime_types` allowlist — the server responds with 415
+ * Unsupported Media Type and code `MIME_NOT_ALLOWED`. The check runs at
+ * presign time, so no bytes are transferred before rejection.
+ *
+ * Allowlists support `type/*` wildcards (e.g. `image/*` matches every
+ * image content-type). A bucket with no allowlist configured accepts
+ * every type.
+ */
+export declare class KoolbaseStorageMimeTypeError 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.
+ *
+ * Status-fallback note: HTTP 409 covers both PATH_CONFLICT and
+ * QUOTA_EXCEEDED. Without a `code` field, the mapper defaults 409 to
+ * {@link KoolbaseStorageConflictError} since path collisions are the more
+ * common case. Modern Koolbase servers always emit `code`, so this only
+ * matters for very old API responses or non-Koolbase 409s.
+ */
+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,207 @@
+"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.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;
+/**
+ * Thrown when an upload would push the bucket past its configured
+ * `max_size_bytes` quota — the server responds with 409 Conflict and code
+ * `QUOTA_EXCEEDED`. The server cleans up the underlying R2 object before
+ * returning; nothing leaks. Catch this to surface a "bucket is full"
+ * message or prompt the caller to delete older files. The per-bucket
+ * quota is set at bucket creation time and is currently immutable.
+ *
+ * Distinct from {@link KoolbaseStorageConflictError} (which also uses
+ * 409 but means "path collides"); branch on the error type via
+ * `instanceof`, not on status.
+ */
+class KoolbaseStorageQuotaError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'Bucket quota exceeded', 'QUOTA_EXCEEDED');
+        this.name = 'KoolbaseStorageQuotaError';
+        Object.setPrototypeOf(this, KoolbaseStorageQuotaError.prototype);
+    }
+}
+exports.KoolbaseStorageQuotaError = KoolbaseStorageQuotaError;
+/**
+ * Thrown when a single file exceeds the bucket's configured
+ * `max_file_size_bytes` — the server responds with 413 Payload Too Large
+ * and code `FILE_TOO_LARGE`. The server cleans up the underlying R2
+ * object before returning. The configured per-file limit lives on the
+ * bucket record; check `Bucket.maxFileSizeBytes` to surface a clear
+ * "files must be under X MB" message at the call site.
+ */
+class KoolbaseStorageFileTooLargeError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'File exceeds the bucket maximum file size', 'FILE_TOO_LARGE');
+        this.name = 'KoolbaseStorageFileTooLargeError';
+        Object.setPrototypeOf(this, KoolbaseStorageFileTooLargeError.prototype);
+    }
+}
+exports.KoolbaseStorageFileTooLargeError = KoolbaseStorageFileTooLargeError;
+/**
+ * Thrown when an upload's content-type isn't in the bucket's configured
+ * `allowed_mime_types` allowlist — the server responds with 415
+ * Unsupported Media Type and code `MIME_NOT_ALLOWED`. The check runs at
+ * presign time, so no bytes are transferred before rejection.
+ *
+ * Allowlists support `type/*` wildcards (e.g. `image/*` matches every
+ * image content-type). A bucket with no allowlist configured accepts
+ * every type.
+ */
+class KoolbaseStorageMimeTypeError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'Content-type not allowed for this bucket', 'MIME_NOT_ALLOWED');
+        this.name = 'KoolbaseStorageMimeTypeError';
+        Object.setPrototypeOf(this, KoolbaseStorageMimeTypeError.prototype);
+    }
+}
+exports.KoolbaseStorageMimeTypeError = KoolbaseStorageMimeTypeError;
+/**
+ * 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.
+ *
+ * Status-fallback note: HTTP 409 covers both PATH_CONFLICT and
+ * QUOTA_EXCEEDED. Without a `code` field, the mapper defaults 409 to
+ * {@link KoolbaseStorageConflictError} since path collisions are the more
+ * common case. Modern Koolbase servers always emit `code`, so this only
+ * matters for very old API responses or non-Koolbase 409s.
+ */
+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);
+        case 'QUOTA_EXCEEDED':
+            return new KoolbaseStorageQuotaError(message);
+        case 'FILE_TOO_LARGE':
+            return new KoolbaseStorageFileTooLargeError(message);
+        case 'MIME_NOT_ALLOWED':
+            return new KoolbaseStorageMimeTypeError(message);
+    }
+    // ─── status fallback (pre-code servers or uncoded paths) ───
+    switch (status) {
+        case 409:
+            return new KoolbaseStorageConflictError(message);
+        case 413:
+            return new KoolbaseStorageFileTooLargeError(message);
+        case 415:
+            return new KoolbaseStorageMimeTypeError(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,8 +155,38 @@ 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;

package/package.json

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