@resultdev/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @resultdev/sdk
 
+## 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-Z0zUHGE3.d.ts → client-CJv_awPt.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-DSVtGaIA.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;

package/dist/{client-DeE086La.d.cts → client-DrsZ1qIm.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-DSVtGaIA.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;

package/dist/index.cjs

@@ -1021,6 +1021,70 @@ var HttpClient = class {
 };
 
 // src/modules/ai.ts
+var SUPPORTED_AUDIO_FORMATS = [
+  "wav",
+  "mp3",
+  "aiff",
+  "aac",
+  "ogg",
+  "flac",
+  "m4a"
+];
+var MULTIMODAL_MODEL = "google/gemini-2.5-flash";
+function summarizeContent(messages) {
+  const summary = {
+    hasImage: false,
+    hasAudio: false,
+    badAudioFormats: []
+  };
+  for (const message of messages) {
+    if (message.images?.length) {
+      summary.hasImage = true;
+    }
+    if (!Array.isArray(message.content)) {
+      continue;
+    }
+    for (const part of message.content) {
+      if (part?.type === "image_url") {
+        summary.hasImage = true;
+      } else if (part?.type === "input_audio") {
+        summary.hasAudio = true;
+        const format2 = part.input_audio?.format;
+        if (format2 && !SUPPORTED_AUDIO_FORMATS.includes(format2)) {
+          summary.badAudioFormats.push(format2);
+        }
+      }
+    }
+  }
+  return summary;
+}
+function assertSupportedContent(model, summary) {
+  if (summary.badAudioFormats.length) {
+    throw new ResultError(
+      `Audio format "${summary.badAudioFormats[0]}" is not supported. Supported formats: ${SUPPORTED_AUDIO_FORMATS.join(", ")}. Browser MediaRecorder produces webm/opus, which the gateway rejects - capture PCM with the Web Audio API and encode a 16 kHz mono WAV instead.`,
+      400,
+      "AI_INVALID_INPUT"
+    );
+  }
+  if (summary.hasAudio && model.startsWith("openai/")) {
+    throw new ResultError(
+      `Model "${model}" does not accept audio input on this gateway. Use ${MULTIMODAL_MODEL} (verified for audio).`,
+      400,
+      "AI_INVALID_INPUT"
+    );
+  }
+}
+function enrichUpstreamError(error, summary) {
+  if (!(error instanceof ResultError) || error.error !== "AI_UPSTREAM_UNAVAILABLE" || !summary.hasImage && !summary.hasAudio) {
+    return error;
+  }
+  const kind = summary.hasImage && summary.hasAudio ? "image and audio" : summary.hasImage ? "image" : "audio";
+  return new ResultError(
+    `${error.message} This request included ${kind} input; if the error persists, use ${MULTIMODAL_MODEL} (verified for vision and audio).`,
+    error.statusCode,
+    error.error
+  );
+}
 var AI = class {
   chat;
   images;
@@ -1043,6 +1107,8 @@ var ChatCompletions = class {
   }
   http;
   async create(params) {
+    const contentSummary = summarizeContent(params.messages ?? []);
+    assertSupportedContent(params.model, contentSummary);
     const backendParams = {
       model: params.model,
       messages: params.messages,
@@ -1071,15 +1137,28 @@ var ChatCompletions = class {
         }
       );
       if (!response2.ok) {
-        const error = await response2.json();
-        throw new Error(error.error || "Stream request failed");
+        let body = null;
+        try {
+          body = await response2.json();
+        } catch {
+        }
+        throw enrichUpstreamError(
+          new ResultError(
+            body?.message || body?.error || "Stream request failed",
+            body?.statusCode ?? response2.status,
+            body?.error || "AI_STREAM_ERROR"
+          ),
+          contentSummary
+        );
       }
       return this.parseSSEStream(response2, params.model);
     }
-    const response = await this.http.post(
-      "/api/ai/chat/completion",
-      backendParams
-    );
+    let response;
+    try {
+      response = await this.http.post("/api/ai/chat/completion", backendParams);
+    } catch (error) {
+      throw enrichUpstreamError(error, contentSummary);
+    }
     const content = response.text || "";
     return {
       id: `chatcmpl-${Date.now()}`,
@@ -1174,6 +1253,37 @@ var ChatCompletions = class {
                     ]
                   };
                 }
+                if (data.annotations?.length) {
+                  yield {
+                    id: `chatcmpl-${Date.now()}`,
+                    object: "chat.completion.chunk",
+                    created: Math.floor(Date.now() / 1e3),
+                    model,
+                    choices: [
+                      {
+                        index: 0,
+                        delta: {
+                          annotations: data.annotations
+                        },
+                        finish_reason: null
+                      }
+                    ]
+                  };
+                }
+                if (data.tokenUsage) {
+                  yield {
+                    id: `chatcmpl-${Date.now()}`,
+                    object: "chat.completion.chunk",
+                    created: Math.floor(Date.now() / 1e3),
+                    model,
+                    choices: [],
+                    usage: {
+                      prompt_tokens: data.tokenUsage.promptTokens || 0,
+                      completion_tokens: data.tokenUsage.completionTokens || 0,
+                      total_tokens: data.tokenUsage.totalTokens || 0
+                    }
+                  };
+                }
                 if (data.done) {
                   reader.releaseLock();
                   return;
@@ -2410,13 +2520,13 @@ var Functions = class _Functions {
   functionsUrl;
   constructor(http, functionsUrl) {
     this.http = http;
-    this.functionsUrl = functionsUrl || _Functions.deriveSubhostingUrl(http.baseUrl);
+    this.functionsUrl = functionsUrl;
   }
   /**
-   * 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.
    */
   static deriveSubhostingUrl(baseUrl) {
     try {
@@ -2449,11 +2559,13 @@ var Functions = 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
@@ -2462,7 +2574,7 @@ var Functions = class _Functions {
     const { method = "POST", body, headers = {} } = options;
     const dispatch = globalThis.__insforge_dispatch__;
     const localFunctionsUrl = _Functions.deriveSubhostingUrl(this.http.baseUrl);
-    if (typeof dispatch === "function" && !!localFunctionsUrl && this.functionsUrl === localFunctionsUrl) {
+    if (typeof dispatch === "function" && (this.functionsUrl === void 0 || !!localFunctionsUrl && this.functionsUrl === localFunctionsUrl)) {
       try {
         const req = this.buildInProcessRequest(slug, method, body, headers);
         const res = await dispatch(req);
@@ -2497,7 +2609,8 @@ var Functions = class _Functions {
         if (error instanceof Error && error.name === "AbortError") {
           throw error;
         }
-        if (error instanceof ResultError && error.statusCode === 404) {
+        const unreachable = error instanceof ResultError && (error.statusCode === 404 || error.statusCode === 0);
+        if (unreachable) {
         } else {
           return {
             data: null,
@@ -2533,6 +2646,17 @@ var Functions = class _Functions {
 // src/modules/realtime.ts
 var CONNECT_TIMEOUT = 1e4;
 var SUBSCRIBE_TIMEOUT = 1e4;
+var CHANNEL_PREFIX = "realtime:";
+function normalizeChannelMeta(message) {
+  const channel = message?.meta?.channel;
+  if (typeof channel !== "string" || !channel.startsWith(CHANNEL_PREFIX)) {
+    return message;
+  }
+  return {
+    ...message,
+    meta: { ...message.meta, channel: channel.slice(CHANNEL_PREFIX.length) }
+  };
+}
 var Realtime = class {
   constructor(baseUrl, tokenManager, anonKey, getValidAccessToken = async () => tokenManager.getAccessToken()) {
     this.baseUrl = baseUrl;
@@ -2654,8 +2778,9 @@ var Realtime = class {
           if (event === "realtime:error") {
             return;
           }
-          this.applyPresenceEvent(event, message);
-          this.notifyListeners(event, message);
+          const normalized = normalizeChannelMeta(message);
+          this.applyPresenceEvent(event, normalized);
+          this.notifyListeners(event, normalized);
         };
         this.connectionAttempt = { id: attemptId, socket, cancel: fail };
         socket.on("connect", onConnect);
@@ -2903,6 +3028,17 @@ var Realtime = class {
       this.socket.emit("realtime:unsubscribe", { channel });
     }
   }
+  /**
+   * 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.
+   */
   async publish(channel, event, payload) {
     if (!this.socket?.connected) {
       throw new Error(
@@ -2911,6 +3047,12 @@ var Realtime = class {
     }
     this.socket.emit("realtime:publish", { channel, event, payload });
   }
+  /**
+   * 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(event, callback) {
     const listeners = this.eventListeners.get(event) ?? /* @__PURE__ */ new Set();
     listeners.add(callback);

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { R as ResultClient } from './client-DeE086La.cjs';
-export { A as AI, a as AccessTokenChangeEvent, b as Auth, c as AuthChangeEvent, d as AuthStateChangeCallback, C as ChatCompletion, e as ChatCompletionChoice, f as ChatCompletionChunk, g as ChatCompletionUsage, h as ConnectionState, D as Database, E as Emails, i as EmbeddingsResult, j as EventCallback, F as FunctionInvokeOptions, k as Functions, H as HttpClient, I as ImageGenerationResult, L as Logger, l as Realtime, S as Storage, m as StorageBucket, n as StorageResponse } from './client-DeE086La.cjs';
-import { R as ResultAdminConfig, a as ResultConfig } from './types-CbsaMttt.cjs';
-export { A as Analytics, b as AnalyticsOptions, c as ApiError, d as AuthErrorResponse, e as AuthSession, C as ChatCompletionRequest, f as ChatMessageSchema, g as CreateSessionRequest, h as CreateUserRequest, D as DeleteObjectResult, i as DeleteObjectsResponse, E as ERROR_CODES, j as EmbeddingsRequest, k as ErrorCode, I as ImageGenerationRequest, O as OAUTH_PROVIDERS, l as OAuthProvidersSchema, P as PresenceMember, m as ProfileSchema, n as RealtimeErrorPayload, o as ResultError, p as ResultErrorCode, S as SendEmailOptions, q as SendEmailResponse, r as SocketMessage, s as StartThreadOptions, t as StartedThread, u as StorageFileSchema, v as SubscribeResponse, w as Support, x as SupportMessage, y as SupportOptions, z as SupportThread, T as Tool, B as ToolCall, F as ToolChoice, U as UserSchema } from './types-CbsaMttt.cjs';
+import { R as ResultClient } from './client-CJv_awPt.cjs';
+export { A as AI, a as AccessTokenChangeEvent, b as Auth, c as AuthChangeEvent, d as AuthStateChangeCallback, C as ChatCompletion, e as ChatCompletionChoice, f as ChatCompletionChunk, g as ChatCompletionUsage, h as ConnectionState, D as Database, E as Emails, i as EmbeddingsResult, j as EventCallback, F as FunctionInvokeOptions, k as Functions, H as HttpClient, I as ImageGenerationResult, L as Logger, l as Realtime, S as Storage, m as StorageBucket, n as StorageResponse } from './client-CJv_awPt.cjs';
+import { R as ResultAdminConfig, a as ResultConfig } from './types-DSVtGaIA.cjs';
+export { A as Analytics, b as AnalyticsOptions, c as ApiError, d as AuthErrorResponse, e as AuthSession, C as ChatCompletionRequest, f as ChatMessageSchema, g as CreateSessionRequest, h as CreateUserRequest, D as DeleteObjectResult, i as DeleteObjectsResponse, E as ERROR_CODES, j as EmbeddingsRequest, k as ErrorCode, I as ImageGenerationRequest, O as OAUTH_PROVIDERS, l as OAuthProvidersSchema, P as PresenceMember, m as ProfileSchema, n as RealtimeErrorPayload, o as ResultError, p as ResultErrorCode, S as SendEmailOptions, q as SendEmailResponse, r as SocketMessage, s as StartThreadOptions, t as StartedThread, u as StorageFileSchema, v as SubscribeResponse, w as Support, x as SupportMessage, y as SupportOptions, z as SupportThread, T as Tool, B as ToolCall, F as ToolChoice, U as UserSchema } from './types-DSVtGaIA.cjs';
 import '@supabase/postgrest-js';
 
 /**