@useago/sdk 0.1.6 → 0.2.0

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","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/react/components/ChatWidget.d.ts

@@ -17,6 +17,8 @@ export interface ChatWidgetProps {
     height?: string | number;
     /** URL of a logo to display in the header */
     logoUrl?: string;
+    /** Show the agent name above assistant messages. Defaults to `true`. */
+    showAgentName?: boolean;
     /** Additional CSS class */
     className?: string;
     /** Callback when a message is sent */

package/dist/react/components/Markdown.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+export interface MarkdownProps {
+    /** Raw markdown string to render. */
+    content: string;
+}
+/**
+ * Renders markdown content with GitHub-flavored markdown support
+ * (tables, task lists, strikethrough, autolinks) and inline-styled
+ * element renderers. Used by {@link Message} but exported so consumers
+ * building a custom chat UI can render assistant content the same way.
+ */
+export declare const Markdown: React.FC<MarkdownProps>;

package/dist/react/components/Message.d.ts

@@ -3,5 +3,7 @@ import type { AgoMessage } from "../../client/types";
 export interface MessageProps {
     message: AgoMessage;
     className?: string;
+    /** Show the agent name above assistant messages. Defaults to `true`. */
+    showAgentName?: boolean;
 }
 export declare const Message: React.FC<MessageProps>;

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

@@ -2,5 +2,7 @@ export { ChatWidget } from "./ChatWidget";
 export type { ChatWidgetProps } from "./ChatWidget";
 export { Message } from "./Message";
 export type { MessageProps } from "./Message";
+export { Markdown } from "./Markdown";
+export type { MarkdownProps } from "./Markdown";
 export { ChatInput } from "./ChatInput";
 export type { ChatInputProps } from "./ChatInput";

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,9 +1,11 @@
 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";
 export type { MessageProps } from "./components/Message";
+export { Markdown } from "./components/Markdown";
+export type { MarkdownProps } from "./components/Markdown";
 export { ChatInput } from "./components/ChatInput";
 export type { ChatInputProps } from "./components/ChatInput";
 export { useAgo } from "./hooks/useAgo";
@@ -16,5 +18,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";