@techfinityedge/koolbase-react-native 3.1.0 → 4.2.0

package/README.md

@@ -257,6 +257,28 @@ const results = await Koolbase.db.batch([
 
 ---
 
+### Handling write conflicts
+
+`insert`, `update`, and `upsert` are online-first: when the server is reachable they throw a typed error on rejection. Catch `KoolbaseConflictError` to handle unique-constraint violations (e.g. a duplicate email):
+
+```ts
+import { KoolbaseConflictError } from '@techfinityedge/koolbase-react-native';
+
+try {
+  await Koolbase.db.insert('users', { email, name });
+} catch (e) {
+  if (e instanceof KoolbaseConflictError) {
+    showError(`That ${e.field ?? 'value'} is already in use.`);
+  } else {
+    throw e;
+  }
+}
+```
+
+When the device is offline, these writes are queued and synced automatically when connectivity returns.
+
+---
+
 ## Storage
 
 ```typescript
@@ -275,15 +297,27 @@ await Koolbase.storage.delete('avatars', `user-${userId}.jpg`);
 
 ## Realtime
 
-```typescript
+Subscribe to live changes on a collection. Realtime uses the signed-in user's
+session, so subscribe after login. It streams `created` and `updated` events for
+collections whose read rule is `public` or `authenticated`.
+
+```ts
+import { Koolbase } from '@techfinityedge/koolbase-react-native';
+
 const unsubscribe = Koolbase.realtime.subscribe('messages', (event) => {
-  if (event.type === 'created') setMessages(prev => [event.record, ...prev]);
+  // event.type       -> 'created' | 'updated'
+  // event.collection -> 'messages'
+  // event.record     -> KoolbaseRecord
+  console.log(event.type, event.record.data);
 });
 
-// Cleanup
-unsubscribe();
+unsubscribe(); // stop listening
 ```
 
+The socket opens lazily on first `subscribe`, is shared across all subscriptions,
+and reconnects automatically. The project is taken from the user's session — you
+don't pass it.
+
 ---
 
 ## Functions

package/dist/database-errors.d.ts

@@ -20,10 +20,11 @@ export declare class KoolbaseDataError extends Error {
  * (`details.field`) — useful when a collection has more than one unique
  * constraint and you need to know which value clashed.
  *
- * Currently surfaced by `upsert` (the online-only write). `insert` and
- * `update` are optimistic/offline-first: they accept the write locally and
- * sync in the background, so a constraint conflict on those paths is a
- * sync-time concern rather than a thrown error.
+ * Surfaced by `insert`, `update`, and `upsert` whenever the server is
+ * reachable and rejects the write with a 409. These writes are online-first:
+ * a server-side conflict throws immediately. Only a genuine network failure
+ * falls back to the offline queue, where a conflict that surfaces at sync
+ * time is handled by the sync engine rather than thrown here.
  *
  * @example
  * try {

package/dist/database-errors.js

@@ -29,10 +29,11 @@ exports.KoolbaseDataError = KoolbaseDataError;
  * (`details.field`) — useful when a collection has more than one unique
  * constraint and you need to know which value clashed.
  *
- * Currently surfaced by `upsert` (the online-only write). `insert` and
- * `update` are optimistic/offline-first: they accept the write locally and
- * sync in the background, so a constraint conflict on those paths is a
- * sync-time concern rather than a thrown error.
+ * Surfaced by `insert`, `update`, and `upsert` whenever the server is
+ * reachable and rejects the write with a 409. These writes are online-first:
+ * a server-side conflict throws immediately. Only a genuine network failure
+ * falls back to the offline queue, where a conflict that surfaces at sync
+ * time is handled by the sync engine rather than thrown here.
  *
  * @example
  * try {

package/dist/database.d.ts

@@ -9,6 +9,18 @@ export declare class KoolbaseDatabase {
     private request;
     private runQuery;
     query(collection: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Insert a new record into a collection.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, validation error, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass — `insert` now throws `KoolbaseConflictError`
+     * with the offending field on a 409, matching `upsert` and `update`.
+     *
+     * On genuine network failure (server unreachable, timeout) the write is
+     * accepted optimistically: saved to the local cache and queued for sync
+     * when connectivity returns.
+     */
     insert(collection: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     /**
      * Insert a record, or update the existing one matching `match`.
@@ -63,6 +75,19 @@ export declare class KoolbaseDatabase {
      */
     batch(operations: BatchOp[]): Promise<BatchResult[]>;
     get(recordId: string): Promise<KoolbaseRecord>;
+    /**
+     * Update a record's fields by id.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, not found, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass. An update that would violate a unique
+     * constraint now throws `KoolbaseConflictError` with the offending field —
+     * same shape as `insert` and `upsert`.
+     *
+     * On genuine network failure the update is queued for sync and a partial
+     * optimistic record is returned so the UI can re-render the new fields
+     * immediately.
+     */
     update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     delete(recordId: string): Promise<void>;
     syncPendingWrites(): Promise<void>;

package/dist/database.js

@@ -84,39 +84,56 @@ class KoolbaseDatabase {
         await (0, cache_store_1.setCached)(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
-    // ─── Insert (optimistic) ────────────────────────────────────────────────────
+    // ─── Insert (online-first with offline fallback) ───────────────────────────
+    /**
+     * Insert a new record into a collection.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, validation error, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass — `insert` now throws `KoolbaseConflictError`
+     * with the offending field on a 409, matching `upsert` and `update`.
+     *
+     * On genuine network failure (server unreachable, timeout) the write is
+     * accepted optimistically: saved to the local cache and queued for sync
+     * when connectivity returns.
+     */
     async insert(collection, data) {
         const userId = this.getUserId() ?? 'anonymous';
-        // Build optimistic record
-        const optimisticRecord = {
-            id: generateId(),
-            createdBy: userId,
-            data,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-        };
-        // Write to local cache immediately
-        await (0, cache_store_1.optimisticallyInsert)(userId, collection, optimisticRecord);
-        // Add to write queue
-        await (0, cache_store_1.addToWriteQueue)(userId, {
-            id: generateId(),
-            type: 'insert',
-            collection,
-            data,
-        });
-        // Try network in background
-        this.request('POST', '/v1/sdk/db/insert', {
-            collection,
-            data,
-        })
-            .then(async (serverRecord) => {
-            // Invalidate cache so next query gets real data
+        try {
+            // Online path: await the server and return the authoritative record
+            // (with the server-assigned id). Refresh the collection cache so the
+            // next query sees real data instead of a stale optimistic copy.
+            const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
+            const record = (0, record_1.recordFromWire)(raw);
             await (0, cache_store_1.invalidateCache)(userId, collection);
-        })
-            .catch(() => {
-            // Will sync when online via SyncEngine
-        });
-        return optimisticRecord;
+            return record;
+        }
+        catch (e) {
+            // Server-reachable rejection: the server saw the request and refused.
+            // Surface to the caller without writing optimistic state or queuing —
+            // the server has already decided it will not accept this write, and
+            // queuing it would just spin SyncEngine until max retries.
+            if (e instanceof database_errors_1.KoolbaseDataError)
+                throw e;
+            // Genuine network failure → offline path: save to local cache and
+            // queue for SyncEngine to retry when online. Return the optimistic
+            // record so the UI has something to render in the meantime.
+            const optimisticRecord = {
+                id: generateId(),
+                createdBy: userId,
+                data,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            };
+            await (0, cache_store_1.optimisticallyInsert)(userId, collection, optimisticRecord);
+            await (0, cache_store_1.addToWriteQueue)(userId, {
+                id: generateId(),
+                type: 'insert',
+                collection,
+                data,
+            });
+            return optimisticRecord;
+        }
     }
     // ─── Upsert (online-only) ─────────────────────────────────────────────────
     /**
@@ -246,20 +263,39 @@ class KoolbaseDatabase {
         const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);
         return (0, record_1.recordFromWire)(raw);
     }
-    // ─── Update ─────────────────────────────────────────────────────────────────
+    // ─── Update (online-first with offline fallback) ───────────────────────────
+    /**
+     * Update a record's fields by id.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, not found, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass. An update that would violate a unique
+     * constraint now throws `KoolbaseConflictError` with the offending field —
+     * same shape as `insert` and `upsert`.
+     *
+     * On genuine network failure the update is queued for sync and a partial
+     * optimistic record is returned so the UI can re-render the new fields
+     * immediately.
+     */
     async update(recordId, data) {
         const userId = this.getUserId() ?? 'anonymous';
-        await (0, cache_store_1.addToWriteQueue)(userId, {
-            id: generateId(),
-            type: 'update',
-            recordId,
-            data,
-        });
         try {
             const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
             return (0, record_1.recordFromWire)(raw);
         }
-        catch {
+        catch (e) {
+            // Server-reachable rejection: surface to caller without queuing — the
+            // server already refused the write and will refuse it again on retry.
+            if (e instanceof database_errors_1.KoolbaseDataError)
+                throw e;
+            // Genuine network failure → queue for sync and return an optimistic
+            // partial record so the UI reflects the update immediately.
+            await (0, cache_store_1.addToWriteQueue)(userId, {
+                id: generateId(),
+                type: 'update',
+                recordId,
+                data,
+            });
             return {
                 id: recordId,
                 data,

package/dist/index.js

@@ -69,7 +69,7 @@ exports.Koolbase = {
         _auth = new auth_1.KoolbaseAuth(config);
         _db = new database_1.KoolbaseDatabase(config, () => _auth?.currentUser?.id ?? null, () => _auth?.validAccessToken() ?? Promise.resolve(null));
         _storage = new storage_1.KoolbaseStorage(config, () => _auth?.validAccessToken() ?? Promise.resolve(null));
-        _realtime = new realtime_1.KoolbaseRealtime(config);
+        _realtime = new realtime_1.KoolbaseRealtime(config, () => _auth?.validAccessToken() ?? Promise.resolve(null));
         _functions = new functions_1.KoolbaseFunctions(config, () => _auth?.validAccessToken() ?? Promise.resolve(null));
         _flags = new flags_1.KoolbaseFlags(config, 'rn-device');
         _codePush = new code_push_1.KoolbaseCodePush(config, config.codePushChannel ?? 'stable');

package/dist/realtime.d.ts

@@ -1,11 +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;
-    constructor(config: KoolbaseConfig);
+    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

@@ -2,58 +2,141 @@
 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) {
+    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)) {
+        if (!this.listeners.has(collection))
             this.listeners.set(collection, []);
-        }
         this.listeners.get(collection).push(callback);
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-            this.connect();
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.sendSubscribe(collection);
+        }
+        else {
+            void this.connect();
         }
-        // Return unsubscribe function
         return () => {
             const callbacks = this.listeners.get(collection) ?? [];
-            const index = callbacks.indexOf(callback);
-            if (index > -1)
-                callbacks.splice(index, 1);
+            const i = callbacks.indexOf(callback);
+            if (i > -1)
+                callbacks.splice(i, 1);
+            if (callbacks.length === 0) {
+                this.listeners.delete(collection);
+                this.sendUnsubscribe(collection);
+            }
         };
     }
-    connect() {
-        const wsUrl = this.config.baseUrl
-            .replace('https://', 'wss://')
-            .replace('http://', 'ws://');
-        this.ws = new WebSocket(`${wsUrl}/v1/sdk/realtime?key=${this.config.publicKey}`);
-        this.ws.onmessage = (event) => {
+    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 {
-                const raw = JSON.parse(event.data);
-                if (!raw || !raw.record)
-                    return;
-                const msg = {
-                    type: raw.type,
-                    collection: raw.collection,
-                    record: (0, record_1.recordFromWire)(raw.record),
-                };
-                const callbacks = this.listeners.get(msg.collection) ?? [];
-                callbacks.forEach((cb) => cb(msg));
+                raw = JSON.parse(event.data);
+            }
+            catch {
+                return;
             }
-            catch (_) { }
+            const mapped = EVENT_TYPE_MAP[raw?.type];
+            if (!mapped)
+                return; // ignore subscribed / unsubscribed / error / unknown
+            const payload = raw.payload;
+            if (!payload || !payload.collection || !payload.record)
+                return; // created/updated carry a record
+            const msg = {
+                type: mapped,
+                collection: payload.collection,
+                record: (0, record_1.recordFromWire)(payload.record),
+            };
+            (this.listeners.get(payload.collection) ?? []).forEach((cb) => cb(msg));
         };
-        this.ws.onclose = () => {
-            this.reconnectTimer = setTimeout(() => this.connect(), 3000);
+        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)
+        if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
         this.ws?.close();
         this.ws = null;
+        this.projectId = null;
         this.listeners.clear();
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@techfinityedge/koolbase-react-native",
-  "version": "3.1.0",
-  "description": "React Native SDK for Koolbase \u2014 auth, database, storage, realtime, feature flags, and functions in one package.",
+  "version": "4.2.0",
+  "description": "React Native SDK for Koolbase — auth, database, storage, realtime, feature flags, and functions in one package.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [