@zuzjs/flare 0.2.1 → 0.2.4

package/dist/index.d.ts

@@ -1,80 +1,251 @@
-export { AuthGuard, AuthToken, Dropbox, Google, NormalizedProfile, OAuthProvider, ProviderId } from '@zuzjs/auth';
+import { AuthToken, AuthGuard, ProviderId } from '@zuzjs/auth';
+export { Anonymous, Apple, AuthGuard, AuthToken, CreateUserWithEmailAndPasswordInput, Credentials, Dropbox, Facebook, GitHub, Google, NormalizedProfile, OAuthProvider, ProviderId, Providers, SignInAnonymouslyInput, SignInWithEmailAndPasswordInput, Twitter, setupProvider } 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.
+     * Optional HTTP base URL for auth API calls.
+     * When set, all auth HTTP calls go through this base instead of calling
+     * Flare directly. Use this to route calls through a Next.js proxy so CSRF
+     * is handled entirely server-side.
+     * Example: '/api/flare'  (relative, browser resolves against current origin)
      */
+    httpBase?: string;
+    appId: string;
+    apiKey?: string;
     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) */
+    requestTiming?: boolean;
     connectionTimeout?: number;
 }
-/**
- * Query configuration (NEW v0.2: Object-based query syntax)
- */
+type FlareAuthProviderId = "credentials" | "anonymous" | "google" | "facebook" | "github" | "dropbox" | "apple" | "twitter";
+interface FlareAuthProviderPublicConfig {
+    enabled: boolean;
+    clientId?: string;
+    scopes?: string[];
+}
+interface FlareAuthConfig {
+    appId: string;
+    enabled: boolean;
+    needsEmailVerification?: boolean;
+    autoSendVerificationEmail?: boolean;
+    redirectUri?: string;
+    csrfToken?: string;
+    cookie?: {
+        accessTokenName?: string;
+        refreshTokenName?: string;
+        csrfTokenName?: string;
+        domain?: string;
+        path?: string;
+        secure?: boolean;
+        sameSite?: "Lax" | "Strict" | "None";
+        accessTokenMaxAge?: number;
+        refreshTokenMaxAge?: number;
+        csrfTokenMaxAge?: number;
+    };
+    providers: Record<FlareAuthProviderId, FlareAuthProviderPublicConfig>;
+}
+interface FlareAuthSession {
+    uid: string;
+    accessToken: string;
+    refreshToken: string | null;
+    provider?: string;
+    email?: string | null;
+    emailVerified?: boolean;
+}
+interface FlareAuthUser {
+    uid: string;
+    email: string;
+    email_verified: string;
+    [x: string]: any;
+}
+type AuthStateListener = (session: FlareAuthSession & FlareAuthUser | null) => void;
+type AuthConfigListener = (conf: FlareAuthConfig) => void;
+interface SubscribeOptions {
+    skipSnapshot?: boolean;
+}
+type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains" | "array-contains-any" | "like" | "not-like" | "contains" | "exists" | "not-exists";
 interface QueryConfig {
     field: string;
     op: QueryOperator;
     value: unknown;
 }
-/**
- * Where condition (NEW v0.2: Object-based syntax)
- * Example: { age: ">= 25", role: "admin" }
- */
+/** OR group */
+interface OrFilter {
+    or: QueryConfig[];
+}
+type AnyFilter = QueryConfig | OrFilter;
 type WhereCondition = Record<string, string | number | boolean | any[]>;
-type QueryOperator = "==" | "!=" | "<" | "<=" | ">" | ">=" | "in" | "not-in" | "array-contains";
+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;
+}
 /**
- * Subscription callback
+ * Join definition used by CollectionReference.Join().
+ *
+ * Example:
+ *   Join("tasks", { source: "id", target: "boardId", as: "tasks" })
  */
-type SubscriptionCallback<T = any> = (data: SubscriptionData<T>) => void;
+interface JoinQueryPattern {
+    where?: AnyFilter[];
+    orderBy?: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    startAt?: CursorValue;
+    startAfter?: CursorValue;
+    endAt?: CursorValue;
+    endBefore?: CursorValue;
+    aggregate?: AggregateSpec[];
+    groupBy?: GroupByClause;
+    having?: HavingClause[];
+    vectorSearch?: VectorSearchClause;
+    select?: string[];
+    distinctField?: string;
+}
+interface NestedJoinClause extends JoinQueryPattern {
+    /** Joined collection name for this nested join. */
+    collection: string;
+    /** Field from the parent join result. */
+    source: string;
+    /** Field from this nested collection to match source. */
+    target: string;
+    /** Alias where nested rows are attached in each parent join row. */
+    as: string;
+    /** If true, expect at most one joined row. */
+    single?: boolean;
+    /** Recursive nested joins. */
+    joins?: NestedJoinClause[];
+}
+interface JoinClause extends JoinQueryPattern {
+    /** Field from the base collection (the collection you started the query on). */
+    source: string;
+    /** Field from the joined collection that should match source. */
+    target: string;
+    /** Alias where joined rows will be attached in each result object. */
+    as: string;
+    /** If true, expect at most one joined row (object instead of array on server side). */
+    single?: boolean;
+    /** Optional nested joins under this join. */
+    joins?: NestedJoinClause[];
+}
+/** Internal wire-ready join shape sent to server query engine. */
+interface StructuredJoinClause extends JoinQueryPattern {
+    from: string;
+    localField: string;
+    foreignField: string;
+    as: string;
+    single?: boolean;
+    joins?: StructuredJoinClause[];
+}
+interface VectorSearchClause {
+    field: string;
+    vector: number[];
+    k: number;
+    metric?: "cosine" | "euclidean" | "dotProduct";
+    minScore?: number;
+}
+/** Full structured query (Firestore + SQL feature set) */
+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;
+}
+type QueryPresetSpec<Params extends Record<string, unknown> = Record<string, unknown>, Row = any> = {
+    params: Params;
+    row: Row;
+};
+type QueryPresetMap = Record<string, QueryPresetSpec<any, any>>;
+type QueryPresetParams<TSpec> = TSpec extends QueryPresetSpec<infer Params, any> ? Params : Record<string, unknown>;
+type QueryPresetRow<TSpec> = TSpec extends QueryPresetSpec<any, infer Row> ? Row : any;
+type ChangeOperation = 'insert' | 'update' | 'replace' | 'delete';
 /**
- * Subscription data received from server
+ * Fired once when the subscription is first established.
+ * `data` is always an array — the full matching collection snapshot.
  */
-interface SubscriptionData<T = any> {
+interface SnapshotEvent<T = any> {
+    type: 'snapshot';
     subscriptionId: string;
     collection: string;
-    docId?: string;
-    data: T | T[];
-    type: 'snapshot' | 'change';
-    operation?: 'insert' | 'update' | 'delete' | 'replace';
+    data: T[];
 }
 /**
- * Document reference
+ * Fired on every subsequent document mutation that matches the subscription query.
+ * `data` is the single affected document (null on delete).
  */
+interface ChangeEvent<T = any> {
+    type: 'change';
+    subscriptionId: string;
+    collection: string;
+    docId: string;
+    operation: ChangeOperation;
+    data: T | null;
+}
+/** Discriminated union — narrow on `event.type` to get the right shape. */
+type SubscriptionData<T = any> = SnapshotEvent<T> | ChangeEvent<T>;
+type SubscriptionCallback<T = any> = (data: SubscriptionData<T>) => void;
+interface SubscriptionError {
+    code?: string;
+    message: string;
+    permissionDenied: boolean;
+    raw?: unknown;
+}
+type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+interface SubscriptionHandle {
+    (): void;
+    unsubscribe: () => void;
+    onError: (callback: SubscriptionErrorCallback) => SubscriptionHandle;
+    onPermissionDenied: (callback: SubscriptionErrorCallback) => SubscriptionHandle;
+    catch: (callback: SubscriptionErrorCallback) => SubscriptionHandle;
+}
+type DocAddedCallback<T = any> = (data: T, docId: string) => void;
+type DocUpdatedCallback<T = any> = (data: T, docId: string) => void;
+type DocDeletedCallback<T = any> = (docId: string) => void;
+type DocChangedCallback<T = any> = (data: T | null, docId: string, operation: ChangeOperation) => void;
 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';
@@ -84,18 +255,74 @@ interface OfflineOperation {
     merge?: boolean;
     clientTs: number;
 }
-/**
- * Authentication result
- */
 interface AuthResult {
     uid: string;
     token?: string;
 }
-/**
- * Connection state
- */
 type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error';
+interface AuthWithPendingVerificationResult {
+    verificationRequired: true;
+    created: true;
+    emailSent: boolean;
+    preview?: {
+        code: string;
+        link: string;
+    };
+}
+interface AuthWithTokenResult extends AuthResult {
+    accessToken: string;
+    refreshToken: string | null;
+    authToken: AuthToken;
+    created: boolean;
+}
+interface PresenceMember {
+    uid: string;
+    socketId: string;
+    room: string;
+    meta?: Record<string, unknown>;
+    joinedAt: number;
+    lastSeen: number;
+}
+type PresenceCallback = (members: PresenceMember[]) => void;
+type PresenceJoinCallback = (member: PresenceMember) => void;
+type PresenceLeaveCallback = (uid: string) => void;
+/** Fields marked as vector will be auto-embedded before write */
+type VectorFieldConfig = {
+    /** Dimensions of the vector (e.g. 1536 for OpenAI ada-002) */
+    dimensions: number;
+    /** Optional custom embedding function; defaults to client-configured embedder */
+    embed?: (text: string) => Promise<number[]>;
+};
+type RulePermission = "create" | "read" | "update" | "delete";
+interface FlareRule {
+    id: string;
+    name: string;
+    auth: "any" | "guest" | "auth";
+    collection: string;
+    document?: string;
+    condition?: string;
+    permissions: RulePermission[];
+}
+interface SecurityRuleEntry {
+    ".read"?: string;
+    ".write"?: string;
+    ".create"?: string;
+    ".update"?: string;
+    ".delete"?: string;
+}
+type SecurityRulesMap = Record<string, SecurityRuleEntry>;
+declare const flareRulesToSecurityMap: (rules: FlareRule[]) => SecurityRulesMap;
+declare const securityMapToFlareRules: (rules: SecurityRulesMap) => FlareRule[];
 
+/**
+ * Parse ORM-style where condition: { age: ">= 25", role: "admin" }
+ * Returns array of QueryConfig objects
+ */
+declare function parseWhereCondition(condition: WhereCondition): QueryConfig[];
+/**
+ * Parse string value to appropriate type
+ */
+declare function parseValue(val: string): any;
 /**
  * Query builder for document operations (ORM-style)
  * Supports: doc('users').update({...}).where({ id: 'alice' })
@@ -114,7 +341,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
     private setData?;
     private deleteOp;
     private promise?;
-    constructor(client: FlareClient, collection: string, legacyId?: string | undefined);
+    constructor(client: FlareClient<any>, collection: string, legacyId?: string | undefined);
     /**
      * Set where condition
      */
@@ -157,6 +384,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
      */
     onSnapshot(callback: SubscriptionCallback<T>): () => void;
 }
+
 /**
  * Legacy document reference (for backward compatibility)
  */
@@ -164,63 +392,124 @@ declare class DocumentReference<T = any> {
     private client;
     readonly collection: string;
     readonly id: string;
-    constructor(client: FlareClient, collection: string, id: string);
+    constructor(client: FlareClient<any>, 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;
+    /**
+     * Fires when this document is updated / replaced.
+     * Aliases: onDocModified, onDocChange
+     */
+    onDocUpdated(callback: DocUpdatedCallback<T>): () => void;
+    /** Alias for onDocUpdated */
+    onDocModified(callback: DocUpdatedCallback<T>): () => void;
+    /** Alias for onDocUpdated */
+    onDocChange(callback: DocUpdatedCallback<T>): () => void;
+    /**
+     * Fires when this document is deleted.
+     */
+    onDocDeleted(callback: DocDeletedCallback<T>): () => void;
+    /**
+     * Fires on any change to this document (update / delete).
+     * `data` is null on deletes.
+     */
+    onDocChanged(callback: DocChangedCallback<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[]> {
+
+type CollectionPresetMethods<TPresetMap extends QueryPresetMap> = {
+    [K in keyof TPresetMap & string]: (params: QueryPresetParams<TPresetMap[K]>) => CollectionQuery<QueryPresetRow<TPresetMap[K]>, TPresetMap>;
+};
+type CollectionQuery<T = any, TPresetMap extends QueryPresetMap = {}> = CollectionReference<T, TPresetMap> & CollectionPresetMethods<TPresetMap>;
+declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {}> implements PromiseLike<T[]> {
     private client;
     readonly collection: string;
-    private queries;
+    private sq;
     private promise?;
-    constructor(client: FlareClient, collection: string);
-    /**
-     * Get a document reference (legacy API)
-     */
+    constructor(client: FlareClient<TPresetMap>, collection: string);
     doc(id: string): DocumentReference<T>;
+    private clone;
+    with<Name extends keyof TPresetMap & string>(name: Name, params: QueryPresetParams<TPresetMap[Name]>): CollectionQuery<QueryPresetRow<TPresetMap[Name]>, TPresetMap>;
+    with(name: string, params?: Record<string, unknown>): CollectionQuery<T, TPresetMap>;
+    /** ORM shorthand: .where({ age: ">= 25", role: "admin" }) */
+    where(condition: WhereCondition): CollectionQuery<T, TPresetMap>;
+    /** Explicit field/op/value */
+    where(field: string, op: QueryConfig['op'], value: unknown): CollectionQuery<T, TPresetMap>;
+    /** OR group: .orWhere([{ field:"status", op:"==", value:"active" }, ...]) */
+    orWhere(filters: QueryConfig[]): CollectionQuery<T, TPresetMap>;
+    /** Get items starting from the most recently created (descending sequence) */
+    latest(): CollectionQuery<T, TPresetMap>;
+    /** Get items starting from the first ever created (ascending sequence) */
+    oldest(): CollectionQuery<T, TPresetMap>;
+    orderBy(field: string, dir?: "asc" | "desc"): CollectionQuery<T, TPresetMap>;
+    limit(n: number): CollectionQuery<T, TPresetMap>;
+    offset(n: number): CollectionQuery<T, TPresetMap>;
+    startAt(...values: unknown[]): CollectionQuery<T, TPresetMap>;
+    startAfter(...values: unknown[]): CollectionQuery<T, TPresetMap>;
+    endAt(...values: unknown[]): CollectionQuery<T, TPresetMap>;
+    endBefore(...values: unknown[]): CollectionQuery<T, TPresetMap>;
+    aggregate(...specs: AggregateSpec[]): CollectionQuery<T, TPresetMap>;
+    count(alias?: string): CollectionQuery<T, TPresetMap>;
+    sum(field: string, alias?: string): CollectionQuery<T, TPresetMap>;
+    avg(field: string, alias?: string): CollectionQuery<T, TPresetMap>;
+    min(field: string, alias?: string): CollectionQuery<T, TPresetMap>;
+    max(field: string, alias?: string): CollectionQuery<T, TPresetMap>;
+    distinct(field: string, alias?: string): CollectionQuery<T, TPresetMap>;
+    groupBy(...fields: string[]): CollectionQuery<T, TPresetMap>;
+    having(field: string, op: HavingClause['op'], value: number): CollectionQuery<T, TPresetMap>;
+    private buildStructuredJoin;
     /**
-     * Add a where filter (NEW ORM-style API)
-     * @example .where({ age: ">= 25", role: "admin" })
+     * Join another collection into this query.
+     *
+     * @param collectionName Joined collection name.
+     * @param j Join mapping clause.
+     * @example
+     *   flare.collection("boards")
+     *     .Join("tasks", { source: "id", target: "boardId", as: "tasks" })
+     *     .get();
      */
-    where(condition: WhereCondition): CollectionReference<T>;
+    Join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
     /**
-     * Get all documents once
-     * @deprecated Use await directly instead of .get()
+     * Legacy join signature.
+     * Prefer Join(collectionName, clause) for better readability.
      */
-    get(): Promise<T[]>;
+    join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
+    join(j: JoinClause & {
+        from?: string;
+        collection?: string;
+    }): CollectionQuery<T, TPresetMap>;
+    select(...fields: string[]): CollectionQuery<T, TPresetMap>;
+    /** Returns unique values for a single field */
+    distinctField(field: string): CollectionQuery<T, TPresetMap>;
     /**
-     * Internal execute method
+     * KNN nearest-neighbour search (requires Atlas vector index).
+     * @example
+     *   col.vectorSearch({ field: "embedding", vector: [...1536 numbers...], k: 10 })
      */
+    vectorSearch(opts: VectorSearchClause): CollectionQuery<T, TPresetMap>;
+    get(): Promise<T[]>;
+    private _isStructured;
     private _execute;
-    /**
-     * Make this class thenable so it can be awaited directly
-     */
+    private _executeQuery;
+    private _executeSubscribe;
     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
+     * Subscribe to real-time updates.
+     * The full StructuredQuery (including orderBy, where, limit, offset) is sent
+     * to the server so the initial snapshot respects all constraints.
+     * Individual change events are then sorted / filtered client-side to keep
+     * the live result consistent.
      */
+    onSnapshot(callback: SubscriptionCallback<T[]>): SubscriptionHandle;
+    onDocAdded(callback: DocAddedCallback<T>): () => void;
+    onDocUpdated(callback: DocUpdatedCallback<T>): () => void;
+    onDocModified(callback: DocUpdatedCallback<T>): () => void;
+    onDocChange(callback: DocUpdatedCallback<T>): () => void;
+    onDocDeleted(callback: DocDeletedCallback<T>): () => void;
+    onDocChanged(callback: DocChangedCallback<T>): () => void;
     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>;
 }
 
@@ -233,8 +522,13 @@ declare enum FlareAction {
     AUTH = "auth",
     PING = "ping",
     OFFLINE_SYNC = "offline_sync",
-    /** General-purpose RPC / topic call */
-    CALL = "call"
+    CALL = "call",
+    /** One-shot rich query (no real-time subscription) */
+    QUERY = "query",
+    /** Presence */
+    PRESENCE_JOIN = "presence_join",
+    PRESENCE_LEAVE = "presence_leave",
+    PRESENCE_HEARTBEAT = "presence_heartbeat"
 }
 /** Server Response */
 declare enum FlareEvent {
@@ -245,116 +539,640 @@ declare enum FlareEvent {
     PONG = "pong",
     AUTH_OK = "auth_ok",
     OFFLINE_ACK = "offline_ack",
-    /** Response to a CALL */
-    CALL_RESPONSE = "call_response"
+    CALL_RESPONSE = "call_response",
+    QUERY_RESULT = "query_result",
+    PRESENCE_STATE = "presence_state",
+    PRESENCE_JOIN = "presence_join",
+    PRESENCE_LEAVE = "presence_leave"
 }
 interface BaseMessage {
     id: string;
     type: FlareAction | FlareEvent;
     ts: number;
 }
+interface SubscribeMessage extends BaseMessage {
+    type: FlareAction.SUBSCRIBE;
+    collection: string;
+    docId?: string;
+    query?: Record<string, unknown>;
+    skipSnapshot?: boolean;
+    resumeToken?: string;
+}
+
+type TransportOptions = {
+    url: string;
+    onMessage: (data: any) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onError?: (error: Error) => void;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnectDelay?: number;
+    debug?: boolean;
+    /** RSA public key (PEM). When set, all outgoing messages are RSA-OAEP encrypted. */
+    publicKey?: string;
+};
+
+declare class FlareTransport {
+    private socket;
+    private reconnectInterval;
+    private maxReconnectDelay;
+    private isConnected;
+    private shouldReconnect;
+    private options;
+    private messageQueue;
+    private heartbeatInterval;
+    private connectionTimeout;
+    constructor(options: TransportOptions);
+    connect(): void;
+    private handleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private flushQueue;
+    send(message: object): void;
+    disconnect(): void;
+    get connected(): boolean;
+    private log;
+}
 
 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;
+type HttpResponseSnapshot = {
+    status: number;
+    headers: Record<string, string>;
+    data: any;
+};
+type ActiveSubscription = {
+    baseId: string;
+    liveId: string;
+    collection: string;
+    docId?: string;
+    query?: QueryConfig | StructuredQuery;
+    callback: SubscriptionCallback;
+    options: SubscribeOptions;
+};
+type QueryPresetHandler<Params extends Record<string, unknown> = Record<string, unknown>, Row = any> = (ref: CollectionQuery<any, any>, params: Params) => CollectionQuery<Row, any>;
+/** Embedder function registered by the user */
+type EmbedFn = (text: string) => Promise<number[]>;
+declare class FlareBase<TPresetMap extends QueryPresetMap = {}> {
+    protected transport: FlareTransport;
+    protected readonly config: FlareConfig;
+    protected readonly pendingAcks: Map<string, (value: any) => void>;
+    protected readonly subscriptions: Map<string, SubscriptionCallback>;
+    protected readonly activeSubscriptions: Map<string, ActiveSubscription>;
+    protected readonly queryPresets: Map<string, QueryPresetHandler<any, any>>;
+    protected readonly subscriptionErrorHandlers: Map<string, Set<SubscriptionErrorCallback>>;
+    protected readonly subscriptionPermissionHandlers: Map<string, Set<SubscriptionErrorCallback>>;
+    protected readonly subscriptionLastErrors: Map<string, SubscriptionError>;
+    protected readonly offlineQueue: any[];
+    protected currentState: ConnectionState;
+    protected connectionListeners: ConnectionListener[];
+    protected errorListeners: ErrorListener[];
+    protected isDebug: boolean;
+    protected socketAuthUid: string;
+    protected pendingSubscriptionReplay: boolean;
+    protected subscriptionReplayPromise: Promise<void>;
+    protected requestTraceSeq: number;
+    protected requestTimingEnabled: boolean;
+    protected httpInFlight: Map<string, Promise<HttpResponseSnapshot>>;
+    protected httpResponseCache: Map<string, HttpResponseSnapshot>;
+    protected readonly maxHttpCacheEntries = 200;
+    protected presenceCallbacks: Map<string, PresenceCallback[]>;
+    protected presenceJoinCbs: Map<string, PresenceJoinCallback[]>;
+    protected presenceLeaveCbs: Map<string, PresenceLeaveCallback[]>;
+    protected presenceHeartbeatTimer?: ReturnType<typeof setInterval>;
+    protected embedder?: EmbedFn;
+    protected vectorSchema: Map<string, Map<string, VectorFieldConfig>>;
+    protected throwFetchFlareError(payload: unknown, fallbackMessage: string, fallbackCode: string): never;
+    protected nowMs(): number;
+    protected normalizeHeaders(headers?: HeadersInit): Record<string, string>;
+    protected redactHeaders(headers: Record<string, string>): Record<string, string>;
+    protected stableStringify(value: unknown): string;
+    protected buildHttpCacheKey(method: string, url: string, headers: Record<string, string>, body: unknown, credentials?: RequestCredentials): string;
+    protected shouldCacheResponse(method: string, url: string): boolean;
+    protected rememberHttpResponse(key: string, value: HttpResponseSnapshot): void;
+    protected createTimedFetchTrace(snapshot: HttpResponseSnapshot, requestId: number, startedAtMs: number, method: string, url: string, networkMs: number): {
+        response: {
+            status: number;
+            ok: boolean;
+            headers: {
+                get: (name: string) => string | null;
+            };
+            json: () => Promise<any>;
+        };
+        requestId: number;
+        startedAtMs: number;
+        networkMs: number;
+        method: string;
+        url: string;
+    };
+    protected logHttpTiming(...args: any[]): void;
+    protected mergeHeaders(base: HeadersInit | undefined, extra: Record<string, string>): HeadersInit;
+    protected toWireField(field: string): string;
+    protected fromWireField(field: string): string;
+    protected normalizeOutboundData(value: unknown): unknown;
+    protected normalizeInboundData(value: unknown): unknown;
+    protected normalizeOutboundAnyFilter(filter: Record<string, unknown>): Record<string, unknown>;
+    protected normalizeOutboundQuery(query: unknown): unknown;
+    protected timedFetch(label: string, input: string, init?: RequestInit): Promise<{
+        response: {
+            status: number;
+            ok: boolean;
+            headers: {
+                get: (name: string) => string | null;
+            };
+            json: () => Promise<any>;
+        };
+        requestId: number;
+        startedAtMs: number;
+        networkMs: number;
+        method: string;
+        url: string;
+    }>;
+    protected parseJsonWithTiming(label: string, trace: {
+        requestId: number;
+        startedAtMs: number;
+        response: {
+            status: number;
+            ok: boolean;
+            headers: {
+                get: (name: string) => string | null;
+            };
+            json: () => Promise<any>;
+        };
+        networkMs: number;
+        method: string;
+        url: string;
+    }): Promise<any>;
+    protected getHttpBase(): string;
+    protected log(...args: any[]): void;
     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;
+    onError(callback: ErrorListener): () => void;
+    collection<T = any>(name: string): CollectionQuery<T, TPresetMap>;
+    registerQueryPreset<Name extends string, Params extends Record<string, unknown>, Row = any>(name: Name, handler: QueryPresetHandler<Params, Row>): this & FlareBase<TPresetMap & Record<Name, QueryPresetSpec<Params, Row>>>;
+    registerQueryPresets<TRegistry extends Record<string, QueryPresetHandler<any, any>>>(presets: TRegistry): this & FlareBase<TPresetMap & {
+        [K in keyof TRegistry]: TRegistry[K] extends QueryPresetHandler<infer Params, infer Row> ? QueryPresetSpec<Params, Row> : QueryPresetSpec<Record<string, unknown>, any>;
+    }>;
+    hasQueryPreset(name: string): boolean;
+    applyQueryPreset<Name extends keyof TPresetMap & string>(ref: CollectionReference<any, TPresetMap>, name: Name, params: QueryPresetParams<TPresetMap[Name]>): CollectionQuery<QueryPresetRow<TPresetMap[Name]>, TPresetMap>;
+    applyQueryPreset<T = any>(ref: CollectionQuery<T, TPresetMap>, name: string, params?: Record<string, unknown>): CollectionQuery<T, TPresetMap>;
+    doc<T = any>(collection: string): DocumentQueryBuilder<T>;
+    doc<T = any>(collection: string, id: string): DocumentReference<T>;
+    ping(): Promise<number>;
+    call<T = Record<string, unknown>>(topic: string, payload?: Record<string, unknown>): Promise<T>;
+    query<T = Record<string, unknown>>(collection: string, q?: StructuredQuery): Promise<T[]>;
+    setEmbedder(fn: EmbedFn): void;
+    markVectorField(collection: string, field: string, config?: VectorFieldConfig): void;
+    embedVectorFields(collection: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    joinPresence(room: string, meta?: Record<string, unknown>): Promise<() => void>;
+    leavePresence(room: string): Promise<void>;
+    onPresenceState(room: string, cb: PresenceCallback): () => void;
+    onPresenceJoin(room: string, cb: PresenceJoinCallback): () => void;
+    onPresenceLeave(room: string, cb: PresenceLeaveCallback): () => void;
+    private _startPresenceHeartbeat;
+    private _stopPresenceHeartbeat;
+    syncOffline(): Promise<void>;
+    protected beforeActivateSubscription(_entry: ActiveSubscription): Promise<void>;
+    protected activateSubscription(entry: ActiveSubscription): Promise<void>;
+    protected toSubscriptionError(err: unknown): SubscriptionError;
+    protected emitSubscriptionError(baseId: string, error: SubscriptionError): void;
+    protected replayActiveSubscriptions(): Promise<void>;
+    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | StructuredQuery | undefined, callback: SubscriptionCallback, options?: SubscribeOptions): SubscriptionHandle;
+    send(type: FlareAction, payload: any): Promise<any>;
+    private handleTransportError;
+    protected onConnected(): void;
+    protected onDisconnected(): void;
+    protected setState(state: ConnectionState): void;
+    protected handleIncoming(msg: any): void;
+}
+
+/**
+ * FlareAuth extends FlareBase with all authentication and CSRF logic.
+ *
+ * CSRF strategy
+ * ─────────────
+ * The server sets an HttpOnly cookie on /auth/config responses. The raw
+ * cookie value is NOT readable by JS (HttpOnly), but the server also echoes
+ * the token in the `x-flare-csrf` response header so the client can send
+ * it back as `x-flare-csrf` on every mutating request.
+ *
+ * Two environments are supported:
+ *   1. Browser  – header is read from the /auth/config fetch; stored in
+ *                 `this.csrfToken` (in-memory only, never written to a
+ *                 readable cookie by the client).
+ *   2. Next.js SSR – use the standalone `createCsrfProxy()` handler
+ *                 (see Client/proxy.ts) which captures the Set-Cookie header
+ *                 from Flare server and sets it on the client domain too, so
+ *                 the browser owns two HttpOnly cookies: one from the Flare
+ *                 domain and one from the Next.js domain.
+ */
+declare class FlareAuth<TPresetMap extends QueryPresetMap = {}> extends FlareBase<TPresetMap> {
+    protected authToken?: string;
+    protected userId?: string;
+    protected authGuard?: AuthGuard;
+    protected authConfig?: FlareAuthConfig;
+    /** In-memory CSRF token extracted from the `x-flare-csrf` response header */
+    protected csrfToken?: string;
+    protected csrfInitPromise?: Promise<void>;
+    protected csrfBootstrapAttempted: boolean;
+    protected socketAuthSyncPromise?: Promise<void>;
+    protected authSession: FlareAuthSession | null;
+    protected authStateListeners: AuthStateListener[];
+    protected authConfigListeners: AuthConfigListener[];
+    protected currentProfile: FlareAuthUser | undefined;
+    private getDefaultCsrfCookieName;
+    getCsrfCookieName(): string;
     /**
-     * Listen to errors
+     * Read the CSRF token from a browser-readable cookie (set by the server as
+     * a non-HttpOnly fallback) or fall back to the in-memory value captured
+     * from the response header.
+     *
+     * Priority:
+     *   1. Non-HttpOnly cookie on the current domain (browser only)
+     *   2. In-memory value from `x-flare-csrf` response header
      */
-    onError(callback: ErrorListener): () => void;
+    getCsrfToken(): string | null;
+    private getCookieValue;
     /**
-     * Ping the server
+     * Extract CSRF token from a server response.
+     * The server now sends it ONLY as the `x-flare-csrf` response header
+     * (not in the JSON body). We still support the body field as a fallback
+     * for older server versions.
      */
-    ping(): Promise<number>;
+    protected extractCsrfToken(json: unknown, response?: {
+        headers: {
+            get: (name: string) => string | null;
+        };
+    }): string | undefined;
+    getCsrfHeaders(): Record<string, string>;
     /**
-     * Invoke a server-side CALL handler by topic and await its response.
+     * Inject CSRF token directly (used by SSR middleware).
+     * This allows the server to bootstrap CSRF once and inject it into the client,
+     * preventing redundant /auth/config calls.
      *
      * @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
+     * // In Next.js middleware
+     * const csrf = extractCsrfFromRequest(request, appId);
+     * if (csrf) {
+     *   flareClient.setCsrfToken(csrf);
+     * }
      */
-    syncOffline(): Promise<void>;
-    private handleTransportError;
-    private onConnected;
-    private onDisconnected;
-    private setState;
-    private handleIncoming;
+    setCsrfToken(token: string): void;
+    ensureCsrfProtection(): Promise<void>;
+    loadAuthConfig(): Promise<FlareAuthConfig>;
+    protected fetchAuthConfig(): Promise<FlareAuthConfig>;
+    onAuthConfigLoaded(listener: AuthConfigListener): () => void;
+    protected setProfile(profile: FlareAuthUser): void;
+    protected setAuthSession(session: FlareAuthSession | null): void;
+    onAuthStateChanged(listener: AuthStateListener): () => void;
+    onAuthStateChange(listener: AuthStateListener): () => void;
+    get currentUser(): FlareAuthUser | undefined;
+    getCurrentUser(): FlareAuthUser | undefined;
+    protected syncSocketAuth(accessToken?: string | null): Promise<void>;
+    protected updateSocketIdentity(uid?: string, forceReplay?: boolean): Promise<void>;
+    protected beforeActivateSubscription(_entry: any): Promise<void>;
+    protected onConnected(): void;
+    protected handleIncoming(msg: any): void;
+    auth(token: string): Promise<AuthResult>;
+    signInWithEmailAndPassword(email: string, password: string, options?: {
+        scope?: string[];
+        createIfMissing?: boolean;
+    }): Promise<AuthResult & {
+        kind?: string;
+        accessToken: string;
+        refreshToken: string | null;
+        authToken: AuthToken;
+        created?: boolean;
+    }>;
+    signInWithEmail(email: string, password: string, options?: {
+        scope?: string[];
+        createIfMissing?: boolean;
+    }): Promise<AuthResult & {
+        kind?: string;
+        accessToken: string;
+        refreshToken: string | null;
+        authToken: AuthToken;
+        created?: boolean;
+    }>;
+    createUserWithEmail(email: string, password: string, options?: {
+        scope?: string[];
+        additionalParams?: Record<string, string>;
+        signInIfAllowed?: boolean;
+    }): Promise<{
+        kind?: string;
+        verificationRequired: true;
+        emailSent: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    } | (AuthResult & {
+        kind?: string;
+        accessToken: string;
+        refreshToken: string | null;
+        authToken: AuthToken;
+        verificationRequired?: false;
+        emailSent?: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    })>;
+    createUserWithEmailAndPassword(email: string, password: string, options?: {
+        scope?: string[];
+        additionalParams?: Record<string, string>;
+        signInIfAllowed?: boolean;
+    }): Promise<{
+        kind?: string;
+        verificationRequired: true;
+        emailSent: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    } | (AuthResult & {
+        kind?: string;
+        accessToken: string;
+        refreshToken: string | null;
+        authToken: AuthToken;
+        verificationRequired?: false;
+        emailSent?: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    })>;
+    signInOrCreateWithEmail(email: string, password: string, options?: {
+        scope?: string[];
+        additionalParams?: Record<string, string>;
+    }): Promise<{
+        kind?: string;
+        verificationRequired: true;
+        created: true;
+        emailSent: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    } | (AuthResult & {
+        accessToken: string;
+        refreshToken: string | null;
+        authToken: AuthToken;
+        created: boolean;
+    })>;
+    signInOrCreateWithEmailAndPassword(email: string, password: string, options?: {
+        scope?: string[];
+        additionalParams?: Record<string, string>;
+    }): Promise<{
+        kind?: string;
+        verificationRequired: true;
+        created: true;
+        emailSent: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    } | (AuthResult & {
+        accessToken: string;
+        refreshToken: string | null;
+        authToken: AuthToken;
+        created: boolean;
+    })>;
+    sendEmailVerification(email: string): Promise<{
+        sent: boolean;
+        emailSent: boolean;
+        preview?: {
+            code: string;
+            link: string;
+        };
+    }>;
+    verifyEmailWithCode(email: string, code: string): Promise<{
+        verified: boolean;
+        email: string;
+    }>;
+    confirmEmailLink(token: string, email: string): Promise<{
+        verified: boolean;
+        email: string;
+    }>;
+    sendAccountRecovery(email: string): Promise<{
+        sent: boolean;
+        emailSent?: boolean;
+        preview?: {
+            code: string;
+            token: string;
+        };
+    }>;
+    recoverAccountWithCode(email: string, code: string, newPassword: string): Promise<{
+        recovered: boolean;
+        email: string;
+        sessionsRevoked?: number;
+    }>;
+    recoverAccountWithToken(token: string, newPassword: string): Promise<{
+        recovered: boolean;
+        email: string;
+        sessionsRevoked?: number;
+    }>;
+    signIn(providerId: ProviderId, options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signIn(authGuard: Pick<AuthGuard, 'signIn'>, providerId: ProviderId, options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithGoogle(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithGitHub(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithFacebook(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithDropbox(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    handleSignInRedirect(autoRedirect?: boolean): Promise<(AuthResult & {
+        authToken: AuthToken;
+        provider?: ProviderId;
+    }) | null>;
+    handleSignInRedirect(authGuard: Pick<AuthGuard, 'handleRedirect'>, autoRedirect?: boolean): Promise<(AuthResult & {
+        authToken: AuthToken;
+        provider?: ProviderId;
+    }) | null>;
+    private exchangeProviderToken;
+    protected getAuthGuard(): Promise<AuthGuard>;
+    refreshAuthSession(refresh_token?: string): Promise<FlareAuthSession | null>;
+    issueSsrToken(ttlSeconds?: number): Promise<{
+        token: string;
+        token_type: string;
+        expires_in: number;
+        uid: string;
+        role: string;
+        email?: string;
+    }>;
+    signOut(): Promise<void>;
+    protected registerWithEmail(email: string, password: string, options?: {
+        scope?: string[];
+        additionalParams?: Record<string, string>;
+        signInIfAllowed?: boolean;
+    }): Promise<Record<string, any>>;
+    protected requestEmailPasswordToken(email: string, password: string, scope?: string[]): Promise<AuthToken & {
+        kind: string;
+    }>;
+    protected fetchAuthMe(token: string): Promise<{
+        id?: string;
+        email?: string | null;
+        email_verified?: boolean;
+    }>;
+}
+
+/**
+ * Client/index.ts ─ entry point
+ *
+ * FlareClient is the public-facing class. All logic lives in:
+ *   - Client/base.ts  → transport, subscriptions, presence, vector, offline
+ *   - Client/auth.ts  → CSRF capture, all auth & session methods
+ *
+ * CSRF Protection (SSR-Only by Default)
+ * ────────────────────────────────────
+ * FlareClient does NOT automatically fetch CSRF on construction. Instead:
+ *
+ *   1. SSR (Next.js): Middleware fetches /auth/config once, sets CSRF as HttpOnly
+ *      cookie on response. Methods automatically use this cookie (no extra calls).
+ *
+ *   2. Browser-only (SPA): Explicitly call client.ensureCsrfProtection() before
+ *      mutations to fetch /auth/config and cache CSRF token in memory.
+ *
+ * Why? Eliminates redundant /auth/config calls in SSR, where every method used
+ * to fetch it again internally. Now CSRF bootstrapping happens once (in middleware),
+ * and auth methods just use getCsrfHeaders() which returns the cached token
+ * (if available) or empty object (relying on HttpOnly cookie validation).
+ *
+ * This file wires FlareAuth together and leaves CSRF bootstrapping to the user.
+ */
+
+declare class FlareClient<TPresetMap extends QueryPresetMap = {}> extends FlareAuth<TPresetMap> {
+    constructor(config: FlareConfig);
+}
+
+/**
+ * Client/proxy.ts ─ Next.js SSR CSRF proxy helper
+ *
+ * Why this exists
+ * ───────────────
+ * The Flare server now sets the CSRF token exclusively as an HttpOnly cookie
+ * on its own domain (e.g. api.flare.example.com) and also echoes it in the
+ * `x-flare-csrf` response header so the browser client can capture it in-
+ * memory and send it back as a request header.
+ *
+ * When your Next.js app runs server-side rendering (SSR / Route Handlers /
+ * Server Actions) it operates on a *different* domain (e.g. app.example.com).
+ * The browser's HttpOnly Flare cookie is scoped to the Flare domain and is
+ * therefore NOT automatically forwarded by the browser to your Next.js
+ * server-side fetch calls.
+ *
+ * Solution — two-cookie strategy
+ * ────────────────────────────────
+ * 1. Browser → Flare domain    : Flare sets `__flare_csrf_<appId>` as HttpOnly
+ *                                on the Flare domain. Browser also reads the
+ *                                token from the `x-flare-csrf` header and keeps
+ *                                it in-memory for direct API calls.
+ *
+ * 2. Browser → Next.js domain  : Mount `createCsrfProxy()` at a route such as
+ *                                `/api/flare/csrf`. On first browser load call
+ *                                this route; it hits Flare's /auth/config,
+ *                                reads the `x-flare-csrf` header, and sets
+ *                                it as an HttpOnly cookie on the *Next.js*
+ *                                domain too (`__flare_csrf_<appId>`).
+ *                                All subsequent SSR fetch calls from the
+ *                                Next.js server can then read this cookie from
+ *                                the incoming request and forward it as the
+ *                                `x-flare-csrf` header to Flare.
+ *
+ * Usage (Next.js App Router)
+ * ─────────────────────────────
+ * // app/api/flare/csrf/route.ts
+ * import { createCsrfProxy } from "@zuzjs/flare-client/proxy";
+ * export const GET = createCsrfProxy({ endpoint: "https://api.flare.example.com", appId: "my-app" });
+ *
+ * // In any Server Component / Route Handler:
+ * import { extractCsrfFromRequest, buildFlareHeaders } from "@zuzjs/flare-client/proxy";
+ * const csrf = extractCsrfFromRequest(request, "my-app");
+ * const res = await withGet(`${FLARE}/auth/whatever`, { headers: buildFlareHeaders(csrf), ignoreKind: true });
+ *
+ * Usage (Next.js Pages Router)
+ * ──────────────────────────────
+ * // pages/api/flare/csrf.ts
+ * import { createCsrfProxyHandler } from "@zuzjs/flare-client/proxy";
+ * export default createCsrfProxyHandler({ endpoint: "...", appId: "my-app" });
+ */
+interface CsrfProxyConfig {
+    /** Base URL of the Flare server, e.g. "https://api.flare.example.com" */
+    endpoint: string;
+    /** App ID passed to Flare's /auth/config */
+    appId: string;
+    /** Optional Flare API key */
+    apiKey?: string;
     /**
-     * Internal: Send message to server
+     * Name of the proxy cookie written on the Next.js domain.
+    * Defaults to `__flare_csrf_<appId>`.
      */
-    send(type: FlareAction, payload: any): Promise<any>;
+    proxyCookieName?: string;
     /**
-     * Internal: Create a subscription
+     * Max-Age for the proxy cookie in seconds.
+     * Defaults to 3600 (1 hour).
      */
-    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | undefined, callback: SubscriptionCallback): () => void;
-    private log;
+    proxyCookieMaxAge?: number;
 }
+/**
+ * Creates a Next.js App Router `GET` handler that:
+ *  1. Calls Flare's /auth/config and captures the `x-flare-csrf` header.
+ *  2. Sets it as `__flare_csrf_<appId>` HttpOnly cookie on the current domain.
+ *  3. Returns the token in JSON for the browser to store in-memory as well.
+ *
+ * Mount at: `app/api/flare/csrf/route.ts`
+ */
+declare function createCsrfProxy(config: CsrfProxyConfig): (_request: Request) => Promise<Response>;
+/**
+ * Creates a Next.js Pages Router API handler (`pages/api/flare/csrf.ts`).
+ * Same behaviour as `createCsrfProxy()` but uses the Node.js req/res API.
+ */
+declare function createCsrfProxyHandler(config: CsrfProxyConfig): (req: any, res: any) => Promise<void>;
+/**
+ * Extract the proxied CSRF token from an incoming Next.js request's cookies.
+ *
+ * Call this inside Server Components, Route Handlers, or `getServerSideProps`
+ * to retrieve the token that was set by `createCsrfProxy`.
+ *
+ * @example
+ * // App Router Route Handler
+ * const csrf = extractCsrfFromRequest(request, "my-app");
+ */
+declare function extractCsrfFromRequest(request: Request | {
+    cookies: Record<string, string> | {
+        get(name: string): {
+            value: string;
+        } | undefined;
+    };
+}, appId: string, proxyCookieName?: string): string | null;
+/**
+ * Build the headers object to attach to a server-side fetch call to Flare,
+ * forwarding the CSRF token and (optionally) the Authorization bearer token.
+ */
+declare function buildFlareHeaders(csrfToken: string | null, options?: {
+    accessToken?: string;
+    apiKey?: string;
+}): Record<string, string>;
 
 declare class FlareError extends Error {
     readonly code: string;
@@ -362,6 +1180,65 @@ declare class FlareError extends Error {
     constructor(message: string, code: string, cause?: unknown | undefined);
 }
 
+declare enum FlareErrors {
+    authEmailNotVerified = "auth/email-not-verified",
+    authEmailAlreadyVerified = "auth/email-already-verified",
+    authInvalidToken = "auth/invalid-token",
+    authUserDisabled = "auth/user-disabled",
+    authUserNotFound = "auth/user-not-found",
+    authWrongPassword = "auth/wrong-password",
+    authEmailAlreadyInUse = "auth/email-already-in-use",
+    authInvalidEmail = "auth/invalid-email",
+    authWeakPassword = "auth/weak-password",
+    authTooManyRequests = "auth/too-many-requests",
+    authInternalError = "auth/internal-error"
+}
+
+declare enum FlareResponseCodes {
+    health = "health",
+    authConfig = "auth_config",
+    authRegistration = "auth/registration",
+    authRegistrationVerificationRequired = "auth/registration-verification-required",
+    authSession = "auth/session",
+    authExchange = "auth/exchange",
+    authLogout = "auth/logout",
+    authSsrBridge = "auth/ssr_bridge",
+    authSsrVerify = "auth/ssr_verify",
+    accountRecovery = "account/recovery",
+    emailVerification = "email/verification",
+    verificationDispatch = "verification/dispatch",
+    authProfile = "auth/profile",
+    adminToken = "admin/token",
+    documentDelete = "document/delete",
+    documentsDelete = "documents/delete",
+    documents = "documents",
+    document = "document",
+    documentCreate = "document/create",
+    documentUpdate = "document/update",
+    oauthProviderResponse = "oauth_provider_response",
+    success = "success",
+    response = "response"
+}
+interface AuthConfigResponse {
+    kind: string;
+    appId: string;
+    enabled: boolean;
+    csrfToken?: string;
+    cookie: {
+        accessTokenName: string;
+        refreshTokenName: string;
+        csrfTokenName: string;
+        path: string;
+        secure: boolean;
+        sameSite: 'Strict' | 'Lax' | 'None';
+        accessTokenMaxAge: number;
+        refreshTokenMaxAge: number;
+        csrfTokenMaxAge: number;
+    };
+    providers: Record<string, any>;
+    ssr: Record<string, any>;
+}
+
 /**
  * Initialize and connect to FlareServer
  * Returns a singleton instance
@@ -376,4 +1253,4 @@ declare const getFlare: () => FlareClient | null;
  */
 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 };
+export { type AggregateFunction, type AggregateSpec, type AnyFilter, type AuthConfigListener, type AuthConfigResponse, type AuthResult, type AuthStateListener, type AuthWithPendingVerificationResult, type AuthWithTokenResult, type BaseMessage, type ChangeEvent, type ChangeOperation, type CollectionPresetMethods, type CollectionQuery, CollectionReference, type ConnectionState, type CsrfProxyConfig, type CursorValue, type DocAddedCallback, type DocChangedCallback, type DocDeletedCallback, type DocUpdatedCallback, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, FlareAction, type FlareAuthConfig, type FlareAuthProviderId, type FlareAuthProviderPublicConfig, type FlareAuthSession, type FlareAuthUser, type FlareConfig, FlareError, FlareErrors, FlareEvent, FlareResponseCodes, type FlareRule, type GroupByClause, type HavingClause, type JoinClause, type JoinQueryPattern, type NestedJoinClause, type OfflineOperation, type OrFilter, type OrderByClause, type PresenceCallback, type PresenceJoinCallback, type PresenceLeaveCallback, type PresenceMember, type QueryConfig, type QueryOperator, type QueryPresetMap, type QueryPresetParams, type QueryPresetRow, type QueryPresetSpec, type QuerySnapshot, type RulePermission, type SecurityRuleEntry, type SecurityRulesMap, type SnapshotEvent, type StructuredJoinClause, type StructuredQuery, type SubscribeMessage, type SubscribeOptions, type SubscriptionCallback, type SubscriptionData, type SubscriptionError, type SubscriptionErrorCallback, type SubscriptionHandle, type VectorFieldConfig, type VectorSearchClause, type WhereCondition, buildFlareHeaders, connectApp, createCsrfProxy, createCsrfProxyHandler, FlareClient as default, disconnectFlare, extractCsrfFromRequest, flareRulesToSecurityMap, getFlare, parseValue, parseWhereCondition, securityMapToFlareRules };