Custom Function Examples

src/ai/functions-modules/
├── session/
│   └── logout.fn.ts
├── support/
│   └── open-help.fn.ts
├── utils/
│   └── math.ts
├── test/
│   └── testing.ts
└── system/
    └── ai-service.ts

# Web
npm run generate:module-loaders

# Mobile
npm run generate:ai-modules

// src/ai/functions-modules/session/logout.fn.ts

/**
 * Logs out the current user by clearing auth tokens and redirecting to home.
 * The agent can call this when user says "logout", "sign out", "cierra sesion", etc.
 */
export function logout_user(context: { navigate: (path: string) => void }) {
  try {
    // Clear authentication tokens from localStorage
    localStorage.removeItem("auth_token");
    localStorage.removeItem("refresh_token");
  } catch {
    // Ignore storage errors to avoid breaking other functions.
    // Some environments (incognito mode) may restrict localStorage.
  }

  // Navigate user to home page
  context.navigate("/");
  
  // Return success result
  return { ok: true, message: "Session closed." };
}

// src/ai/functions-modules/support/open-help.fn.ts

/**
 * Opens the help center page.
 * Can be invoked by saying "open help", "need support", "ayuda", etc.
 */
export const open_help_center = (context: { navigate: (path: string) => void }) => {
  // Navigate to help page
  context.navigate("/help");
  
  // Return the path for confirmation
  return { ok: true, path: "/help" };
};

// src/ai/functions-modules/utils/math.ts

/**
 * Adds two numbers together.
 */
export function sumar(a: number, b: number): number {
  return a + b;
}

/**
 * Checks if a person is an adult (18 or older).
 */
export const es_mayor_de_edad = (edad: number): boolean => {
  return edad >= 18;
};

/**
 * Module version - exported constants are ignored by generator.
 */
export const version = "1.0.0";

// src/ai/functions-modules/system/ai-service.ts

/**
 * AI service management class.
 * The agent can create instances and call methods.
 */
export default class ServicioIA {
  constructor(private readonly apiKey: string = "demo-key") {}

  /**
   * Initialize the AI service.
   */
  iniciar(): string {
    return `Servicio iniciado con key: ${this.apiKey}`;
  }
}

// src/ai/functions-modules/test/testing.ts

/**
 * Returns a secret word for testing purposes.
 */
export function secret_word(a: string): string {
  return "45_JOSE_MARIA_45";
}

/**
 * Module version.
 */
export const version = "1.0.0";

export async function fetch_user_data(context: { navigate: (path: string) => void }) {
  try {
    const response = await fetch("/api/user");
    const data = await response.json();
    return { ok: true, data };
  } catch (error) {
    return { ok: false, error: String(error) };
  }
}

export function risky_operation(value: number) {
  if (value < 0) {
    return { ok: false, error: "Value must be positive" };
  }
  
  try {
    const result = performOperation(value);
    return { ok: true, result };
  } catch (error) {
    return { ok: false, error: error instanceof Error ? error.message : "Unknown error" };
  }
}

type Context = {
  navigate: (path: string) => void;
  user?: { id: string; name: string };
  config?: Record<string, unknown>;
};

export function personalized_greeting(context: Context) {
  const userName = context.user?.name ?? "Guest";
  return { ok: true, message: `Welcome, ${userName}!` };
}

type NavaiContext = {
  // Navigate to a route by path
  navigate: (path: string) => void;
  
  // Additional properties can be added by your app
  [key: string]: unknown;
};

// In your VoiceNavigator setup
const agent = useWebVoiceAgent({
  navigate,
  moduleLoaders: NAVAI_WEB_MODULE_LOADERS,
  defaultRoutes: NAVAI_ROUTE_ITEMS,
  
  // Custom context passed to all functions
  customContext: {
    user: currentUser,
    theme: currentTheme,
    appVersion: "1.0.0"
  }
});

export function get_app_info(context: any) {
  return {
    ok: true,
    version: context.appVersion,
    user: context.user?.name
  };
}

functions-modules/
├── auth/
│   ├── login.fn.ts
│   ├── logout.fn.ts
│   └── reset-password.fn.ts
├── profile/
│   ├── update-bio.fn.ts
│   └── upload-avatar.fn.ts
└── settings/
    ├── change-theme.fn.ts
    └── update-preferences.fn.ts

functions-modules/
├── navigation/
│   └── open-pages.ts
├── data/
│   └── fetch-resources.ts
└── actions/
    └── user-actions.ts

import { logout_user } from "./logout.fn";

test("logout_user clears tokens and navigates home", () => {
  const mockNavigate = jest.fn();
  const context = { navigate: mockNavigate };
  
  localStorage.setItem("auth_token", "test-token");
  
  const result = logout_user(context);
  
  expect(result.ok).toBe(true);
  expect(localStorage.getItem("auth_token")).toBeNull();
  expect(mockNavigate).toHaveBeenCalledWith("/");
});

import { useWebVoiceAgent } from "@navai/voice-frontend";

test("voice command triggers logout", async () => {
  const { result } = renderHook(() => useWebVoiceAgent({ ... }));
  
  // Simulate voice command
  await result.current.processCommand("logout");
  
  expect(mockNavigate).toHaveBeenCalledWith("/");
});

// Good: Consistent result shape
export function my_function() {
  if (error) {
    return { ok: false, error: "Something went wrong" };
  }
  return { ok: true, data: result };
}

// Avoid: Inconsistent returns
export function bad_function() {
  if (error) return null;
  return result;
}

export function safe_operation() {
  try {
    riskyCode();
    return { ok: true };
  } catch (error) {
    console.error("Operation failed:", error);
    return { ok: false, error: String(error) };
  }
}

/**
 * Sends a password reset email to the user.
 * 
 * @param context - Navigation context
 * @param email - User's email address
 * @returns Result with confirmation message
 */
export async function send_password_reset(
  context: { navigate: (path: string) => void },
  email: string
) {
  // Implementation
}

// Good: Single responsibility
export function logout_user(context) {
  clearAuthTokens();
  context.navigate("/");
  return { ok: true };
}

// Avoid: Too many responsibilities
export function logout_and_show_message_and_track(context) {
  clearAuthTokens();
  showToast("Logged out");
  trackEvent("logout");
  updateAnalytics();
  context.navigate("/");
  return { ok: true };
}