@ragable/sdk 0.4.1 → 0.5.0

package/dist/index.d.mts

@@ -53,6 +53,19 @@ 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)`),
@@ -242,6 +255,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,58 +293,160 @@ 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>>;
 }
 
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
@@ -455,7 +576,11 @@ declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown>
     }>;
 }
 interface BrowserSqlQueryParams {
-    databaseInstanceId: string;
+    /**
+     * Defaults to `databaseInstanceId` on {@link RagableBrowserClientOptions} when set
+     * (so you can configure it once on `createBrowserClient`).
+     */
+    databaseInstanceId?: string;
     sql: string;
     params?: unknown[];
     /**
@@ -517,7 +642,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).
@@ -614,4 +739,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 BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, 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,6 +53,19 @@ 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)`),
@@ -242,6 +255,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,58 +293,160 @@ 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>>;
 }
 
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
@@ -455,7 +576,11 @@ declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown>
     }>;
 }
 interface BrowserSqlQueryParams {
-    databaseInstanceId: string;
+    /**
+     * Defaults to `databaseInstanceId` on {@link RagableBrowserClientOptions} when set
+     * (so you can configure it once on `createBrowserClient`).
+     */
+    databaseInstanceId?: string;
     sql: string;
     params?: unknown[];
     /**
@@ -517,7 +642,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).
@@ -614,4 +739,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 BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, 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 };