@ragable/sdk 0.7.10 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -981,53 +981,10 @@ type StreamPart = {
981
981
  type: "error";
982
982
  error: unknown;
983
983
  };
984
- /** Plain text segment inside a multimodal user message. */
985
- interface TextPart {
986
- type: "text";
987
- text: string;
988
- }
989
- /**
990
- * Image segment inside a multimodal user message. Mirrors Vercel AI SDK's
991
- * `ImagePart` shape — the discriminator is `"image"` and the data field is
992
- * `image` (not `image_url`). The SDK converts to the OpenAI `image_url`
993
- * wire format internally.
994
- */
995
- interface ImagePart {
996
- type: "image";
997
- /**
998
- * Accepted forms:
999
- * - HTTP(S) URL string (`"https://…"`) — passed through; the provider fetches it.
1000
- * - Data URL string (`"data:image/png;base64,…"`) — passed through.
1001
- * - Raw base64 string (no `data:` prefix) — `mediaType` then required.
1002
- * - `Uint8Array` / `ArrayBuffer` — base64-encoded; `mediaType` required.
1003
- * - `URL` instance — `href` is passed through.
1004
- */
1005
- image: string | Uint8Array | ArrayBuffer | URL;
1006
- /** IANA media type, e.g. `"image/png"`. Required when `image` is binary or a raw base64 string. */
1007
- mediaType?: string;
1008
- /** OpenAI-compatible detail hint; forwarded as `image_url.detail`. */
1009
- detail?: "auto" | "low" | "high";
1010
- }
1011
- /**
1012
- * Content for a user message — either a plain string (back-compat with the
1013
- * original text-only shape) or an array of text/image parts.
1014
- */
1015
- type UserContent = string | Array<TextPart | ImagePart>;
1016
- /**
1017
- * Chat message. `user` messages may carry multimodal content; `system` and
1018
- * `assistant` are text-only (vision models consume images on user turns,
1019
- * and image *output* isn't supported here).
1020
- */
1021
- type Message = {
1022
- role: "system";
984
+ interface Message {
985
+ role: "system" | "user" | "assistant";
1023
986
  content: string;
1024
- } | {
1025
- role: "user";
1026
- content: UserContent;
1027
- } | {
1028
- role: "assistant";
1029
- content: string;
1030
- };
987
+ }
1031
988
  /**
1032
989
  * OpenAI/Fireworks SSE chunk shape, only the fields we actually consume.
1033
990
  * Kept as a local type so we don't depend on backend internals.
@@ -1289,6 +1246,98 @@ declare function streamObjectFromContext<T = unknown>(ctx: InferenceRequestConte
1289
1246
  */
1290
1247
  declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): StreamObjectResult<T>;
1291
1248
 
1249
+ /**
1250
+ * Backend "edge functions".
1251
+ *
1252
+ * A function is a single file in the project's `/functions` folder whose name is
1253
+ * the function name and whose **default export is the handler**:
1254
+ *
1255
+ * ```ts
1256
+ * // /functions/getUsers.ts
1257
+ * import type { RagableFunctionContext } from "@ragable/sdk";
1258
+ *
1259
+ * export default async function getUsers(
1260
+ * input: { limit?: number },
1261
+ * context: RagableFunctionContext,
1262
+ * ) {
1263
+ * const res = await fetch("https://api.example.com/users", {
1264
+ * headers: { Authorization: `Bearer ${context.env.API_KEY}` },
1265
+ * });
1266
+ * return (await res.json()).slice(0, input.limit ?? 20);
1267
+ * }
1268
+ * ```
1269
+ *
1270
+ * Saving the file deploys it (near-instant). It runs **server-side** — so secrets
1271
+ * stay off the client and there are no browser CORS limits — and is invoked from
1272
+ * the browser with `client.functions.getUsers({ limit: 5 })`.
1273
+ *
1274
+ * The handler's second argument (`context`) is injected by the server; callers
1275
+ * pass only `input`.
1276
+ */
1277
+ /**
1278
+ * Server-injected second argument to every function handler. Never constructed
1279
+ * on the client — the values come from the backend at invocation time.
1280
+ */
1281
+ interface RagableFunctionContext {
1282
+ /**
1283
+ * Secrets for this function, parsed from the project's `/functions/.env`.
1284
+ * Server-only: this file is read at invoke time and never bundled into the
1285
+ * browser app. Empty when no `/functions/.env` exists.
1286
+ */
1287
+ env: Record<string, string>;
1288
+ /** Metadata about the invoking HTTP request. */
1289
+ request: {
1290
+ method: string;
1291
+ headers: Record<string, string>;
1292
+ };
1293
+ /**
1294
+ * End-user auth forwarded from the caller. `token` is the bearer the browser
1295
+ * client was holding (an end-user access token or the data static key), or
1296
+ * `null` for anonymous calls.
1297
+ */
1298
+ auth: {
1299
+ token: string | null;
1300
+ };
1301
+ }
1302
+ /**
1303
+ * The shape a `/functions/<name>.ts` default export must satisfy. Type the
1304
+ * `input` parameter as optional (`input?: Foo`) when callers may omit it.
1305
+ */
1306
+ type RagableFunctionHandler<Input = any, Output = any> = (input: Input, context: RagableFunctionContext) => Output | Promise<Output>;
1307
+ /**
1308
+ * A project's function map: function name → handler. Generated as `AppFunctions`.
1309
+ * The constraint is intentionally loose (any function shape) so a handler that
1310
+ * deviates from `(input, context)` never breaks the generated client as a whole;
1311
+ * the per-call typing in {@link RagableFunctionCall} adapts to each signature.
1312
+ */
1313
+ type RagableFunctions = Record<string, (...args: any[]) => any>;
1314
+ /** Permissive default used when no generated `AppFunctions` is supplied. */
1315
+ interface DefaultRagableFunctions {
1316
+ [name: string]: (...args: any[]) => any;
1317
+ }
1318
+ /** Per-call options for an invocation. */
1319
+ interface RagableFunctionInvokeOptions {
1320
+ signal?: AbortSignal;
1321
+ headers?: HeadersInit;
1322
+ }
1323
+ /**
1324
+ * The browser-side call signature derived from a server handler `H`: the server
1325
+ * injects `context`, so the caller passes only `input`. `input` is optional when
1326
+ * the handler's input type permits `undefined`.
1327
+ */
1328
+ type RagableFunctionCall<H> = H extends (input: infer I, ...rest: any[]) => infer R ? undefined extends I ? (input?: I, options?: RagableFunctionInvokeOptions) => Promise<Awaited<R>> : (input: I, options?: RagableFunctionInvokeOptions) => Promise<Awaited<R>> : (input?: unknown, options?: RagableFunctionInvokeOptions) => Promise<unknown>;
1329
+ /**
1330
+ * The type of `client.functions`: a typed callable per function in `F`, plus an
1331
+ * `invoke(name, input?)` escape hatch for dynamic dispatch. (A function literally
1332
+ * named `invoke` is therefore reserved.)
1333
+ */
1334
+ type FunctionInvoker<F extends RagableFunctions = DefaultRagableFunctions> = {
1335
+ [K in keyof F]: RagableFunctionCall<F[K]>;
1336
+ } & {
1337
+ /** Invoke a function by name. Useful when the name is dynamic. */
1338
+ invoke<Result = unknown>(name: string, input?: unknown, options?: RagableFunctionInvokeOptions): Promise<Result>;
1339
+ };
1340
+
1292
1341
  /** Canonical browser/server API base (`…/api`, no trailing slash). */
1293
1342
  declare function normalizeBrowserApiBase(): string;
1294
1343
  type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
@@ -1930,6 +1979,33 @@ declare class RagableBrowserMailClient {
1930
1979
  /** Fetch a single message in full (headers + decoded text/html body). */
1931
1980
  getMessage(messageId: string): Promise<MailMessageDetail>;
1932
1981
  }
1982
+ /**
1983
+ * Invokes the project's backend edge functions (handlers in `/functions/<name>.ts`).
1984
+ *
1985
+ * Exposed on the client as a typed Proxy — `client.functions.<name>(input)` — so
1986
+ * each generated function name is a direct callable. Functions run server-side,
1987
+ * so calls can use secrets and reach any external API without browser CORS limits.
1988
+ */
1989
+ declare class RagableBrowserFunctionsClient {
1990
+ private readonly options;
1991
+ private readonly auth;
1992
+ private readonly fetchImpl;
1993
+ constructor(options: RagableBrowserClientOptions, auth: RagableAuth | null);
1994
+ private requireWebsiteId;
1995
+ private toUrl;
1996
+ /**
1997
+ * Best-effort end-user bearer, forwarded to the function as `context.auth.token`.
1998
+ * Functions are public, so this never throws — anonymous calls send no token.
1999
+ */
2000
+ private getOptionalToken;
2001
+ /**
2002
+ * Invoke a function by name. Prefer the typed `client.functions.<name>(input)`
2003
+ * accessors; use this when the name is dynamic.
2004
+ */
2005
+ invoke<Result = unknown>(name: string, input?: unknown, options?: RagableFunctionInvokeOptions): Promise<Result>;
2006
+ /** Build the typed Proxy exposed as `client.functions`. */
2007
+ asInvoker<F extends RagableFunctions = DefaultRagableFunctions>(): FunctionInvoker<F>;
2008
+ }
1933
2009
  interface AgentConversationMessage {
1934
2010
  role: "user" | "assistant";
1935
2011
  content: string;
@@ -2062,7 +2138,7 @@ interface AgentPublicChatParams extends AgentChatParams {
2062
2138
  triggerSubtype?: string;
2063
2139
  triggerNodeId?: string;
2064
2140
  }
2065
- declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser> {
2141
+ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions> {
2066
2142
  readonly agents: RagableBrowserAgentsClient;
2067
2143
  readonly ai: RagableBrowserAiClient;
2068
2144
  readonly auth: RagableBrowserAuthClient<AuthUser>;
@@ -2070,6 +2146,11 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
2070
2146
  readonly db: RagableBrowserDatabaseClient<Database>;
2071
2147
  readonly storage: RagableBrowserStorageClient;
2072
2148
  readonly mail: RagableBrowserMailClient;
2149
+ /**
2150
+ * Backend edge functions — call a `/functions/<name>.ts` handler with
2151
+ * `client.functions.<name>(input)`. Runs server-side. See {@link FunctionInvoker}.
2152
+ */
2153
+ readonly functions: FunctionInvoker<Functions>;
2073
2154
  readonly transport: Transport;
2074
2155
  private readonly _ragableAuth;
2075
2156
  constructor(options: RagableBrowserClientOptions);
@@ -2077,7 +2158,7 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
2077
2158
  from: <TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string) => PostgrestTableApi<Database, TableName>;
2078
2159
  destroy(): void;
2079
2160
  }
2080
- declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
2161
+ declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
2081
2162
  declare const createRagableBrowserClient: typeof createBrowserClient;
2082
2163
 
2083
2164
  /**
@@ -2092,45 +2173,6 @@ declare function parseSseDataLine(line: string): SseJsonEvent | null;
2092
2173
  */
2093
2174
  declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<SseJsonEvent, void, undefined>;
2094
2175
 
2095
- /**
2096
- * Convert SDK-shape multimodal content to the OpenAI/Fireworks `image_url`
2097
- * wire format the Ragable inference proxy expects. Keeps the public SDK
2098
- * types Vercel-AI-SDK-shaped (`{ type: "image", image: ... }`) while the
2099
- * over-the-wire shape stays OpenAI canonical.
2100
- */
2101
-
2102
- /** OpenAI/Fireworks image content part — what flows on the wire. */
2103
- interface WireImagePart {
2104
- type: "image_url";
2105
- image_url: {
2106
- url: string;
2107
- detail?: "auto" | "low" | "high";
2108
- };
2109
- }
2110
- type WireTextPart = {
2111
- type: "text";
2112
- text: string;
2113
- };
2114
- type WireContentPart = WireTextPart | WireImagePart;
2115
- type WireUserContent = string | WireContentPart[];
2116
- /**
2117
- * Convert a single `UserContent` value to wire shape. Strings pass through
2118
- * unchanged so existing callers keep producing byte-identical request bodies.
2119
- */
2120
- declare function toWireUserContent(content: UserContent): WireUserContent;
2121
- /**
2122
- * Resolve an `ImagePart.image` value into a URL string suitable for
2123
- * `image_url.url`. URLs pass through; binary and raw base64 are wrapped
2124
- * into a data URL.
2125
- */
2126
- declare function imagePartToUrl(part: ImagePart): string;
2127
- /**
2128
- * Cross-runtime `Uint8Array → base64`. `btoa(String.fromCharCode(...bytes))`
2129
- * trips the JS call-stack limit on large payloads, so we chunk the binary
2130
- * string. Works in browser, Node 18+, Edge, and Bun.
2131
- */
2132
- declare function bytesToBase64(bytes: Uint8Array): string;
2133
-
2134
2176
  /**
2135
2177
  * Best-effort parser for incomplete JSON streamed token-by-token from an LLM.
2136
2178
  *
@@ -2147,6 +2189,6 @@ declare function bytesToBase64(bytes: Uint8Array): string;
2147
2189
  */
2148
2190
  declare function tryParsePartialJson(text: string): unknown | undefined;
2149
2191
 
2150
- declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
2192
+ declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
2151
2193
 
2152
- 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 FinishReason, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type ImagePart, 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, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, 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 TextPart, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type UserContent, type WhereInput, type WhereOperatorObject, type WireContentPart, type WireImagePart, type WireTextPart, type WireUserContent, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, bytesToBase64, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, imagePartToUrl, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, toWireUserContent, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };
2194
+ 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 };
package/dist/index.d.ts CHANGED
@@ -981,53 +981,10 @@ type StreamPart = {
981
981
  type: "error";
982
982
  error: unknown;
983
983
  };
984
- /** Plain text segment inside a multimodal user message. */
985
- interface TextPart {
986
- type: "text";
987
- text: string;
988
- }
989
- /**
990
- * Image segment inside a multimodal user message. Mirrors Vercel AI SDK's
991
- * `ImagePart` shape — the discriminator is `"image"` and the data field is
992
- * `image` (not `image_url`). The SDK converts to the OpenAI `image_url`
993
- * wire format internally.
994
- */
995
- interface ImagePart {
996
- type: "image";
997
- /**
998
- * Accepted forms:
999
- * - HTTP(S) URL string (`"https://…"`) — passed through; the provider fetches it.
1000
- * - Data URL string (`"data:image/png;base64,…"`) — passed through.
1001
- * - Raw base64 string (no `data:` prefix) — `mediaType` then required.
1002
- * - `Uint8Array` / `ArrayBuffer` — base64-encoded; `mediaType` required.
1003
- * - `URL` instance — `href` is passed through.
1004
- */
1005
- image: string | Uint8Array | ArrayBuffer | URL;
1006
- /** IANA media type, e.g. `"image/png"`. Required when `image` is binary or a raw base64 string. */
1007
- mediaType?: string;
1008
- /** OpenAI-compatible detail hint; forwarded as `image_url.detail`. */
1009
- detail?: "auto" | "low" | "high";
1010
- }
1011
- /**
1012
- * Content for a user message — either a plain string (back-compat with the
1013
- * original text-only shape) or an array of text/image parts.
1014
- */
1015
- type UserContent = string | Array<TextPart | ImagePart>;
1016
- /**
1017
- * Chat message. `user` messages may carry multimodal content; `system` and
1018
- * `assistant` are text-only (vision models consume images on user turns,
1019
- * and image *output* isn't supported here).
1020
- */
1021
- type Message = {
1022
- role: "system";
984
+ interface Message {
985
+ role: "system" | "user" | "assistant";
1023
986
  content: string;
1024
- } | {
1025
- role: "user";
1026
- content: UserContent;
1027
- } | {
1028
- role: "assistant";
1029
- content: string;
1030
- };
987
+ }
1031
988
  /**
1032
989
  * OpenAI/Fireworks SSE chunk shape, only the fields we actually consume.
1033
990
  * Kept as a local type so we don't depend on backend internals.
@@ -1289,6 +1246,98 @@ declare function streamObjectFromContext<T = unknown>(ctx: InferenceRequestConte
1289
1246
  */
1290
1247
  declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): StreamObjectResult<T>;
1291
1248
 
1249
+ /**
1250
+ * Backend "edge functions".
1251
+ *
1252
+ * A function is a single file in the project's `/functions` folder whose name is
1253
+ * the function name and whose **default export is the handler**:
1254
+ *
1255
+ * ```ts
1256
+ * // /functions/getUsers.ts
1257
+ * import type { RagableFunctionContext } from "@ragable/sdk";
1258
+ *
1259
+ * export default async function getUsers(
1260
+ * input: { limit?: number },
1261
+ * context: RagableFunctionContext,
1262
+ * ) {
1263
+ * const res = await fetch("https://api.example.com/users", {
1264
+ * headers: { Authorization: `Bearer ${context.env.API_KEY}` },
1265
+ * });
1266
+ * return (await res.json()).slice(0, input.limit ?? 20);
1267
+ * }
1268
+ * ```
1269
+ *
1270
+ * Saving the file deploys it (near-instant). It runs **server-side** — so secrets
1271
+ * stay off the client and there are no browser CORS limits — and is invoked from
1272
+ * the browser with `client.functions.getUsers({ limit: 5 })`.
1273
+ *
1274
+ * The handler's second argument (`context`) is injected by the server; callers
1275
+ * pass only `input`.
1276
+ */
1277
+ /**
1278
+ * Server-injected second argument to every function handler. Never constructed
1279
+ * on the client — the values come from the backend at invocation time.
1280
+ */
1281
+ interface RagableFunctionContext {
1282
+ /**
1283
+ * Secrets for this function, parsed from the project's `/functions/.env`.
1284
+ * Server-only: this file is read at invoke time and never bundled into the
1285
+ * browser app. Empty when no `/functions/.env` exists.
1286
+ */
1287
+ env: Record<string, string>;
1288
+ /** Metadata about the invoking HTTP request. */
1289
+ request: {
1290
+ method: string;
1291
+ headers: Record<string, string>;
1292
+ };
1293
+ /**
1294
+ * End-user auth forwarded from the caller. `token` is the bearer the browser
1295
+ * client was holding (an end-user access token or the data static key), or
1296
+ * `null` for anonymous calls.
1297
+ */
1298
+ auth: {
1299
+ token: string | null;
1300
+ };
1301
+ }
1302
+ /**
1303
+ * The shape a `/functions/<name>.ts` default export must satisfy. Type the
1304
+ * `input` parameter as optional (`input?: Foo`) when callers may omit it.
1305
+ */
1306
+ type RagableFunctionHandler<Input = any, Output = any> = (input: Input, context: RagableFunctionContext) => Output | Promise<Output>;
1307
+ /**
1308
+ * A project's function map: function name → handler. Generated as `AppFunctions`.
1309
+ * The constraint is intentionally loose (any function shape) so a handler that
1310
+ * deviates from `(input, context)` never breaks the generated client as a whole;
1311
+ * the per-call typing in {@link RagableFunctionCall} adapts to each signature.
1312
+ */
1313
+ type RagableFunctions = Record<string, (...args: any[]) => any>;
1314
+ /** Permissive default used when no generated `AppFunctions` is supplied. */
1315
+ interface DefaultRagableFunctions {
1316
+ [name: string]: (...args: any[]) => any;
1317
+ }
1318
+ /** Per-call options for an invocation. */
1319
+ interface RagableFunctionInvokeOptions {
1320
+ signal?: AbortSignal;
1321
+ headers?: HeadersInit;
1322
+ }
1323
+ /**
1324
+ * The browser-side call signature derived from a server handler `H`: the server
1325
+ * injects `context`, so the caller passes only `input`. `input` is optional when
1326
+ * the handler's input type permits `undefined`.
1327
+ */
1328
+ type RagableFunctionCall<H> = H extends (input: infer I, ...rest: any[]) => infer R ? undefined extends I ? (input?: I, options?: RagableFunctionInvokeOptions) => Promise<Awaited<R>> : (input: I, options?: RagableFunctionInvokeOptions) => Promise<Awaited<R>> : (input?: unknown, options?: RagableFunctionInvokeOptions) => Promise<unknown>;
1329
+ /**
1330
+ * The type of `client.functions`: a typed callable per function in `F`, plus an
1331
+ * `invoke(name, input?)` escape hatch for dynamic dispatch. (A function literally
1332
+ * named `invoke` is therefore reserved.)
1333
+ */
1334
+ type FunctionInvoker<F extends RagableFunctions = DefaultRagableFunctions> = {
1335
+ [K in keyof F]: RagableFunctionCall<F[K]>;
1336
+ } & {
1337
+ /** Invoke a function by name. Useful when the name is dynamic. */
1338
+ invoke<Result = unknown>(name: string, input?: unknown, options?: RagableFunctionInvokeOptions): Promise<Result>;
1339
+ };
1340
+
1292
1341
  /** Canonical browser/server API base (`…/api`, no trailing slash). */
1293
1342
  declare function normalizeBrowserApiBase(): string;
1294
1343
  type BrowserDataAuthMode = "user" | "publicAnon" | "admin";
@@ -1930,6 +1979,33 @@ declare class RagableBrowserMailClient {
1930
1979
  /** Fetch a single message in full (headers + decoded text/html body). */
1931
1980
  getMessage(messageId: string): Promise<MailMessageDetail>;
1932
1981
  }
1982
+ /**
1983
+ * Invokes the project's backend edge functions (handlers in `/functions/<name>.ts`).
1984
+ *
1985
+ * Exposed on the client as a typed Proxy — `client.functions.<name>(input)` — so
1986
+ * each generated function name is a direct callable. Functions run server-side,
1987
+ * so calls can use secrets and reach any external API without browser CORS limits.
1988
+ */
1989
+ declare class RagableBrowserFunctionsClient {
1990
+ private readonly options;
1991
+ private readonly auth;
1992
+ private readonly fetchImpl;
1993
+ constructor(options: RagableBrowserClientOptions, auth: RagableAuth | null);
1994
+ private requireWebsiteId;
1995
+ private toUrl;
1996
+ /**
1997
+ * Best-effort end-user bearer, forwarded to the function as `context.auth.token`.
1998
+ * Functions are public, so this never throws — anonymous calls send no token.
1999
+ */
2000
+ private getOptionalToken;
2001
+ /**
2002
+ * Invoke a function by name. Prefer the typed `client.functions.<name>(input)`
2003
+ * accessors; use this when the name is dynamic.
2004
+ */
2005
+ invoke<Result = unknown>(name: string, input?: unknown, options?: RagableFunctionInvokeOptions): Promise<Result>;
2006
+ /** Build the typed Proxy exposed as `client.functions`. */
2007
+ asInvoker<F extends RagableFunctions = DefaultRagableFunctions>(): FunctionInvoker<F>;
2008
+ }
1933
2009
  interface AgentConversationMessage {
1934
2010
  role: "user" | "assistant";
1935
2011
  content: string;
@@ -2062,7 +2138,7 @@ interface AgentPublicChatParams extends AgentChatParams {
2062
2138
  triggerSubtype?: string;
2063
2139
  triggerNodeId?: string;
2064
2140
  }
2065
- declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser> {
2141
+ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions> {
2066
2142
  readonly agents: RagableBrowserAgentsClient;
2067
2143
  readonly ai: RagableBrowserAiClient;
2068
2144
  readonly auth: RagableBrowserAuthClient<AuthUser>;
@@ -2070,6 +2146,11 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
2070
2146
  readonly db: RagableBrowserDatabaseClient<Database>;
2071
2147
  readonly storage: RagableBrowserStorageClient;
2072
2148
  readonly mail: RagableBrowserMailClient;
2149
+ /**
2150
+ * Backend edge functions — call a `/functions/<name>.ts` handler with
2151
+ * `client.functions.<name>(input)`. Runs server-side. See {@link FunctionInvoker}.
2152
+ */
2153
+ readonly functions: FunctionInvoker<Functions>;
2073
2154
  readonly transport: Transport;
2074
2155
  private readonly _ragableAuth;
2075
2156
  constructor(options: RagableBrowserClientOptions);
@@ -2077,7 +2158,7 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
2077
2158
  from: <TableName extends RagableTableNames<Database>>(table: TableName, databaseInstanceId?: string) => PostgrestTableApi<Database, TableName>;
2078
2159
  destroy(): void;
2079
2160
  }
2080
- declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
2161
+ declare function createBrowserClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
2081
2162
  declare const createRagableBrowserClient: typeof createBrowserClient;
2082
2163
 
2083
2164
  /**
@@ -2092,45 +2173,6 @@ declare function parseSseDataLine(line: string): SseJsonEvent | null;
2092
2173
  */
2093
2174
  declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<SseJsonEvent, void, undefined>;
2094
2175
 
2095
- /**
2096
- * Convert SDK-shape multimodal content to the OpenAI/Fireworks `image_url`
2097
- * wire format the Ragable inference proxy expects. Keeps the public SDK
2098
- * types Vercel-AI-SDK-shaped (`{ type: "image", image: ... }`) while the
2099
- * over-the-wire shape stays OpenAI canonical.
2100
- */
2101
-
2102
- /** OpenAI/Fireworks image content part — what flows on the wire. */
2103
- interface WireImagePart {
2104
- type: "image_url";
2105
- image_url: {
2106
- url: string;
2107
- detail?: "auto" | "low" | "high";
2108
- };
2109
- }
2110
- type WireTextPart = {
2111
- type: "text";
2112
- text: string;
2113
- };
2114
- type WireContentPart = WireTextPart | WireImagePart;
2115
- type WireUserContent = string | WireContentPart[];
2116
- /**
2117
- * Convert a single `UserContent` value to wire shape. Strings pass through
2118
- * unchanged so existing callers keep producing byte-identical request bodies.
2119
- */
2120
- declare function toWireUserContent(content: UserContent): WireUserContent;
2121
- /**
2122
- * Resolve an `ImagePart.image` value into a URL string suitable for
2123
- * `image_url.url`. URLs pass through; binary and raw base64 are wrapped
2124
- * into a data URL.
2125
- */
2126
- declare function imagePartToUrl(part: ImagePart): string;
2127
- /**
2128
- * Cross-runtime `Uint8Array → base64`. `btoa(String.fromCharCode(...bytes))`
2129
- * trips the JS call-stack limit on large payloads, so we chunk the binary
2130
- * string. Works in browser, Node 18+, Edge, and Bun.
2131
- */
2132
- declare function bytesToBase64(bytes: Uint8Array): string;
2133
-
2134
2176
  /**
2135
2177
  * Best-effort parser for incomplete JSON streamed token-by-token from an LLM.
2136
2178
  *
@@ -2147,6 +2189,6 @@ declare function bytesToBase64(bytes: Uint8Array): string;
2147
2189
  */
2148
2190
  declare function tryParsePartialJson(text: string): unknown | undefined;
2149
2191
 
2150
- declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
2192
+ declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser, Functions extends RagableFunctions = DefaultRagableFunctions>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser, Functions>;
2151
2193
 
2152
- 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 FinishReason, type GenerateObjectResult, type GenerateTextResult, type HttpMethod, type ImagePart, 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, RagableBrowserMailClient, RagableBrowserStorageClient, type RagableDatabase, RagableError, 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 TextPart, type TokenUsage, type ToolCallRecord, Transport, type TransportOptions, type TransportRequest, type UserContent, type WhereInput, type WhereOperatorObject, type WireContentPart, type WireImagePart, type WireTextPart, type WireUserContent, asPostgrestResponse, assertPostgrestSuccess, bindFetch, buildInferenceRequestBody, buildResponseFormat, bytesToBase64, collectAssistantTextFromUiSegments, collectionRecordToRowWithMeta, collectionRecordsToRowWithMeta, createBrowserClient, createClient, createRagableBrowserClient, createStreamResultFromParts, detectStorage, effectiveDataAuth, extractErrorMessage, finalizeAgentChatUiTurn, foldAgentStreamIntoUiSegments, formatPostgrestError, formatSdkError, generateIdempotencyKey, imagePartToUrl, isIncompleteAgentStreamError, mapAgentEvent, mapFireworksChunk, normalizeBrowserApiBase, parseAgentStreamAgentInfo, parseAgentStreamDone, parseSseDataLine, parseTransportResponse, readSseStream, runAgentChatStream, runAgentChatStreamForUi, runAgentChatStreamLenient, streamObjectFromContext, toRagableResult, toWireUserContent, tryParsePartialJson, unwrapPostgrest, wrapStreamTextAsObject };
2194
+ 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 };