@yak-io/javascript 0.8.0 → 0.9.0

package/README.md

@@ -1,80 +1,152 @@
 # @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.
+> 📚 **Full documentation:** https://docs.yak.io/docs/sdks/javascript
+>
+> 🤖 **For LLMs / AI agents:** https://docs.yak.io/llms.txt
 
-## When to use this package directly
+Framework-agnostic core SDK for [Yak](https://docs.yak.io) — an embeddable AI assistant (text chat **and** push-to-talk voice) for web apps. This package is the low-level runtime that every framework SDK (`@yak-io/react`, `@yak-io/vue`, …) is built on. It owns iframe messaging, the WebRTC voice session, DOM rendering of the trigger pill + chat panel, and an optional server handler.
 
-- 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
+**Use this package directly when** you're on vanilla JS/TS, building a new framework adapter, or need the server handler (`@yak-io/javascript/server`) outside Next.js. On a supported framework, prefer that framework's package instead.
 
 ```bash
 pnpm add @yak-io/javascript
 ```
 
-## Quickstart — Vanilla JS
+## Exports
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `YakEmbed` | class | Drop-in widget: trigger pill + chat panel + voice, all wired. Start here. |
+| `YakClient` | class | Headless chat-only iframe client (no DOM). Advanced. |
+| `YakVoiceSession` | class | Headless WebRTC voice session. Advanced. |
+| `enableYakLogging` / `disableYakLogging` / `isYakLoggingEnabled` | fn | Toggle verbose SDK logging. |
+| `EMBED_PROTOCOL_VERSION` | const | Host ↔ iframe protocol version. |
+| Types | — | `YakEmbedConfig`, `YakClientConfig`, `Theme`, `WidgetMode`, `VoiceState`, `VoiceMachine`, `ToolCallEvent`, `ChatConfig`, and more (see [Types](#types)). |
+| `@yak-io/javascript/server` | subpath | `createYakHandler` + route/tool source types (see [Server](#server-side-handler)). |
+
+## Quickstart
 
 ```ts
 import { YakEmbed } from "@yak-io/javascript";
 
 const embed = new YakEmbed({
   appId: "your-app-id",
+  mode: "both", // "chat" | "voice" | "both" — default "chat"
+  trigger: true, // render the floating launcher pill
   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}`);
+  // Routes + tools the assistant may use. Usually fetched from your server.
+  getConfig: async () => {
+    const res = await fetch("/api/yak");
+    return res.json(); // ChatConfig: { routes, tools? }
   },
-  onRedirect: (path) => {
-    window.location.assign(path);
+  // Execute a tool the assistant decides to call.
+  onToolCall: async (name, args) => {
+    const res = await fetch("/api/yak", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, args }),
+    });
+    const data = await res.json();
+    if (!data.ok) throw new Error(data.error);
+    return data.result;
   },
 });
 
-embed.mount();
+embed.mount(); // inject into the DOM
+```
+
+## Programmatic control
+
+Every method works whether or not the trigger pill is shown — pass `trigger: false` to drive a fully custom UI.
+
+```ts
+// Chat
+embed.open();
+embed.close();
+embed.toggle();
+embed.openWithPrompt("How do I export my data?");
+
+// Voice (requires mode "voice" or "both"; must be called from a user gesture)
+await embed.voiceStart();
+await embed.voiceStop();
+await embed.voiceToggle();
+
+// State
+embed.getState(); // { isOpen, isReady, isLoading, isExpanded }
+const stop = embed.onStateChange((s) => console.log(s.isLoading));
+const stopVoice = embed.onVoiceStateChange((m) => console.log(m.state));
 ```
 
-## Server-side utilities
+`isLoading` is `isOpen && !isReady` — true from the moment the panel opens until the iframe handshakes ready. Drive a custom loading spinner off it instead of re-deriving the condition. For voice, the equivalent "still spinning up" check is `getVoiceState().state === "connecting"`.
 
-Use `@yak-io/javascript/server` to build framework-agnostic API handlers:
+## API reference
+
+### `new YakEmbed(config)`
+
+**Config** (`YakEmbedConfig`):
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `appId` | `string` | — | Your Yak app ID (required). |
+| `mode` | `"chat" \| "voice" \| "both"` | `"chat"` | Which surfaces the widget exposes. |
+| `trigger` | `boolean \| TriggerButtonConfig` | `true` | Show the floating pill. `false` = headless. `TriggerButtonConfig` recolors it. |
+| `theme` | `Theme` | — | Position, color mode, and colors. |
+| `getConfig` | `ChatConfigProvider` | — | Async provider of `{ routes, tools? }`. Called on open and on each voice start. |
+| `onToolCall` | `ToolCallHandler` | — | Executes a tool the assistant calls. |
+| `onGraphQLSchemaCall` | `GraphQLSchemaHandler` | — | Handles GraphQL schema tool calls. |
+| `onRESTSchemaCall` | `RESTSchemaHandler` | — | Handles REST/OpenAPI schema tool calls. |
+| `onRedirect` | `(path: string) => void` | `window.location.assign` | Handle navigation requested by the assistant. |
+| `onToolCallComplete` | `(event: ToolCallEvent) => void` | — | Fires after every tool call (use for cache invalidation). |
+| `user` | `UserIdentity` | — | Signed end-user identity for server-side conversation persistence. See [end-user identity](https://docs.yak.io/docs/customization/end-user-identity). |
+| `target` | `HTMLElement` | `document.body` | Where to mount the widget DOM. |
+| `options.disableRestartButton` | `boolean` | `false` | Hide the restart-session button in the header. |
+
+**Methods:** `mount()`, `destroy()`, `open()`, `close()`, `toggle()`, `openWithPrompt(prompt)`, `getState()`, `onStateChange(fn)`, `voiceStart()`, `voiceStop()`, `voiceToggle()`, `getVoiceState()`, `onVoiceStateChange(fn)`, `getClient()`, `getVoiceSession()`, `getMode()`.
+
+### `Theme`
+
+```ts
+type Theme = {
+  position?: WidgetPosition;            // default "bottom-left"
+  colorMode?: "light" | "dark" | "system";
+  displayMode?: "chatbox" | "drawer";   // floating panel vs full-height side drawer
+  fullscreen?: boolean;
+  light?: ThemeColors;                  // { background?, border?, messageBackground?, ... }
+  dark?: ThemeColors;
+};
+// WidgetPosition: top-left | top-center | top-right | left-center | right-center
+//               | bottom-left | bottom-center | bottom-right
+```
+
+### `VoiceState` / `VoiceMachine`
+
+```ts
+type VoiceState = "idle" | "connecting" | "listening" | "thinking" | "speaking" | "error";
+interface VoiceMachine { state: VoiceState; errorMessage?: string }
+```
+
+### `YakClient` / `YakVoiceSession`
+
+Headless building blocks used internally by `YakEmbed`. Reach for them only when composing a bespoke integration — most apps should use `YakEmbed`.
+
+## Server-side handler
+
+`@yak-io/javascript/server` builds a framework-agnostic `Request`/`Response` handler (Remix, Fastify, Hono, plain Node, …):
 
 ```ts
 import { createYakHandler } from "@yak-io/javascript/server";
 
-// Works with any Request/Response runtime (Remix, Fastify, etc.)
-const { GET, POST } = createYakHandler({
+export const { GET, POST } = createYakHandler({
+  // GET returns the route + tool manifest the assistant sees.
   routes: [
     { path: "/", title: "Home" },
     { path: "/tasks", title: "Tasks" },
   ],
+  // POST executes a tool call.
   tools: {
     getTools: async () => [
       {
         name: "tasks.list",
-        displayName: "List Tasks",
         description: "Return all tasks",
         inputSchema: { type: "object", properties: {} },
       },
@@ -87,61 +159,17 @@ const { GET, POST } = createYakHandler({
 });
 ```
 
-## API Reference
-
-### `YakEmbed`
-
-High-level class that handles DOM rendering (panel, iframe, trigger button) and client wiring.
+`routes` and `tools` each accept a single source or an array of sources, so you can compose filesystem routes with adapters like [`@yak-io/trpc`](https://docs.yak.io/docs/tool-adapters/trpc) or [`@yak-io/prismic`](https://docs.yak.io/docs/cms/prismic).
 
-```ts
-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
+## Logging
 
 ```ts
 import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/javascript";
 
-enableYakLogging();   // Turn on verbose SDK logging
-disableYakLogging();  // Turn off SDK logging
-isYakLoggingEnabled(); // Returns current state
+enableYakLogging(); // verbose SDK logs
 ```
 
-In development, set `window.__YAK_INTERNAL_DEV__ = true` before mounting to connect to a locally running chat UI.
+In development, set `window.__YAK_INTERNAL_DEV__ = true` before `mount()` to connect to a locally running chat UI.
 
 ## Types
 
@@ -149,6 +177,16 @@ All types are exported from the package root:
 
 ```ts
 import type {
+  YakEmbedConfig,
+  YakEmbedState,
+  YakClientConfig,
+  WidgetMode,
+  Theme,
+  ThemeColors,
+  WidgetPosition,
+  TriggerButtonConfig,
+  VoiceState,
+  VoiceMachine,
   ChatConfig,
   ChatConfigProvider,
   RouteManifest,
@@ -157,25 +195,12 @@ import type {
   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.
+Proprietary — see [LICENSE](./LICENSE).

package/dist/embed.d.ts

@@ -2,6 +2,12 @@ import { YakClient, type YakClientConfig } from "./client.js";
 import type { ChatConfigProvider } from "./types/config.js";
 import { type VoiceMachine } from "./voice-machine.js";
 import { type VoiceStateListener, YakVoiceSession } from "./voice-session.js";
+/**
+ * Which experiences the widget exposes:
+ * - `chat` — chat icon only (opens the chat iframe panel). The default.
+ * - `voice` — voice icon only (starts a WebRTC voice session).
+ * - `both` — both icons, sharing one trigger pill.
+ */
 export type WidgetMode = "chat" | "voice" | "both";
 export type TriggerButtonConfig = {
     /** Custom color overrides for light mode */
@@ -38,8 +44,17 @@ export type YakEmbedConfig = YakClientConfig & {
     getConfig?: ChatConfigProvider;
 };
 export type YakEmbedState = {
+    /** Whether the chat panel is open. */
     isOpen: boolean;
+    /** Whether the chat iframe has handshaked and can receive messages. */
     isReady: boolean;
+    /**
+     * Whether the chat is opening but not yet interactive — `isOpen && !isReady`.
+     * Stays true from the moment the panel opens until the iframe reports ready,
+     * so custom triggers can show a spinner without re-deriving it.
+     */
+    isLoading: boolean;
+    /** Whether the panel is expanded to (near) full-screen. */
     isExpanded: boolean;
 };
 export type YakEmbedStateListener = (state: YakEmbedState) => void;

package/dist/embed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../src/embed.ts"],"names":[],"mappings":"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"}

package/dist/embed.js

@@ -483,7 +483,12 @@ export class YakEmbed {
     }
     /** Get the current widget state. */
     getState() {
-        return { isOpen: this.isOpen, isReady: this.isReady, isExpanded: this.isExpanded };
+        return {
+            isOpen: this.isOpen,
+            isReady: this.isReady,
+            isLoading: this.isOpen && !this.isReady,
+            isExpanded: this.isExpanded,
+        };
     }
     /** Subscribe to state changes. Returns an unsubscribe function. */
     onStateChange(listener) {

package/dist/voice-machine.d.ts

@@ -10,11 +10,24 @@
  * delegated to the injected `RealtimeMessageContext` so the function is
  * testable with a plain in-memory mock.
  */
+/**
+ * Lifecycle of a voice session, in order:
+ * - `idle` — no session (the starting and stopped state).
+ * - `connecting` — establishing the WebRTC connection.
+ * - `listening` — connected and capturing the user's speech.
+ * - `thinking` — the model is processing / generating a response.
+ * - `speaking` — the assistant is playing audio back.
+ * - `error` — the session failed; see {@link VoiceMachine.errorMessage}.
+ */
 export type VoiceState = "idle" | "connecting" | "listening" | "thinking" | "speaking" | "error";
 export type VoiceEvent = {
     type: "start";
 } | {
     type: "connected";
+}
+/** An assistant-initiated turn was requested (e.g. the opening greeting). */
+ | {
+    type: "response_requested";
 } | {
     type: "speech_started";
 } | {
@@ -29,8 +42,11 @@ export type VoiceEvent = {
     type: "error";
     message: string;
 };
+/** Snapshot of a voice session's state machine. */
 export interface VoiceMachine {
+    /** Current lifecycle state of the session. */
     state: VoiceState;
+    /** Human-readable failure reason — set only when `state === "error"`. */
     errorMessage?: string;
 }
 export declare const INITIAL_VOICE_MACHINE: VoiceMachine;

package/dist/voice-machine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voice-machine.d.ts","sourceRoot":"","sources":["../src/voice-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAEjG,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,qBAAqB,EAAE,YAAgC,CAAC;AAErE,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,YAAY,CA4BnF;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACtD;AAmID,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmCf"}
+{"version":3,"file":"voice-machine.d.ts","sourceRoot":"","sources":["../src/voice-machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAEjG,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE;AACvB,6EAA6E;GAC3E;IAAE,IAAI,EAAE,oBAAoB,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GACzB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,KAAK,EAAE,UAAU,CAAC;IAClB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,qBAAqB,EAAE,YAAgC,CAAC;AAErE,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,YAAY,CAiCnF;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACtD;AAmID,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/voice-machine.js

@@ -17,6 +17,11 @@ export function voiceReducer(machine, event) {
             return machine.state === "idle" ? { state: "connecting" } : machine;
         case "connected":
             return machine.state === "connecting" ? { state: "listening" } : machine;
+        case "response_requested":
+            // The assistant is generating an unprompted turn (the opening greeting).
+            // Move to `thinking` so the subsequent `audio_delta` lands on `speaking`,
+            // matching a normal turn; no-op if we're not idling in `listening`.
+            return machine.state === "listening" ? { state: "thinking" } : machine;
         case "speech_started":
             if (machine.state === "idle" || machine.state === "error")
                 return machine;

package/dist/voice-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voice-session.d.ts","sourceRoot":"","sources":["../src/voice-session.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,KAAK,EAEV,oBAAoB,EAEpB,iBAAiB,EACjB,eAAe,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC;CACF;AAkBD,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA2DD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,eAAe,CAA6B;IACpD,6EAA6E;IAC7E,OAAO,CAAC,KAAK,CAAkC;IAC/C;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAA6B;gBAErC,MAAM,EAAE,qBAAqB;IAKzC;;;;;OAKG;IACH,OAAO,KAAK,SAAS,GAEpB;IAED,0DAA0D;IACnD,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,IAAI;IAIzD,QAAQ,IAAI,YAAY;IAI/B;;;;OAIG;IACI,YAAY,IAAI,MAAM;IAItB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAO9D;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+InC,oDAAoD;IACvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,2FAA2F;IACpF,OAAO,IAAI,IAAI;IAWtB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,mBAAmB;YAeb,aAAa;IAsC3B;;;;OAIG;YACW,WAAW;YAwBX,SAAS;IAuBvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;YA4BhB,WAAW;IAmBzB,OAAO,CAAC,kBAAkB;YAWZ,gBAAgB;YA2BhB,QAAQ;YAuCR,QAAQ;IAMtB,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,cAAc;CAevB"}
+{"version":3,"file":"voice-session.d.ts","sourceRoot":"","sources":["../src/voice-session.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,KAAK,EAEV,oBAAoB,EAEpB,iBAAiB,EACjB,eAAe,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC;CACF;AAkBD,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,OAAO,CAAuC;IACtD,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,eAAe,CAA6B;IACpD,6EAA6E;IAC7E,OAAO,CAAC,KAAK,CAAkC;IAC/C;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAA6B;gBAErC,MAAM,EAAE,qBAAqB;IAKzC;;;;;OAKG;IACH,OAAO,KAAK,SAAS,GAEpB;IAED,0DAA0D;IACnD,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,IAAI;IAIzD,QAAQ,IAAI,YAAY;IAI/B;;;;OAIG;IACI,YAAY,IAAI,MAAM;IAItB,aAAa,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAO9D;;;OAGG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0JnC,oDAAoD;IACvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlC,2FAA2F;IACpF,OAAO,IAAI,IAAI;IAWtB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,mBAAmB;YAeb,aAAa;IAsC3B;;;;OAIG;YACW,WAAW;YAwBX,SAAS;IAuBvB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;YA4BhB,WAAW;IAmBzB,OAAO,CAAC,kBAAkB;YAWZ,gBAAgB;YA2BhB,QAAQ;YAuCR,QAAQ;IAMtB,OAAO,CAAC,QAAQ;IAahB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,cAAc;CAevB"}

package/dist/voice-session.js

@@ -197,6 +197,17 @@ export class YakVoiceSession {
         dataChannel.onopen = () => {
             logger.debug("Voice: data channel opened");
             this.dispatch({ type: "connected" });
+            // Kick off an opening greeting so the assistant speaks first instead of
+            // waiting silently for the user. The minted session already carries the
+            // full instructions (persona, governance, language, "first turn" rule),
+            // so a bare `response.create` is enough — do NOT attach response-level
+            // instructions here, which would replace the session instructions.
+            // Skip it when the app's voice intro is "none" (`autoGreet === false`);
+            // a missing flag defaults to greeting for back-compat.
+            if (mint.autoGreet !== false) {
+                this.dispatch({ type: "response_requested" });
+                this.sendOverDataChannel({ type: "response.create" });
+            }
         };
         dataChannel.onclose = () => {
             logger.debug("Voice: data channel closed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yak-io/javascript",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Core JavaScript SDK for embedding yak chatbot",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -25,6 +25,7 @@
     "node": ">=18"
   },
   "files": [
+    "README.md",
     "dist",
     "LICENSE"
   ],
@@ -62,6 +63,7 @@
     "vitest": "^4.1.6",
     "@repo/typescript-config": "0.0.0"
   },
+  "homepage": "https://docs.yak.io/docs/sdks/javascript",
   "scripts": {
     "build": "tsc",
     "check-types": "tsc --noEmit",