@koolbase/core 10.0.0

package/dist/cjs/platform.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoryPlatform = memoryPlatform;
+exports.setPlatform = setPlatform;
+exports.getPlatform = getPlatform;
+// Shared across module instances; see shared.ts for why.
+const shared_js_1 = require("./shared.js");
+/**
+ * An adapter that persists nothing beyond the process and reports the
+ * network as always up. The default until a platform sets its own — which
+ * makes tests run without a module mapper, and makes forgetting to call
+ * setPlatform an obvious failure (nothing survives a restart) rather than a
+ * crash.
+ */
+function memoryPlatform() {
+    const store = new Map();
+    return {
+        storage: {
+            getItem: async (k) => store.get(k) ?? null,
+            setItem: async (k, v) => { store.set(k, v); },
+            removeItem: async (k) => { store.delete(k); },
+            getAllKeys: async () => Array.from(store.keys()),
+        },
+        network: {
+            onChange: () => () => { },
+        },
+        lifecycle: {
+            onBackground: () => () => { },
+        },
+        info: { os: 'memory', version: '' },
+        authStorage: () => null,
+    };
+}
+/** Install the host platform. Called once by the platform package's initialize. */
+function setPlatform(adapter) {
+    (0, shared_js_1.setShared)('platform', adapter);
+}
+/** The installed platform. Always returns something; see memoryPlatform. */
+function getPlatform() {
+    return (0, shared_js_1.shared)('platform', memoryPlatform);
+}

package/dist/cjs/realtime.d.ts

@@ -0,0 +1,44 @@
+import { KoolbaseConfig, RealtimeCallback } from './types.js';
+type TokenProvider = () => Promise<string | null>;
+export declare class KoolbaseRealtime {
+    private config;
+    private getToken;
+    private ws;
+    private projectId;
+    private listeners;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private connecting;
+    /**
+     * Identifies whose cache a seen record belongs in.
+     *
+     * The record cache is keyed by user, so without this a watched record would
+     * be filed under the wrong key — or under 'anonymous', which is worse than
+     * not caching at all: a baseline stored where it will never be read.
+     */
+    private getUserId?;
+    constructor(config: KoolbaseConfig, getToken: TokenProvider, getUserId?: () => string | null);
+    /** Files a record seen over the socket, if we know whose it is. */
+    private cacheSeenRecord;
+    private forgetSeenRecord;
+    subscribe(collection: string, callback: RealtimeCallback): () => void;
+    private connect;
+    private sendSubscribe;
+    private sendUnsubscribe;
+    /**
+     * 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.
+     */
+    private scheduleReconnect;
+    disconnect(): void;
+}
+export {};

package/dist/cjs/realtime.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseRealtime = void 0;
+const cache_store_js_1 = require("./cache-store.js");
+const record_js_1 = require("./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;
+    }
+}
+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 (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
+    }
+    async forgetSeenRecord(recordId) {
+        const userId = this.getUserId?.();
+        if (!userId)
+            return;
+        await (0, cache_store_js_1.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 = (0, record_js_1.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();
+    }
+}
+exports.KoolbaseRealtime = KoolbaseRealtime;

package/dist/cjs/record.d.ts

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

package/dist/cjs/record.js

@@ -0,0 +1,23 @@
+"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'],
+        revision: typeof raw['$revision'] === 'number'
+            ? raw['$revision']
+            : undefined,
+    };
+}

package/dist/cjs/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/cjs/shared.js

@@ -0,0 +1,43 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shared = shared;
+exports.setShared = setShared;
+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. */
+function shared(key, create) {
+    const s = slot();
+    if (s[key] === undefined)
+        s[key] = create();
+    return s[key];
+}
+/** Replace a shared value. */
+function setShared(key, value) {
+    slot()[key] = value;
+}

package/dist/cjs/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>;