@yak-io/angular 0.3.0 → 0.4.0

package/README.md

@@ -1,13 +1,23 @@
 # @yak-io/angular
 
-Angular integration for the Yak embeddable chat widget. Uses a factory function compatible with Angular's component and service patterns.
+> 📚 **Full documentation:** https://docs.yak.io/docs/sdks/angular
+>
+> 🤖 **For LLMs / AI agents:** https://docs.yak.io/llms.txt
 
-## Installation
+Angular SDK for [Yak](https://docs.yak.io) — an embeddable AI assistant (text chat **and** push-to-talk voice) for web apps. `createYakProvider` returns a `YakApi`; bridge its state into Angular signals (or RxJS) with `subscribeToState`.
 
 ```bash
 pnpm add @yak-io/angular
 ```
 
+## Exports
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `createYakProvider(options)` | fn | Create a widget instance. Returns a `YakApi` with `mount`/`destroy` + `subscribeToState`. |
+| `enableYakLogging` / `disableYakLogging` / `isYakLoggingEnabled` | fn | Toggle verbose SDK logging. |
+| Types | — | `YakProviderOptions`, `YakApi`, `YakState`, `ToolCallEventHandler`, plus core types from `@yak-io/javascript`. |
+
 ## Quickstart
 
 ### 1. Initialize in your root component
@@ -26,32 +36,27 @@ import { environment } from "../environments/environment";
 })
 export class AppComponent implements OnInit, OnDestroy {
   private router = inject(Router);
-  private yak: YakApi;
-
-  constructor() {
-    this.yak = createYakProvider({
-      appId: environment.yakAppId,
-      theme: { position: "bottom-right", colorMode: "system" },
-      trigger: { label: "Ask with AI" },
-      getConfig: async () => {
-        const res = await fetch("/api/yak");
-        return res.json();
-      },
-      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;
-      },
-      onRedirect: (path) => {
-        this.router.navigateByUrl(path);
-      },
-    });
-  }
+  private yak: YakApi = createYakProvider({
+    appId: environment.yakAppId,
+    mode: "both",   // "chat" | "voice" | "both" — default "chat"
+    trigger: true,  // show the floating launcher pill
+    theme: { position: "bottom-right", colorMode: "system" },
+    getConfig: async () => {
+      const res = await fetch("/api/yak");
+      return res.json();
+    },
+    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;
+    },
+    onRedirect: (path) => this.router.navigateByUrl(path),
+  });
 
   ngOnInit() {
     this.yak.mount();
@@ -63,9 +68,7 @@ export class AppComponent implements OnInit, OnDestroy {
 }
 ```
 
-### 2. Share via an Angular service
-
-Create a service to share the widget API across components:
+### 2. Share via a service
 
 ```ts
 // yak.service.ts
@@ -76,95 +79,108 @@ import type { YakApi } from "@yak-io/angular";
 export class YakService {
   private yak: YakApi | null = null;
   readonly isOpen = signal(false);
-  readonly isReady = signal(false);
 
-  setYak(yak: YakApi) {
+  register(yak: YakApi) {
     this.yak = yak;
-    yak.subscribeToState(({ isOpen, isReady }) => {
-      this.isOpen.set(isOpen);
-      this.isReady.set(isReady);
-    });
+    yak.subscribeToState((state) => this.isOpen.set(state.isOpen));
   }
 
   open() { this.yak?.open(); }
-  close() { this.yak?.close(); }
   openWithPrompt(prompt: string) { this.yak?.openWithPrompt(prompt); }
+  voiceToggle() { return this.yak?.voiceToggle(); }
 }
 ```
 
-### 3. Use in components
+Call `yakService.register(this.yak)` from your root component, then inject `YakService` anywhere:
 
 ```ts
-// any.component.ts
-import { Component, inject } from "@angular/core";
-import { YakService } from "./yak.service";
-
 @Component({
-  template: `
-    <button (click)="yakService.open()">Open Chat</button>
-    <p *ngIf="yakService.isOpen()">Chat is open</p>
-  `,
+  template: `<button (click)="yak.open()">Open chat</button>
+             <span *ngIf="yak.isOpen()">Chat is open</span>`,
 })
-export class AnyComponent {
-  yakService = inject(YakService);
+export class HeaderComponent {
+  yak = inject(YakService);
 }
 ```
 
-## API Reference
+## Voice
 
-### `createYakProvider(options)`
+Set `mode: "voice"` or `mode: "both"`, then drive the session. `voiceStart()` must run from a user gesture (browser mic requirement). Voice state arrives through `subscribeToState` as `state.voiceMachine`:
 
-Creates a Yak widget instance. Returns a `YakApi` object.
+```ts
+yak.subscribeToState((state) => {
+  this.voiceState.set(state.voiceMachine.state); // "idle" | "listening" | "speaking" | ...
+});
+// button handler:
+this.yak.voiceToggle();
+```
 
-Call `yak.mount()` in `ngOnInit()` and `yak.destroy()` in `ngOnDestroy()`.
+## Tool events
 
-**Options:**
+```ts
+yak.subscribeToToolEvents((event) => {
+  // { name, args, ok, result?, error? }
+  if (event.ok && event.name.startsWith("tasks.")) this.refreshTasks();
+});
+```
 
-| 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 |
+## API reference
+
+### `createYakProvider(options)`
+
+Returns a `YakApi`. Call `yak.mount()` in `ngOnInit()` and `yak.destroy()` in `ngOnDestroy()`.
+
+| 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. |
 
 ### `YakApi`
 
+State (`isOpen`/`isReady`/`voiceMachine`) is read via the `subscribeToState` callback — Angular has no built-in reactive primitive the SDK can return, so wire it into signals or RxJS yourself.
+
 ```ts
+type YakState = {
+  isOpen: boolean;
+  isReady: boolean;
+  chatLoading: boolean;
+  voiceMachine: VoiceMachine;
+  voiceLoading: boolean;
+};
+
 type YakApi = {
-  readonly isOpen: boolean;  // Plain boolean (use subscribeToState for reactivity)
-  readonly isReady: boolean; // Plain boolean
+  readonly isOpen: boolean;        // snapshot — use subscribeToState for reactivity
+  readonly isReady: boolean;       // snapshot
+  readonly chatLoading: boolean;   // snapshot — isOpen && !isReady
+  readonly voiceMachine: VoiceMachine; // snapshot — { state, errorMessage? }
+  readonly voiceLoading: boolean;  // snapshot — state === "connecting"
   open: () => void;
   close: () => void;
   openWithPrompt: (prompt: string) => void;
+  voiceStart: () => Promise<void>;
+  voiceStop: () => Promise<void>;
+  voiceToggle: () => Promise<void>;
   subscribeToToolEvents: (handler: ToolCallEventHandler) => () => void;
-  subscribeToState: (handler: (state: { isOpen: boolean; isReady: boolean }) => void) => () => void;
-  mount: () => void;    // Call in ngOnInit() or ngAfterViewInit()
-  destroy: () => void;  // Call in ngOnDestroy()
+  subscribeToState: (handler: (state: YakState) => void) => () => void;
+  mount: () => void;    // call in ngOnInit()
+  destroy: () => void;  // call in ngOnDestroy()
 };
 ```
 
-Use `subscribeToState` to react to state changes — wire it to Angular signals, `BehaviorSubject`s, or change detection:
-
-```ts
-yak.subscribeToState(({ isOpen, isReady }) => {
-  this.isOpen.set(isOpen);
-  this.changeDetector.markForCheck();
-});
-```
-
 ## Logging
 
 ```ts
 import { enableYakLogging, disableYakLogging, isYakLoggingEnabled } from "@yak-io/angular";
 
-enableYakLogging();    // Enable verbose SDK logs
-disableYakLogging();   // Disable SDK logs
-isYakLoggingEnabled(); // → boolean
+enableYakLogging(); // verbose SDK logs
 ```
 
 ## Types
@@ -173,16 +189,19 @@ isYakLoggingEnabled(); // → boolean
 import type {
   YakProviderOptions,
   YakApi,
+  YakState,
   ToolCallEventHandler,
   ChatConfigProvider,
   ToolCallHandler,
   ToolCallEvent,
   Theme,
-  TriggerButtonConfig,
+  WidgetMode,
   WidgetPosition,
+  VoiceState,
+  VoiceMachine,
 } from "@yak-io/angular";
 ```
 
 ## License
 
-Proprietary — see LICENSE file.
+Proprietary — see [LICENSE](./LICENSE).

package/dist/service.d.ts

@@ -15,22 +15,41 @@ export type YakProviderOptions = {
 export type YakState = {
     isOpen: boolean;
     isReady: boolean;
+    chatLoading: boolean;
     voiceMachine: VoiceMachine;
+    voiceLoading: boolean;
 };
+/** Handle for controlling the Yak widget — chat + voice — from Angular. */
 export type YakApi = {
+    /** Whether the chat panel is currently open. */
     readonly isOpen: boolean;
+    /** Whether the chat iframe is ready to receive messages. */
     readonly isReady: boolean;
+    /** Whether the chat is opening but not yet interactive (`isOpen && !isReady`). */
+    readonly chatLoading: boolean;
+    /** Current voice state-machine snapshot. `idle` when mode is `chat`. */
     readonly voiceMachine: VoiceMachine;
+    /** Whether the voice session is establishing its connection (`state === "connecting"`). */
+    readonly voiceLoading: 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;
+    /** 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>;
+    /** Subscribe to tool-call completion events; returns an unsubscribe function. */
     subscribeToToolEvents: (handler: ToolCallEventHandler) => () => void;
     /** Subscribe to chat + voice state changes. */
     subscribeToState: (handler: (state: YakState) => void) => () => void;
+    /** Mount the widget into the DOM. */
     mount: () => void;
+    /** Tear down the widget and remove its listeners. */
     destroy: () => void;
 };
 /**

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.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;AAI5B,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,QAAQ,GAAG;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,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;IACjC,qBAAqB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IACrE,+CAA+C;IAC/C,gBAAgB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACrE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAIF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CA6HrE"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.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;AAI5B,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,QAAQ,GAAG;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,MAAM,GAAG;IACnB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,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,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;IACjC,iFAAiF;IACjF,qBAAqB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,MAAM,IAAI,CAAC;IACrE,+CAA+C;IAC/C,gBAAgB,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACrE,qCAAqC;IACrC,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAIF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAyIrE"}

package/dist/service.js

@@ -11,7 +11,13 @@ export function createYakProvider(options) {
     const toolEventSubscribers = new Set();
     const stateSubscribers = new Set();
     const notifyState = () => {
-        const snap = { isOpen: _isOpen, isReady: _isReady, voiceMachine: _voiceMachine };
+        const snap = {
+            isOpen: _isOpen,
+            isReady: _isReady,
+            chatLoading: _isOpen && !_isReady,
+            voiceMachine: _voiceMachine,
+            voiceLoading: _voiceMachine.state === "connecting",
+        };
         for (const subscriber of stateSubscribers) {
             try {
                 subscriber(snap);
@@ -95,9 +101,15 @@ export function createYakProvider(options) {
         get isReady() {
             return _isReady;
         },
+        get chatLoading() {
+            return _isOpen && !_isReady;
+        },
         get voiceMachine() {
             return _voiceMachine;
         },
+        get voiceLoading() {
+            return _voiceMachine.state === "connecting";
+        },
         open: () => embed.open(),
         close: () => embed.close(),
         openWithPrompt: (prompt) => embed.openWithPrompt(prompt),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yak-io/angular",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Angular 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": {
     "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0"
@@ -51,6 +52,7 @@
     "typescript": "^5.3.0",
     "@repo/typescript-config": "0.0.0"
   },
+  "homepage": "https://docs.yak.io/docs/sdks/angular",
   "scripts": {
     "build": "tsc",
     "check-types": "tsc --noEmit",