@useago/sdk 0.1.6 → 0.2.0

package/dist/index.cjs

@@ -1,20 +1,315 @@
-"use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const createMockClient = require("./createMockClient-BZKh_1em.cjs");
+const require_AgoClient = require("./AgoClient-D0l1GTRs.cjs");
+const require_createMockClient = require("./createMockClient-Ci_N2tH8.cjs");
+const require_functions = require("./functions--c6lx3ic.cjs");
+//#region src/functions/defineFunction.ts
+/**
+* Create a reusable function definition.
+* Returns the same object — this is an identity function for discoverability and type-checking.
+*
+* ```ts
+* // Define once, reuse anywhere
+* export const lookupOrder = defineFunction({
+*   name: "lookupOrder",
+*   description: "Look up an order by ID",
+*   parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+*   handler: async (args) => fetchOrder(args.id as string),
+* });
+*
+* // Register with client
+* client.registerFunction(lookupOrder);
+*
+* // Or use in React
+* useAgoFunction(lookupOrder.name, lookupOrder);
+* ```
+*/
 function defineFunction(definition) {
-  return definition;
-}
-exports.AgoApiError = createMockClient.AgoApiError;
-exports.AgoClient = createMockClient.AgoClient;
-exports.AgoError = createMockClient.AgoError;
-exports.AgoFunctionError = createMockClient.AgoFunctionError;
-exports.AgoNetworkError = createMockClient.AgoNetworkError;
-exports.AgoStreamError = createMockClient.AgoStreamError;
-exports.EventEmitter = createMockClient.EventEmitter;
-exports.FunctionRegistry = createMockClient.FunctionRegistry;
-exports.SSEHandler = createMockClient.SSEHandler;
-exports.createMockClient = createMockClient.createMockClient;
-exports.isStreamNetworkError = createMockClient.isStreamNetworkError;
-exports.logger = createMockClient.logger;
+	return definition;
+}
+//#endregion
+//#region src/streaming/helpers.ts
+/**
+* Subscribe to complete messages with a simple callback. Returns an unsubscribe function.
+*
+* ```ts
+* const unsub = onMessage(client, (msg) => console.log(msg.content));
+* // later: unsub();
+* ```
+*/
+function onMessage(client, callback) {
+	client.on("message:complete", callback);
+	return () => client.off("message:complete", callback);
+}
+/**
+* Subscribe to streaming text chunks.
+*
+* ```ts
+* onMessageChunk(client, ({ content }) => {
+*   outputEl.textContent += content;
+* });
+* ```
+*/
+function onMessageChunk(client, callback) {
+	client.on("message:chunk", callback);
+	return () => client.off("message:chunk", callback);
+}
+/**
+* Subscribe to message start events.
+*/
+function onMessageStart(client, callback) {
+	client.on("message:start", callback);
+	return () => client.off("message:start", callback);
+}
+/**
+* Subscribe to message errors.
+*/
+function onMessageError(client, callback) {
+	client.on("message:error", callback);
+	return () => client.off("message:error", callback);
+}
+/**
+* Subscribe to tool call events.
+*/
+function onToolCall(client, callback) {
+	client.on("toolCall:received", callback);
+	return () => client.off("toolCall:received", callback);
+}
+/**
+* Subscribe to client function invocations.
+*/
+function onFunctionInvoke(client, callback) {
+	client.on("function:invoke", callback);
+	return () => client.off("function:invoke", callback);
+}
+/**
+* Send a message and iterate over chunks as an async generator.
+* Gives you full control over how you process the stream.
+*
+* ```ts
+* for await (const chunk of createMessageStream(client, "Hello!")) {
+*   console.log(chunk.type, chunk.data);
+* }
+* ```
+*/
+async function* createMessageStream(client, content, options) {
+	const queue = [];
+	let resolve = null;
+	let done = false;
+	const push = (event) => {
+		queue.push(event);
+		resolve?.();
+	};
+	const onStart = (data) => push({
+		type: "start",
+		data
+	});
+	const onChunk = (data) => push({
+		type: "chunk",
+		data
+	});
+	const onComplete = (data) => {
+		push({
+			type: "complete",
+			data
+		});
+		done = true;
+		resolve?.();
+	};
+	const onError = (data) => {
+		push({
+			type: "error",
+			data
+		});
+		done = true;
+		resolve?.();
+	};
+	const onTool = (data) => push({
+		type: "toolCall",
+		data
+	});
+	client.on("message:start", onStart);
+	client.on("message:chunk", onChunk);
+	client.on("message:complete", onComplete);
+	client.on("message:error", onError);
+	client.on("toolCall:received", onTool);
+	client.sendMessage(content, options).catch(() => {
+		done = true;
+		resolve?.();
+	});
+	try {
+		while (!done || queue.length > 0) if (queue.length > 0) yield queue.shift();
+		else {
+			await new Promise((r) => {
+				resolve = r;
+			});
+			resolve = null;
+		}
+	} finally {
+		client.off("message:start", onStart);
+		client.off("message:chunk", onChunk);
+		client.off("message:complete", onComplete);
+		client.off("message:error", onError);
+		client.off("toolCall:received", onTool);
+	}
+}
+//#endregion
+//#region src/auto/createAgo.ts
+/**
+* Auto-detect AGO configuration from the DOM environment.
+*
+* Checks (in order of priority):
+* 1. `window.AGO` global object (widget config)
+* 2. `<meta>` tags: `<meta name="ago-api-key" content="...">`
+* 3. `data-ago-*` attributes on `<body>` or `<script data-ago-api-key="...">`
+* 4. Explicit overrides passed as argument
+*
+* Returns null if no API key can be found.
+*/
+function autoDetectConfig(overrides) {
+	let baseUrl;
+	let widgetId;
+	let agent;
+	let permission;
+	let userEmail;
+	let userJwt;
+	if (typeof window !== "undefined" && window.AGO) {
+		const ago = window.AGO;
+		baseUrl = ago.basepath;
+		widgetId = ago.widgetId;
+		agent = ago.agent || ago.defaultAgent;
+		permission = ago.permission;
+		userEmail = ago.email;
+		userJwt = ago.jwt;
+	}
+	if (typeof document !== "undefined") {
+		const getMeta = (name) => document.querySelector(`meta[name="${name}"]`)?.getAttribute("content") || void 0;
+		baseUrl = baseUrl || getMeta("ago-base-url");
+		widgetId = widgetId || getMeta("ago-widget-id");
+		agent = agent || getMeta("ago-agent") || getMeta("ago-agent-id");
+		permission = permission || getMeta("ago-permission");
+		userEmail = userEmail || getMeta("ago-user-email");
+	}
+	if (typeof document !== "undefined") {
+		const sources = [document.body, ...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);
+		for (const el of sources) {
+			if (!el) continue;
+			baseUrl = baseUrl || el.getAttribute("data-ago-base-url") || void 0;
+			widgetId = widgetId || el.getAttribute("data-ago-widget-id") || void 0;
+			agent = agent || el.getAttribute("data-ago-agent") || el.getAttribute("data-ago-agent-id") || void 0;
+			permission = permission || el.getAttribute("data-ago-permission") || void 0;
+			userEmail = userEmail || el.getAttribute("data-ago-user-email") || void 0;
+		}
+	}
+	baseUrl = overrides?.baseUrl || baseUrl;
+	widgetId = overrides?.widgetId || widgetId;
+	agent = overrides?.agent || overrides?.defaultAgentId || agent;
+	permission = overrides?.permission || permission;
+	userEmail = overrides?.userEmail || userEmail;
+	userJwt = overrides?.userJwt || userJwt;
+	const debug = overrides?.debug;
+	if (!baseUrl) return null;
+	return {
+		baseUrl,
+		widgetId,
+		agent,
+		permission,
+		userEmail,
+		userJwt,
+		debug
+	};
+}
+/**
+* Create an AgoClient with zero configuration.
+* Auto-detects config from window.AGO, meta tags, and data-ago-* attributes.
+*
+* ```html
+* <!-- In your HTML -->
+* <meta name="ago-base-url" content="https://YOUR-DOMAIN.useago.com">
+*
+* <!-- Or on a script tag -->
+* <script src="app.js" data-ago-base-url="https://YOUR-DOMAIN.useago.com"><\/script>
+* ```
+*
+* ```ts
+* import { createAgo } from "@useago/sdk";
+*
+* // Zero config — picks up from DOM
+* const client = createAgo();
+*
+* // Or with partial overrides
+* const client = createAgo({ debug: true });
+* ```
+*
+* Throws if no base URL can be detected.
+*/
+function createAgo(overrides) {
+	const config = autoDetectConfig(overrides);
+	if (!config) throw new Error("createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name=\"ago-base-url\">, or pass { baseUrl } explicitly.");
+	return new require_AgoClient.AgoClient(config);
+}
+//#endregion
+//#region src/helpers/factory.ts
+/**
+* Attach a handler to a pre-built function definition.
+*
+* Pre-built helpers (`showToast`, `trackEvent`, ...) ship with a no-op or
+* console-logging default handler. Use `withHandler` to wire them up to
+* your actual implementation without mutating the original definition.
+*
+* ```ts
+* import { showToast, withHandler } from "@useago/sdk";
+*
+* client.register(
+*   withHandler(showToast, (args) => {
+*     myToast(args.message as string);
+*     return { shown: true };
+*   })
+* );
+* ```
+*/
+function withHandler(definition, handler) {
+	return {
+		...definition,
+		handler
+	};
+}
+//#endregion
+exports.AgoApiError = require_AgoClient.AgoApiError;
+exports.AgoClient = require_AgoClient.AgoClient;
+exports.AgoError = require_AgoClient.AgoError;
+exports.AgoFunctionError = require_AgoClient.AgoFunctionError;
+exports.AgoNetworkError = require_AgoClient.AgoNetworkError;
+exports.AgoStreamError = require_AgoClient.AgoStreamError;
+exports.ClientContextRegistry = require_AgoClient.ClientContextRegistry;
+exports.EventEmitter = require_AgoClient.EventEmitter;
+exports.FunctionRegistry = require_AgoClient.FunctionRegistry;
+exports.SSEHandler = require_AgoClient.SSEHandler;
+exports.autoDetectConfig = autoDetectConfig;
+exports.copyToClipboard = require_functions.copyToClipboard;
+exports.createAgo = createAgo;
+exports.createMessageStream = createMessageStream;
+exports.createMockClient = require_createMockClient.createMockClient;
 exports.defineFunction = defineFunction;
-//# sourceMappingURL=index.cjs.map
+exports.getLocalStorage = require_functions.getLocalStorage;
+exports.getUserLocation = require_functions.getUserLocation;
+exports.highlightElement = require_functions.highlightElement;
+exports.isStreamNetworkError = require_AgoClient.isStreamNetworkError;
+exports.logger = require_AgoClient.logger;
+exports.onFunctionInvoke = onFunctionInvoke;
+exports.onMessage = onMessage;
+exports.onMessageChunk = onMessageChunk;
+exports.onMessageError = onMessageError;
+exports.onMessageStart = onMessageStart;
+exports.onToolCall = onToolCall;
+exports.openUrl = require_functions.openUrl;
+exports.scrollToElement = require_functions.scrollToElement;
+exports.setLocalStorage = require_functions.setLocalStorage;
+exports.setTheme = require_functions.setTheme;
+exports.showConfirmDialog = require_functions.showConfirmDialog;
+exports.showNotification = require_functions.showNotification;
+exports.showToast = require_functions.showToast;
+exports.submitForm = require_functions.submitForm;
+exports.trackEvent = require_functions.trackEvent;
+exports.withHandler = withHandler;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/functions/defineFunction.ts"],"sourcesContent":["import type { ClientFunctionDefinition } from \"./types\";\n\n/**\n * Create a reusable function definition.\n * Returns the same object — this is an identity function for discoverability and type-checking.\n *\n * ```ts\n * // Define once, reuse anywhere\n * export const lookupOrder = defineFunction({\n *   name: \"lookupOrder\",\n *   description: \"Look up an order by ID\",\n *   parameters: { type: \"object\", properties: { id: { type: \"string\" } }, required: [\"id\"] },\n *   handler: async (args) => fetchOrder(args.id as string),\n * });\n *\n * // Register with client\n * client.registerFunction(lookupOrder);\n *\n * // Or use in React\n * useAgoFunction(lookupOrder.name, lookupOrder);\n * ```\n */\nexport function defineFunction(\n  definition: ClientFunctionDefinition\n): ClientFunctionDefinition {\n  return definition;\n}\n"],"names":[],"mappings":";;;AAsBO,SAAS,eACd,YAC0B;AAC1B,SAAO;AACT;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/functions/defineFunction.ts","../src/streaming/helpers.ts","../src/auto/createAgo.ts","../src/helpers/factory.ts"],"sourcesContent":["import type { ClientFunctionDefinition } from \"./types\";\n\n/**\n * Create a reusable function definition.\n * Returns the same object — this is an identity function for discoverability and type-checking.\n *\n * ```ts\n * // Define once, reuse anywhere\n * export const lookupOrder = defineFunction({\n *   name: \"lookupOrder\",\n *   description: \"Look up an order by ID\",\n *   parameters: { type: \"object\", properties: { id: { type: \"string\" } }, required: [\"id\"] },\n *   handler: async (args) => fetchOrder(args.id as string),\n * });\n *\n * // Register with client\n * client.registerFunction(lookupOrder);\n *\n * // Or use in React\n * useAgoFunction(lookupOrder.name, lookupOrder);\n * ```\n */\nexport function defineFunction(\n  definition: ClientFunctionDefinition\n): ClientFunctionDefinition {\n  return definition;\n}\n","import type { AgoClient } from \"../client/AgoClient\";\nimport type {\n  AgoMessage,\n  AgoClientEvents,\n  ToolCallData,\n  ClientFunctionInvocation,\n} from \"../client/types\";\n\n/**\n * Subscribe to complete messages with a simple callback. Returns an unsubscribe function.\n *\n * ```ts\n * const unsub = onMessage(client, (msg) => console.log(msg.content));\n * // later: unsub();\n * ```\n */\nexport function onMessage(\n  client: AgoClient,\n  callback: (message: AgoMessage) => void\n): () => void {\n  client.on(\"message:complete\", callback);\n  return () => client.off(\"message:complete\", callback);\n}\n\n/**\n * Subscribe to streaming text chunks.\n *\n * ```ts\n * onMessageChunk(client, ({ content }) => {\n *   outputEl.textContent += content;\n * });\n * ```\n */\nexport function onMessageChunk(\n  client: AgoClient,\n  callback: (data: AgoClientEvents[\"message:chunk\"]) => void\n): () => void {\n  client.on(\"message:chunk\", callback);\n  return () => client.off(\"message:chunk\", callback);\n}\n\n/**\n * Subscribe to message start events.\n */\nexport function onMessageStart(\n  client: AgoClient,\n  callback: (data: AgoClientEvents[\"message:start\"]) => void\n): () => void {\n  client.on(\"message:start\", callback);\n  return () => client.off(\"message:start\", callback);\n}\n\n/**\n * Subscribe to message errors.\n */\nexport function onMessageError(\n  client: AgoClient,\n  callback: (data: AgoClientEvents[\"message:error\"]) => void\n): () => void {\n  client.on(\"message:error\", callback);\n  return () => client.off(\"message:error\", callback);\n}\n\n/**\n * Subscribe to tool call events.\n */\nexport function onToolCall(\n  client: AgoClient,\n  callback: (toolCall: ToolCallData) => void\n): () => void {\n  client.on(\"toolCall:received\", callback);\n  return () => client.off(\"toolCall:received\", callback);\n}\n\n/**\n * Subscribe to client function invocations.\n */\nexport function onFunctionInvoke(\n  client: AgoClient,\n  callback: (data: ClientFunctionInvocation) => void\n): () => void {\n  client.on(\"function:invoke\", callback);\n  return () => client.off(\"function:invoke\", callback);\n}\n\n/**\n * Send a message and iterate over chunks as an async generator.\n * Gives you full control over how you process the stream.\n *\n * ```ts\n * for await (const chunk of createMessageStream(client, \"Hello!\")) {\n *   console.log(chunk.type, chunk.data);\n * }\n * ```\n */\nexport async function* createMessageStream(\n  client: AgoClient,\n  content: string,\n  options?: { conversationId?: string; agentId?: string; files?: File[] }\n): AsyncGenerator<\n  | { type: \"start\"; data: AgoClientEvents[\"message:start\"] }\n  | { type: \"chunk\"; data: AgoClientEvents[\"message:chunk\"] }\n  | { type: \"complete\"; data: AgoMessage }\n  | { type: \"error\"; data: AgoClientEvents[\"message:error\"] }\n  | { type: \"toolCall\"; data: ToolCallData }\n> {\n  type StreamEvent =\n    | { type: \"start\"; data: AgoClientEvents[\"message:start\"] }\n    | { type: \"chunk\"; data: AgoClientEvents[\"message:chunk\"] }\n    | { type: \"complete\"; data: AgoMessage }\n    | { type: \"error\"; data: AgoClientEvents[\"message:error\"] }\n    | { type: \"toolCall\"; data: ToolCallData };\n\n  const queue: StreamEvent[] = [];\n  let resolve: (() => void) | null = null;\n  let done = false;\n\n  const push = (event: StreamEvent) => {\n    queue.push(event);\n    resolve?.();\n  };\n\n  const onStart = (data: AgoClientEvents[\"message:start\"]) => push({ type: \"start\", data });\n  const onChunk = (data: AgoClientEvents[\"message:chunk\"]) => push({ type: \"chunk\", data });\n  const onComplete = (data: AgoMessage) => {\n    push({ type: \"complete\", data });\n    done = true;\n    resolve?.();\n  };\n  const onError = (data: AgoClientEvents[\"message:error\"]) => {\n    push({ type: \"error\", data });\n    done = true;\n    resolve?.();\n  };\n  const onTool = (data: ToolCallData) => push({ type: \"toolCall\", data });\n\n  client.on(\"message:start\", onStart);\n  client.on(\"message:chunk\", onChunk);\n  client.on(\"message:complete\", onComplete);\n  client.on(\"message:error\", onError);\n  client.on(\"toolCall:received\", onTool);\n\n  // Fire the request (don't await — we'll consume events via the generator)\n  client.sendMessage(content, options).catch(() => {\n    done = true;\n    resolve?.();\n  });\n\n  try {\n    while (!done || queue.length > 0) {\n      if (queue.length > 0) {\n        yield queue.shift()!;\n      } else {\n        await new Promise<void>((r) => { resolve = r; });\n        resolve = null;\n      }\n    }\n  } finally {\n    client.off(\"message:start\", onStart);\n    client.off(\"message:chunk\", onChunk);\n    client.off(\"message:complete\", onComplete);\n    client.off(\"message:error\", onError);\n    client.off(\"toolCall:received\", onTool);\n  }\n}\n","import { AgoClient } from \"../client/AgoClient\";\nimport type { AgoConfig } from \"../client/types\";\n\n/**\n * Auto-detect AGO configuration from the DOM environment.\n *\n * Checks (in order of priority):\n * 1. `window.AGO` global object (widget config)\n * 2. `<meta>` tags: `<meta name=\"ago-api-key\" content=\"...\">`\n * 3. `data-ago-*` attributes on `<body>` or `<script data-ago-api-key=\"...\">`\n * 4. Explicit overrides passed as argument\n *\n * Returns null if no API key can be found.\n */\nexport function autoDetectConfig(\n  overrides?: Partial<AgoConfig>\n): AgoConfig | null {\n  let baseUrl: string | undefined;\n  let widgetId: string | undefined;\n  let agent: string | undefined;\n  let permission: string | undefined;\n  let userEmail: string | undefined;\n  let userJwt: string | undefined;\n\n  // 1. window.AGO (widget config format)\n  if (typeof window !== \"undefined\" && (window as unknown as Record<string, unknown>).AGO) {\n    const ago = (window as unknown as Record<string, unknown>).AGO as Record<string, unknown>;\n    baseUrl = ago.basepath as string | undefined;\n    widgetId = ago.widgetId as string | undefined;\n    agent = (ago.agent as string | undefined) || (ago.defaultAgent as string | undefined);\n    permission = ago.permission as string | undefined;\n    userEmail = ago.email as string | undefined;\n    userJwt = ago.jwt as string | undefined;\n  }\n\n  // 2. Meta tags\n  if (typeof document !== \"undefined\") {\n    const getMeta = (name: string) =>\n      document.querySelector(`meta[name=\"${name}\"]`)?.getAttribute(\"content\") || undefined;\n\n    baseUrl = baseUrl || getMeta(\"ago-base-url\");\n    widgetId = widgetId || getMeta(\"ago-widget-id\");\n    agent = agent || getMeta(\"ago-agent\") || getMeta(\"ago-agent-id\");\n    permission = permission || getMeta(\"ago-permission\");\n    userEmail = userEmail || getMeta(\"ago-user-email\");\n  }\n\n  // 3. data-ago-* attributes on body or script tags\n  if (typeof document !== \"undefined\") {\n    const sources = [\n      document.body,\n      ...Array.from(document.querySelectorAll(\"script[data-ago-base-url]\")),\n    ].filter(Boolean);\n\n    for (const el of sources) {\n      if (!el) continue;\n      baseUrl = baseUrl || el.getAttribute(\"data-ago-base-url\") || undefined;\n      widgetId = widgetId || el.getAttribute(\"data-ago-widget-id\") || undefined;\n      agent = agent || el.getAttribute(\"data-ago-agent\") || el.getAttribute(\"data-ago-agent-id\") || undefined;\n      permission = permission || el.getAttribute(\"data-ago-permission\") || undefined;\n      userEmail = userEmail || el.getAttribute(\"data-ago-user-email\") || undefined;\n    }\n  }\n\n  // 4. Apply overrides\n  baseUrl = overrides?.baseUrl || baseUrl;\n  widgetId = overrides?.widgetId || widgetId;\n  agent = overrides?.agent || overrides?.defaultAgentId || agent;\n  permission = overrides?.permission || permission;\n  userEmail = overrides?.userEmail || userEmail;\n  userJwt = overrides?.userJwt || userJwt;\n  const debug = overrides?.debug;\n\n  if (!baseUrl) {\n    return null;\n  }\n\n  return {\n    baseUrl,\n    widgetId,\n    agent,\n    permission,\n    userEmail,\n    userJwt,\n    debug,\n  };\n}\n\n/**\n * Create an AgoClient with zero configuration.\n * Auto-detects config from window.AGO, meta tags, and data-ago-* attributes.\n *\n * ```html\n * <!-- In your HTML -->\n * <meta name=\"ago-base-url\" content=\"https://YOUR-DOMAIN.useago.com\">\n *\n * <!-- Or on a script tag -->\n * <script src=\"app.js\" data-ago-base-url=\"https://YOUR-DOMAIN.useago.com\"></script>\n * ```\n *\n * ```ts\n * import { createAgo } from \"@useago/sdk\";\n *\n * // Zero config — picks up from DOM\n * const client = createAgo();\n *\n * // Or with partial overrides\n * const client = createAgo({ debug: true });\n * ```\n *\n * Throws if no base URL can be detected.\n */\nexport function createAgo(overrides?: Partial<AgoConfig>): AgoClient {\n  const config = autoDetectConfig(overrides);\n\n  if (!config) {\n    throw new Error(\n      \"createAgo(): could not detect AGO configuration. \" +\n        \"Set window.AGO, add <meta name=\\\"ago-base-url\\\">, or pass { baseUrl } explicitly.\"\n    );\n  }\n\n  return new AgoClient(config);\n}\n","import type {\n  ClientFunctionDefinition,\n  ClientFunctionHandler,\n} from \"../functions/types\";\n\n/**\n * Attach a handler to a pre-built function definition.\n *\n * Pre-built helpers (`showToast`, `trackEvent`, ...) ship with a no-op or\n * console-logging default handler. Use `withHandler` to wire them up to\n * your actual implementation without mutating the original definition.\n *\n * ```ts\n * import { showToast, withHandler } from \"@useago/sdk\";\n *\n * client.register(\n *   withHandler(showToast, (args) => {\n *     myToast(args.message as string);\n *     return { shown: true };\n *   })\n * );\n * ```\n */\nexport function withHandler<T extends ClientFunctionDefinition>(\n  definition: T,\n  handler: ClientFunctionHandler\n): T {\n  return { ...definition, handler };\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { AgoClient } from "./client/AgoClient";
 export type { AgoConfig, SendMessageOptions, AgoMessage, Conversation, AgoAgent, AgoSource, ToolCallData, ToolCallType, FormSchema, FormField, FunctionSchema, ClientFunction, FunctionDefinition, ClientFunctionInvocation, AgoClientEvents, AgoEventName, AgoEventHandler, MessageStatus, SSEChunkData, } from "./client/types";
 export { AgoError, AgoApiError, AgoNetworkError, AgoStreamError, AgoFunctionError, } from "./client/errors";
+export { ClientContextRegistry } from "./state/ClientContextRegistry";
+export type { ContextEntry, ContextSnapshot, DynamicContextProvider, } from "./state/ClientContextRegistry";
 export { FunctionRegistry } from "./functions/FunctionRegistry";
 export { defineFunction } from "./functions/defineFunction";
 export type { ClientFunctionSchema, ClientFunctionHandler, ClientFunctionDefinition, RegisteredFunction, } from "./functions/types";
@@ -8,5 +10,9 @@ export { createMockClient } from "./testing";
 export type { MockAgoClient, MockAgoClientOptions } from "./testing";
 export { SSEHandler, isStreamNetworkError } from "./streaming/SSEHandler";
 export type { AgoWidgetConfig, AgoWidgetColors } from "./widget/types";
+export { onMessage, onMessageChunk, onMessageStart, onMessageError, onToolCall, onFunctionInvoke, createMessageStream, } from "./streaming/helpers";
+export { createAgo, autoDetectConfig } from "./auto/createAgo";
+export { showToast, showNotification, openUrl, copyToClipboard, setTheme, showConfirmDialog, getUserLocation, scrollToElement, setLocalStorage, getLocalStorage, highlightElement, submitForm, trackEvent, } from "./helpers/functions";
+export { withHandler } from "./helpers/factory";
 export { EventEmitter } from "./utils/eventEmitter";
 export { logger } from "./utils/logger";

package/dist/index.js

@@ -1,20 +1,278 @@
-import { A, a, b, c, d, e, E, F, S, f, i, l } from "./createMockClient-uGlVyjbL.js";
+import { a as ClientContextRegistry, c as AgoApiError, d as AgoNetworkError, f as AgoStreamError, i as isStreamNetworkError, l as AgoError, n as EventEmitter, o as FunctionRegistry, r as SSEHandler, s as logger, t as AgoClient, u as AgoFunctionError } from "./AgoClient-CNT-8sh_.js";
+import { t as createMockClient } from "./createMockClient-U0ae_AYy.js";
+import { a as highlightElement, c as setLocalStorage, d as showNotification, f as showToast, i as getUserLocation, l as setTheme, m as trackEvent, o as openUrl, p as submitForm, r as getLocalStorage, s as scrollToElement, t as copyToClipboard, u as showConfirmDialog } from "./functions-C9F1dnmh.js";
+//#region src/functions/defineFunction.ts
+/**
+* Create a reusable function definition.
+* Returns the same object — this is an identity function for discoverability and type-checking.
+*
+* ```ts
+* // Define once, reuse anywhere
+* export const lookupOrder = defineFunction({
+*   name: "lookupOrder",
+*   description: "Look up an order by ID",
+*   parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+*   handler: async (args) => fetchOrder(args.id as string),
+* });
+*
+* // Register with client
+* client.registerFunction(lookupOrder);
+*
+* // Or use in React
+* useAgoFunction(lookupOrder.name, lookupOrder);
+* ```
+*/
 function defineFunction(definition) {
-  return definition;
-}
-export {
-  A as AgoApiError,
-  a as AgoClient,
-  b as AgoError,
-  c as AgoFunctionError,
-  d as AgoNetworkError,
-  e as AgoStreamError,
-  E as EventEmitter,
-  F as FunctionRegistry,
-  S as SSEHandler,
-  f as createMockClient,
-  defineFunction,
-  i as isStreamNetworkError,
-  l as logger
-};
-//# sourceMappingURL=index.js.map
+	return definition;
+}
+//#endregion
+//#region src/streaming/helpers.ts
+/**
+* Subscribe to complete messages with a simple callback. Returns an unsubscribe function.
+*
+* ```ts
+* const unsub = onMessage(client, (msg) => console.log(msg.content));
+* // later: unsub();
+* ```
+*/
+function onMessage(client, callback) {
+	client.on("message:complete", callback);
+	return () => client.off("message:complete", callback);
+}
+/**
+* Subscribe to streaming text chunks.
+*
+* ```ts
+* onMessageChunk(client, ({ content }) => {
+*   outputEl.textContent += content;
+* });
+* ```
+*/
+function onMessageChunk(client, callback) {
+	client.on("message:chunk", callback);
+	return () => client.off("message:chunk", callback);
+}
+/**
+* Subscribe to message start events.
+*/
+function onMessageStart(client, callback) {
+	client.on("message:start", callback);
+	return () => client.off("message:start", callback);
+}
+/**
+* Subscribe to message errors.
+*/
+function onMessageError(client, callback) {
+	client.on("message:error", callback);
+	return () => client.off("message:error", callback);
+}
+/**
+* Subscribe to tool call events.
+*/
+function onToolCall(client, callback) {
+	client.on("toolCall:received", callback);
+	return () => client.off("toolCall:received", callback);
+}
+/**
+* Subscribe to client function invocations.
+*/
+function onFunctionInvoke(client, callback) {
+	client.on("function:invoke", callback);
+	return () => client.off("function:invoke", callback);
+}
+/**
+* Send a message and iterate over chunks as an async generator.
+* Gives you full control over how you process the stream.
+*
+* ```ts
+* for await (const chunk of createMessageStream(client, "Hello!")) {
+*   console.log(chunk.type, chunk.data);
+* }
+* ```
+*/
+async function* createMessageStream(client, content, options) {
+	const queue = [];
+	let resolve = null;
+	let done = false;
+	const push = (event) => {
+		queue.push(event);
+		resolve?.();
+	};
+	const onStart = (data) => push({
+		type: "start",
+		data
+	});
+	const onChunk = (data) => push({
+		type: "chunk",
+		data
+	});
+	const onComplete = (data) => {
+		push({
+			type: "complete",
+			data
+		});
+		done = true;
+		resolve?.();
+	};
+	const onError = (data) => {
+		push({
+			type: "error",
+			data
+		});
+		done = true;
+		resolve?.();
+	};
+	const onTool = (data) => push({
+		type: "toolCall",
+		data
+	});
+	client.on("message:start", onStart);
+	client.on("message:chunk", onChunk);
+	client.on("message:complete", onComplete);
+	client.on("message:error", onError);
+	client.on("toolCall:received", onTool);
+	client.sendMessage(content, options).catch(() => {
+		done = true;
+		resolve?.();
+	});
+	try {
+		while (!done || queue.length > 0) if (queue.length > 0) yield queue.shift();
+		else {
+			await new Promise((r) => {
+				resolve = r;
+			});
+			resolve = null;
+		}
+	} finally {
+		client.off("message:start", onStart);
+		client.off("message:chunk", onChunk);
+		client.off("message:complete", onComplete);
+		client.off("message:error", onError);
+		client.off("toolCall:received", onTool);
+	}
+}
+//#endregion
+//#region src/auto/createAgo.ts
+/**
+* Auto-detect AGO configuration from the DOM environment.
+*
+* Checks (in order of priority):
+* 1. `window.AGO` global object (widget config)
+* 2. `<meta>` tags: `<meta name="ago-api-key" content="...">`
+* 3. `data-ago-*` attributes on `<body>` or `<script data-ago-api-key="...">`
+* 4. Explicit overrides passed as argument
+*
+* Returns null if no API key can be found.
+*/
+function autoDetectConfig(overrides) {
+	let baseUrl;
+	let widgetId;
+	let agent;
+	let permission;
+	let userEmail;
+	let userJwt;
+	if (typeof window !== "undefined" && window.AGO) {
+		const ago = window.AGO;
+		baseUrl = ago.basepath;
+		widgetId = ago.widgetId;
+		agent = ago.agent || ago.defaultAgent;
+		permission = ago.permission;
+		userEmail = ago.email;
+		userJwt = ago.jwt;
+	}
+	if (typeof document !== "undefined") {
+		const getMeta = (name) => document.querySelector(`meta[name="${name}"]`)?.getAttribute("content") || void 0;
+		baseUrl = baseUrl || getMeta("ago-base-url");
+		widgetId = widgetId || getMeta("ago-widget-id");
+		agent = agent || getMeta("ago-agent") || getMeta("ago-agent-id");
+		permission = permission || getMeta("ago-permission");
+		userEmail = userEmail || getMeta("ago-user-email");
+	}
+	if (typeof document !== "undefined") {
+		const sources = [document.body, ...Array.from(document.querySelectorAll("script[data-ago-base-url]"))].filter(Boolean);
+		for (const el of sources) {
+			if (!el) continue;
+			baseUrl = baseUrl || el.getAttribute("data-ago-base-url") || void 0;
+			widgetId = widgetId || el.getAttribute("data-ago-widget-id") || void 0;
+			agent = agent || el.getAttribute("data-ago-agent") || el.getAttribute("data-ago-agent-id") || void 0;
+			permission = permission || el.getAttribute("data-ago-permission") || void 0;
+			userEmail = userEmail || el.getAttribute("data-ago-user-email") || void 0;
+		}
+	}
+	baseUrl = overrides?.baseUrl || baseUrl;
+	widgetId = overrides?.widgetId || widgetId;
+	agent = overrides?.agent || overrides?.defaultAgentId || agent;
+	permission = overrides?.permission || permission;
+	userEmail = overrides?.userEmail || userEmail;
+	userJwt = overrides?.userJwt || userJwt;
+	const debug = overrides?.debug;
+	if (!baseUrl) return null;
+	return {
+		baseUrl,
+		widgetId,
+		agent,
+		permission,
+		userEmail,
+		userJwt,
+		debug
+	};
+}
+/**
+* Create an AgoClient with zero configuration.
+* Auto-detects config from window.AGO, meta tags, and data-ago-* attributes.
+*
+* ```html
+* <!-- In your HTML -->
+* <meta name="ago-base-url" content="https://YOUR-DOMAIN.useago.com">
+*
+* <!-- Or on a script tag -->
+* <script src="app.js" data-ago-base-url="https://YOUR-DOMAIN.useago.com"><\/script>
+* ```
+*
+* ```ts
+* import { createAgo } from "@useago/sdk";
+*
+* // Zero config — picks up from DOM
+* const client = createAgo();
+*
+* // Or with partial overrides
+* const client = createAgo({ debug: true });
+* ```
+*
+* Throws if no base URL can be detected.
+*/
+function createAgo(overrides) {
+	const config = autoDetectConfig(overrides);
+	if (!config) throw new Error("createAgo(): could not detect AGO configuration. Set window.AGO, add <meta name=\"ago-base-url\">, or pass { baseUrl } explicitly.");
+	return new AgoClient(config);
+}
+//#endregion
+//#region src/helpers/factory.ts
+/**
+* Attach a handler to a pre-built function definition.
+*
+* Pre-built helpers (`showToast`, `trackEvent`, ...) ship with a no-op or
+* console-logging default handler. Use `withHandler` to wire them up to
+* your actual implementation without mutating the original definition.
+*
+* ```ts
+* import { showToast, withHandler } from "@useago/sdk";
+*
+* client.register(
+*   withHandler(showToast, (args) => {
+*     myToast(args.message as string);
+*     return { shown: true };
+*   })
+* );
+* ```
+*/
+function withHandler(definition, handler) {
+	return {
+		...definition,
+		handler
+	};
+}
+//#endregion
+export { AgoApiError, AgoClient, AgoError, AgoFunctionError, AgoNetworkError, AgoStreamError, ClientContextRegistry, EventEmitter, FunctionRegistry, SSEHandler, autoDetectConfig, copyToClipboard, createAgo, createMessageStream, createMockClient, defineFunction, getLocalStorage, getUserLocation, highlightElement, isStreamNetworkError, logger, onFunctionInvoke, onMessage, onMessageChunk, onMessageError, onMessageStart, onToolCall, openUrl, scrollToElement, setLocalStorage, setTheme, showConfirmDialog, showNotification, showToast, submitForm, trackEvent, withHandler };
+
+//# sourceMappingURL=index.js.map