@koolbase/core 10.0.0

package/dist/esm/index.d.ts

@@ -0,0 +1,22 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './conflict.js';
+export * from './pending-write.js';
+export * from './function-errors.js';
+export * from './auth-errors.js';
+export * from './database-errors.js';
+export * from './storage-errors.js';
+export { KoolbaseAuth } from './auth.js';
+export { KoolbaseDatabase } from './database.js';
+export { KoolbaseFlags } from './flags.js';
+export { KoolbaseFunctions } from './functions.js';
+export { KoolbaseRealtime } from './realtime.js';
+export { KoolbaseStorage } from './storage.js';
+export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseMessaging } from './messaging.js';
+export type { RegisterTokenOptions } from './messaging.js';
+export { getOrCreateDeviceId } from './device-id.js';
+export { koolbaseSdkVersion } from './device-metadata.js';
+export { RestoreResult } from './types.js';
+export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
+export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformInfo, } from './platform.js';

package/dist/esm/index.js

@@ -0,0 +1,25 @@
+// @koolbase/core — the SDK's shared behaviour, with no host assumptions.
+//
+// A platform package (react-native, js) supplies a PlatformAdapter and an auth
+// storage, composes the clients, and re-exports this surface. Application
+// code installs the platform package, never this one directly.
+export * from './types.js';
+export * from './errors.js';
+export * from './conflict.js';
+export * from './pending-write.js';
+export * from './function-errors.js';
+export * from './auth-errors.js';
+export * from './database-errors.js';
+export * from './storage-errors.js';
+export { KoolbaseAuth } from './auth.js';
+export { KoolbaseDatabase } from './database.js';
+export { KoolbaseFlags } from './flags.js';
+export { KoolbaseFunctions } from './functions.js';
+export { KoolbaseRealtime } from './realtime.js';
+export { KoolbaseStorage } from './storage.js';
+export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseMessaging } from './messaging.js';
+export { getOrCreateDeviceId } from './device-id.js';
+export { koolbaseSdkVersion } from './device-metadata.js';
+export { RestoreResult } from './types.js';
+export { setPlatform, getPlatform, memoryPlatform, } from './platform.js';

package/dist/esm/messaging.d.ts

@@ -0,0 +1,13 @@
+import { KoolbaseConfig } from './types.js';
+export interface RegisterTokenOptions {
+    token: string;
+    platform: 'android' | 'ios';
+    userId?: string;
+}
+export declare class KoolbaseMessaging {
+    private config;
+    private deviceId;
+    constructor(config: KoolbaseConfig);
+    setDeviceId(deviceId: string): void;
+    registerToken(options: RegisterTokenOptions): Promise<boolean>;
+}

package/dist/esm/messaging.js

@@ -0,0 +1,32 @@
+// ─── KoolbaseMessaging ────────────────────────────────────────────────────────
+export 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;
+        }
+    }
+}

package/dist/esm/offline-state.d.ts

@@ -0,0 +1,97 @@
+export declare function recordKey(userId: string, collection: string, recordId: string): string;
+/** A write waiting to be sent. */
+export interface QueuedWrite {
+    id: string;
+    operation: 'insert' | 'update' | 'delete';
+    collection: string;
+    recordId?: string;
+    data?: Record<string, unknown>;
+    /**
+     * The record as the client last saw it, for update and delete.
+     *
+     * Copied in at enqueue time rather than looked up at replay: the record cache
+     * can be evicted or invalidated in between, and a write whose baseline
+     * depends on something else surviving is not durable. From here on the write
+     * is self-contained.
+     */
+    baseline?: Record<string, unknown>;
+    /** The revision that baseline carried, sent so the server can refuse atomically. */
+    baseRevision?: number;
+    retries: number;
+    enqueuedAt: string;
+}
+/**
+ * Why a write is waiting for a decision.
+ *
+ * Kept distinct because they are different situations and an app showing them
+ * to someone should say different things. One means two people changed the same
+ * thing; the other means we never knew what the change was based on, so there is
+ * nothing to compare it against.
+ */
+export type ConflictReason = 
+/** The record moved between the change being made and the queue reaching it. */
+'concurrent_modification'
+/**
+ * Queued by a version of this SDK that did not record what the change was
+ * composed against. It cannot be replayed safely — there is nothing to check
+ * it against — so it waits rather than overwriting whatever is there now.
+ */
+ | 'baseline_unavailable'
+/**
+ * The server refused the write for a reason retrying cannot change — the data
+ * no longer satisfies the collection's rules, the record is gone, the caller
+ * is not permitted, a unique value is taken.
+ *
+ * Held rather than retried or dropped. Retrying sends identical bytes to
+ * identical rules; dropping loses a change the user believes is saved. Neither
+ * tells them anything.
+ */
+ | 'rejected';
+/** A write the server would not apply, held until someone decides. */
+export interface QueuedConflict {
+    reason: ConflictReason;
+    id: string;
+    operation: 'insert' | 'update' | 'delete';
+    collection: string;
+    recordId: string;
+    local?: Record<string, unknown>;
+    baseline?: Record<string, unknown>;
+    server?: Record<string, unknown>;
+    baseRevision?: number;
+    serverRevision?: number;
+    /** What the server said, when it refused for a terminal reason. */
+    message?: string;
+    createdAt: string;
+}
+export interface OfflineState {
+    pending: QueuedWrite[];
+    conflicts: QueuedConflict[];
+}
+export declare class OfflineStateTooLargeError extends Error {
+    constructor(bytes: number);
+}
+export declare function readOfflineState(userId: string): Promise<OfflineState>;
+/**
+ * Reads, mutates, and writes the state under the user's lock.
+ *
+ * Every mutation goes through here. A caller that reads and writes separately
+ * reintroduces the race this exists to prevent.
+ */
+export declare function mutateOfflineState(userId: string, mutate: (state: OfflineState) => void): Promise<void>;
+/** Adds a write to the queue, under the user's lock. */
+export declare function queueWrite(userId: string, write: Omit<QueuedWrite, 'retries' | 'enqueuedAt'>): Promise<void>;
+/**
+ * Moves writes queued by an earlier version into the current state.
+ *
+ * Runs once, before any replay, and never contacts the network. Migration that
+ * depended on connectivity would give the same input two different outcomes
+ * depending on whether the device happened to be online at startup — which is
+ * how a bug becomes unreproducible.
+ *
+ * Inserts carry everything they need and simply move across. Updates and
+ * deletes do not: they were queued before baselines were recorded, so replaying
+ * one would apply it blindly and overwrite whatever changed in the meantime.
+ * They are preserved as waiting for a decision instead — the change is not lost,
+ * and nothing is written on a guess.
+ */
+export declare function migrateLegacyQueue(userId: string): Promise<void>;

package/dist/esm/offline-state.js

@@ -0,0 +1,189 @@
+import { getPlatform } from './platform.js';
+import { shared } from './shared.js';
+/**
+ * The offline system's correctness-critical state: writes waiting to be sent,
+ * and writes the server refused because the record moved underneath them.
+ *
+ * Both live under one key so moving between them is a single write. A conflict
+ * recorded without removing the pending write would replay and be refused
+ * forever; a pending write removed without recording the conflict would lose a
+ * change the user believes is saved. Two keys admit both outcomes.
+ *
+ * Records are cached separately, per record. Putting them here would let a
+ * growing cache push this value past a storage ceiling and make the queue
+ * unreadable — losing the correctness-critical state to something incidental.
+ */
+const VERSION = 'v1';
+function stateKey(userId) {
+    return `koolbase:${VERSION}:${userId}:offline-state`;
+}
+export function recordKey(userId, collection, recordId) {
+    return `koolbase:${VERSION}:${userId}:record:${collection}:${recordId}`;
+}
+const EMPTY = { pending: [], conflicts: [] };
+/**
+ * A conservative ceiling, below the lowest per-value limit any supported
+ * AsyncStorage implementation imposes.
+ *
+ * Not a claim about a platform maximum — a boundary that leaves headroom for
+ * rewriting and migration. A queue that cannot be written is a queue that
+ * silently stops accepting work, so the limit is enforced with an error rather
+ * than discovered.
+ */
+const MAX_STATE_BYTES = 1000000;
+export class OfflineStateTooLargeError extends Error {
+    constructor(bytes) {
+        super(`Offline state is ${bytes} bytes, above the ${MAX_STATE_BYTES} byte limit. ` +
+            'Sync or resolve what is queued before making more offline changes.');
+        this.name = 'OfflineStateTooLargeError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Serialises access per user.
+ *
+ * A single setItem is one storage operation, but read-modify-write is not: two
+ * callers can both read, both modify, and the second write silently discards
+ * the first. Two components queueing a write in the same tick is enough. The
+ * lock is in-process — one JavaScript runtime is the assumption every React
+ * Native app satisfies, and the SDK does not promise more.
+ */
+/** UTF-8 byte length, without depending on TextEncoder being present. */
+function byteLength(s) {
+    if (typeof TextEncoder !== 'undefined') {
+        return new TextEncoder().encode(s).length;
+    }
+    let bytes = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.codePointAt(i);
+        if (c > 0xffff)
+            i++; // surrogate pair, counted once
+        bytes += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4;
+    }
+    return bytes;
+}
+const locks = () => shared('locks', () => new Map());
+async function withLock(userId, fn) {
+    const previous = locks().get(userId) ?? Promise.resolve();
+    let release = () => { };
+    const next = new Promise((resolve) => { release = resolve; });
+    locks().set(userId, previous.then(() => next));
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (locks().get(userId) === next)
+            locks().delete(userId);
+    }
+}
+export async function readOfflineState(userId) {
+    try {
+        const raw = await getPlatform().storage.getItem(stateKey(userId));
+        if (!raw)
+            return { ...EMPTY, pending: [], conflicts: [] };
+        const parsed = JSON.parse(raw);
+        return { pending: parsed.pending ?? [], conflicts: parsed.conflicts ?? [] };
+    }
+    catch {
+        // Unreadable state is treated as empty rather than throwing: an app that
+        // cannot start is worse than one that has lost a queue it could not read
+        // anyway. The write path's size guard is what keeps this from happening.
+        return { pending: [], conflicts: [] };
+    }
+}
+/**
+ * Reads, mutates, and writes the state under the user's lock.
+ *
+ * Every mutation goes through here. A caller that reads and writes separately
+ * reintroduces the race this exists to prevent.
+ */
+export async function mutateOfflineState(userId, mutate) {
+    await withLock(userId, async () => {
+        const state = await readOfflineState(userId);
+        mutate(state);
+        const serialised = JSON.stringify(state);
+        // Bytes, not characters. String length undercounts anything outside ASCII —
+        // an accented name, any non-Latin script — so a limit measured in
+        // characters permits more than it claims, which is the wrong direction for
+        // a safety boundary. TextEncoder is not guaranteed in every React Native
+        // runtime, so fall back to a byte count computed directly.
+        const bytes = byteLength(serialised);
+        if (bytes > MAX_STATE_BYTES) {
+            throw new OfflineStateTooLargeError(bytes);
+        }
+        await getPlatform().storage.setItem(stateKey(userId), serialised);
+    });
+}
+/** Adds a write to the queue, under the user's lock. */
+export async function queueWrite(userId, write) {
+    await mutateOfflineState(userId, (state) => {
+        state.pending.push({
+            ...write,
+            retries: 0,
+            enqueuedAt: new Date().toISOString(),
+        });
+    });
+}
+const LEGACY_QUEUE_VERSION = 'v1';
+function legacyQueueKey(userId) {
+    return `koolbase:${LEGACY_QUEUE_VERSION}:${userId}:write_queue`;
+}
+/**
+ * Moves writes queued by an earlier version into the current state.
+ *
+ * Runs once, before any replay, and never contacts the network. Migration that
+ * depended on connectivity would give the same input two different outcomes
+ * depending on whether the device happened to be online at startup — which is
+ * how a bug becomes unreproducible.
+ *
+ * Inserts carry everything they need and simply move across. Updates and
+ * deletes do not: they were queued before baselines were recorded, so replaying
+ * one would apply it blindly and overwrite whatever changed in the meantime.
+ * They are preserved as waiting for a decision instead — the change is not lost,
+ * and nothing is written on a guess.
+ */
+export async function migrateLegacyQueue(userId) {
+    const raw = await getPlatform().storage.getItem(legacyQueueKey(userId));
+    if (!raw)
+        return;
+    let legacy = [];
+    try {
+        legacy = JSON.parse(raw);
+    }
+    catch {
+        // Unreadable: nothing recoverable, and leaving the key would retry forever.
+        await getPlatform().storage.removeItem(legacyQueueKey(userId));
+        return;
+    }
+    await mutateOfflineState(userId, (state) => {
+        for (const w of legacy) {
+            const operation = w.type;
+            if (operation === 'insert') {
+                state.pending.push({
+                    id: w.id,
+                    operation: 'insert',
+                    collection: w.collection,
+                    recordId: w.recordId,
+                    data: w.data,
+                    retries: w.retries ?? 0,
+                    enqueuedAt: w.createdAt ?? new Date().toISOString(),
+                });
+                continue;
+            }
+            if (!w.recordId)
+                continue;
+            state.conflicts.push({
+                id: w.id,
+                reason: 'baseline_unavailable',
+                operation,
+                collection: w.collection ?? '',
+                recordId: w.recordId,
+                local: w.data,
+                createdAt: w.createdAt ?? new Date().toISOString(),
+            });
+        }
+    });
+    await getPlatform().storage.removeItem(legacyQueueKey(userId));
+}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/pending-write.d.ts

@@ -0,0 +1,47 @@
+import { QueuedWrite } from './offline-state.js';
+/**
+ * A change made offline, waiting to be sent.
+ *
+ * The counterpart to KoolbaseConflict, one step earlier in the lifecycle: a
+ * conflict is a write the server refused; a pending write is one the server has
+ * not seen yet. Both are durable state an app should surface — a queue nobody
+ * can see accumulates invisibly, and the changes it holds feel saved to the
+ * user while existing only on this device.
+ *
+ * The case that makes this API matter: logout. Queues are per-user and survive
+ * logout by design, so a user signing out with pending writes walks away
+ * believing their edits saved — and they sync whenever that user next logs in
+ * on this device, which may be never. Warn before logout:
+ *
+ * ```ts
+ * const pending = await Koolbase.db.pendingWrites();
+ * if (pending.length > 0) {
+ *   // "You have 3 unsynced changes. Sync now, or they wait until you
+ *   //  next sign in on this device."
+ * }
+ * ```
+ *
+ * This is a snapshot, not a live handle — re-read after a sync. Per-user:
+ * another account's queue on this device is not visible here.
+ */
+export interface PendingWrite {
+    id: string;
+    operation: 'insert' | 'update' | 'delete';
+    collection: string;
+    /** Absent for an insert the server has not yet assigned. */
+    recordId?: string;
+    /** What the user changed. Absent for a delete. */
+    data?: Record<string, unknown>;
+    enqueuedAt: string;
+    /** Failed send attempts so far. A count, not a policy — nothing drops it. */
+    attempts: number;
+}
+/**
+ * Maps the stored write to its public shape, field by field.
+ *
+ * Deliberately not a spread: the stored write carries baseline and baseRevision
+ * — replay mechanics, not contract. A spread would leak whatever the storage
+ * shape grows next; naming each field means new internals stay internal until
+ * someone chooses otherwise.
+ */
+export declare function toPendingWrite(w: QueuedWrite): PendingWrite;

package/dist/esm/pending-write.js

@@ -0,0 +1,19 @@
+/**
+ * Maps the stored write to its public shape, field by field.
+ *
+ * Deliberately not a spread: the stored write carries baseline and baseRevision
+ * — replay mechanics, not contract. A spread would leak whatever the storage
+ * shape grows next; naming each field means new internals stay internal until
+ * someone chooses otherwise.
+ */
+export function toPendingWrite(w) {
+    return {
+        id: w.id,
+        operation: w.operation,
+        collection: w.collection,
+        recordId: w.recordId,
+        data: w.data,
+        enqueuedAt: w.enqueuedAt,
+        attempts: w.retries,
+    };
+}

package/dist/esm/platform.d.ts

@@ -0,0 +1,51 @@
+export interface PlatformStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<string[]>;
+}
+export interface PlatformNetwork {
+    /**
+     * Subscribe to connectivity changes. The callback receives true when the
+     * host believes it is online. Treated as a hint: the sync engine still
+     * discovers reachability by trying, and a host that reports online while
+     * Koolbase is unreachable is handled the same as any failed request.
+     */
+    onChange(callback: (online: boolean) => void): () => void;
+}
+export interface PlatformLifecycle {
+    /** Subscribe to the app moving to the background. Used to flush analytics. */
+    onBackground(callback: () => void): () => void;
+}
+export interface PlatformInfo {
+    /** e.g. 'ios', 'android', 'web' */
+    os: string;
+    /** OS or browser version, as a string; '' if unknown. */
+    version: string;
+}
+export interface PlatformAdapter {
+    storage: PlatformStorage;
+    network: PlatformNetwork;
+    lifecycle: PlatformLifecycle;
+    info: PlatformInfo;
+    /**
+     * The host's best persistent store for the auth session, or null if it has
+     * none worth the name. Used only when the app injects nothing through
+     * KoolbaseConfig.authStorage. React Native answers with the keychain when
+     * it is installed; a browser answers with IndexedDB and says so in its
+     * README, since nothing JavaScript can read is secure against XSS.
+     */
+    authStorage(): import('./types.js').KoolbaseAuthStorage | null;
+}
+/**
+ * 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.
+ */
+export declare function memoryPlatform(): PlatformAdapter;
+/** Install the host platform. Called once by the platform package's initialize. */
+export declare function setPlatform(adapter: PlatformAdapter): void;
+/** The installed platform. Always returns something; see memoryPlatform. */
+export declare function getPlatform(): PlatformAdapter;

package/dist/esm/platform.js

@@ -0,0 +1,36 @@
+// Shared across module instances; see shared.ts for why.
+import { shared, setShared } from './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.
+ */
+export 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. */
+export function setPlatform(adapter) {
+    setShared('platform', adapter);
+}
+/** The installed platform. Always returns something; see memoryPlatform. */
+export function getPlatform() {
+    return shared('platform', memoryPlatform);
+}

package/dist/esm/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 {};