@ragable/sdk 0.7.7 → 0.7.9

package/dist/index.d.ts

@@ -1062,6 +1062,8 @@ declare function mapAgentEvent(event: AgentStreamLikeEvent): StreamPart | null;
  * against the website's organization.
  */
 
+/** JSON Schema for a structured response. Plain object — no Zod dep. */
+type JsonSchema = Record<string, unknown>;
 interface StreamTextParams {
     model: string;
     messages: Message[];
@@ -1100,15 +1102,87 @@ interface GenerateTextResult {
     finishReason: FinishReason;
     toolCalls: ToolCallRecord[];
 }
+interface StreamObjectParams {
+    model: string;
+    /**
+     * JSON Schema describing the expected output. Constrains the model via the
+     * Fireworks `response_format: { type: "json_object", schema }` mode.
+     */
+    schema: JsonSchema;
+    /** Optional name for the schema (passed through to providers that support it). */
+    schemaName?: string;
+    /** Optional natural-language description of the schema. */
+    schemaDescription?: string;
+    messages: Message[];
+    system?: string;
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    signal?: AbortSignal;
+}
+interface StreamObjectResult<T = unknown> {
+    /** Raw text deltas — the JSON string as it streams in. */
+    textStream: AsyncIterable<string>;
+    /**
+     * Async iterable of best-effort parsed partial objects. Emits whenever the
+     * accumulated JSON parses cleanly under the partial-JSON repair rules.
+     * Subsequent values are *replacements*, not patches — each is a snapshot.
+     */
+    partialObjectStream: AsyncIterable<T>;
+    /** Resolves to the final parsed object once the stream ends. Rejects if the final JSON is invalid. */
+    object: Promise<T>;
+    /** Resolves to the raw JSON string the model produced. */
+    text: Promise<string>;
+    usage: Promise<TokenUsage>;
+    finishReason: Promise<FinishReason>;
+    /**
+     * Resolves to tool calls the model made during this turn.
+     * Empty for `client.ai.streamObject` (no tools exposed on raw inference);
+     * populated for `client.agents.runObject` when the agent has tools.
+     */
+    toolCalls: Promise<ToolCallRecord[]>;
+}
+interface GenerateObjectResult<T = unknown> {
+    object: T;
+    usage: TokenUsage;
+    finishReason: FinishReason;
+    toolCalls: ToolCallRecord[];
+}
 /**
  * Build the JSON body for the inference proxy. Public so tests can assert it.
+ * Accepts an optional `responseFormat` so the same builder serves both
+ * `streamText` and `streamObject`.
+ */
+declare function buildInferenceRequestBody(params: StreamTextParams, responseFormat?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Build the `response_format` payload for a JSON-Schema-constrained call.
+ * Emits Fireworks' canonical shape (also accepted by OpenAI):
+ *
+ *   { type: "json_schema",
+ *     json_schema: { name, schema, description?, strict? } }
+ *
+ * @see https://docs.fireworks.ai/structured-responses/structured-response-formatting
  */
-declare function buildInferenceRequestBody(params: StreamTextParams): Record<string, unknown>;
+declare function buildResponseFormat(params: {
+    schema: JsonSchema;
+    name?: string;
+    description?: string;
+    /** Default `true` — providers ignore unknown fields safely. */
+    strict?: boolean;
+}): Record<string, unknown>;
 /**
  * Build a `StreamTextResult` from a pre-existing async iterable of StreamParts.
  * Used by `client.agents.run()` to share the same DX as `client.ai.streamText`.
  */
 declare function createStreamResultFromParts(source: AsyncIterable<StreamPart>): StreamTextResult;
+interface InferenceRequestContext {
+    /** Resolved URL of the inference endpoint. */
+    url: string;
+    /** Pre-built request headers (`Content-Type` already set). */
+    headers: Headers;
+    /** Bound fetch (already wraps user `fetch` option). */
+    fetch: typeof fetch;
+}
 interface AiClientOptions {
     organizationId: string;
     websiteId?: string;
@@ -1125,7 +1199,52 @@ declare class RagableBrowserAiClient {
     private buildContext;
     streamText(params: StreamTextParams): StreamTextResult;
     generateText(params: StreamTextParams): Promise<GenerateTextResult>;
+    /**
+     * Stream a JSON-Schema-constrained response. Matches Vercel AI SDK's
+     * `streamObject` shape — returns a synchronous result with `partialObjectStream`
+     * (best-effort incremental parses) and `object` (the final parsed JSON).
+     *
+     * ```ts
+     * const { partialObjectStream, object } = client.ai.streamObject({
+     *   model: "accounts/fireworks/models/kimi-k2p5",
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       title: { type: "string" },
+     *       tags: { type: "array", items: { type: "string" } },
+     *     },
+     *     required: ["title", "tags"],
+     *   },
+     *   messages: [{ role: "user", content: "Give me a blog post idea about AI." }],
+     * });
+     * for await (const partial of partialObjectStream) renderPreview(partial);
+     * const final = await object;
+     * ```
+     */
+    streamObject<T = unknown>(params: StreamObjectParams): StreamObjectResult<T>;
+    /**
+     * Non-streaming variant of {@link streamObject}. Resolves once the model
+     * finishes; rejects if the final text isn't valid JSON for the schema.
+     */
+    generateObject<T = unknown>(params: StreamObjectParams): Promise<GenerateObjectResult<T>>;
 }
+/**
+ * Open a JSON-mode inference stream against the proxy and return a
+ * `StreamObjectResult`. Exposed for advanced callers; most code should use
+ * `RagableBrowserAiClient.streamObject`.
+ */
+declare function streamObjectFromContext<T = unknown>(ctx: InferenceRequestContext, params: StreamObjectParams): StreamObjectResult<T>;
+/**
+ * Wrap a `StreamTextResult` (text-only stream) into a `StreamObjectResult`
+ * by parsing the accumulated text as JSON. The text path stays the source of
+ * truth for `text`/`usage`/`finishReason`/`toolCalls`; this helper only adds
+ * `partialObjectStream` and `object` on top.
+ *
+ * Public so `client.agents.runObject` can reuse the parsing logic — agents
+ * stream text through their own SSE protocol, but the structured-output
+ * conversion is identical.
+ */
+declare function wrapStreamTextAsObject<T = unknown>(inner: StreamTextResult): StreamObjectResult<T>;
 
 /** Canonical browser/server API base (`…/api`, no trailing slash). */
 declare function normalizeBrowserApiBase(): string;
@@ -1675,6 +1794,99 @@ declare class RagableBrowserStorageClient {
     constructor(options: RagableBrowserClientOptions, fetchImpl: typeof fetch);
     from(bucketId: string): BrowserStorageBucketClient;
 }
+interface MailSendParams {
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    /** Plain-text body. At least one of `bodyText` / `bodyHtml` is required. */
+    bodyText?: string;
+    /** HTML body. If both are set, sent as multipart/alternative. */
+    bodyHtml?: string;
+    /** RFC 822 Message-ID of the message you're replying to (enables threading). */
+    inReplyToMessageId?: string;
+    /** Existing References header value, chained with In-Reply-To. */
+    referencesHeader?: string;
+}
+interface MailSendResult {
+    sentMailMessageId: string;
+    gmailMessageId: string;
+    gmailThreadId: string;
+    fromAddress: string;
+}
+interface MailSearchParams {
+    /** Gmail search syntax, e.g. `from:alice is:unread newer_than:7d`. */
+    query?: string;
+    /** 1–50; default 20. */
+    maxResults?: number;
+    pageToken?: string;
+    labelIds?: string[];
+}
+interface MailMessagePreview {
+    id: string;
+    threadId: string;
+    snippet: string;
+    labelIds: string[];
+}
+interface MailMessageDetail {
+    id: string;
+    threadId: string;
+    receivedAt: number;
+    fromAddress: string;
+    fromName: string | null;
+    to: string[];
+    cc: string[];
+    subject: string;
+    snippet: string;
+    bodyText: string | null;
+    bodyHtml: string | null;
+    messageIdHeader: string | null;
+    referencesHeader: string | null;
+    labelIds: string[];
+}
+/**
+ * Send and read email through the Gmail account linked to this Ragable
+ * website (via the IDE Infrastructure → Integrations tab).
+ *
+ * All requests require a Bearer token — either an end-user JWT from this
+ * website's auth group (call `client.auth.signIn(...)` first) or the
+ * data-admin key (server-side use).
+ *
+ * The website MUST have:
+ *   1. A Gmail account linked under Integrations
+ *   2. An auth group linked under Auth
+ *
+ * Otherwise calls return a 412 with a clear error message.
+ */
+declare class RagableBrowserMailClient {
+    private readonly options;
+    private readonly auth;
+    private readonly fetchImpl;
+    constructor(options: RagableBrowserClientOptions, auth: RagableAuth | null);
+    private requireWebsiteId;
+    private pathTo;
+    /**
+     * Get the Bearer token used to authenticate the call:
+     *  1. End-user access token (preferred when an auth group is configured
+     *     and the user has signed in)
+     *  2. `dataStaticKey` from createBrowserClient options
+     *  3. Caller-supplied `getAccessToken()`
+     *
+     * If none is available, throws — server-side use should pass the
+     * data-admin key as `dataStaticKey`.
+     */
+    private getBearerToken;
+    private request;
+    /** Send an email from this website's linked Gmail account. */
+    send(params: MailSendParams): Promise<MailSendResult>;
+    /** Search messages with Gmail query syntax. */
+    search(params?: MailSearchParams): Promise<{
+        messages: MailMessagePreview[];
+        nextPageToken: string | null;
+    }>;
+    /** Fetch a single message in full (headers + decoded text/html body). */
+    getMessage(messageId: string): Promise<MailMessageDetail>;
+}
 interface AgentConversationMessage {
     role: "user" | "assistant";
     content: string;
@@ -1720,6 +1932,52 @@ declare class RagableBrowserAgentsClient {
         messages: Message[];
         signal?: AbortSignal;
     }): StreamTextResult;
+    /**
+     * Same agent, same tools/instructions/RAG — but constrain the final output
+     * to a JSON Schema. Matches `client.ai.streamObject` exactly so callers can
+     * swap between raw inference and an agent without changing call shape.
+     *
+     * Tool calling and structured output are **compatible**: the model may call
+     * the agent's tools as usual; the final assistant message is the schema-
+     * conformant JSON. The agent's `agents/<name>.json` is unchanged — whether
+     * the run is conversational or structured is decided by the call site.
+     *
+     * ```ts
+     * const { partialObjectStream, object } = client.agents.runObject<Plan>(
+     *   "planner",
+     *   {
+     *     messages: [{ role: "user", content: "Plan a 3-day trip to Kyoto." }],
+     *     schema: {
+     *       type: "object",
+     *       properties: {
+     *         days: {
+     *           type: "array",
+     *           items: { type: "object", properties: { date: { type: "string" }, activities: { type: "array", items: { type: "string" } } } },
+     *         },
+     *       },
+     *       required: ["days"],
+     *     },
+     *   },
+     * );
+     * for await (const p of partialObjectStream) renderPreview(p);
+     * console.log(await object);
+     * ```
+     */
+    runObject<T = unknown>(agentName: string, params: {
+        messages: Message[];
+        schema: JsonSchema;
+        schemaName?: string;
+        schemaDescription?: string;
+        signal?: AbortSignal;
+    }): StreamObjectResult<T>;
+    /** Non-streaming variant of {@link runObject}. */
+    generateObject<T = unknown>(agentName: string, params: {
+        messages: Message[];
+        schema: JsonSchema;
+        schemaName?: string;
+        schemaDescription?: string;
+        signal?: AbortSignal;
+    }): Promise<GenerateObjectResult<T>>;
     private runStreamParts;
     /**
      * @deprecated Use {@link run} for new code. This method is kept for
@@ -1768,6 +2026,7 @@ declare class RagableBrowser<Database extends RagableDatabase = DefaultRagableDa
     readonly database: RagableBrowserDatabaseClient<Database>;
     readonly db: RagableBrowserDatabaseClient<Database>;
     readonly storage: RagableBrowserStorageClient;
+    readonly mail: RagableBrowserMailClient;
     readonly transport: Transport;
     private readonly _ragableAuth;
     constructor(options: RagableBrowserClientOptions);
@@ -1790,6 +2049,22 @@ declare function parseSseDataLine(line: string): SseJsonEvent | null;
  */
 declare function readSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<SseJsonEvent, void, undefined>;
 
+/**
+ * Best-effort parser for incomplete JSON streamed token-by-token from an LLM.
+ *
+ * Used by `streamObject` to emit partial objects as the model writes them.
+ * Strategy:
+ *   1. Try `JSON.parse(text)` — if it works, the JSON is already complete.
+ *   2. Otherwise scan the text and close any open `{`, `[`, or string literal
+ *      so the result is parseable.
+ *   3. If a trailing comma is the problem, strip it and retry.
+ *
+ * Returns `undefined` when no parseable prefix can be recovered.
+ *
+ * Designed to be allocation-light and dep-free.
+ */
+declare function tryParsePartialJson(text: string): unknown | undefined;
+
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends object = DefaultAuthUser>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
 
-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 GenerateTextResult, type HttpMethod, type Json, LocalStorageAdapter, 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, 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 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, 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, toRagableResult, unwrapPostgrest };
+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 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 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 };