@ragable/sdk 0.4.2 → 0.5.1

package/dist/index.d.mts

@@ -53,12 +53,27 @@ type TablesInsert<D extends RagableDatabase, TableName extends keyof D["public"]
 type TablesUpdate<D extends RagableDatabase, TableName extends keyof D["public"]["Tables"] & string> = [D["public"]["Tables"][TableName]] extends [never] ? Record<string, unknown> : D["public"]["Tables"][TableName] extends {
     Update: infer U;
 } ? U extends Record<string, unknown> ? U : Record<string, unknown> : Partial<Tables<D, TableName>>;
+/**
+ * Table name union for `client.from(...)`.
+ * When `Tables` is empty (`DefaultRagableDatabase`), any `string` is allowed.
+ */
+type RagableTableNames<D extends RagableDatabase> = [
+    keyof D["public"]["Tables"]
+] extends [never] ? string : Extract<keyof D["public"]["Tables"], string>;
+/** Row type for `from(table)` when a concrete `Database` generic is set. */
+type TableRow<D extends RagableDatabase, T extends RagableTableNames<D>> = [keyof D["public"]["Tables"]] extends [never] ? Record<string, unknown> : T extends keyof D["public"]["Tables"] ? Tables<D, T> : Record<string, unknown>;
+/** Insert payload for typed `from(table).insert(...)`. */
+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>;
 
 /**
  * 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;
+/** Default hosted API (`…/api`) when `baseUrl` is omitted (browser + server clients). */
+declare const DEFAULT_RAGABLE_API_BASE = "https://ragable-341305259977.asia-southeast1.run.app/api";
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -242,6 +257,12 @@ interface BrowserSqlExecResult<Row extends Record<string, unknown> = Record<stri
     truncated: boolean;
     rows: Row[];
 }
+type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike";
+interface Filter {
+    op: FilterOp;
+    column: string;
+    value: unknown;
+}
 type PostgrestResult<T> = {
     data: T;
     error: null;
@@ -274,61 +295,169 @@ declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Recor
     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[]>> {
+/** 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 databaseInstanceId;
     private readonly table;
     private readonly rows;
-    private returning;
     constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
-    select(columns?: string): this;
+    /**
+     * Return inserted rows (Supabase: chain `.select()` to get data).
+     * @see https://supabase.com/docs/reference/javascript/insert
+     */
+    select(columns?: string): PostgrestInsertReturningBuilder<Row>;
+    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 databaseInstanceId;
+    private readonly table;
+    private readonly rows;
+    private readonly returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[], returning: string);
     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;
+    private executeMany;
+    single(): Promise<PostgrestResult<Row>>;
+    maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-declare class PostgrestUpdateBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+/** 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;
     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;
+    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
+     */
+    select(columns?: string): PostgrestUpdateReturningBuilder<Row>;
+    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 PostgrestUpdateReturningBuilder<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 readonly filters;
+    private readonly returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>, filters: Filter[], returning: string);
     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;
+    private executeMany;
+    single(): Promise<PostgrestResult<Row>>;
+    maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-declare class PostgrestDeleteBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+/** Delete without `.select()` → `{ data: null }`. */
+declare class PostgrestDeleteRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<null>> {
     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;
+    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
+     */
+    select(columns?: string): PostgrestDeleteReturningBuilder<Row>;
+    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 databaseInstanceId;
+    private readonly table;
+    private readonly filters;
+    private readonly returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, filters: Filter[], returning: string);
     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;
+    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;
 }
-declare class PostgrestTableApi<Row extends Record<string, unknown> = Record<string, unknown>> {
+/** 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 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>;
+    private readonly rows;
+    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
+     */
+    select(columns?: string): PostgrestUpsertReturningBuilder<Row>;
+    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>>;
+}
+declare class PostgrestUpsertReturningBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly root;
+    private readonly returning;
+    constructor(root: PostgrestUpsertRootBuilder<Row>, returning: string);
+    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 PostgrestTableApi<Database extends RagableDatabase = DefaultRagableDatabase, TableName extends RagableTableNames<Database> = RagableTableNames<Database>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    constructor(run: RunQuery, databaseInstanceId: string, table: TableName extends string ? string : string);
+    select(columns?: string): PostgrestSelectBuilder<TableRow<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
+     */
+    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).
+ */
 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;
@@ -341,14 +470,27 @@ interface RagableBrowserClientOptions {
      * 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 `database.query`.
+     * 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 "http://localhost:8080/api"
+     * @default `https://ragable-341305259977.asia-southeast1.run.app/api` ({@link DEFAULT_RAGABLE_API_BASE})
      */
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -521,7 +663,7 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
      * 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>;
+    from<TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string): PostgrestTableApi<Database, TableName>;
 }
 /**
  * **Supabase-equivalent** browser client factory (no org API key).
@@ -618,4 +760,4 @@ declare function createClient<Database extends RagableDatabase = DefaultRagableD
  */
 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 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 };
+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 };

package/dist/index.d.ts

@@ -53,12 +53,27 @@ type TablesInsert<D extends RagableDatabase, TableName extends keyof D["public"]
 type TablesUpdate<D extends RagableDatabase, TableName extends keyof D["public"]["Tables"] & string> = [D["public"]["Tables"][TableName]] extends [never] ? Record<string, unknown> : D["public"]["Tables"][TableName] extends {
     Update: infer U;
 } ? U extends Record<string, unknown> ? U : Record<string, unknown> : Partial<Tables<D, TableName>>;
+/**
+ * Table name union for `client.from(...)`.
+ * When `Tables` is empty (`DefaultRagableDatabase`), any `string` is allowed.
+ */
+type RagableTableNames<D extends RagableDatabase> = [
+    keyof D["public"]["Tables"]
+] extends [never] ? string : Extract<keyof D["public"]["Tables"], string>;
+/** Row type for `from(table)` when a concrete `Database` generic is set. */
+type TableRow<D extends RagableDatabase, T extends RagableTableNames<D>> = [keyof D["public"]["Tables"]] extends [never] ? Record<string, unknown> : T extends keyof D["public"]["Tables"] ? Tables<D, T> : Record<string, unknown>;
+/** Insert payload for typed `from(table).insert(...)`. */
+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>;
 
 /**
  * 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;
+/** Default hosted API (`…/api`) when `baseUrl` is omitted (browser + server clients). */
+declare const DEFAULT_RAGABLE_API_BASE = "https://ragable-341305259977.asia-southeast1.run.app/api";
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -242,6 +257,12 @@ interface BrowserSqlExecResult<Row extends Record<string, unknown> = Record<stri
     truncated: boolean;
     rows: Row[];
 }
+type FilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike";
+interface Filter {
+    op: FilterOp;
+    column: string;
+    value: unknown;
+}
 type PostgrestResult<T> = {
     data: T;
     error: null;
@@ -274,61 +295,169 @@ declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Recor
     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[]>> {
+/** 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 databaseInstanceId;
     private readonly table;
     private readonly rows;
-    private returning;
     constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
-    select(columns?: string): this;
+    /**
+     * Return inserted rows (Supabase: chain `.select()` to get data).
+     * @see https://supabase.com/docs/reference/javascript/insert
+     */
+    select(columns?: string): PostgrestInsertReturningBuilder<Row>;
+    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 databaseInstanceId;
+    private readonly table;
+    private readonly rows;
+    private readonly returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[], returning: string);
     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;
+    private executeMany;
+    single(): Promise<PostgrestResult<Row>>;
+    maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-declare class PostgrestUpdateBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+/** 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;
     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;
+    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
+     */
+    select(columns?: string): PostgrestUpdateReturningBuilder<Row>;
+    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 PostgrestUpdateReturningBuilder<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 readonly filters;
+    private readonly returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>, filters: Filter[], returning: string);
     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;
+    private executeMany;
+    single(): Promise<PostgrestResult<Row>>;
+    maybeSingle(): Promise<PostgrestResult<Row | null>>;
 }
-declare class PostgrestDeleteBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+/** Delete without `.select()` → `{ data: null }`. */
+declare class PostgrestDeleteRootBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<null>> {
     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;
+    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
+     */
+    select(columns?: string): PostgrestDeleteReturningBuilder<Row>;
+    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 databaseInstanceId;
+    private readonly table;
+    private readonly filters;
+    private readonly returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, filters: Filter[], returning: string);
     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;
+    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;
 }
-declare class PostgrestTableApi<Row extends Record<string, unknown> = Record<string, unknown>> {
+/** 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 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>;
+    private readonly rows;
+    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
+     */
+    select(columns?: string): PostgrestUpsertReturningBuilder<Row>;
+    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>>;
+}
+declare class PostgrestUpsertReturningBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly root;
+    private readonly returning;
+    constructor(root: PostgrestUpsertRootBuilder<Row>, returning: string);
+    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 PostgrestTableApi<Database extends RagableDatabase = DefaultRagableDatabase, TableName extends RagableTableNames<Database> = RagableTableNames<Database>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    constructor(run: RunQuery, databaseInstanceId: string, table: TableName extends string ? string : string);
+    select(columns?: string): PostgrestSelectBuilder<TableRow<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
+     */
+    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).
+ */
 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;
@@ -341,14 +470,27 @@ interface RagableBrowserClientOptions {
      * 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 `database.query`.
+     * 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 "http://localhost:8080/api"
+     * @default `https://ragable-341305259977.asia-southeast1.run.app/api` ({@link DEFAULT_RAGABLE_API_BASE})
      */
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -521,7 +663,7 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
      * 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>;
+    from<TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string): PostgrestTableApi<Database, TableName>;
 }
 /**
  * **Supabase-equivalent** browser client factory (no org API key).
@@ -618,4 +760,4 @@ declare function createClient<Database extends RagableDatabase = DefaultRagableD
  */
 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 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 };
+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 };