@koolbase/react-native 9.0.0

package/dist/messaging.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseMessaging = void 0;
+// ─── KoolbaseMessaging ────────────────────────────────────────────────────────
+class KoolbaseMessaging {
+    constructor(config) {
+        this.deviceId = '';
+        this.config = config;
+    }
+    setDeviceId(deviceId) {
+        this.deviceId = deviceId;
+    }
+    // ─── Register token ───────────────────────────────────────────────────────
+    async registerToken(options) {
+        try {
+            const response = await fetch(`${this.config.baseUrl}/v1/messaging/register`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.publicKey,
+                },
+                body: JSON.stringify({
+                    device_id: this.deviceId,
+                    token: options.token,
+                    platform: options.platform,
+                    ...(options.userId && { user_id: options.userId }),
+                }),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ─── Send notification ────────────────────────────────────────────────────
+    async send(options) {
+        try {
+            const response = await fetch(`${this.config.baseUrl}/v1/messaging/send`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.publicKey,
+                },
+                body: JSON.stringify({
+                    token: options.to,
+                    title: options.title,
+                    body: options.body,
+                    data: options.data ?? {},
+                }),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.KoolbaseMessaging = KoolbaseMessaging;

package/dist/realtime.d.ts

@@ -0,0 +1,19 @@
+import { KoolbaseConfig, RealtimeCallback } from './types';
+type TokenProvider = () => Promise<string | null>;
+export declare class KoolbaseRealtime {
+    private config;
+    private getToken;
+    private ws;
+    private projectId;
+    private listeners;
+    private reconnectTimer;
+    private connecting;
+    constructor(config: KoolbaseConfig, getToken: TokenProvider);
+    subscribe(collection: string, callback: RealtimeCallback): () => void;
+    private connect;
+    private sendSubscribe;
+    private sendUnsubscribe;
+    private scheduleReconnect;
+    disconnect(): void;
+}
+export {};

package/dist/realtime.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseRealtime = void 0;
+const record_1 = require("./record");
+const EVENT_TYPE_MAP = {
+    'db.record.created': 'created',
+    'db.record.updated': 'updated',
+    'db.record.deleted': 'deleted',
+};
+function projectIdFromToken(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            return null;
+        const b64 = part.replace(/-/g, '+').replace(/_/g, '/');
+        const g = globalThis;
+        let json;
+        if (typeof g.atob === 'function') {
+            const bin = g.atob(b64);
+            json = decodeURIComponent(bin.split('').map((c) => '%' + c.charCodeAt(0).toString(16).padStart(2, '0')).join(''));
+        }
+        else if (g.Buffer) {
+            json = g.Buffer.from(b64, 'base64').toString('utf8');
+        }
+        else {
+            return null;
+        }
+        return JSON.parse(json).project_id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+class KoolbaseRealtime {
+    constructor(config, getToken) {
+        this.ws = null;
+        this.projectId = null;
+        this.listeners = new Map();
+        this.reconnectTimer = null;
+        this.connecting = false;
+        this.config = config;
+        this.getToken = getToken;
+    }
+    subscribe(collection, callback) {
+        if (!this.listeners.has(collection))
+            this.listeners.set(collection, []);
+        this.listeners.get(collection).push(callback);
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.sendSubscribe(collection);
+        }
+        else {
+            void this.connect();
+        }
+        return () => {
+            const callbacks = this.listeners.get(collection) ?? [];
+            const i = callbacks.indexOf(callback);
+            if (i > -1)
+                callbacks.splice(i, 1);
+            if (callbacks.length === 0) {
+                this.listeners.delete(collection);
+                this.sendUnsubscribe(collection);
+            }
+        };
+    }
+    async connect() {
+        if (this.connecting)
+            return;
+        if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING))
+            return;
+        const token = await this.getToken();
+        if (!token) {
+            this.scheduleReconnect(); // sign-in may be in flight
+            return;
+        }
+        this.projectId = projectIdFromToken(token);
+        this.connecting = true;
+        const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
+        const ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+        this.ws = ws;
+        ws.onopen = () => {
+            this.connecting = false;
+            for (const collection of this.listeners.keys())
+                this.sendSubscribe(collection); // (re)subscribe all
+        };
+        ws.onmessage = (event) => {
+            let raw;
+            try {
+                raw = JSON.parse(event.data);
+            }
+            catch {
+                return;
+            }
+            const mapped = EVENT_TYPE_MAP[raw?.type];
+            if (!mapped)
+                return; // ignore subscribed / unsubscribed / error / unknown
+            const payload = raw.payload;
+            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 = () => {
+            this.connecting = false;
+            if (this.ws === ws)
+                this.ws = null;
+            this.scheduleReconnect();
+        };
+        ws.onerror = () => { };
+    }
+    sendSubscribe(collection) {
+        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+    }
+    sendUnsubscribe(collection) {
+        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+    }
+    scheduleReconnect() {
+        if (this.listeners.size === 0 || this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.connect();
+        }, 3000);
+    }
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.ws?.close();
+        this.ws = null;
+        this.projectId = null;
+        this.listeners.clear();
+    }
+}
+exports.KoolbaseRealtime = KoolbaseRealtime;

package/dist/record.d.ts

@@ -0,0 +1,2 @@
+import { KoolbaseRecord } from './types';
+export declare function recordFromWire(raw: Record<string, unknown>): KoolbaseRecord;

package/dist/record.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordFromWire = recordFromWire;
+// Converts the flat public wire shape into a KoolbaseRecord.
+// Server sends: { $id, $createdAt, $updatedAt, $collection, $createdBy?, ...fields }
+function recordFromWire(raw) {
+    const data = {};
+    for (const key of Object.keys(raw)) {
+        if (!key.startsWith('$'))
+            data[key] = raw[key];
+    }
+    return {
+        id: raw['$id'],
+        collection: raw['$collection'],
+        createdBy: raw['$createdBy'],
+        data,
+        createdAt: raw['$createdAt'],
+        updatedAt: raw['$updatedAt'],
+    };
+}

package/dist/storage-errors.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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);
+}
+/**
+ * Thrown when an object metadata payload (either at upload-confirm time
+ * or via `updateMetadata`) fails server-side validation — the server
+ * responds with 400 and code `metadata_invalid`.
+ *
+ * The `detail` field carries the specific reason from the server — e.g.
+ * `'key "foo bar": must match [a-z0-9_]+'`, `'exceeds 50 keys (got 53)'`,
+ * or `'exceeds 8192 bytes total (sum of all key + value lengths)'`. The
+ * detail names the failing key and rule so callers can fix the offending
+ * entry without guessing what shape rule was violated.
+ *
+ * Validation rules (enforced server-side):
+ * - At most 50 keys per object.
+ * - At most 8KB total (sum of byte lengths across all keys + values).
+ * - Keys: 1–64 chars, must match `[a-z0-9_]+`.
+ * - Keys with a leading underscore are reserved for system use.
+ * - Values: at most 1024 chars each.
+ *
+ * @example
+ * try {
+ *   await Koolbase.storage.updateMetadata('photos', 'sunset.jpg', {
+ *     tag: 'sunset',
+ *     'BAD KEY': 'oops',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseStorageMetadataInvalidError) {
+ *     console.warn('Metadata rejected:', e.detail);
+ *     // -> 'Metadata rejected: key "BAD KEY": must match [a-z0-9_]+'
+ *   }
+ * }
+ */
+export declare class KoolbaseStorageMetadataInvalidError extends KoolbaseStorageError {
+    /**
+     * The specific validation failure reported by the server. Names the
+     * failing key (when applicable) and the rule that was violated.
+     * Surface this directly to developer logs or user-facing UI.
+     */
+    detail?: string;
+    constructor(message?: string, detail?: string);
+}
+/**
+ * Maps a non-2xx storage-layer response to a typed
+ * {@link KoolbaseStorageError}, preferring the server's stable `code` and
+ * 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,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
+exports.koolbaseStorageError = koolbaseStorageError;
+exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
+/**
+ * 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;
+/**
+ * Thrown when an object metadata payload (either at upload-confirm time
+ * or via `updateMetadata`) fails server-side validation — the server
+ * responds with 400 and code `metadata_invalid`.
+ *
+ * The `detail` field carries the specific reason from the server — e.g.
+ * `'key "foo bar": must match [a-z0-9_]+'`, `'exceeds 50 keys (got 53)'`,
+ * or `'exceeds 8192 bytes total (sum of all key + value lengths)'`. The
+ * detail names the failing key and rule so callers can fix the offending
+ * entry without guessing what shape rule was violated.
+ *
+ * Validation rules (enforced server-side):
+ * - At most 50 keys per object.
+ * - At most 8KB total (sum of byte lengths across all keys + values).
+ * - Keys: 1–64 chars, must match `[a-z0-9_]+`.
+ * - Keys with a leading underscore are reserved for system use.
+ * - Values: at most 1024 chars each.
+ *
+ * @example
+ * try {
+ *   await Koolbase.storage.updateMetadata('photos', 'sunset.jpg', {
+ *     tag: 'sunset',
+ *     'BAD KEY': 'oops',
+ *   });
+ * } catch (e) {
+ *   if (e instanceof KoolbaseStorageMetadataInvalidError) {
+ *     console.warn('Metadata rejected:', e.detail);
+ *     // -> 'Metadata rejected: key "BAD KEY": must match [a-z0-9_]+'
+ *   }
+ * }
+ */
+class KoolbaseStorageMetadataInvalidError extends KoolbaseStorageError {
+    constructor(message, detail) {
+        super(message ?? 'Metadata payload is invalid', 'metadata_invalid');
+        this.detail = detail;
+        this.name = 'KoolbaseStorageMetadataInvalidError';
+        Object.setPrototypeOf(this, KoolbaseStorageMetadataInvalidError.prototype);
+    }
+}
+exports.KoolbaseStorageMetadataInvalidError = KoolbaseStorageMetadataInvalidError;
+/**
+ * Maps a non-2xx storage-layer response to a typed
+ * {@link KoolbaseStorageError}, preferring the server's stable `code` and
+ * 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);
+        case 'metadata_invalid':
+            return new KoolbaseStorageMetadataInvalidError(message, body?.detail);
+    }
+    // ─── 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);
+}