@resultdev/sdk 0.2.0 → 0.3.1

package/dist/ssr.cjs

@@ -690,7 +690,15 @@ var HttpClient = class {
    */
   constructor(config, tokenManager, logger) {
     this.config = config;
-    this.baseUrl = config.baseUrl || "http://localhost:7130";
+    if (!config.baseUrl) {
+      throw new ResultError(
+        "createClient needs a baseUrl, but it was undefined at runtime.",
+        0,
+        "MISSING_BASE_URL",
+        "Pass the NEXT_PUBLIC_BACKEND_URL value from .env.local. In browser code, write process.env.NEXT_PUBLIC_BACKEND_URL as a literal expression (never through an imported process module) so the bundler inlines it, and set it as a deployments build variable before deploying."
+      );
+    }
+    this.baseUrl = config.baseUrl;
     this.fetch = config.fetch || (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
     this.anonKey = config.anonKey;
     this.defaultHeaders = {
@@ -1208,6 +1216,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;
@@ -1230,6 +1302,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,
@@ -1258,15 +1332,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()}`,
@@ -1361,6 +1448,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;
@@ -2597,13 +2715,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 {
@@ -2636,11 +2754,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
@@ -2649,7 +2769,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);
@@ -2684,7 +2804,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,
@@ -2720,6 +2841,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;
@@ -2841,8 +2973,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);
@@ -3090,6 +3223,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(
@@ -3098,6 +3242,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/ssr.d.cts

@@ -1,7 +1,7 @@
-import { R as ResultClient } from './client-DeE086La.cjs';
-import { o as ResultError, a as ResultConfig, G as AuthRefreshResponse } from './types-CbsaMttt.cjs';
-import { A as AuthCookieSettings, C as CookieStore, a as CookieWriter } from './middleware-BBY_6hyx.cjs';
-export { b as AuthCookieNames, c as AuthCookieOptions, d as CookieOptions, e as CookieReader, D as DEFAULT_ACCESS_TOKEN_COOKIE, f as DEFAULT_REFRESH_TOKEN_COOKIE, U as UpdateSessionOptions, g as UpdateSessionResult, h as accessTokenCookieOptions, i as clearAuthCookies, j as getAccessTokenCookieName, k as getRefreshTokenCookieName, r as refreshTokenCookieOptions, s as setAuthCookies, u as updateSession } from './middleware-BBY_6hyx.cjs';
+import { R as ResultClient } from './client-BrOD2EO5.cjs';
+import { o as ResultError, a as ResultConfig, G as AuthRefreshResponse } from './types-BmU3deRO.cjs';
+import { A as AuthCookieSettings, C as CookieStore, a as CookieWriter } from './middleware-VCWoai4o.cjs';
+export { b as AuthCookieNames, c as AuthCookieOptions, d as CookieOptions, e as CookieReader, D as DEFAULT_ACCESS_TOKEN_COOKIE, f as DEFAULT_REFRESH_TOKEN_COOKIE, U as UpdateSessionOptions, g as UpdateSessionResult, h as accessTokenCookieOptions, i as clearAuthCookies, j as getAccessTokenCookieName, k as getRefreshTokenCookieName, r as refreshTokenCookieOptions, s as setAuthCookies, u as updateSession } from './middleware-VCWoai4o.cjs';
 import '@supabase/postgrest-js';
 
 interface CreateAuthActionsOptions extends Omit<ResultConfig, "accessToken" | "edgeFunctionToken" | "isServerMode" | "auth">, AuthCookieSettings {

package/dist/ssr.d.ts

@@ -1,7 +1,7 @@
-import { R as ResultClient } from './client-Z0zUHGE3.js';
-import { o as ResultError, a as ResultConfig, G as AuthRefreshResponse } from './types-CbsaMttt.js';
-import { A as AuthCookieSettings, C as CookieStore, a as CookieWriter } from './middleware-TGaDOhE9.js';
-export { b as AuthCookieNames, c as AuthCookieOptions, d as CookieOptions, e as CookieReader, D as DEFAULT_ACCESS_TOKEN_COOKIE, f as DEFAULT_REFRESH_TOKEN_COOKIE, U as UpdateSessionOptions, g as UpdateSessionResult, h as accessTokenCookieOptions, i as clearAuthCookies, j as getAccessTokenCookieName, k as getRefreshTokenCookieName, r as refreshTokenCookieOptions, s as setAuthCookies, u as updateSession } from './middleware-TGaDOhE9.js';
+import { R as ResultClient } from './client--Xjaaw1l.js';
+import { o as ResultError, a as ResultConfig, G as AuthRefreshResponse } from './types-BmU3deRO.js';
+import { A as AuthCookieSettings, C as CookieStore, a as CookieWriter } from './middleware-Uh09_lFn.js';
+export { b as AuthCookieNames, c as AuthCookieOptions, d as CookieOptions, e as CookieReader, D as DEFAULT_ACCESS_TOKEN_COOKIE, f as DEFAULT_REFRESH_TOKEN_COOKIE, U as UpdateSessionOptions, g as UpdateSessionResult, h as accessTokenCookieOptions, i as clearAuthCookies, j as getAccessTokenCookieName, k as getRefreshTokenCookieName, r as refreshTokenCookieOptions, s as setAuthCookies, u as updateSession } from './middleware-Uh09_lFn.js';
 import '@supabase/postgrest-js';
 
 interface CreateAuthActionsOptions extends Omit<ResultConfig, "accessToken" | "edgeFunctionToken" | "isServerMode" | "auth">, AuthCookieSettings {

package/dist/ssr.js

@@ -641,7 +641,15 @@ var HttpClient = class {
    */
   constructor(config, tokenManager, logger) {
     this.config = config;
-    this.baseUrl = config.baseUrl || "http://localhost:7130";
+    if (!config.baseUrl) {
+      throw new ResultError(
+        "createClient needs a baseUrl, but it was undefined at runtime.",
+        0,
+        "MISSING_BASE_URL",
+        "Pass the NEXT_PUBLIC_BACKEND_URL value from .env.local. In browser code, write process.env.NEXT_PUBLIC_BACKEND_URL as a literal expression (never through an imported process module) so the bundler inlines it, and set it as a deployments build variable before deploying."
+      );
+    }
+    this.baseUrl = config.baseUrl;
     this.fetch = config.fetch || (globalThis.fetch ? globalThis.fetch.bind(globalThis) : void 0);
     this.anonKey = config.anonKey;
     this.defaultHeaders = {
@@ -1159,6 +1167,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;
@@ -1181,6 +1253,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,
@@ -1209,15 +1283,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()}`,
@@ -1312,6 +1399,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;
@@ -2548,13 +2666,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 {
@@ -2587,11 +2705,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
@@ -2600,7 +2720,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);
@@ -2635,7 +2755,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,
@@ -2671,6 +2792,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;
@@ -2792,8 +2924,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);
@@ -3041,6 +3174,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(
@@ -3049,6 +3193,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/{types-CbsaMttt.d.cts → types-BmU3deRO.d.cts}

@@ -498,13 +498,21 @@ interface RealtimeErrorPayload {
     message: string;
 }
 interface SocketMessageMeta {
-    /** Present for room broadcasts. */
+    /**
+     * Present for room broadcasts. Matches the exact channel name passed to
+     * subscribe() - the SDK strips the server's transport prefix on delivery.
+     */
     channel?: string;
     messageId: string;
     senderType: SenderType;
     senderId?: string;
     timestamp: string;
 }
+/**
+ * A received realtime message. The published payload's fields arrive spread
+ * onto this object next to `meta` (publish `{ text: "hi" }`, read
+ * `msg.text`) - there is no `payload` wrapper key.
+ */
 interface SocketMessage {
     meta: SocketMessageMeta;
     [key: string]: unknown;
@@ -518,8 +526,9 @@ interface SocketMessage {
 type ResultErrorCode = ErrorCode | (string & {});
 interface ResultConfig {
     /**
-     * The base URL of the Result backend API
-     * @default "http://localhost:7130"
+     * The base URL of the Result backend API (the NEXT_PUBLIC_BACKEND_URL
+     * value from .env.local). Required at runtime: constructing a client
+     * without it throws MISSING_BASE_URL.
      */
     baseUrl?: string;
     /**

package/dist/{types-CbsaMttt.d.ts → types-BmU3deRO.d.ts}

@@ -498,13 +498,21 @@ interface RealtimeErrorPayload {
     message: string;
 }
 interface SocketMessageMeta {
-    /** Present for room broadcasts. */
+    /**
+     * Present for room broadcasts. Matches the exact channel name passed to
+     * subscribe() - the SDK strips the server's transport prefix on delivery.
+     */
     channel?: string;
     messageId: string;
     senderType: SenderType;
     senderId?: string;
     timestamp: string;
 }
+/**
+ * A received realtime message. The published payload's fields arrive spread
+ * onto this object next to `meta` (publish `{ text: "hi" }`, read
+ * `msg.text`) - there is no `payload` wrapper key.
+ */
 interface SocketMessage {
     meta: SocketMessageMeta;
     [key: string]: unknown;
@@ -518,8 +526,9 @@ interface SocketMessage {
 type ResultErrorCode = ErrorCode | (string & {});
 interface ResultConfig {
     /**
-     * The base URL of the Result backend API
-     * @default "http://localhost:7130"
+     * The base URL of the Result backend API (the NEXT_PUBLIC_BACKEND_URL
+     * value from .env.local). Required at runtime: constructing a client
+     * without it throws MISSING_BASE_URL.
      */
     baseUrl?: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resultdev/sdk",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Result Backend SDK - authentication, database, storage, functions, realtime, AI, email, web analytics and customer support for apps built on Result.",
   "license": "UNLICENSED",
   "homepage": "https://docs.result.dev",