@yak-io/javascript

Framework-agnostic core SDK for embedding the Yak chat widget. This package provides the low-level client and DOM rendering layer. Most developers should use a framework-specific package (@yak-io/react, @yak-io/vue, etc.) instead.

When to use this package directly

• You are building a vanilla JS / TypeScript app
• You are building a new framework adapter
• You need the server-side handler utilities (./server export) outside Next.js

Installation

pnpm add @yak-io/javascript

Quickstart — Vanilla JS

import { YakEmbed } from "@yak-io/javascript";

const embed = new YakEmbed({
  appId: "your-app-id",
  theme: { position: "bottom-right", colorMode: "system" },
  trigger: { label: "Ask with AI" },
  getConfig: async () => ({
    routes: {
      routes: [
        { path: "/", title: "Home", description: "Landing page" },
        { path: "/docs", title: "Docs", description: "Documentation" },
      ],
      generated_at: new Date().toISOString(),
    },
    tools: {
      tools: [
        {
          name: "tasks.list",
          displayName: "List Tasks",
          description: "Return all tasks",
          inputSchema: { type: "object", properties: {} },
        },
      ],
      generated_at: new Date().toISOString(),
    },
  }),
  onToolCall: async (name, args) => {
    if (name === "tasks.list") {
      return { tasks: [] };
    }
    throw new Error(`Unknown tool: ${name}`);
  },
  onRedirect: (path) => {
    window.location.assign(path);
  },
});

embed.mount();

Server-side utilities

Use @yak-io/javascript/server to build framework-agnostic API handlers:

import { createYakHandler } from "@yak-io/javascript/server";

// Works with any Request/Response runtime (Remix, Fastify, etc.)
const { GET, POST } = createYakHandler({
  routes: [
    { path: "/", title: "Home" },
    { path: "/tasks", title: "Tasks" },
  ],
  tools: {
    getTools: async () => [
      {
        name: "tasks.list",
        displayName: "List Tasks",
        description: "Return all tasks",
        inputSchema: { type: "object", properties: {} },
      },
    ],
    executeTool: async (name, args) => {
      if (name === "tasks.list") return { tasks: [] };
      throw new Error(`Unknown tool: ${name}`);
    },
  },
});

API Reference

YakEmbed

High-level class that handles DOM rendering (panel, iframe, trigger button) and client wiring.

new YakEmbed(config: YakEmbedConfig)

Key methods:

| Method | Description | |--------|-------------| | mount() | Injects the widget into the DOM | | destroy() | Removes the widget from the DOM | | open() | Open the chat panel | | close() | Close the chat panel | | toggle() | Toggle open/close | | openWithPrompt(prompt) | Open and pre-fill a prompt | | getState() | Get current { isOpen, isReady } state | | onStateChange(fn) | Subscribe to state changes, returns unsubscribe | | getClient() | Access the underlying YakClient |

Configuration (YakEmbedConfig):

| Option | Type | Description | |--------|------|-------------| | appId | string | Your Yak app ID | | theme | Theme | Position, color mode, and widget colors | | trigger | boolean \| TriggerButtonConfig | Show built-in trigger button | | getConfig | ChatConfigProvider | Async function returning routes + tools config | | chatConfig | ChatConfig | Static config (alternative to getConfig) | | onToolCall | ToolCallHandler | Handle tool calls from the assistant | | onGraphQLSchemaCall | GraphQLSchemaHandler | Handle GraphQL schema tool calls | | onRESTSchemaCall | RESTSchemaHandler | Handle REST/OpenAPI schema tool calls | | onRedirect | (path: string) => void | Handle navigation requests | | onToolCallComplete | (event: ToolCallEvent) => void | Called after each tool call | | options.disableRestartButton | boolean | Hide the restart session button |

YakClient

Low-level iframe communication client. Use YakEmbed for most cases.

Logging utilities

import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/javascript";

enableYakLogging();   // Turn on verbose SDK logging
disableYakLogging();  // Turn off SDK logging
isYakLoggingEnabled(); // Returns current state

In development, set window.__YAK_INTERNAL_DEV__ = true before mounting to connect to a locally running chat UI.

Types

All types are exported from the package root:

import type {
  ChatConfig,
  ChatConfigProvider,
  RouteManifest,
  RouteInfo,
  ToolManifest,
  ToolDefinition,
  ToolCallHandler,
  ToolCallEvent,
  ToolCallPayload,
  ToolCallResult,
  GraphQLSchemaHandler,
  RESTSchemaHandler,
  GraphQLRequest,
  RESTRequest,
  SchemaSource,
  GraphQLSchemaSource,
  OpenAPISchemaSource,
  Theme,
  ThemeColors,
  TriggerButtonConfig,
  WidgetPosition,
  YakClientConfig,
  YakEmbedConfig,
  YakEmbedState,
} from "@yak-io/javascript";

License

Proprietary — see LICENSE file.