@ragable/sdk 0.5.1 → 0.6.1

package/dist/index.d.ts

@@ -66,6 +66,10 @@ type TableRow<D extends RagableDatabase, T extends RagableTableNames<D>> = [keyo
 type TableInsertRow<D extends RagableDatabase, T extends RagableTableNames<D>> = [keyof D["public"]["Tables"]] extends [never] ? Record<string, unknown> : T extends keyof D["public"]["Tables"] ? TablesInsert<D, T> : Record<string, unknown>;
 /** Update patch for typed `from(table).update(...)`. */
 type TableUpdatePatch<D extends RagableDatabase, T extends RagableTableNames<D>> = [keyof D["public"]["Tables"]] extends [never] ? Record<string, unknown> : T extends keyof D["public"]["Tables"] ? TablesUpdate<D, T> : Record<string, unknown>;
+/** Column name union for a given table (keys of `Row`). Falls back to `string` when untyped. */
+type ColumnName<D extends RagableDatabase, T extends RagableTableNames<D>> = [keyof D["public"]["Tables"]] extends [never] ? string : T extends keyof D["public"]["Tables"] ? Extract<keyof TableRow<D, T>, string> : string;
+/** Value type for a specific column. Falls back to `unknown` when untyped. */
+type ColumnValue<D extends RagableDatabase, T extends RagableTableNames<D>, C extends ColumnName<D, T>> = [keyof D["public"]["Tables"]] extends [never] ? unknown : T extends keyof D["public"]["Tables"] ? C extends keyof TableRow<D, T> ? TableRow<D, T>[C] : unknown : unknown;
 
 /**
  * Native `fetch` must not be called as a detached reference (`const f = fetch; f(url)`),
@@ -83,10 +87,35 @@ interface RagableClientOptions {
 type RequestOptions = Omit<RequestInit, "body"> & {
     body?: unknown;
 };
-declare class RagableError extends Error {
+declare abstract class RagableSdkError extends Error {
+    abstract readonly __type: string;
+    constructor(message: string);
+    toJSON(): Record<string, unknown>;
+}
+declare class RagableError extends RagableSdkError {
+    readonly __type: "RagableError";
     readonly status: number;
     readonly body: unknown;
+    readonly code: string | undefined;
+    readonly details: string | undefined;
     constructor(message: string, status: number, body: unknown);
+    toJSON(): Record<string, unknown>;
+}
+declare class RagableNetworkError extends RagableSdkError {
+    readonly __type: "RagableNetworkError";
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+declare class RagableAbortError extends RagableSdkError {
+    readonly __type: "RagableAbortError";
+    constructor(message?: string);
+}
+declare class RagableTimeoutError extends RagableSdkError {
+    readonly __type: "RagableTimeoutError";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+    toJSON(): Record<string, unknown>;
 }
 declare function extractErrorMessage(payload: unknown, fallback: string): string;
 declare class RagableRequestClient {
@@ -242,7 +271,7 @@ declare class AgentsClient {
     chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
 
-/** Shared with {@link RagableBrowserDatabaseClient.query} — duplicated to avoid circular imports. */
+/** @deprecated Kept for backward compat with `database.query()`. Not used by PostgREST path. */
 interface BrowserSqlExecParams {
     databaseInstanceId: string;
     sql: string;
@@ -251,18 +280,26 @@ interface BrowserSqlExecParams {
     timeoutMs?: number;
     rowLimit?: number;
 }
+/** @deprecated Kept for backward compat with `database.query()`. Not used by PostgREST path. */
 interface BrowserSqlExecResult<Row extends Record<string, unknown> = Record<string, unknown>> {
     command: string;
     rowCount: number;
     truncated: boolean;
     rows: Row[];
 }
-type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike";
-interface Filter {
-    op: FilterOp;
-    column: string;
-    value: unknown;
+/** @deprecated Use PostgRESTFetch instead. Kept for `database.query()` backward compat. */
+type RunQuery = <R extends Record<string, unknown> = Record<string, unknown>>(p: BrowserSqlExecParams) => Promise<BrowserSqlExecResult<R>>;
+interface PostgRESTFetchParams {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    table: string;
+    searchParams: URLSearchParams;
+    body?: unknown;
+    headers?: Record<string, string>;
+    databaseInstanceId: string;
+    signal?: AbortSignal;
+    idempotencyKey?: string;
 }
+type PostgRESTFetch = (params: PostgRESTFetchParams) => Promise<Response>;
 type PostgrestResult<T> = {
     data: T;
     error: null;
@@ -270,161 +307,167 @@ type PostgrestResult<T> = {
     data: null;
     error: RagableError;
 };
-/** Map async throws to `{ data, error }` like Supabase JS client. */
 declare function asPostgrestResponse<T>(fn: () => Promise<T>): Promise<PostgrestResult<T>>;
-type RunQuery = <R extends Record<string, unknown> = Record<string, unknown>>(p: BrowserSqlExecParams) => Promise<BrowserSqlExecResult<R>>;
-/** Supabase/PostgREST-style read builder: `.from('t').select().eq().single()` */
-declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
-    private readonly run;
+type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "is" | "in";
+interface Filter {
+    op: FilterOp;
+    column: string;
+    value: unknown;
+}
+declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Record<string, unknown>, D extends RagableDatabase = DefaultRagableDatabase, T extends RagableTableNames<D> = RagableTableNames<D>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly columns;
-    private filters;
+    filters: Filter[];
     private _limit?;
+    private _offset?;
     private _order?;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, columns: string);
-    eq(column: string, value: unknown): this;
-    neq(column: string, value: unknown): this;
-    gt(column: string, value: unknown): this;
-    gte(column: string, value: unknown): this;
-    lt(column: string, value: unknown): this;
-    lte(column: string, value: unknown): this;
-    like(column: string, value: unknown): this;
-    ilike(column: string, value: unknown): this;
+    private _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, columns: string);
+    eq<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    neq<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    gt<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    gte<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    lt<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    lte<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    like<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    ilike<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    is<C extends ColumnName<D, T>>(column: C, value: null | boolean): this;
+    in<C extends ColumnName<D, T>>(column: C, values: ColumnValue<D, T, C>[]): this;
+    match(query: Partial<TableRow<D, T>>): this;
     limit(n: number): this;
-    order(column: string, options?: {
+    offset(n: number): this;
+    range(from: number, to: number): this;
+    order(column: ColumnName<D, T>, options?: {
         ascending?: boolean;
+        nullsFirst?: boolean;
     }): this;
-    private buildSelectCore;
+    abortSignal(signal: AbortSignal): this;
+    private buildSearchParams;
     then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeMany;
     single(): Promise<PostgrestResult<Row>>;
     maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-/** After `.insert()`: await without `.select()` → `{ data: null }` (Supabase default). */
 declare class PostgrestInsertRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<null>> {
-    private readonly run;
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly rows;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
-    /**
-     * Return inserted rows (Supabase: chain `.select()` to get data).
-     * @see https://supabase.com/docs/reference/javascript/insert
-     */
+    private _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
     select(columns?: string): PostgrestInsertReturningBuilder<Row>;
+    abortSignal(signal: AbortSignal): this;
     then<TResult1 = PostgrestResult<null>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<null>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeNoReturn;
 }
 declare class PostgrestInsertReturningBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
-    private readonly run;
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly rows;
     private readonly returning;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[], returning: string);
+    private readonly _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, rows: Record<string, unknown>[], returning: string, _signal?: AbortSignal | undefined);
     then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeMany;
     single(): Promise<PostgrestResult<Row>>;
     maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-/** Update without `.select()` → `{ data: null }` on success. */
-declare class PostgrestUpdateRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<null>> {
-    private readonly run;
+declare class PostgrestUpdateRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>, D extends RagableDatabase = DefaultRagableDatabase, T extends RagableTableNames<D> = RagableTableNames<D>> implements PromiseLike<PostgrestResult<null>> {
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly patch;
-    private filters;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>);
-    eq(column: string, value: unknown): this;
-    neq(column: string, value: unknown): this;
-    gt(column: string, value: unknown): this;
-    gte(column: string, value: unknown): this;
-    lt(column: string, value: unknown): this;
-    lte(column: string, value: unknown): this;
-    like(column: string, value: unknown): this;
-    ilike(column: string, value: unknown): this;
-    /**
-     * Return updated rows (Supabase: `.update().eq().select()`).
-     * @see https://supabase.com/docs/reference/javascript/update
-     */
+    filters: Filter[];
+    private _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, patch: Record<string, unknown>);
+    eq<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    neq<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    gt<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    gte<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    lt<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    lte<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    like<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    ilike<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    is<C extends ColumnName<D, T>>(column: C, value: null | boolean): this;
+    in<C extends ColumnName<D, T>>(column: C, values: ColumnValue<D, T, C>[]): this;
+    match(query: Partial<TableRow<D, T>>): this;
     select(columns?: string): PostgrestUpdateReturningBuilder<Row>;
+    abortSignal(signal: AbortSignal): this;
     then<TResult1 = PostgrestResult<null>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<null>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private buildSearchParams;
     private executeNoReturn;
 }
 declare class PostgrestUpdateReturningBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
-    private readonly run;
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly patch;
     private readonly filters;
     private readonly returning;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>, filters: Filter[], returning: string);
+    private readonly _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, patch: Record<string, unknown>, filters: Filter[], returning: string, _signal?: AbortSignal | undefined);
     then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeMany;
     single(): Promise<PostgrestResult<Row>>;
     maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-/** Delete without `.select()` → `{ data: null }`. */
-declare class PostgrestDeleteRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<null>> {
-    private readonly run;
+declare class PostgrestDeleteRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>, D extends RagableDatabase = DefaultRagableDatabase, T extends RagableTableNames<D> = RagableTableNames<D>> implements PromiseLike<PostgrestResult<null>> {
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
-    private filters;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string);
-    eq(column: string, value: unknown): this;
-    neq(column: string, value: unknown): this;
-    gt(column: string, value: unknown): this;
-    gte(column: string, value: unknown): this;
-    lt(column: string, value: unknown): this;
-    lte(column: string, value: unknown): this;
-    like(column: string, value: unknown): this;
-    ilike(column: string, value: unknown): this;
-    /**
-     * Return deleted rows (Supabase: `.delete().eq().select()`).
-     * @see https://supabase.com/docs/reference/javascript/delete
-     */
+    filters: Filter[];
+    private _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string);
+    eq<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    neq<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    gt<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    gte<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    lt<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    lte<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    like<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    ilike<C extends ColumnName<D, T>>(column: C, value: ColumnValue<D, T, C>): this;
+    is<C extends ColumnName<D, T>>(column: C, value: null | boolean): this;
+    in<C extends ColumnName<D, T>>(column: C, values: ColumnValue<D, T, C>[]): this;
+    match(query: Partial<TableRow<D, T>>): this;
     select(columns?: string): PostgrestDeleteReturningBuilder<Row>;
+    abortSignal(signal: AbortSignal): this;
     then<TResult1 = PostgrestResult<null>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<null>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeNoReturn;
 }
 declare class PostgrestDeleteReturningBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
-    private readonly run;
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly filters;
     private readonly returning;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, filters: Filter[], returning: string);
+    private readonly _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, filters: Filter[], returning: string, _signal?: AbortSignal | undefined);
     then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeMany;
     single(): Promise<PostgrestResult<Row>>;
     maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
 interface PostgrestUpsertOptions {
-    /** Column(s) for `ON CONFLICT` — single name or comma-separated, e.g. `"id"` or `"org_id,user_id"`. */
     onConflict: string;
-    /** When true, `ON CONFLICT DO NOTHING` (no update of existing rows). */
     ignoreDuplicates?: boolean;
 }
-/** Upsert without `.select()` → `{ data: null }`. */
 declare class PostgrestUpsertRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<null>> {
-    private readonly run;
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
     private readonly rows;
+    private readonly onConflict;
     private readonly ignoreDuplicates;
-    private readonly conflictCols;
-    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[], onConflict: string, ignoreDuplicates: boolean);
-    /**
-     * Return upserted rows (Supabase: `.upsert().select()`).
-     * @see https://supabase.com/docs/reference/javascript/upsert
-     */
+    private _signal?;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: string, rows: Record<string, unknown>[], onConflict: string, ignoreDuplicates: boolean);
     select(columns?: string): PostgrestUpsertReturningBuilder<Row>;
+    abortSignal(signal: AbortSignal): this;
     then<TResult1 = PostgrestResult<null>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<null>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
     private executeNoReturn;
-    private runUpsert;
-    /** Used by returning builder */
-    runWithReturning(returning: string): Promise<BrowserSqlExecResult<Row>>;
+    runUpsert(prefer: string, selectCols: string | null): Promise<Row[]>;
 }
 declare class PostgrestUpsertReturningBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
     private readonly root;
@@ -436,67 +479,282 @@ declare class PostgrestUpsertReturningBuilder<Row extends Record<string, unknown
     maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
 declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagableDatabase, TableName extends RagableTableNames<Database> = RagableTableNames<Database>> {
-    private readonly run;
+    private readonly pgFetch;
     private readonly databaseInstanceId;
     private readonly table;
-    constructor(run: RunQuery, databaseInstanceId: string, table: TableName extends string ? string : string);
-    select(columns?: string): PostgrestSelectBuilder<TableRow<Database, TableName>>;
+    constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: TableName extends string ? string : string);
+    select(columns?: string): PostgrestSelectBuilder<TableRow<Database, TableName>, Database, TableName>;
     insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
-    update(patch: TableUpdatePatch<Database, TableName>): PostgrestUpdateRootBuilder<TableRow<Database, TableName>>;
-    delete(): PostgrestDeleteRootBuilder<TableRow<Database, TableName>>;
-    /**
-     * `INSERT ... ON CONFLICT ... DO UPDATE` (or `DO NOTHING` with `ignoreDuplicates`).
-     * @see https://supabase.com/docs/reference/javascript/upsert
-     */
+    update(patch: TableUpdatePatch<Database, TableName>): PostgrestUpdateRootBuilder<TableRow<Database, TableName>, Database, TableName>;
+    delete(): PostgrestDeleteRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     upsert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], options: PostgrestUpsertOptions): PostgrestUpsertRootBuilder<TableRow<Database, TableName>>;
 }
 
-/**
- * Ensures the browser SDK hits `/api/...` routes. Accepts either `https://host` or `https://host/api`
- * (same rule as two-arg `createClient(url, opts)` from the package entry).
- */
+interface SessionStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+declare class LocalStorageAdapter implements SessionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare class SessionStorageAdapter implements SessionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare class MemoryStorageAdapter implements SessionStorage {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare class CookieStorageAdapter implements SessionStorage {
+    private readonly maxAge;
+    private readonly path;
+    private readonly sameSite;
+    constructor(maxAge?: number, path?: string, sameSite?: "Lax" | "Strict" | "None");
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare function detectStorage(): SessionStorage;
+type AuthBroadcastMessage = {
+    type: "SESSION_UPDATED";
+    payload: string;
+} | {
+    type: "SESSION_REMOVED";
+};
+declare class AuthBroadcastChannel {
+    private channel;
+    constructor(channelName: string);
+    onMessage(cb: (msg: AuthBroadcastMessage) => void): void;
+    postSessionUpdated(serialized: string): void;
+    postSessionRemoved(): void;
+    close(): void;
+}
+
+type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "USER_UPDATED";
+interface AuthSession<U extends Record<string, unknown> = Record<string, unknown>> {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    expires_at: number;
+    token_type: "bearer";
+    user: U;
+}
+interface AuthOptions {
+    persistSession?: boolean;
+    autoRefreshToken?: boolean;
+    storage?: SessionStorage;
+    storageKey?: string;
+    refreshSkewSeconds?: number;
+    debug?: boolean;
+}
+interface RagableAuthConfig {
+    baseUrl: string;
+    authGroupId: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+    auth?: AuthOptions;
+}
+type AuthListener<U extends Record<string, unknown>> = (event: AuthChangeEvent, session: AuthSession<U> | null) => void;
+interface Subscription {
+    id: string;
+    unsubscribe: () => void;
+}
+declare class RagableAuth<U extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    private readonly authGroupId;
+    private readonly defaultHeaders;
+    private readonly persistSession;
+    private readonly autoRefreshToken;
+    private readonly storage;
+    private readonly storageKey;
+    private readonly refreshSkewSeconds;
+    private readonly debug;
+    private currentSession;
+    private refreshTimer;
+    private refreshPromise;
+    private listeners;
+    private broadcast;
+    private visibilityHandler;
+    private initialized;
+    constructor(config: RagableAuthConfig);
+    private log;
+    initialize(): Promise<AuthSession<U> | null>;
+    signUp(credentials: {
+        email: string;
+        password: string;
+        options?: {
+            data?: Record<string, unknown>;
+        };
+    }): Promise<PostgrestResult<{
+        user: U;
+        session: AuthSession<U>;
+    }>>;
+    signInWithPassword(credentials: {
+        email: string;
+        password: string;
+    }): Promise<PostgrestResult<{
+        user: U;
+        session: AuthSession<U>;
+    }>>;
+    signOut(_options?: {
+        scope?: "global" | "local";
+    }): Promise<{
+        error: null;
+    }>;
+    refreshSession(refreshToken?: string): Promise<PostgrestResult<{
+        session: AuthSession<U>;
+        user: U;
+    }>>;
+    getSession(): Promise<PostgrestResult<{
+        session: AuthSession<U> | null;
+    }>>;
+    getUser(): Promise<PostgrestResult<{
+        user: U;
+    }>>;
+    setSession(tokens: {
+        access_token: string;
+        refresh_token: string;
+    }): Promise<PostgrestResult<{
+        session: AuthSession<U>;
+        user: U;
+    }>>;
+    updateUser(attributes: {
+        email?: string;
+        password?: string;
+        data?: {
+            name?: string | null;
+        };
+    }): Promise<PostgrestResult<{
+        user: U;
+    }>>;
+    onAuthStateChange(callback: AuthListener<U>): {
+        data: {
+            subscription: Subscription;
+        };
+    };
+    getAccessToken(): string | null;
+    getCurrentSession(): AuthSession<U> | null;
+    register(body: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<{
+        user: U;
+        accessToken: string;
+        refreshToken: string;
+        expiresIn: string;
+    }>;
+    login(body: {
+        email: string;
+        password: string;
+    }): Promise<{
+        user: U;
+        accessToken: string;
+        refreshToken: string;
+        expiresIn: string;
+    }>;
+    refresh(body: {
+        refreshToken: string;
+    }): Promise<{
+        accessToken: string;
+        refreshToken: string;
+        expiresIn: string;
+    }>;
+    getMe(): Promise<{
+        user: U;
+    }>;
+    updateMe(body: {
+        name?: string | null;
+        password?: string;
+    }): Promise<{
+        user: U;
+    }>;
+    destroy(): void;
+    private authPrefix;
+    private toUrl;
+    private baseHeaders;
+    private fetchAuth;
+    private fetchAuthWithBearer;
+    private rawToSession;
+    private setSessionInternal;
+    private persistCurrentSession;
+    private emit;
+    private scheduleRefresh;
+    private clearRefreshTimer;
+    singleFlightRefresh(refreshToken: string): Promise<AuthSession<U> | null>;
+    private _doRefresh;
+    private setupVisibilityListener;
+}
+
+type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD";
+interface RetryOptions {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryOn: number[];
+    respectRetryAfter: boolean;
+}
+interface TransportOptions {
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+    retry?: Partial<RetryOptions>;
+    timeoutMs?: number;
+    onRequest?: (req: TransportRequest) => void;
+    onResponse?: (req: TransportRequest, res: Response, durationMs: number) => void;
+    onRetry?: (req: TransportRequest, attempt: number, delayMs: number, reason: string) => void;
+}
+interface TransportRequest {
+    url: string;
+    method: HttpMethod;
+    headers: Headers;
+    body?: BodyInit;
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+    retry?: Partial<RetryOptions>;
+    timeoutMs?: number;
+}
+declare function generateIdempotencyKey(): string;
+declare class Transport {
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly defaultRetry;
+    private readonly defaultTimeoutMs;
+    private readonly onRequest?;
+    private readonly onResponse?;
+    private readonly onRetry?;
+    private readonly inflightGets;
+    private _refreshHandler;
+    constructor(options?: TransportOptions);
+    setRefreshHandler(handler: (() => Promise<string | null>) | null): void;
+    execute(req: TransportRequest): Promise<Response>;
+    private _executeWithRetry;
+    private _singleFetch;
+}
+declare function parseTransportResponse<T>(response: Response): Promise<T>;
+
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
-/** How {@link RagableBrowserDatabaseClient.query} and `.from()` send `Authorization`. */
 type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
 interface RagableBrowserClientOptions {
-    /** Organization id (UUID) — public agent chat URLs. */
     organizationId: string;
-    /**
-     * Authentication group id when using {@link RagableBrowserAuthClient} or
-     * {@link RagableBrowserDatabaseClient}.
-     */
     authGroupId?: string;
-    /**
-     * Default Backspace SQL instance id for {@link RagableBrowser.from} (Supabase-style table API).
-     */
     databaseInstanceId?: string;
-    /**
-     * Database SQL auth. Default `user`: Bearer = JWT from {@link getAccessToken}.
-     * `publicAnon`: Bearer = public anon key (read-only SQL only). `admin`: Bearer = data admin key
-     * (same SQL rules as a logged-in user; **never** expose in browser bundles).
-     */
     dataAuth?: BrowserDataAuthMode;
-    /**
-     * Static key when {@link dataAuth} is `publicAnon` or `admin` (e.g. `import.meta.env.VITE_…`).
-     * Ignored when {@link getDataStaticKey} returns a non-empty string.
-     */
     dataStaticKey?: string;
-    /** Load anon/admin key at runtime; wins over {@link dataStaticKey} when non-empty. */
     getDataStaticKey?: () => string | null | Promise<string | null>;
-    /**
-     * Returns the end-user access JWT (from login/register/refresh).
-     * Required for `auth.getMe`, `auth.updateMe`, and for `database.query` when {@link dataAuth} is `user` (default).
-     */
     getAccessToken?: () => string | null | Promise<string | null>;
-    /**
-     * API base URL including `/api`, e.g. `https://api.example.com/api`.
-     * @default `https://ragable-341305259977.asia-southeast1.run.app/api` ({@link DEFAULT_RAGABLE_API_BASE})
-     */
     baseUrl?: string;
     fetch?: typeof fetch;
     headers?: HeadersInit;
+    auth?: AuthOptions;
+    transport?: Partial<TransportOptions>;
 }
-/** Successful register/login response (typed `user` via `AuthUser` generic). */
 interface BrowserAuthSession<AuthUser extends Record<string, unknown> = Record<string, unknown>> {
     user: AuthUser;
     accessToken: string;
@@ -508,25 +766,18 @@ interface BrowserAuthTokens {
     refreshToken: string;
     expiresIn: string;
 }
-/** Supabase-compatible session shape (snake_case tokens). */
 interface SupabaseCompatSession<AuthUser extends Record<string, unknown> = Record<string, unknown>> {
     access_token: string;
     refresh_token: string;
-    /** Best-effort seconds from Ragable `expiresIn` (e.g. `7d`, `3600`). */
     expires_in: number;
     token_type: "bearer";
     user: AuthUser;
 }
 
-/** End-user auth — Ragable names + Supabase/Firebase-style aliases returning `{ data, error }`. */
 declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown> = Record<string, unknown>> {
-    private readonly options;
-    private readonly fetchImpl;
-    constructor(options: RagableBrowserClientOptions);
-    private toUrl;
-    private baseHeaders;
-    private authPrefix;
-    /** Supabase: `signUp` → `{ data: { user, session }, error }` */
+    private readonly ragableAuth;
+    constructor(_options: RagableBrowserClientOptions, ragableAuth?: RagableAuth<AuthUser> | null);
+    private get auth();
     signUp(credentials: {
         email: string;
         password: string;
@@ -537,7 +788,6 @@ declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown>
         user: AuthUser;
         session: SupabaseCompatSession<AuthUser>;
     }>>;
-    /** Supabase: `signInWithPassword` */
     signInWithPassword(credentials: {
         email: string;
         password: string;
@@ -545,16 +795,13 @@ declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown>
         user: AuthUser;
         session: SupabaseCompatSession<AuthUser>;
     }>>;
-    /** Supabase: `refreshSession` */
     refreshSession(refreshToken: string): Promise<PostgrestResult<{
         session: SupabaseCompatSession<AuthUser>;
         user: AuthUser;
     }>>;
-    /** Supabase: `getUser()` — needs `getAccessToken` on the client */
     getUser(): Promise<PostgrestResult<{
         user: AuthUser;
     }>>;
-    /** Supabase: `updateUser` */
     updateUser(attributes: {
         email?: string;
         password?: string;
@@ -564,16 +811,11 @@ declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown>
     }): Promise<PostgrestResult<{
         user: AuthUser;
     }>>;
-    /**
-     * Supabase/Firebase: no server call — clear tokens in your app.
-     * Returns `{ error: null }` for API compatibility.
-     */
     signOut(_options?: {
         scope?: "global" | "local";
     }): Promise<{
         error: null;
     }>;
-    private getUserFromToken;
     register(body: {
         email: string;
         password: string;
@@ -595,19 +837,22 @@ declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown>
     }): Promise<{
         user: AuthUser;
     }>;
+    onAuthStateChange(callback: (event: AuthChangeEvent, session: AuthSession<AuthUser> | null) => void): {
+        data: {
+            subscription: {
+                id: string;
+                unsubscribe: () => void;
+            };
+        };
+    };
+    getSession(): Promise<PostgrestResult<{
+        session: AuthSession<AuthUser> | null;
+    }>>;
 }
 interface BrowserSqlQueryParams {
-    /**
-     * Defaults to `databaseInstanceId` on {@link RagableBrowserClientOptions} when set
-     * (so you can configure it once on `createBrowserClient`).
-     */
     databaseInstanceId?: string;
     sql: string;
     params?: unknown[];
-    /**
-     * Default `true`. When `false`, the API allows INSERT/UPDATE/DELETE (and existing safe reads);
-     * DDL (`CREATE`/`DROP`/`ALTER`/…) and privilege changes remain blocked.
-     */
     readOnly?: boolean;
     timeoutMs?: number;
     rowLimit?: number;
@@ -618,59 +863,38 @@ interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<str
     truncated: boolean;
     rows: Row[];
 }
-/**
- * Raw SQL against linked Postgres (escape hatch). Prefer {@link RagableBrowser.from} for
- * Supabase-style `.select()` / `.insert()` / `.update()` / `.delete()`.
- */
 declare class RagableBrowserDatabaseClient<_Schema extends RagableDatabase = DefaultRagableDatabase> {
     private readonly options;
+    private readonly ragableAuth;
     private readonly fetchImpl;
-    constructor(options: RagableBrowserClientOptions);
+    constructor(options: RagableBrowserClientOptions, ragableAuth?: RagableAuth | null);
     private toUrl;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams): Promise<BrowserSqlQueryResult<Row>>;
     private baseHeaders;
 }
-/**
- * Browser-safe client: **no org API key**. Uses public routes and end-user JWTs
- * from {@link RagableBrowserAuthClient}.
- */
 declare class RagableBrowserAgentsClient {
     private readonly options;
     private readonly fetchImpl;
     constructor(options: RagableBrowserClientOptions);
     private toUrl;
-    /**
-     * Stream agent execution as SSE (`POST /public/organizations/:orgId/agents/:agentId/chat/stream`).
-     */
     chatStream(agentId: string, params: AgentPublicChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
-/** Public chat params — same shape as {@link AgentChatParams} plus optional trigger fields. */
 interface AgentPublicChatParams extends AgentChatParams {
     triggerSubtype?: string;
     triggerNodeId?: string;
 }
-/**
- * Browser client: mirrors **Supabase JS** (`createClient`, `.from()`, `.auth.signInWithPassword`, `{ data, error }`)
- * plus Ragable **`agents.chatStream`**. Server secrets: {@link createRagableServerClient} / {@link createClient} with `apiKey`.
- */
 declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>> {
     readonly agents: RagableBrowserAgentsClient;
     readonly auth: RagableBrowserAuthClient<AuthUser>;
     readonly database: RagableBrowserDatabaseClient<Database>;
+    readonly transport: Transport;
     private readonly options;
+    private readonly _ragableAuth;
     constructor(options: RagableBrowserClientOptions);
-    /**
-     * Supabase-style table API: `.from('items').select().eq('id', 1).single()`.
-     * Pass `databaseInstanceId` here or set `databaseInstanceId` on the client options.
-     */
     from<TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string): PostgrestTableApi<Database, TableName>;
+    destroy(): void;
 }
-/**
- * **Supabase-equivalent** browser client factory (no org API key).
- * Same as {@link createRagableBrowserClient}.
- */
 declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
-/** Alias for {@link createBrowserClient} — matches Supabase `createClient` naming. */
 declare const createRagableBrowserClient: typeof createBrowserClient;
 
 /**
@@ -744,20 +968,9 @@ declare class Ragable {
     };
     constructor(options: RagableClientOptions);
 }
-/**
- * **Supabase-style overloads**
- * - `createClient(RAGABLE_URL, { organizationId, authGroupId, … })` — browser (no API key)
- * - `createClient({ apiKey, baseUrl })` — server / Engine (secret key)
- *
- * Prefer {@link createRagableServerClient} in backend code if the dual overload is confusing.
- */
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(url: string, options: Omit<RagableBrowserClientOptions, "baseUrl">): RagableBrowser<Database, AuthUser>;
 declare function createClient(options: RagableClientOptions): Ragable;
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
-/**
- * Explicit **server** factory — same as `createClient({ apiKey, baseUrl })`.
- * Use in the Engine; never import alongside browser `createClient(url, …)` if you want tree-shaking clarity.
- */
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type Json, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RagableTableNames, type RequestOptions, type RetrieveParams, type RunQuery, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, extractErrorMessage, formatRetrievalContext, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };