@techfinityedge/koolbase-react-native 5.0.0 → 5.1.1

package/README.md

@@ -322,24 +322,64 @@ try {
     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 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,
-      });
-    }
+  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;
   }
 }
-```
+````
 
-See [Error handling](#error-handling) for the full set of storage errors.
+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.
 
 ---
 
@@ -555,12 +595,13 @@ 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';

package/dist/storage-errors.d.ts

@@ -10,7 +10,7 @@ export declare class KoolbaseStorageError extends Error {
 /**
  * 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?"
+ * `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
@@ -64,11 +64,56 @@ export declare class KoolbaseStorageValidationError extends KoolbaseStorageError
 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;
 /**

package/dist/storage-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
+exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
 exports.koolbaseStorageError = koolbaseStorageError;
 exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
 /**
@@ -20,7 +20,7 @@ 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?"
+ * `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
@@ -49,7 +49,7 @@ exports.KoolbaseStorageError = KoolbaseStorageError;
  */
 class KoolbaseStorageConflictError extends KoolbaseStorageError {
     constructor(message, path) {
-        super(message ?? 'An object already exists at this path', 'PATH_CONFLICT');
+        super(message ?? 'An object already exists at this path', 'path_conflict');
         this.path = path;
         this.name = 'KoolbaseStorageConflictError';
         Object.setPrototypeOf(this, KoolbaseStorageConflictError.prototype);
@@ -94,24 +94,94 @@ class KoolbaseStoragePermissionError extends KoolbaseStorageError {
     }
 }
 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':
+        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:

package/package.json

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