@yak-io/javascript 0.10.1 → 0.11.1

package/dist/logger.js

@@ -1,117 +0,0 @@
-/**
- * Simple logger utility for the yak client SDK.
- * Debug/info logs are controlled by __YAK_LOGGING_ENABLED__.
- * Warnings and errors are always logged.
- *
- * Logging is controlled via:
- * 1. localStorage key "yakLogging" (persists across reloads)
- * 2. window.__YAK_LOGGING_ENABLED__ (runtime override)
- *
- * Use the helper functions to enable/disable:
- *   enableYakLogging()  - turns on logging, persists in localStorage
- *   disableYakLogging() - turns off logging, clears localStorage
- */
-const STORAGE_KEY = "yakLogging";
-function isLoggingEnabled() {
-    if (typeof window === "undefined") {
-        return false;
-    }
-    // Window flag takes precedence (runtime override)
-    if (typeof window.__YAK_LOGGING_ENABLED__ === "boolean") {
-        return window.__YAK_LOGGING_ENABLED__;
-    }
-    // Fall back to localStorage for persistence across reloads
-    try {
-        return localStorage.getItem(STORAGE_KEY) === "true";
-    }
-    catch {
-        // localStorage may be unavailable (e.g., private browsing)
-        return false;
-    }
-}
-/**
- * Check if Yak logging is currently enabled.
- * Useful for checking state before creating iframes.
- */
-export function isYakLoggingEnabled() {
-    return isLoggingEnabled();
-}
-/**
- * Enable Yak debug logging.
- * Persists in localStorage so it survives page reloads.
- * Call this from browser console: `enableYakLogging()`
- */
-export function enableYakLogging() {
-    if (typeof window === "undefined") {
-        return;
-    }
-    window.__YAK_LOGGING_ENABLED__ = true;
-    try {
-        localStorage.setItem(STORAGE_KEY, "true");
-    }
-    catch {
-        // localStorage may be unavailable
-    }
-    console.info("[yak] Logging enabled");
-}
-/**
- * Disable Yak debug logging.
- * Clears localStorage and window flag.
- * Call this from browser console: `disableYakLogging()`
- */
-export function disableYakLogging() {
-    if (typeof window === "undefined") {
-        return;
-    }
-    window.__YAK_LOGGING_ENABLED__ = false;
-    try {
-        localStorage.removeItem(STORAGE_KEY);
-    }
-    catch {
-        // localStorage may be unavailable
-    }
-    console.info("[yak] Logging disabled");
-}
-// Expose helpers globally so they can be called from browser console
-if (typeof window !== "undefined") {
-    window.enableYakLogging = enableYakLogging;
-    window.disableYakLogging = disableYakLogging;
-}
-export const logger = {
-    debug: (message, data) => {
-        if (isLoggingEnabled()) {
-            if (data !== undefined) {
-                console.log(`[yak-host] ${message}`, data);
-            }
-            else {
-                console.log(`[yak-host] ${message}`);
-            }
-        }
-    },
-    info: (message, data) => {
-        if (isLoggingEnabled()) {
-            if (data !== undefined) {
-                console.info(`[yak-host] ${message}`, data);
-            }
-            else {
-                console.info(`[yak-host] ${message}`);
-            }
-        }
-    },
-    warn: (message, data) => {
-        if (data !== undefined) {
-            console.warn(`[yak-host] ${message}`, data);
-        }
-        else {
-            console.warn(`[yak-host] ${message}`);
-        }
-    },
-    error: (message, data) => {
-        if (data !== undefined) {
-            console.error(`[yak-host] ${message}`, data);
-        }
-        else {
-            console.error(`[yak-host] ${message}`);
-        }
-    },
-};

package/dist/page-context.js

@@ -1,71 +0,0 @@
-/**
- * Extract visible text content from the DOM, filtering out non-content elements
- */
-function extractPageText() {
-    if (typeof document === "undefined")
-        return "";
-    // Clone the body to avoid modifying the actual DOM
-    const bodyClone = document.body.cloneNode(true);
-    // Remove script, style, noscript tags and hidden elements
-    const unwantedSelectors = [
-        "script",
-        "style",
-        "noscript",
-        "iframe",
-        "[style*='display: none']",
-        "[style*='display:none']",
-        "[hidden]",
-        ".yak-chat-widget",
-    ];
-    for (const selector of unwantedSelectors) {
-        const elements = bodyClone.querySelectorAll(selector);
-        for (const el of elements) {
-            el.remove();
-        }
-    }
-    // Get text content and clean it up
-    let text = bodyClone.textContent || bodyClone.innerText || "";
-    // Normalize whitespace: replace multiple spaces/newlines with single space
-    text = text.replace(/\s+/g, " ").trim();
-    // Limit to reasonable size (100KB max)
-    const maxLength = 100000;
-    if (text.length > maxLength) {
-        text = `${text.substring(0, maxLength)}... [truncated]`;
-    }
-    return text;
-}
-/**
- * Extract page context including URL, title, and visible text content
- */
-export function extractPageContext() {
-    if (typeof window === "undefined") {
-        return {
-            url: "",
-            title: "",
-            text: "",
-            timestamp: Date.now(),
-        };
-    }
-    return {
-        url: window.location.href,
-        title: document.title,
-        text: extractPageText(),
-        timestamp: Date.now(),
-    };
-}
-/**
- * Debounce function to limit how often a function is called
- */
-export function debounce(func, wait) {
-    let timeout = null;
-    return function executedFunction(...args) {
-        const later = () => {
-            timeout = null;
-            func(...args);
-        };
-        if (timeout) {
-            clearTimeout(timeout);
-        }
-        timeout = setTimeout(later, wait);
-    };
-}

package/dist/server/createYakHandler.js

@@ -1,185 +0,0 @@
-import { normalizeRouteSources, normalizeToolSources } from "./sources.js";
-export function createYakHandler(config) {
-    const routeSources = normalizeRouteSources(config.routes);
-    const toolSources = normalizeToolSources(config.tools);
-    const GET = async function handleConfig(_req) {
-        const chatConfig = {
-            routes: await buildRouteManifest(routeSources),
-        };
-        if (toolSources.length > 0) {
-            const { manifest } = await buildToolRegistry(toolSources);
-            chatConfig.tools = manifest;
-        }
-        return jsonResponse(chatConfig, 200, {
-            "Cache-Control": "no-store",
-        });
-    };
-    const POST = async function handleToolCall(req) {
-        if (toolSources.length === 0) {
-            return errorResponse("Tool execution is not configured", 501);
-        }
-        let payload;
-        try {
-            payload = await req.json();
-        }
-        catch {
-            return errorResponse("Invalid JSON payload", 400);
-        }
-        if (!isHostToolCallPayload(payload)) {
-            return errorResponse("Invalid tool call payload", 400);
-        }
-        try {
-            const { lookup } = await buildToolRegistry(toolSources);
-            const owner = lookup.get(payload.name);
-            if (!owner) {
-                return createToolErrorResponse(`Tool '${payload.name}' is not registered`);
-            }
-            if (!owner.executeTool) {
-                return createToolErrorResponse(`Tool '${payload.name}' does not expose an executor`);
-            }
-            const result = await owner.executeTool(payload.name, payload.args, req);
-            const successResult = {
-                ok: true,
-                result,
-            };
-            return jsonResponse(successResult);
-        }
-        catch (error) {
-            return createToolErrorResponse(extractErrorMessage(error));
-        }
-    };
-    return { GET, POST };
-}
-export function createYakConfigHandler(config) {
-    const routeSources = normalizeRouteSources(config.routes);
-    const toolSources = normalizeToolSources(config.tools);
-    return async function handleConfig(_req) {
-        const chatConfig = {
-            routes: await buildRouteManifest(routeSources),
-        };
-        if (toolSources.length > 0) {
-            const { manifest } = await buildToolRegistry(toolSources);
-            chatConfig.tools = manifest;
-        }
-        return jsonResponse(chatConfig, 200, {
-            "Cache-Control": "no-store",
-        });
-    };
-}
-export function createYakToolsHandler(config) {
-    const toolSources = normalizeToolSources(config.tools);
-    if (toolSources.length === 0) {
-        throw new Error("createYakToolsHandler requires at least one tool source");
-    }
-    return async function handleTools(req) {
-        let payload;
-        try {
-            payload = await req.json();
-        }
-        catch {
-            return errorResponse("Invalid JSON payload", 400);
-        }
-        if (!isHostToolCallPayload(payload)) {
-            return errorResponse("Invalid tool call payload", 400);
-        }
-        try {
-            const { lookup } = await buildToolRegistry(toolSources);
-            const owner = lookup.get(payload.name);
-            if (!owner) {
-                return createToolErrorResponse(`Tool '${payload.name}' is not registered`);
-            }
-            if (!owner.executeTool) {
-                return createToolErrorResponse(`Tool '${payload.name}' does not expose an executor`);
-            }
-            const result = await owner.executeTool(payload.name, payload.args, req);
-            const successResult = {
-                ok: true,
-                result,
-            };
-            return jsonResponse(successResult);
-        }
-        catch (error) {
-            return createToolErrorResponse(extractErrorMessage(error));
-        }
-    };
-}
-async function buildRouteManifest(routeSources) {
-    const entries = await Promise.all(routeSources.map(async (source) => ({
-        id: source.id ?? "routes",
-        routes: await source.getRoutes(),
-    })));
-    const merged = [];
-    const seen = new Set();
-    for (const entry of entries) {
-        for (const route of entry.routes) {
-            const key = route.path;
-            if (!seen.has(key)) {
-                seen.add(key);
-                merged.push(route);
-            }
-        }
-    }
-    merged.sort((a, b) => a.path.localeCompare(b.path));
-    return {
-        routes: merged,
-        generated_at: new Date().toISOString(),
-        sources: entries.map((entry) => ({ id: entry.id, count: entry.routes.length })),
-    };
-}
-async function buildToolRegistry(toolSources) {
-    const entries = await Promise.all(toolSources.map(async (source) => ({
-        id: source.id ?? "tools",
-        source,
-        tools: await source.getTools(),
-    })));
-    const manifestTools = [];
-    const lookup = new Map();
-    for (const entry of entries) {
-        for (const tool of entry.tools) {
-            manifestTools.push(tool);
-            lookup.set(tool.name, entry.source);
-        }
-    }
-    return {
-        manifest: {
-            tools: manifestTools,
-            generated_at: new Date().toISOString(),
-            sources: entries.map((entry) => ({ id: entry.id, count: entry.tools.length })),
-        },
-        lookup,
-    };
-}
-function isHostToolCallPayload(payload) {
-    return (typeof payload === "object" &&
-        payload !== null &&
-        typeof payload.name === "string" &&
-        "args" in payload);
-}
-function extractErrorMessage(error) {
-    if (error instanceof Error) {
-        return error.message;
-    }
-    if (typeof error === "string") {
-        return error;
-    }
-    return "An unknown error occurred";
-}
-function jsonResponse(body, status = 200, headers = {}) {
-    return new Response(JSON.stringify(body), {
-        status,
-        headers: {
-            "Content-Type": "application/json",
-            ...headers,
-        },
-    });
-}
-function errorResponse(message, status) {
-    return jsonResponse({ error: message }, status);
-}
-function createToolErrorResponse(error) {
-    const errorResult = {
-        ok: false,
-        error,
-    };
-    return jsonResponse(errorResult);
-}

package/dist/server/index.js

@@ -1,2 +0,0 @@
-export { createYakConfigHandler, createYakHandler, createYakToolsHandler, } from "./createYakHandler.js";
-export { normalizeRouteSources, normalizeToolSources, } from "./sources.js";

package/dist/server/sources.js

@@ -1,125 +0,0 @@
-function isRouteSource(value) {
-    return Boolean(value &&
-        typeof value === "object" &&
-        "getRoutes" in value &&
-        typeof value.getRoutes === "function");
-}
-function isRouteInfoArray(value) {
-    return Array.isArray(value) && value.every((route) => route && typeof route.path === "string");
-}
-function normalizeRouteSourceItem(item, index) {
-    if (isRouteSource(item)) {
-        return {
-            id: item.id ?? `route-source-${index}`,
-            getRoutes: item.getRoutes,
-        };
-    }
-    if (typeof item === "function") {
-        return {
-            id: `route-fn-${index}`,
-            getRoutes: item,
-        };
-    }
-    if (isRouteInfoArray(item)) {
-        return {
-            id: `route-static-${index}`,
-            getRoutes: async () => item,
-        };
-    }
-    throw new Error("Unsupported route source input");
-}
-export function normalizeRouteSources(input) {
-    if (Array.isArray(input)) {
-        if (input.length === 0) {
-            return [];
-        }
-        if (isRouteInfoArray(input)) {
-            return [normalizeRouteSourceItem(input, 0)];
-        }
-        return input.map((item, index) => normalizeRouteSourceItem(item, index));
-    }
-    return [normalizeRouteSourceItem(input, 0)];
-}
-function isToolSource(value) {
-    return Boolean(value &&
-        typeof value === "object" &&
-        "getTools" in value &&
-        typeof value.getTools === "function");
-}
-function isToolManifest(value) {
-    return Boolean(value && typeof value === "object" && "tools" in value);
-}
-function isToolDefinitionArray(value) {
-    return Array.isArray(value) && value.every((tool) => tool && typeof tool.name === "string");
-}
-function toToolDefinitions(result) {
-    if (isToolDefinitionArray(result)) {
-        return result;
-    }
-    if (isToolManifest(result)) {
-        return result.tools;
-    }
-    throw new Error("Tool source must resolve to ToolDefinition[] or ToolManifest");
-}
-function normalizeToolSourceItem(item, index) {
-    if (isToolSource(item)) {
-        return {
-            id: item.id ?? `tool-source-${index}`,
-            getTools: async () => {
-                const result = await item.getTools();
-                return toToolDefinitions(result);
-            },
-            executeTool: item.executeTool,
-        };
-    }
-    if (typeof item === "function") {
-        return {
-            id: `tool-fn-${index}`,
-            getTools: async () => {
-                const result = await item();
-                return toToolDefinitions(result);
-            },
-        };
-    }
-    if (isToolDefinitionArray(item)) {
-        return {
-            id: `tool-static-${index}`,
-            getTools: async () => item,
-        };
-    }
-    if (isToolManifest(item)) {
-        return {
-            id: `tool-manifest-${index}`,
-            getTools: async () => item.tools,
-        };
-    }
-    if (item &&
-        typeof item === "object" &&
-        "getTools" in item &&
-        typeof item.getTools === "function") {
-        return {
-            id: item.id ?? `tool-wrapper-${index}`,
-            getTools: async () => {
-                const result = await item.getTools();
-                return toToolDefinitions(result);
-            },
-            executeTool: item.executeTool,
-        };
-    }
-    throw new Error("Unsupported tool source input");
-}
-export function normalizeToolSources(input) {
-    if (!input) {
-        return [];
-    }
-    if (Array.isArray(input)) {
-        if (input.length === 0) {
-            return [];
-        }
-        if (isToolDefinitionArray(input)) {
-            return [normalizeToolSourceItem(input, 0)];
-        }
-        return input.map((item, index) => normalizeToolSourceItem(item, index));
-    }
-    return [normalizeToolSourceItem(input, 0)];
-}

package/dist/tool-name.js

@@ -1,42 +0,0 @@
-/** OpenAI/Realtime function names must match `^[a-zA-Z0-9_-]{1,64}$`. */
-const MAX_TOOL_NAME_LENGTH = 64;
-/**
- * Convert a host tool name into a model-facing function name.
- *
- * We sanitise to the allowed function-name charset (rather than hashing to an opaque
- * `yt_<hex>`), so the model keeps the semantic signal of a readable name — e.g.
- * `orders.list` → `orders_list`.
- *
- * This is a pure per-name transform; uniqueness across a manifest (and avoiding the
- * reserved `redirect` name / `mcp__` namespace) is handled by the caller via
- * {@link uniqueToolId}. Each runtime (the chat-ui iframe and this SDK's voice session)
- * decorates and reverse-maps with its own manifest, so the ids never need to match
- * across paths — only to be self-consistent within one.
- */
-export function generateToolId(originalName) {
-    const sanitized = originalName.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, MAX_TOOL_NAME_LENGTH);
-    return sanitized.length > 0 ? sanitized : "tool";
-}
-/** The MCP namespace prefix the voice/chat dispatchers route on. */
-const MCP_NAMESPACE_PREFIX = "mcp__";
-/**
- * Resolve a collision-free, model-safe id for a host tool name, given the ids already
- * taken in this manifest (seed `used` with reserved names like `redirect`). Host ids must
- * never start with the `mcp__` namespace, which the dispatcher routes on.
- */
-export function uniqueToolId(originalName, used) {
-    let base = generateToolId(originalName);
-    if (base.startsWith(MCP_NAMESPACE_PREFIX)) {
-        base = `t_${base}`.slice(0, MAX_TOOL_NAME_LENGTH);
-    }
-    if (!used.has(base))
-        return base;
-    for (let i = 2; i < 1000; i++) {
-        const suffix = `_${i}`;
-        const candidate = `${base.slice(0, MAX_TOOL_NAME_LENGTH - suffix.length)}${suffix}`;
-        if (!used.has(candidate))
-            return candidate;
-    }
-    // Pathological fallback — vanishingly unlikely in practice.
-    return `${base.slice(0, 56)}_${used.size}`;
-}

package/dist/toolset.js

@@ -1,119 +0,0 @@
-import { logger } from "./logger.js";
-/**
- * Compose client-side {@link ToolAdapter}s into ONE merged tool manifest and ONE
- * routed `onToolCall`. This is the single injection point for "available tools"
- * into the iframe: every adapter — client-side (GraphQL/REST/custom, run by your own
- * `execute` callback) or server-relayed ({@link createYakServerAdapter}) — contributes
- * its tools to the merged manifest and its executor to the routed handler. Because every
- * tool now flows through `onToolCall`, they all surface through `onToolCallComplete` /
- * `useYakToolEvent`.
- *
- * @example
- * ```tsx
- * const toolset = createYakToolset([
- *   createYakServerAdapter({ endpoint: "/api/yak" }),               // tRPC + custom server tools
- *   createGraphQLToolAdapter({ name: "shop", schema, execute: runShopQuery }),
- *   createRESTToolAdapter({ name: "billing", spec, execute: callBillingApi }),
- * ]);
- *
- * <YakProvider
- *   getConfig={async () => ({ routes, ...(await toolset.getConfig()) })}
- *   onToolCall={toolset.onToolCall}
- * />;
- * ```
- */
-export function createYakToolset(adapters) {
-    let cache = null;
-    async function resolve(force = false) {
-        if (cache && !force)
-            return cache;
-        cache = await Promise.all(adapters.map(async (adapter) => ({ adapter, tools: await adapter.getTools() })));
-        return cache;
-    }
-    async function getConfig() {
-        // Refresh on every config load — tools may depend on page/user.
-        const resolved = await resolve(true);
-        const tools = [];
-        const seen = new Set();
-        for (const { adapter, tools: adapterTools } of resolved) {
-            for (const tool of adapterTools) {
-                if (seen.has(tool.name)) {
-                    logger.warn(`Duplicate tool name "${tool.name}"; keeping the first and ignoring the one from adapter "${adapter.id ?? "unknown"}".`);
-                    continue;
-                }
-                seen.add(tool.name);
-                tools.push(tool);
-            }
-        }
-        return {
-            tools: {
-                tools,
-                sources: resolved.map(({ adapter, tools: adapterTools }, index) => ({
-                    id: adapter.id ?? `adapter-${index}`,
-                    count: adapterTools.length,
-                })),
-            },
-        };
-    }
-    const onToolCall = async (name, args) => {
-        // Fast path: explicit ownership predicates need no resolution.
-        for (const adapter of adapters) {
-            if (adapter.ownsTool?.(name)) {
-                return adapter.execute(name, args);
-            }
-        }
-        // Otherwise route by the adapter's resolved tool names.
-        const resolved = await resolve();
-        for (const { adapter, tools } of resolved) {
-            if (adapter.ownsTool)
-                continue; // already consulted above
-            if (tools.some((tool) => tool.name === name)) {
-                return adapter.execute(name, args);
-            }
-        }
-        throw new Error(`Unknown tool: ${name}`);
-    };
-    return { getConfig, onToolCall };
-}
-async function buildHeaders(source, base) {
-    const headers = new Headers(base);
-    const resolved = typeof source === "function" ? await source() : source;
-    if (resolved) {
-        for (const [key, value] of new Headers(resolved)) {
-            headers.set(key, value);
-        }
-    }
-    return headers;
-}
-/**
- * Bridge a server-side yak handler ({@link createYakHandler} /
- * `createNextYakHandler`, e.g. fronting the `@yak-io/trpc` adapter) into a
- * client-side {@link ToolAdapter}, so server-relayed tools merge into the same
- * manifest + `onToolCall` as browser-executed adapters.
- */
-export function createYakServerAdapter(config = {}) {
-    const endpoint = config.endpoint ?? "/api/yak";
-    return {
-        id: config.id ?? "server",
-        getTools: async () => {
-            const res = await fetch(endpoint, { headers: await buildHeaders(config.headers) });
-            if (!res.ok) {
-                throw new Error(`Failed to load tools from ${endpoint} (${res.status})`);
-            }
-            const chatConfig = (await res.json());
-            return chatConfig.tools?.tools ?? [];
-        },
-        execute: async (name, args) => {
-            const res = await fetch(endpoint, {
-                method: "POST",
-                headers: await buildHeaders(config.headers, { "Content-Type": "application/json" }),
-                body: JSON.stringify({ name, args }),
-            });
-            const data = (await res.json().catch(() => ({})));
-            if (!res.ok || !data.ok) {
-                throw new Error(data.error ?? `Tool "${name}" failed (${res.status})`);
-            }
-            return data.result;
-        },
-    };
-}

package/dist/types/config.js

@@ -1 +0,0 @@
-export {};

package/dist/types/messaging.js

@@ -1 +0,0 @@
-export {};

package/dist/types/routes.js

@@ -1 +0,0 @@
-export {};

package/dist/types/tools.js

@@ -1 +0,0 @@
-export {};

package/dist/version.js

@@ -1,18 +0,0 @@
-/**
- * Embed protocol version.
- *
- * This version is used in the embed URL path (e.g., /embed/v1/[appId])
- * and in the message protocol to ensure compatibility between the
- * host packages (@yak-io/javascript, @yak-io/react, @yak-io/nextjs)
- * and the embedded chat UI.
- *
- * Increment this version when making breaking changes to:
- * - The postMessage protocol (IframeMessageFromHost, IframeMessageToHost)
- * - The tool manifest format
- * - The route manifest format
- * - The config payload structure
- *
- * Version history:
- * - v1: Initial versioned protocol
- */
-export const EMBED_PROTOCOL_VERSION = "1";