@useruna/client

Official JavaScript & React client SDK for Runa AI — embed an AI assistant into any web application.

Installation

npm install @useruna/client

React Usage

RunaProvider

Wrap your app with RunaProvider to configure global settings:

import { RunaProvider } from '@useruna/client';

export default function App({ children }) {
  return (
    <RunaProvider
      productId="your-product-id"
      userId={currentUser.id}
      userEmail={currentUser.email}
    >
      {children}
    </RunaProvider>
  );
}

useRuna hook

Access the agent programmatically inside your components:

import { useRuna } from '@useruna/client';

export function MyComponent() {
  const { sendMessage, messages, isLoading, openWidget } = useRuna();

  const handleAction = async () => {
    const reply = await sendMessage('Show me this user\'s recent activity');
    console.log(reply);
  };

  return (
    <button onClick={handleAction}>
      Ask Runa
    </button>
  );
}

Vanilla JavaScript Usage

import { RunaClient } from '@useruna/client';

const runa = new RunaClient({
  productId: 'your-product-id',
  apiEndpoint: 'https://api.useruna.ai',
});

// Send a message
const response = await runa.chat({
  message: 'How many users signed up this week?',
  sessionId: 'user-session-123',
});

console.log(response.reply);

Configuration

| Prop | Type | Required | Description | |------|------|----------|-------------| | productId | string | ✅ | Your Runa product ID from the dashboard. | | apiEndpoint | string | — | API base URL. Defaults to https://api.useruna.ai. | | userId | string | — | Identify the current user for personalization. | | userEmail | string | — | User email for context and analytics. | | theme | "light" \| "dark" | — | Widget color theme. Defaults to "light". | | position | "bottom-right" \| "bottom-left" | — | Widget button position. Defaults to "bottom-right". | | initialMessage | string | — | Greeting message shown when the widget opens. | | onMessage | (msg: Message) => void | — | Callback fired on each new assistant message. |

TypeScript Types

export interface RunaConfig {
  productId: string;
  apiEndpoint?: string;
  userId?: string;
  userEmail?: string;
  theme?: 'light' | 'dark';
  position?: 'bottom-right' | 'bottom-left';
  initialMessage?: string;
  onMessage?: (message: Message) => void;
}

export interface Message {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  timestamp: string;
  toolCalls?: ToolCall[];
}

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
  result?: unknown;
}

License

MIT © Runa AI