@zuzjs/flare-admin 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,793 @@
+interface FlareAdminConfig {
+    /**
+     * Base URL of your FlareServer instance.
+     * Self-hosted:  "http://localhost:5050"
+     * SaaS:         "https://www.zedgon.io"
+     */
+    serverUrl: string;
+    /** The app ID created with `flare app create` */
+    appId: string;
+    /**
+     * Admin key printed when you run `flare app create`.
+     * Keep in an environment variable — NEVER expose to the browser.
+     */
+    adminKey: string;
+    /** Default token TTL, e.g. "24h" */
+    defaultTtl?: string;
+}
+interface CreateCustomTokenOptions {
+    role?: "user" | "admin" | "anon";
+    claims?: Record<string, unknown>;
+    ttl?: string;
+}
+interface FlareAdminAuth {
+    createCustomToken(uid: string | number, opts?: CreateCustomTokenOptions): Promise<string>;
+}
+interface AdminPushSendInput {
+    title?: string;
+    body?: string;
+    image?: string;
+    data?: Record<string, unknown>;
+    tokens?: string[];
+    uid?: string;
+    topic?: string;
+    priority?: "normal" | "high";
+    ttlSeconds?: number;
+    dryRun?: boolean;
+}
+interface AdminPushSendResult {
+    sent: boolean;
+    appId: string;
+    targetCount: number;
+    successCount: number;
+    failureCount: number;
+    invalidatedTokenCount: number;
+    dryRun: boolean;
+}
+interface AdminPushToken {
+    token: string;
+    uid: string;
+    platform?: string;
+    deviceId?: string;
+    topics?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    lastSeenAt?: string;
+}
+interface FlareAdminNotifications {
+    send(input: AdminPushSendInput): Promise<AdminPushSendResult>;
+    tokens(): Promise<{
+        appId: string;
+        hasPushGateway: boolean;
+        total: number;
+        tokens: AdminPushToken[];
+    }>;
+}
+type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains" | "array-contains-any" | "elem-match" | "like" | "not-like" | "contains" | "exists" | "not-exists";
+interface WhereFilter {
+    field: string;
+    op: QueryOperator;
+    value: unknown;
+}
+/** OR group — matches if ANY inner filter matches */
+interface OrFilter {
+    or: AnyFilter[];
+}
+/** AND group — matches only if ALL inner filters match */
+interface AndFilter {
+    and: AnyFilter[];
+}
+type AnyFilter = WhereFilter | OrFilter | AndFilter;
+/**
+ * ORM-style shorthand: `{ age: ">= 25", role: "admin" }`
+ */
+type WhereCondition = Record<string, string | number | boolean | unknown[]>;
+interface OrderByClause {
+    field: string;
+    dir?: "asc" | "desc";
+}
+interface GroupByClause {
+    fields: string[];
+}
+interface HavingClause {
+    field: string;
+    op: "==" | "!=" | "<" | "<=" | ">" | ">=";
+    value: number;
+}
+interface CursorValue {
+    values: unknown[];
+}
+type AggregateFunction = "count" | "sum" | "avg" | "min" | "max" | "distinct";
+interface AggregateSpec {
+    fn: AggregateFunction;
+    field?: string;
+    alias?: string;
+}
+interface JoinClause {
+    source: string;
+    target: string;
+    as: string;
+    single?: boolean;
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    select?: string[];
+    joins?: NestedJoinClause[];
+}
+interface NestedJoinClause extends JoinClause {
+    collection: string;
+}
+interface StructuredJoinClause {
+    from: string;
+    localField: string;
+    foreignField: string;
+    as: string;
+    single?: boolean;
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    select?: string[];
+    joins?: StructuredJoinClause[];
+}
+interface VectorSearchClause {
+    field: string;
+    vector: number[];
+    k: number;
+    metric?: "cosine" | "euclidean" | "dotProduct";
+    minScore?: number;
+}
+/** Full structured query (mirrors client StructuredQuery / server StructuredQuery) */
+interface StructuredQuery {
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    startAt?: CursorValue;
+    startAfter?: CursorValue;
+    endAt?: CursorValue;
+    endBefore?: CursorValue;
+    aggregate?: AggregateSpec[];
+    groupBy?: GroupByClause;
+    having?: HavingClause[];
+    joins?: StructuredJoinClause[];
+    vectorSearch?: VectorSearchClause;
+    select?: string[];
+    distinctField?: string;
+}
+/** Minimal structural interface satisfied by AdminCollectionReference<T>. */
+interface FlareAdminDb {
+    collection<T = Record<string, unknown>>(name: string): AdminCollectionShape<T>;
+}
+interface AdminDocumentShape<T> {
+    get(): Promise<T | null>;
+    set(data: Partial<T>): Promise<void>;
+    update(data: Partial<T>): Promise<void>;
+    delete(): Promise<void>;
+}
+interface AdminCollectionShape<T> {
+    allowSensitiveAuthUserFields(enabled?: boolean): AdminCollectionShape<T>;
+    where(condition: WhereCondition): AdminCollectionShape<T>;
+    and(condition: WhereCondition): AdminCollectionShape<T>;
+    or(condition: WhereCondition): AdminCollectionShape<T>;
+    in(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    andIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    orIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    notIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    andNotIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    orNotIn(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    arrayContains(field: string, value: unknown): AdminCollectionShape<T>;
+    andArrayContains(field: string, value: unknown): AdminCollectionShape<T>;
+    orArrayContains(field: string, value: unknown): AdminCollectionShape<T>;
+    arrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    andArrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    orArrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionShape<T>;
+    some(field: string, condition: Record<string, unknown>): AdminCollectionShape<T>;
+    andSome(field: string, condition: Record<string, unknown>): AdminCollectionShape<T>;
+    orSome(field: string, condition: Record<string, unknown>): AdminCollectionShape<T>;
+    like(field: string, value: string): AdminCollectionShape<T>;
+    andLike(field: string, value: string): AdminCollectionShape<T>;
+    orLike(field: string, value: string): AdminCollectionShape<T>;
+    notLike(field: string, value: string): AdminCollectionShape<T>;
+    andNotLike(field: string, value: string): AdminCollectionShape<T>;
+    orNotLike(field: string, value: string): AdminCollectionShape<T>;
+    exists(field: string): AdminCollectionShape<T>;
+    andExists(field: string): AdminCollectionShape<T>;
+    orExists(field: string): AdminCollectionShape<T>;
+    notExists(field: string): AdminCollectionShape<T>;
+    andNotExists(field: string): AdminCollectionShape<T>;
+    orNotExists(field: string): AdminCollectionShape<T>;
+    latest(): AdminCollectionShape<T>;
+    newest(): AdminCollectionShape<T>;
+    oldest(): AdminCollectionShape<T>;
+    orderBy(field: string, dir?: "asc" | "desc"): AdminCollectionShape<T>;
+    limit(n: number): AdminCollectionShape<T>;
+    offset(n: number): AdminCollectionShape<T>;
+    startAt(...values: unknown[]): AdminCollectionShape<T>;
+    startAfter(...values: unknown[]): AdminCollectionShape<T>;
+    endAt(...values: unknown[]): AdminCollectionShape<T>;
+    endBefore(...values: unknown[]): AdminCollectionShape<T>;
+    aggregate(...specs: AggregateSpec[]): AdminCollectionShape<T>;
+    count(alias?: string): AdminCollectionShape<T>;
+    sum(field: string, alias?: string): AdminCollectionShape<T>;
+    avg(field: string, alias?: string): AdminCollectionShape<T>;
+    min(field: string, alias?: string): AdminCollectionShape<T>;
+    max(field: string, alias?: string): AdminCollectionShape<T>;
+    distinct(field: string, alias?: string): AdminCollectionShape<T>;
+    groupBy(...fields: string[]): AdminCollectionShape<T>;
+    having(field: string, op: HavingClause["op"], value: number): AdminCollectionShape<T>;
+    join(collection: string, j: JoinClause): AdminCollectionShape<T>;
+    joinNested(parentAlias: string, collection: string, j: JoinClause): AdminCollectionShape<T>;
+    Join(collection: string, j: JoinClause): AdminCollectionShape<T>;
+    JoinNested(parentAlias: string, collection: string, j: JoinClause): AdminCollectionShape<T>;
+    withRelation(relation: string, options?: Omit<JoinClause, "source" | "target" | "as"> & {
+        as?: string;
+    }): AdminCollectionShape<T>;
+    select(...fields: string[]): AdminCollectionShape<T>;
+    distinctField(field: string): AdminCollectionShape<T>;
+    vectorSearch(opts: VectorSearchClause): AdminCollectionShape<T>;
+    getRawQuery(): {
+        collection: string;
+        query: StructuredQuery;
+    };
+    get(): Promise<T[]>;
+    first(): Promise<T | null>;
+    last(): Promise<T | null>;
+    add(data: Partial<T>): Promise<AdminDocumentShape<T>>;
+    deleteMany(): Promise<number>;
+    doc(id: string): AdminDocumentShape<T>;
+}
+interface AdminSnapshotData<T = unknown> {
+    subscriptionId: string;
+    collection: string;
+    docId?: string;
+    data: T;
+    type: "snapshot" | "change";
+    operation?: "insert" | "update" | "delete" | "replace";
+}
+type AdminSnapshotCallback<T = unknown> = (data: AdminSnapshotData<T>) => void;
+type AdminDocAddedCallback<T = unknown> = (data: T, docId: string) => void;
+type AdminDocUpdatedCallback<T = unknown> = (data: T, docId: string) => void;
+type AdminDocDeletedCallback = (docId: string) => void;
+type AdminDocChangedCallback<T = unknown> = (data: T | null, docId: string, operation: "insert" | "update" | "delete" | "replace") => void;
+interface AdminSubscribeOptions {
+    skipSnapshot?: boolean;
+}
+interface AdminSubscriptionError {
+    code?: string;
+    message: string;
+    permissionDenied: boolean;
+    raw?: unknown;
+}
+type AdminSubscriptionErrorCallback = (error: AdminSubscriptionError) => void;
+interface AdminSubscriptionHandle {
+    (): void;
+    unsubscribe: () => void;
+    onError: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
+    onPermissionDenied: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
+    catch: (callback: AdminSubscriptionErrorCallback) => AdminSubscriptionHandle;
+}
+
+declare class AdminDocumentReference<T = Record<string, unknown>> {
+    private readonly cfg;
+    readonly collection: string;
+    readonly id: string;
+    constructor(cfg: Required<FlareAdminConfig>, collection: string, id: string);
+    private get baseUrl();
+    private get headers();
+    private request;
+    /** Fetch this document. Returns `null` if it does not exist. */
+    get(): Promise<T | null>;
+    /**
+     * Replace (or create) this document entirely.
+     * All fields not in `data` are removed.
+     */
+    set(data: Partial<T>): Promise<void>;
+    /**
+     * Merge `data` into the existing document (upsert).
+     * Only the provided fields are changed.
+     */
+    update(data: Partial<T>): Promise<void>;
+    /** Delete this document. */
+    delete(): Promise<void>;
+    /** Return the parent collection reference. */
+    parent(): AdminCollectionReference<T>;
+}
+
+declare class AdminCollectionReference<T = Record<string, unknown>> {
+    private readonly cfg;
+    readonly name: string;
+    private sq;
+    private opts;
+    constructor(cfg: Required<FlareAdminConfig>, name: string);
+    private get baseUrl();
+    private get headers();
+    private clone;
+    allowSensitiveAuthUserFields(enabled?: boolean): AdminCollectionReference<T>;
+    private normalizeFilterValue;
+    private toQueryFilters;
+    private appendAndFilters;
+    private appendOrFilters;
+    private appendFilters;
+    private appendOperatorFilter;
+    where(condition: WhereCondition): AdminCollectionReference<T>;
+    and(condition: WhereCondition): AdminCollectionReference<T>;
+    or(condition: WhereCondition): AdminCollectionReference<T>;
+    in(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    andIn(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    orIn(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    notIn(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    andNotIn(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    orNotIn(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    arrayContains(field: string, value: unknown): AdminCollectionReference<T>;
+    andArrayContains(field: string, value: unknown): AdminCollectionReference<T>;
+    orArrayContains(field: string, value: unknown): AdminCollectionReference<T>;
+    arrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    andArrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    orArrayContainsAny(field: string, values: unknown[] | unknown): AdminCollectionReference<T>;
+    some(field: string, condition: Record<string, unknown>): AdminCollectionReference<T>;
+    andSome(field: string, condition: Record<string, unknown>): AdminCollectionReference<T>;
+    orSome(field: string, condition: Record<string, unknown>): AdminCollectionReference<T>;
+    like(field: string, value: string): AdminCollectionReference<T>;
+    andLike(field: string, value: string): AdminCollectionReference<T>;
+    orLike(field: string, value: string): AdminCollectionReference<T>;
+    notLike(field: string, value: string): AdminCollectionReference<T>;
+    andNotLike(field: string, value: string): AdminCollectionReference<T>;
+    orNotLike(field: string, value: string): AdminCollectionReference<T>;
+    exists(field: string): AdminCollectionReference<T>;
+    andExists(field: string): AdminCollectionReference<T>;
+    orExists(field: string): AdminCollectionReference<T>;
+    notExists(field: string): AdminCollectionReference<T>;
+    andNotExists(field: string): AdminCollectionReference<T>;
+    orNotExists(field: string): AdminCollectionReference<T>;
+    latest(): AdminCollectionReference<T>;
+    newest(): AdminCollectionReference<T>;
+    oldest(): AdminCollectionReference<T>;
+    orderBy(field: string, dir?: "asc" | "desc"): AdminCollectionReference<T>;
+    limit(n: number): AdminCollectionReference<T>;
+    offset(n: number): AdminCollectionReference<T>;
+    startAt(...values: unknown[]): AdminCollectionReference<T>;
+    startAfter(...values: unknown[]): AdminCollectionReference<T>;
+    endAt(...values: unknown[]): AdminCollectionReference<T>;
+    endBefore(...values: unknown[]): AdminCollectionReference<T>;
+    aggregate(...specs: AggregateSpec[]): AdminCollectionReference<T>;
+    count(alias?: string): AdminCollectionReference<T>;
+    sum(field: string, alias?: string): AdminCollectionReference<T>;
+    avg(field: string, alias?: string): AdminCollectionReference<T>;
+    min(field: string, alias?: string): AdminCollectionReference<T>;
+    max(field: string, alias?: string): AdminCollectionReference<T>;
+    distinct(field: string, alias?: string): AdminCollectionReference<T>;
+    groupBy(...fields: string[]): AdminCollectionReference<T>;
+    having(field: string, op: HavingClause["op"], value: number): AdminCollectionReference<T>;
+    private buildStructuredJoin;
+    private cloneStructuredJoin;
+    private appendNestedJoinByAlias;
+    private parseRelationRef;
+    join(collectionName: string, j: JoinClause): AdminCollectionReference<T>;
+    joinNested(parentAlias: string, collectionName: string, j: JoinClause): AdminCollectionReference<T>;
+    Join(collectionName: string, j: JoinClause): AdminCollectionReference<T>;
+    JoinNested(parentAlias: string, collectionName: string, j: JoinClause): AdminCollectionReference<T>;
+    withRelation(relation: string, options?: (Omit<JoinClause, "source" | "target" | "as"> & {
+        as?: string;
+    })): AdminCollectionReference<T>;
+    select(...fields: string[]): AdminCollectionReference<T>;
+    distinctField(field: string): AdminCollectionReference<T>;
+    vectorSearch(opts: VectorSearchClause): AdminCollectionReference<T>;
+    getRawQuery(): {
+        collection: string;
+        query: StructuredQuery;
+    };
+    get(): Promise<T[]>;
+    first(): Promise<T | null>;
+    last(): Promise<T | null>;
+    add(data: Partial<T>): Promise<AdminDocumentReference<T>>;
+    deleteMany(): Promise<number>;
+    doc(id: string): AdminDocumentReference<T>;
+}
+
+declare class FlareAdminDbService implements FlareAdminDb {
+    private readonly cfg;
+    constructor(cfg: Required<FlareAdminConfig>);
+    /**
+     * Reference a collection for one-shot queries and mutations.
+     *
+     * 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<User>("users").get();
+     *   const admins = await admin.db().collection("users")
+     *     .where({ role: "admin" }).orderBy("name").get();
+     *   const ref = await admin.db().collection("users").add({ name: "Alice" });
+     *   await admin.db().collection("users").doc("alice").update({ plan: "pro" });
+     */
+    collection<T = Record<string, unknown>>(name: string): AdminCollectionReference<T>;
+}
+
+declare class FlareAdminAuthService implements FlareAdminAuth {
+    private readonly cfg;
+    constructor(cfg: Required<FlareAdminConfig>);
+    createCustomToken(uid: string | number, opts?: CreateCustomTokenOptions): Promise<string>;
+}
+
+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[];
+    }>;
+}
+
+type AdminRealtimeSubscriber$1 = {
+    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));
+ */
+declare class AdminLiveDocumentReference<T = Record<string, unknown>> {
+    private readonly conn;
+    /** Collection name */
+    readonly collection: string;
+    /** Document ID */
+    readonly id: string;
+    constructor(conn: AdminRealtimeSubscriber$1, 
+    /** 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;
+}
+
+type AdminRealtimeSubscriber = {
+    subscribe: (collection: string, docId: string | undefined, structuredQuery: StructuredQuery | undefined, callback: AdminSnapshotCallback, options?: AdminSubscribeOptions) => AdminSubscriptionHandle;
+};
+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;
+}
+
+/**
+ * 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();
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * @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));
+ */
+
+/**
+ * A FlareAdmin application instance.
+ * Create one with `connectApp()` and keep it as a module-level singleton.
+ */
+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!,
+ *   });
+ */
+declare function connectApp(config: FlareAdminConfig, name?: string): FlareAdminApp;
+/**
+ * Retrieve an already-initialized app by name.
+ * @throws If the app has not been initialized yet.
+ */
+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);
+ */
+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();
+ */
+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));
+ */
+declare function connection(name?: string): FlareAdminConnection;
+/**
+ * Get the notifications service from the default app.
+ * Equivalent to `getApp().notifications()`.
+ */
+declare function notifications(name?: string): FlareAdminNotifications;
+
+export { AdminCollectionReference, type AdminDocAddedCallback, type AdminDocChangedCallback, type AdminDocDeletedCallback, type AdminDocUpdatedCallback, AdminDocumentReference, AdminLiveCollectionReference, AdminLiveDocumentReference, type AdminPushSendInput, type AdminPushSendResult, type AdminPushToken, type AdminSnapshotCallback, type AdminSnapshotData, type AdminSubscriptionError, type AdminSubscriptionErrorCallback, type AdminSubscriptionHandle, type AggregateFunction, type AggregateSpec, type AnyFilter, type CreateCustomTokenOptions, type CursorValue, FlareAdminApp, type FlareAdminAuth, FlareAdminAuthService, type FlareAdminConfig, FlareAdminConnection, type FlareAdminDb, FlareAdminDbService, type FlareAdminNotifications, FlareAdminNotificationsService, FlareAdminWsConnection, type GroupByClause, type HavingClause, type JoinClause, type OrFilter, type OrderByClause, type QueryOperator, type StructuredQuery, type VectorSearchClause, type WhereCondition, type WhereFilter, auth, connectApp, connection, db, getApp, notifications };