@techfinityedge/koolbase-react-native 1.11.0 → 2.1.0

package/README.md

@@ -16,9 +16,9 @@ Auth, database, storage, realtime, functions, feature flags, remote config, vers
 3. Add the SDK:
 
 ```bash
-npm install @techfinityedge/koolbase-react-native@^1.10.0
+npm install @techfinityedge/koolbase-react-native@^2.0.0
 # or
-yarn add @techfinityedge/koolbase-react-native@^1.10.0
+yarn add @techfinityedge/koolbase-react-native@^2.0.0
 ```
 
 **4. Initialize at app startup:**
@@ -147,6 +147,11 @@ const { records } = await Koolbase.db.query('posts', {
   orderDesc: true,
 });
 
+// Read fields off a record
+const post = records[0];
+console.log(post.data.title);          // your fields live under .data
+console.log(post.id, post.collection); // metadata
+
 // Populate related records
 const { records: postsWithAuthor } = await Koolbase.db.query('posts', {
   populate: ['author_id:users'],
@@ -157,6 +162,38 @@ await Koolbase.db.update('record-id', { title: 'Updated' });
 await Koolbase.db.delete('record-id');
 ```
 
+### Upsert
+
+Insert a record, or update the existing one matching a filter.
+
+\`\`\`ts
+const result = await Koolbase.db.upsert(
+  'profiles',
+  { user_id: userId },
+  { weightKg: 70 }
+);
+
+console.log(result.created); // true if inserted, false if updated
+console.log(result.record.id);
+\`\`\`
+
+> Online-only: needs the server's view to decide insert vs update, so unlike
+> `insert` it isn't queued offline and throws on network failure.
+
+### Delete where
+
+Bulk-delete every record matching a filter. Returns the number deleted.
+
+\`\`\`ts
+const deleted = await Koolbase.db.deleteWhere('sessions', {
+  user_id: userId,
+  status: 'expired',
+});
+\`\`\`
+
+> A non-empty filter is required. The collection's delete rule applies; for
+> `owner`/`scoped` rules the delete is scoped to your own records. Online-only.
+
 ### Offline-first
 
 ```typescript

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult } from './types';
+import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult } from './types';
 export declare class KoolbaseDatabase {
     private config;
     private getUserId;
@@ -6,8 +6,37 @@ export declare class KoolbaseDatabase {
     constructor(config: KoolbaseConfig, getUserId: () => string | null);
     private get headers();
     private request;
+    private runQuery;
     query(collection: string, options?: QueryOptions): Promise<QueryResult>;
     insert(collection: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
+    /**
+     * Insert a record, or update the existing one matching `match`.
+     *
+     * The server decides: exactly one match updates it, no match inserts a new
+     * record (seeded with the `match` fields), more than one match is an error.
+     * Returns the resulting record and a `created` flag (true = inserted, false
+     * = updated).
+     *
+     * Online-only by design. Unlike `insert`, an upsert is NOT queued offline:
+     * the insert-vs-update decision needs the server's authoritative view of
+     * what already exists, so deferring it could create a duplicate or apply a
+     * wrong update on later sync. It throws on network failure instead. A raw
+     * fetch is used (not `request`) so the status code is readable: 201 =
+     * created, 200 = updated.
+     */
+    upsert(collection: string, match: Record<string, unknown>, data: Record<string, unknown>): Promise<UpsertResult>;
+    /**
+     * Bulk-delete every record in `collection` matching `filters`.
+     *
+     * The server applies the collection's delete rule (scoping to the caller for
+     * owner/scoped rules) and returns the number of records deleted.
+     *
+     * Online-only by design — like upsert, this is NOT queued offline: a bulk
+     * delete needs the server's authoritative view of what matches, so it throws
+     * on network failure rather than risk deleting the wrong set on later sync.
+     * The collection cache is invalidated on success.
+     */
+    deleteWhere(collection: string, filters: Record<string, unknown>): Promise<number>;
     get(recordId: string): Promise<KoolbaseRecord>;
     update(recordId: string, data: Record<string, unknown>): Promise<KoolbaseRecord>;
     delete(recordId: string): Promise<void>;

package/dist/database.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseDatabase = void 0;
 const cache_store_1 = require("./cache-store");
 const sync_engine_1 = require("./sync-engine");
+const record_1 = require("./record");
 function generateId() {
     return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
 }
@@ -34,13 +35,8 @@ class KoolbaseDatabase {
         return data;
     }
     // ─── Query (cache-first) ───────────────────────────────────────────────────
-    async query(collection, options = {}) {
-        const userId = this.getUserId() ?? 'anonymous';
-        const queryHash = (0, cache_store_1.hashQuery)(collection, options);
-        // 1. Return cached data immediately if available
-        const cached = await (0, cache_store_1.getCached)(userId, collection, queryHash);
-        // 2. Fetch from network in background
-        this.request('POST', '/v1/sdk/db/query', {
+    async runQuery(collection, options) {
+        const raw = await this.request('POST', '/v1/sdk/db/query', {
             collection,
             filters: options.filters ?? {},
             limit: options.limit ?? 20,
@@ -48,26 +44,22 @@ class KoolbaseDatabase {
             order_by: options.orderBy,
             order_desc: options.orderDesc ?? false,
             populate: options.populate ?? [],
-        })
-            .then(async (result) => {
-            await (0, cache_store_1.setCached)(userId, collection, queryHash, result);
-        })
+        });
+        return { records: raw.records.map(record_1.recordFromWire), total: raw.total };
+    }
+    async query(collection, options = {}) {
+        const userId = this.getUserId() ?? 'anonymous';
+        const queryHash = (0, cache_store_1.hashQuery)(collection, options);
+        const cached = await (0, cache_store_1.getCached)(userId, collection, queryHash);
+        this.runQuery(collection, options)
+            .then(result => (0, cache_store_1.setCached)(userId, collection, queryHash, result))
             .catch(() => {
-            // Network unavailable — cached data is already returned
+            // Network unavailable — cached data already returned
         });
         if (cached) {
             return { ...cached, isFromCache: true };
         }
-        // No cache — wait for network
-        const result = await this.request('POST', '/v1/sdk/db/query', {
-            collection,
-            filters: options.filters ?? {},
-            limit: options.limit ?? 20,
-            offset: options.offset ?? 0,
-            order_by: options.orderBy,
-            order_desc: options.orderDesc ?? false,
-            populate: options.populate ?? [],
-        });
+        const result = await this.runQuery(collection, options);
         await (0, cache_store_1.setCached)(userId, collection, queryHash, result);
         return { ...result, isFromCache: false };
     }
@@ -77,8 +69,6 @@ class KoolbaseDatabase {
         // Build optimistic record
         const optimisticRecord = {
             id: generateId(),
-            projectId: '',
-            collectionId: '',
             createdBy: userId,
             data,
             createdAt: new Date().toISOString(),
@@ -107,31 +97,86 @@ class KoolbaseDatabase {
         });
         return optimisticRecord;
     }
+    // ─── Upsert (online-only) ─────────────────────────────────────────────────
+    /**
+     * Insert a record, or update the existing one matching `match`.
+     *
+     * The server decides: exactly one match updates it, no match inserts a new
+     * record (seeded with the `match` fields), more than one match is an error.
+     * Returns the resulting record and a `created` flag (true = inserted, false
+     * = updated).
+     *
+     * Online-only by design. Unlike `insert`, an upsert is NOT queued offline:
+     * the insert-vs-update decision needs the server's authoritative view of
+     * what already exists, so deferring it could create a duplicate or apply a
+     * wrong update on later sync. It throws on network failure instead. A raw
+     * fetch is used (not `request`) so the status code is readable: 201 =
+     * created, 200 = updated.
+     */
+    async upsert(collection, match, data) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/upsert`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ collection, match, data }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw new Error(body.error ?? `Upsert failed: ${res.status}`);
+        }
+        const created = res.status === 201;
+        const record = (0, record_1.recordFromWire)(body);
+        // Keep the cache fresh, same intent as insert's post-success invalidate.
+        const userId = this.getUserId() ?? 'anonymous';
+        await (0, cache_store_1.invalidateCache)(userId, collection);
+        return { record, created };
+    }
+    // ─── Delete where (online-only) ─────────────────────────────────────────────
+    /**
+     * Bulk-delete every record in `collection` matching `filters`.
+     *
+     * The server applies the collection's delete rule (scoping to the caller for
+     * owner/scoped rules) and returns the number of records deleted.
+     *
+     * Online-only by design — like upsert, this is NOT queued offline: a bulk
+     * delete needs the server's authoritative view of what matches, so it throws
+     * on network failure rather than risk deleting the wrong set on later sync.
+     * The collection cache is invalidated on success.
+     */
+    async deleteWhere(collection, filters) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-where`, {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify({ collection, filters }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw new Error(body.error ?? `Delete failed: ${res.status}`);
+        }
+        const userId = this.getUserId() ?? 'anonymous';
+        await (0, cache_store_1.invalidateCache)(userId, collection);
+        return body.deleted ?? 0;
+    }
     // ─── Get single record ──────────────────────────────────────────────────────
     async get(recordId) {
-        return this.request('GET', `/v1/sdk/db/records/${recordId}`);
+        const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);
+        return (0, record_1.recordFromWire)(raw);
     }
     // ─── Update ─────────────────────────────────────────────────────────────────
     async update(recordId, data) {
         const userId = this.getUserId() ?? 'anonymous';
-        // Add to write queue
         await (0, cache_store_1.addToWriteQueue)(userId, {
             id: generateId(),
             type: 'update',
             recordId,
             data,
         });
-        // Try network
         try {
-            const result = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
-            return result;
+            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
+            return (0, record_1.recordFromWire)(raw);
         }
         catch {
-            // Return optimistic version
             return {
                 id: recordId,
-                projectId: '',
-                collectionId: '',
                 data,
                 createdAt: '',
                 updatedAt: new Date().toISOString(),

package/dist/realtime.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseRealtime = void 0;
+const record_1 = require("./record");
 class KoolbaseRealtime {
     constructor(config) {
         this.ws = null;
@@ -31,7 +32,14 @@ class KoolbaseRealtime {
         this.ws = new WebSocket(`${wsUrl}/v1/sdk/realtime?key=${this.config.publicKey}`);
         this.ws.onmessage = (event) => {
             try {
-                const msg = JSON.parse(event.data);
+                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));
             }

package/dist/record.d.ts

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

package/dist/record.js

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

package/dist/types.d.ts

@@ -111,8 +111,7 @@ export interface PhoneVerifyResult {
 }
 export interface KoolbaseRecord {
     id: string;
-    projectId: string;
-    collectionId: string;
+    collection?: string;
     createdBy?: string;
     data: Record<string, unknown>;
     createdAt: string;
@@ -131,6 +130,10 @@ export interface QueryResult {
     total: number;
     isFromCache?: boolean;
 }
+export interface UpsertResult {
+    record: KoolbaseRecord;
+    created: boolean;
+}
 export interface PendingWrite {
     id: string;
     type: 'insert' | 'update' | 'delete';

package/package.json

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