@koolbase/core 10.0.0

package/dist/esm/realtime.js

@@ -0,0 +1,191 @@
+import { cacheRecord, removeCachedRecord } from './cache-store.js';
+import { recordFromWire } from './record.js';
+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;
+    }
+}
+export class KoolbaseRealtime {
+    constructor(config, getToken, getUserId) {
+        this.ws = null;
+        this.projectId = null;
+        this.listeners = new Map();
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.connecting = false;
+        this.config = config;
+        this.getToken = getToken;
+        this.getUserId = getUserId;
+    }
+    /** Files a record seen over the socket, if we know whose it is. */
+    async cacheSeenRecord(collection, record) {
+        const userId = this.getUserId?.();
+        if (!userId)
+            return;
+        await cacheRecord(userId, collection, record.id, record.data, record.revision);
+    }
+    async forgetSeenRecord(recordId) {
+        const userId = this.getUserId?.();
+        if (!userId)
+            return;
+        await removeCachedRecord(userId, recordId);
+    }
+    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;
+            // A connection that opened is the only proof the endpoint and the
+            // credentials are usable, so the backoff resets here rather than on a
+            // close — a flaky link should not accumulate delay.
+            this.reconnectAttempts = 0;
+            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 };
+                // Gone for everyone, so the cached copy is no longer a baseline for
+                // anything. An edit composed against it would be refused at replay
+                // regardless; removing it makes that a local refusal rather than a
+                // round trip.
+                void this.forgetSeenRecord(payload.record_id);
+            }
+            else if (payload.record) {
+                const record = recordFromWire(payload.record);
+                msg = { type: mapped, collection: payload.collection, record };
+                // A record seen over the socket is as freshly seen as one fetched, and
+                // a client watching a collection would otherwise hold a stale baseline
+                // while looking at the change. Writes already queued are unaffected:
+                // their baseline was copied in when they were made, so this cannot move
+                // ground beneath them.
+                void this.cacheSeenRecord(payload.collection, 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 }));
+    }
+    /**
+     * Reconnects with backoff, rather than every three seconds forever.
+     *
+     * A fixed interval is fine while a connection is merely interrupted and
+     * costly when it is not: a device with no network, a wrong URL, or a session
+     * the server will not accept retried indefinitely, draining battery and data
+     * the user cannot see or stop.
+     *
+     * Doubling from three seconds to a minute keeps a brief interruption
+     * recovering quickly while a lasting one settles into an interval that costs
+     * almost nothing. The counter resets when a connection opens, so a flaky link
+     * does not accumulate delay.
+     */
+    scheduleReconnect() {
+        if (this.listeners.size === 0 || this.reconnectTimer)
+            return;
+        const delay = Math.min(3000 * Math.pow(2, this.reconnectAttempts), 60000);
+        this.reconnectAttempts += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.connect();
+        }, delay);
+    }
+    disconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.ws?.close();
+        this.ws = null;
+        this.projectId = null;
+        this.listeners.clear();
+    }
+}

package/dist/esm/record.d.ts

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

package/dist/esm/record.js

@@ -0,0 +1,20 @@
+// Converts the flat public wire shape into a KoolbaseRecord.
+// Server sends: { $id, $createdAt, $updatedAt, $collection, $createdBy?, ...fields }
+export 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'],
+        revision: typeof raw['$revision'] === 'number'
+            ? raw['$revision']
+            : undefined,
+    };
+}

package/dist/esm/shared.d.ts

@@ -0,0 +1,9 @@
+interface Slot {
+    platform?: unknown;
+    locks?: Map<string, Promise<unknown>>;
+}
+/** Read a shared value, initialising it on first use. */
+export declare function shared<K extends keyof Slot>(key: K, create: () => NonNullable<Slot[K]>): NonNullable<Slot[K]>;
+/** Replace a shared value. */
+export declare function setShared<K extends keyof Slot>(key: K, value: Slot[K]): void;
+export {};

package/dist/esm/shared.js

@@ -0,0 +1,39 @@
+// State that must be singular, even when this package is loaded twice.
+//
+// A dual-published package can end up in one application twice: the app's own
+// code resolves the ESM build while a dependency resolves the CommonJS one.
+// Module-level variables are then duplicated, and anything that assumes it is
+// the only copy quietly stops being true.
+//
+// Two things here cannot tolerate that:
+//
+//   - the platform adapter, which a platform package installs once at
+//     initialize. A second copy would keep the in-memory default, so sessions
+//     would not persist and the offline queue would read empty.
+//
+//   - the offline-state lock table, which serialises read-modify-write on one
+//     storage key per user. A second copy means two chains over the same key:
+//     a queued write or a conflict can be lost. That is data, not a feature.
+//
+// Both live on a well-known globalThis key instead, so every copy of the
+// module shares one instance. Keyed by a symbol registered in the global
+// symbol registry, which is the same symbol across module instances and
+// cannot collide with an application's own globals.
+const SLOT = Symbol.for('koolbase.sdk.shared.v1');
+function slot() {
+    const g = globalThis;
+    if (!g[SLOT])
+        g[SLOT] = {};
+    return g[SLOT];
+}
+/** Read a shared value, initialising it on first use. */
+export function shared(key, create) {
+    const s = slot();
+    if (s[key] === undefined)
+        s[key] = create();
+    return s[key];
+}
+/** Replace a shared value. */
+export function setShared(key, value) {
+    slot()[key] = value;
+}

package/dist/esm/storage-errors.d.ts

@@ -0,0 +1,163 @@
+import { KoolbaseError } from './errors.js';
+/**
+ * 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 KoolbaseError {
+    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/esm/storage-errors.js

@@ -0,0 +1,239 @@
+import { KoolbaseError, KoolbaseUnauthenticatedError } from './errors.js';
+/**
+ * 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 class KoolbaseStorageError extends KoolbaseError {
+    constructor(message, code) {
+        super(message, code);
+        this.name = 'KoolbaseStorageError';
+        Object.setPrototypeOf(this, KoolbaseStorageError.prototype);
+    }
+}
+/**
+ * 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 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);
+    }
+}
+/**
+ * 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 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);
+    }
+}
+/**
+ * Thrown when the request is rejected as invalid — the server responds
+ * with 400 (e.g. a malformed path, missing field, invalid bucket name).
+ */
+export class KoolbaseStorageValidationError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The storage request was invalid', 'validation_error');
+        this.name = 'KoolbaseStorageValidationError';
+        Object.setPrototypeOf(this, KoolbaseStorageValidationError.prototype);
+    }
+}
+/**
+ * Thrown when the caller is authenticated but not allowed to perform the
+ * storage operation — the server responds with 403.
+ */
+export 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);
+    }
+}
+/**
+ * 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) {
+        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) {
+        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) {
+        super(message ?? 'Content-type not allowed for this bucket', 'mime_not_allowed');
+        this.name = 'KoolbaseStorageMimeTypeError';
+        Object.setPrototypeOf(this, KoolbaseStorageMimeTypeError.prototype);
+    }
+}
+/**
+ * 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 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);
+    }
+}
+/**
+ * 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, 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 401:
+            // A rejected credential is not a storage problem: a session stops
+            // working for the whole SDK at once, so it raises the shared type.
+            return new KoolbaseUnauthenticatedError(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`.
+ */
+export 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);
+}