@ragable/sdk 0.0.3 → 0.3.0

package/dist/index.d.mts

@@ -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,151 @@ declare class AgentsClient {
     chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
 
+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;
+    /**
+     * 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;
+}
+/** End-user auth (email/password) for a linked authentication group — no org API key. */
+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;
+    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[];
+    /** Ignored — the API only allows safe read-only SQL for end users. */
+    readOnly?: true;
+    timeoutMs?: number;
+    rowLimit?: number;
+}
+interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<string, unknown>> {
+    command: string;
+    rowCount: number;
+    truncated: boolean;
+    rows: Row[];
+}
+/**
+ * Run SQL against a Postgres instance linked to a website that uses the same `authGroupId`,
+ * authenticated as the signed-in end-user (access token).
+ *
+ * Pass `createBrowserClient<YourDatabase>()` and use `query<Tables<YourDatabase, 't'>>()`
+ * for Supabase-style row typing.
+ */
+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 root. Use `createBrowserClient<Database, AuthUser>()` for Supabase-style
+ * typing on {@link RagableBrowserDatabaseClient.query} and auth `user` payloads.
+ */
+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>;
+    constructor(options: RagableBrowserClientOptions);
+}
+/**
+ * Browser client: **no org `ragable_*` API key**.
+ * - {@link RagableBrowser.agents} — public agent SSE.
+ * - {@link RagableBrowser.auth} / {@link RagableBrowser.database} — need `authGroupId` (+ `getAccessToken` for protected calls).
+ *
+ * Pass schema and user types like Supabase: `createBrowserClient<Database, AuthUser>({ ... })`.
+ * For Shift and `/v1/*`, use {@link createClient} on a server.
+ */
+declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
+
+/**
+ * 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 +426,11 @@ declare class Ragable {
     };
     constructor(options: RagableClientOptions);
 }
+/**
+ * Server-side client with your **secret** `ragable_*` API key.
+ * Use from Node, Edge, or your Engine — never in browser bundles.
+ * For public agent streaming from the browser without a key, use {@link createBrowserClient}.
+ */
 declare function createClient(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 BrowserSqlQueryParams, type BrowserSqlQueryResult, type DefaultRagableDatabase, type FormatContextOptions, type Json, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RequestOptions, type RetrieveParams, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type Tables, type TablesInsert, type TablesUpdate, createBrowserClient, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };

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,151 @@ declare class AgentsClient {
     chatStream(agentId: string, params: AgentChatParams): AsyncGenerator<AgentStreamEvent, void, undefined>;
 }
 
+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;
+    /**
+     * 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;
+}
+/** End-user auth (email/password) for a linked authentication group — no org API key. */
+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;
+    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[];
+    /** Ignored — the API only allows safe read-only SQL for end users. */
+    readOnly?: true;
+    timeoutMs?: number;
+    rowLimit?: number;
+}
+interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<string, unknown>> {
+    command: string;
+    rowCount: number;
+    truncated: boolean;
+    rows: Row[];
+}
+/**
+ * Run SQL against a Postgres instance linked to a website that uses the same `authGroupId`,
+ * authenticated as the signed-in end-user (access token).
+ *
+ * Pass `createBrowserClient<YourDatabase>()` and use `query<Tables<YourDatabase, 't'>>()`
+ * for Supabase-style row typing.
+ */
+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 root. Use `createBrowserClient<Database, AuthUser>()` for Supabase-style
+ * typing on {@link RagableBrowserDatabaseClient.query} and auth `user` payloads.
+ */
+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>;
+    constructor(options: RagableBrowserClientOptions);
+}
+/**
+ * Browser client: **no org `ragable_*` API key**.
+ * - {@link RagableBrowser.agents} — public agent SSE.
+ * - {@link RagableBrowser.auth} / {@link RagableBrowser.database} — need `authGroupId` (+ `getAccessToken` for protected calls).
+ *
+ * Pass schema and user types like Supabase: `createBrowserClient<Database, AuthUser>({ ... })`.
+ * For Shift and `/v1/*`, use {@link createClient} on a server.
+ */
+declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
+
+/**
+ * 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 +426,11 @@ declare class Ragable {
     };
     constructor(options: RagableClientOptions);
 }
+/**
+ * Server-side client with your **secret** `ragable_*` API key.
+ * Use from Node, Edge, or your Engine — never in browser bundles.
+ * For public agent streaming from the browser without a key, use {@link createBrowserClient}.
+ */
 declare function createClient(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 BrowserSqlQueryParams, type BrowserSqlQueryResult, type DefaultRagableDatabase, type FormatContextOptions, type Json, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RequestOptions, type RetrieveParams, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type Tables, type TablesInsert, type TablesUpdate, createBrowserClient, createClient, createRagPipeline, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };