@zuzjs/flare 0.2.1 → 0.2.2

package/dist/index.d.cts

@@ -1,80 +1,174 @@
-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;
+}
+type AuthStateListener = (session: FlareAuthSession | 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";
-/**
- * Subscription callback
- */
-type SubscriptionCallback<T = any> = (data: SubscriptionData<T>) => void;
+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 {
+    from: string;
+    localField: string;
+    foreignField: string;
+    as: string;
+    single?: boolean;
+}
+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?: JoinClause[];
+    vectorSearch?: VectorSearchClause;
+    select?: string[];
+    distinctField?: string;
+}
+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;
+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 +178,54 @@ 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[]>;
+};
 
+/**
+ * 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' })
@@ -157,6 +287,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
      */
     onSnapshot(callback: SubscriptionCallback<T>): () => void;
 }
+
 /**
  * Legacy document reference (for backward compatibility)
  */
@@ -170,57 +301,88 @@ declare class DocumentReference<T = any> {
     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[]> {
     private client;
     readonly collection: string;
-    private queries;
+    private sq;
     private promise?;
     constructor(client: FlareClient, collection: string);
-    /**
-     * Get a document reference (legacy API)
-     */
     doc(id: string): DocumentReference<T>;
-    /**
-     * Add a where filter (NEW ORM-style API)
-     * @example .where({ age: ">= 25", role: "admin" })
-     */
+    private clone;
+    /** ORM shorthand: .where({ age: ">= 25", role: "admin" }) */
     where(condition: WhereCondition): CollectionReference<T>;
+    /** Explicit field/op/value */
+    where(field: string, op: QueryConfig['op'], value: unknown): CollectionReference<T>;
+    /** OR group: .orWhere([{ field:"status", op:"==", value:"active" }, ...]) */
+    orWhere(filters: QueryConfig[]): CollectionReference<T>;
+    orderBy(field: string, dir?: "asc" | "desc"): CollectionReference<T>;
+    limit(n: number): CollectionReference<T>;
+    offset(n: number): CollectionReference<T>;
+    startAt(...values: unknown[]): CollectionReference<T>;
+    startAfter(...values: unknown[]): CollectionReference<T>;
+    endAt(...values: unknown[]): CollectionReference<T>;
+    endBefore(...values: unknown[]): CollectionReference<T>;
+    aggregate(...specs: AggregateSpec[]): CollectionReference<T>;
+    count(alias?: string): CollectionReference<T>;
+    sum(field: string, alias?: string): CollectionReference<T>;
+    avg(field: string, alias?: string): CollectionReference<T>;
+    min(field: string, alias?: string): CollectionReference<T>;
+    max(field: string, alias?: string): CollectionReference<T>;
+    distinct(field: string, alias?: string): CollectionReference<T>;
+    groupBy(...fields: string[]): CollectionReference<T>;
+    having(field: string, op: HavingClause['op'], value: number): CollectionReference<T>;
+    join(j: JoinClause): CollectionReference<T>;
+    select(...fields: string[]): CollectionReference<T>;
+    /** Returns unique values for a single field */
+    distinctField(field: string): CollectionReference<T>;
     /**
-     * Get all documents once
-     * @deprecated Use await directly instead of .get()
+     * KNN nearest-neighbour search (requires Atlas vector index).
+     * @example
+     *   col.vectorSearch({ field: "embedding", vector: [...1536 numbers...], k: 10 })
      */
+    vectorSearch(opts: VectorSearchClause): CollectionReference<T>;
     get(): Promise<T[]>;
-    /**
-     * Internal execute method
-     */
+    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
+     * 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[]>): () => void;
-    /**
-     * Add a new document with auto-generated ID
-     */
+    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 +395,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 +412,586 @@ 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 ActiveSubscription = {
+    baseId: string;
+    liveId: string;
+    collection: string;
+    docId?: string;
+    query?: QueryConfig | StructuredQuery;
+    callback: SubscriptionCallback;
+    options: SubscribeOptions;
+};
+/** Embedder function registered by the user */
+type EmbedFn = (text: string) => Promise<number[]>;
+declare class FlareBase {
+    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 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 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 logHttpTiming(...args: any[]): void;
+    protected mergeHeaders(base: HeadersInit | undefined, extra: Record<string, string>): HeadersInit;
+    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): CollectionReference<T>;
+    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 activateSubscription(entry: ActiveSubscription): Promise<void>;
+    protected replayActiveSubscriptions(): Promise<void>;
+    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | StructuredQuery | undefined, callback: SubscriptionCallback, options?: SubscribeOptions): () => void;
+    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 extends FlareBase {
+    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 authSession: FlareAuthSession | null;
+    protected authStateListeners: AuthStateListener[];
+    protected authConfigListeners: AuthConfigListener[];
+    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 setAuthSession(session: FlareAuthSession | null): void;
+    onAuthStateChanged(listener: AuthStateListener): () => void;
+    onAuthStateChange(listener: AuthStateListener): () => void;
+    get currentUser(): string | undefined;
+    getCurrentUser(): string | undefined;
+    protected syncSocketAuth(accessToken?: string | null): Promise<void>;
+    protected updateSocketIdentity(uid?: string, forceReplay?: boolean): 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>;
+    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 extends FlareAuth {
+    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 +999,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 +1072,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, 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 FlareConfig, FlareError, FlareErrors, FlareEvent, FlareResponseCodes, type GroupByClause, type HavingClause, type JoinClause, type OfflineOperation, type OrFilter, type OrderByClause, type PresenceCallback, type PresenceJoinCallback, type PresenceLeaveCallback, type PresenceMember, type QueryConfig, type QueryOperator, type QuerySnapshot, type SnapshotEvent, type StructuredQuery, type SubscribeMessage, type SubscribeOptions, type SubscriptionCallback, type SubscriptionData, type VectorFieldConfig, type VectorSearchClause, type WhereCondition, buildFlareHeaders, connectApp, createCsrfProxy, createCsrfProxyHandler, FlareClient as default, disconnectFlare, extractCsrfFromRequest, getFlare, parseValue, parseWhereCondition };