@navai/voice-frontend 0.1.0 → 0.1.2

package/dist/index.js

@@ -240,6 +240,8 @@ function getNavaiRoutePromptLines(routes = []) {
 }
 
 // src/agent.ts
+var RESERVED_TOOL_NAMES = /* @__PURE__ */ new Set(["navigate_to", "execute_app_function"]);
+var TOOL_NAME_REGEXP = /^[a-zA-Z0-9_-]{1,64}$/;
 function toErrorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -274,6 +276,76 @@ async function buildNavaiAgent(options) {
     ...functionsRegistry.ordered.map((item) => item.name),
     ...backendFunctionsOrdered.map((item) => item.name)
   ];
+  const aliasWarnings = [];
+  const directFunctionToolNames = [...new Set(availableFunctionNames)].map((name) => name.trim().toLowerCase()).filter((name) => {
+    if (!name) {
+      return false;
+    }
+    if (RESERVED_TOOL_NAMES.has(name)) {
+      aliasWarnings.push(
+        `[navai] Function "${name}" is available only via execute_app_function because its name conflicts with a built-in tool.`
+      );
+      return false;
+    }
+    if (!TOOL_NAME_REGEXP.test(name)) {
+      aliasWarnings.push(
+        `[navai] Function "${name}" is available only via execute_app_function because its name is not a valid tool id.`
+      );
+      return false;
+    }
+    return true;
+  });
+  const executeAppFunction = async (requestedName, payload) => {
+    const requested = requestedName.trim().toLowerCase();
+    const frontendDefinition = functionsRegistry.byName.get(requested);
+    if (frontendDefinition) {
+      try {
+        const result = await frontendDefinition.run(payload ?? {}, options);
+        return { ok: true, function_name: frontendDefinition.name, source: frontendDefinition.source, result };
+      } catch (error) {
+        return {
+          ok: false,
+          function_name: frontendDefinition.name,
+          error: "Function execution failed.",
+          details: toErrorMessage2(error)
+        };
+      }
+    }
+    const backendDefinition = backendFunctionsByName.get(requested);
+    if (!backendDefinition) {
+      return {
+        ok: false,
+        error: "Unknown or disallowed function.",
+        available_functions: availableFunctionNames
+      };
+    }
+    if (!options.executeBackendFunction) {
+      return {
+        ok: false,
+        function_name: backendDefinition.name,
+        error: "Backend function execution is not configured."
+      };
+    }
+    try {
+      const result = await options.executeBackendFunction({
+        functionName: backendDefinition.name,
+        payload: payload ?? null
+      });
+      return {
+        ok: true,
+        function_name: backendDefinition.name,
+        source: backendDefinition.source ?? "backend",
+        result
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        function_name: backendDefinition.name,
+        error: "Function execution failed.",
+        details: toErrorMessage2(error)
+      };
+    }
+  };
   const navigateTool = tool({
     name: "navigate_to",
     description: "Navigate to an allowed route in the current app.",
@@ -298,58 +370,20 @@ async function buildNavaiAgent(options) {
         "Payload object. Use null when no arguments are needed. Use payload.args as array for function args, payload.constructorArgs for class constructors, payload.methodArgs for class methods."
       )
     }),
-    execute: async ({ function_name, payload }) => {
-      const requested = function_name.trim().toLowerCase();
-      const frontendDefinition = functionsRegistry.byName.get(requested);
-      if (frontendDefinition) {
-        try {
-          const result = await frontendDefinition.run(payload ?? {}, options);
-          return { ok: true, function_name: frontendDefinition.name, source: frontendDefinition.source, result };
-        } catch (error) {
-          return {
-            ok: false,
-            function_name: frontendDefinition.name,
-            error: "Function execution failed.",
-            details: toErrorMessage2(error)
-          };
-        }
-      }
-      const backendDefinition = backendFunctionsByName.get(requested);
-      if (!backendDefinition) {
-        return {
-          ok: false,
-          error: "Unknown or disallowed function.",
-          available_functions: availableFunctionNames
-        };
-      }
-      if (!options.executeBackendFunction) {
-        return {
-          ok: false,
-          function_name: backendDefinition.name,
-          error: "Backend function execution is not configured."
-        };
-      }
-      try {
-        const result = await options.executeBackendFunction({
-          functionName: backendDefinition.name,
-          payload: payload ?? null
-        });
-        return {
-          ok: true,
-          function_name: backendDefinition.name,
-          source: backendDefinition.source ?? "backend",
-          result
-        };
-      } catch (error) {
-        return {
-          ok: false,
-          function_name: backendDefinition.name,
-          error: "Function execution failed.",
-          details: toErrorMessage2(error)
-        };
-      }
-    }
+    execute: async ({ function_name, payload }) => await executeAppFunction(function_name, payload)
   });
+  const directFunctionTools = directFunctionToolNames.map(
+    (functionName) => tool({
+      name: functionName,
+      description: `Direct alias for execute_app_function("${functionName}").`,
+      parameters: z.object({
+        payload: z.record(z.string(), z.unknown()).nullable().optional().describe(
+          "Payload object. Optional. Use payload.args as array for function args, payload.constructorArgs for class constructors, payload.methodArgs for class methods."
+        )
+      }),
+      execute: async ({ payload }) => await executeAppFunction(functionName, payload ?? null)
+    })
+  );
   const routeLines = getNavaiRoutePromptLines(options.routes);
   const functionLines = functionsRegistry.ordered.length + backendFunctionsOrdered.length > 0 ? [
     ...functionsRegistry.ordered.map((item) => `- ${item.name}: ${item.description}`),
@@ -365,7 +399,7 @@ async function buildNavaiAgent(options) {
     ...functionLines,
     "Rules:",
     "- If user asks to go/open a section, always call navigate_to.",
-    "- If user asks to run an internal action, always call execute_app_function.",
+    "- If user asks to run an internal action, call execute_app_function or the matching direct function tool.",
     "- Always include payload in execute_app_function. Use null when no arguments are needed.",
     "- For execute_app_function, pass arguments using payload.args (array).",
     "- For class methods, pass payload.constructorArgs and payload.methodArgs.",
@@ -375,9 +409,9 @@ async function buildNavaiAgent(options) {
   const agent = new RealtimeAgent({
     name: options.agentName ?? "Navai Voice Agent",
     instructions,
-    tools: [navigateTool, executeFunctionTool]
+    tools: [navigateTool, executeFunctionTool, ...directFunctionTools]
   });
-  return { agent, warnings: [...functionsRegistry.warnings, ...backendWarnings] };
+  return { agent, warnings: [...functionsRegistry.warnings, ...backendWarnings, ...aliasWarnings] };
 }
 
 // src/backend.ts
@@ -675,11 +709,183 @@ function readOptional2(value) {
 function toErrorMessage3(error) {
   return error instanceof Error ? error.message : String(error);
 }
+
+// src/useWebVoiceAgent.ts
+import { RealtimeSession } from "@openai/agents/realtime";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+function emitWarnings(warnings) {
+  for (const warning of warnings) {
+    if (warning.trim().length > 0) {
+      console.warn(warning);
+    }
+  }
+}
+function useWebVoiceAgent(options) {
+  const sessionRef = useRef(null);
+  const attachedRealtimeSessionRef = useRef(null);
+  const runtimeConfigPromise = useMemo(
+    () => resolveNavaiFrontendRuntimeConfig({
+      moduleLoaders: options.moduleLoaders,
+      defaultRoutes: options.defaultRoutes,
+      env: options.env,
+      routesFile: options.routesFile,
+      functionsFolders: options.functionsFolders,
+      modelOverride: options.modelOverride,
+      defaultRoutesFile: options.defaultRoutesFile,
+      defaultFunctionsFolder: options.defaultFunctionsFolder
+    }),
+    [
+      options.defaultFunctionsFolder,
+      options.defaultRoutes,
+      options.defaultRoutesFile,
+      options.env,
+      options.functionsFolders,
+      options.modelOverride,
+      options.moduleLoaders,
+      options.routesFile
+    ]
+  );
+  const backendClient = useMemo(
+    () => createNavaiBackendClient({
+      ...options.apiBaseUrl ? { apiBaseUrl: options.apiBaseUrl } : {},
+      env: options.env
+    }),
+    [options.apiBaseUrl, options.env]
+  );
+  const [status, setStatus] = useState("idle");
+  const [agentVoiceState, setAgentVoiceState] = useState("idle");
+  const [error, setError] = useState(null);
+  const setAgentVoiceStateIfChanged = useCallback((next) => {
+    setAgentVoiceState((current) => current === next ? current : next);
+  }, []);
+  const handleSessionAudioStart = useCallback(() => {
+    setAgentVoiceStateIfChanged("speaking");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionAudioStopped = useCallback(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionAudioInterrupted = useCallback(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionError = useCallback(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const detachSessionAudioListeners = useCallback(() => {
+    const attachedSession = attachedRealtimeSessionRef.current;
+    if (!attachedSession) {
+      return;
+    }
+    attachedSession.off("audio_start", handleSessionAudioStart);
+    attachedSession.off("audio_stopped", handleSessionAudioStopped);
+    attachedSession.off("audio_interrupted", handleSessionAudioInterrupted);
+    attachedSession.off("error", handleSessionError);
+    attachedRealtimeSessionRef.current = null;
+  }, [handleSessionAudioInterrupted, handleSessionAudioStart, handleSessionAudioStopped, handleSessionError]);
+  const attachSessionAudioListeners = useCallback(
+    (session) => {
+      detachSessionAudioListeners();
+      session.on("audio_start", handleSessionAudioStart);
+      session.on("audio_stopped", handleSessionAudioStopped);
+      session.on("audio_interrupted", handleSessionAudioInterrupted);
+      session.on("error", handleSessionError);
+      attachedRealtimeSessionRef.current = session;
+    },
+    [
+      detachSessionAudioListeners,
+      handleSessionAudioInterrupted,
+      handleSessionAudioStart,
+      handleSessionAudioStopped,
+      handleSessionError
+    ]
+  );
+  const stop = useCallback(() => {
+    detachSessionAudioListeners();
+    try {
+      sessionRef.current?.close();
+    } finally {
+      sessionRef.current = null;
+      setStatus("idle");
+      setAgentVoiceStateIfChanged("idle");
+    }
+  }, [detachSessionAudioListeners, setAgentVoiceStateIfChanged]);
+  useEffect(() => {
+    return () => {
+      stop();
+    };
+  }, [stop]);
+  const start = useCallback(async () => {
+    if (status === "connecting" || status === "connected") {
+      return;
+    }
+    setError(null);
+    setStatus("connecting");
+    setAgentVoiceStateIfChanged("idle");
+    try {
+      const runtimeConfig = await runtimeConfigPromise;
+      const requestPayload = runtimeConfig.modelOverride ? { model: runtimeConfig.modelOverride } : {};
+      const secretPayload = await backendClient.createClientSecret(requestPayload);
+      const backendFunctionsResult = await backendClient.listFunctions();
+      const { agent, warnings } = await buildNavaiAgent({
+        navigate: options.navigate,
+        routes: runtimeConfig.routes,
+        functionModuleLoaders: runtimeConfig.functionModuleLoaders,
+        backendFunctions: backendFunctionsResult.functions,
+        executeBackendFunction: backendClient.executeFunction
+      });
+      emitWarnings([...runtimeConfig.warnings, ...backendFunctionsResult.warnings, ...warnings]);
+      const session = new RealtimeSession(agent);
+      attachSessionAudioListeners(session);
+      if (runtimeConfig.modelOverride) {
+        await session.connect({ apiKey: secretPayload.value, model: runtimeConfig.modelOverride });
+      } else {
+        await session.connect({ apiKey: secretPayload.value });
+      }
+      sessionRef.current = session;
+      setStatus("connected");
+    } catch (startError) {
+      const message = formatError(startError);
+      setError(message);
+      setStatus("error");
+      setAgentVoiceStateIfChanged("idle");
+      detachSessionAudioListeners();
+      try {
+        sessionRef.current?.close();
+      } catch {
+      }
+      sessionRef.current = null;
+    }
+  }, [
+    attachSessionAudioListeners,
+    backendClient,
+    detachSessionAudioListeners,
+    options.navigate,
+    runtimeConfigPromise,
+    setAgentVoiceStateIfChanged,
+    status
+  ]);
+  return {
+    status,
+    agentVoiceState,
+    error,
+    isConnecting: status === "connecting",
+    isConnected: status === "connected",
+    isAgentSpeaking: agentVoiceState === "speaking",
+    start,
+    stop
+  };
+}
 export {
   buildNavaiAgent,
   createNavaiBackendClient,
   getNavaiRoutePromptLines,
   loadNavaiFunctions,
   resolveNavaiFrontendRuntimeConfig,
-  resolveNavaiRoute
+  resolveNavaiRoute,
+  useWebVoiceAgent
 };

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@navai/voice-frontend",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Frontend helpers to build OpenAI Realtime voice agents",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "navai-generate-web-loaders": "./bin/generate-web-module-loaders.mjs",
+    "navai-setup-voice-frontend": "./bin/auto-configure-consumer.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,10 +19,14 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "bin",
+    "README.md",
+    "README.es.md",
+    "README.en.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "postinstall": "node ./bin/auto-configure-consumer.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "lint": "tsc --noEmit -p tsconfig.json"
   },
@@ -26,6 +34,9 @@
     "@openai/agents": "^0.4.14",
     "zod": "^4.0.0"
   },
+  "peerDependencies": {
+    "react": ">=18"
+  },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.3"