@ragable/sdk 0.6.1 → 0.6.3

package/dist/index.d.mts

@@ -100,7 +100,11 @@ declare class RagableError extends RagableSdkError {
     readonly details: string | undefined;
     constructor(message: string, status: number, body: unknown);
     toJSON(): Record<string, unknown>;
+    /** Stable string for logs — avoids `{}` when coercing or stringifying. */
+    toString(): string;
 }
+/** Safe one-line log for any thrown value (catch blocks, TanStack Query). */
+declare function formatSdkError(err: unknown): string;
 declare class RagableNetworkError extends RagableSdkError {
     readonly __type: "RagableNetworkError";
     readonly cause: unknown;
@@ -484,7 +488,7 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     private readonly table;
     constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: TableName extends string ? string : string);
     select(columns?: string): PostgrestSelectBuilder<TableRow<Database, TableName>, Database, TableName>;
-    insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
+    insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], ...rest: unknown[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
     update(patch: TableUpdatePatch<Database, TableName>): PostgrestUpdateRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     delete(): PostgrestDeleteRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     upsert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], options: PostgrestUpsertOptions): PostgrestUpsertRootBuilder<TableRow<Database, TableName>>;
@@ -863,11 +867,17 @@ interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<str
     truncated: boolean;
     rows: Row[];
 }
-declare class RagableBrowserDatabaseClient<_Schema extends RagableDatabase = DefaultRagableDatabase> {
+declare class RagableBrowserDatabaseClient<Database extends RagableDatabase = DefaultRagableDatabase> {
     private readonly options;
     private readonly ragableAuth;
+    private readonly postgrestFrom?;
     private readonly fetchImpl;
-    constructor(options: RagableBrowserClientOptions, ragableAuth?: RagableAuth | null);
+    constructor(options: RagableBrowserClientOptions, ragableAuth?: RagableAuth | null, postgrestFrom?: (<T extends RagableTableNames<Database>>(table: T, databaseInstanceId?: string) => PostgrestTableApi<Database, T>) | undefined);
+    /**
+     * PostgREST fluent API — same as `client.from('table')`.
+     * Use either the root client or `database` for Supabase-style table access; `database.query()` is raw SQL only.
+     */
+    from<TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string): PostgrestTableApi<Database, TableName>;
     private toUrl;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams): Promise<BrowserSqlQueryResult<Row>>;
     private baseHeaders;
@@ -973,4 +983,4 @@ 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>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, extractErrorMessage, formatRetrievalContext, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, extractErrorMessage, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };

package/dist/index.d.ts

@@ -100,7 +100,11 @@ declare class RagableError extends RagableSdkError {
     readonly details: string | undefined;
     constructor(message: string, status: number, body: unknown);
     toJSON(): Record<string, unknown>;
+    /** Stable string for logs — avoids `{}` when coercing or stringifying. */
+    toString(): string;
 }
+/** Safe one-line log for any thrown value (catch blocks, TanStack Query). */
+declare function formatSdkError(err: unknown): string;
 declare class RagableNetworkError extends RagableSdkError {
     readonly __type: "RagableNetworkError";
     readonly cause: unknown;
@@ -484,7 +488,7 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     private readonly table;
     constructor(pgFetch: PostgRESTFetch, databaseInstanceId: string, table: TableName extends string ? string : string);
     select(columns?: string): PostgrestSelectBuilder<TableRow<Database, TableName>, Database, TableName>;
-    insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
+    insert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], ...rest: unknown[]): PostgrestInsertRootBuilder<TableRow<Database, TableName>>;
     update(patch: TableUpdatePatch<Database, TableName>): PostgrestUpdateRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     delete(): PostgrestDeleteRootBuilder<TableRow<Database, TableName>, Database, TableName>;
     upsert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], options: PostgrestUpsertOptions): PostgrestUpsertRootBuilder<TableRow<Database, TableName>>;
@@ -863,11 +867,17 @@ interface BrowserSqlQueryResult<Row extends Record<string, unknown> = Record<str
     truncated: boolean;
     rows: Row[];
 }
-declare class RagableBrowserDatabaseClient<_Schema extends RagableDatabase = DefaultRagableDatabase> {
+declare class RagableBrowserDatabaseClient<Database extends RagableDatabase = DefaultRagableDatabase> {
     private readonly options;
     private readonly ragableAuth;
+    private readonly postgrestFrom?;
     private readonly fetchImpl;
-    constructor(options: RagableBrowserClientOptions, ragableAuth?: RagableAuth | null);
+    constructor(options: RagableBrowserClientOptions, ragableAuth?: RagableAuth | null, postgrestFrom?: (<T extends RagableTableNames<Database>>(table: T, databaseInstanceId?: string) => PostgrestTableApi<Database, T>) | undefined);
+    /**
+     * PostgREST fluent API — same as `client.from('table')`.
+     * Use either the root client or `database` for Supabase-style table access; `database.query()` is raw SQL only.
+     */
+    from<TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string): PostgrestTableApi<Database, TableName>;
     private toUrl;
     query<Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams): Promise<BrowserSqlQueryResult<Row>>;
     private baseHeaders;
@@ -973,4 +983,4 @@ 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>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, extractErrorMessage, formatRetrievalContext, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, extractErrorMessage, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };

package/dist/index.js

@@ -63,6 +63,7 @@ __export(index_exports, {
   detectStorage: () => detectStorage,
   extractErrorMessage: () => extractErrorMessage,
   formatRetrievalContext: () => formatRetrievalContext,
+  formatSdkError: () => formatSdkError,
   generateIdempotencyKey: () => generateIdempotencyKey,
   normalizeBrowserApiBase: () => normalizeBrowserApiBase,
   parseSseDataLine: () => parseSseDataLine,
@@ -114,7 +115,34 @@ var RagableError = class extends RagableSdkError {
       details: this.details
     };
   }
+  /** Stable string for logs — avoids `{}` when coercing or stringifying. */
+  toString() {
+    const bits = [`${this.name}: ${this.message}`];
+    if (this.status) bits.push(`status=${this.status}`);
+    if (this.code) bits.push(`code=${this.code}`);
+    return bits.join(" \xB7 ");
+  }
 };
+function formatSdkError(err) {
+  if (err instanceof RagableError) {
+    return `${err.message} (HTTP ${err.status}${err.code ? `, ${err.code}` : ""})`;
+  }
+  if (err instanceof RagableSdkError) {
+    return err.message;
+  }
+  if (err instanceof Error) {
+    return err.message || err.name;
+  }
+  if (typeof err === "string") return err;
+  if (err && typeof err === "object") {
+    try {
+      const s = JSON.stringify(err);
+      if (s !== "{}") return s;
+    } catch {
+    }
+  }
+  return String(err);
+}
 var RagableNetworkError = class extends RagableSdkError {
   constructor(message, cause) {
     super(message);
@@ -1445,7 +1473,14 @@ var PostgrestTableApi = class {
       columns
     );
   }
-  insert(values) {
+  insert(values, ...rest) {
+    if (rest.length > 0) {
+      throw new RagableError(
+        ".insert() accepts only one argument: the row object or an array of rows. Do not pass readOnly, options, or a second object \u2014 those apply only to database.query({ sql, readOnly }). PostgREST inserts are writes by default.",
+        400,
+        { code: "SDK_INSERT_EXTRA_ARGS" }
+      );
+    }
     const rows = Array.isArray(values) ? values : [values];
     return new PostgrestInsertRootBuilder(
       this.pgFetch,
@@ -2163,12 +2198,27 @@ var RagableBrowserAuthClient = class {
   }
 };
 var RagableBrowserDatabaseClient = class {
-  constructor(options, ragableAuth = null) {
+  constructor(options, ragableAuth = null, postgrestFrom) {
     this.options = options;
     this.ragableAuth = ragableAuth;
+    this.postgrestFrom = postgrestFrom;
     __publicField(this, "fetchImpl");
     this.fetchImpl = bindFetch(options.fetch);
   }
+  /**
+   * PostgREST fluent API — same as `client.from('table')`.
+   * Use either the root client or `database` for Supabase-style table access; `database.query()` is raw SQL only.
+   */
+  from(table, databaseInstanceId) {
+    if (!this.postgrestFrom) {
+      throw new RagableError(
+        "database.from() is only available on the client from createBrowserClient().",
+        500,
+        { code: "SDK_DATABASE_FROM_UNAVAILABLE" }
+      );
+    }
+    return this.postgrestFrom(table, databaseInstanceId);
+  }
   toUrl(path) {
     return `${normalizeBrowserApiBase(this.options.baseUrl)}${path.startsWith("/") ? path : `/${path}`}`;
   }
@@ -2282,7 +2332,11 @@ var RagableBrowser = class {
     }
     this.agents = new RagableBrowserAgentsClient(options);
     this.auth = new RagableBrowserAuthClient(options, this._ragableAuth);
-    this.database = new RagableBrowserDatabaseClient(options, this._ragableAuth);
+    this.database = new RagableBrowserDatabaseClient(
+      options,
+      this._ragableAuth,
+      (table, databaseInstanceId) => this.from(table, databaseInstanceId)
+    );
   }
   from(table, databaseInstanceId) {
     const id = databaseInstanceId?.trim() || this.options.databaseInstanceId?.trim();
@@ -2464,6 +2518,7 @@ function createRagableServerClient(options) {
   detectStorage,
   extractErrorMessage,
   formatRetrievalContext,
+  formatSdkError,
   generateIdempotencyKey,
   normalizeBrowserApiBase,
   parseSseDataLine,