@zuzjs/flare-admin 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @zuzjs/flare-admin
+ *
+ * Server-side admin SDK for FlareServer.
+ * Runs only on your backend, never in a browser.
+ *
+ * ─── Quick start ──────────────────────────────────────────────────────────────
+ *
+ *   import { connectApp } from "@zuzjs/flare-admin";
+ *
+ *   const admin = connectApp({
+ *     serverUrl: process.env.FLARE_URL!,
+ *     appId:     process.env.FLARE_APP_ID!,
+ *     adminKey:  process.env.FLARE_ADMIN_KEY!,
+ *   });
+ *
+ *   // Mint a custom auth token (for use by the browser client)
+ *   const token = await admin.auth().createCustomToken(String(user.id), {
+ *     role:   user.isAdmin ? "admin" : "user",
+ *     claims: { email: user.email, plan: user.plan },
+ *   });
+ *
+ *   // One-shot DB queries (bypasses security rules)
+ *   const users = await admin.db().collection("users").get();
+ *   await admin.db().collection("users").doc("alice").set({ name: "Alice" });
+ *
+ *   // Rich queries
+ *   const seniors = await admin.db()
+ *     .collection("users")
+ *     .where({ age: ">= 60" })
+ *     .orderBy("name")
+ *     .limit(10)
+ *     .get();
+ *
+ *   // Real-time subscriptions over WebSocket
+ *   const unsub = admin.connection()
+ *     .collection("orders")
+ *     .where({ status: "pending" })
+ *     .orderBy("createdAt", "desc")
+ *     .onSnapshot((snap) => console.log(snap));
+ */
+export type { AdminDocAddedCallback, AdminDocChangedCallback, AdminDocDeletedCallback, AdminDocUpdatedCallback, AdminPushSendInput, AdminPushSendResult, AdminPushToken, AdminSnapshotCallback, AdminSnapshotData, AdminSubscriptionError, AdminSubscriptionErrorCallback, AdminSubscriptionHandle, AggregateFunction, AggregateSpec, AnyFilter, CreateCustomTokenOptions, CursorValue, FlareAdminAuth, FlareAdminConfig, FlareAdminDb, FlareAdminNotifications, GroupByClause, HavingClause, JoinClause, OrderByClause, OrFilter, QueryOperator, StructuredQuery, VectorSearchClause, WhereCondition, WhereFilter } from "./types";
+export { AdminCollectionReference } from "./db/Collection";
+export { AdminDocumentReference } from "./db/Document";
+export { FlareAdminDbService } from "./db/index";
+export { FlareAdminAuthService } from "./lib/auth";
+export { FlareAdminNotificationsService } from "./lib/notifications";
+export { FlareAdminConnection } from "./realtime/Connection";
+export { AdminLiveCollectionReference } from "./realtime/LiveCollection";
+export { AdminLiveDocumentReference } from "./realtime/LiveDocument";
+export { FlareAdminWsConnection } from "./realtime/WsConnection";
+import { FlareAdminConnection } from "./realtime/Connection";
+import { FlareAdminAuth, FlareAdminConfig, FlareAdminDb, FlareAdminNotifications } from "./types";
+/**
+ * A FlareAdmin application instance.
+ * Create one with `connectApp()` and keep it as a module-level singleton.
+ */
+export declare class FlareAdminApp {
+    private readonly cfg;
+    private _auth?;
+    private _db?;
+    private _conn?;
+    private _notifications?;
+    /**
+     * Access the auth service.
+     *
+     * @example
+     *   const token = await admin.auth().createCustomToken(uid, { role: "user" });
+     */
+    auth(): FlareAdminAuth;
+    /**
+     * Access the database service.
+     * All operations bypass security rules — admin has full read/write access.
+     *
+     * Supports the full StructuredQuery builder API:
+    * `where`, `and`, `or`, `orderBy`, `limit`, `offset`,
+     * `startAt/After`, `endAt/Before`, `count/sum/avg/min/max/distinct`,
+    * `groupBy`, `having`, `Join`, `select`, `distinctField`, `vectorSearch`.
+     *
+     * @example
+     *   const users  = await admin.db().collection("users").get();
+    *   const admins = await admin.db().collection("users")
+     *     .where({ role: "admin" }).orderBy("name").get();
+     *   const [{ count }] = await admin.db().collection("users").count().get();
+     *   await admin.db().collection("users").doc("alice").update({ plan: "pro" });
+     */
+    db(): FlareAdminDb;
+    /**
+     * Open (or reuse) a persistent admin WebSocket connection.
+     * One socket is shared per app instance — call `.disconnect()` when done.
+     *
+     * Supports the full query-builder API on live subscriptions:
+    * `where`, `and`, `or`, `orderBy`, `limit`, `offset`,
+     * `startAt/After`, `endAt/Before`, `count/sum/avg/min/max/distinct`,
+    * `groupBy`, `having`, `Join`, `select`, `distinctField`, `vectorSearch`.
+     *
+     * @example
+     *   const unsub = admin.connection()
+     *     .collection("orders")
+     *     .where({ status: "pending" })
+     *     .orderBy("createdAt", "desc")
+     *     .limit(50)
+     *     .onSnapshot((snap) => {
+     *       if (snap.type === "snapshot") console.log("initial:", snap.data);
+     *       else console.log(snap.operation, snap.data);
+     *     });
+     *
+     *   const unsub2 = admin.connection()
+     *     .collection("users").doc("alice")
+     *     .onSnapshot((snap) => console.log(snap.data));
+     *
+     *   unsub();
+     *   unsub2();
+     *   admin.connection().disconnect();
+     */
+    connection(): FlareAdminConnection;
+    /**
+     * Access push notification management APIs.
+     */
+    notifications(): FlareAdminNotifications;
+}
+/**
+ * Initialize a FlareAdmin app instance.
+ * Call once at server boot. Calling again with the same name is idempotent.
+ *
+ * @param config  Server coordinates + admin key.
+ * @param name    App name for multi-tenant setups (default: `"[DEFAULT]"`).
+ *
+ * @example
+ *   const admin = connectApp({
+ *     serverUrl: process.env.FLARE_URL!,
+ *     appId:     process.env.FLARE_APP_ID!,
+ *     adminKey:  process.env.FLARE_ADMIN_KEY!,
+ *   });
+ */
+export declare function connectApp(config: FlareAdminConfig, name?: string): FlareAdminApp;
+/**
+ * Retrieve an already-initialized app by name.
+ * @throws If the app has not been initialized yet.
+ */
+export declare function getApp(name?: string): FlareAdminApp;
+/**
+ * Get the auth service from the default app.
+ * Equivalent to `getApp().auth()`.
+ *
+ * @example
+ *   import { auth } from "@zuzjs/flare-admin";
+ *   const token = await auth().createCustomToken(uid);
+ */
+export declare function auth(name?: string): FlareAdminAuth;
+/**
+ * Get the db service from the default app.
+ * Equivalent to `getApp().db()`.
+ *
+ * @example
+ *   import { db } from "@zuzjs/flare-admin";
+ *   const users = await db().collection("users").get();
+ */
+export declare function db(name?: string): FlareAdminDb;
+/**
+ * Get the real-time WebSocket connection from the default app.
+ * Equivalent to `getApp().connection()`.
+ *
+ * @example
+ *   import { connection } from "@zuzjs/flare-admin";
+ *   const unsub = connection().collection("users")
+ *     .where({ role: "admin" })
+ *     .onSnapshot((snap) => console.log(snap));
+ */
+export declare function connection(name?: string): FlareAdminConnection;
+/**
+ * Get the notifications service from the default app.
+ * Equivalent to `getApp().notifications()`.
+ */
+export declare function notifications(name?: string): FlareAdminNotifications;

package/dist/index.js

@@ -0,0 +1,2 @@
+import q from'ws';function S(o){let e=[];for(let[n,r]of Object.entries(o))if(typeof r=="string"){let t=r.match(/^(>=|<=|!=|>|<|==)\s*(.+)$/);if(t){let[,i,s]=t;e.push({field:n,op:i,value:E(s.trim())});}else e.push({field:n,op:"==",value:r});}else Array.isArray(r)?e.push({field:n,op:"in",value:r}):e.push({field:n,op:"==",value:r});return e}function E(o){return isNaN(Number(o))?o==="true"?true:o==="false"?false:o==="null"?null:o:Number(o)}function T(){return Math.random().toString(36).slice(2,12)+Date.now().toString(36)}var f=class{constructor(e,n,r){this.cfg=e;this.collection=n;this.id=r;}get baseUrl(){return `${this.cfg.serverUrl}/admin/db/${this.cfg.appId}/${this.collection}/${this.id}`}get headers(){return {"Content-Type":"application/json",Authorization:`Bearer ${this.cfg.adminKey}`}}async request(e,n){let r;try{r=await fetch(this.baseUrl,{method:e,headers:this.headers,...n!==void 0?{body:JSON.stringify(n)}:{}});}catch(i){let s=i instanceof Error?i.message:String(i);throw new Error(`[flare-admin] Network error (${e} ${this.baseUrl}): ${s}`)}let t=await r.json().catch(()=>({}));if(!r.ok)throw new Error(`[flare-admin] ${e} ${this.baseUrl} failed (HTTP ${r.status}): `+(t.error??"Unknown error"));return t}async get(){let e;try{e=await fetch(this.baseUrl,{headers:this.headers});}catch(r){let t=r instanceof Error?r.message:String(r);throw new Error(`[flare-admin] Network error (GET ${this.baseUrl}): ${t}`)}if(e.status===404)return null;let n=await e.json().catch(()=>({}));if(!e.ok)throw new Error(`[flare-admin] GET ${this.baseUrl} failed (HTTP ${e.status}): `+(n.error??"Unknown error"));return n.data??null}async set(e){await this.request("PUT",e);}async update(e){await this.request("PATCH",e);}async delete(){await this.request("DELETE");}parent(){return new m(this.cfg,this.collection)}};var m=class o{constructor(e,n){this.cfg=e;this.name=n;this.sq={};this.opts={allowSensitiveAuthUserFields:true};}get baseUrl(){return `${this.cfg.serverUrl}/admin/db/${this.cfg.appId}/${this.name}`}get headers(){return {"Content-Type":"application/json",Authorization:`Bearer ${this.cfg.adminKey}`}}clone(e){let n=new o(this.cfg,this.name);return n.sq={...this.sq,...e},n.opts={...this.opts},n}allowSensitiveAuthUserFields(e=true){let n=this.clone({});return n.opts.allowSensitiveAuthUserFields=!!e,n}normalizeFilterValue(e,n){return e==="in"||e==="not-in"||e==="array-contains-any"?Array.isArray(n)?n:[n]:n}toQueryFilters(e){return S(e).map(r=>typeof r=="object"&&r!=null&&"field"in r&&"op"in r?{...r,value:this.normalizeFilterValue(r.op,r.value)}:r)}appendAndFilters(e){return this.clone({where:[...this.sq.where??[],...e]})}appendOrFilters(e){let n=[...this.sq.where??[]];if(n.length===0)return this.clone({where:[{or:e}]});let r=n[0];if(n.length===1&&typeof r=="object"&&r!=null&&"or"in r)return this.clone({where:[{or:[...r.or,...e]}]});let i=n.length===1?n[0]:{and:n};return this.clone({where:[{or:[i,...e]}]})}appendFilters(e,n){return n==="or"?this.appendOrFilters(e):this.appendAndFilters(e)}appendOperatorFilter(e,n,r,t){return this.appendFilters([{field:e,op:n,value:this.normalizeFilterValue(n,r)}],t)}where(e){return this.appendFilters(this.toQueryFilters(e),"and")}and(e){return this.appendFilters(this.toQueryFilters(e),"and")}or(e){return this.appendFilters(this.toQueryFilters(e),"or")}in(e,n){return this.appendOperatorFilter(e,"in",n,"and")}andIn(e,n){return this.appendOperatorFilter(e,"in",n,"and")}orIn(e,n){return this.appendOperatorFilter(e,"in",n,"or")}notIn(e,n){return this.appendOperatorFilter(e,"not-in",n,"and")}andNotIn(e,n){return this.appendOperatorFilter(e,"not-in",n,"and")}orNotIn(e,n){return this.appendOperatorFilter(e,"not-in",n,"or")}arrayContains(e,n){return this.appendOperatorFilter(e,"array-contains",n,"and")}andArrayContains(e,n){return this.appendOperatorFilter(e,"array-contains",n,"and")}orArrayContains(e,n){return this.appendOperatorFilter(e,"array-contains",n,"or")}arrayContainsAny(e,n){return this.appendOperatorFilter(e,"array-contains-any",n,"and")}andArrayContainsAny(e,n){return this.appendOperatorFilter(e,"array-contains-any",n,"and")}orArrayContainsAny(e,n){return this.appendOperatorFilter(e,"array-contains-any",n,"or")}some(e,n){return this.appendOperatorFilter(e,"elem-match",n,"and")}andSome(e,n){return this.appendOperatorFilter(e,"elem-match",n,"and")}orSome(e,n){return this.appendOperatorFilter(e,"elem-match",n,"or")}like(e,n){return this.appendOperatorFilter(e,"like",n,"and")}andLike(e,n){return this.appendOperatorFilter(e,"like",n,"and")}orLike(e,n){return this.appendOperatorFilter(e,"like",n,"or")}notLike(e,n){return this.appendOperatorFilter(e,"not-like",n,"and")}andNotLike(e,n){return this.appendOperatorFilter(e,"not-like",n,"and")}orNotLike(e,n){return this.appendOperatorFilter(e,"not-like",n,"or")}exists(e){return this.appendOperatorFilter(e,"exists",true,"and")}andExists(e){return this.appendOperatorFilter(e,"exists",true,"and")}orExists(e){return this.appendOperatorFilter(e,"exists",true,"or")}notExists(e){return this.appendOperatorFilter(e,"not-exists",true,"and")}andNotExists(e){return this.appendOperatorFilter(e,"not-exists",true,"and")}orNotExists(e){return this.appendOperatorFilter(e,"not-exists",true,"or")}latest(){return this.clone({orderBy:[...this.sq.orderBy??[],{field:"_seq",dir:"desc"}]})}newest(){return this.latest()}oldest(){return this.clone({orderBy:[...this.sq.orderBy??[],{field:"_seq",dir:"asc"}]})}orderBy(e,n="asc"){return this.clone({orderBy:[...this.sq.orderBy??[],{field:e,dir:n}]})}limit(e){return this.clone({limit:e})}offset(e){return this.clone({offset:e})}startAt(...e){return this.clone({startAt:{values:e}})}startAfter(...e){return this.clone({startAfter:{values:e}})}endAt(...e){return this.clone({endAt:{values:e}})}endBefore(...e){return this.clone({endBefore:{values:e}})}aggregate(...e){return this.clone({aggregate:[...this.sq.aggregate??[],...e]})}count(e="count"){return this.aggregate({fn:"count",alias:e})}sum(e,n){return this.aggregate({fn:"sum",field:e,alias:n??`sum_${e}`})}avg(e,n){return this.aggregate({fn:"avg",field:e,alias:n??`avg_${e}`})}min(e,n){return this.aggregate({fn:"min",field:e,alias:n??`min_${e}`})}max(e,n){return this.aggregate({fn:"max",field:e,alias:n??`max_${e}`})}distinct(e,n){return this.aggregate({fn:"distinct",field:e,alias:n??`distinct_${e}`})}groupBy(...e){return this.clone({groupBy:{fields:e}})}having(e,n,r){return this.clone({having:[...this.sq.having??[],{field:e,op:n,value:r}]})}buildStructuredJoin(e,n){let r={from:String(e??""),localField:String(n?.source??""),foreignField:String(n?.target??""),as:String(n?.as??""),single:n?.single};return Array.isArray(n?.where)&&(r.where=n.where),Array.isArray(n?.orderBy)&&(r.orderBy=n.orderBy),typeof n?.limit=="number"&&(r.limit=n.limit),typeof n?.offset=="number"&&(r.offset=n.offset),Array.isArray(n?.select)&&(r.select=n.select),Array.isArray(n?.joins)&&(r.joins=n.joins.map(t=>this.buildStructuredJoin(String(t?.collection??""),t))),r}cloneStructuredJoin(e){let n={...e};return Array.isArray(e.where)&&(n.where=e.where.map(r=>({...r}))),Array.isArray(e.orderBy)&&(n.orderBy=e.orderBy.map(r=>({...r}))),Array.isArray(e.select)&&(n.select=[...e.select]),Array.isArray(e.joins)&&(n.joins=e.joins.map(r=>this.cloneStructuredJoin(r))),n}appendNestedJoinByAlias(e,n,r){for(let t of e){if(t.as===n)return t.joins=[...t.joins??[],r],true;if(Array.isArray(t.joins)&&this.appendNestedJoinByAlias(t.joins,n,r))return  true}return  false}parseRelationRef(e){let r=String(e??"").trim().match(/^([A-Za-z0-9_.]+)\s*->\s*([A-Za-z0-9_]+)\.([A-Za-z0-9_.]+)(?:\s+as\s+([A-Za-z0-9_]+))?$/i);if(!r)throw new Error(`Invalid relation format: "${e}". Expected "source.path->collection.target"`);return {source:r[1],collection:r[2],target:r[3],alias:r[4]}}join(e,n){let r=this.buildStructuredJoin(e,n);return this.clone({joins:[...this.sq.joins??[],r]})}joinNested(e,n,r){let t=String(e??"").trim();if(!t)throw new Error("joinNested requires parentAlias");let i=(this.sq.joins??[]).map(a=>this.cloneStructuredJoin(a));if(i.length===0)throw new Error(`joinNested parent alias "${t}" not found`);let s=this.buildStructuredJoin(n,r);if(!this.appendNestedJoinByAlias(i,t,s))throw new Error(`joinNested parent alias "${t}" not found`);return this.clone({joins:i})}Join(e,n){return this.join(e,n)}JoinNested(e,n,r){return this.joinNested(e,n,r)}withRelation(e,n={}){let r=this.parseRelationRef(e);return this.join(r.collection,{...n,source:r.source,target:r.target,as:n.as??r.alias??r.collection})}select(...e){return this.clone({select:e})}distinctField(e){return this.clone({distinctField:e})}vectorSearch(e){return this.clone({vectorSearch:e})}getRawQuery(){let e={...this.sq};return Array.isArray(this.sq.where)&&(e.where=this.sq.where.map(n=>({...n}))),Array.isArray(this.sq.orderBy)&&(e.orderBy=this.sq.orderBy.map(n=>({...n}))),Array.isArray(this.sq.aggregate)&&(e.aggregate=this.sq.aggregate.map(n=>({...n}))),Array.isArray(this.sq.having)&&(e.having=this.sq.having.map(n=>({...n}))),Array.isArray(this.sq.select)&&(e.select=[...this.sq.select]),Array.isArray(this.sq.joins)&&(e.joins=this.sq.joins.map(n=>this.cloneStructuredJoin(n))),this.sq.groupBy?.fields&&(e.groupBy={fields:[...this.sq.groupBy.fields]}),this.sq.startAt?.values&&(e.startAt={values:[...this.sq.startAt.values]}),this.sq.startAfter?.values&&(e.startAfter={values:[...this.sq.startAfter.values]}),this.sq.endAt?.values&&(e.endAt={values:[...this.sq.endAt.values]}),this.sq.endBefore?.values&&(e.endBefore={values:[...this.sq.endBefore.values]}),{collection:this.name,query:e}}async get(){let e=new URL(this.baseUrl);e.searchParams.set("query",JSON.stringify(this.sq)),e.searchParams.set("allowSensitiveAuthUserFields",this.opts.allowSensitiveAuthUserFields?"1":"0");let n;try{n=await fetch(e.toString(),{headers:this.headers});}catch(t){let i=t instanceof Error?t.message:String(t);throw new Error(`[flare-admin] Network error (GET ${this.baseUrl}): ${i}`)}let r=await n.json().catch(()=>({}));if(!n.ok)throw new Error(`[flare-admin] GET ${this.baseUrl} failed (HTTP ${n.status}): ${r.error??"Unknown error"}`);return r.data??[]}async first(){let e=await this.get();return e.length>0?e[0]:null}async last(){let e=await this.get();return e.length>0?e[e.length-1]:null}async add(e){let n;try{n=await fetch(this.baseUrl,{method:"POST",headers:this.headers,body:JSON.stringify(e)});}catch(t){let i=t instanceof Error?t.message:String(t);throw new Error(`[flare-admin] Network error (POST ${this.baseUrl}): ${i}`)}let r=await n.json().catch(()=>({}));if(!n.ok)throw new Error(`[flare-admin] POST ${this.baseUrl} failed (HTTP ${n.status}): ${r.error??"Unknown error"}`);return new f(this.cfg,this.name,r.id)}async deleteMany(){let e;try{e=await fetch(this.baseUrl,{method:"DELETE",headers:this.headers,body:JSON.stringify({where:this.sq.where??[]})});}catch(r){let t=r instanceof Error?r.message:String(r);throw new Error(`[flare-admin] Network error (DELETE ${this.baseUrl}): ${t}`)}let n=await e.json().catch(()=>({}));if(!e.ok)throw new Error(`[flare-admin] DELETE ${this.baseUrl} failed (HTTP ${e.status}): ${n.error??"Unknown error"}`);return n.deleted??0}doc(e){return new f(this.cfg,this.name,e)}};var g=class{constructor(e){this.cfg=e;}collection(e){return new m(this.cfg,e)}};var A=class{constructor(e){this.cfg=e;}async createCustomToken(e,n={}){let r=`${this.cfg.serverUrl.replace(/\/$/,"")}/admin/token`,t=JSON.stringify({appId:this.cfg.appId,uid:String(e),role:n.role??"user",claims:n.claims??{},ttl:n.ttl??this.cfg.defaultTtl}),i;try{i=await fetch(r,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.cfg.adminKey}`},body:t});}catch(a){let p=a instanceof Error?a.message:String(a);throw new Error(`[flare-admin] Could not reach FlareServer at "${r}": ${p}
+Make sure FLARE_URL is set correctly and the server is running.`)}let s;try{s=await i.json();}catch{throw new Error(`[flare-admin] Server returned non-JSON response (status ${i.status})`)}if(!i.ok)throw new Error(`[flare-admin] createCustomToken failed (HTTP ${i.status}): `+(s.error??"Unknown error"));if(typeof s.token!="string")throw new Error('[flare-admin] Server response missing "token" field');return s.token}};var y=class{constructor(e){this.cfg=e;}get baseUrl(){return `${this.cfg.serverUrl.replace(/\/$/,"")}/admin/notify/${this.cfg.appId}`}get headers(){return {"Content-Type":"application/json",Authorization:`Bearer ${this.cfg.adminKey}`}}async send(e){let n;try{n=await fetch(`${this.baseUrl}/send`,{method:"POST",headers:this.headers,body:JSON.stringify(e??{})});}catch(t){let i=t instanceof Error?t.message:String(t);throw new Error(`[flare-admin] Network error (POST ${this.baseUrl}/send): ${i}`)}let r=await n.json().catch(()=>({}));if(!n.ok)throw new Error(`[flare-admin] Notification send failed (HTTP ${n.status}): `+(r.error??"Unknown error"));return {sent:!!r.sent,appId:String(r.appId??this.cfg.appId),targetCount:Number(r.targetCount??0),successCount:Number(r.successCount??0),failureCount:Number(r.failureCount??0),invalidatedTokenCount:Number(r.invalidatedTokenCount??0),dryRun:!!r.dryRun}}async tokens(){let e;try{e=await fetch(`${this.baseUrl}/tokens`,{method:"GET",headers:this.headers});}catch(r){let t=r instanceof Error?r.message:String(r);throw new Error(`[flare-admin] Network error (GET ${this.baseUrl}/tokens): ${t}`)}let n=await e.json().catch(()=>({}));if(!e.ok)throw new Error(`[flare-admin] Tokens fetch failed (HTTP ${e.status}): `+(n.error??"Unknown error"));return {appId:String(n.appId??this.cfg.appId),hasPushGateway:!!n.hasPushGateway,total:Number(n.total??0),tokens:Array.isArray(n.tokens)?n.tokens:[]}}};var w=class{constructor(e){this.cfg=e;this.ws=null;this.pendingAcks=new Map;this.subscriptions=new Map;this.activeSubscriptions=new Map;this.subscriptionErrorHandlers=new Map;this.subscriptionPermissionHandlers=new Map;this.subscriptionLastErrors=new Map;this.connected=false;this.shouldReconnect=true;this.reconnectDelay=2e3;let n=e.serverUrl.replace(/^http/,"ws");this.wsUrl=`${n}/?appId=${encodeURIComponent(e.appId)}&adminKey=${encodeURIComponent(e.adminKey)}`,this._readyPromise=new Promise(r=>{this._readyResolve=r;}),this._connect();}ready(){return this._readyPromise}disconnect(){this.shouldReconnect=false,this.ws?.close(1e3,"Admin disconnect"),this.ws=null,this.connected=false;}send(e,n){return new Promise((r,t)=>{let i=T(),s={id:i,type:e,ts:Date.now(),...n},a=setTimeout(()=>{this.pendingAcks.delete(i),t(new Error(`[flare-admin] WS request timeout (${e})`));},1e4);this.pendingAcks.set(i,c=>{clearTimeout(a),c.type==="error"?t(new Error(`[flare-admin] Server error: ${c.message}`)):r(c);});let p=()=>this.ws?.send(JSON.stringify(s));this.connected&&this.ws?.readyState===q.OPEN?p():this.ready().then(p).catch(t);})}subscribe(e,n,r,t,i={}){let s=T(),a={baseId:s,liveId:s,collection:e,docId:n,structuredQuery:r,callback:t,options:i};this.activeSubscriptions.set(s,a),this.subscriptionErrorHandlers.set(s,new Set),this.subscriptionPermissionHandlers.set(s,new Set),this.activateSubscription(a);let p=()=>{let h=this.activeSubscriptions.get(s)?.liveId??s;this.activeSubscriptions.delete(s),this.subscriptions.delete(s),this.subscriptions.delete(h),this.subscriptionErrorHandlers.delete(s),this.subscriptionPermissionHandlers.delete(s),this.subscriptionLastErrors.delete(s),this.connected&&this.send("unsubscribe",{subscriptionId:h}).catch(()=>{});},c=p;return c.unsubscribe=p,c.onError=u=>{this.subscriptionErrorHandlers.get(s)?.add(u);let h=this.subscriptionLastErrors.get(s);if(h)try{u(h);}catch{}return c},c.onPermissionDenied=u=>{this.subscriptionPermissionHandlers.get(s)?.add(u);let h=this.subscriptionLastErrors.get(s);if(h?.permissionDenied)try{u(h);}catch{}return c},c.catch=u=>c.onError(u),c}activateSubscription(e){let n=()=>{this.subscriptions.set(e.liveId,e.callback);let r={collection:e.collection};e.docId&&(r.docId=e.docId),e.structuredQuery&&(r.query=e.structuredQuery),e.options.skipSnapshot&&(r.skipSnapshot=true),this.send("subscribe",r).then(t=>{let i=t.subscriptionId;if(i&&i!==e.liveId){let s=this.subscriptions.get(e.liveId);s&&(this.subscriptions.delete(e.liveId),this.subscriptions.set(i,s),e.liveId=i);}}).catch(()=>{this.subscriptions.delete(e.liveId),this.emitSubscriptionError(e.baseId,this.toSubscriptionError(new Error("Subscribe failed")));});};this.connected?n():this.ready().then(n).catch(r=>{this.emitSubscriptionError(e.baseId,this.toSubscriptionError(r));});}async replayActiveSubscriptions(){if(!this.connected)return;let e=Array.from(this.activeSubscriptions.values());for(let n of e){if(!this.activeSubscriptions.has(n.baseId))continue;let r=n.liveId;this.subscriptions.delete(r),n.liveId=n.baseId,r&&r!==n.baseId&&await this.send("unsubscribe",{subscriptionId:r}).catch(()=>{}),this.activateSubscription(n);}}toSubscriptionError(e){let n=e instanceof Error?e.message:String(e??"Unknown subscription error"),r=n.match(/^\[([^\]]+)\]\s*(.*)$/),t=r?.[1],i=(r?.[2]??n).trim()||n,s=t==="PERMISSION_DENIED"||n.includes("PERMISSION_DENIED");return {code:t,message:i,permissionDenied:s,raw:e}}emitSubscriptionError(e,n){this.subscriptionLastErrors.set(e,n);let r=this.subscriptionErrorHandlers.get(e);if(r)for(let t of r)try{t(n);}catch{}if(n.permissionDenied){let t=this.subscriptionPermissionHandlers.get(e);if(t)for(let i of t)try{i(n);}catch{}}}_connect(){this._readyPromise=new Promise(e=>{this._readyResolve=e;}),this.ws=new q(this.wsUrl),this.ws.on("message",e=>{let n;try{n=JSON.parse(e.toString());}catch{return}this._handle(n);}),this.ws.on("close",e=>{this.connected=false,this.shouldReconnect&&e!==1e3&&setTimeout(()=>{this.reconnectDelay=Math.min(this.reconnectDelay*2,3e4),this._connect();},this.reconnectDelay);}),this.ws.on("error",()=>{});}_handle(e){let n=e.type;if(n==="auth_ok"){this.connected||(this.connected=true,this.reconnectDelay=2e3,this._readyResolve(),this.replayActiveSubscriptions().catch(()=>{}));return}if(n==="ack"||n==="pong"||n==="call_response"){let r=e.correlationId??e.id,t=this.pendingAcks.get(r);t&&(t(e),this.pendingAcks.delete(r));return}if(n==="error"){let r=e.correlationId;if(r){let t=this.pendingAcks.get(r);t&&(t(e),this.pendingAcks.delete(r));let i=Array.from(this.activeSubscriptions.values()).find(s=>s.liveId===r||s.baseId===r);if(i){let s=this.toSubscriptionError(new Error(`[${String(e.code??"ERROR")}] ${String(e.message??"Unknown error")}`));this.emitSubscriptionError(i.baseId,s);}}return}if(n==="snapshot"||n==="change"){let r=e.subscriptionId,t=this.subscriptions.get(r);t&&t({subscriptionId:r,collection:e.collection,docId:e.docId,data:e.data,type:n==="snapshot"?"snapshot":"change",operation:e.operation});}}};var C=class{constructor(e,n,r){this.conn=e;this.collection=n;this.id=r;}onSnapshot(e){let n=()=>{};return n=this.conn.subscribe(this.collection,this.id,void 0,r=>{r.type==="snapshot"&&(e(r),n());}),n}};var b=class o{constructor(e,n){this.conn=e;this.name=n;this.sq={};}clone(e){let n=new o(this.conn,this.name);return n.sq={...this.sq,...e},n}normalizeFilterValue(e,n){return e==="in"||e==="not-in"||e==="array-contains-any"?Array.isArray(n)?n:[n]:n}toQueryFilters(e){return S(e).map(r=>typeof r=="object"&&r!=null&&"field"in r&&"op"in r?{...r,value:this.normalizeFilterValue(r.op,r.value)}:r)}appendAndFilters(e){return this.clone({where:[...this.sq.where??[],...e]})}appendOrFilters(e){let n=[...this.sq.where??[]];if(n.length===0)return this.clone({where:[{or:e}]});let r=n[0];if(n.length===1&&typeof r=="object"&&r!=null&&"or"in r)return this.clone({where:[{or:[...r.or,...e]}]});let i=n.length===1?n[0]:{and:n};return this.clone({where:[{or:[i,...e]}]})}appendFilters(e,n){return n==="or"?this.appendOrFilters(e):this.appendAndFilters(e)}appendOperatorFilter(e,n,r,t){return this.appendFilters([{field:e,op:n,value:this.normalizeFilterValue(n,r)}],t)}where(e){return this.appendFilters(this.toQueryFilters(e),"and")}and(e){return this.appendFilters(this.toQueryFilters(e),"and")}or(e){return this.appendFilters(this.toQueryFilters(e),"or")}in(e,n){return this.appendOperatorFilter(e,"in",n,"and")}andIn(e,n){return this.appendOperatorFilter(e,"in",n,"and")}orIn(e,n){return this.appendOperatorFilter(e,"in",n,"or")}notIn(e,n){return this.appendOperatorFilter(e,"not-in",n,"and")}andNotIn(e,n){return this.appendOperatorFilter(e,"not-in",n,"and")}orNotIn(e,n){return this.appendOperatorFilter(e,"not-in",n,"or")}arrayContains(e,n){return this.appendOperatorFilter(e,"array-contains",n,"and")}andArrayContains(e,n){return this.appendOperatorFilter(e,"array-contains",n,"and")}orArrayContains(e,n){return this.appendOperatorFilter(e,"array-contains",n,"or")}arrayContainsAny(e,n){return this.appendOperatorFilter(e,"array-contains-any",n,"and")}andArrayContainsAny(e,n){return this.appendOperatorFilter(e,"array-contains-any",n,"and")}orArrayContainsAny(e,n){return this.appendOperatorFilter(e,"array-contains-any",n,"or")}some(e,n){return this.appendOperatorFilter(e,"elem-match",n,"and")}andSome(e,n){return this.appendOperatorFilter(e,"elem-match",n,"and")}orSome(e,n){return this.appendOperatorFilter(e,"elem-match",n,"or")}like(e,n){return this.appendOperatorFilter(e,"like",n,"and")}andLike(e,n){return this.appendOperatorFilter(e,"like",n,"and")}orLike(e,n){return this.appendOperatorFilter(e,"like",n,"or")}notLike(e,n){return this.appendOperatorFilter(e,"not-like",n,"and")}andNotLike(e,n){return this.appendOperatorFilter(e,"not-like",n,"and")}orNotLike(e,n){return this.appendOperatorFilter(e,"not-like",n,"or")}exists(e){return this.appendOperatorFilter(e,"exists",true,"and")}andExists(e){return this.appendOperatorFilter(e,"exists",true,"and")}orExists(e){return this.appendOperatorFilter(e,"exists",true,"or")}notExists(e){return this.appendOperatorFilter(e,"not-exists",true,"and")}andNotExists(e){return this.appendOperatorFilter(e,"not-exists",true,"and")}orNotExists(e){return this.appendOperatorFilter(e,"not-exists",true,"or")}latest(){return this.clone({orderBy:[...this.sq.orderBy??[],{field:"_seq",dir:"desc"}]})}newest(){return this.latest()}oldest(){return this.clone({orderBy:[...this.sq.orderBy??[],{field:"_seq",dir:"asc"}]})}orderBy(e,n="asc"){return this.clone({orderBy:[...this.sq.orderBy??[],{field:e,dir:n}]})}limit(e){return this.clone({limit:e})}offset(e){return this.clone({offset:e})}startAt(...e){return this.clone({startAt:{values:e}})}startAfter(...e){return this.clone({startAfter:{values:e}})}endAt(...e){return this.clone({endAt:{values:e}})}endBefore(...e){return this.clone({endBefore:{values:e}})}aggregate(...e){return this.clone({aggregate:[...this.sq.aggregate??[],...e]})}count(e="count"){return this.aggregate({fn:"count",alias:e})}sum(e,n){return this.aggregate({fn:"sum",field:e,alias:n??`sum_${e}`})}avg(e,n){return this.aggregate({fn:"avg",field:e,alias:n??`avg_${e}`})}min(e,n){return this.aggregate({fn:"min",field:e,alias:n??`min_${e}`})}max(e,n){return this.aggregate({fn:"max",field:e,alias:n??`max_${e}`})}distinct(e,n){return this.aggregate({fn:"distinct",field:e,alias:n??`distinct_${e}`})}groupBy(...e){return this.clone({groupBy:{fields:e}})}having(e,n,r){return this.clone({having:[...this.sq.having??[],{field:e,op:n,value:r}]})}buildStructuredJoin(e,n){let r={from:String(e??""),localField:String(n?.source??""),foreignField:String(n?.target??""),as:String(n?.as??""),single:n?.single};return Array.isArray(n?.where)&&(r.where=n.where),Array.isArray(n?.orderBy)&&(r.orderBy=n.orderBy),typeof n?.limit=="number"&&(r.limit=n.limit),typeof n?.offset=="number"&&(r.offset=n.offset),Array.isArray(n?.select)&&(r.select=n.select),Array.isArray(n?.joins)&&(r.joins=n.joins.map(t=>this.buildStructuredJoin(String(t?.collection??""),t))),r}cloneStructuredJoin(e){let n={...e};return Array.isArray(e.where)&&(n.where=e.where.map(r=>({...r}))),Array.isArray(e.orderBy)&&(n.orderBy=e.orderBy.map(r=>({...r}))),Array.isArray(e.select)&&(n.select=[...e.select]),Array.isArray(e.joins)&&(n.joins=e.joins.map(r=>this.cloneStructuredJoin(r))),n}appendNestedJoinByAlias(e,n,r){for(let t of e){if(t.as===n)return t.joins=[...t.joins??[],r],true;if(Array.isArray(t.joins)&&this.appendNestedJoinByAlias(t.joins,n,r))return  true}return  false}parseRelationRef(e){let r=String(e??"").trim().match(/^([A-Za-z0-9_.]+)\s*->\s*([A-Za-z0-9_]+)\.([A-Za-z0-9_.]+)(?:\s+as\s+([A-Za-z0-9_]+))?$/i);if(!r)throw new Error(`Invalid relation format: "${e}". Expected "source.path->collection.target"`);return {source:r[1],collection:r[2],target:r[3],alias:r[4]}}join(e,n){let r=this.buildStructuredJoin(e,n);return this.clone({joins:[...this.sq.joins??[],r]})}joinNested(e,n,r){let t=String(e??"").trim();if(!t)throw new Error("joinNested requires parentAlias");let i=(this.sq.joins??[]).map(a=>this.cloneStructuredJoin(a));if(i.length===0)throw new Error(`joinNested parent alias "${t}" not found`);let s=this.buildStructuredJoin(n,r);if(!this.appendNestedJoinByAlias(i,t,s))throw new Error(`joinNested parent alias "${t}" not found`);return this.clone({joins:i})}Join(e,n){return this.join(e,n)}JoinNested(e,n,r){return this.joinNested(e,n,r)}withRelation(e,n={}){let r=this.parseRelationRef(e);return this.join(r.collection,{...n,source:r.source,target:r.target,as:n.as??r.alias??r.collection})}select(...e){return this.clone({select:e})}distinctField(e){return this.clone({distinctField:e})}vectorSearch(e){return this.clone({vectorSearch:e})}doc(e){return new C(this.conn,this.name,e)}getRawQuery(){let e={...this.sq};return Array.isArray(this.sq.where)&&(e.where=this.sq.where.map(n=>({...n}))),Array.isArray(this.sq.orderBy)&&(e.orderBy=this.sq.orderBy.map(n=>({...n}))),Array.isArray(this.sq.aggregate)&&(e.aggregate=this.sq.aggregate.map(n=>({...n}))),Array.isArray(this.sq.having)&&(e.having=this.sq.having.map(n=>({...n}))),Array.isArray(this.sq.select)&&(e.select=[...this.sq.select]),Array.isArray(this.sq.joins)&&(e.joins=this.sq.joins.map(n=>this.cloneStructuredJoin(n))),this.sq.groupBy?.fields&&(e.groupBy={fields:[...this.sq.groupBy.fields]}),this.sq.startAt?.values&&(e.startAt={values:[...this.sq.startAt.values]}),this.sq.startAfter?.values&&(e.startAfter={values:[...this.sq.startAfter.values]}),this.sq.endAt?.values&&(e.endAt={values:[...this.sq.endAt.values]}),this.sq.endBefore?.values&&(e.endBefore={values:[...this.sq.endBefore.values]}),{collection:this.name,query:e}}onSnapshot(e){let n=this._buildSq(),r=()=>{};return r=this.conn.subscribe(this.name,void 0,n,t=>{t.type==="snapshot"&&(e(t),r());}),r}onDocAdded(e){let n=this._buildSq();return this.conn.subscribe(this.name,void 0,n,r=>{r.type==="change"&&r.operation==="insert"&&r.data!=null&&e(r.data,r.docId);},{skipSnapshot:true})}onDocUpdated(e){let n=this._buildSq();return this.conn.subscribe(this.name,void 0,n,r=>{r.type==="change"&&(r.operation==="update"||r.operation==="replace")&&r.data!=null&&e(r.data,r.docId);},{skipSnapshot:true})}onDocDeleted(e){let n=this._buildSq();return this.conn.subscribe(this.name,void 0,n,r=>{r.type==="change"&&r.operation==="delete"&&e(r.docId);},{skipSnapshot:true})}onDocChanged(e){let n=this._buildSq();return this.conn.subscribe(this.name,void 0,n,r=>{r.type==="change"&&e(r.data??null,r.docId,r.operation);},{skipSnapshot:true})}_buildSq(){let e={};return this.sq.where&&this.sq.where.length>0&&(e.where=this.sq.where),this.sq.orderBy&&this.sq.orderBy.length>0&&(e.orderBy=this.sq.orderBy),this.sq.limit!==void 0&&(e.limit=this.sq.limit),this.sq.offset!==void 0&&(e.offset=this.sq.offset),this.sq.startAt&&(e.startAt=this.sq.startAt),this.sq.startAfter&&(e.startAfter=this.sq.startAfter),this.sq.endAt&&(e.endAt=this.sq.endAt),this.sq.endBefore&&(e.endBefore=this.sq.endBefore),this.sq.aggregate&&this.sq.aggregate.length>0&&(e.aggregate=this.sq.aggregate),this.sq.groupBy&&(e.groupBy=this.sq.groupBy),this.sq.having&&this.sq.having.length>0&&(e.having=this.sq.having),this.sq.joins&&this.sq.joins.length>0&&(e.joins=this.sq.joins),this.sq.vectorSearch&&(e.vectorSearch=this.sq.vectorSearch),this.sq.select&&this.sq.select.length>0&&(e.select=this.sq.select),this.sq.distinctField&&(e.distinctField=this.sq.distinctField),e}};var v=class{constructor(e){this._ws=new w(e);}collection(e){return new b(this._ws,e)}ready(){return this._ws.ready()}disconnect(){this._ws.disconnect();}};var F=class{constructor(e){this.cfg={defaultTtl:"24h",...e,serverUrl:e.serverUrl.replace(/\/$/,"")};}auth(){return this._auth??(this._auth=new A(this.cfg))}db(){return this._db??(this._db=new g(this.cfg))}connection(){return this._conn??(this._conn=new v(this.cfg))}notifications(){return this._notifications??(this._notifications=new y(this.cfg))}},R=new Map;function de(o,e="[DEFAULT]"){if(R.has(e))return R.get(e);let n=new F(o);return R.set(e,n),n}function k(o="[DEFAULT]"){let e=R.get(o);if(!e)throw new Error(`[flare-admin] No app named "${o}" found. Call connectApp() before getApp().`);return e}function ue(o="[DEFAULT]"){return k(o).auth()}function he(o="[DEFAULT]"){return k(o).db()}function pe(o="[DEFAULT]"){return k(o).connection()}function me(o="[DEFAULT]"){return k(o).notifications()}export{m as AdminCollectionReference,f as AdminDocumentReference,b as AdminLiveCollectionReference,C as AdminLiveDocumentReference,F as FlareAdminApp,A as FlareAdminAuthService,v as FlareAdminConnection,g as FlareAdminDbService,y as FlareAdminNotificationsService,w as FlareAdminWsConnection,ue as auth,de as connectApp,pe as connection,he as db,k as getApp,me as notifications};

package/dist/lib/auth.d.ts

@@ -0,0 +1,6 @@
+import { FlareAdminConfig, FlareAdminAuth, CreateCustomTokenOptions } from "../types";
+export declare class FlareAdminAuthService implements FlareAdminAuth {
+    private readonly cfg;
+    constructor(cfg: Required<FlareAdminConfig>);
+    createCustomToken(uid: string | number, opts?: CreateCustomTokenOptions): Promise<string>;
+}

package/dist/lib/notifications.d.ts

@@ -0,0 +1,14 @@
+import { AdminPushSendInput, AdminPushSendResult, FlareAdminConfig, FlareAdminNotifications, AdminPushToken } from "../types";
+export declare class FlareAdminNotificationsService implements FlareAdminNotifications {
+    private readonly cfg;
+    constructor(cfg: Required<FlareAdminConfig>);
+    private get baseUrl();
+    private get headers();
+    send(input: AdminPushSendInput): Promise<AdminPushSendResult>;
+    tokens(): Promise<{
+        appId: string;
+        hasPushGateway: boolean;
+        total: number;
+        tokens: AdminPushToken[];
+    }>;
+}

package/dist/lib/utils.d.ts

@@ -0,0 +1,5 @@
+import { WhereCondition, WhereFilter } from "../types";
+/** Parse ORM-style shorthand: `{ age: ">= 25" }` → WhereFilter[] */
+export declare function parseWhereCondition(condition: WhereCondition): WhereFilter[];
+export declare function parseScalar(val: string): unknown;
+export declare function shortId(): string;

package/dist/realtime/Connection.d.ts

@@ -0,0 +1,33 @@
+import { AdminLiveCollectionReference } from "./LiveCollection";
+/**
+ * The real-time connection service returned by `admin.connection()`.
+ *
+ * One `FlareAdminConnection` (and its underlying WebSocket) is shared per
+ * `FlareAdminApp` instance. Call `.disconnect()` when you no longer need it.
+ *
+ * @example
+ *   const unsub = admin.connection()
+ *     .collection("orders")
+ *     .where({ status: "pending" })
+ *     .or({ priority: "high" })
+ *     .orderBy("createdAt", "desc")
+ *     .onSnapshot((snap) => console.log(snap));
+ *
+ *   const unsub2 = admin.connection()
+ *     .collection("users").doc("alice")
+ *     .onSnapshot((snap) => console.log(snap.data));
+ *
+ *   unsub(); unsub2();
+ *   admin.connection().disconnect();
+ */
+export declare class FlareAdminConnection {
+    /**
+     * Reference a collection for real-time subscriptions.
+     * Returns an `AdminLiveCollectionReference` with the full query-builder API.
+     */
+    collection<T = Record<string, unknown>>(name: string): AdminLiveCollectionReference<T>;
+    /** Wait until the WebSocket is open and authenticated. */
+    ready(): Promise<void>;
+    /** Close the WebSocket connection permanently (no reconnect). */
+    disconnect(): void;
+}

package/dist/realtime/LiveCollection.d.ts

@@ -0,0 +1,93 @@
+import { WhereCondition, HavingClause, JoinClause, AggregateSpec, VectorSearchClause, StructuredQuery, AdminDocAddedCallback, AdminDocChangedCallback, AdminDocDeletedCallback, AdminDocUpdatedCallback, AdminSnapshotCallback, AdminSubscribeOptions, AdminSubscriptionHandle } from "../types";
+import { AdminLiveDocumentReference } from "./LiveDocument";
+type AdminRealtimeSubscriber = {
+    subscribe: (collection: string, docId: string | undefined, structuredQuery: StructuredQuery | undefined, callback: AdminSnapshotCallback, options?: AdminSubscribeOptions) => AdminSubscriptionHandle;
+};
+export declare class AdminLiveCollectionReference<T = Record<string, unknown>> {
+    private readonly conn;
+    readonly name: string;
+    private sq;
+    constructor(conn: AdminRealtimeSubscriber, name: string);
+    private clone;
+    private normalizeFilterValue;
+    private toQueryFilters;
+    private appendAndFilters;
+    private appendOrFilters;
+    private appendFilters;
+    private appendOperatorFilter;
+    where(condition: WhereCondition): AdminLiveCollectionReference<T>;
+    and(condition: WhereCondition): AdminLiveCollectionReference<T>;
+    or(condition: WhereCondition): AdminLiveCollectionReference<T>;
+    in(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    andIn(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    orIn(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    notIn(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    andNotIn(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    orNotIn(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    arrayContains(field: string, value: unknown): AdminLiveCollectionReference<T>;
+    andArrayContains(field: string, value: unknown): AdminLiveCollectionReference<T>;
+    orArrayContains(field: string, value: unknown): AdminLiveCollectionReference<T>;
+    arrayContainsAny(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    andArrayContainsAny(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    orArrayContainsAny(field: string, values: unknown[] | unknown): AdminLiveCollectionReference<T>;
+    some(field: string, condition: Record<string, unknown>): AdminLiveCollectionReference<T>;
+    andSome(field: string, condition: Record<string, unknown>): AdminLiveCollectionReference<T>;
+    orSome(field: string, condition: Record<string, unknown>): AdminLiveCollectionReference<T>;
+    like(field: string, value: string): AdminLiveCollectionReference<T>;
+    andLike(field: string, value: string): AdminLiveCollectionReference<T>;
+    orLike(field: string, value: string): AdminLiveCollectionReference<T>;
+    notLike(field: string, value: string): AdminLiveCollectionReference<T>;
+    andNotLike(field: string, value: string): AdminLiveCollectionReference<T>;
+    orNotLike(field: string, value: string): AdminLiveCollectionReference<T>;
+    exists(field: string): AdminLiveCollectionReference<T>;
+    andExists(field: string): AdminLiveCollectionReference<T>;
+    orExists(field: string): AdminLiveCollectionReference<T>;
+    notExists(field: string): AdminLiveCollectionReference<T>;
+    andNotExists(field: string): AdminLiveCollectionReference<T>;
+    orNotExists(field: string): AdminLiveCollectionReference<T>;
+    latest(): AdminLiveCollectionReference<T>;
+    newest(): AdminLiveCollectionReference<T>;
+    oldest(): AdminLiveCollectionReference<T>;
+    orderBy(field: string, dir?: "asc" | "desc"): AdminLiveCollectionReference<T>;
+    limit(n: number): AdminLiveCollectionReference<T>;
+    offset(n: number): AdminLiveCollectionReference<T>;
+    startAt(...values: unknown[]): AdminLiveCollectionReference<T>;
+    startAfter(...values: unknown[]): AdminLiveCollectionReference<T>;
+    endAt(...values: unknown[]): AdminLiveCollectionReference<T>;
+    endBefore(...values: unknown[]): AdminLiveCollectionReference<T>;
+    aggregate(...specs: AggregateSpec[]): AdminLiveCollectionReference<T>;
+    count(alias?: string): AdminLiveCollectionReference<T>;
+    sum(field: string, alias?: string): AdminLiveCollectionReference<T>;
+    avg(field: string, alias?: string): AdminLiveCollectionReference<T>;
+    min(field: string, alias?: string): AdminLiveCollectionReference<T>;
+    max(field: string, alias?: string): AdminLiveCollectionReference<T>;
+    distinct(field: string, alias?: string): AdminLiveCollectionReference<T>;
+    groupBy(...fields: string[]): AdminLiveCollectionReference<T>;
+    having(field: string, op: HavingClause["op"], value: number): AdminLiveCollectionReference<T>;
+    private buildStructuredJoin;
+    private cloneStructuredJoin;
+    private appendNestedJoinByAlias;
+    private parseRelationRef;
+    join(collectionName: string, j: JoinClause): AdminLiveCollectionReference<T>;
+    joinNested(parentAlias: string, collectionName: string, j: JoinClause): AdminLiveCollectionReference<T>;
+    Join(collectionName: string, j: JoinClause): AdminLiveCollectionReference<T>;
+    JoinNested(parentAlias: string, collectionName: string, j: JoinClause): AdminLiveCollectionReference<T>;
+    withRelation(relation: string, options?: (Omit<JoinClause, "source" | "target" | "as"> & {
+        as?: string;
+    })): AdminLiveCollectionReference<T>;
+    select(...fields: string[]): AdminLiveCollectionReference<T>;
+    distinctField(field: string): AdminLiveCollectionReference<T>;
+    vectorSearch(opts: VectorSearchClause): AdminLiveCollectionReference<T>;
+    doc(id: string): AdminLiveDocumentReference<T>;
+    getRawQuery(): {
+        collection: string;
+        query: StructuredQuery;
+    };
+    onSnapshot(callback: AdminSnapshotCallback<T[]>): () => void;
+    onDocAdded(callback: AdminDocAddedCallback<T>): () => void;
+    onDocUpdated(callback: AdminDocUpdatedCallback<T>): () => void;
+    onDocDeleted(callback: AdminDocDeletedCallback): () => void;
+    onDocChanged(callback: AdminDocChangedCallback<T>): () => void;
+    private _buildSq;
+}
+export {};

package/dist/realtime/LiveDocument.d.ts

@@ -0,0 +1,32 @@
+import { AdminSnapshotCallback, AdminSubscribeOptions, AdminSubscriptionHandle, StructuredQuery } from "../types";
+type AdminRealtimeSubscriber = {
+    subscribe: (collection: string, docId: string | undefined, structuredQuery: StructuredQuery | undefined, callback: AdminSnapshotCallback, options?: AdminSubscribeOptions) => AdminSubscriptionHandle;
+};
+/**
+ * Real-time reference to a single document.
+ *
+ * @example
+ *   const unsub = admin.connection()
+ *     .collection("users").doc("alice")
+ *     .onSnapshot((snap) => console.log(snap.data));
+ */
+export declare class AdminLiveDocumentReference<T = Record<string, unknown>> {
+    private readonly conn;
+    /** Collection name */
+    readonly collection: string;
+    /** Document ID */
+    readonly id: string;
+    constructor(conn: AdminRealtimeSubscriber, 
+    /** Collection name */
+    collection: string, 
+    /** Document ID */
+    id: string);
+    /**
+     * Subscribe to real-time changes for this document.
+     * The callback fires once with the initial snapshot, then on every update.
+     *
+     * @returns An unsubscribe function — call it to stop listening.
+     */
+    onSnapshot(callback: AdminSnapshotCallback<T>): () => void;
+}
+export {};

package/dist/realtime/WsConnection.d.ts

@@ -0,0 +1,43 @@
+import { FlareAdminConfig, AdminSnapshotCallback, AdminSubscribeOptions, StructuredQuery, AdminSubscriptionHandle } from "../types";
+/**
+ * Manages a persistent admin WebSocket connection to FlareServer.
+ * Passes `adminKey` as a query param — the server immediately elevates the
+ * socket to role "admin", bypassing all security rules.
+ */
+export declare class FlareAdminWsConnection {
+    private readonly cfg;
+    private ws;
+    private readonly pendingAcks;
+    private readonly subscriptions;
+    private readonly activeSubscriptions;
+    private readonly subscriptionErrorHandlers;
+    private readonly subscriptionPermissionHandlers;
+    private readonly subscriptionLastErrors;
+    private connected;
+    private shouldReconnect;
+    private reconnectDelay;
+    private readonly wsUrl;
+    private _readyResolve;
+    private _readyPromise;
+    constructor(cfg: Required<FlareAdminConfig>);
+    /** Resolves once the WS is open and AUTH_OK is received from the server. */
+    ready(): Promise<void>;
+    /** Close the connection permanently (no reconnect). */
+    disconnect(): void;
+    /**
+     * Send a typed message and await its ACK / response.
+     */
+    send(type: string, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Subscribe to a collection / document in real-time.
+     * Passes a full `StructuredQuery` (or docId) to the server.
+     * Returns an unsubscribe function.
+     */
+    subscribe(collection: string, docId: string | undefined, structuredQuery: StructuredQuery | undefined, callback: AdminSnapshotCallback, options?: AdminSubscribeOptions): AdminSubscriptionHandle;
+    private activateSubscription;
+    private replayActiveSubscriptions;
+    private toSubscriptionError;
+    private emitSubscriptionError;
+    private _connect;
+    private _handle;
+}