nexabase-console 1.1.3 → 1.1.5

package/README.md

@@ -42,6 +42,21 @@ const app = initializeApp({
 const db = getFirestore(app);
 ```
 
+#### 🛡️ Keamanan & Autentikasi Ganda (API Key & Sesi)
+Untuk mendukung arsitektur server-side proxy atau direct API key yang sangat fleksibel, SDK secara otomatis mengirimkan token Anda dalam dua format header sekaligus:
+- **`Authorization: Bearer <token>`**: Digunakan untuk validasi token JWT sesi user.
+- **`x-api-key: <api_key>`**: Digunakan untuk otentikasi aman tanpa sesi menggunakan API Key proyek.
+
+Hal ini mencegah kegagalan otentikasi (Error `403 Forbidden: Please login`) saat memanggil metode di server menggunakan API Key proyek.
+
+#### ⚡ Sinkronisasi Offline & Database-Priority Engine (IndexedDB Cache)
+NexaBase SDK mengimplementasikan manajemen cache tangguh yang serupa dengan Firebase untuk menjamin keandalan aplikasi saat jaringan tidak stabil:
+1. **Prioritas Database Utama (`network-first` secara default)**: SDK memprioritaskan pengambilan data dari database remote server untuk menjamin kesegaran data (*data freshness*).
+2. **Fast-Fail Network Timeout**: Setiap permintaan database remote memiliki batas waktu (*timeout*) selama 6 detik. Jika jaringan sangat lambat (*lie-fi*) atau offline, SDK akan gagal cepat dan mengalihkan pembacaan ke **IndexedDB local cache** secara transparan tanpa menghentikan aplikasi.
+3. **Pembaruan Optimistik Instan**: Mutasi data (`setDoc`, `patchDoc`, `deleteDoc`, `writeBatch`) langsung ditulis ke IndexedDB secara optimistik. Semua listener snapshot (`onSnapshot`) akan menerima perubahan secara instan agar UI terasa sangat responsif (*snappy*).
+4. **Heartbeat Polling Outbox (Setiap 10 Detik)**: Di samping mendengarkan event transisi jaringan `online`, SDK menjalankan polling latar belakang setiap 10 detik. Jika koneksi terdeteksi pulih, SDK akan mem-flush antrean mutasi offline secara berurutan (FIFO).
+5. **Deduplikasi & Proteksi Kemacetan Antrean**: SDK menggunakan kunci idempotensi (`X-Idempotency-Key`) untuk mencegah tulisan ganda. Selain itu, jika server membalas dengan kesalahan definitif sisi klien (seperti `400 Bad Request` atau `403 Forbidden`), SDK akan secara otomatis membuang job cacat tersebut dari antrean untuk mencegah antrean macet selamanya.
+
 ---
 
 ### 2. Firestore-like Modular API (NoSQL)
@@ -242,6 +257,11 @@ const uploadImage = async (fileBlob) => {
 };
 ```
 
+#### 📂 Penanganan Tipe Konten Dinamis (Form Data Boundary)
+Unggahan file menggunakan format multipart standard yang dibungkus dalam objek `FormData`. SDK ini secara otomatis mendeteksi payload `FormData` dan membebaskan header `Content-Type` bawaan agar browser dapat secara dinamis menetapkan tipe konten yang menyertakan kode batas unik (*multipart boundary*). 
+
+Ini menghilangkan bug berkas kosong (`{}`) yang disebabkan oleh tumpang tindihnya header `application/json` di Axios.
+
 ---
 
 ### 5. Keamanan Tipe TypeScript (Generics) & Kueri Lanjutan

package/dist/index.js

@@ -38,7 +38,7 @@ class NexaApp {
         this.projectId = config.projectId;
         this.token = config.apiKey || null;
         this.enablePersistence = config.enablePersistence !== false;
-        this.cacheStrategy = config.cacheStrategy || 'cache-first';
+        this.cacheStrategy = config.cacheStrategy || 'network-first';
         if (typeof window !== 'undefined' && window.localStorage) {
             const savedToken = localStorage.getItem(`nexa_token_${this.projectId}`);
             if (savedToken) {
@@ -52,8 +52,10 @@ class NexaApp {
         }
         this.endpoint = config.endpoint || defaultEndpoint;
         // Do not set default Content-Type globally to let Axios auto-detect FormData
+        // Include 6000ms timeout for reliable fast failover fallback to local IndexedDB cache when network is slow
         this.client = axios_1.default.create({
-            baseURL: this.endpoint
+            baseURL: this.endpoint,
+            timeout: 6000
         });
         // Request interceptor to attach bearer/x-api-key token and boundary fix
         this.client.interceptors.request.use((req) => {
@@ -388,6 +390,12 @@ class NexaApp {
             if (typeof window !== 'undefined') {
                 window.addEventListener('online', () => this._syncOfflineQueue());
                 setTimeout(() => this._syncOfflineQueue(), 1000);
+                // Robust automatic heartbeat polling every 10 seconds to sync any pending queue jobs
+                setInterval(() => {
+                    if (typeof navigator !== 'undefined' && navigator.onLine) {
+                        this._syncOfflineQueue();
+                    }
+                }, 10000);
             }
         }
         catch (err) {
@@ -499,7 +507,14 @@ class NexaApp {
                 await this._saveOfflineQueue(currentQueue.filter((q) => q.id !== job.id));
             }
             catch (err) {
-                break; // Stop syncing on network exception
+                // Discard invalid/unauthorized client-side failures (4xx) to prevent clogging the queue
+                if (err && err.response && err.response.status >= 400 && err.response.status < 500) {
+                    console.error(`[NexaBase SDK] Discarding invalid offline job (${job.type} on ${job.path}):`, err.response.data);
+                    const currentQueue = await this._getOfflineQueue();
+                    await this._saveOfflineQueue(currentQueue.filter((q) => q.id !== job.id));
+                    continue; // Move on to next job
+                }
+                break; // Stop syncing on transient network exceptions or server 5xx errors to retry later
             }
         }
         this._isSyncing = false;
@@ -662,6 +677,25 @@ const getDocs = async (queryOrCollection) => {
         await db._initPromise;
     const collectionPath = queryOrCollection.path;
     const constraints = 'constraints' in queryOrCollection ? queryOrCollection.constraints || [] : [];
+    // If cache-first strategy, try loading from local cache first
+    if (db.cacheStrategy === 'cache-first') {
+        const cached = (0, exports.getCachedDocs)(queryOrCollection);
+        if (cached && !cached.empty) {
+            // Background-sync silently to update the local cache
+            db.client.post(`/api/firestore/${db.projectId}/query`, {
+                collectionPath,
+                constraints
+            }).then(async (res) => {
+                const docs = res.data.documents || [];
+                for (const d of docs) {
+                    await db._setCache(`${collectionPath}/${d.id}`, d.fields);
+                }
+                db._notifySnapshotCallbacks(collectionPath, 'bulk_update', null);
+            }).catch(() => { });
+            return cached;
+        }
+    }
+    // Network-first (or cache-first with empty cache): Prioritize the remote database
     try {
         const res = await db.client.post(`/api/firestore/${db.projectId}/query`, {
             collectionPath,
@@ -689,9 +723,11 @@ const getDocs = async (queryOrCollection) => {
         };
     }
     catch (err) {
-        if (err && err.response) {
+        // If it's a definitive authorization or validation 4xx error, propagate it
+        if (err && err.response && err.response.status < 500) {
             throw err;
         }
+        // Failover: Smoothly fallback to the IndexedDB local cache on network/5xx exceptions
         return (0, exports.getCachedDocs)(queryOrCollection);
     }
 };
@@ -702,6 +738,21 @@ const getDoc = async (docRef) => {
         await db._initPromise;
     const segments = docRef.path.split('/');
     const docId = segments[segments.length - 1];
+    // If cache-first strategy, try loading from local cache first
+    if (db.cacheStrategy === 'cache-first') {
+        const cached = (0, exports.getCachedDoc)(docRef);
+        if (cached && cached.exists()) {
+            // Background-sync silently to update the local cache
+            db.client.get(`/api/firestore/${db.projectId}/document?docPath=${encodeURIComponent(docRef.path)}`)
+                .then(async (res) => {
+                const data = res.data.data;
+                await db._setCache(docRef.path, data);
+                db._notifySnapshotCallbacks(docRef.path, 'document_written', data);
+            }).catch(() => { });
+            return cached;
+        }
+    }
+    // Network-first (or cache-first with empty cache): Prioritize the remote database
     try {
         const res = await db.client.get(`/api/firestore/${db.projectId}/document?docPath=${encodeURIComponent(docRef.path)}`);
         const data = res.data.data;
@@ -714,9 +765,11 @@ const getDoc = async (docRef) => {
         };
     }
     catch (err) {
-        if (err && err.response) {
+        // If it's a definitive authorization or validation 4xx error, propagate it
+        if (err && err.response && err.response.status < 500) {
             throw err;
         }
+        // Failover: Smoothly fallback to the IndexedDB local cache on network/5xx exceptions
         return (0, exports.getCachedDoc)(docRef);
     }
 };
@@ -827,26 +880,41 @@ const onSnapshot = (ref, callback) => {
                 callback(cached);
             }
         }
+        let isInitial = true;
         let debounceTimer = null;
         const triggerCallback = () => {
             if (debounceTimer)
                 clearTimeout(debounceTimer);
             debounceTimer = setTimeout(async () => {
                 if (ref.type === 'collection' || ref.type === 'query') {
-                    callback((0, exports.getCachedDocs)(ref));
-                    try {
-                        const docs = await (0, exports.getDocs)(ref);
-                        callback(docs);
+                    if (isInitial) {
+                        isInitial = false;
+                        callback((0, exports.getCachedDocs)(ref));
+                        try {
+                            const docs = await (0, exports.getDocs)(ref);
+                            callback(docs);
+                        }
+                        catch (e) { }
+                    }
+                    else {
+                        // Real-time updates: emit instantly and synchronously from cache.
+                        // Eliminates redundant HTTP requests and rendering lag/flicker!
+                        callback((0, exports.getCachedDocs)(ref));
                     }
-                    catch (e) { }
                 }
                 else {
-                    callback((0, exports.getCachedDoc)(ref));
-                    try {
-                        const docData = await (0, exports.getDoc)(ref);
-                        callback(docData);
+                    if (isInitial) {
+                        isInitial = false;
+                        callback((0, exports.getCachedDoc)(ref));
+                        try {
+                            const docData = await (0, exports.getDoc)(ref);
+                            callback(docData);
+                        }
+                        catch (e) { }
+                    }
+                    else {
+                        callback((0, exports.getCachedDoc)(ref));
                     }
-                    catch (e) { }
                 }
             }, 50); // Debounce to batch rapid updates
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexabase-console",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "SDK Client resmi untuk NexaBase: Platform Sinkronisasi NoSQL, Realtime, File Storage, & Autentikasi Offline-First.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",