@ragable/sdk 0.5.0 → 0.5.1

package/dist/index.d.mts

@@ -72,6 +72,8 @@ type TableUpdatePatch<D extends RagableDatabase, T extends RagableTableNames<D>>
  * or the browser throws **Illegal invocation**. Use this for defaults and for `options.fetch`.
  */
 declare function bindFetch(custom?: typeof fetch): typeof fetch;
+/** Default hosted API (`…/api`) when `baseUrl` is omitted (browser + server clients). */
+declare const DEFAULT_RAGABLE_API_BASE = "https://ragable-341305259977.asia-southeast1.run.app/api";
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -449,7 +451,13 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     upsert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], options: PostgrestUpsertOptions): PostgrestUpsertRootBuilder<TableRow<Database, TableName>>;
 }
 
+/**
+ * Ensures the browser SDK hits `/api/...` routes. Accepts either `https://host` or `https://host/api`
+ * (same rule as two-arg `createClient(url, opts)` from the package entry).
+ */
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
+/** How {@link RagableBrowserDatabaseClient.query} and `.from()` send `Authorization`. */
+type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
 interface RagableBrowserClientOptions {
     /** Organization id (UUID) — public agent chat URLs. */
     organizationId: string;
@@ -462,14 +470,27 @@ interface RagableBrowserClientOptions {
      * Default Backspace SQL instance id for {@link RagableBrowser.from} (Supabase-style table API).
      */
     databaseInstanceId?: string;
+    /**
+     * Database SQL auth. Default `user`: Bearer = JWT from {@link getAccessToken}.
+     * `publicAnon`: Bearer = public anon key (read-only SQL only). `admin`: Bearer = data admin key
+     * (same SQL rules as a logged-in user; **never** expose in browser bundles).
+     */
+    dataAuth?: BrowserDataAuthMode;
+    /**
+     * Static key when {@link dataAuth} is `publicAnon` or `admin` (e.g. `import.meta.env.VITE_…`).
+     * Ignored when {@link getDataStaticKey} returns a non-empty string.
+     */
+    dataStaticKey?: string;
+    /** Load anon/admin key at runtime; wins over {@link dataStaticKey} when non-empty. */
+    getDataStaticKey?: () => string | null | Promise<string | null>;
     /**
      * Returns the end-user access JWT (from login/register/refresh).
-     * Required for `auth.getMe`, `auth.updateMe`, and `database.query`.
+     * Required for `auth.getMe`, `auth.updateMe`, and for `database.query` when {@link dataAuth} is `user` (default).
      */
     getAccessToken?: () => string | null | Promise<string | null>;
     /**
      * API base URL including `/api`, e.g. `https://api.example.com/api`.
-     * @default "http://localhost:8080/api"
+     * @default `https://ragable-341305259977.asia-southeast1.run.app/api` ({@link DEFAULT_RAGABLE_API_BASE})
      */
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -739,4 +760,4 @@ declare function createClient<Database extends RagableDatabase = DefaultRagableD
  */
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-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, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RagableTableNames, 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 TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type Json, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RagableTableNames, 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 TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };

package/dist/index.d.ts

@@ -72,6 +72,8 @@ type TableUpdatePatch<D extends RagableDatabase, T extends RagableTableNames<D>>
  * or the browser throws **Illegal invocation**. Use this for defaults and for `options.fetch`.
  */
 declare function bindFetch(custom?: typeof fetch): typeof fetch;
+/** Default hosted API (`…/api`) when `baseUrl` is omitted (browser + server clients). */
+declare const DEFAULT_RAGABLE_API_BASE = "https://ragable-341305259977.asia-southeast1.run.app/api";
 interface RagableClientOptions {
     apiKey: string;
     baseUrl?: string;
@@ -449,7 +451,13 @@ declare class PostgrestTableApi<Database extends RagableDatabase = DefaultRagabl
     upsert(values: TableInsertRow<Database, TableName> | TableInsertRow<Database, TableName>[], options: PostgrestUpsertOptions): PostgrestUpsertRootBuilder<TableRow<Database, TableName>>;
 }
 
+/**
+ * Ensures the browser SDK hits `/api/...` routes. Accepts either `https://host` or `https://host/api`
+ * (same rule as two-arg `createClient(url, opts)` from the package entry).
+ */
 declare function normalizeBrowserApiBase(baseUrl?: string): string;
+/** How {@link RagableBrowserDatabaseClient.query} and `.from()` send `Authorization`. */
+type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
 interface RagableBrowserClientOptions {
     /** Organization id (UUID) — public agent chat URLs. */
     organizationId: string;
@@ -462,14 +470,27 @@ interface RagableBrowserClientOptions {
      * Default Backspace SQL instance id for {@link RagableBrowser.from} (Supabase-style table API).
      */
     databaseInstanceId?: string;
+    /**
+     * Database SQL auth. Default `user`: Bearer = JWT from {@link getAccessToken}.
+     * `publicAnon`: Bearer = public anon key (read-only SQL only). `admin`: Bearer = data admin key
+     * (same SQL rules as a logged-in user; **never** expose in browser bundles).
+     */
+    dataAuth?: BrowserDataAuthMode;
+    /**
+     * Static key when {@link dataAuth} is `publicAnon` or `admin` (e.g. `import.meta.env.VITE_…`).
+     * Ignored when {@link getDataStaticKey} returns a non-empty string.
+     */
+    dataStaticKey?: string;
+    /** Load anon/admin key at runtime; wins over {@link dataStaticKey} when non-empty. */
+    getDataStaticKey?: () => string | null | Promise<string | null>;
     /**
      * Returns the end-user access JWT (from login/register/refresh).
-     * Required for `auth.getMe`, `auth.updateMe`, and `database.query`.
+     * Required for `auth.getMe`, `auth.updateMe`, and for `database.query` when {@link dataAuth} is `user` (default).
      */
     getAccessToken?: () => string | null | Promise<string | null>;
     /**
      * API base URL including `/api`, e.g. `https://api.example.com/api`.
-     * @default "http://localhost:8080/api"
+     * @default `https://ragable-341305259977.asia-southeast1.run.app/api` ({@link DEFAULT_RAGABLE_API_BASE})
      */
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -739,4 +760,4 @@ declare function createClient<Database extends RagableDatabase = DefaultRagableD
  */
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-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, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RagableTableNames, 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 TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type Json, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableRequestClient, type RagableTableDefinition, type RagableTableNames, 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 TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, extractErrorMessage, formatRetrievalContext, normalizeBrowserApiBase, parseSseDataLine, readSseStream };

package/dist/index.js

@@ -23,6 +23,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var index_exports = {};
 __export(index_exports, {
   AgentsClient: () => AgentsClient,
+  DEFAULT_RAGABLE_API_BASE: () => DEFAULT_RAGABLE_API_BASE,
   PostgrestDeleteReturningBuilder: () => PostgrestDeleteReturningBuilder,
   PostgrestDeleteRootBuilder: () => PostgrestDeleteRootBuilder,
   PostgrestInsertReturningBuilder: () => PostgrestInsertReturningBuilder,
@@ -63,6 +64,7 @@ function bindFetch(custom) {
     return f.call(globalThis, input, init);
   };
 }
+var DEFAULT_RAGABLE_API_BASE = "https://ragable-341305259977.asia-southeast1.run.app/api";
 var RagableError = class extends Error {
   constructor(message, status, body) {
     super(message);
@@ -94,7 +96,7 @@ var RagableRequestClient = class {
     __publicField(this, "fetchImpl");
     __publicField(this, "defaultHeaders");
     this.apiKey = options.apiKey;
-    this.baseUrl = options.baseUrl ?? "http://localhost:8080/api";
+    this.baseUrl = options.baseUrl ?? DEFAULT_RAGABLE_API_BASE;
     this.fetchImpl = bindFetch(options.fetch);
     this.defaultHeaders = options.headers;
   }
@@ -1161,7 +1163,8 @@ var PostgrestTableApi = class {
 
 // src/browser.ts
 function normalizeBrowserApiBase(baseUrl) {
-  return (baseUrl ?? "http://localhost:8080/api").replace(/\/+$/, "");
+  const trimmed = (baseUrl ?? DEFAULT_RAGABLE_API_BASE).trim().replace(/\/+$/, "");
+  return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
 }
 function requireAuthGroupId(options) {
   const id = options.authGroupId?.trim();
@@ -1185,6 +1188,20 @@ async function requireAccessToken(options) {
   }
   return token.trim();
 }
+async function resolveDatabaseAuthBearer(options) {
+  const mode = options.dataAuth ?? "user";
+  if (mode === "user") {
+    return requireAccessToken(options);
+  }
+  const fromGetter = options.getDataStaticKey ? await options.getDataStaticKey() : null;
+  const key = (fromGetter?.trim() || options.dataStaticKey?.trim()) ?? "";
+  if (!key) {
+    throw new Error(
+      mode === "publicAnon" ? "dataAuth publicAnon requires getDataStaticKey or dataStaticKey (rotate key in dashboard)" : "dataAuth admin requires getDataStaticKey or dataStaticKey (server-side only; rotate in dashboard)"
+    );
+  }
+  return key;
+}
 async function parseJsonOrThrow(response) {
   const payload = await parseMaybeJsonBody(response);
   if (!response.ok) {
@@ -1354,7 +1371,7 @@ var RagableBrowserDatabaseClient = class {
   }
   async query(params) {
     const gid = requireAuthGroupId(this.options);
-    const token = await requireAccessToken(this.options);
+    const token = await resolveDatabaseAuthBearer(this.options);
     const databaseInstanceId = params.databaseInstanceId?.trim() || this.options.databaseInstanceId?.trim();
     if (!databaseInstanceId) {
       throw new Error(
@@ -1364,6 +1381,7 @@ var RagableBrowserDatabaseClient = class {
     const headers = this.baseHeaders();
     headers.set("Authorization", `Bearer ${token}`);
     headers.set("Content-Type", "application/json");
+    const readOnly = (this.options.dataAuth ?? "user") === "publicAnon" ? true : params.readOnly !== false;
     const response = await this.fetchImpl(
       this.toUrl(`/auth-groups/${gid}/data/query`),
       {
@@ -1373,7 +1391,7 @@ var RagableBrowserDatabaseClient = class {
           databaseInstanceId,
           sql: params.sql,
           ...params.params !== void 0 ? { params: params.params } : {},
-          ...params.readOnly === false ? { readOnly: false } : {},
+          readOnly,
           ...params.timeoutMs !== void 0 ? { timeoutMs: params.timeoutMs } : {},
           ...params.rowLimit !== void 0 ? { rowLimit: params.rowLimit } : {}
         })
@@ -1549,6 +1567,7 @@ function createRagableServerClient(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentsClient,
+  DEFAULT_RAGABLE_API_BASE,
   PostgrestDeleteReturningBuilder,
   PostgrestDeleteRootBuilder,
   PostgrestInsertReturningBuilder,