@ragable/sdk 0.3.0 → 0.4.1

package/dist/index.d.mts

@@ -54,6 +54,11 @@ type TablesUpdate<D extends RagableDatabase, TableName extends keyof D["public"]
     Update: infer U;
 } ? U extends Record<string, unknown> ? U : Record<string, unknown> : Partial<Tables<D, TableName>>;
 
+/**
+ * Native `fetch` must not be called as a detached reference (`const f = fetch; f(url)`),
+ * or the browser throws **Illegal invocation**. Use this for defaults and for `options.fetch`.
+ */
+declare function bindFetch(custom?: typeof fetch): typeof fetch;
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -222,6 +227,107 @@ declare class AgentsClient {
     chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
 
+/** Shared with {@link RagableBrowserDatabaseClient.query} — duplicated to avoid circular imports. */
+interface BrowserSqlExecParams {
+    databaseInstanceId: string;
+    sql: string;
+    params?: unknown[];
+    readOnly?: boolean;
+    timeoutMs?: number;
+    rowLimit?: number;
+}
+interface BrowserSqlExecResult<Row extends Record<string, unknown> = Record<string, unknown>> {
+    command: string;
+    rowCount: number;
+    truncated: boolean;
+    rows: Row[];
+}
+type PostgrestResult<T> = {
+    data: T;
+    error: null;
+} | {
+    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;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly columns;
+    private filters;
+    private _limit?;
+    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;
+    limit(n: number): this;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): this;
+    /** @param includeUserLimit when false, omit `.limit()` (for `.single()` / `.maybeSingle()`). */
+    private buildSelectCore;
+    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>>;
+}
+declare class PostgrestInsertBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly rows;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
+    select(columns?: string): this;
+    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 execute;
+}
+declare class PostgrestUpdateBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly patch;
+    private filters;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>);
+    eq(column: string, value: unknown): this;
+    select(columns?: string): this;
+    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 execute;
+}
+declare class PostgrestDeleteBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private filters;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string);
+    eq(column: string, value: unknown): this;
+    select(columns?: string): this;
+    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 execute;
+}
+declare class PostgrestTableApi<Row extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string);
+    select(columns?: string): PostgrestSelectBuilder<Row>;
+    insert(values: Record<string, unknown> | Record<string, unknown>[]): PostgrestInsertBuilder<Row>;
+    update(patch: Record<string, unknown>): PostgrestUpdateBuilder<Row>;
+    delete(): PostgrestDeleteBuilder<Row>;
+}
+
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
 interface RagableBrowserClientOptions {
     /** Organization id (UUID) — public agent chat URLs. */
@@ -231,6 +337,10 @@ interface RagableBrowserClientOptions {
      * {@link RagableBrowserDatabaseClient}.
      */
     authGroupId?: string;
+    /**
+     * Default Backspace SQL instance id for {@link RagableBrowser.from} (Supabase-style table API).
+     */
+    databaseInstanceId?: string;
     /**
      * Returns the end-user access JWT (from login/register/refresh).
      * Required for `auth.getMe`, `auth.updateMe`, and `database.query`.
@@ -256,14 +366,72 @@ interface BrowserAuthTokens {
     refreshToken: string;
     expiresIn: string;
 }
-/** End-user auth (email/password) for a linked authentication group — no org API key. */
+/** 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 get fetchImpl();
     private toUrl;
     private baseHeaders;
     private authPrefix;
+    /** Supabase: `signUp` → `{ data: { user, session }, error }` */
+    signUp(credentials: {
+        email: string;
+        password: string;
+        options?: {
+            data?: Record<string, unknown>;
+        };
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+        session: SupabaseCompatSession<AuthUser>;
+    }>>;
+    /** Supabase: `signInWithPassword` */
+    signInWithPassword(credentials: {
+        email: string;
+        password: string;
+    }): Promise<PostgrestResult<{
+        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;
+        data?: {
+            name?: string | null;
+        };
+    }): 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;
@@ -290,8 +458,11 @@ interface BrowserSqlQueryParams {
     databaseInstanceId: string;
     sql: string;
     params?: unknown[];
-    /** Ignored — the API only allows safe read-only SQL for end users. */
-    readOnly?: true;
+    /**
+     * 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;
 }
@@ -302,16 +473,13 @@ interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<str
     rows: Row[];
 }
 /**
- * Run SQL against a Postgres instance linked to a website that uses the same `authGroupId`,
- * authenticated as the signed-in end-user (access token).
- *
- * Pass `createBrowserClient<YourDatabase>()` and use `query<Tables<YourDatabase, 't'>>()`
- * for Supabase-style row typing.
+ * 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 fetchImpl;
     constructor(options: RagableBrowserClientOptions);
-    private get fetchImpl();
     private toUrl;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams): Promise<BrowserSqlQueryResult<Row>>;
     private baseHeaders;
@@ -322,8 +490,8 @@ declare class RagableBrowserDatabaseClient<_Schema extends RagableDatabase = Def
  */
 declare class RagableBrowserAgentsClient {
     private readonly options;
+    private readonly fetchImpl;
     constructor(options: RagableBrowserClientOptions);
-    private get fetchImpl();
     private toUrl;
     /**
      * Stream agent execution as SSE (`POST /public/organizations/:orgId/agents/:agentId/chat/stream`).
@@ -336,24 +504,28 @@ interface AgentPublicChatParams extends AgentChatParams {
     triggerNodeId?: string;
 }
 /**
- * Browser client root. Use `createBrowserClient<Database, AuthUser>()` for Supabase-style
- * typing on {@link RagableBrowserDatabaseClient.query} and auth `user` payloads.
+ * 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>;
+    private readonly options;
     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<Row extends Record<string, unknown> = Record<string, unknown>>(table: string, databaseInstanceId?: string): PostgrestTableApi<Row>;
 }
 /**
- * Browser client: **no org `ragable_*` API key**.
- * - {@link RagableBrowser.agents} — public agent SSE.
- * - {@link RagableBrowser.auth} / {@link RagableBrowser.database} — need `authGroupId` (+ `getAccessToken` for protected calls).
- *
- * Pass schema and user types like Supabase: `createBrowserClient<Database, AuthUser>({ ... })`.
- * For Shift and `/v1/*`, use {@link createClient} on a server.
+ * **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;
 
 /**
  * Shared SSE parsing for `data: {json}` lines (Ragable agent streams).
@@ -427,10 +599,19 @@ declare class Ragable {
     constructor(options: RagableClientOptions);
 }
 /**
- * Server-side client with your **secret** `ragable_*` API key.
- * Use from Node, Edge, or your Engine — never in browser bundles.
- * For public agent streaming from the browser without a key, use {@link createBrowserClient}.
+ * **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 BrowserSqlQueryParams, type BrowserSqlQueryResult, type DefaultRagableDatabase, type FormatContextOptions, type Json, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RequestOptions, type RetrieveParams, 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 Tables, type TablesInsert, type TablesUpdate, createBrowserClient, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, type BrowserAuthSession, type BrowserAuthTokens, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type DefaultRagableDatabase, type FormatContextOptions, type Json, PostgrestDeleteBuilder, PostgrestInsertBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, 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 Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };

package/dist/index.d.ts

@@ -54,6 +54,11 @@ type TablesUpdate<D extends RagableDatabase, TableName extends keyof D["public"]
     Update: infer U;
 } ? U extends Record<string, unknown> ? U : Record<string, unknown> : Partial<Tables<D, TableName>>;
 
+/**
+ * Native `fetch` must not be called as a detached reference (`const f = fetch; f(url)`),
+ * or the browser throws **Illegal invocation**. Use this for defaults and for `options.fetch`.
+ */
+declare function bindFetch(custom?: typeof fetch): typeof fetch;
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -222,6 +227,107 @@ declare class AgentsClient {
     chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
 
+/** Shared with {@link RagableBrowserDatabaseClient.query} — duplicated to avoid circular imports. */
+interface BrowserSqlExecParams {
+    databaseInstanceId: string;
+    sql: string;
+    params?: unknown[];
+    readOnly?: boolean;
+    timeoutMs?: number;
+    rowLimit?: number;
+}
+interface BrowserSqlExecResult<Row extends Record<string, unknown> = Record<string, unknown>> {
+    command: string;
+    rowCount: number;
+    truncated: boolean;
+    rows: Row[];
+}
+type PostgrestResult<T> = {
+    data: T;
+    error: null;
+} | {
+    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;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly columns;
+    private filters;
+    private _limit?;
+    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;
+    limit(n: number): this;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): this;
+    /** @param includeUserLimit when false, omit `.limit()` (for `.single()` / `.maybeSingle()`). */
+    private buildSelectCore;
+    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>>;
+}
+declare class PostgrestInsertBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly rows;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
+    select(columns?: string): this;
+    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 execute;
+}
+declare class PostgrestUpdateBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly patch;
+    private filters;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>);
+    eq(column: string, value: unknown): this;
+    select(columns?: string): this;
+    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 execute;
+}
+declare class PostgrestDeleteBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private filters;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string);
+    eq(column: string, value: unknown): this;
+    select(columns?: string): this;
+    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 execute;
+}
+declare class PostgrestTableApi<Row extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string);
+    select(columns?: string): PostgrestSelectBuilder<Row>;
+    insert(values: Record<string, unknown> | Record<string, unknown>[]): PostgrestInsertBuilder<Row>;
+    update(patch: Record<string, unknown>): PostgrestUpdateBuilder<Row>;
+    delete(): PostgrestDeleteBuilder<Row>;
+}
+
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
 interface RagableBrowserClientOptions {
     /** Organization id (UUID) — public agent chat URLs. */
@@ -231,6 +337,10 @@ interface RagableBrowserClientOptions {
      * {@link RagableBrowserDatabaseClient}.
      */
     authGroupId?: string;
+    /**
+     * Default Backspace SQL instance id for {@link RagableBrowser.from} (Supabase-style table API).
+     */
+    databaseInstanceId?: string;
     /**
      * Returns the end-user access JWT (from login/register/refresh).
      * Required for `auth.getMe`, `auth.updateMe`, and `database.query`.
@@ -256,14 +366,72 @@ interface BrowserAuthTokens {
     refreshToken: string;
     expiresIn: string;
 }
-/** End-user auth (email/password) for a linked authentication group — no org API key. */
+/** 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 get fetchImpl();
     private toUrl;
     private baseHeaders;
     private authPrefix;
+    /** Supabase: `signUp` → `{ data: { user, session }, error }` */
+    signUp(credentials: {
+        email: string;
+        password: string;
+        options?: {
+            data?: Record<string, unknown>;
+        };
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+        session: SupabaseCompatSession<AuthUser>;
+    }>>;
+    /** Supabase: `signInWithPassword` */
+    signInWithPassword(credentials: {
+        email: string;
+        password: string;
+    }): Promise<PostgrestResult<{
+        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;
+        data?: {
+            name?: string | null;
+        };
+    }): 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;
@@ -290,8 +458,11 @@ interface BrowserSqlQueryParams {
     databaseInstanceId: string;
     sql: string;
     params?: unknown[];
-    /** Ignored — the API only allows safe read-only SQL for end users. */
-    readOnly?: true;
+    /**
+     * 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;
 }
@@ -302,16 +473,13 @@ interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<str
     rows: Row[];
 }
 /**
- * Run SQL against a Postgres instance linked to a website that uses the same `authGroupId`,
- * authenticated as the signed-in end-user (access token).
- *
- * Pass `createBrowserClient<YourDatabase>()` and use `query<Tables<YourDatabase, 't'>>()`
- * for Supabase-style row typing.
+ * 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 fetchImpl;
     constructor(options: RagableBrowserClientOptions);
-    private get fetchImpl();
     private toUrl;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams): Promise<BrowserSqlQueryResult<Row>>;
     private baseHeaders;
@@ -322,8 +490,8 @@ declare class RagableBrowserDatabaseClient<_Schema extends RagableDatabase = Def
  */
 declare class RagableBrowserAgentsClient {
     private readonly options;
+    private readonly fetchImpl;
     constructor(options: RagableBrowserClientOptions);
-    private get fetchImpl();
     private toUrl;
     /**
      * Stream agent execution as SSE (`POST /public/organizations/:orgId/agents/:agentId/chat/stream`).
@@ -336,24 +504,28 @@ interface AgentPublicChatParams extends AgentChatParams {
     triggerNodeId?: string;
 }
 /**
- * Browser client root. Use `createBrowserClient<Database, AuthUser>()` for Supabase-style
- * typing on {@link RagableBrowserDatabaseClient.query} and auth `user` payloads.
+ * 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>;
+    private readonly options;
     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<Row extends Record<string, unknown> = Record<string, unknown>>(table: string, databaseInstanceId?: string): PostgrestTableApi<Row>;
 }
 /**
- * Browser client: **no org `ragable_*` API key**.
- * - {@link RagableBrowser.agents} — public agent SSE.
- * - {@link RagableBrowser.auth} / {@link RagableBrowser.database} — need `authGroupId` (+ `getAccessToken` for protected calls).
- *
- * Pass schema and user types like Supabase: `createBrowserClient<Database, AuthUser>({ ... })`.
- * For Shift and `/v1/*`, use {@link createClient} on a server.
+ * **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;
 
 /**
  * Shared SSE parsing for `data: {json}` lines (Ragable agent streams).
@@ -427,10 +599,19 @@ declare class Ragable {
     constructor(options: RagableClientOptions);
 }
 /**
- * Server-side client with your **secret** `ragable_*` API key.
- * Use from Node, Edge, or your Engine — never in browser bundles.
- * For public agent streaming from the browser without a key, use {@link createBrowserClient}.
+ * **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 BrowserSqlQueryParams, type BrowserSqlQueryResult, type DefaultRagableDatabase, type FormatContextOptions, type Json, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RequestOptions, type RetrieveParams, 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 Tables, type TablesInsert, type TablesUpdate, createBrowserClient, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, type BrowserAuthSession, type BrowserAuthTokens, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type DefaultRagableDatabase, type FormatContextOptions, type Json, PostgrestDeleteBuilder, PostgrestInsertBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, 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 Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };