@yak-io/vue 0.3.0 → 0.4.0

package/README.md

@@ -1,25 +1,40 @@
 # @yak-io/vue
 
-Vue 3 integration for the Yak embeddable chat widget. Uses Vue's Composition API with reactive refs.
+> 📚 **Full documentation:** https://docs.yak.io/docs/sdks/vue
+>
+> 🤖 **For LLMs / AI agents:** https://docs.yak.io/llms.txt
 
-## Installation
+Vue 3 SDK for [Yak](https://docs.yak.io) — an embeddable AI assistant (text chat **and** push-to-talk voice) for web apps. Call `createYakProvider` once in your root component; reactive state is exposed as Vue refs and shared with descendants via `provide`/`inject`.
 
 ```bash
 pnpm add @yak-io/vue
 ```
 
-## Quickstart
+## Exports
 
-### 1. Initialize in your root component
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `createYakProvider(options)` | fn | Initialize the widget in your root component. Returns a `YakApi`. Auto-mounts/unmounts. |
+| `useYak()` | fn | Inject the `YakApi` in any descendant component. |
+| `useYakToolEvent(handler)` | fn | Run a callback after each tool call (auto-unsubscribes on unmount). |
+| `enableYakLogging` / `disableYakLogging` / `isYakLoggingEnabled` | fn | Toggle verbose SDK logging. |
+| Types | — | `YakProviderOptions`, `YakApi`, `ToolCallEventHandler`, plus core types from `@yak-io/javascript`. |
 
-```ts
-// App.vue <script setup>
+## Quickstart
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { useRouter } from "vue-router";
 import { createYakProvider } from "@yak-io/vue";
 
+const router = useRouter();
+
 createYakProvider({
   appId: import.meta.env.VITE_YAK_APP_ID,
+  mode: "both",   // "chat" | "voice" | "both" — default "chat"
+  trigger: true,  // show the floating launcher pill
   theme: { position: "bottom-right", colorMode: "system" },
-  trigger: { label: "Ask with AI" },
   getConfig: async () => {
     const res = await fetch("/api/yak");
     return res.json();
@@ -34,100 +49,110 @@ createYakProvider({
     if (!data.ok) throw new Error(data.error);
     return data.result;
   },
-  onRedirect: (path) => {
-    router.push(path);
-  },
+  onRedirect: (path) => router.push(path),
 });
+</script>
+
+<template>
+  <RouterView />
+</template>
 ```
 
-`createYakProvider` calls `onMounted` and `onUnmounted` internally — no manual lifecycle management needed.
+`createYakProvider` registers `onMounted`/`onUnmounted` for you — no manual lifecycle needed.
 
-### 2. Use in descendant components
+## Programmatic control
 
-```ts
-// MyComponent.vue <script setup>
+```vue
+<script setup lang="ts">
 import { useYak } from "@yak-io/vue";
 
-const { open, openWithPrompt, isOpen, isReady } = useYak();
+const { open, openWithPrompt, isOpen } = useYak();
+</script>
+
+<template>
+  <button @click="open">Open chat</button>
+  <button @click="openWithPrompt('How do I get started?')">Get help</button>
+  <span v-if="isOpen">Chat is open</span>
+</template>
 ```
 
-`isOpen` and `isReady` are `readonly` Vue refs — use them like any other ref:
+`isOpen`/`isReady` are `readonly` refs — use them directly in templates.
+
+## Voice
+
+Set `mode: "voice"` or `mode: "both"`, then drive the session. `voiceStart()` must run from a user gesture (browser mic requirement).
+
+```vue
+<script setup lang="ts">
+import { useYak } from "@yak-io/vue";
+
+const { voiceToggle, voiceLoading, voiceMachine } = useYak();
+</script>
 
-```html
 <template>
-  <div>
-    <button @click="open">Open Chat</button>
-    <p v-if="isOpen">Chat is open</p>
-    <p v-if="!isReady && isOpen">Loading…</p>
-  </div>
+  <button @click="voiceToggle" :disabled="voiceLoading">
+    {{ voiceMachine.state === "idle" ? "Start voice" : `Stop (${voiceMachine.state})` }}
+  </button>
 </template>
 ```
 
-### 3. Subscribe to tool events
+## Tool events
 
 ```ts
 import { useYakToolEvent } from "@yak-io/vue";
 
 useYakToolEvent((event) => {
-  if (event.ok && event.name.startsWith("tasks.")) {
-    refreshTasks();
-  }
+  // { name, args, ok, result?, error? }
+  if (event.ok && event.name.startsWith("tasks.")) refreshTasks();
 });
 ```
 
-Automatically unsubscribes when the component unmounts.
-
-## API Reference
+## API reference
 
 ### `createYakProvider(options)`
 
-Call once in your root/layout component. Sets up the widget, registers lifecycle hooks, and provides the API to all descendant components via Vue's `provide/inject`.
+Call once in your root component. Returns a `YakApi` (same object `useYak()` injects).
 
-Returns a `YakApi` object (same as `useYak()`).
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `appId` | `string` | — | Your Yak app ID (required). |
+| `mode` | `"chat" \| "voice" \| "both"` | `"chat"` | Which surfaces the widget exposes. |
+| `trigger` | `boolean \| TriggerButtonConfig` | `false` | Show the floating pill. **Set `true`** to display it; `TriggerButtonConfig` recolors it. |
+| `getConfig` | `ChatConfigProvider` | — | Async provider of routes + tools. Called on open / 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. |
+| `theme` | `Theme` | — | Position, color mode, and colors. |
+| `onRedirect` | `(path: string) => void` | `window.location.assign` | Navigation handler. |
+| `disableRestartButton` | `boolean` | `false` | Hide the restart-session button. |
 
-**Options:**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `appId` | `string` | Your Yak app ID |
-| `getConfig` | `ChatConfigProvider` | Async function returning routes + tools. Called on first open. |
-| `onToolCall` | `ToolCallHandler` | Handle tool invocations from the assistant |
-| `onGraphQLSchemaCall` | `GraphQLSchemaHandler` | Handle GraphQL schema tool calls |
-| `onRESTSchemaCall` | `RESTSchemaHandler` | Handle REST/OpenAPI schema tool calls |
-| `theme` | `Theme` | Position, color mode, and custom colors |
-| `onRedirect` | `(path: string) => void` | Navigation handler (defaults to `window.location.assign`) |
-| `disableRestartButton` | `boolean` | Hide the restart session button |
-| `trigger` | `boolean \| TriggerButtonConfig` | Built-in trigger button |
-
-### `useYak()`
-
-Inject the widget API in any descendant component.
+### `YakApi`
 
 ```ts
-const {
-  isOpen,             // DeepReadonly<Ref<boolean>>
-  isReady,            // DeepReadonly<Ref<boolean>>
-  open,               // () => void
-  close,              // () => void
-  openWithPrompt,     // (prompt: string) => void
-  subscribeToToolEvents, // (handler) => () => void
-} = useYak();
+type YakApi = {
+  // chat
+  isOpen: DeepReadonly<Ref<boolean>>;
+  isReady: DeepReadonly<Ref<boolean>>;
+  chatLoading: DeepReadonly<Ref<boolean>>; // isOpen && !isReady
+  open: () => void;
+  close: () => void;
+  openWithPrompt: (prompt: string) => void;
+  subscribeToToolEvents: (handler: ToolCallEventHandler) => () => void;
+  // voice
+  voiceMachine: DeepReadonly<Ref<VoiceMachine>>; // { state, errorMessage? }
+  voiceLoading: DeepReadonly<Ref<boolean>>; // state === "connecting"
+  voiceStart: () => Promise<void>;
+  voiceStop: () => Promise<void>;
+  voiceToggle: () => Promise<void>;
+};
 ```
 
-Throws if called outside a component tree where `createYakProvider` was used.
-
-### `useYakToolEvent(handler)`
-
-Subscribe to tool call completion events. Unsubscribes automatically on component unmount.
-
 ## Logging
 
 ```ts
 import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/vue";
 
-enableYakLogging();    // Enable verbose SDK logs
-disableYakLogging();   // Disable SDK logs
-isYakLoggingEnabled(); // → boolean
+enableYakLogging(); // verbose SDK logs
 ```
 
 ## Types
@@ -141,11 +166,13 @@ import type {
   ToolCallHandler,
   ToolCallEvent,
   Theme,
-  TriggerButtonConfig,
+  WidgetMode,
   WidgetPosition,
+  VoiceState,
+  VoiceMachine,
 } from "@yak-io/vue";
 ```
 
 ## License
 
-Proprietary — see LICENSE file.
+Proprietary — see [LICENSE](./LICENSE).

package/dist/composables.d.ts

@@ -13,16 +13,31 @@ export type YakProviderOptions = {
     disableRestartButton?: boolean;
     trigger?: boolean | TriggerButtonConfig;
 };
+/** Reactive handle for controlling the Yak widget — chat + voice — from Vue. */
 export type YakApi = {
+    /** Whether the chat panel is currently open. */
     isOpen: DeepReadonly<Ref<boolean>>;
+    /** Whether the chat iframe is ready to receive messages. */
     isReady: DeepReadonly<Ref<boolean>>;
+    /** Whether the chat is opening but not yet interactive (`isOpen && !isReady`). */
+    chatLoading: DeepReadonly<Ref<boolean>>;
+    /** Open the chat panel. */
     open: () => void;
+    /** Close the chat panel. */
     close: () => void;
+    /** Open the chat panel and send a specific prompt. */
     openWithPrompt: (prompt: string) => void;
+    /** Subscribe to tool-call completion events; returns an unsubscribe function. */
     subscribeToToolEvents: (handler: ToolCallEventHandler) => () => void;
+    /** Current voice state-machine snapshot. `idle` when mode is `chat`. */
     voiceMachine: DeepReadonly<Ref<VoiceMachine>>;
+    /** Whether the voice session is establishing its connection (`state === "connecting"`). */
+    voiceLoading: DeepReadonly<Ref<boolean>>;
+    /** Start a voice session. Must be invoked from a user gesture. */
     voiceStart: () => Promise<void>;
+    /** Stop the current voice session. */
     voiceStop: () => Promise<void>;
+    /** Toggle voice: start if idle/error, stop if active. */
     voiceToggle: () => Promise<void>;
 };
 /**

package/dist/composables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composables.d.ts","sourceRoot":"","sources":["../src/composables.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAGzB,KAAK,iBAAiB,EACtB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,YAAY,EAMjB,KAAK,GAAG,EAGT,MAAM,KAAK,CAAC;AAIb,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IAEnB,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACnC,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,qBAAqB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IAErE,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9C,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC;AAQF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CA6GrE;AAID;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAM/B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAUnE"}
+{"version":3,"file":"composables.d.ts","sourceRoot":"","sources":["../src/composables.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAGzB,KAAK,iBAAiB,EACtB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,YAAY,EAMjB,KAAK,GAAG,EAGT,MAAM,KAAK,CAAC;AAIb,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAAC;CACzC,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,MAAM,GAAG;IAEnB,gDAAgD;IAChD,MAAM,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACnC,4DAA4D;IAC5D,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,kFAAkF;IAClF,WAAW,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,sDAAsD;IACtD,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,iFAAiF;IACjF,qBAAqB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IAErE,wEAAwE;IACxE,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9C,2FAA2F;IAC3F,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IACzC,kEAAkE;IAClE,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,sCAAsC;IACtC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,yDAAyD;IACzD,WAAW,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC;AAQF;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAkHrE;AAID;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAM/B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAUnE"}

package/dist/composables.js

@@ -1,5 +1,5 @@
 import { INITIAL_VOICE_MACHINE, logger, YakEmbed, } from "@yak-io/javascript";
-import { inject, onMounted, onUnmounted, provide, readonly, ref, } from "vue";
+import { computed, inject, onMounted, onUnmounted, provide, readonly, ref, } from "vue";
 // ── Injection key ───────────────────────────────────────────────────────────
 const YAK_KEY = Symbol("yak");
 // ── Provider composable ─────────────────────────────────────────────────────
@@ -92,9 +92,12 @@ export function createYakProvider(options) {
             logger.warn("Voice start failed", err);
         }
     };
+    const chatLoading = computed(() => isOpen.value && !isReady.value);
+    const voiceLoading = computed(() => voiceMachine.value.state === "connecting");
     const api = {
         isOpen: readonly(isOpen),
         isReady: readonly(isReady),
+        chatLoading,
         open: () => embed.open(),
         close: () => embed.close(),
         openWithPrompt: (prompt) => embed.openWithPrompt(prompt),
@@ -105,6 +108,7 @@ export function createYakProvider(options) {
             };
         },
         voiceMachine: readonly(voiceMachine),
+        voiceLoading,
         voiceStart,
         voiceStop: () => embed.voiceStop(),
         voiceToggle: () => embed.voiceToggle(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yak-io/vue",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Vue SDK for embedding yak chatbot",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -25,6 +25,7 @@
     "node": ">=18"
   },
   "files": [
+    "README.md",
     "dist",
     "LICENSE"
   ],
@@ -41,7 +42,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@yak-io/javascript": "0.8.0"
+    "@yak-io/javascript": "0.9.0"
   },
   "peerDependencies": {
     "vue": "^3.3.0"
@@ -52,6 +53,7 @@
     "vue": "^3.5.34",
     "@repo/typescript-config": "0.0.0"
   },
+  "homepage": "https://docs.yak.io/docs/sdks/vue",
   "scripts": {
     "build": "tsc",
     "check-types": "tsc --noEmit",