@zuzjs/flare 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zuz.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# 🔥 ZuzFlare Client
+
+> Official JavaScript/TypeScript client for ZuzFlare Server
+
+[![npm version](https://badge.fury.io/js/%40zuzjs%2Fflare.svg)](https://www.npmjs.com/package/@zuzjs/flare)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Real-time database client with Firebase-like API for your self-hosted ZuzFlare server.
+
+## 📦 Installation
+
+```bash
+npm install @zuzjs/flare
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { FlareClient } from '@zuzjs/flare';
+
+const flare = new FlareClient({
+  endpoint: 'http://localhost:5050',
+  appId: 'my-app'
+});
+
+flare.connect();
+
+// Write data
+await flare.collection('users').doc('alice').set({
+  name: 'Alice',
+  email: 'alice@example.com'
+});
+
+// Real-time updates
+flare.collection('users').onSnapshot((data) => {
+  console.log('Users:', data);
+});
+```
+
+## 📖 Full Documentation
+
+See [complete documentation](https://flare.zuz.com.pk) for:
+- API Reference
+- Usage Examples  
+- TypeScript Types
+- React/Vue/Svelte Integration
+- Authentication
+- Offline Support
+
+## 🔗 Links
+
+- [Server Package](@zuzjs/flare-server)
+- [GitHub](https://github.com/zuzjs/flare-client)
+- [Documentation](https://flare.zuz.com.pk)
+
+## 📄 License
+
+MIT © Zuz.js Team

package/dist/index.cjs

@@ -0,0 +1,3 @@
+'use strict';Object.defineProperty(exports,'__esModule',{value:true});var core=require('@zuzjs/core'),auth=require('@zuzjs/auth');/* ZuzFlare Client */
+var C=(c=>(c.SUBSCRIBE="subscribe",c.UNSUBSCRIBE="unsubscribe",c.WRITE="write",c.DELETE="delete",c.AUTH="auth",c.PING="ping",c.OFFLINE_SYNC="offline_sync",c.CALL="call",c))(C||{}),v=(c=>(c.SNAPSHOT="snapshot",c.CHANGE="change",c.ERROR="error",c.ACK="ack",c.PONG="pong",c.AUTH_OK="auth_ok",c.OFFLINE_ACK="offline_ack",c.CALL_RESPONSE="call_response",c))(v||{});function S(r){let e=[];for(let[t,i]of Object.entries(r))if(typeof i=="string"){let o=i.match(/^(>=|<=|!=|>|<|==)\s*(.+)$/);if(o){let[,n,s]=o;e.push({field:t,op:n,value:w(s.trim())});}else e.push({field:t,op:"==",value:i});}else Array.isArray(i)?e.push({field:t,op:"in",value:i}):e.push({field:t,op:"==",value:i});return e}function w(r){if(!isNaN(Number(r)))return Number(r);if(r==="true")return  true;if(r==="false")return  false;if(r==="null")return null;if(r!=="undefined")return r}var a=class{constructor(e,t,i){this.client=e;this.collection=t;this.legacyId=i;}whereCondition;updateData;setData;deleteOp=false;promise;where(e){return this.whereCondition=e,this}update(e){return this.updateData=e,this}set(e){return this.setData=e,this}delete(){return this.deleteOp=true,this}getDocId(){if(this.legacyId)return this.legacyId;if(this.whereCondition&&this.whereCondition.id){let e=this.whereCondition.id;if(typeof e=="string")return e}throw new Error('Document ID not specified. Use .where({ id: "..." }) or doc(collection, id)')}async execute(){return this._execute()}async _execute(){let e=this.getDocId();if(this.deleteOp){await this.client.send("delete",{collection:this.collection,docId:e});return}if(this.updateData){await this.client.send("write",{collection:this.collection,docId:e,data:this.updateData,merge:true});return}if(this.setData){await this.client.send("write",{collection:this.collection,docId:e,data:this.setData,merge:false});return}return this.get()}then(e,t){return this.promise||(this.promise=this._execute()),this.promise.then(e,t)}async get(){let e=this.getDocId(),t=core.uuid2(18);return new Promise((i,o)=>{let n=this.client.subscribe(t,this.collection,e,void 0,s=>{s.type==="snapshot"&&(n(),i(s.data));});setTimeout(()=>{n(),o(new Error("Document fetch timeout"));},1e4);})}onSnapshot(e){let t=this.getDocId(),i=core.uuid2(18);return this.client.subscribe(i,this.collection,t,void 0,e)}},h=class{constructor(e,t,i){this.client=e;this.collection=t;this.id=i;}async get(){return new a(this.client,this.collection,this.id).get()}async set(e){await this.client.send("write",{collection:this.collection,docId:this.id,data:e,merge:false});}async update(e){await this.client.send("write",{collection:this.collection,docId:this.id,data:e,merge:true});}async delete(){await this.client.send("delete",{collection:this.collection,docId:this.id});}onSnapshot(e){let t=core.uuid2(18);return this.client.subscribe(t,this.collection,this.id,void 0,e)}},f=class r{constructor(e,t){this.client=e;this.collection=t;}queries=[];promise;doc(e){return new h(this.client,this.collection,e)}where(e){let t=new r(this.client,this.collection),i=S(e);return t.queries=[...this.queries,...i],t}async get(){return this._execute()}async _execute(){let e=core.uuid2(18);return new Promise((t,i)=>{let o=this.queries.length>0?this.queries:void 0,n=this.client.subscribe(e,this.collection,void 0,o,s=>{s.type==="snapshot"&&(n(),t(Array.isArray(s.data)?s.data:[s.data]));});setTimeout(()=>{n(),i(new Error("Collection fetch timeout"));},1e4);})}then(e,t){return this.promise||(this.promise=this._execute()),this.promise.then(e,t)}onSnapshot(e){let t=core.uuid2(18),i=this.queries.length>0?this.queries:void 0;return this.client.subscribe(t,this.collection,void 0,i,e)}async add(e){let t=core.uuid2(18),i=this.doc(t);return await i.set(e),i}update(e){return new a(this.client,this.collection).update(e)}delete(){return new a(this.client,this.collection).delete()}};async function R(r){let e=r.replace(/-----BEGIN PUBLIC KEY-----/,"").replace(/-----END PUBLIC KEY-----/,"").replace(/\s+/g,""),t=typeof atob<"u"?atob(e):Buffer.from(e,"base64").toString("binary"),i=new Uint8Array(t.length);for(let n=0;n<t.length;n++)i[n]=t.charCodeAt(n);return (globalThis.crypto??(await import('crypto')).webcrypto).subtle.importKey("spki",i.buffer,{name:"RSA-OAEP",hash:"SHA-256"},false,["encrypt"])}async function I(r,e){let t=await R(e),i=new TextEncoder().encode(JSON.stringify(r)),n=await(globalThis.crypto??(await import('crypto')).webcrypto).subtle.encrypt({name:"RSA-OAEP"},t,i),s=typeof btoa<"u"?btoa(String.fromCharCode(...new Uint8Array(n))):Buffer.from(n).toString("base64");return JSON.stringify({enc:"rsa",data:s})}var g=class{socket=null;reconnectInterval;maxReconnectDelay;isConnected=false;shouldReconnect=true;options;messageQueue=[];heartbeatInterval=null;connectionTimeout=null;constructor(e){this.options=e,this.reconnectInterval=e.reconnectDelay||2,this.maxReconnectDelay=e.maxReconnectDelay||60,this.log("Transport initialized",e.url);}connect(){if(this.socket){this.log("Socket already exists, skipping connection");return}this.log("Connecting to",this.options.url),this.socket=new WebSocket(this.options.url),this.connectionTimeout=setTimeout(()=>{this.isConnected||(this.log("Connection timeout"),this.socket?.close(),this.handleReconnect());},1e4),this.socket.onopen=()=>{this.connectionTimeout&&(clearTimeout(this.connectionTimeout),this.connectionTimeout=null),this.isConnected=true,this.reconnectInterval=this.options.reconnectDelay||2,this.log("Connected to server"),this.options.onOpen?.(),this.startHeartbeat(),this.flushQueue();},this.socket.onmessage=e=>{try{let t=JSON.parse(e.data);this.options.onMessage(t);}catch(t){this.log("Parse error",t),this.options.onError?.(t);}},this.socket.onerror=e=>{this.log("WebSocket error",e),this.options.onError?.(new Error("WebSocket error"));},this.socket.onclose=e=>{this.connectionTimeout&&(clearTimeout(this.connectionTimeout),this.connectionTimeout=null),this.isConnected=false,this.socket=null,this.stopHeartbeat(),this.log("Connection closed",e.code,e.reason),this.options.onClose?.(),e.code!==1e3&&this.shouldReconnect&&this.options.autoReconnect&&this.handleReconnect();};}handleReconnect(){let e=this.reconnectInterval*1e3;this.log(`Reconnecting in ${this.reconnectInterval}s...`),setTimeout(()=>{this.reconnectInterval=Math.min(this.reconnectInterval*2,this.maxReconnectDelay),this.connect();},e);}startHeartbeat(){this.heartbeatInterval=setInterval(()=>{this.isConnected&&this.send({type:"ping",id:Date.now().toString(),ts:Date.now()});},3e4);}stopHeartbeat(){this.heartbeatInterval&&(clearInterval(this.heartbeatInterval),this.heartbeatInterval=null);}flushQueue(){for(this.log("Flushing message queue",this.messageQueue.length);this.messageQueue.length>0;){let e=this.messageQueue.shift();e&&this.send(e);}}send(e){if(this.socket&&this.socket.readyState===WebSocket.OPEN){let t=i=>{try{this.socket.send(i),this.log("Sent message",e);}catch(o){this.log("Send error",o),this.messageQueue.push(e);}};this.options.publicKey?I(e,this.options.publicKey).then(t).catch(i=>{this.log("RSA encrypt error \u2014 sending plaintext",i),t(JSON.stringify(e));}):t(JSON.stringify(e));}else this.log("Socket not ready, queueing message"),this.messageQueue.push(e);}disconnect(){this.shouldReconnect=false,this.stopHeartbeat(),this.socket&&(this.socket.close(1e3,"Client disconnect"),this.socket=null),this.isConnected=false,this.log("Disconnected");}get connected(){return this.isConnected}log(...e){this.options.debug&&console.log("[FlareTransport]",...e);}};var m=class{transport;config;pendingAcks=new Map;subscriptions=new Map;offlineQueue=[];currentState="disconnected";connectionListeners=[];errorListeners=[];authToken;userId;isDebug=false;constructor(e){this.config={autoReconnect:true,reconnectDelay:2,maxReconnectDelay:60,debug:false,connectionTimeout:1e4,...e},this.isDebug=this.config.debug||false;let{hostname:t,port:i,protocol:o}=new URL(this.config.endpoint),n=o==="https:",c=`${n?"wss":"ws"}://${t}:${i||(n?"443":"80")}/?appId=${this.config.appId}${this.config.apiKey?`&apiKey=${this.config.apiKey}`:""}`;this.transport=new g({url:c,publicKey:this.config.publicKey,autoReconnect:this.config.autoReconnect,reconnectDelay:this.config.reconnectDelay,maxReconnectDelay:this.config.maxReconnectDelay,onMessage:y=>this.handleIncoming(y),onOpen:()=>this.onConnected(),onClose:()=>this.onDisconnected(),onError:y=>this.handleTransportError(y),debug:this.isDebug}),this.log("FlareClient initialized",e);}connect(){this.setState("connecting"),this.transport.connect();}disconnect(){this.transport.disconnect(),this.setState("disconnected");}collection(e){return new f(this,e)}doc(e,t){return t!==void 0?new h(this,e,t):new a(this,e)}async auth(e){let t=await this.send("auth",{token:e});if(t.type==="auth_ok")return this.authToken=e,this.userId=t.uid,this.log("Authentication successful",t.uid),{uid:t.uid,token:e};throw new Error("Authentication failed")}signOut(){this.authToken=void 0,this.userId=void 0,this.log("Signed out");}get currentUser(){return this.userId}get connectionState(){return this.currentState}get isConnected(){return this.currentState==="connected"}onConnectionStateChange(e){return this.connectionListeners.push(e),()=>{this.connectionListeners=this.connectionListeners.filter(t=>t!==e);}}onError(e){return this.errorListeners.push(e),()=>{this.errorListeners=this.errorListeners.filter(t=>t!==e);}}async ping(){let e=Date.now();return await this.send("ping",{}),Date.now()-e}async call(e,t={}){let i=await this.send("call",{topic:e,payload:t});if(!i.success)throw new Error(i.error??`CALL "${e}" failed`);return i.result}async syncOffline(){if(this.offlineQueue.length===0)return;this.log("Syncing offline operations",this.offlineQueue.length);let e=[...this.offlineQueue];this.offlineQueue.length=0;let t=await this.send("offline_sync",{operations:e});t.conflicts&&t.conflicts.length>0&&(this.log("Offline sync conflicts",t.conflicts),t.conflicts.forEach(i=>{let o=e.find(n=>n.id===i.operationId);o&&this.offlineQueue.push(o);}));}handleTransportError(e){this.log("Transport error",e),this.errorListeners.forEach(t=>{try{t(e);}catch(i){this.log("Error listener error",i);}});}onConnected(){this.setState("connected"),this.log("Connected to FlareServer"),this.offlineQueue.length>0&&this.syncOffline().catch(e=>{this.log("Offline sync failed",e);});}onDisconnected(){this.currentState!=="disconnected"&&this.setState("reconnecting"),this.log("Disconnected from FlareServer");}setState(e){this.currentState!==e&&(this.currentState=e,this.log("Connection state changed",e),this.connectionListeners.forEach(t=>{try{t(e);}catch(i){this.log("Connection listener error",i);}}));}handleIncoming(e){if(this.log("Received message",e.type,e),e.type==="ack"||e.type==="pong"||e.type==="auth_ok"||e.type==="call_response"){let t=this.pendingAcks.get(e.correlationId||e.id);t&&(t(e),this.pendingAcks.delete(e.correlationId||e.id));return}if(e.type==="error"){this.log("Server error",e.code,e.message);let t=new Error(`[${e.code}] ${e.message}`);if(this.errorListeners.forEach(i=>{try{i(t);}catch(o){this.log("Error listener error",o);}}),e.correlationId){let i=this.pendingAcks.get(e.correlationId);i&&(i(e),this.pendingAcks.delete(e.correlationId));}return}if(e.type==="snapshot"||e.type==="change"){let t=this.subscriptions.get(e.subscriptionId);if(t){let i={subscriptionId:e.subscriptionId,collection:e.collection,docId:e.docId,data:e.data,type:e.type==="snapshot"?"snapshot":"change",operation:e.operation};try{t(i);}catch(o){this.log("Subscription callback error",o);}}}}async send(e,t){return new Promise((i,o)=>{let n=core.uuid2(18),s={id:n,type:e,ts:Date.now(),...t};this.pendingAcks.set(n,d=>{d.type==="error"?o(new Error(`[${d.code}] ${d.message}`)):i(d);}),this.isConnected?this.transport.send(s):(this.log("Queueing message for offline",s),this.offlineQueue.push(s),o(new Error("Not connected - message queued"))),setTimeout(()=>{this.pendingAcks.has(n)&&(this.pendingAcks.delete(n),o(new Error("Request timeout")));},this.config.connectionTimeout);})}subscribe(e,t,i,o,n){return this.log("Creating subscription",e,t,i),this.subscriptions.set(e,n),this.send("subscribe",{collection:t,docId:i,query:o}).then(s=>{s.subscriptionId&&(this.subscriptions.delete(e),this.subscriptions.set(s.subscriptionId,n));}).catch(s=>{this.log("Subscription failed",s),this.subscriptions.delete(e);}),()=>{this.log("Unsubscribing",e),this.subscriptions.delete(e),this.isConnected&&this.send("unsubscribe",{subscriptionId:e}).catch(s=>this.log("Unsubscribe failed",s));}}log(...e){this.isDebug&&console.log("[FlareClient]",...e);}},b=m;var T=class extends Error{constructor(t,i,o){super(t);this.code=i;this.cause=o;this.name="ZuzFlareError";}};var l=null,q=r=>(l||(l=new b(r),l.connect()),l),$=()=>l,G=()=>{l&&(l.disconnect(),l=null);};var J=b;
+Object.defineProperty(exports,"AuthGuard",{enumerable:true,get:function(){return auth.AuthGuard}});Object.defineProperty(exports,"Dropbox",{enumerable:true,get:function(){return auth.Dropbox}});Object.defineProperty(exports,"Google",{enumerable:true,get:function(){return auth.Google}});exports.CollectionReference=f;exports.DocumentQueryBuilder=a;exports.DocumentReference=h;exports.FlareAction=C;exports.FlareError=T;exports.FlareEvent=v;exports.connectApp=q;exports.default=J;exports.disconnectFlare=G;exports.getFlare=$;

package/dist/index.d.cts

@@ -0,0 +1,379 @@
+export { AuthGuard, AuthToken, Dropbox, Google, NormalizedProfile, OAuthProvider, ProviderId } from '@zuzjs/auth';
+
+/**
+ * Client Configuration
+ */
+interface FlareConfig {
+    /** WebSocket endpoint URL (e.g., 'http://localhost:5050' or 'wss://api.example.com') */
+    endpoint: string;
+    /** Application/Project ID */
+    appId: string;
+    /** API Key for authentication (optional) */
+    apiKey?: string;
+    /**
+     * RSA public key (PEM) returned by `flare app create`.
+     * When provided, all outgoing messages are wrapped in an RSA-OAEP encrypted
+     * envelope: `{ enc: "rsa", data: "<base64>" }` before being sent over the wire.
+     */
+    publicKey?: string;
+    /** Enable automatic reconnection (default: true) */
+    autoReconnect?: boolean;
+    /** Initial reconnect delay in seconds (default: 2) */
+    reconnectDelay?: number;
+    /** Maximum reconnect delay in seconds (default: 60) */
+    maxReconnectDelay?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Connection timeout in milliseconds (default: 10000) */
+    connectionTimeout?: number;
+}
+/**
+ * Query configuration (NEW v0.2: Object-based query syntax)
+ */
+interface QueryConfig {
+    field: string;
+    op: QueryOperator;
+    value: unknown;
+}
+/**
+ * Where condition (NEW v0.2: Object-based syntax)
+ * Example: { age: ">= 25", role: "admin" }
+ */
+type WhereCondition = Record<string, string | number | boolean | any[]>;
+type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains";
+/**
+ * Subscription callback
+ */
+type SubscriptionCallback<T = any> = (data: SubscriptionData<T>) => void;
+/**
+ * Subscription data received from server
+ */
+interface SubscriptionData<T = any> {
+    subscriptionId: string;
+    collection: string;
+    docId?: string;
+    data: T | T[];
+    type: 'snapshot' | 'change';
+    operation?: 'insert' | 'update' | 'delete' | 'replace';
+}
+/**
+ * Document reference
+ */
+interface DocumentSnapshot<T = any> {
+    id: string;
+    data: T | null;
+    exists: boolean;
+}
+/**
+ * Collection query result
+ */
+interface QuerySnapshot<T = any> {
+    docs: DocumentSnapshot<T>[];
+    size: number;
+    empty: boolean;
+}
+/**
+ * Offline operation
+ */
+interface OfflineOperation {
+    id: string;
+    type: 'write' | 'delete';
+    collection: string;
+    docId: string;
+    data?: Record<string, unknown>;
+    merge?: boolean;
+    clientTs: number;
+}
+/**
+ * Authentication result
+ */
+interface AuthResult {
+    uid: string;
+    token?: string;
+}
+/**
+ * Connection state
+ */
+type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error';
+
+/**
+ * Query builder for document operations (ORM-style)
+ * Supports: doc('users').update({...}).where({ id: 'alice' })
+ *
+ * This class is thenable - you can await it directly without .execute() or .get()
+ * @example
+ * await doc('users').where({ id: 'alice' })
+ * await doc('users').update({ name: 'Alice' }).where({ id: 'alice' })
+ */
+declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | void> {
+    private client;
+    private collection;
+    private legacyId?;
+    private whereCondition?;
+    private updateData?;
+    private setData?;
+    private deleteOp;
+    private promise?;
+    constructor(client: FlareClient, collection: string, legacyId?: string | undefined);
+    /**
+     * Set where condition
+     */
+    where(condition: WhereCondition): this;
+    /**
+     * Set update data (for update operations)
+     */
+    update(data: Partial<T>): this;
+    /**
+     * Set data (for set operations)
+     */
+    set(data: Partial<T>): this;
+    /**
+     * Mark for deletion
+     */
+    delete(): this;
+    /**
+     * Get the document ID from where condition or legacy id
+     */
+    private getDocId;
+    /**
+     * Execute the query
+     * @deprecated Use await directly instead of .execute()
+     */
+    execute(): Promise<T | null | void>;
+    /**
+     * Internal execute method
+     */
+    private _execute;
+    /**
+     * Make this class thenable so it can be awaited directly
+     */
+    then<TResult1 = T | null | void, TResult2 = never>(onfulfilled?: ((value: T | null | void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Get the document data once
+     */
+    get(): Promise<T | null>;
+    /**
+     * Subscribe to real-time updates
+     */
+    onSnapshot(callback: SubscriptionCallback<T>): () => void;
+}
+/**
+ * Legacy document reference (for backward compatibility)
+ */
+declare class DocumentReference<T = any> {
+    private client;
+    readonly collection: string;
+    readonly id: string;
+    constructor(client: FlareClient, collection: string, id: string);
+    get(): Promise<T | null>;
+    set(data: Partial<T>): Promise<void>;
+    update(data: Partial<T>): Promise<void>;
+    delete(): Promise<void>;
+    onSnapshot(callback: SubscriptionCallback<T>): () => void;
+}
+/**
+ * Collection reference with ORM-style query builder
+ *
+ * This class is thenable - you can await it directly without .get()
+ * @example
+ * await collection('users').where({ age: '>= 25' })
+ */
+declare class CollectionReference<T = any> implements PromiseLike<T[]> {
+    private client;
+    readonly collection: string;
+    private queries;
+    private promise?;
+    constructor(client: FlareClient, collection: string);
+    /**
+     * Get a document reference (legacy API)
+     */
+    doc(id: string): DocumentReference<T>;
+    /**
+     * Add a where filter (NEW ORM-style API)
+     * @example .where({ age: ">= 25", role: "admin" })
+     */
+    where(condition: WhereCondition): CollectionReference<T>;
+    /**
+     * Get all documents once
+     * @deprecated Use await directly instead of .get()
+     */
+    get(): Promise<T[]>;
+    /**
+     * Internal execute method
+     */
+    private _execute;
+    /**
+     * Make this class thenable so it can be awaited directly
+     */
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Subscribe to real-time updates
+     */
+    onSnapshot(callback: SubscriptionCallback<T[]>): () => void;
+    /**
+     * Add a new document with auto-generated ID
+     */
+    add(data: Partial<T>): Promise<DocumentReference<T>>;
+    /**
+     * Update documents matching the where condition
+     */
+    update(data: Partial<T>): DocumentQueryBuilder<T>;
+    /**
+     * Delete documents matching the where condition
+     */
+    delete(): DocumentQueryBuilder<T>;
+}
+
+/** Client Request */
+declare enum FlareAction {
+    SUBSCRIBE = "subscribe",
+    UNSUBSCRIBE = "unsubscribe",
+    WRITE = "write",
+    DELETE = "delete",
+    AUTH = "auth",
+    PING = "ping",
+    OFFLINE_SYNC = "offline_sync",
+    /** General-purpose RPC / topic call */
+    CALL = "call"
+}
+/** Server Response */
+declare enum FlareEvent {
+    SNAPSHOT = "snapshot",
+    CHANGE = "change",
+    ERROR = "error",
+    ACK = "ack",
+    PONG = "pong",
+    AUTH_OK = "auth_ok",
+    OFFLINE_ACK = "offline_ack",
+    /** Response to a CALL */
+    CALL_RESPONSE = "call_response"
+}
+interface BaseMessage {
+    id: string;
+    type: FlareAction | FlareEvent;
+    ts: number;
+}
+
+type ConnectionListener = (state: ConnectionState) => void;
+type ErrorListener = (error: Error) => void;
+declare class FlareClient {
+    private transport;
+    private readonly config;
+    private readonly pendingAcks;
+    private readonly subscriptions;
+    private readonly offlineQueue;
+    private currentState;
+    private connectionListeners;
+    private errorListeners;
+    private authToken?;
+    private userId?;
+    private isDebug;
+    constructor(config: FlareConfig);
+    /**
+     * Connect to the server
+     */
+    connect(): void;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+    /**
+     * Get a collection reference
+     */
+    collection<T = any>(name: string): CollectionReference<T>;
+    /**
+     * Get a document query builder (NEW ORM-style API)
+     * @example flare.doc('users').update({...}).where({ id: 'alice' })
+     */
+    doc<T = any>(collection: string): DocumentQueryBuilder<T>;
+    /**
+     * Get a document reference (Legacy API - deprecated)
+     * @deprecated Use doc(collection).where({ id: '...' }) instead
+     */
+    doc<T = any>(collection: string, id: string): DocumentReference<T>;
+    /**
+     * Authenticate with a token
+     */
+    auth(token: string): Promise<AuthResult>;
+    /**
+     * Sign out
+     */
+    signOut(): void;
+    /**
+     * Get current user ID
+     */
+    get currentUser(): string | undefined;
+    /**
+     * Get connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Listen to connection state changes
+     */
+    onConnectionStateChange(listener: ConnectionListener): () => void;
+    /**
+     * Listen to errors
+     */
+    onError(callback: ErrorListener): () => void;
+    /**
+     * Ping the server
+     */
+    ping(): Promise<number>;
+    /**
+     * Invoke a server-side CALL handler by topic and await its response.
+     *
+     * @example
+     *   const result = await flare.call("agent:backup", { name: "db-daily" });
+     *   console.log(result.jobId);
+     *
+     * @param topic   The topic registered with `flare.registerCallHandler(topic, fn)` on the server.
+     * @param payload Arbitrary JSON payload forwarded to the handler.
+     * @returns       The object returned by the server handler.
+     * @throws        If the server returns `success: false` or the request times out.
+     */
+    call<T = Record<string, unknown>>(topic: string, payload?: Record<string, unknown>): Promise<T>;
+    /**
+     * Sync offline operations
+     */
+    syncOffline(): Promise<void>;
+    private handleTransportError;
+    private onConnected;
+    private onDisconnected;
+    private setState;
+    private handleIncoming;
+    /**
+     * Internal: Send message to server
+     */
+    send(type: FlareAction, payload: any): Promise<any>;
+    /**
+     * Internal: Create a subscription
+     */
+    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | undefined, callback: SubscriptionCallback): () => void;
+    private log;
+}
+
+declare class FlareError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+
+/**
+ * Initialize and connect to FlareServer
+ * Returns a singleton instance
+ */
+declare const connectApp: (config: FlareConfig) => FlareClient;
+/**
+ * Get the current Flare instance
+ */
+declare const getFlare: () => FlareClient | null;
+/**
+ * Disconnect and reset the instance
+ */
+declare const disconnectFlare: () => void;
+
+export { type AuthResult, type BaseMessage, CollectionReference, type ConnectionState, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, FlareAction, type FlareConfig, FlareError, FlareEvent, type OfflineOperation, type QueryConfig, type QueryOperator, type QuerySnapshot, type SubscriptionCallback, type SubscriptionData, type WhereCondition, connectApp, FlareClient as default, disconnectFlare, getFlare };

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+export { AuthGuard, AuthToken, Dropbox, Google, NormalizedProfile, OAuthProvider, ProviderId } from '@zuzjs/auth';
+
+/**
+ * Client Configuration
+ */
+interface FlareConfig {
+    /** WebSocket endpoint URL (e.g., 'http://localhost:5050' or 'wss://api.example.com') */
+    endpoint: string;
+    /** Application/Project ID */
+    appId: string;
+    /** API Key for authentication (optional) */
+    apiKey?: string;
+    /**
+     * RSA public key (PEM) returned by `flare app create`.
+     * When provided, all outgoing messages are wrapped in an RSA-OAEP encrypted
+     * envelope: `{ enc: "rsa", data: "<base64>" }` before being sent over the wire.
+     */
+    publicKey?: string;
+    /** Enable automatic reconnection (default: true) */
+    autoReconnect?: boolean;
+    /** Initial reconnect delay in seconds (default: 2) */
+    reconnectDelay?: number;
+    /** Maximum reconnect delay in seconds (default: 60) */
+    maxReconnectDelay?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Connection timeout in milliseconds (default: 10000) */
+    connectionTimeout?: number;
+}
+/**
+ * Query configuration (NEW v0.2: Object-based query syntax)
+ */
+interface QueryConfig {
+    field: string;
+    op: QueryOperator;
+    value: unknown;
+}
+/**
+ * Where condition (NEW v0.2: Object-based syntax)
+ * Example: { age: ">= 25", role: "admin" }
+ */
+type WhereCondition = Record<string, string | number | boolean | any[]>;
+type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains";
+/**
+ * Subscription callback
+ */
+type SubscriptionCallback<T = any> = (data: SubscriptionData<T>) => void;
+/**
+ * Subscription data received from server
+ */
+interface SubscriptionData<T = any> {
+    subscriptionId: string;
+    collection: string;
+    docId?: string;
+    data: T | T[];
+    type: 'snapshot' | 'change';
+    operation?: 'insert' | 'update' | 'delete' | 'replace';
+}
+/**
+ * Document reference
+ */
+interface DocumentSnapshot<T = any> {
+    id: string;
+    data: T | null;
+    exists: boolean;
+}
+/**
+ * Collection query result
+ */
+interface QuerySnapshot<T = any> {
+    docs: DocumentSnapshot<T>[];
+    size: number;
+    empty: boolean;
+}
+/**
+ * Offline operation
+ */
+interface OfflineOperation {
+    id: string;
+    type: 'write' | 'delete';
+    collection: string;
+    docId: string;
+    data?: Record<string, unknown>;
+    merge?: boolean;
+    clientTs: number;
+}
+/**
+ * Authentication result
+ */
+interface AuthResult {
+    uid: string;
+    token?: string;
+}
+/**
+ * Connection state
+ */
+type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error';
+
+/**
+ * Query builder for document operations (ORM-style)
+ * Supports: doc('users').update({...}).where({ id: 'alice' })
+ *
+ * This class is thenable - you can await it directly without .execute() or .get()
+ * @example
+ * await doc('users').where({ id: 'alice' })
+ * await doc('users').update({ name: 'Alice' }).where({ id: 'alice' })
+ */
+declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | void> {
+    private client;
+    private collection;
+    private legacyId?;
+    private whereCondition?;
+    private updateData?;
+    private setData?;
+    private deleteOp;
+    private promise?;
+    constructor(client: FlareClient, collection: string, legacyId?: string | undefined);
+    /**
+     * Set where condition
+     */
+    where(condition: WhereCondition): this;
+    /**
+     * Set update data (for update operations)
+     */
+    update(data: Partial<T>): this;
+    /**
+     * Set data (for set operations)
+     */
+    set(data: Partial<T>): this;
+    /**
+     * Mark for deletion
+     */
+    delete(): this;
+    /**
+     * Get the document ID from where condition or legacy id
+     */
+    private getDocId;
+    /**
+     * Execute the query
+     * @deprecated Use await directly instead of .execute()
+     */
+    execute(): Promise<T | null | void>;
+    /**
+     * Internal execute method
+     */
+    private _execute;
+    /**
+     * Make this class thenable so it can be awaited directly
+     */
+    then<TResult1 = T | null | void, TResult2 = never>(onfulfilled?: ((value: T | null | void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Get the document data once
+     */
+    get(): Promise<T | null>;
+    /**
+     * Subscribe to real-time updates
+     */
+    onSnapshot(callback: SubscriptionCallback<T>): () => void;
+}
+/**
+ * Legacy document reference (for backward compatibility)
+ */
+declare class DocumentReference<T = any> {
+    private client;
+    readonly collection: string;
+    readonly id: string;
+    constructor(client: FlareClient, collection: string, id: string);
+    get(): Promise<T | null>;
+    set(data: Partial<T>): Promise<void>;
+    update(data: Partial<T>): Promise<void>;
+    delete(): Promise<void>;
+    onSnapshot(callback: SubscriptionCallback<T>): () => void;
+}
+/**
+ * Collection reference with ORM-style query builder
+ *
+ * This class is thenable - you can await it directly without .get()
+ * @example
+ * await collection('users').where({ age: '>= 25' })
+ */
+declare class CollectionReference<T = any> implements PromiseLike<T[]> {
+    private client;
+    readonly collection: string;
+    private queries;
+    private promise?;
+    constructor(client: FlareClient, collection: string);
+    /**
+     * Get a document reference (legacy API)
+     */
+    doc(id: string): DocumentReference<T>;
+    /**
+     * Add a where filter (NEW ORM-style API)
+     * @example .where({ age: ">= 25", role: "admin" })
+     */
+    where(condition: WhereCondition): CollectionReference<T>;
+    /**
+     * Get all documents once
+     * @deprecated Use await directly instead of .get()
+     */
+    get(): Promise<T[]>;
+    /**
+     * Internal execute method
+     */
+    private _execute;
+    /**
+     * Make this class thenable so it can be awaited directly
+     */
+    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Subscribe to real-time updates
+     */
+    onSnapshot(callback: SubscriptionCallback<T[]>): () => void;
+    /**
+     * Add a new document with auto-generated ID
+     */
+    add(data: Partial<T>): Promise<DocumentReference<T>>;
+    /**
+     * Update documents matching the where condition
+     */
+    update(data: Partial<T>): DocumentQueryBuilder<T>;
+    /**
+     * Delete documents matching the where condition
+     */
+    delete(): DocumentQueryBuilder<T>;
+}
+
+/** Client Request */
+declare enum FlareAction {
+    SUBSCRIBE = "subscribe",
+    UNSUBSCRIBE = "unsubscribe",
+    WRITE = "write",
+    DELETE = "delete",
+    AUTH = "auth",
+    PING = "ping",
+    OFFLINE_SYNC = "offline_sync",
+    /** General-purpose RPC / topic call */
+    CALL = "call"
+}
+/** Server Response */
+declare enum FlareEvent {
+    SNAPSHOT = "snapshot",
+    CHANGE = "change",
+    ERROR = "error",
+    ACK = "ack",
+    PONG = "pong",
+    AUTH_OK = "auth_ok",
+    OFFLINE_ACK = "offline_ack",
+    /** Response to a CALL */
+    CALL_RESPONSE = "call_response"
+}
+interface BaseMessage {
+    id: string;
+    type: FlareAction | FlareEvent;
+    ts: number;
+}
+
+type ConnectionListener = (state: ConnectionState) => void;
+type ErrorListener = (error: Error) => void;
+declare class FlareClient {
+    private transport;
+    private readonly config;
+    private readonly pendingAcks;
+    private readonly subscriptions;
+    private readonly offlineQueue;
+    private currentState;
+    private connectionListeners;
+    private errorListeners;
+    private authToken?;
+    private userId?;
+    private isDebug;
+    constructor(config: FlareConfig);
+    /**
+     * Connect to the server
+     */
+    connect(): void;
+    /**
+     * Disconnect from the server
+     */
+    disconnect(): void;
+    /**
+     * Get a collection reference
+     */
+    collection<T = any>(name: string): CollectionReference<T>;
+    /**
+     * Get a document query builder (NEW ORM-style API)
+     * @example flare.doc('users').update({...}).where({ id: 'alice' })
+     */
+    doc<T = any>(collection: string): DocumentQueryBuilder<T>;
+    /**
+     * Get a document reference (Legacy API - deprecated)
+     * @deprecated Use doc(collection).where({ id: '...' }) instead
+     */
+    doc<T = any>(collection: string, id: string): DocumentReference<T>;
+    /**
+     * Authenticate with a token
+     */
+    auth(token: string): Promise<AuthResult>;
+    /**
+     * Sign out
+     */
+    signOut(): void;
+    /**
+     * Get current user ID
+     */
+    get currentUser(): string | undefined;
+    /**
+     * Get connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Listen to connection state changes
+     */
+    onConnectionStateChange(listener: ConnectionListener): () => void;
+    /**
+     * Listen to errors
+     */
+    onError(callback: ErrorListener): () => void;
+    /**
+     * Ping the server
+     */
+    ping(): Promise<number>;
+    /**
+     * Invoke a server-side CALL handler by topic and await its response.
+     *
+     * @example
+     *   const result = await flare.call("agent:backup", { name: "db-daily" });
+     *   console.log(result.jobId);
+     *
+     * @param topic   The topic registered with `flare.registerCallHandler(topic, fn)` on the server.
+     * @param payload Arbitrary JSON payload forwarded to the handler.
+     * @returns       The object returned by the server handler.
+     * @throws        If the server returns `success: false` or the request times out.
+     */
+    call<T = Record<string, unknown>>(topic: string, payload?: Record<string, unknown>): Promise<T>;
+    /**
+     * Sync offline operations
+     */
+    syncOffline(): Promise<void>;
+    private handleTransportError;
+    private onConnected;
+    private onDisconnected;
+    private setState;
+    private handleIncoming;
+    /**
+     * Internal: Send message to server
+     */
+    send(type: FlareAction, payload: any): Promise<any>;
+    /**
+     * Internal: Create a subscription
+     */
+    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | undefined, callback: SubscriptionCallback): () => void;
+    private log;
+}
+
+declare class FlareError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+
+/**
+ * Initialize and connect to FlareServer
+ * Returns a singleton instance
+ */
+declare const connectApp: (config: FlareConfig) => FlareClient;
+/**
+ * Get the current Flare instance
+ */
+declare const getFlare: () => FlareClient | null;
+/**
+ * Disconnect and reset the instance
+ */
+declare const disconnectFlare: () => void;
+
+export { type AuthResult, type BaseMessage, CollectionReference, type ConnectionState, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, FlareAction, type FlareConfig, FlareError, FlareEvent, type OfflineOperation, type QueryConfig, type QueryOperator, type QuerySnapshot, type SubscriptionCallback, type SubscriptionData, type WhereCondition, connectApp, FlareClient as default, disconnectFlare, getFlare };

package/dist/index.js

@@ -0,0 +1,2 @@
+import {uuid2}from'@zuzjs/core';export{AuthGuard,Dropbox,Google}from'@zuzjs/auth';var v=(c=>(c.SUBSCRIBE="subscribe",c.UNSUBSCRIBE="unsubscribe",c.WRITE="write",c.DELETE="delete",c.AUTH="auth",c.PING="ping",c.OFFLINE_SYNC="offline_sync",c.CALL="call",c))(v||{}),S=(c=>(c.SNAPSHOT="snapshot",c.CHANGE="change",c.ERROR="error",c.ACK="ack",c.PONG="pong",c.AUTH_OK="auth_ok",c.OFFLINE_ACK="offline_ack",c.CALL_RESPONSE="call_response",c))(S||{});function w(r){let e=[];for(let[t,i]of Object.entries(r))if(typeof i=="string"){let o=i.match(/^(>=|<=|!=|>|<|==)\s*(.+)$/);if(o){let[,n,s]=o;e.push({field:t,op:n,value:R(s.trim())});}else e.push({field:t,op:"==",value:i});}else Array.isArray(i)?e.push({field:t,op:"in",value:i}):e.push({field:t,op:"==",value:i});return e}function R(r){if(!isNaN(Number(r)))return Number(r);if(r==="true")return  true;if(r==="false")return  false;if(r==="null")return null;if(r!=="undefined")return r}var a=class{constructor(e,t,i){this.client=e;this.collection=t;this.legacyId=i;}whereCondition;updateData;setData;deleteOp=false;promise;where(e){return this.whereCondition=e,this}update(e){return this.updateData=e,this}set(e){return this.setData=e,this}delete(){return this.deleteOp=true,this}getDocId(){if(this.legacyId)return this.legacyId;if(this.whereCondition&&this.whereCondition.id){let e=this.whereCondition.id;if(typeof e=="string")return e}throw new Error('Document ID not specified. Use .where({ id: "..." }) or doc(collection, id)')}async execute(){return this._execute()}async _execute(){let e=this.getDocId();if(this.deleteOp){await this.client.send("delete",{collection:this.collection,docId:e});return}if(this.updateData){await this.client.send("write",{collection:this.collection,docId:e,data:this.updateData,merge:true});return}if(this.setData){await this.client.send("write",{collection:this.collection,docId:e,data:this.setData,merge:false});return}return this.get()}then(e,t){return this.promise||(this.promise=this._execute()),this.promise.then(e,t)}async get(){let e=this.getDocId(),t=uuid2(18);return new Promise((i,o)=>{let n=this.client.subscribe(t,this.collection,e,void 0,s=>{s.type==="snapshot"&&(n(),i(s.data));});setTimeout(()=>{n(),o(new Error("Document fetch timeout"));},1e4);})}onSnapshot(e){let t=this.getDocId(),i=uuid2(18);return this.client.subscribe(i,this.collection,t,void 0,e)}},h=class{constructor(e,t,i){this.client=e;this.collection=t;this.id=i;}async get(){return new a(this.client,this.collection,this.id).get()}async set(e){await this.client.send("write",{collection:this.collection,docId:this.id,data:e,merge:false});}async update(e){await this.client.send("write",{collection:this.collection,docId:this.id,data:e,merge:true});}async delete(){await this.client.send("delete",{collection:this.collection,docId:this.id});}onSnapshot(e){let t=uuid2(18);return this.client.subscribe(t,this.collection,this.id,void 0,e)}},g=class r{constructor(e,t){this.client=e;this.collection=t;}queries=[];promise;doc(e){return new h(this.client,this.collection,e)}where(e){let t=new r(this.client,this.collection),i=w(e);return t.queries=[...this.queries,...i],t}async get(){return this._execute()}async _execute(){let e=uuid2(18);return new Promise((t,i)=>{let o=this.queries.length>0?this.queries:void 0,n=this.client.subscribe(e,this.collection,void 0,o,s=>{s.type==="snapshot"&&(n(),t(Array.isArray(s.data)?s.data:[s.data]));});setTimeout(()=>{n(),i(new Error("Collection fetch timeout"));},1e4);})}then(e,t){return this.promise||(this.promise=this._execute()),this.promise.then(e,t)}onSnapshot(e){let t=uuid2(18),i=this.queries.length>0?this.queries:void 0;return this.client.subscribe(t,this.collection,void 0,i,e)}async add(e){let t=uuid2(18),i=this.doc(t);return await i.set(e),i}update(e){return new a(this.client,this.collection).update(e)}delete(){return new a(this.client,this.collection).delete()}};async function I(r){let e=r.replace(/-----BEGIN PUBLIC KEY-----/,"").replace(/-----END PUBLIC KEY-----/,"").replace(/\s+/g,""),t=typeof atob<"u"?atob(e):Buffer.from(e,"base64").toString("binary"),i=new Uint8Array(t.length);for(let n=0;n<t.length;n++)i[n]=t.charCodeAt(n);return (globalThis.crypto??(await import('crypto')).webcrypto).subtle.importKey("spki",i.buffer,{name:"RSA-OAEP",hash:"SHA-256"},false,["encrypt"])}async function E(r,e){let t=await I(e),i=new TextEncoder().encode(JSON.stringify(r)),n=await(globalThis.crypto??(await import('crypto')).webcrypto).subtle.encrypt({name:"RSA-OAEP"},t,i),s=typeof btoa<"u"?btoa(String.fromCharCode(...new Uint8Array(n))):Buffer.from(n).toString("base64");return JSON.stringify({enc:"rsa",data:s})}var y=class{socket=null;reconnectInterval;maxReconnectDelay;isConnected=false;shouldReconnect=true;options;messageQueue=[];heartbeatInterval=null;connectionTimeout=null;constructor(e){this.options=e,this.reconnectInterval=e.reconnectDelay||2,this.maxReconnectDelay=e.maxReconnectDelay||60,this.log("Transport initialized",e.url);}connect(){if(this.socket){this.log("Socket already exists, skipping connection");return}this.log("Connecting to",this.options.url),this.socket=new WebSocket(this.options.url),this.connectionTimeout=setTimeout(()=>{this.isConnected||(this.log("Connection timeout"),this.socket?.close(),this.handleReconnect());},1e4),this.socket.onopen=()=>{this.connectionTimeout&&(clearTimeout(this.connectionTimeout),this.connectionTimeout=null),this.isConnected=true,this.reconnectInterval=this.options.reconnectDelay||2,this.log("Connected to server"),this.options.onOpen?.(),this.startHeartbeat(),this.flushQueue();},this.socket.onmessage=e=>{try{let t=JSON.parse(e.data);this.options.onMessage(t);}catch(t){this.log("Parse error",t),this.options.onError?.(t);}},this.socket.onerror=e=>{this.log("WebSocket error",e),this.options.onError?.(new Error("WebSocket error"));},this.socket.onclose=e=>{this.connectionTimeout&&(clearTimeout(this.connectionTimeout),this.connectionTimeout=null),this.isConnected=false,this.socket=null,this.stopHeartbeat(),this.log("Connection closed",e.code,e.reason),this.options.onClose?.(),e.code!==1e3&&this.shouldReconnect&&this.options.autoReconnect&&this.handleReconnect();};}handleReconnect(){let e=this.reconnectInterval*1e3;this.log(`Reconnecting in ${this.reconnectInterval}s...`),setTimeout(()=>{this.reconnectInterval=Math.min(this.reconnectInterval*2,this.maxReconnectDelay),this.connect();},e);}startHeartbeat(){this.heartbeatInterval=setInterval(()=>{this.isConnected&&this.send({type:"ping",id:Date.now().toString(),ts:Date.now()});},3e4);}stopHeartbeat(){this.heartbeatInterval&&(clearInterval(this.heartbeatInterval),this.heartbeatInterval=null);}flushQueue(){for(this.log("Flushing message queue",this.messageQueue.length);this.messageQueue.length>0;){let e=this.messageQueue.shift();e&&this.send(e);}}send(e){if(this.socket&&this.socket.readyState===WebSocket.OPEN){let t=i=>{try{this.socket.send(i),this.log("Sent message",e);}catch(o){this.log("Send error",o),this.messageQueue.push(e);}};this.options.publicKey?E(e,this.options.publicKey).then(t).catch(i=>{this.log("RSA encrypt error \u2014 sending plaintext",i),t(JSON.stringify(e));}):t(JSON.stringify(e));}else this.log("Socket not ready, queueing message"),this.messageQueue.push(e);}disconnect(){this.shouldReconnect=false,this.stopHeartbeat(),this.socket&&(this.socket.close(1e3,"Client disconnect"),this.socket=null),this.isConnected=false,this.log("Disconnected");}get connected(){return this.isConnected}log(...e){this.options.debug&&console.log("[FlareTransport]",...e);}};var b=class{transport;config;pendingAcks=new Map;subscriptions=new Map;offlineQueue=[];currentState="disconnected";connectionListeners=[];errorListeners=[];authToken;userId;isDebug=false;constructor(e){this.config={autoReconnect:true,reconnectDelay:2,maxReconnectDelay:60,debug:false,connectionTimeout:1e4,...e},this.isDebug=this.config.debug||false;let{hostname:t,port:i,protocol:o}=new URL(this.config.endpoint),n=o==="https:",c=`${n?"wss":"ws"}://${t}:${i||(n?"443":"80")}/?appId=${this.config.appId}${this.config.apiKey?`&apiKey=${this.config.apiKey}`:""}`;this.transport=new y({url:c,publicKey:this.config.publicKey,autoReconnect:this.config.autoReconnect,reconnectDelay:this.config.reconnectDelay,maxReconnectDelay:this.config.maxReconnectDelay,onMessage:m=>this.handleIncoming(m),onOpen:()=>this.onConnected(),onClose:()=>this.onDisconnected(),onError:m=>this.handleTransportError(m),debug:this.isDebug}),this.log("FlareClient initialized",e);}connect(){this.setState("connecting"),this.transport.connect();}disconnect(){this.transport.disconnect(),this.setState("disconnected");}collection(e){return new g(this,e)}doc(e,t){return t!==void 0?new h(this,e,t):new a(this,e)}async auth(e){let t=await this.send("auth",{token:e});if(t.type==="auth_ok")return this.authToken=e,this.userId=t.uid,this.log("Authentication successful",t.uid),{uid:t.uid,token:e};throw new Error("Authentication failed")}signOut(){this.authToken=void 0,this.userId=void 0,this.log("Signed out");}get currentUser(){return this.userId}get connectionState(){return this.currentState}get isConnected(){return this.currentState==="connected"}onConnectionStateChange(e){return this.connectionListeners.push(e),()=>{this.connectionListeners=this.connectionListeners.filter(t=>t!==e);}}onError(e){return this.errorListeners.push(e),()=>{this.errorListeners=this.errorListeners.filter(t=>t!==e);}}async ping(){let e=Date.now();return await this.send("ping",{}),Date.now()-e}async call(e,t={}){let i=await this.send("call",{topic:e,payload:t});if(!i.success)throw new Error(i.error??`CALL "${e}" failed`);return i.result}async syncOffline(){if(this.offlineQueue.length===0)return;this.log("Syncing offline operations",this.offlineQueue.length);let e=[...this.offlineQueue];this.offlineQueue.length=0;let t=await this.send("offline_sync",{operations:e});t.conflicts&&t.conflicts.length>0&&(this.log("Offline sync conflicts",t.conflicts),t.conflicts.forEach(i=>{let o=e.find(n=>n.id===i.operationId);o&&this.offlineQueue.push(o);}));}handleTransportError(e){this.log("Transport error",e),this.errorListeners.forEach(t=>{try{t(e);}catch(i){this.log("Error listener error",i);}});}onConnected(){this.setState("connected"),this.log("Connected to FlareServer"),this.offlineQueue.length>0&&this.syncOffline().catch(e=>{this.log("Offline sync failed",e);});}onDisconnected(){this.currentState!=="disconnected"&&this.setState("reconnecting"),this.log("Disconnected from FlareServer");}setState(e){this.currentState!==e&&(this.currentState=e,this.log("Connection state changed",e),this.connectionListeners.forEach(t=>{try{t(e);}catch(i){this.log("Connection listener error",i);}}));}handleIncoming(e){if(this.log("Received message",e.type,e),e.type==="ack"||e.type==="pong"||e.type==="auth_ok"||e.type==="call_response"){let t=this.pendingAcks.get(e.correlationId||e.id);t&&(t(e),this.pendingAcks.delete(e.correlationId||e.id));return}if(e.type==="error"){this.log("Server error",e.code,e.message);let t=new Error(`[${e.code}] ${e.message}`);if(this.errorListeners.forEach(i=>{try{i(t);}catch(o){this.log("Error listener error",o);}}),e.correlationId){let i=this.pendingAcks.get(e.correlationId);i&&(i(e),this.pendingAcks.delete(e.correlationId));}return}if(e.type==="snapshot"||e.type==="change"){let t=this.subscriptions.get(e.subscriptionId);if(t){let i={subscriptionId:e.subscriptionId,collection:e.collection,docId:e.docId,data:e.data,type:e.type==="snapshot"?"snapshot":"change",operation:e.operation};try{t(i);}catch(o){this.log("Subscription callback error",o);}}}}async send(e,t){return new Promise((i,o)=>{let n=uuid2(18),s={id:n,type:e,ts:Date.now(),...t};this.pendingAcks.set(n,d=>{d.type==="error"?o(new Error(`[${d.code}] ${d.message}`)):i(d);}),this.isConnected?this.transport.send(s):(this.log("Queueing message for offline",s),this.offlineQueue.push(s),o(new Error("Not connected - message queued"))),setTimeout(()=>{this.pendingAcks.has(n)&&(this.pendingAcks.delete(n),o(new Error("Request timeout")));},this.config.connectionTimeout);})}subscribe(e,t,i,o,n){return this.log("Creating subscription",e,t,i),this.subscriptions.set(e,n),this.send("subscribe",{collection:t,docId:i,query:o}).then(s=>{s.subscriptionId&&(this.subscriptions.delete(e),this.subscriptions.set(s.subscriptionId,n));}).catch(s=>{this.log("Subscription failed",s),this.subscriptions.delete(e);}),()=>{this.log("Unsubscribing",e),this.subscriptions.delete(e),this.isConnected&&this.send("unsubscribe",{subscriptionId:e}).catch(s=>this.log("Unsubscribe failed",s));}}log(...e){this.isDebug&&console.log("[FlareClient]",...e);}},T=b;var C=class extends Error{constructor(t,i,o){super(t);this.code=i;this.cause=o;this.name="ZuzFlareError";}};var l=null,$=r=>(l||(l=new T(r),l.connect()),l),G=()=>l,J=()=>{l&&(l.disconnect(),l=null);};var M=T;
+export{g as CollectionReference,a as DocumentQueryBuilder,h as DocumentReference,v as FlareAction,C as FlareError,S as FlareEvent,$ as connectApp,M as default,J as disconnectFlare,G as getFlare};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zuzjs/flare",
+  "version": "0.2.1",
+  "keywords": [
+    "core",
+    "zuz",
+    "zuz.js",
+    "zuz flare",
+    "zuz flare client",
+    "zuzjs"
+  ],
+  "description": "Official JavaScript/TypeScript client for ZuzFlare Server - Self-hosted real-time database",
+  "author": "Zuz.js Team <support@zuz.com.pk>",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zuzjs/flare-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zuzjs/flare-client/issues"
+  },
+  "homepage": "https://flare.zedgon.io",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "sideEffects": [
+    "reflect-metadata"
+  ],
+  "dependencies": {
+    "@zuzjs/auth": "^0.1.7",
+    "@zuzjs/core": "^0.3.8"
+  }
+}