@ragable/sdk 0.8.1 → 0.8.3

package/dist/index.d.mts

@@ -662,6 +662,265 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     upsert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], options: PostgrestUpsertOptions): PostgrestUpsertRootBuilder<TableRow<Database, TableName>>;
 }
 
+/**
+ * Supabase-style chainable query builders for Ragable collections.
+ *
+ * ```ts
+ * const { data, error } = await client.db.collections.todos
+ *   .select("*")
+ *   .eq("done", false)
+ *   .order("createdAt", { ascending: false })
+ *   .limit(20);
+ * ```
+ *
+ * Rows come back **flat**: the JSON document's fields at the top level with the
+ * record envelope merged in (`id`, `createdAt`, `updatedAt` — envelope wins on
+ * name collisions).
+ */
+/** A collection record as returned by the chainable builders. */
+type CollectionRow<Row extends Record<string, unknown> = Record<string, unknown>> = Omit<Row, "id" | "createdAt" | "updatedAt"> & {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+};
+interface RecordEnvelope {
+    id: string;
+    data: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CollectionSelectedEmbed {
+    /** Row key the embedded value lands under (defaults to the collection name). */
+    alias: string;
+    collection: string;
+    /** Linking field (`!hint`); when omitted the server infers it from schemas/conventions. */
+    hint?: string;
+    /** Projection of the embedded rows' fields (null = all). */
+    columns: string[] | null;
+}
+interface CollectionSelectedAggregate {
+    fn: "count" | "sum" | "avg" | "min" | "max";
+    field?: string;
+    alias: string;
+}
+interface ParsedSelectExpression {
+    /** Plain fields (group keys when aggregates are present); null = `*`. */
+    fields: string[] | null;
+    embeds: CollectionSelectedEmbed[];
+    aggregates: CollectionSelectedAggregate[];
+}
+/**
+ * Parse a `select()` string into plain columns, relation embeds, and
+ * aggregates (Supabase grammar):
+ *
+ * - `"*, author:users!author_id(name,avatar_url), comments(*)"` — embeds
+ * - `"category, count(), total:amount.sum()"` — aggregation grouped by `category`
+ */
+declare function parseSelectExpression(columns: string | undefined): ParsedSelectExpression;
+/**
+ * Transport bound to one collection: `path` is relative to the collection
+ * (e.g. `"/find"`, `"/records"`). Implemented by the database client.
+ */
+type CollectionRequestFn = <T>(method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown, signal?: AbortSignal) => Promise<T>;
+type CollectionFilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "startsWith" | "endsWith" | "in" | "nin" | "contains" | "is" | "exists";
+interface FilterEntry {
+    field: string;
+    op: CollectionFilterOp;
+    value: unknown;
+    not?: boolean;
+}
+/** Loose-but-helpful field name type: known row fields, envelope fields, or any string. */
+type CollectionField<Row extends Record<string, unknown>> = Extract<keyof Row, string> | "id" | "createdAt" | "updatedAt" | (string & {});
+/**
+ * Parse a Supabase-style `.or()` string into where-shaped OR groups.
+ * Top-level commas separate OR branches; `and(...)` groups conditions
+ * within one branch.
+ */
+declare function parseOrString(input: string): Record<string, unknown>[];
+declare abstract class CollectionConditionBuilder<Row extends Record<string, unknown>> {
+    protected filters: FilterEntry[];
+    protected orGroups: Record<string, unknown>[] | null;
+    protected signal?: AbortSignal;
+    /** `field = value` (or `IS NULL` when value is null). */
+    eq(field: CollectionField<Row>, value: unknown): this;
+    /** `field != value` (null-aware). */
+    neq(field: CollectionField<Row>, value: unknown): this;
+    gt(field: CollectionField<Row>, value: number | string): this;
+    gte(field: CollectionField<Row>, value: number | string): this;
+    lt(field: CollectionField<Row>, value: number | string): this;
+    lte(field: CollectionField<Row>, value: number | string): this;
+    /** SQL LIKE — you supply the `%` wildcards, e.g. `.like("title", "%report%")`. */
+    like(field: CollectionField<Row>, pattern: string): this;
+    /** Case-insensitive LIKE. */
+    ilike(field: CollectionField<Row>, pattern: string): this;
+    /** Prefix match; wildcard characters in `value` are matched literally. */
+    startsWith(field: CollectionField<Row>, value: string): this;
+    /** Suffix match; wildcard characters in `value` are matched literally. */
+    endsWith(field: CollectionField<Row>, value: string): this;
+    /** Value is one of `values`. */
+    in(field: CollectionField<Row>, values: unknown[]): this;
+    /** Value is NOT one of `values`. */
+    nin(field: CollectionField<Row>, values: unknown[]): this;
+    /**
+     * JSONB containment: array fields contain the given element(s), object
+     * fields contain the given key/value pairs.
+     * `.contains("tags", ["urgent"])`, `.contains("meta", { plan: "pro" })`.
+     */
+    contains(field: CollectionField<Row>, value: unknown): this;
+    /** Strict null / boolean check: `.is("archivedAt", null)`, `.is("done", true)`. */
+    is(field: CollectionField<Row>, value: null | boolean): this;
+    /** Whether the JSON key is present at all: `.exists("avatarUrl", false)`. */
+    exists(field: CollectionField<Row>, present?: boolean): this;
+    /** Negated condition: `.not("status", "eq", "archived")`. */
+    not(field: CollectionField<Row>, op: CollectionFilterOp, value: unknown): this;
+    /** Generic escape hatch, mirroring Supabase `.filter(column, op, value)`. */
+    filter(field: CollectionField<Row>, op: CollectionFilterOp, value: unknown): this;
+    /** Equality on every key of `query` (null values become IS NULL). */
+    match(query: Partial<Row> & Record<string, unknown>): this;
+    /**
+     * OR conditions, ANDed with the other filters. Accepts the Supabase string
+     * grammar — `.or('done.eq.true,priority.gte.3')`, with `and(...)` for a
+     * multi-condition branch — or an array of where-style objects:
+     * `.or([{ done: true }, { priority: { gte: 3 } }])`.
+     *
+     * One `.or()` per query: the wire format carries a single disjunction.
+     */
+    or(conditions: string | Record<string, unknown>[]): this;
+    abortSignal(signal: AbortSignal): this;
+    protected get hasConditions(): boolean;
+    protected wireFilters(): Array<Record<string, unknown>>;
+    private assertOp;
+    private push;
+}
+interface CollectionSelectOptions {
+    /** `"exact"` runs a COUNT(*) with the same filters; result lands on `count`. */
+    count?: "exact";
+    /** With `head: true`, no rows are fetched — only the count. */
+    head?: boolean;
+}
+/** List results carry `count` (populated when `{ count: "exact" }` was requested). */
+type CollectionListResult<T> = {
+    data: T[];
+    error: null;
+    count: number | null;
+} | {
+    data: null;
+    error: RagableError;
+    count: null;
+};
+declare class CollectionSelectBuilder<Row extends Record<string, unknown> = Record<string, unknown>, Out extends Record<string, unknown> = CollectionRow<Row>> extends CollectionConditionBuilder<Row> implements PromiseLike<CollectionListResult<Out>> {
+    private readonly request;
+    private _limit?;
+    private _offset?;
+    private _order;
+    private readonly parsed;
+    private readonly wantCount;
+    private readonly headOnly;
+    constructor(request: CollectionRequestFn, columns?: string, options?: CollectionSelectOptions);
+    /** Sort by a field. Call again to add secondary sort keys (max 4). */
+    order(field: CollectionField<Row>, options?: {
+        ascending?: boolean;
+    }): this;
+    limit(n: number): this;
+    offset(n: number): this;
+    /** Rows `from`..`to` inclusive (zero-based), like Supabase `.range()`. */
+    range(from: number, to: number): this;
+    then<TResult1 = CollectionListResult<Out>, TResult2 = never>(onfulfilled?: ((value: CollectionListResult<Out>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Exactly one row. 0 or >1 matching rows is an error (code PGRST116),
+     * mirroring Supabase `.single()`.
+     */
+    single(): Promise<PostgrestResult<Out>>;
+    /** One row or `null` — only >1 matching rows is an error. */
+    maybeSingle(): Promise<PostgrestResult<Out | null>>;
+    private buildBody;
+    /** Flatten the envelope and apply column + embedded-column projection. */
+    private shapeRow;
+    private executeRows;
+    private execute;
+}
+/**
+ * `.select()` stage of a mutation: resolves to the affected rows (flattened),
+ * with `single()` / `maybeSingle()` narrowing.
+ */
+declare class CollectionMutationReturning<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<CollectionRow<Row>[]>> {
+    private readonly run;
+    private readonly columns;
+    constructor(run: () => Promise<PostgrestResult<RecordEnvelope[]>>, columns: string[] | null);
+    then<TResult1 = PostgrestResult<CollectionRow<Row>[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<CollectionRow<Row>[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private executeMany;
+    single(): Promise<PostgrestResult<CollectionRow<Row>>>;
+    maybeSingle(): Promise<PostgrestResult<CollectionRow<Row> | null>>;
+}
+declare class CollectionUpdateBuilder<Row extends Record<string, unknown> = Record<string, unknown>> extends CollectionConditionBuilder<Row> implements PromiseLike<PostgrestResult<null>> {
+    private readonly request;
+    private readonly patch;
+    private _limit?;
+    constructor(request: CollectionRequestFn, patch: Record<string, unknown>);
+    limit(n: number): this;
+    select(columns?: string): CollectionMutationReturning<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 execute;
+}
+declare class CollectionDeleteBuilder<Row extends Record<string, unknown> = Record<string, unknown>> extends CollectionConditionBuilder<Row> implements PromiseLike<PostgrestResult<null>> {
+    private readonly request;
+    private _limit?;
+    constructor(request: CollectionRequestFn);
+    limit(n: number): this;
+    select(columns?: string): CollectionMutationReturning<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 execute;
+}
+/** A collection record envelope (`data` holds the JSON document). */
+interface CollectionRecordEnvelope<Row extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    data: Row;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Insert chain. Awaiting it directly resolves to the inserted record
+ * envelope(s) — a Ragable extension kept for back-compat (Supabase resolves to
+ * `null` without `.select()`). Chain `.select()` for flat rows.
+ */
+declare class CollectionInsertChain<Row extends Record<string, unknown> = Record<string, unknown>, Resolved = CollectionRecordEnvelope<Row>> implements PromiseLike<PostgrestResult<Resolved>> {
+    private readonly request;
+    private readonly rows;
+    private readonly single;
+    private _signal?;
+    constructor(request: CollectionRequestFn, rows: Record<string, unknown>[], single: boolean);
+    abortSignal(signal: AbortSignal): this;
+    select(columns?: string): CollectionMutationReturning<Row>;
+    then<TResult1 = PostgrestResult<Resolved>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Resolved>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private executeEnvelopes;
+}
+interface CollectionUpsertOptions {
+    /**
+     * Field to match existing records on: `"id"` (default) or a data field,
+     * e.g. `"slug"`. Collections have no unique indexes, so this is
+     * match-then-update: if several records share the value, all are updated.
+     */
+    onConflict?: string;
+    /** Skip items that match an existing record instead of updating them. */
+    ignoreDuplicates?: boolean;
+}
+interface CollectionUpsertSummary {
+    inserted: number;
+    updated: number;
+    skipped: number;
+}
+declare class CollectionUpsertBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<CollectionUpsertSummary>> {
+    private readonly request;
+    private readonly rows;
+    private readonly options;
+    private _signal?;
+    constructor(request: CollectionRequestFn, rows: Record<string, unknown>[], options: CollectionUpsertOptions);
+    abortSignal(signal: AbortSignal): this;
+    select(columns?: string): CollectionMutationReturning<Row>;
+    then<TResult1 = PostgrestResult<CollectionUpsertSummary>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<CollectionUpsertSummary>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
+
 interface SessionStorage {
     getItem(key: string): string | null | Promise<string | null>;
     setItem(key: string, value: string): void | Promise<void>;
@@ -708,7 +967,9 @@ declare class AuthBroadcastChannel {
     close(): void;
 }
 
-type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "TOKEN_REFRESH_FAILED" | "USER_UPDATED";
+type AuthChangeEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "TOKEN_REFRESH_FAILED" | "PASSWORD_RECOVERY" | "USER_UPDATED";
+/** Email token kinds accepted by {@link RagableAuth.verifyOtp}. `"email"` is an alias for `"magiclink"`. */
+type AuthOtpType = "recovery" | "magiclink" | "email";
 type AuthUserMetadata = Record<string, unknown>;
 interface DefaultAuthUser<Metadata extends AuthUserMetadata = AuthUserMetadata> {
     id: string;
@@ -819,6 +1080,83 @@ declare class RagableAuth<U extends object = DefaultAuthUser> {
     }): Promise<{
         error: null;
     }>;
+    /**
+     * Email a password-recovery link. The link points at `redirectTo` (or the
+     * site's deployed domain when omitted) with `?token_hash=…&type=recovery`
+     * appended. On that page, either:
+     * - call {@link resetPassword} with the token and the new password, or
+     * - call {@link verifyOtp} to sign the user in, then `updateUser({ password })`.
+     *
+     * Always resolves successfully for well-formed requests — whether the email
+     * has an account is never revealed.
+     */
+    resetPasswordForEmail(email: string, options?: {
+        redirectTo?: string;
+    }): Promise<PostgrestResult<Record<string, never>>>;
+    /**
+     * Email a one-click sign-in (magic) link — passwordless auth. New addresses
+     * get an account automatically unless `shouldCreateUser: false`. The emailed
+     * link carries `?token_hash=…&type=magiclink`; complete sign-in on that page
+     * with {@link verifyOtp}.
+     */
+    signInWithOtp(params: {
+        email: string;
+        options?: {
+            emailRedirectTo?: string;
+            shouldCreateUser?: boolean;
+        };
+    }): Promise<PostgrestResult<{
+        user: null;
+        session: null;
+    }>>;
+    /**
+     * Exchange an emailed `token_hash` for a session. Reads the token from the
+     * URL your recovery / magic-link page receives:
+     *
+     * ```ts
+     * const qs = new URLSearchParams(window.location.search);
+     * const { data, error } = await client.auth.verifyOtp({
+     *   token_hash: qs.get("token_hash")!,
+     *   type: qs.get("type") as "recovery" | "magiclink",
+     * });
+     * ```
+     *
+     * Emits `SIGNED_IN` (and `PASSWORD_RECOVERY` for recovery tokens — listen
+     * for it to route to your "choose a new password" screen).
+     */
+    verifyOtp(params: {
+        token_hash?: string;
+        /** Alias for `token_hash`. */
+        tokenHash?: string;
+        type: AuthOtpType;
+    }): Promise<PostgrestResult<{
+        user: U;
+        session: AuthSession<U>;
+    }>>;
+    /**
+     * One-shot recovery: verify the emailed recovery token, set the new
+     * password, and sign the user in — no intermediate session juggling.
+     *
+     * ```ts
+     * const qs = new URLSearchParams(window.location.search);
+     * const { data, error } = await client.auth.resetPassword({
+     *   tokenHash: qs.get("token_hash")!,
+     *   newPassword: form.password,
+     * });
+     * ```
+     *
+     * Recovery links are single-use: once the password changes, the same link
+     * is rejected.
+     */
+    resetPassword(params: {
+        tokenHash?: string;
+        /** Alias for `tokenHash`. */
+        token_hash?: string;
+        newPassword: string;
+    }): Promise<PostgrestResult<{
+        user: U;
+        session: AuthSession<U>;
+    }>>;
     refreshSession(refreshToken?: string): Promise<PostgrestResult<{
         session: AuthSession<U>;
         user: U;
@@ -1279,6 +1617,106 @@ declare function streamObjectFromContext<T = unknown>(ctx: InferenceRequestConte
  */
 declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): StreamObjectResult<T>;
 
+/**
+ * Server-side client — the authenticated SDK for code that runs on a trusted
+ * server (a Ragable backend **function**, an Engine, or your own Node service).
+ *
+ * Unlike the browser client there is **no sign-in / session machinery** here:
+ * a server is not a logged-in user. Instead you provide credentials up front and
+ * the client speaks to the same Ragable data plane the browser uses, so the
+ * semantics (collection security, `{ data, error }` shapes, PostgREST) are
+ * identical — this reuses the exact same fetch-based sub-clients, never a
+ * reimplementation.
+ *
+ * Two privilege levels:
+ *  - **caller** (default): acts as the end user who invoked you — uses their
+ *    forwarded access token, falling back to the public anon key for anonymous
+ *    callers. Collection security applies, exactly as in the browser.
+ *  - **admin**: authenticates with the auth group's **data-admin key**, which
+ *    bypasses collection security (owner/group/claim grants do not apply) and
+ *    can write protected collections. Reach for it deliberately.
+ *
+ * ```ts
+ * // inside /functions/<name>.ts — `context.ragable` is a pre-built server client
+ * export default async function createTask(input, context) {
+ *   // as the caller (respects collection security):
+ *   const { data, error } = await context.ragable.db.collections.tasks.insert(input);
+ *   // privileged work (bypasses collection security):
+ *   await context.ragable.asAdmin().db.collections.audit_log.insert({ action: "create" });
+ *   return data;
+ * }
+ * ```
+ */
+
+/** Which credential a server client authenticates with. */
+type ServerPrivilege = "caller" | "admin";
+/**
+ * Inputs to {@link createServerClient}. The IDs and keys are normally supplied by
+ * the runtime (a function's injected `context.ragable`); construct one by hand
+ * only for a standalone server.
+ */
+interface RagableServerClientConfig {
+    organizationId: string;
+    websiteId?: string;
+    authGroupId?: string;
+    databaseInstanceId?: string;
+    storageBucketId?: string;
+    mailAccountId?: string;
+    /**
+     * The auth group's **data-admin key**. Required for `admin` privilege; omit it
+     * and `asAdmin()` throws. Server-only — never expose this to the browser.
+     */
+    adminKey?: string;
+    /**
+     * The invoking end user's access token (a real auth-group JWT), forwarded by
+     * the runtime. `null`/omitted for anonymous callers. Used by `caller`
+     * privilege; the public anon key is the fallback when this is absent.
+     */
+    callerToken?: string | null;
+    /** Public anon key — the `caller` fallback when no end user is signed in. */
+    publicAnonKey?: string;
+    /** Default privilege for the returned client. Defaults to `"caller"`. */
+    defaultPrivilege?: ServerPrivilege;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+/**
+ * A trusted, server-side Ragable client. Surface mirrors the browser client
+ * (`db`, `storage`, `mail`, `functions`, `ai`, `agents`) minus `auth` — a server
+ * authenticates with keys, not a session. Switch privilege with {@link asAdmin}
+ * / {@link asCaller}.
+ */
+declare class RagableServerClient<Database extends RagableDatabase = DefaultRagableDatabase, Functions extends RagableFunctions = DefaultRagableFunctions> {
+    private readonly config;
+    readonly database: RagableBrowserDatabaseClient<Database>;
+    readonly db: RagableBrowserDatabaseClient<Database>;
+    readonly storage: RagableBrowserStorageClient;
+    readonly mail: RagableBrowserMailClient;
+    readonly functions: FunctionInvoker<Functions>;
+    readonly ai: RagableBrowserAiClient;
+    readonly agents: RagableBrowserAgentsClient;
+    /** Which credential this client is using. */
+    readonly privilege: ServerPrivilege;
+    constructor(config: RagableServerClientConfig, privilege: ServerPrivilege);
+    /**
+     * A client authenticated with the **data-admin key** — bypasses collection
+     * security (owner/group/claim grants do not apply) and can write protected
+     * collections. Throws `SDK_ADMIN_KEY_REQUIRED` when no admin key is configured.
+     */
+    asAdmin(): RagableServerClient<Database, Functions>;
+    /**
+     * A client scoped to the invoking end user's identity (respects collection
+     * security). This is already the default; use it to drop back from `asAdmin()`.
+     */
+    asCaller(): RagableServerClient<Database, Functions>;
+}
+/**
+ * Create a server-side Ragable client. Defaults to **caller** privilege (acts as
+ * the invoking end user, respecting collection security); call `.asAdmin()` for
+ * privileged, security-bypassing access.
+ */
+declare function createServerClient<Database extends RagableDatabase = DefaultRagableDatabase, Functions extends RagableFunctions = DefaultRagableFunctions>(config: RagableServerClientConfig): RagableServerClient<Database, Functions>;
+
 /**
  * Backend "edge functions".
  *
@@ -1307,6 +1745,7 @@ declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): S
  * The handler's second argument (`context`) is injected by the server; callers
  * pass only `input`.
  */
+
 /**
  * Server-injected second argument to every function handler. Never constructed
  * on the client — the values come from the backend at invocation time.
@@ -1331,6 +1770,16 @@ interface RagableFunctionContext {
     auth: {
         token: string | null;
     };
+    /**
+     * A pre-authenticated {@link RagableServerClient} for talking back to your
+     * Ragable Cloud (db / storage / mail / functions / ai / agents) — already
+     * wired to this project, no setup or keys to manage.
+     *
+     * Defaults to the **caller's** identity, so collection security applies just
+     * like in the browser. Call `context.ragable.asAdmin()` for privileged work
+     * that must bypass collection security (e.g. owner-only writes, audit logs).
+     */
+    ragable: RagableServerClient;
 }
 /**
  * The shape a `/functions/<name>.ts` default export must satisfy. Type the
@@ -1461,6 +1910,39 @@ declare class RagableBrowserAuthClient<AuthUser extends object = DefaultAuthUser
     }): Promise<{
         error: null;
     }>;
+    /** Email a password-recovery link — see {@link RagableAuth.resetPasswordForEmail}. */
+    resetPasswordForEmail(email: string, options?: {
+        redirectTo?: string;
+    }): Promise<PostgrestResult<Record<string, never>>>;
+    /** Email a magic sign-in link — see {@link RagableAuth.signInWithOtp}. */
+    signInWithOtp(params: {
+        email: string;
+        options?: {
+            emailRedirectTo?: string;
+            shouldCreateUser?: boolean;
+        };
+    }): Promise<PostgrestResult<{
+        user: null;
+        session: null;
+    }>>;
+    /** Exchange an emailed token_hash for a session — see {@link RagableAuth.verifyOtp}. */
+    verifyOtp(params: {
+        token_hash?: string;
+        tokenHash?: string;
+        type: AuthOtpType;
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+        session: AuthSession<AuthUser>;
+    }>>;
+    /** Verify a recovery token and set a new password in one call — see {@link RagableAuth.resetPassword}. */
+    resetPassword(params: {
+        tokenHash?: string;
+        token_hash?: string;
+        newPassword: string;
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+        session: AuthSession<AuthUser>;
+    }>>;
     register(body: {
         email: string;
         password: string;
@@ -1638,6 +2120,35 @@ declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<
     private readonly name;
     private readonly databaseInstanceId?;
     constructor(database: RagableBrowserDatabaseClient<any>, name: string, databaseInstanceId?: string | undefined);
+    /** Transport for the chainable builders, bound to this collection. */
+    private chainRequest;
+    /**
+     * Supabase-style chainable query. Rows come back flat (`id`, `createdAt`,
+     * `updatedAt` merged into the document fields).
+     *
+     * ```ts
+     * const { data, error, count } = await collections.todos
+     *   .select("*", { count: "exact" })
+     *   .eq("done", false)
+     *   .or("priority.gte.3,starred.eq.true")
+     *   .order("createdAt", { ascending: false })
+     *   .range(0, 19);
+     * ```
+     *
+     * Relation embeds (one level): `select("*, author:users!author_id(name), comments(*)")`
+     * — to-one embeds become an object (or null), to-many an array. Aggregations:
+     * `select("category, count(), total:amount.sum()")` groups by the plain
+     * columns; pass a type argument for the result shape:
+     * `select<{ category: string; count: number }>("category, count()")`.
+     */
+    select: <Out extends Record<string, unknown> = CollectionRow<RowD<Row>>>(columns?: string, options?: CollectionSelectOptions) => CollectionSelectBuilder<RowD<Row>, Out>;
+    /**
+     * Insert-or-update matched on `onConflict` (`"id"` by default, or any data
+     * field, e.g. `{ onConflict: "slug" }`). Chain `.select()` for the affected
+     * rows. Match-based (no unique indexes): concurrent upserts of the same new
+     * value can both insert.
+     */
+    upsert: (values: BrowserCollectionInsertData<Row, Insert> | BrowserCollectionInsertData<Row, Insert>[], options?: CollectionUpsertOptions) => CollectionUpsertBuilder<RowD<Row>>;
     private normalizeFindArgs;
     private requestFind;
     /**
@@ -1662,18 +2173,32 @@ declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<
             id: string;
         } & Partial<WhereInput<RowD<Row>>>;
     }) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>> | null>>;
-    insert: (data: BrowserCollectionInsertData<Row, Insert>) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>>>;
+    /**
+     * Insert one row or an array of rows. Chain `.select()` for the inserted
+     * rows in flat shape, or await directly for the record envelope(s)
+     * (back-compat extension; Supabase resolves to null without `.select()`).
+     */
+    insert: {
+        (data: BrowserCollectionInsertData<Row, Insert>[]): CollectionInsertChain<RowD<Row>, BrowserCollectionRecord<RowD<Row>>[]>;
+        (data: BrowserCollectionInsertData<Row, Insert>): CollectionInsertChain<RowD<Row>, BrowserCollectionRecord<RowD<Row>>>;
+    };
     /**
      * Insert multiple rows in one request (server multi-value `INSERT`, single transaction).
      * Empty **`items`** resolves to an empty array. Max batch size is enforced on the server (500).
      */
     insertMany: (items: BrowserCollectionInsertData<Row, Insert>[]) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[]>>;
     /**
-     * Update rows matching `where` (JSON fields, plus envelope `id` / `createdAt` / `updatedAt`).
+     * Two forms:
+     * - `update(patch)` — Supabase-style chain: add filters, then await.
+     *   `update({ done: true }).eq("id", id)` (optionally `.select()`).
+     * - `update(where, patch)` — legacy direct call, returns updated records.
      */
-    update: (where: WhereInput<RowD<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
-        limit?: number;
-    }) => Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[]>>;
+    update: {
+        (patch: BrowserCollectionUpdateData<Row, Update>): CollectionUpdateBuilder<RowD<Row>>;
+        (where: WhereInput<RowD<Row>>, patch: BrowserCollectionUpdateData<Row, Update>, options?: {
+            limit?: number;
+        }): Promise<PostgrestResult<BrowserCollectionRecord<RowD<Row>>[]>>;
+    };
     /**
      * Like {@link BrowserCollectionApi.update} but the success payload includes
      * `meta.count` (number of rows returned from the update, bounded by `limit`).
@@ -1686,12 +2211,21 @@ declare class BrowserCollectionApi<Row extends Record<string, unknown> = Record<
             count: number;
         };
     }>>;
-    delete: (where: WhereInput<RowD<Row>>, options?: {
-        limit?: number;
-    }) => Promise<PostgrestResult<{
-        deleted: number;
-        records: BrowserCollectionRecord<RowD<Row>>[];
-    }>>;
+    /**
+     * Two forms:
+     * - `delete()` — Supabase-style chain: add filters, then await.
+     *   `delete().eq("id", id)` (optionally `.select()`).
+     * - `delete(where)` — legacy direct call, returns `{ deleted, records }`.
+     */
+    delete: {
+        (): CollectionDeleteBuilder<RowD<Row>>;
+        (where: WhereInput<RowD<Row>>, options?: {
+            limit?: number;
+        }): Promise<PostgrestResult<{
+            deleted: number;
+            records: BrowserCollectionRecord<RowD<Row>>[];
+        }>>;
+    };
     /**
      * Like {@link BrowserCollectionApi.delete} but the success payload includes **`meta.count`**
      * (number of deleted rows), matching {@link BrowserCollectionApi.updateMany}.
@@ -1730,7 +2264,7 @@ declare class RagableBrowserDatabaseClient<Database extends RagableDatabase = De
     private toUrl;
     defineCollection: (name: string, schema?: Record<string, unknown>, databaseInstanceId?: string) => Promise<PostgrestResult<BrowserCollectionDefinition>>;
     listCollections: (databaseInstanceId?: string) => Promise<PostgrestResult<BrowserCollectionDefinition[]>>;
-    _requestCollection<T>(method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown, databaseInstanceId?: string): Promise<T>;
+    _requestCollection<T>(method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown, databaseInstanceId?: string, signal?: AbortSignal): Promise<T>;
     query: <Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams) => Promise<PostgrestResult<BrowserSqlQueryResult<Row>>>;
     private baseHeaders;
     /**
@@ -2271,4 +2805,4 @@ declare function tryParsePartialJson(text: string): unknown | undefined;
 
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, BrowserStorageBucketClient, type BrowserStorageBulkDeleteResult, type BrowserStorageDownloadResult, type BrowserStorageItem, type BrowserStorageListResult, type BrowserStorageSignedUrlResult, type BrowserStorageUploadResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type DefaultRagableFunctions, type FinishReason, type FunctionInvoker, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type Json, type JsonSchema, LocalStorageAdapter, type MailMessageDetail, type MailMessagePreview, type MailSearchParams, type MailSendParams, type MailSendResult, MemoryStorageAdapter, type Message, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAiClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, RagableBrowserFunctionsClient, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, type RagableFunctionCall, type RagableFunctionContext, type RagableFunctionHandler, type RagableFunctionInvokeOptions, type RagableFunctions, RagableNetworkError, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type SseJsonEvent, type StreamObjectParams, type StreamObjectResult, type StreamPart, type StreamTextParams, type StreamTextResult, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthOtpType, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, BrowserStorageBucketClient, type BrowserStorageBulkDeleteResult, type BrowserStorageDownloadResult, type BrowserStorageItem, type BrowserStorageListResult, type BrowserStorageSignedUrlResult, type BrowserStorageUploadResult, CollectionDeleteBuilder, type CollectionField, type CollectionFilterOp, CollectionInsertChain, type CollectionListResult, CollectionMutationReturning, type CollectionRecordEnvelope, type CollectionRequestFn, type CollectionReturnMode, type CollectionRow, type CollectionRowData, type CollectionRowWithMeta, CollectionSelectBuilder, type CollectionSelectOptions, type CollectionSelectedAggregate, type CollectionSelectedEmbed, CollectionUpdateBuilder, CollectionUpsertBuilder, type CollectionUpsertOptions, type CollectionUpsertSummary, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type DefaultRagableFunctions, type FinishReason, type FunctionInvoker, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type Json, type JsonSchema, LocalStorageAdapter, type MailMessageDetail, type MailMessagePreview, type MailSearchParams, type MailSendParams, type MailSendResult, MemoryStorageAdapter, type Message, type ParsedSelectExpression, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAiClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, RagableBrowserFunctionsClient, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, type RagableFunctionCall, type RagableFunctionContext, type RagableFunctionHandler, type RagableFunctionInvokeOptions, type RagableFunctions, RagableNetworkError, type RagableResult, RagableSdkError, RagableServerClient, type RagableServerClientConfig, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type ServerPrivilege, type SessionStorage, SessionStorageAdapter, type SseJsonEvent, type StreamObjectParams, type StreamObjectResult, type StreamPart, type StreamTextParams, type StreamTextResult, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createServerClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseOrString, parseSelectExpression, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };