@resultdev/sdk 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @resultdev/sdk
 
+## 0.3.1
+
+- A missing `baseUrl` now throws `MISSING_BASE_URL` at client construction
+  instead of silently falling back to a localhost dev URL. The fallback made
+  deployed sites whose `NEXT_PUBLIC_BACKEND_URL` was undefined in the
+  browser bundle (for example when the env var is read through an imported
+  `process` module, which defeats build-time inlining) call `localhost` from
+  production pages, which surfaced as Chrome's "access other apps and
+  services on this device" permission prompt. The error's fix hint names the
+  env var and the inlining rule.
+
+## 0.3.0
+
+Reliability release: every fix here comes from live verification against a
+freshly provisioned backend.
+
+- Functions: `invoke()` now goes through the main host's `/functions/{slug}`
+  route by default. The legacy subhosting fast-path was retired upstream and
+  broke browser calls entirely (its preflight 404s surfaced as
+  `TypeError: Failed to fetch`). The main route works from browsers with
+  correct CORS. In-process dispatch inside deployments is unchanged, and an
+  explicit `functionsUrl` is still honored (now with fallback to the main
+  route on network failure, not just 404).
+- Realtime: incoming `meta.channel` had a transport prefix
+  (`realtime:chat:1` for a subscription to `chat:1`), so the natural
+  `msg.meta.channel === channel` filter silently dropped every message. The
+  SDK now strips the prefix before delivery; presence join/leave tracking is
+  fixed by the same change.
+- Realtime docs: payload fields arrive spread onto the message (not under a
+  `payload` key), and the sender receives its own broadcast; dedupe with
+  `meta.messageId`.
+- AI: streaming responses now surface web-search/file citations
+  (`chunk.choices[0].delta.annotations`, trailing chunk) and token usage
+  (`chunk.usage`). Both were silently dropped before.
+- AI: deterministic bad requests fail fast with specific errors instead of
+  an opaque upstream 4xx after a round trip: unsupported audio formats
+  (browser MediaRecorder webm/opus included) and audio input on `openai/*`
+  models. Upstream provider errors on image/audio requests now name
+  `google/gemini-2.5-flash` as the verified multimodal model.
+- Docs: session model documented on `auth` (httpOnly cookie + in-memory
+  token; localStorage is empty by design), verified model names in every AI
+  example, return shapes clarified across modules.
+
 ## 0.2.0
 
 The SDK is now built fully first-party instead of wrapping a bundled

package/dist/{client-DeE086La.d.cts → client--Xjaaw1l.d.ts}

@@ -1,4 +1,4 @@
-import { e as AuthSession, U as UserSchema, a as ResultConfig, G as AuthRefreshResponse, C as ChatCompletionRequest, B as ToolCall, H as Annotation, I as ImageGenerationRequest, j as EmbeddingsRequest, J as EmbeddingObject, h as CreateUserRequest, K as CreateUserResponse, o as ResultError, g as CreateSessionRequest, L as CreateSessionResponse, l as OAuthProvidersSchema, M as RefreshSessionResponse, N as GetProfileResponse, Q as SendVerificationEmailRequest, V as VerifyEmailRequest, W as VerifyEmailResponse, X as SendResetPasswordEmailRequest, Y as ExchangeResetPasswordTokenRequest, Z as ExchangeResetPasswordTokenResponse, _ as ResetPasswordResponse, $ as GetPublicAuthConfigResponse, S as SendRawEmailRequest, q as SendEmailResponse, v as SubscribeResponse, r as SocketMessage, P as PresenceMember, u as StorageFileSchema, a0 as ListObjectsResponseSchema, i as DeleteObjectsResponse, A as Analytics, w as Support } from './types-CbsaMttt.cjs';
+import { e as AuthSession, U as UserSchema, a as ResultConfig, G as AuthRefreshResponse, C as ChatCompletionRequest, B as ToolCall, H as Annotation, I as ImageGenerationRequest, j as EmbeddingsRequest, J as EmbeddingObject, h as CreateUserRequest, K as CreateUserResponse, o as ResultError, g as CreateSessionRequest, L as CreateSessionResponse, l as OAuthProvidersSchema, M as RefreshSessionResponse, N as GetProfileResponse, Q as SendVerificationEmailRequest, V as VerifyEmailRequest, W as VerifyEmailResponse, X as SendResetPasswordEmailRequest, Y as ExchangeResetPasswordTokenRequest, Z as ExchangeResetPasswordTokenResponse, _ as ResetPasswordResponse, $ as GetPublicAuthConfigResponse, S as SendRawEmailRequest, q as SendEmailResponse, v as SubscribeResponse, r as SocketMessage, P as PresenceMember, u as StorageFileSchema, a0 as ListObjectsResponseSchema, i as DeleteObjectsResponse, A as Analytics, w as Support } from './types-BmU3deRO.js';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 import { PostgrestClient } from '@supabase/postgrest-js';
 
@@ -248,9 +248,13 @@ interface ChatCompletionChunk {
         delta: {
             content?: string;
             tool_calls?: ToolCall[];
+            /** Web-search/file citations; arrives in a trailing chunk. */
+            annotations?: Annotation[];
         };
         finish_reason: "tool_calls" | null;
     }[];
+    /** Token usage; arrives in a trailing chunk with empty choices. */
+    usage?: ChatCompletionUsage;
 }
 interface EmbeddingsResult {
     object: "list";
@@ -293,14 +297,16 @@ declare class ChatCompletions {
      * ```typescript
      * // Non-streaming
      * const completion = await client.ai.chat.completions.create({
-     *   model: 'gpt-4',
+     *   model: 'openai/gpt-4o-mini',
      *   messages: [{ role: 'user', content: 'Hello!' }]
      * });
      * console.log(completion.choices[0].message.content);
      *
-     * // With images (OpenAI-compatible format)
+     * // With images. google/gemini-2.5-flash is the verified multimodal
+     * // model (openai/gpt-4o and gpt-4o-mini also accept images, but audio
+     * // requires gemini). URLs and base64 data URIs both work.
      * const response = await client.ai.chat.completions.create({
-     *   model: 'gpt-4-vision',
+     *   model: 'google/gemini-2.5-flash',
      *   messages: [{
      *     role: 'user',
      *     content: [
@@ -310,37 +316,32 @@ declare class ChatCompletions {
      *   }]
      * });
      *
-     * // With PDF files
-     * const pdfResponse = await client.ai.chat.completions.create({
-     *   model: 'anthropic/claude-3.5-sonnet',
+     * // With audio. Base64 data in wav/mp3/aiff/aac/ogg/flac/m4a only -
+     * // browser MediaRecorder's webm/opus is rejected; record PCM via the
+     * // Web Audio API and encode a 16 kHz mono WAV instead.
+     * const audioResponse = await client.ai.chat.completions.create({
+     *   model: 'google/gemini-2.5-flash',
      *   messages: [{
      *     role: 'user',
      *     content: [
-     *       { type: 'text', text: 'Summarize this document' },
-     *       { type: 'file', file: { filename: 'doc.pdf', file_data: 'https://example.com/doc.pdf' } }
+     *       { type: 'text', text: 'Transcribe this recording' },
+     *       { type: 'input_audio', input_audio: { data: base64Wav, format: 'wav' } }
      *     ]
-     *   }],
-     *   fileParser: { enabled: true, pdf: { engine: 'mistral-ocr' } }
+     *   }]
      * });
      *
-     * // With web search
+     * // With web search. Non-streaming: citations arrive on
+     * // response.choices[0].message.annotations. Streaming: they arrive in a
+     * // trailing chunk as chunk.choices[0].delta.annotations.
      * const searchResponse = await client.ai.chat.completions.create({
-     *   model: 'openai/gpt-4',
+     *   model: 'openai/gpt-4o-mini',
      *   messages: [{ role: 'user', content: 'What are the latest news about AI?' }],
      *   webSearch: { enabled: true, maxResults: 5 }
      * });
-     * // Access citations from response.choices[0].message.annotations
-     *
-     * // With thinking/reasoning mode (Anthropic models)
-     * const thinkingResponse = await client.ai.chat.completions.create({
-     *   model: 'anthropic/claude-3.5-sonnet',
-     *   messages: [{ role: 'user', content: 'Solve this complex math problem...' }],
-     *   thinking: true
-     * });
      *
      * // Streaming - returns async iterable
      * const stream = await client.ai.chat.completions.create({
-     *   model: 'gpt-4',
+     *   model: 'openai/gpt-4o-mini',
      *   messages: [{ role: 'user', content: 'Tell me a story' }],
      *   stream: true
      * });
@@ -452,6 +453,16 @@ type OAuthSignInOptions = {
 type OAuthSignInLegacyOptions = OAuthSignInOptions & {
     provider: OAuthProvidersSchema | string;
 };
+/**
+ * Authentication client.
+ *
+ * Session model: the refresh token lives in an httpOnly cookie set by the
+ * backend (plus a CSRF cookie); the access token is held in memory and
+ * refreshed from that cookie. Nothing auth-related is written to
+ * localStorage, so an empty localStorage does NOT mean the user is signed
+ * out. Check state with getCurrentUser() or onAuthStateChange(), never by
+ * reading browser storage.
+ */
 declare class Auth {
     private http;
     private tokenManager;
@@ -748,10 +759,10 @@ declare class Functions {
     private functionsUrl;
     constructor(http: HttpClient, functionsUrl?: string);
     /**
-     * Derive the subhosting URL from the base URL.
-     * Rewrites the backend base URL to its functions subhosting URL
+     * Derive the legacy subhosting URL from the base URL
      * ({appKey}.{region}.<domain> -> {appKey}.functions.<domain>).
-     * Only applies to platform-hosted backends.
+     * Only used to recognize when a configured functionsUrl still points at
+     * the local deployment, so in-process dispatch can short-circuit it.
      */
     private static deriveSubhostingUrl;
     /**
@@ -763,11 +774,13 @@ declare class Functions {
      * Invoke an Edge Function.
      *
      * Dispatch order:
-     * 1. If the platform's in-process dispatch hook is present, call it directly.
-     *    This avoids Deno Subhosting's 508 Loop Detected when one bundled
-     *    function invokes another inside the same deployment.
-     * 2. Otherwise, try the configured subhosting URL.
-     * 3. On 404 from subhosting, fall back to the proxy path.
+     * 1. If the platform's in-process dispatch hook is present and no foreign
+     *    functionsUrl is configured, call it directly (function-to-function
+     *    calls inside the same deployment).
+     * 2. If a custom functionsUrl is configured, try it; fall back to the
+     *    proxy path on 404 or network failure.
+     * 3. Otherwise, invoke through the main host's /functions/{slug} proxy.
+     *    This route works from browsers too (correct CORS).
      *
      * @param slug The function slug to invoke
      * @param options Request options
@@ -811,7 +824,24 @@ declare class Realtime {
     get socketId(): string | undefined;
     subscribe(channel: string): Promise<SubscribeResponse>;
     unsubscribe(channel: string): void;
+    /**
+     * Publish an event to a channel.
+     *
+     * Delivery notes (verified against a live backend):
+     * - Payload fields arrive spread onto the received message itself, next to
+     *   `meta` - not nested under a `payload` key. Publishing `{ text: "hi" }`
+     *   means receivers read `msg.text`.
+     * - The sender receives its own message too. Deduplicate with
+     *   `msg.meta.messageId` (or `msg.meta.senderId`) if you also update local
+     *   state optimistically.
+     */
     publish<T = unknown>(channel: string, event: string, payload: T): Promise<void>;
+    /**
+     * Listen for an event by name, across all subscribed channels.
+     * Filter by channel inside the callback: `msg.meta.channel` always matches
+     * the exact name passed to subscribe() (the SDK strips the server's
+     * transport prefix before delivery).
+     */
     on<T = SocketMessage>(event: string, callback: EventCallback<T>): void;
     off<T = SocketMessage>(event: string, callback: EventCallback<T>): void;
     once<T = SocketMessage>(event: string, callback: EventCallback<T>): void;
@@ -966,7 +996,7 @@ type AccessTokenChangeEvent = typeof AuthChangeEvent.SIGNED_IN | typeof AuthChan
  * import { ResultClient } from '@resultdev/sdk';
  *
  * const client = new ResultClient({
- *   baseUrl: 'http://localhost:7130'
+ *   baseUrl: process.env.NEXT_PUBLIC_BACKEND_URL!
  * });
  *
  * // Authentication
@@ -997,7 +1027,7 @@ type AccessTokenChangeEvent = typeof AuthChangeEvent.SIGNED_IN | typeof AuthChan
  *
  * // Enable debug logging
  * const debugClient = new ResultClient({
- *   baseUrl: 'http://localhost:7130',
+ *   baseUrl: process.env.NEXT_PUBLIC_BACKEND_URL!,
  *   debug: true
  * });
  * ```

package/dist/{client-Z0zUHGE3.d.ts → client-BrOD2EO5.d.cts}

@@ -1,4 +1,4 @@
-import { e as AuthSession, U as UserSchema, a as ResultConfig, G as AuthRefreshResponse, C as ChatCompletionRequest, B as ToolCall, H as Annotation, I as ImageGenerationRequest, j as EmbeddingsRequest, J as EmbeddingObject, h as CreateUserRequest, K as CreateUserResponse, o as ResultError, g as CreateSessionRequest, L as CreateSessionResponse, l as OAuthProvidersSchema, M as RefreshSessionResponse, N as GetProfileResponse, Q as SendVerificationEmailRequest, V as VerifyEmailRequest, W as VerifyEmailResponse, X as SendResetPasswordEmailRequest, Y as ExchangeResetPasswordTokenRequest, Z as ExchangeResetPasswordTokenResponse, _ as ResetPasswordResponse, $ as GetPublicAuthConfigResponse, S as SendRawEmailRequest, q as SendEmailResponse, v as SubscribeResponse, r as SocketMessage, P as PresenceMember, u as StorageFileSchema, a0 as ListObjectsResponseSchema, i as DeleteObjectsResponse, A as Analytics, w as Support } from './types-CbsaMttt.js';
+import { e as AuthSession, U as UserSchema, a as ResultConfig, G as AuthRefreshResponse, C as ChatCompletionRequest, B as ToolCall, H as Annotation, I as ImageGenerationRequest, j as EmbeddingsRequest, J as EmbeddingObject, h as CreateUserRequest, K as CreateUserResponse, o as ResultError, g as CreateSessionRequest, L as CreateSessionResponse, l as OAuthProvidersSchema, M as RefreshSessionResponse, N as GetProfileResponse, Q as SendVerificationEmailRequest, V as VerifyEmailRequest, W as VerifyEmailResponse, X as SendResetPasswordEmailRequest, Y as ExchangeResetPasswordTokenRequest, Z as ExchangeResetPasswordTokenResponse, _ as ResetPasswordResponse, $ as GetPublicAuthConfigResponse, S as SendRawEmailRequest, q as SendEmailResponse, v as SubscribeResponse, r as SocketMessage, P as PresenceMember, u as StorageFileSchema, a0 as ListObjectsResponseSchema, i as DeleteObjectsResponse, A as Analytics, w as Support } from './types-BmU3deRO.cjs';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 import { PostgrestClient } from '@supabase/postgrest-js';
 
@@ -248,9 +248,13 @@ interface ChatCompletionChunk {
         delta: {
             content?: string;
             tool_calls?: ToolCall[];
+            /** Web-search/file citations; arrives in a trailing chunk. */
+            annotations?: Annotation[];
         };
         finish_reason: "tool_calls" | null;
     }[];
+    /** Token usage; arrives in a trailing chunk with empty choices. */
+    usage?: ChatCompletionUsage;
 }
 interface EmbeddingsResult {
     object: "list";
@@ -293,14 +297,16 @@ declare class ChatCompletions {
      * ```typescript
      * // Non-streaming
      * const completion = await client.ai.chat.completions.create({
-     *   model: 'gpt-4',
+     *   model: 'openai/gpt-4o-mini',
      *   messages: [{ role: 'user', content: 'Hello!' }]
      * });
      * console.log(completion.choices[0].message.content);
      *
-     * // With images (OpenAI-compatible format)
+     * // With images. google/gemini-2.5-flash is the verified multimodal
+     * // model (openai/gpt-4o and gpt-4o-mini also accept images, but audio
+     * // requires gemini). URLs and base64 data URIs both work.
      * const response = await client.ai.chat.completions.create({
-     *   model: 'gpt-4-vision',
+     *   model: 'google/gemini-2.5-flash',
      *   messages: [{
      *     role: 'user',
      *     content: [
@@ -310,37 +316,32 @@ declare class ChatCompletions {
      *   }]
      * });
      *
-     * // With PDF files
-     * const pdfResponse = await client.ai.chat.completions.create({
-     *   model: 'anthropic/claude-3.5-sonnet',
+     * // With audio. Base64 data in wav/mp3/aiff/aac/ogg/flac/m4a only -
+     * // browser MediaRecorder's webm/opus is rejected; record PCM via the
+     * // Web Audio API and encode a 16 kHz mono WAV instead.
+     * const audioResponse = await client.ai.chat.completions.create({
+     *   model: 'google/gemini-2.5-flash',
      *   messages: [{
      *     role: 'user',
      *     content: [
-     *       { type: 'text', text: 'Summarize this document' },
-     *       { type: 'file', file: { filename: 'doc.pdf', file_data: 'https://example.com/doc.pdf' } }
+     *       { type: 'text', text: 'Transcribe this recording' },
+     *       { type: 'input_audio', input_audio: { data: base64Wav, format: 'wav' } }
      *     ]
-     *   }],
-     *   fileParser: { enabled: true, pdf: { engine: 'mistral-ocr' } }
+     *   }]
      * });
      *
-     * // With web search
+     * // With web search. Non-streaming: citations arrive on
+     * // response.choices[0].message.annotations. Streaming: they arrive in a
+     * // trailing chunk as chunk.choices[0].delta.annotations.
      * const searchResponse = await client.ai.chat.completions.create({
-     *   model: 'openai/gpt-4',
+     *   model: 'openai/gpt-4o-mini',
      *   messages: [{ role: 'user', content: 'What are the latest news about AI?' }],
      *   webSearch: { enabled: true, maxResults: 5 }
      * });
-     * // Access citations from response.choices[0].message.annotations
-     *
-     * // With thinking/reasoning mode (Anthropic models)
-     * const thinkingResponse = await client.ai.chat.completions.create({
-     *   model: 'anthropic/claude-3.5-sonnet',
-     *   messages: [{ role: 'user', content: 'Solve this complex math problem...' }],
-     *   thinking: true
-     * });
      *
      * // Streaming - returns async iterable
      * const stream = await client.ai.chat.completions.create({
-     *   model: 'gpt-4',
+     *   model: 'openai/gpt-4o-mini',
      *   messages: [{ role: 'user', content: 'Tell me a story' }],
      *   stream: true
      * });
@@ -452,6 +453,16 @@ type OAuthSignInOptions = {
 type OAuthSignInLegacyOptions = OAuthSignInOptions & {
     provider: OAuthProvidersSchema | string;
 };
+/**
+ * Authentication client.
+ *
+ * Session model: the refresh token lives in an httpOnly cookie set by the
+ * backend (plus a CSRF cookie); the access token is held in memory and
+ * refreshed from that cookie. Nothing auth-related is written to
+ * localStorage, so an empty localStorage does NOT mean the user is signed
+ * out. Check state with getCurrentUser() or onAuthStateChange(), never by
+ * reading browser storage.
+ */
 declare class Auth {
     private http;
     private tokenManager;
@@ -748,10 +759,10 @@ declare class Functions {
     private functionsUrl;
     constructor(http: HttpClient, functionsUrl?: string);
     /**
-     * Derive the subhosting URL from the base URL.
-     * Rewrites the backend base URL to its functions subhosting URL
+     * Derive the legacy subhosting URL from the base URL
      * ({appKey}.{region}.<domain> -> {appKey}.functions.<domain>).
-     * Only applies to platform-hosted backends.
+     * Only used to recognize when a configured functionsUrl still points at
+     * the local deployment, so in-process dispatch can short-circuit it.
      */
     private static deriveSubhostingUrl;
     /**
@@ -763,11 +774,13 @@ declare class Functions {
      * Invoke an Edge Function.
      *
      * Dispatch order:
-     * 1. If the platform's in-process dispatch hook is present, call it directly.
-     *    This avoids Deno Subhosting's 508 Loop Detected when one bundled
-     *    function invokes another inside the same deployment.
-     * 2. Otherwise, try the configured subhosting URL.
-     * 3. On 404 from subhosting, fall back to the proxy path.
+     * 1. If the platform's in-process dispatch hook is present and no foreign
+     *    functionsUrl is configured, call it directly (function-to-function
+     *    calls inside the same deployment).
+     * 2. If a custom functionsUrl is configured, try it; fall back to the
+     *    proxy path on 404 or network failure.
+     * 3. Otherwise, invoke through the main host's /functions/{slug} proxy.
+     *    This route works from browsers too (correct CORS).
      *
      * @param slug The function slug to invoke
      * @param options Request options
@@ -811,7 +824,24 @@ declare class Realtime {
     get socketId(): string | undefined;
     subscribe(channel: string): Promise<SubscribeResponse>;
     unsubscribe(channel: string): void;
+    /**
+     * Publish an event to a channel.
+     *
+     * Delivery notes (verified against a live backend):
+     * - Payload fields arrive spread onto the received message itself, next to
+     *   `meta` - not nested under a `payload` key. Publishing `{ text: "hi" }`
+     *   means receivers read `msg.text`.
+     * - The sender receives its own message too. Deduplicate with
+     *   `msg.meta.messageId` (or `msg.meta.senderId`) if you also update local
+     *   state optimistically.
+     */
     publish<T = unknown>(channel: string, event: string, payload: T): Promise<void>;
+    /**
+     * Listen for an event by name, across all subscribed channels.
+     * Filter by channel inside the callback: `msg.meta.channel` always matches
+     * the exact name passed to subscribe() (the SDK strips the server's
+     * transport prefix before delivery).
+     */
     on<T = SocketMessage>(event: string, callback: EventCallback<T>): void;
     off<T = SocketMessage>(event: string, callback: EventCallback<T>): void;
     once<T = SocketMessage>(event: string, callback: EventCallback<T>): void;
@@ -966,7 +996,7 @@ type AccessTokenChangeEvent = typeof AuthChangeEvent.SIGNED_IN | typeof AuthChan
  * import { ResultClient } from '@resultdev/sdk';
  *
  * const client = new ResultClient({
- *   baseUrl: 'http://localhost:7130'
+ *   baseUrl: process.env.NEXT_PUBLIC_BACKEND_URL!
  * });
  *
  * // Authentication
@@ -997,7 +1027,7 @@ type AccessTokenChangeEvent = typeof AuthChangeEvent.SIGNED_IN | typeof AuthChan
  *
  * // Enable debug logging
  * const debugClient = new ResultClient({
- *   baseUrl: 'http://localhost:7130',
+ *   baseUrl: process.env.NEXT_PUBLIC_BACKEND_URL!,
  *   debug: true
  * });
  * ```