@ragable/sdk 0.0.3 → 0.4.0

package/dist/index.d.ts

@@ -1,3 +1,59 @@
+/**
+ * Supabase-style schema types for `createBrowserClient<Database>()`.
+ * Define `Row` (and optionally `Insert` / `Update`) per table, then use
+ * `Tables<Database, 'my_table'>` with `database.query<...>()`.
+ *
+ * @see https://supabase.com/docs/reference/javascript/typescript-support
+ */
+/** JSON-serializable values (matches common Supabase `Json` definition). */
+type Json = string | number | boolean | null | {
+    [key: string]: Json | undefined;
+} | Json[];
+/** One table’s type bundle — at minimum provide `Row`. */
+type RagableTableDefinition<Row extends Record<string, unknown> = Record<string, unknown>, Insert extends Record<string, unknown> = Row, Update extends Record<string, unknown> = Partial<Row>> = {
+    Row: Row;
+    Insert?: Insert;
+    Update?: Update;
+    Relationships?: unknown;
+};
+/**
+ * Top-level database shape (Supabase `Database` pattern).
+ * Consumers extend `public.Tables` with table names → {@link RagableTableDefinition}.
+ */
+interface RagableDatabase {
+    public: {
+        Tables: Record<string, RagableTableDefinition>;
+        Views?: Record<string, {
+            Row: Record<string, unknown>;
+        }>;
+        Enums?: Record<string, string>;
+    };
+}
+/**
+ * Default schema when no generic is passed to `createBrowserClient`.
+ * `Record<string, never>` for `Tables` is assignable to `Record<string, RagableTableDefinition>`;
+ * use `database.query<YourRow>()` or pass a concrete `Database` generic.
+ */
+interface DefaultRagableDatabase extends RagableDatabase {
+    public: {
+        Tables: Record<string, never>;
+        Views: Record<string, never>;
+        Enums: Record<string, never>;
+    };
+}
+/** Row type for a table name (Supabase `Tables<'x'>` pattern). */
+type Tables<D extends RagableDatabase, TableName extends keyof D["public"]["Tables"] & string> = [D["public"]["Tables"][TableName]] extends [never] ? Record<string, unknown> : D["public"]["Tables"][TableName] extends {
+    Row: infer R;
+} ? R extends Record<string, unknown> ? R : Record<string, unknown> : Record<string, unknown>;
+/** Insert payload type when declared; otherwise a partial of `Row`. */
+type TablesInsert<D extends RagableDatabase, TableName extends keyof D["public"]["Tables"] & string> = [D["public"]["Tables"][TableName]] extends [never] ? Record<string, unknown> : D["public"]["Tables"][TableName] extends {
+    Insert: infer I;
+} ? I extends Record<string, unknown> ? I : Record<string, unknown> : Partial<Tables<D, TableName>>;
+/** Update payload type when declared; otherwise partial `Row`. */
+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>>;
+
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -166,6 +222,318 @@ declare class AgentsClient {
     chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
 
+/** Shared with {@link RagableBrowserDatabaseClient.query} — duplicated to avoid circular imports. */
+interface BrowserSqlExecParams {
+    databaseInstanceId: string;
+    sql: string;
+    params?: unknown[];
+    readOnly?: boolean;
+    timeoutMs?: number;
+    rowLimit?: number;
+}
+interface BrowserSqlExecResult<Row extends Record<string, unknown> = Record<string, unknown>> {
+    command: string;
+    rowCount: number;
+    truncated: boolean;
+    rows: Row[];
+}
+type PostgrestResult<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: RagableError;
+};
+/** Map async throws to `{ data, error }` like Supabase JS client. */
+declare function asPostgrestResponse<T>(fn: () => Promise<T>): Promise<PostgrestResult<T>>;
+type RunQuery = <R extends Record<string, unknown> = Record<string, unknown>>(p: BrowserSqlExecParams) => Promise<BrowserSqlExecResult<R>>;
+/** Supabase/PostgREST-style read builder: `.from('t').select().eq().single()` */
+declare class PostgrestSelectBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly columns;
+    private filters;
+    private _limit?;
+    private _order?;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, columns: string);
+    eq(column: string, value: unknown): this;
+    neq(column: string, value: unknown): this;
+    gt(column: string, value: unknown): this;
+    gte(column: string, value: unknown): this;
+    lt(column: string, value: unknown): this;
+    lte(column: string, value: unknown): this;
+    like(column: string, value: unknown): this;
+    ilike(column: string, value: unknown): this;
+    limit(n: number): this;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): this;
+    /** @param includeUserLimit when false, omit `.limit()` (for `.single()` / `.maybeSingle()`). */
+    private buildSelectCore;
+    then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private executeMany;
+    single(): Promise<PostgrestResult<Row>>;
+    maybeSingle(): Promise<PostgrestResult<Row | null>>;
+}
+declare class PostgrestInsertBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly rows;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, rows: Record<string, unknown>[]);
+    select(columns?: string): this;
+    then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
+declare class PostgrestUpdateBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private readonly patch;
+    private filters;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string, patch: Record<string, unknown>);
+    eq(column: string, value: unknown): this;
+    select(columns?: string): this;
+    then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
+declare class PostgrestDeleteBuilder<Row extends Record<string, unknown> = Record<string, unknown>> implements PromiseLike<PostgrestResult<Row[]>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    private filters;
+    private returning;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string);
+    eq(column: string, value: unknown): this;
+    select(columns?: string): this;
+    then<TResult1 = PostgrestResult<Row[]>, TResult2 = never>(onfulfilled?: ((value: PostgrestResult<Row[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
+declare class PostgrestTableApi<Row extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly run;
+    private readonly databaseInstanceId;
+    private readonly table;
+    constructor(run: RunQuery, databaseInstanceId: string, table: string);
+    select(columns?: string): PostgrestSelectBuilder<Row>;
+    insert(values: Record<string, unknown> | Record<string, unknown>[]): PostgrestInsertBuilder<Row>;
+    update(patch: Record<string, unknown>): PostgrestUpdateBuilder<Row>;
+    delete(): PostgrestDeleteBuilder<Row>;
+}
+
+declare function normalizeBrowserApiBase(baseUrl?: string): string;
+interface RagableBrowserClientOptions {
+    /** Organization id (UUID) — public agent chat URLs. */
+    organizationId: string;
+    /**
+     * Authentication group id when using {@link RagableBrowserAuthClient} or
+     * {@link RagableBrowserDatabaseClient}.
+     */
+    authGroupId?: string;
+    /**
+     * Default Backspace SQL instance id for {@link RagableBrowser.from} (Supabase-style table API).
+     */
+    databaseInstanceId?: string;
+    /**
+     * Returns the end-user access JWT (from login/register/refresh).
+     * Required for `auth.getMe`, `auth.updateMe`, and `database.query`.
+     */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /**
+     * API base URL including `/api`, e.g. `https://api.example.com/api`.
+     * @default "http://localhost:8080/api"
+     */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+/** Successful register/login response (typed `user` via `AuthUser` generic). */
+interface BrowserAuthSession<AuthUser extends Record<string, unknown> = Record<string, unknown>> {
+    user: AuthUser;
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: string;
+}
+interface BrowserAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: string;
+}
+/** Supabase-compatible session shape (snake_case tokens). */
+interface SupabaseCompatSession<AuthUser extends Record<string, unknown> = Record<string, unknown>> {
+    access_token: string;
+    refresh_token: string;
+    /** Best-effort seconds from Ragable `expiresIn` (e.g. `7d`, `3600`). */
+    expires_in: number;
+    token_type: "bearer";
+    user: AuthUser;
+}
+
+/** End-user auth — Ragable names + Supabase/Firebase-style aliases returning `{ data, error }`. */
+declare class RagableBrowserAuthClient<AuthUser extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly options;
+    constructor(options: RagableBrowserClientOptions);
+    private get fetchImpl();
+    private toUrl;
+    private baseHeaders;
+    private authPrefix;
+    /** Supabase: `signUp` → `{ data: { user, session }, error }` */
+    signUp(credentials: {
+        email: string;
+        password: string;
+        options?: {
+            data?: Record<string, unknown>;
+        };
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+        session: SupabaseCompatSession<AuthUser>;
+    }>>;
+    /** Supabase: `signInWithPassword` */
+    signInWithPassword(credentials: {
+        email: string;
+        password: string;
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+        session: SupabaseCompatSession<AuthUser>;
+    }>>;
+    /** Supabase: `refreshSession` */
+    refreshSession(refreshToken: string): Promise<PostgrestResult<{
+        session: SupabaseCompatSession<AuthUser>;
+        user: AuthUser;
+    }>>;
+    /** Supabase: `getUser()` — needs `getAccessToken` on the client */
+    getUser(): Promise<PostgrestResult<{
+        user: AuthUser;
+    }>>;
+    /** Supabase: `updateUser` */
+    updateUser(attributes: {
+        email?: string;
+        password?: string;
+        data?: {
+            name?: string | null;
+        };
+    }): Promise<PostgrestResult<{
+        user: AuthUser;
+    }>>;
+    /**
+     * Supabase/Firebase: no server call — clear tokens in your app.
+     * Returns `{ error: null }` for API compatibility.
+     */
+    signOut(_options?: {
+        scope?: "global" | "local";
+    }): Promise<{
+        error: null;
+    }>;
+    private getUserFromToken;
+    register(body: {
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<BrowserAuthSession<AuthUser>>;
+    login(body: {
+        email: string;
+        password: string;
+    }): Promise<BrowserAuthSession<AuthUser>>;
+    refresh(body: {
+        refreshToken: string;
+    }): Promise<BrowserAuthTokens>;
+    getMe(): Promise<{
+        user: AuthUser;
+    }>;
+    updateMe(body: {
+        name?: string | null;
+        password?: string;
+    }): Promise<{
+        user: AuthUser;
+    }>;
+}
+interface BrowserSqlQueryParams {
+    databaseInstanceId: string;
+    sql: string;
+    params?: unknown[];
+    /**
+     * Default `true`. When `false`, the API allows INSERT/UPDATE/DELETE (and existing safe reads);
+     * DDL (`CREATE`/`DROP`/`ALTER`/…) and privilege changes remain blocked.
+     */
+    readOnly?: boolean;
+    timeoutMs?: number;
+    rowLimit?: number;
+}
+interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<string, unknown>> {
+    command: string;
+    rowCount: number;
+    truncated: boolean;
+    rows: Row[];
+}
+/**
+ * Raw SQL against linked Postgres (escape hatch). Prefer {@link RagableBrowser.from} for
+ * Supabase-style `.select()` / `.insert()` / `.update()` / `.delete()`.
+ */
+declare class RagableBrowserDatabaseClient<_Schema extends RagableDatabase = DefaultRagableDatabase> {
+    private readonly options;
+    constructor(options: RagableBrowserClientOptions);
+    private get fetchImpl();
+    private toUrl;
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams): Promise<BrowserSqlQueryResult<Row>>;
+    private baseHeaders;
+}
+/**
+ * Browser-safe client: **no org API key**. Uses public routes and end-user JWTs
+ * from {@link RagableBrowserAuthClient}.
+ */
+declare class RagableBrowserAgentsClient {
+    private readonly options;
+    constructor(options: RagableBrowserClientOptions);
+    private get fetchImpl();
+    private toUrl;
+    /**
+     * Stream agent execution as SSE (`POST /public/organizations/:orgId/agents/:agentId/chat/stream`).
+     */
+    chatStream(agentId: string, params: AgentPublicChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
+}
+/** Public chat params — same shape as {@link AgentChatParams} plus optional trigger fields. */
+interface AgentPublicChatParams extends AgentChatParams {
+    triggerSubtype?: string;
+    triggerNodeId?: string;
+}
+/**
+ * Browser client: mirrors **Supabase JS** (`createClient`, `.from()`, `.auth.signInWithPassword`, `{ data, error }`)
+ * plus Ragable **`agents.chatStream`**. Server secrets: {@link createRagableServerClient} / {@link createClient} with `apiKey`.
+ */
+declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>> {
+    readonly agents: RagableBrowserAgentsClient;
+    readonly auth: RagableBrowserAuthClient<AuthUser>;
+    readonly database: RagableBrowserDatabaseClient<Database>;
+    private readonly options;
+    constructor(options: RagableBrowserClientOptions);
+    /**
+     * Supabase-style table API: `.from('items').select().eq('id', 1).single()`.
+     * Pass `databaseInstanceId` here or set `databaseInstanceId` on the client options.
+     */
+    from<Row extends Record<string, unknown> = Record<string, unknown>>(table: string, databaseInstanceId?: string): PostgrestTableApi<Row>;
+}
+/**
+ * **Supabase-equivalent** browser client factory (no org API key).
+ * Same as {@link createRagableBrowserClient}.
+ */
+declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
+/** Alias for {@link createBrowserClient} — matches Supabase `createClient` naming. */
+declare const createRagableBrowserClient: typeof createBrowserClient;
+
+/**
+ * Shared SSE parsing for `data: {json}` lines (Ragable agent streams).
+ */
+type SseJsonEvent = Record<string, unknown> & {
+    type: string;
+};
+declare function parseSseDataLine(line: string): SseJsonEvent | null;
+/**
+ * Read an SSE body and yield parsed `data:` JSON objects (double-newline framed).
+ */
+declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<SseJsonEvent, void, undefined>;
+
 /** Minimal client surface for {@link createRagPipeline} (implemented by {@link Ragable}). */
 interface RagClientForPipeline {
     shift: {
@@ -225,6 +593,20 @@ declare class Ragable {
     };
     constructor(options: RagableClientOptions);
 }
+/**
+ * **Supabase-style overloads**
+ * - `createClient(RAGABLE_URL, { organizationId, authGroupId, … })` — browser (no API key)
+ * - `createClient({ apiKey, baseUrl })` — server / Engine (secret key)
+ *
+ * Prefer {@link createRagableServerClient} in backend code if the dual overload is confusing.
+ */
+declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(url: string, options: Omit<RagableBrowserClientOptions, "baseUrl">): RagableBrowser<Database, AuthUser>;
 declare function createClient(options: RagableClientOptions): Ragable;
+declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
+/**
+ * Explicit **server** factory — same as `createClient({ apiKey, baseUrl })`.
+ * Use in the Engine; never import alongside browser `createClient(url, …)` if you want tree-shaking clarity.
+ */
+declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentStreamEvent, type AgentSummary, AgentsClient, type FormatContextOptions, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, type RagableClientOptions, RagableError, RagableRequestClient, type RequestOptions, type RetrieveParams, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext };
+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, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };