feat(client): pass normalized app+path to TokenProvider

libs/client/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fal-ai/client",
   "description": "The fal.ai client for JavaScript and TypeScript",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "license": "MIT",
   "repository": {
     "type": "git",

libs/client/src/auth.ts

@@ -4,7 +4,7 @@
 
 /**
  * A function that provides a temporary authentication token.
- * @param app - The app/endpoint identifier
+ * @param app - The app/endpoint identifier, including the path (e.g. "fal-ai/myapp/realtime")
  * @returns A promise that resolves to the token string
  */
 export type TokenProvider = (app: string) => Promise<string>;
@@ -19,7 +19,7 @@
   config: RequiredConfig,
 ): Promise<string> {
   const appId = parseEndpointId(app);
   const token: string | object = await dispatchRequest<any, string>({
     method: "POST",
     targetUrl: `${getRestApiUrl()}/tokens/`,
     config,

libs/client/src/realtime.spec.ts

@@ -15,9 +15,9 @@
 class MockWebSocket {
   public readonly url: string;
   public onopen?: () => void;
   public onclose?: (event: any) => void;
   public onerror?: (event: any) => void;
   public onmessage?: (event: any) => void;
   public readyState = MockWebSocket.CONNECTING;
   public readonly send = jest.fn();
   public readonly close = jest.fn();
@@ -48,7 +48,7 @@
   beforeAll(() => {
     // minimal fetch stub to satisfy createConfig
     // eslint-disable-next-line @typescript-eslint/no-empty-function
     global.fetch = jest.fn(() => {}) as any;
   });
 
   beforeEach(() => {
@@ -64,14 +64,14 @@
     // eslint-disable-next-line @typescript-eslint/no-empty-function
     jest.spyOn(console, "warn").mockImplementation(() => {});
     // Provide a minimal crypto polyfill for randomUUID used by the client
     (global as any).crypto = {
       randomUUID: () => "00000000-0000-0000-0000-000000000000",
     };
     // @ts-expect-error override global
     global.WebSocket = WebSocketMock;
     config = createConfig({
       credentials: "test-key",
       fetch: global.fetch as any,
     });
   });
 
@@ -333,7 +333,7 @@
     await Promise.resolve();
 
     expect(customTokenProvider).toHaveBeenCalledTimes(1);
-    expect(customTokenProvider).toHaveBeenCalledWith("123-myapp");
+    expect(customTokenProvider).toHaveBeenCalledWith("123/myapp/realtime");
     expect(getTemporaryAuthToken).not.toHaveBeenCalled();
 
     expect(WebSocketMock).toHaveBeenCalledTimes(1);
@@ -359,7 +359,7 @@
     await Promise.resolve();
     await Promise.resolve();
 
-    expect(customTokenProvider).toHaveBeenCalledWith("456-otherapp");
+    expect(customTokenProvider).toHaveBeenCalledWith("456/otherapp/realtime");
     expect(getTemporaryAuthToken).not.toHaveBeenCalled();
   });
 

libs/client/src/realtime.ts

@@ -20,7 +20,12 @@
 import { RequiredConfig } from "./config";
 import { ApiError } from "./response";
 import { isBrowser } from "./runtime";
-import { ensureEndpointIdFormat, isReact, throttle } from "./utils";
+import {
+  ensureEndpointIdFormat,
+  isReact,
+  resolveEndpointPath,
+  throttle,
+} from "./utils";
 
 // Define the context
 interface Context {
@@ -312,8 +317,8 @@
     queryParams.set("max_buffering", maxBuffering.toFixed(0));
   }
   const appId = ensureEndpointIdFormat(app);
-  const normalizedPath = path ? `/${path.replace(/^\/+/, "")}` : "/realtime";
-  return `wss://fal.run/${appId}${normalizedPath}?${queryParams.toString()}`;
+  const resolvedPath = resolveEndpointPath(app, path, "/realtime") ?? "";
+  return `wss://fal.run/${appId}${resolvedPath}?${queryParams.toString()}`;
 }
 
 const DEFAULT_THROTTLE_INTERVAL = 128;
@@ -567,8 +572,11 @@
           ) {
             send({ type: "initiateAuth" });
             // Use custom tokenProvider if provided, otherwise use default
+            const appId = ensureEndpointIdFormat(app);
+            const resolvedPath =
+              resolveEndpointPath(app, path, "/realtime") ?? "";
             const fetchToken = tokenProvider
-              ? () => tokenProvider(app)
+              ? () => tokenProvider(`${appId}${resolvedPath}`)
               : () => {
                   console.warn(
                     "[fal.realtime] Using the default token provider is deprecated. " +
@@ -640,7 +648,7 @@
               }
               send({ type: "connectionClosed", code: event.code });
             };
             ws.onerror = (event) => {
               // TODO specify error protocol for identified errors
               const { onError = noop } = getCallbacks();
               onError(new ApiError({ message: "Unknown error", status: 500 }));

libs/client/src/streaming.ts

@@ -5,6 +5,7 @@ import { buildUrl, dispatchRequest } from "./request";
 import { ApiError, defaultResponseHandler } from "./response";
 import { type StorageClient } from "./storage";
 import { EndpointType, InputType, OutputType } from "./types/client";
+import { ensureEndpointIdFormat, resolveEndpointPath } from "./utils";
 
 export type StreamingConnectionMode = "client" | "server";
 
@@ -116,7 +117,7 @@ export class FalStream<Input, Output> {
     this.url =
       options.url ??
       buildUrl(endpointId, {
-        path: "/stream",
+        path: resolveEndpointPath(endpointId, undefined, "/stream"),
         query: options.queryParams,
       });
     this.options = options;
@@ -166,8 +167,11 @@ export class FalStream<Input, Output> {
       if (connectionMode === "client") {
         // if we are in the browser, we need to get a temporary token
         // to authenticate the request
+        const appId = ensureEndpointIdFormat(endpointId);
+        const resolvedPath =
+          resolveEndpointPath(endpointId, undefined, "/stream") ?? "";
         const fetchToken = tokenProvider
-          ? () => tokenProvider(endpointId)
+          ? () => tokenProvider(`${appId}${resolvedPath}`)
           : () => {
               console.warn(
                 "[fal.stream] Using the default token provider is deprecated. " +

libs/client/src/utils.ts

@@ -41,6 +41,30 @@ export function parseEndpointId(id: string): EndpointId {
   };
 }
 
+/**
+ * Resolves the endpoint path, normalizing it and applying a default.
+ * If no explicit path is provided and the app already ends with the
+ * default path, returns undefined to avoid duplication.
+ *
+ * @param app - The app/endpoint identifier
+ * @param path - An explicitly provided path (always used if present)
+ * @param defaultPath - The default path to use (e.g. "/realtime")
+ * @returns The resolved path, or undefined if the app already includes it
+ */
+export function resolveEndpointPath(
+  app: string,
+  path: string | undefined,
+  defaultPath: string,
+): string | undefined {
+  if (path) {
+    return `/${path.replace(/^\/+/, "")}`;
+  }
+  if (app.endsWith(defaultPath)) {
+    return undefined;
+  }
+  return defaultPath;
+}
+
 export function isValidUrl(url: string) {
   try {
     const { host } = new URL(url);