nexabase-console 1.1.4 → 2.0.0

package/README.md

@@ -6,7 +6,9 @@ SDK Client Resmi untuk **NexaBase**: Platform sinkronisasi database modern yang
 
 ## 🚀 Fitur Utama
 
--   **⚡ Real-Time Synchronization**: Sinkronisasi data real-time dengan latency rendah menggunakan Server-Sent Events (SSE).
+-   **⚡ Real-Time Synchronization & Anti-Flicker Engine**: Sinkronisasi data real-time dengan latency rendah menggunakan Server-Sent Events (SSE) yang dilengkapi *Deep Comparison Data Hashing* untuk mencegah re-render/flicker komponen UI saat sync.
+-   **🚀 Latency Compensation (Optimistic UI & 0ms Local Render)**: Penulisan data (`setDoc`, `updateDoc`, `deleteDoc`, `writeBatch`) langsung memperbarui cache lokal IndexedDB dan memicu `onSnapshot` secara instan (0ms) sebelum konfirmasi jaringan selesai.
+-   **🔄 Delta Updates (`docChanges()`)**: Dukungan native pelacakan perubahan inkremental (`added`, `modified`, `removed`) pada `QuerySnapshot` untuk manipulasi elemen UI secara presisi tanpa mengunduh ulang seluruh dataset.
 -   **🔒 Concurrency Control & Transactions (`runTransaction`)**: Transaksi dua arah (Read-Before-Write) atomik dengan kontrol konkurensi (Optimistic Locking & Automatic Retry) untuk mencegah race conditions pada pemotongan stok, kuota, atau transaksi finansial.
 -   **📦 Offline-First & Auto-Sync**: Sinkronisasi state lokal secara otomatis menggunakan **IndexedDB**. Data tetap tersimpan di browser jika koneksi terputus dan akan disinkronkan ke server secara otomatis saat kembali online.
 -   **🔥 Modular Firestore API & TypeScript Generics**: Desain API modular modern mirip Firebase SDK (v9+) dengan dukungan penuh parameter tipe generik (TypeScript Generics) untuk menjamin tipe data yang aman (type-safe) secara end-to-end.
@@ -49,6 +51,14 @@ Untuk mendukung arsitektur server-side proxy atau direct API key yang sangat fle
 
 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)
@@ -100,16 +110,31 @@ const readData = async () => {
 };
 ```
 
-#### Mendengarkan Perubahan Data secara Real-Time (onSnapshot)
+#### Mendengarkan Perubahan Data secara Real-Time (onSnapshot & docChanges)
 ```javascript
-import { doc, onSnapshot } from 'nexabase-console';
+import { collection, onSnapshot } from 'nexabase-console';
 
-const listenLive = () => {
-  const docRef = doc(db, 'chats', 'global_room');
+const listenLiveChats = () => {
+  const chatsRef = collection(db, 'chats');
   
-  // onSnapshot akan terpanggil seketika jika ada perubahan data baik di lokal maupun di server
-  const unsubscribe = onSnapshot(docRef, (snapshot) => {
-    console.log("⚡ Perubahan Terdeteksi! Data Terbaru:", snapshot.data());
+  // onSnapshot menggunakan Anti-Flicker Engine (Deep Comparison)
+  // - Langsung memancarkan cache lokal secara instan (0ms) tanpa layar putih
+  // - Membandingkan hash data server sebelum re-render agar UI tidak berkedip
+  const unsubscribe = onSnapshot(chatsRef, (querySnapshot) => {
+    // 1. Ambil rincian pembaruan inkremental (Delta/Diff Updates)
+    if (querySnapshot.docChanges) {
+      const changes = querySnapshot.docChanges();
+      changes.forEach((change) => {
+        if (change.type === 'added') console.log("Pesan baru:", change.doc.data());
+        if (change.type === 'modified') console.log("Pesan diedit:", change.doc.data());
+        if (change.type === 'removed') console.log("Pesan dihapus:", change.doc.id);
+      });
+    }
+
+    // 2. Iterasi seluruh koleksi
+    querySnapshot.forEach((doc) => {
+      console.log(doc.id, "=>", doc.data());
+    });
   });
   
   // Panggil unsubscribe() untuk menghentikan pemantauan realtime

package/dist/app/NexaApp.d.ts

@@ -0,0 +1,63 @@
+import { AxiosInstance } from 'axios';
+import { NexaConfig, User, AuthResponse, DatabaseReference, StorageReference, UploadOptions, OfflineJob } from '../types/index';
+import { HttpClient } from '../transport/HttpClient';
+import { SSEClient } from '../transport/SSEClient';
+import { Auth } from '../auth/Auth';
+import { IndexedDB } from '../persistence/IndexedDB';
+import { LocalStore } from '../persistence/LocalStore';
+import { MutationQueue } from '../persistence/MutationQueue';
+import { SyncEngine } from '../sync/SyncEngine';
+import { RealtimeDatabase } from '../realtime/RealtimeDatabase';
+import { Storage } from '../storage/Storage';
+export declare class NexaApp {
+    projectId: string;
+    token: string | null;
+    endpoint: string;
+    enablePersistence: boolean;
+    cacheStrategy: 'network-first' | 'cache-first';
+    httpClient: HttpClient;
+    client: AxiosInstance;
+    sseClient: SSEClient;
+    authService: Auth;
+    indexedDB: IndexedDB;
+    localStore: LocalStore;
+    mutationQueue: MutationQueue;
+    syncEngine: SyncEngine;
+    realtimeDatabase: RealtimeDatabase;
+    storage: Storage;
+    _snapshotCallbacks: Record<string, (payload?: any) => void>;
+    _firestoreListening: boolean;
+    _firestoreUnsubscribes: (() => void)[];
+    _initPromise: Promise<void> | null;
+    constructor(config: NexaConfig);
+    get _firestoreCache(): Record<string, any>;
+    private _setupCrossTabSync;
+    _broadcastLocalMutation(path: string, action: string, data?: any): void;
+    hasPendingWrites(path: string): boolean;
+    markInflight(path: string): void;
+    unmarkInflight(path: string): void;
+    _initFirestoreState(): Promise<void>;
+    _setCache(path: string, data: any): Promise<void>;
+    _deleteCache(path: string): Promise<void>;
+    _addOfflineJob(job: OfflineJob): Promise<void>;
+    _syncOfflineQueue(): Promise<void>;
+    _ensureFirestoreSSE(): void;
+    _closeFirestoreSSEIfIdle(): void;
+    _notifySnapshotCallbacks(path: string, actionType: string, payload: any): void;
+    signInWithEmailAndPassword(email: string, password: string): Promise<AuthResponse>;
+    createUserWithEmailAndPassword(email: string, password: string, name: string): Promise<User>;
+    sendOtp(email: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    signInWithOtp(email: string, otp: string, name?: string): Promise<AuthResponse>;
+    signOut(): void;
+    getCurrentUser(): User | null;
+    ref(path: string): DatabaseReference;
+    storageRef(path: string): StorageReference;
+    uploadFile(path: string, file: File | Blob, options?: UploadOptions): Promise<{
+        url: string;
+        path: string;
+    }>;
+    getDownloadURL(path: string): Promise<string>;
+}

package/dist/app/NexaApp.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NexaApp = void 0;
+const HttpClient_1 = require("../transport/HttpClient");
+const SSEClient_1 = require("../transport/SSEClient");
+const Auth_1 = require("../auth/Auth");
+const IndexedDB_1 = require("../persistence/IndexedDB");
+const LocalStore_1 = require("../persistence/LocalStore");
+const MutationQueue_1 = require("../persistence/MutationQueue");
+const SyncEngine_1 = require("../sync/SyncEngine");
+const RealtimeDatabase_1 = require("../realtime/RealtimeDatabase");
+const RealtimeConnection_1 = require("../realtime/RealtimeConnection");
+const Storage_1 = require("../storage/Storage");
+class NexaApp {
+    constructor(config) {
+        this.token = null;
+        // Internal Firestore caches/callbacks
+        this._snapshotCallbacks = {};
+        this._firestoreListening = false;
+        this._firestoreUnsubscribes = [];
+        this._initPromise = null;
+        this.projectId = config.projectId;
+        this.token = config.apiKey || null;
+        this.enablePersistence = config.enablePersistence !== false;
+        this.cacheStrategy = config.cacheStrategy || 'network-first';
+        let defaultEndpoint = 'https://db.nexabase.id';
+        if (typeof window !== 'undefined' && window.location) {
+            defaultEndpoint = window.location.origin;
+        }
+        this.endpoint = config.endpoint || defaultEndpoint;
+        // Transport
+        this.httpClient = new HttpClient_1.HttpClient(this.endpoint, () => this.authService ? this.authService.getToken() : this.token);
+        this.client = this.httpClient.getAxiosInstance();
+        this.sseClient = new SSEClient_1.SSEClient(this.projectId, this.endpoint);
+        // Auth & Persistence
+        this.authService = new Auth_1.Auth(this.projectId, this.client, this.token);
+        this.token = this.authService.getToken();
+        this.indexedDB = new IndexedDB_1.IndexedDB(`nexabase_${this.projectId}`);
+        this.localStore = new LocalStore_1.LocalStore(this.indexedDB);
+        this.mutationQueue = new MutationQueue_1.MutationQueue(this.projectId, this.indexedDB, this.client);
+        this.syncEngine = new SyncEngine_1.SyncEngine(this.projectId, this.mutationQueue, this.sseClient);
+        // Realtime & Storage
+        const realtimeConn = new RealtimeConnection_1.RealtimeConnection(this.sseClient);
+        this.realtimeDatabase = new RealtimeDatabase_1.RealtimeDatabase(this.projectId, this.client, realtimeConn);
+        this.storage = new Storage_1.Storage(this.projectId, this.client);
+        this._setupCrossTabSync();
+    }
+    get _firestoreCache() {
+        return this.localStore.getMemoryCache();
+    }
+    _setupCrossTabSync() {
+        this.syncEngine.listenCrossTab((path, action, data) => {
+            if (action === 'delete') {
+                this.localStore.delete(path);
+            }
+            else if (data) {
+                this.localStore.set(path, data);
+            }
+            this._notifySnapshotCallbacks(path, action === 'delete' ? 'document_deleted' : 'document_written', data);
+        });
+    }
+    _broadcastLocalMutation(path, action, data) {
+        this.syncEngine.broadcastLocalMutation(path, action, data);
+    }
+    hasPendingWrites(path) {
+        return this.mutationQueue.hasPendingWrites(path);
+    }
+    markInflight(path) {
+        this.mutationQueue.markInflight(path);
+    }
+    unmarkInflight(path) {
+        this.mutationQueue.unmarkInflight(path);
+    }
+    async _initFirestoreState() {
+        if (!this.enablePersistence)
+            return;
+        try {
+            await this.indexedDB.init();
+            await this.localStore.loadAll();
+            await this.mutationQueue.init();
+            if (typeof window !== 'undefined') {
+                window.addEventListener('online', () => this._syncOfflineQueue());
+            }
+            this._syncOfflineQueue();
+        }
+        catch (err) {
+            console.warn('[NexaApp] Failed to initialize IndexedDB offline cache:', err);
+        }
+    }
+    async _setCache(path, data) {
+        await this.localStore.set(path, data);
+    }
+    async _deleteCache(path) {
+        await this.localStore.delete(path);
+    }
+    async _addOfflineJob(job) {
+        await this.mutationQueue.addJob(job);
+    }
+    async _syncOfflineQueue() {
+        await this.syncEngine.syncOfflineMutations();
+    }
+    _ensureFirestoreSSE() {
+        if (this._firestoreListening)
+            return;
+        this._firestoreListening = true;
+        const unsub1 = this.sseClient.addListener('data_changed', (payload) => {
+            if (payload && payload.path) {
+                if (payload.action === 'delete') {
+                    this._deleteCache(payload.path);
+                }
+                else if (payload.data) {
+                    this._setCache(payload.path, payload.data);
+                }
+                this._notifySnapshotCallbacks(payload.path, payload.action === 'delete' ? 'document_deleted' : 'document_written', payload.data);
+            }
+        });
+        const unsub2 = this.sseClient.addListener('firestore_changed', (payload) => {
+            this._notifySnapshotCallbacks(payload.collectionPath || payload.docPath, 'server_update', payload.data);
+        });
+        this._firestoreUnsubscribes.push(unsub1, unsub2);
+    }
+    _closeFirestoreSSEIfIdle() {
+        if (Object.keys(this._snapshotCallbacks).length === 0) {
+            this._firestoreUnsubscribes.forEach((unsub) => unsub());
+            this._firestoreUnsubscribes = [];
+            this._firestoreListening = false;
+        }
+    }
+    _notifySnapshotCallbacks(path, actionType, payload) {
+        Object.keys(this._snapshotCallbacks).forEach((cbKey) => {
+            const parts = cbKey.split('_');
+            const targetPath = parts.slice(2).join('_');
+            if (cbKey.startsWith('document_') && targetPath === path) {
+                this._snapshotCallbacks[cbKey](payload);
+            }
+            else if ((cbKey.startsWith('collection_') || cbKey.startsWith('query_')) && (path.startsWith(targetPath + '/') || path === targetPath)) {
+                this._snapshotCallbacks[cbKey](payload);
+            }
+        });
+    }
+    // Auth Shortcuts
+    async signInWithEmailAndPassword(email, password) {
+        const res = await this.authService.signInWithEmailAndPassword(email, password);
+        this.token = this.authService.getToken();
+        return res;
+    }
+    async createUserWithEmailAndPassword(email, password, name) {
+        return this.authService.createUserWithEmailAndPassword(email, password, name);
+    }
+    async sendOtp(email) {
+        return this.authService.sendOtp(email);
+    }
+    async signInWithOtp(email, otp, name) {
+        const res = await this.authService.signInWithOtp(email, otp, name);
+        this.token = this.authService.getToken();
+        return res;
+    }
+    signOut() {
+        this.authService.signOut();
+        this.token = null;
+    }
+    getCurrentUser() {
+        return this.authService.getCurrentUser();
+    }
+    // Realtime Database Shortcut
+    ref(path) {
+        return this.realtimeDatabase.ref(path);
+    }
+    // Storage Shortcuts
+    storageRef(path) {
+        return {
+            path,
+            upload: (file, options) => this.storage.uploadFile(path, file, options),
+            getDownloadURL: () => this.storage.getDownloadURL(path)
+        };
+    }
+    async uploadFile(path, file, options) {
+        return this.storage.uploadFile(path, file, options);
+    }
+    async getDownloadURL(path) {
+        return this.storage.getDownloadURL(path);
+    }
+}
+exports.NexaApp = NexaApp;

package/dist/app/initializeApp.d.ts

@@ -0,0 +1,8 @@
+import { NexaApp } from './NexaApp';
+import { NexaConfig } from '../types/index';
+export declare const NexaBase: {
+    init: (config: NexaConfig) => NexaApp;
+    initializeApp: (config: NexaConfig) => NexaApp;
+};
+export declare const initializeApp: (config: NexaConfig) => NexaApp;
+export declare const getFirestore: (app: NexaApp) => NexaApp;

package/dist/app/initializeApp.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFirestore = exports.initializeApp = exports.NexaBase = void 0;
+const NexaApp_1 = require("./NexaApp");
+exports.NexaBase = {
+    init: (config) => {
+        const app = new NexaApp_1.NexaApp(config);
+        if (app.enablePersistence) {
+            app._initPromise = app._initFirestoreState();
+        }
+        return app;
+    },
+    initializeApp: (config) => {
+        return exports.NexaBase.init(config);
+    }
+};
+const initializeApp = (config) => {
+    return exports.NexaBase.init(config);
+};
+exports.initializeApp = initializeApp;
+const getFirestore = (app) => {
+    if (app.enablePersistence) {
+        app._initPromise = app._initFirestoreState();
+    }
+    return app;
+};
+exports.getFirestore = getFirestore;

package/dist/auth/Auth.d.ts

@@ -0,0 +1,21 @@
+import { AxiosInstance } from 'axios';
+import { User, AuthResponse } from './authTypes';
+export declare class Auth {
+    private projectId;
+    private client;
+    private token;
+    private persistence;
+    constructor(projectId: string, client: AxiosInstance, initialToken: string | null);
+    getToken(): string | null;
+    setToken(token: string | null): void;
+    signInWithEmailAndPassword(email: string, password: string): Promise<AuthResponse>;
+    createUserWithEmailAndPassword(email: string, password: string, name: string): Promise<User>;
+    sendOtp(email: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    signInWithOtp(email: string, otp: string, name?: string): Promise<AuthResponse>;
+    signOut(): void;
+    getCurrentUser(): User | null;
+}
+export { Auth as AuthService };

package/dist/auth/Auth.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthService = exports.Auth = void 0;
+const persistence_1 = require("./persistence");
+const NexaError_1 = require("../errors/NexaError");
+class Auth {
+    constructor(projectId, client, initialToken) {
+        this.token = null;
+        this.projectId = projectId;
+        this.client = client;
+        this.persistence = new persistence_1.AuthPersistence(projectId);
+        this.token = initialToken || this.persistence.getSavedToken();
+    }
+    getToken() {
+        return this.token;
+    }
+    setToken(token) {
+        this.token = token;
+    }
+    async signInWithEmailAndPassword(email, password) {
+        try {
+            const res = await this.client.post(`/api/project/${this.projectId}/auth/login`, { email, password });
+            if (res.data.token) {
+                this.token = res.data.token;
+                this.persistence.saveSession(res.data.token, res.data.user);
+            }
+            return res.data;
+        }
+        catch (err) {
+            throw (0, NexaError_1.toNexaError)(err);
+        }
+    }
+    async createUserWithEmailAndPassword(email, password, name) {
+        try {
+            const res = await this.client.post(`/api/project/${this.projectId}/users`, { email, password, name });
+            return res.data;
+        }
+        catch (err) {
+            throw (0, NexaError_1.toNexaError)(err);
+        }
+    }
+    async sendOtp(email) {
+        try {
+            const res = await this.client.post(`/api/project/${this.projectId}/auth/otp/send`, { email });
+            return res.data;
+        }
+        catch (err) {
+            throw (0, NexaError_1.toNexaError)(err);
+        }
+    }
+    async signInWithOtp(email, otp, name) {
+        try {
+            const res = await this.client.post(`/api/project/${this.projectId}/auth/otp/login`, { email, otp, name });
+            if (res.data.token) {
+                this.token = res.data.token;
+                this.persistence.saveSession(res.data.token, res.data.user);
+            }
+            return res.data;
+        }
+        catch (err) {
+            throw (0, NexaError_1.toNexaError)(err);
+        }
+    }
+    signOut() {
+        this.token = null;
+        this.persistence.clearSession();
+    }
+    getCurrentUser() {
+        return this.persistence.getSavedUser();
+    }
+}
+exports.Auth = Auth;
+exports.AuthService = Auth;

package/dist/auth/authTypes.d.ts

@@ -0,0 +1 @@
+export type { User, AuthResponse } from '../types/index';

package/dist/auth/authTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/auth/persistence.d.ts

@@ -0,0 +1,9 @@
+import { User } from './authTypes';
+export declare class AuthPersistence {
+    private projectId;
+    constructor(projectId: string);
+    saveSession(token: string, user: User): void;
+    clearSession(): void;
+    getSavedToken(): string | null;
+    getSavedUser(): User | null;
+}

package/dist/auth/persistence.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthPersistence = void 0;
+class AuthPersistence {
+    constructor(projectId) {
+        this.projectId = projectId;
+    }
+    saveSession(token, user) {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            localStorage.setItem(`nexa_token_${this.projectId}`, token);
+            localStorage.setItem(`nexa_user_${this.projectId}`, JSON.stringify(user));
+        }
+    }
+    clearSession() {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            localStorage.removeItem(`nexa_token_${this.projectId}`);
+            localStorage.removeItem(`nexa_user_${this.projectId}`);
+        }
+    }
+    getSavedToken() {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            return localStorage.getItem(`nexa_token_${this.projectId}`);
+        }
+        return null;
+    }
+    getSavedUser() {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            const userStr = localStorage.getItem(`nexa_user_${this.projectId}`);
+            return userStr ? JSON.parse(userStr) : null;
+        }
+        return null;
+    }
+}
+exports.AuthPersistence = AuthPersistence;

package/dist/errors/NexaError.d.ts

@@ -0,0 +1,7 @@
+export type NexaErrorCode = 'cancelled' | 'unknown' | 'invalid-argument' | 'deadline-exceeded' | 'not-found' | 'already-exists' | 'permission-denied' | 'resource-exhausted' | 'failed-precondition' | 'aborted' | 'out-of-range' | 'unimplemented' | 'internal' | 'unavailable' | 'data-loss' | 'unauthenticated';
+export declare class NexaError extends Error {
+    readonly code: NexaErrorCode;
+    readonly details?: unknown;
+    constructor(code: NexaErrorCode, message: string, details?: unknown);
+}
+export declare function toNexaError(err: unknown): NexaError;

package/dist/errors/NexaError.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NexaError = void 0;
+exports.toNexaError = toNexaError;
+class NexaError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'NexaError';
+        this.code = code;
+        this.details = details;
+        // Maintain proper stack trace in V8 / Node / modern browsers
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, NexaError);
+        }
+    }
+}
+exports.NexaError = NexaError;
+function toNexaError(err) {
+    if (err instanceof NexaError) {
+        return err;
+    }
+    if (err && typeof err === 'object') {
+        const e = err;
+        if (e.response) {
+            const status = e.response.status;
+            const message = e.response.data?.message || e.response.data?.error || e.message || `HTTP ${status} error`;
+            const details = e.response.data;
+            switch (status) {
+                case 400:
+                    return new NexaError('invalid-argument', message, details);
+                case 401:
+                    return new NexaError('unauthenticated', message, details);
+                case 403:
+                    return new NexaError('permission-denied', message, details);
+                case 404:
+                    return new NexaError('not-found', message, details);
+                case 409:
+                    return new NexaError('already-exists', message, details);
+                case 412:
+                    return new NexaError('failed-precondition', message, details);
+                case 429:
+                    return new NexaError('resource-exhausted', message, details);
+                case 501:
+                    return new NexaError('unimplemented', message, details);
+                case 502:
+                case 503:
+                case 504:
+                    return new NexaError('unavailable', message, details);
+                default:
+                    return new NexaError('internal', message, details);
+            }
+        }
+        if (e.code === 'ECONNABORTED' || e.code === 'ERR_NETWORK' || e.message?.includes('Network Error')) {
+            return new NexaError('unavailable', 'The service is currently unavailable or network is offline.', e);
+        }
+        if (e instanceof Error) {
+            return new NexaError('unknown', e.message, e);
+        }
+    }
+    return new NexaError('unknown', String(err));
+}

package/dist/firestore/CollectionReference.d.ts

@@ -0,0 +1,3 @@
+import { NexaApp } from '../app/NexaApp';
+import { CollectionReference } from '../types/index';
+export declare const collection: <T = any>(db: NexaApp, collectionPath: string) => CollectionReference<T>;

package/dist/firestore/CollectionReference.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collection = void 0;
+const collection = (db, collectionPath) => {
+    return { type: 'collection', path: collectionPath, db };
+};
+exports.collection = collection;

package/dist/firestore/DocumentReference.d.ts

@@ -0,0 +1,3 @@
+import { NexaApp } from '../app/NexaApp';
+import { CollectionReference, DocumentReference } from '../types/index';
+export declare const doc: <T = any>(dbOrCollection: NexaApp | CollectionReference<any>, ...pathSegments: string[]) => DocumentReference<T>;

package/dist/firestore/DocumentReference.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.doc = void 0;
+const doc = (dbOrCollection, ...pathSegments) => {
+    let docRef;
+    if ('type' in dbOrCollection && dbOrCollection.type === 'collection') {
+        docRef = {
+            type: 'document',
+            path: `${dbOrCollection.path}/${pathSegments.join('/')}`,
+            db: dbOrCollection.db
+        };
+    }
+    else {
+        docRef = {
+            type: 'document',
+            path: pathSegments.join('/'),
+            db: dbOrCollection
+        };
+    }
+    return docRef;
+};
+exports.doc = doc;

package/dist/firestore/FieldPath.d.ts

@@ -0,0 +1,7 @@
+export declare class FieldPath {
+    private readonly segments;
+    constructor(...fieldNames: string[]);
+    static documentId(): FieldPath;
+    getPathString(): string;
+    isEqual(other: FieldPath): boolean;
+}

package/dist/firestore/FieldPath.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldPath = void 0;
+class FieldPath {
+    constructor(...fieldNames) {
+        if (fieldNames.length === 0) {
+            throw new Error('FieldPath must contain at least one field name');
+        }
+        this.segments = fieldNames;
+    }
+    static documentId() {
+        return new FieldPath('__name__');
+    }
+    getPathString() {
+        return this.segments.join('.');
+    }
+    isEqual(other) {
+        if (this.segments.length !== other.segments.length)
+            return false;
+        return this.segments.every((seg, idx) => seg === other.segments[idx]);
+    }
+}
+exports.FieldPath = FieldPath;

package/dist/firestore/FieldValue.d.ts

@@ -0,0 +1,11 @@
+export declare class FieldValue {
+    method: string;
+    value?: any | undefined;
+    _isFieldValue: boolean;
+    constructor(method: string, value?: any | undefined);
+}
+export declare const serverTimestamp: () => FieldValue;
+export declare const increment: (n: number) => FieldValue;
+export declare const arrayUnion: (...elements: any[]) => FieldValue;
+export declare const arrayRemove: (...elements: any[]) => FieldValue;
+export declare const deleteField: () => FieldValue;