@ragable/sdk 0.0.2 → 0.3.0

package/dist/index.d.ts

@@ -1,9 +1,89 @@
+/**
+ * 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;
     fetch?: typeof fetch;
     headers?: HeadersInit;
 }
+type RequestOptions = Omit<RequestInit, "body"> & {
+    body?: unknown;
+};
+declare class RagableError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare function extractErrorMessage(payload: unknown, fallback: string): string;
+declare class RagableRequestClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(options: RagableClientOptions);
+    toUrl(path: string): string;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Low-level fetch with API key and JSON body encoding. Caller handles status and body.
+     */
+    rawFetch(path: string, options?: RequestOptions): Promise<Response>;
+    private parseResponseBody;
+}
+
 interface ShiftIndex {
     id: string;
     name: string;
@@ -70,24 +150,6 @@ interface ShiftListEntriesResponse {
     entries: ShiftEntry[];
     total: number;
 }
-declare class RagableError extends Error {
-    readonly status: number;
-    readonly body: unknown;
-    constructor(message: string, status: number, body: unknown);
-}
-type RequestOptions = Omit<RequestInit, "body"> & {
-    body?: unknown;
-};
-declare class RagableRequestClient {
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly fetchImpl;
-    private readonly defaultHeaders;
-    constructor(options: RagableClientOptions);
-    request<T>(path: string, options?: RequestOptions): Promise<T>;
-    private toUrl;
-    private parseResponseBody;
-}
 declare class ShiftClient {
     private readonly client;
     readonly indexes: {
@@ -116,13 +178,259 @@ declare class ShiftClient {
         results: ShiftSearchResult[];
     }>;
 }
+
+interface AgentSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface AgentChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface AgentChatParams {
+    message: string;
+    history?: AgentChatMessage[];
+}
+/** Mirrors backend ExecutionResult JSON shape (traces are opaque in the SDK). */
+interface AgentChatResult {
+    response: string;
+    traces: unknown[];
+    totalDurationMs: number;
+    httpResponse?: unknown;
+}
+/**
+ * Loose SSE event from POST /v1/agents/:id/chat/stream — narrows with `type` at runtime.
+ */
+type AgentStreamEvent = Record<string, unknown> & {
+    type: string;
+};
+declare class AgentsClient {
+    private readonly client;
+    constructor(client: RagableRequestClient);
+    list(): Promise<{
+        agents: AgentSummary[];
+    }>;
+    get(agentId: string): Promise<AgentSummary>;
+    chat(agentId: string, params: AgentChatParams): Promise<AgentChatResult>;
+    /**
+     * Stream agent execution as SSE (`data: {json}` lines). Yields parsed JSON objects.
+     */
+    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: {
+        documents: {
+            create: (indexId: string, params: ShiftAddDocumentParams) => Promise<ShiftIngestResponse>;
+            upload: (indexId: string, params: ShiftUploadFileParams) => Promise<ShiftIngestResponse>;
+        };
+        search: (indexId: string, params: ShiftSearchParams) => Promise<{
+            results: ShiftSearchResult[];
+        }>;
+    };
+}
+interface FormatContextOptions {
+    /** Prepended before numbered passages (default: "Relevant passages:\\n") */
+    header?: string;
+    /** Joiner between passages (default: "\\n\\n") */
+    separator?: string;
+    /** Omit results with similarity score below this (default: no filter) */
+    minScore?: number;
+    /** Truncate total context string to this UTF-16 length (default: no limit) */
+    maxChars?: number;
+    /** Include similarity score in each block (default: false) */
+    includeScores?: boolean;
+}
+interface RagPipelineOptions {
+    indexId: string;
+}
+type RetrieveParams = ShiftSearchParams & {
+    format?: FormatContextOptions;
+};
+interface RagPipeline {
+    readonly indexId: string;
+    ingestText(params: ShiftAddDocumentParams): Promise<ShiftIngestResponse>;
+    ingestFile(params: ShiftUploadFileParams): Promise<ShiftIngestResponse>;
+    search(params: ShiftSearchParams): Promise<{
+        results: ShiftSearchResult[];
+    }>;
+    retrieve(params: RetrieveParams): Promise<{
+        results: ShiftSearchResult[];
+        context: string;
+    }>;
+}
+/**
+ * Turn vector search hits into a single block of text for system prompts or RAG user messages.
+ */
+declare function formatRetrievalContext(results: ShiftSearchResult[], options?: FormatContextOptions): string;
+/**
+ * High-level RAG helpers bound to one Shift index: ingest, search, retrieve with prompt-ready context.
+ */
+declare function createRagPipeline(client: RagClientForPipeline, options: RagPipelineOptions): RagPipeline;
+
 declare class Ragable {
     readonly shift: ShiftClient;
+    readonly agents: AgentsClient;
     readonly infrastructure: {
         shift: ShiftClient;
     };
     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 { Ragable, type RagableClientOptions, RagableError, type ShiftAddDocumentParams, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, createClient };
+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 };