feat(storage): typed errors for bucket-limit failures (v5.1.0)

Three new error classes covering the bucket-limit failure modes
introduced by Storage #2 server-side. All extend KoolbaseStorageError
so existing catch-all handlers (instanceof KoolbaseStorageError) keep
working; check the specifics to branch on the kind of limit hit.

- KoolbaseStorageQuotaError        — 409 + QUOTA_EXCEEDED
- KoolbaseStorageFileTooLargeError — 413 + FILE_TOO_LARGE
- KoolbaseStorageMimeTypeError     — 415 + MIME_NOT_ALLOWED

Mapper (koolbaseStorageError / koolbaseStorageErrorFromResponse)
recognizes the new codes via code-first lookup and the new HTTP
statuses (413, 415) via status fallback. Status-fallback for 409
remains KoolbaseStorageConflictError (path collisions are the more
common case); modern servers always emit code so the ambiguity only
affects very old API responses.

No breaking changes — pure additive surface. v5.0.0 → v5.1.0.

Pairs with koolbase_flutter v6.1.0 (published earlier today). Same
three error types, same code-first mapper extension.

Author: kennedyowusu

CHANGELOG.md

@@ -7,6 +7,35 @@ adheres to [Semantic Versioning][semver].
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
 
+## 5.1.0
+
+### Added — storage
+
+- Three new typed errors covering the bucket-limit failure modes
+  introduced server-side in Storage #2. All extend
+  `KoolbaseStorageError`, so existing `instanceof KoolbaseStorageError`
+  catch-all blocks continue to work; check the specific type to branch
+  on the kind of limit hit.
+  - `KoolbaseStorageQuotaError` — 409 + `QUOTA_EXCEEDED`, thrown when
+    an upload would push the bucket past its `max_size_bytes` cap.
+  - `KoolbaseStorageFileTooLargeError` — 413 + `FILE_TOO_LARGE`, thrown
+    when a single file exceeds the bucket's `max_file_size_bytes` cap.
+  - `KoolbaseStorageMimeTypeError` — 415 + `MIME_NOT_ALLOWED`, thrown
+    when an upload's content-type isn't in the bucket's
+    `allowed_mime_types` allowlist (supports `type/*` wildcards).
+- Mapper (`koolbaseStorageError` / `koolbaseStorageErrorFromResponse`)
+  recognizes the new codes via code-first lookup and the new HTTP
+  statuses (413, 415) via status fallback.
+
+### Notes
+
+- Backwards-compatible: pure additive surface. v5.0.0 → v5.1.0.
+- Status-fallback for 409 remains `KoolbaseStorageConflictError` (path
+  collisions are the more common case); modern servers always emit
+  `code`, so the ambiguity only affects very old API responses.
+- Pairs with `koolbase_flutter` v6.1.0 (published earlier today). Same
+  three error types, same code-first mapper extension.
+
 ## 5.0.0
 
 ### Breaking — storage

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.json

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

src/storage-errors.ts

@@ -96,11 +96,71 @@ export class KoolbaseStoragePermissionError extends KoolbaseStorageError {
   }
 }
 
+/**
+ * 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 class KoolbaseStorageQuotaError extends KoolbaseStorageError {
+  constructor(message?: string) {
+    super(message ?? 'Bucket quota exceeded', 'QUOTA_EXCEEDED');
+    this.name = 'KoolbaseStorageQuotaError';
+    Object.setPrototypeOf(this, KoolbaseStorageQuotaError.prototype);
+  }
+}
+
+/**
+ * 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 class KoolbaseStorageFileTooLargeError extends KoolbaseStorageError {
+  constructor(message?: string) {
+    super(message ?? 'File exceeds the bucket maximum file size', 'FILE_TOO_LARGE');
+    this.name = 'KoolbaseStorageFileTooLargeError';
+    Object.setPrototypeOf(this, KoolbaseStorageFileTooLargeError.prototype);
+  }
+}
+
+/**
+ * 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 class KoolbaseStorageMimeTypeError extends KoolbaseStorageError {
+  constructor(message?: string) {
+    super(message ?? 'Content-type not allowed for this bucket', 'MIME_NOT_ALLOWED');
+    this.name = 'KoolbaseStorageMimeTypeError';
+    Object.setPrototypeOf(this, KoolbaseStorageMimeTypeError.prototype);
+  }
+}
+
 /**
  * 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 function koolbaseStorageError(
   status: number,
@@ -114,12 +174,22 @@ export function koolbaseStorageError(
   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: