@useago/sdk 0.1.6 → 0.1.7

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","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 defaultAgentId: string | undefined;\n  let userEmail: string | undefined;\n  let userJwt: string | undefined;\n  let debug: boolean | 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    defaultAgentId = ago.defaultAgent 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    defaultAgentId = defaultAgentId || getMeta(\"ago-agent-id\");\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      defaultAgentId = defaultAgentId || el.getAttribute(\"data-ago-agent-id\") || 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  defaultAgentId = overrides?.defaultAgentId || defaultAgentId;\n  userEmail = overrides?.userEmail || userEmail;\n  userJwt = overrides?.userJwt || userJwt;\n  debug = overrides?.debug ?? debug;\n\n  if (!baseUrl) {\n    return null;\n  }\n\n  return {\n    baseUrl,\n    widgetId,\n    defaultAgentId,\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"],"names":["AgoClient"],"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,188 @@
-import { A, a, b, c, d, e, E, F, S, f, i, l } from "./createMockClient-uGlVyjbL.js";
+import { A as AgoClient } from "./AgoClient-D-c91tx5.js";
+import { a, b, c, d, e, C, E, F, S, i, l } from "./AgoClient-D-c91tx5.js";
+import { c as c2 } from "./createMockClient-B1DcBiIK.js";
+import { copyToClipboard, getLocalStorage, getUserLocation, highlightElement, openUrl, scrollToElement, setLocalStorage, setTheme, showConfirmDialog, showNotification, showToast, submitForm, trackEvent } from "./functions-C-wLEc8b.js";
 function defineFunction(definition) {
   return definition;
 }
+function onMessage(client, callback) {
+  client.on("message:complete", callback);
+  return () => client.off("message:complete", callback);
+}
+function onMessageChunk(client, callback) {
+  client.on("message:chunk", callback);
+  return () => client.off("message:chunk", callback);
+}
+function onMessageStart(client, callback) {
+  client.on("message:start", callback);
+  return () => client.off("message:start", callback);
+}
+function onMessageError(client, callback) {
+  client.on("message:error", callback);
+  return () => client.off("message:error", callback);
+}
+function onToolCall(client, callback) {
+  client.on("toolCall:received", callback);
+  return () => client.off("toolCall:received", callback);
+}
+function onFunctionInvoke(client, callback) {
+  client.on("function:invoke", callback);
+  return () => client.off("function:invoke", callback);
+}
+async function* createMessageStream(client, content, options) {
+  const queue = [];
+  let resolve = null;
+  let done = false;
+  const push = (event) => {
+    queue.push(event);
+    resolve == null ? void 0 : 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 == null ? void 0 : resolve();
+  };
+  const onError = (data) => {
+    push({ type: "error", data });
+    done = true;
+    resolve == null ? void 0 : 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 == null ? void 0 : 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);
+  }
+}
+function autoDetectConfig(overrides) {
+  let baseUrl;
+  let widgetId;
+  let defaultAgentId;
+  let userEmail;
+  let userJwt;
+  let debug;
+  if (typeof window !== "undefined" && window.AGO) {
+    const ago = window.AGO;
+    baseUrl = ago.basepath;
+    widgetId = ago.widgetId;
+    defaultAgentId = ago.defaultAgent;
+    userEmail = ago.email;
+    userJwt = ago.jwt;
+  }
+  if (typeof document !== "undefined") {
+    const getMeta = (name) => {
+      var _a;
+      return ((_a = document.querySelector(`meta[name="${name}"]`)) == null ? void 0 : _a.getAttribute("content")) || void 0;
+    };
+    baseUrl = baseUrl || getMeta("ago-base-url");
+    widgetId = widgetId || getMeta("ago-widget-id");
+    defaultAgentId = defaultAgentId || getMeta("ago-agent-id");
+    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;
+      defaultAgentId = defaultAgentId || el.getAttribute("data-ago-agent-id") || void 0;
+      userEmail = userEmail || el.getAttribute("data-ago-user-email") || void 0;
+    }
+  }
+  baseUrl = (overrides == null ? void 0 : overrides.baseUrl) || baseUrl;
+  widgetId = (overrides == null ? void 0 : overrides.widgetId) || widgetId;
+  defaultAgentId = (overrides == null ? void 0 : overrides.defaultAgentId) || defaultAgentId;
+  userEmail = (overrides == null ? void 0 : overrides.userEmail) || userEmail;
+  userJwt = (overrides == null ? void 0 : overrides.userJwt) || userJwt;
+  debug = (overrides == null ? void 0 : overrides.debug) ?? debug;
+  if (!baseUrl) {
+    return null;
+  }
+  return {
+    baseUrl,
+    widgetId,
+    defaultAgentId,
+    userEmail,
+    userJwt,
+    debug
+  };
+}
+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);
+}
+function withHandler(definition, handler) {
+  return { ...definition, handler };
+}
 export {
-  A as AgoApiError,
-  a as AgoClient,
+  a as AgoApiError,
+  AgoClient,
   b as AgoError,
   c as AgoFunctionError,
   d as AgoNetworkError,
   e as AgoStreamError,
+  C as ClientContextRegistry,
   E as EventEmitter,
   F as FunctionRegistry,
   S as SSEHandler,
-  f as createMockClient,
+  autoDetectConfig,
+  copyToClipboard,
+  createAgo,
+  createMessageStream,
+  c2 as createMockClient,
   defineFunction,
+  getLocalStorage,
+  getUserLocation,
+  highlightElement,
   i as isStreamNetworkError,
-  l as logger
+  l as logger,
+  onFunctionInvoke,
+  onMessage,
+  onMessageChunk,
+  onMessageError,
+  onMessageStart,
+  onToolCall,
+  openUrl,
+  scrollToElement,
+  setLocalStorage,
+  setTheme,
+  showConfirmDialog,
+  showNotification,
+  showToast,
+  submitForm,
+  trackEvent,
+  withHandler
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","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.js","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 defaultAgentId: string | undefined;\n  let userEmail: string | undefined;\n  let userJwt: string | undefined;\n  let debug: boolean | 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    defaultAgentId = ago.defaultAgent 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    defaultAgentId = defaultAgentId || getMeta(\"ago-agent-id\");\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      defaultAgentId = defaultAgentId || el.getAttribute(\"data-ago-agent-id\") || 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  defaultAgentId = overrides?.defaultAgentId || defaultAgentId;\n  userEmail = overrides?.userEmail || userEmail;\n  userJwt = overrides?.userJwt || userJwt;\n  debug = overrides?.debug ?? debug;\n\n  if (!baseUrl) {\n    return null;\n  }\n\n  return {\n    baseUrl,\n    widgetId,\n    defaultAgentId,\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"],"names":[],"mappings":"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"}

package/dist/react/context/AgoContext.d.ts

@@ -1,9 +1,22 @@
 import React from "react";
 import type { AgoClient } from "../../client/AgoClient";
 import type { AgoConfig } from "../../client/types";
+import type { ClientFunctionDefinition, ClientFunctionHandler } from "../../functions/types";
+/**
+ * Top-level declarative configuration for the `AgoProvider`.
+ *
+ * - `tools` — full function definitions to expose to the AI app-wide
+ * - `helpers` — map of pre-built helper name → handler override (or `true` for default)
+ * - `pageContext` — `"auto"` enables automatic URL/title capture
+ */
+export interface AgoDeclarativeConfig {
+    tools?: ClientFunctionDefinition[];
+    helpers?: Record<string, ClientFunctionHandler | true>;
+    pageContext?: "auto" | "manual";
+}
 export type AgoProviderProps = {
     children: React.ReactNode;
-} & (({
+} & AgoDeclarativeConfig & (({
     client: AgoClient;
 } & Partial<Record<keyof AgoConfig, never>>) | ({
     client?: never;
@@ -12,12 +25,25 @@ export type AgoProviderProps = {
  * Provides an AgoClient to all descendant components via React context.
  *
  * ```tsx
- * // Create client from config
- * <AgoProvider apiKey="..." widgetId="...">
+ * // Minimal setup
+ * <AgoProvider baseUrl="https://YOUR-DOMAIN.useago.com">
+ *   <App />
+ * </AgoProvider>
+ *
+ * // Declarative config — tools, helpers, page context
+ * <AgoProvider
+ *   baseUrl="https://YOUR-DOMAIN.useago.com"
+ *   tools={[lookupOrder, cancelOrder]}
+ *   helpers={{
+ *     showToast: (args) => toast(args.message as string),
+ *     copyToClipboard: true, // use default handler
+ *   }}
+ *   pageContext="auto"
+ * >
  *   <App />
  * </AgoProvider>
  *
- * // Or pass a pre-built client (useful for testing)
+ * // With a pre-built client (useful for testing)
  * <AgoProvider client={myClient}>
  *   <App />
  * </AgoProvider>

package/dist/react/context/index.d.ts

@@ -1,2 +1,2 @@
 export { AgoProvider, useAgoClient, useOptionalAgoClient } from "./AgoContext";
-export type { AgoProviderProps } from "./AgoContext";
+export type { AgoProviderProps, AgoDeclarativeConfig } from "./AgoContext";

package/dist/react/hooks/index.d.ts

@@ -4,3 +4,4 @@ export { useMessages } from "./useMessages";
 export type { UseMessagesOptions, UseMessagesResult } from "./useMessages";
 export { useConversation } from "./useConversation";
 export type { UseConversationOptions, UseConversationResult } from "./useConversation";
+export { useAgoContext } from "./useAgoContext";

package/dist/react/hooks/useAgoContext.d.ts

@@ -0,0 +1,40 @@
+import type { ContextEntry, DynamicContextProvider } from "../../state/ClientContextRegistry";
+/**
+ * Declaratively expose a piece of context to the AI agent with every message.
+ *
+ * Accepts either:
+ * - An **object** — sent as-is on every message (re-registered when it changes).
+ *   Use for data that already lives in React state.
+ * - A **function** — called lazily at each message send, so the AI always gets
+ *   the freshest value. Use for data outside React state (global stores, refs,
+ *   computed values).
+ *
+ * A unique key is auto-generated per component instance via `useId()`. Pass an
+ * explicit key as second argument to share context across components or
+ * reference it from elsewhere.
+ *
+ * ```tsx
+ * // Static object — captured at render time
+ * function OrderPage({ order }) {
+ *   useAgoContext({
+ *     name: "Order detail",
+ *     description: "The user is viewing a specific order",
+ *     data: { orderId: order.id, status: order.status },
+ *   });
+ * }
+ *
+ * // Dynamic function — evaluated at each sendMessage
+ * function App() {
+ *   const storeRef = useRef(reduxStore);
+ *   useAgoContext(() => {
+ *     const state = storeRef.current.getState();
+ *     return { name: "App shell", data: { userId: state.auth.userId } };
+ *   });
+ * }
+ *
+ * // With an explicit key
+ * useAgoContext({ name: "Sidebar filter", data: { filter } }, "sidebar-filter");
+ * ```
+ */
+export declare function useAgoContext(entry: ContextEntry, key?: string): void;
+export declare function useAgoContext(provider: DynamicContextProvider, key?: string): void;

package/dist/react/hooks/useAgoFunction.d.ts

@@ -1,4 +1,4 @@
-import type { ClientFunctionHandler } from "../../functions/types";
+import type { ClientFunctionDefinition, ClientFunctionHandler } from "../../functions/types";
 export interface UseAgoFunctionOptions {
     description: string;
     parameters: {
@@ -17,14 +17,26 @@ export interface UseAgoFunctionOptions {
  * Declaratively register a client-side function with the AGO agent.
  * Automatically unregisters on unmount and re-registers when deps change.
  *
+ * Accepts either a full definition object (preferred) or classic (name, options) args.
+ *
  * ```tsx
- * useAgoFunction("showToast", {
+ * // Preferred — pass the whole definition
+ * useAgoFunction({
+ *   name: "showToast",
  *   description: "Show a notification to the user",
  *   parameters: { type: "object", properties: { message: { type: "string" } } },
  *   handler: async (args) => { toast(args.message); return { shown: true }; },
  * });
+ *
+ * // Or reuse a pre-defined function
+ * const lookupOrder = defineFunction({ name: "lookupOrder", ... });
+ * useAgoFunction(lookupOrder);
+ *
+ * // Classic form
+ * useAgoFunction("showToast", { description: "...", parameters: {...}, handler: async (args) => ... });
  * ```
  */
+export declare function useAgoFunction(definition: ClientFunctionDefinition): void;
 export declare function useAgoFunction(name: string, options: UseAgoFunctionOptions): void;
 export interface AgoRoute {
     name: string;

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
 export { AgoProvider, useAgoClient, useOptionalAgoClient } from "./context";
-export type { AgoProviderProps } from "./context";
+export type { AgoProviderProps, AgoDeclarativeConfig } from "./context/AgoContext";
 export { ChatWidget } from "./components/ChatWidget";
 export type { ChatWidgetProps } from "./components/ChatWidget";
 export { Message } from "./components/Message";
@@ -16,5 +16,6 @@ export { useChat } from "./hooks/useChat";
 export type { UseChatOptions, UseChatResult } from "./hooks/useChat";
 export { useAgoFunction, useAgoNavigation } from "./hooks/useAgoFunction";
 export type { UseAgoFunctionOptions, AgoRoute } from "./hooks/useAgoFunction";
+export { useAgoContext } from "./hooks/useAgoContext";
 export { createMockClient } from "./testing";
 export type { AgoConfig, AgoMessage, Conversation, AgoAgent, AgoSource, ToolCallData, } from "../client/types";

package/dist/react.cjs

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const jsxRuntime = require("react/jsx-runtime");
 const react = require("react");
-const createMockClient = require("./createMockClient-BZKh_1em.cjs");
+const AgoClient = require("./AgoClient-BDO4avLq.cjs");
+const createMockClient = require("./createMockClient-BqNSJUu4.cjs");
 function useAgo(config) {
   const [isReady, setIsReady] = react.useState(false);
   const clientRef = react.useRef(null);
@@ -10,10 +11,10 @@ function useAgo(config) {
     if (clientRef.current) {
       clientRef.current.destroy();
     }
-    const newClient = new createMockClient.AgoClient(config);
+    const newClient = new AgoClient.AgoClient(config);
     clientRef.current = newClient;
     return newClient;
-  }, [config.apiKey, config.widgetId, config.baseUrl]);
+  }, [config.baseUrl, config.widgetId]);
   react.useEffect(() => {
     setIsReady(true);
     return () => {
@@ -41,19 +42,59 @@ const AgoContext = react.createContext(null);
 const AgoProvider = ({
   children,
   client: externalClient,
+  tools,
+  helpers,
+  pageContext,
   ...config
 }) => {
   const { client: internalClient } = useAgo(
-    externalClient ? { apiKey: "", widgetId: "" } : config
+    externalClient ? { baseUrl: "" } : config
   );
   const client = externalClient || internalClient;
+  react.useEffect(() => {
+    if (!tools || tools.length === 0) return;
+    for (const tool of tools) {
+      client.register(tool);
+    }
+    return () => {
+      for (const tool of tools) {
+        client.unregisterFunction(tool.name);
+      }
+    };
+  }, [client, tools]);
+  react.useEffect(() => {
+    if (!helpers) return;
+    const registered = [];
+    Promise.resolve().then(() => require("./functions-B0Z0rNQW.cjs")).then((mod) => {
+      for (const [name2, handlerOrTrue] of Object.entries(helpers)) {
+        const helper = mod[name2];
+        if (!helper) {
+          console.warn(`[AGO] Unknown helper: "${name2}"`);
+          continue;
+        }
+        const definition2 = handlerOrTrue === true ? helper : { ...helper, handler: handlerOrTrue };
+        client.register(definition2);
+        registered.push(definition2.name);
+      }
+    });
+    return () => {
+      for (const name2 of registered) {
+        client.unregisterFunction(name2);
+      }
+    };
+  }, [client, helpers]);
+  react.useEffect(() => {
+    if (pageContext === "auto") {
+      client.enableAutoPageContext();
+    }
+  }, [client, pageContext]);
   return /* @__PURE__ */ jsxRuntime.jsx(AgoContext.Provider, { value: client, children });
 };
 function useAgoClient() {
   const client = react.useContext(AgoContext);
   if (!client) {
     throw new Error(
-      'useAgoClient must be used within an <AgoProvider>. Wrap your component tree with <AgoProvider apiKey="..." widgetId="...">.'
+      'useAgoClient must be used within an <AgoProvider>. Wrap your component tree with <AgoProvider baseUrl="...">.'
     );
   }
   return client;
@@ -10540,20 +10581,21 @@ function useChat(options = {}) {
     refreshConversations: conversationResult.refreshConversations
   };
 }
-function useAgoFunction(name2, options) {
+function useAgoFunction(nameOrDef, options) {
   const client = useAgoClient();
-  const handlerRef = react.useRef(options.handler);
-  handlerRef.current = options.handler;
+  const { name: name2, description, parameters, handler } = typeof nameOrDef === "string" ? { name: nameOrDef, ...options } : nameOrDef;
+  const handlerRef = react.useRef(handler);
+  handlerRef.current = handler;
   react.useEffect(() => {
     const stableHandler = (args) => handlerRef.current(args);
     client.registerFunction(name2, stableHandler, {
-      description: options.description,
-      parameters: options.parameters
+      description,
+      parameters
     });
     return () => {
       client.unregisterFunction(name2);
     };
-  }, [client, name2, options.description, options.parameters]);
+  }, [client, name2, description, parameters]);
 }
 function useAgoNavigation(navigate, routes) {
   const client = useAgoClient();
@@ -10569,6 +10611,28 @@ function useAgoNavigation(navigate, routes) {
     };
   }, [client, routes]);
 }
+function useAgoContext(entryOrProvider, key) {
+  const client = useAgoClient();
+  const autoKey = react.useId();
+  const effectiveKey = key ?? autoKey;
+  const providerRef = react.useRef(entryOrProvider);
+  providerRef.current = entryOrProvider;
+  const isDynamic = typeof entryOrProvider === "function";
+  const serialized = isDynamic ? "" : JSON.stringify(entryOrProvider);
+  react.useEffect(() => {
+    if (typeof providerRef.current === "function") {
+      const stableProvider = () => providerRef.current();
+      client.addDynamicContext(effectiveKey, stableProvider);
+      return () => {
+        client.removeDynamicContext(effectiveKey);
+      };
+    }
+    client.setContext(effectiveKey, providerRef.current);
+    return () => {
+      client.removeContext(effectiveKey);
+    };
+  }, [client, effectiveKey, isDynamic, serialized]);
+}
 exports.createMockClient = createMockClient.createMockClient;
 exports.AgoProvider = AgoProvider;
 exports.ChatInput = ChatInput;
@@ -10576,6 +10640,7 @@ exports.ChatWidget = ChatWidget;
 exports.Message = Message;
 exports.useAgo = useAgo;
 exports.useAgoClient = useAgoClient;
+exports.useAgoContext = useAgoContext;
 exports.useAgoFunction = useAgoFunction;
 exports.useAgoNavigation = useAgoNavigation;
 exports.useChat = useChat;