@yak-io/javascript 0.6.0 → 0.7.0

package/README.md

@@ -0,0 +1,181 @@
+# @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
+
+```bash
+pnpm add @yak-io/javascript
+```
+
+## Quickstart — Vanilla JS
+
+```ts
+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:
+
+```ts
+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.
+
+```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
+
+```ts
+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:
+
+```ts
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yak-io/javascript",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Core JavaScript SDK for embedding yak chatbot",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -56,7 +56,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.10.4",
+    "@types/node": "^24.12.0",
     "typescript": "^5.3.0",
     "@repo/typescript-config": "0.0.0"
   },