@ragable/sdk 0.8.1 → 0.8.2

package/dist/index.d.mts

@@ -1279,6 +1279,106 @@ declare function streamObjectFromContext<T = unknown>(ctx: InferenceRequestConte
  */
 declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): StreamObjectResult<T>;
 
+/**
+ * Server-side client — the authenticated SDK for code that runs on a trusted
+ * server (a Ragable backend **function**, an Engine, or your own Node service).
+ *
+ * Unlike the browser client there is **no sign-in / session machinery** here:
+ * a server is not a logged-in user. Instead you provide credentials up front and
+ * the client speaks to the same Ragable data plane the browser uses, so the
+ * semantics (collection security, `{ data, error }` shapes, PostgREST) are
+ * identical — this reuses the exact same fetch-based sub-clients, never a
+ * reimplementation.
+ *
+ * Two privilege levels:
+ *  - **caller** (default): acts as the end user who invoked you — uses their
+ *    forwarded access token, falling back to the public anon key for anonymous
+ *    callers. Collection security applies, exactly as in the browser.
+ *  - **admin**: authenticates with the auth group's **data-admin key**, which
+ *    bypasses collection security (owner/group/claim grants do not apply) and
+ *    can write protected collections. Reach for it deliberately.
+ *
+ * ```ts
+ * // inside /functions/<name>.ts — `context.ragable` is a pre-built server client
+ * export default async function createTask(input, context) {
+ *   // as the caller (respects collection security):
+ *   const { data, error } = await context.ragable.db.collections.tasks.insert(input);
+ *   // privileged work (bypasses collection security):
+ *   await context.ragable.asAdmin().db.collections.audit_log.insert({ action: "create" });
+ *   return data;
+ * }
+ * ```
+ */
+
+/** Which credential a server client authenticates with. */
+type ServerPrivilege = "caller" | "admin";
+/**
+ * Inputs to {@link createServerClient}. The IDs and keys are normally supplied by
+ * the runtime (a function's injected `context.ragable`); construct one by hand
+ * only for a standalone server.
+ */
+interface RagableServerClientConfig {
+    organizationId: string;
+    websiteId?: string;
+    authGroupId?: string;
+    databaseInstanceId?: string;
+    storageBucketId?: string;
+    mailAccountId?: string;
+    /**
+     * The auth group's **data-admin key**. Required for `admin` privilege; omit it
+     * and `asAdmin()` throws. Server-only — never expose this to the browser.
+     */
+    adminKey?: string;
+    /**
+     * The invoking end user's access token (a real auth-group JWT), forwarded by
+     * the runtime. `null`/omitted for anonymous callers. Used by `caller`
+     * privilege; the public anon key is the fallback when this is absent.
+     */
+    callerToken?: string | null;
+    /** Public anon key — the `caller` fallback when no end user is signed in. */
+    publicAnonKey?: string;
+    /** Default privilege for the returned client. Defaults to `"caller"`. */
+    defaultPrivilege?: ServerPrivilege;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+/**
+ * A trusted, server-side Ragable client. Surface mirrors the browser client
+ * (`db`, `storage`, `mail`, `functions`, `ai`, `agents`) minus `auth` — a server
+ * authenticates with keys, not a session. Switch privilege with {@link asAdmin}
+ * / {@link asCaller}.
+ */
+declare class RagableServerClient<Database extends RagableDatabase = DefaultRagableDatabase, Functions extends RagableFunctions = DefaultRagableFunctions> {
+    private readonly config;
+    readonly database: RagableBrowserDatabaseClient<Database>;
+    readonly db: RagableBrowserDatabaseClient<Database>;
+    readonly storage: RagableBrowserStorageClient;
+    readonly mail: RagableBrowserMailClient;
+    readonly functions: FunctionInvoker<Functions>;
+    readonly ai: RagableBrowserAiClient;
+    readonly agents: RagableBrowserAgentsClient;
+    /** Which credential this client is using. */
+    readonly privilege: ServerPrivilege;
+    constructor(config: RagableServerClientConfig, privilege: ServerPrivilege);
+    /**
+     * A client authenticated with the **data-admin key** — bypasses collection
+     * security (owner/group/claim grants do not apply) and can write protected
+     * collections. Throws `SDK_ADMIN_KEY_REQUIRED` when no admin key is configured.
+     */
+    asAdmin(): RagableServerClient<Database, Functions>;
+    /**
+     * A client scoped to the invoking end user's identity (respects collection
+     * security). This is already the default; use it to drop back from `asAdmin()`.
+     */
+    asCaller(): RagableServerClient<Database, Functions>;
+}
+/**
+ * Create a server-side Ragable client. Defaults to **caller** privilege (acts as
+ * the invoking end user, respecting collection security); call `.asAdmin()` for
+ * privileged, security-bypassing access.
+ */
+declare function createServerClient<Database extends RagableDatabase = DefaultRagableDatabase, Functions extends RagableFunctions = DefaultRagableFunctions>(config: RagableServerClientConfig): RagableServerClient<Database, Functions>;
+
 /**
  * Backend "edge functions".
  *
@@ -1307,6 +1407,7 @@ declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): S
  * The handler's second argument (`context`) is injected by the server; callers
  * pass only `input`.
  */
+
 /**
  * Server-injected second argument to every function handler. Never constructed
  * on the client — the values come from the backend at invocation time.
@@ -1331,6 +1432,16 @@ interface RagableFunctionContext {
     auth: {
         token: string | null;
     };
+    /**
+     * A pre-authenticated {@link RagableServerClient} for talking back to your
+     * Ragable Cloud (db / storage / mail / functions / ai / agents) — already
+     * wired to this project, no setup or keys to manage.
+     *
+     * Defaults to the **caller's** identity, so collection security applies just
+     * like in the browser. Call `context.ragable.asAdmin()` for privileged work
+     * that must bypass collection security (e.g. owner-only writes, audit logs).
+     */
+    ragable: RagableServerClient;
 }
 /**
  * The shape a `/functions/<name>.ts` default export must satisfy. Type the
@@ -2271,4 +2382,4 @@ declare function tryParsePartialJson(text: string): unknown | undefined;
 
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, BrowserStorageBucketClient, type BrowserStorageBulkDeleteResult, type BrowserStorageDownloadResult, type BrowserStorageItem, type BrowserStorageListResult, type BrowserStorageSignedUrlResult, type BrowserStorageUploadResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type DefaultRagableFunctions, type FinishReason, type FunctionInvoker, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type Json, type JsonSchema, LocalStorageAdapter, type MailMessageDetail, type MailMessagePreview, type MailSearchParams, type MailSendParams, type MailSendResult, MemoryStorageAdapter, type Message, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAiClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, RagableBrowserFunctionsClient, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, type RagableFunctionCall, type RagableFunctionContext, type RagableFunctionHandler, type RagableFunctionInvokeOptions, type RagableFunctions, RagableNetworkError, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type SseJsonEvent, type StreamObjectParams, type StreamObjectResult, type StreamPart, type StreamTextParams, type StreamTextResult, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, BrowserStorageBucketClient, type BrowserStorageBulkDeleteResult, type BrowserStorageDownloadResult, type BrowserStorageItem, type BrowserStorageListResult, type BrowserStorageSignedUrlResult, type BrowserStorageUploadResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type DefaultRagableFunctions, type FinishReason, type FunctionInvoker, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type Json, type JsonSchema, LocalStorageAdapter, type MailMessageDetail, type MailMessagePreview, type MailSearchParams, type MailSendParams, type MailSendResult, MemoryStorageAdapter, type Message, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAiClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, RagableBrowserFunctionsClient, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, type RagableFunctionCall, type RagableFunctionContext, type RagableFunctionHandler, type RagableFunctionInvokeOptions, type RagableFunctions, RagableNetworkError, type RagableResult, RagableSdkError, RagableServerClient, type RagableServerClientConfig, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type ServerPrivilege, type SessionStorage, SessionStorageAdapter, type SseJsonEvent, type StreamObjectParams, type StreamObjectResult, type StreamPart, type StreamTextParams, type StreamTextResult, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createServerClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };

package/dist/index.d.ts

@@ -1279,6 +1279,106 @@ declare function streamObjectFromContext<T = unknown>(ctx: InferenceRequestConte
  */
 declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): StreamObjectResult<T>;
 
+/**
+ * Server-side client — the authenticated SDK for code that runs on a trusted
+ * server (a Ragable backend **function**, an Engine, or your own Node service).
+ *
+ * Unlike the browser client there is **no sign-in / session machinery** here:
+ * a server is not a logged-in user. Instead you provide credentials up front and
+ * the client speaks to the same Ragable data plane the browser uses, so the
+ * semantics (collection security, `{ data, error }` shapes, PostgREST) are
+ * identical — this reuses the exact same fetch-based sub-clients, never a
+ * reimplementation.
+ *
+ * Two privilege levels:
+ *  - **caller** (default): acts as the end user who invoked you — uses their
+ *    forwarded access token, falling back to the public anon key for anonymous
+ *    callers. Collection security applies, exactly as in the browser.
+ *  - **admin**: authenticates with the auth group's **data-admin key**, which
+ *    bypasses collection security (owner/group/claim grants do not apply) and
+ *    can write protected collections. Reach for it deliberately.
+ *
+ * ```ts
+ * // inside /functions/<name>.ts — `context.ragable` is a pre-built server client
+ * export default async function createTask(input, context) {
+ *   // as the caller (respects collection security):
+ *   const { data, error } = await context.ragable.db.collections.tasks.insert(input);
+ *   // privileged work (bypasses collection security):
+ *   await context.ragable.asAdmin().db.collections.audit_log.insert({ action: "create" });
+ *   return data;
+ * }
+ * ```
+ */
+
+/** Which credential a server client authenticates with. */
+type ServerPrivilege = "caller" | "admin";
+/**
+ * Inputs to {@link createServerClient}. The IDs and keys are normally supplied by
+ * the runtime (a function's injected `context.ragable`); construct one by hand
+ * only for a standalone server.
+ */
+interface RagableServerClientConfig {
+    organizationId: string;
+    websiteId?: string;
+    authGroupId?: string;
+    databaseInstanceId?: string;
+    storageBucketId?: string;
+    mailAccountId?: string;
+    /**
+     * The auth group's **data-admin key**. Required for `admin` privilege; omit it
+     * and `asAdmin()` throws. Server-only — never expose this to the browser.
+     */
+    adminKey?: string;
+    /**
+     * The invoking end user's access token (a real auth-group JWT), forwarded by
+     * the runtime. `null`/omitted for anonymous callers. Used by `caller`
+     * privilege; the public anon key is the fallback when this is absent.
+     */
+    callerToken?: string | null;
+    /** Public anon key — the `caller` fallback when no end user is signed in. */
+    publicAnonKey?: string;
+    /** Default privilege for the returned client. Defaults to `"caller"`. */
+    defaultPrivilege?: ServerPrivilege;
+    fetch?: typeof fetch;
+    headers?: HeadersInit;
+}
+/**
+ * A trusted, server-side Ragable client. Surface mirrors the browser client
+ * (`db`, `storage`, `mail`, `functions`, `ai`, `agents`) minus `auth` — a server
+ * authenticates with keys, not a session. Switch privilege with {@link asAdmin}
+ * / {@link asCaller}.
+ */
+declare class RagableServerClient<Database extends RagableDatabase = DefaultRagableDatabase, Functions extends RagableFunctions = DefaultRagableFunctions> {
+    private readonly config;
+    readonly database: RagableBrowserDatabaseClient<Database>;
+    readonly db: RagableBrowserDatabaseClient<Database>;
+    readonly storage: RagableBrowserStorageClient;
+    readonly mail: RagableBrowserMailClient;
+    readonly functions: FunctionInvoker<Functions>;
+    readonly ai: RagableBrowserAiClient;
+    readonly agents: RagableBrowserAgentsClient;
+    /** Which credential this client is using. */
+    readonly privilege: ServerPrivilege;
+    constructor(config: RagableServerClientConfig, privilege: ServerPrivilege);
+    /**
+     * A client authenticated with the **data-admin key** — bypasses collection
+     * security (owner/group/claim grants do not apply) and can write protected
+     * collections. Throws `SDK_ADMIN_KEY_REQUIRED` when no admin key is configured.
+     */
+    asAdmin(): RagableServerClient<Database, Functions>;
+    /**
+     * A client scoped to the invoking end user's identity (respects collection
+     * security). This is already the default; use it to drop back from `asAdmin()`.
+     */
+    asCaller(): RagableServerClient<Database, Functions>;
+}
+/**
+ * Create a server-side Ragable client. Defaults to **caller** privilege (acts as
+ * the invoking end user, respecting collection security); call `.asAdmin()` for
+ * privileged, security-bypassing access.
+ */
+declare function createServerClient<Database extends RagableDatabase = DefaultRagableDatabase, Functions extends RagableFunctions = DefaultRagableFunctions>(config: RagableServerClientConfig): RagableServerClient<Database, Functions>;
+
 /**
  * Backend "edge functions".
  *
@@ -1307,6 +1407,7 @@ declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): S
  * The handler's second argument (`context`) is injected by the server; callers
  * pass only `input`.
  */
+
 /**
  * Server-injected second argument to every function handler. Never constructed
  * on the client — the values come from the backend at invocation time.
@@ -1331,6 +1432,16 @@ interface RagableFunctionContext {
     auth: {
         token: string | null;
     };
+    /**
+     * A pre-authenticated {@link RagableServerClient} for talking back to your
+     * Ragable Cloud (db / storage / mail / functions / ai / agents) — already
+     * wired to this project, no setup or keys to manage.
+     *
+     * Defaults to the **caller's** identity, so collection security applies just
+     * like in the browser. Call `context.ragable.asAdmin()` for privileged work
+     * that must bypass collection security (e.g. owner-only writes, audit logs).
+     */
+    ragable: RagableServerClient;
 }
 /**
  * The shape a `/functions/<name>.ts` default export must satisfy. Type the
@@ -2271,4 +2382,4 @@ declare function tryParsePartialJson(text: string): unknown | undefined;
 
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, BrowserStorageBucketClient, type BrowserStorageBulkDeleteResult, type BrowserStorageDownloadResult, type BrowserStorageItem, type BrowserStorageListResult, type BrowserStorageSignedUrlResult, type BrowserStorageUploadResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type DefaultRagableFunctions, type FinishReason, type FunctionInvoker, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type Json, type JsonSchema, LocalStorageAdapter, type MailMessageDetail, type MailMessagePreview, type MailSearchParams, type MailSendParams, type MailSendResult, MemoryStorageAdapter, type Message, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAiClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, RagableBrowserFunctionsClient, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, type RagableFunctionCall, type RagableFunctionContext, type RagableFunctionHandler, type RagableFunctionInvokeOptions, type RagableFunctions, RagableNetworkError, type RagableResult, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type SseJsonEvent, type StreamObjectParams, type StreamObjectResult, type StreamPart, type StreamTextParams, type StreamTextResult, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatStreamDonePayload, type AgentChatStreamHandlers, type AgentChatStreamResult, type AgentChatStreamUiHandlers, type AgentChatUiAssistantMessage, type AgentChatUiSegment, type AgentChatUiStreamResult, type AgentConversation, type AgentConversationMessage, type AgentConversationSubscription, type AgentPublicChatParams, type AgentStreamAgentInfoEvent, type AgentStreamEvent, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type AuthSignUpCredentials, type AuthUpdateUserAttributes, type AuthUserMetadata, type BrowserAuthSession, type BrowserAuthTokens, BrowserCollectionApi, type BrowserCollectionDefinition, type BrowserCollectionFactory, type BrowserCollectionFindParams, type BrowserCollectionRecord, type BrowserCollections, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, BrowserStorageBucketClient, type BrowserStorageBulkDeleteResult, type BrowserStorageDownloadResult, type BrowserStorageItem, type BrowserStorageListResult, type BrowserStorageSignedUrlResult, type BrowserStorageUploadResult, type CollectionReturnMode, type CollectionRowData, type CollectionRowWithMeta, type CollectionWhere, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultAuthUser, type DefaultRagableDatabase, type DefaultRagableFunctions, type FinishReason, type FunctionInvoker, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type Json, type JsonSchema, LocalStorageAdapter, type MailMessageDetail, type MailMessagePreview, type MailSearchParams, type MailSendParams, type MailSendResult, MemoryStorageAdapter, type Message, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAiClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, RagableBrowserFunctionsClient, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, type RagableFunctionCall, type RagableFunctionContext, type RagableFunctionHandler, type RagableFunctionInvokeOptions, type RagableFunctions, RagableNetworkError, type RagableResult, RagableSdkError, RagableServerClient, type RagableServerClientConfig, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetryOptions, type RunAgentChatStreamOptions, type RunQuery, type ServerPrivilege, type SessionStorage, SessionStorageAdapter, type SseJsonEvent, type StreamObjectParams, type StreamObjectResult, type StreamPart, type StreamTextParams, type StreamTextResult, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type WhereInput, type WhereOperatorObject, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createServerClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };

package/dist/index.js

@@ -53,6 +53,7 @@ __export(index_exports, {
   RagableError: () => RagableError,
   RagableNetworkError: () => RagableNetworkError,
   RagableSdkError: () => RagableSdkError,
+  RagableServerClient: () => RagableServerClient,
   RagableTimeoutError: () => RagableTimeoutError,
   SessionStorageAdapter: () => SessionStorageAdapter,
   Transport: () => Transport,
@@ -67,6 +68,7 @@ __export(index_exports, {
   createBrowserClient: () => createBrowserClient,
   createClient: () => createClient,
   createRagableBrowserClient: () => createRagableBrowserClient,
+  createServerClient: () => createServerClient,
   createStreamResultFromParts: () => createStreamResultFromParts,
   detectStorage: () => detectStorage,
   effectiveDataAuth: () => effectiveDataAuth,
@@ -4650,6 +4652,91 @@ function createBrowserClient(options) {
 }
 var createRagableBrowserClient = createBrowserClient;
 
+// src/server.ts
+function optionsForPrivilege(config, privilege) {
+  const base = {
+    organizationId: config.organizationId,
+    ...config.websiteId !== void 0 ? { websiteId: config.websiteId } : {},
+    ...config.authGroupId !== void 0 ? { authGroupId: config.authGroupId } : {},
+    ...config.databaseInstanceId !== void 0 ? { databaseInstanceId: config.databaseInstanceId } : {},
+    ...config.fetch !== void 0 ? { fetch: config.fetch } : {},
+    ...config.headers !== void 0 ? { headers: config.headers } : {}
+  };
+  if (privilege === "admin") {
+    const key = config.adminKey?.trim();
+    if (!key) {
+      throw new RagableError(
+        "Admin privilege requires `adminKey` (the auth group's data-admin key). It is not available \u2014 admin functions may be disabled for this project.",
+        403,
+        { code: "SDK_ADMIN_KEY_REQUIRED" }
+      );
+    }
+    return { ...base, dataAuth: "admin", dataStaticKey: key };
+  }
+  return {
+    ...base,
+    dataAuth: "auto",
+    getAccessToken: () => config.callerToken ?? null,
+    ...config.publicAnonKey !== void 0 ? { dataStaticKey: config.publicAnonKey } : {}
+  };
+}
+var RagableServerClient = class _RagableServerClient {
+  constructor(config, privilege) {
+    this.config = config;
+    __publicField(this, "database");
+    __publicField(this, "db");
+    __publicField(this, "storage");
+    __publicField(this, "mail");
+    __publicField(this, "functions");
+    __publicField(this, "ai");
+    __publicField(this, "agents");
+    /** Which credential this client is using. */
+    __publicField(this, "privilege");
+    this.privilege = privilege;
+    const options = optionsForPrivilege(config, privilege);
+    const transport = new Transport({
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.headers !== void 0 ? { headers: options.headers } : {},
+      ...options.transport
+    });
+    this.database = new RagableBrowserDatabaseClient(options, null);
+    this.database._setTransport(transport);
+    this.db = this.database;
+    this.storage = new RagableBrowserStorageClient(options, bindFetch(options.fetch), null);
+    this.mail = new RagableBrowserMailClient(options, null);
+    this.functions = new RagableBrowserFunctionsClient(options, null).asInvoker();
+    this.ai = new RagableBrowserAiClient({
+      organizationId: options.organizationId,
+      ...options.websiteId !== void 0 ? { websiteId: options.websiteId } : {},
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.headers !== void 0 ? { headers: options.headers } : {},
+      apiBase: normalizeBrowserApiBase()
+    });
+    this.agents = new RagableBrowserAgentsClient(options);
+  }
+  /**
+   * A client authenticated with the **data-admin key** — bypasses collection
+   * security (owner/group/claim grants do not apply) and can write protected
+   * collections. Throws `SDK_ADMIN_KEY_REQUIRED` when no admin key is configured.
+   */
+  asAdmin() {
+    return new _RagableServerClient(this.config, "admin");
+  }
+  /**
+   * A client scoped to the invoking end user's identity (respects collection
+   * security). This is already the default; use it to drop back from `asAdmin()`.
+   */
+  asCaller() {
+    return new _RagableServerClient(this.config, "caller");
+  }
+};
+function createServerClient(config) {
+  return new RagableServerClient(
+    config,
+    config.defaultPrivilege ?? "caller"
+  );
+}
+
 // src/index.ts
 function createClient(options) {
   return createBrowserClient(options);
@@ -4687,6 +4774,7 @@ function createClient(options) {
   RagableError,
   RagableNetworkError,
   RagableSdkError,
+  RagableServerClient,
   RagableTimeoutError,
   SessionStorageAdapter,
   Transport,
@@ -4701,6 +4789,7 @@ function createClient(options) {
   createBrowserClient,
   createClient,
   createRagableBrowserClient,
+  createServerClient,
   createStreamResultFromParts,
   detectStorage,
   effectiveDataAuth,