@useago/sdk 0.4.4 → 0.4.6

package/dist/widget.d.cts

@@ -516,11 +516,14 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
 /**
- * JSON-schema shape of a form's fields — identical to a client function's
- * `parameters`, so one schema feeds the store, the update function, and the
- * dynamic context with no second type.
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
  */
-declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+declare interface FormCollectorSchema {
+    type: "object";
+    properties: Record<string, FormFieldSchema>;
+    required?: string[];
+}
 
 declare interface FormField {
     type: "string" | "number" | "boolean" | "array";
@@ -530,6 +533,43 @@ declare interface FormField {
     default?: unknown;
 }
 
+/**
+ * A field's conditional-requiredness rule. The field becomes required exactly
+ * when the controlling `property` matches `value` against the answers collected
+ * so far:
+ * - a single `value`, no `op` — equality (compared as strings);
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
+ * - an array `value`, no `op` — "one of": matches when the property equals any
+ *   listed value.
+ *
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
+ */
+declare interface FormFieldCondition {
+    /** The controlling field whose value the rule tests. */
+    property: string;
+    /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
+    op?: ">=" | "<=" | ">" | "<";
+    /**
+     * The value(s) to test the controlling field against. A single value is an
+     * equality (or, with `op`, a numeric comparison); an array is an "is one of"
+     * membership test, e.g. `value: ["1", "2", "3"]`.
+     */
+    value: string | number | Array<string | number>;
+}
+
+/** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
+declare interface FormFieldSchema {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /**
+     * Makes the field required only while this condition holds. Drives the dynamic
+     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     */
+    requiredWhen?: FormFieldCondition;
+}
+
 /**
  * Form schema for tool calls requiring user input
  */
@@ -546,8 +586,9 @@ declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCEL
  * Vue, or Angular required. Mirrors the React `<ChatWidget>`: it streams replies,
  * renders clickable suggested replies, and installs conversational form collectors.
  *
- * Message content is rendered as plain text (no markdown) to stay dependency-free;
- * use the React `<Message>` component if you need GitHub-flavored markdown.
+ * Message content is rendered as GitHub-flavored markdown by a tiny built-in
+ * parser (no dependencies); all message text is HTML-escaped first (see
+ * {@link renderMarkdown}).
  *
  * ```ts
  * import { mountChatWidget } from "@useago/sdk/widget";
@@ -638,6 +679,34 @@ export declare interface MountChatWidgetOptions {
     }) => void;
 }
 
+/**
+ * Tiny, dependency-free markdown → DOM renderer for the vanilla chat widget.
+ *
+ * The React widget renders GitHub-flavored markdown via `react-markdown` +
+ * `remark-gfm`; bundling those into the framework-agnostic widget would defeat
+ * its "no dependencies" promise, so this is a hand-rolled subset that mirrors
+ * the visible styling of `react/components/Markdown.tsx`.
+ *
+ * Supported: paragraphs (single newline → `<br>`), ATX headings, **bold**,
+ * *italic*, ~~strikethrough~~, `inline code`, fenced code blocks, links,
+ * images, ordered/unordered (and nested) lists, blockquotes, horizontal rules,
+ * and GFM tables.
+ *
+ * ## Security
+ *
+ * The widget is embedded into third-party pages, so the agent's message content
+ * is untrusted. Every span of message text is HTML-escaped before it reaches the
+ * DOM; only a fixed set of safe tags is ever emitted, and `href`/`src` URLs are
+ * scheme-validated (see {@link safeUrl}) so `javascript:`/`data:` payloads can't
+ * slip through. Callers should append the returned fragment — never feed raw
+ * message content to `innerHTML` directly.
+ */
+/**
+ * Parse a markdown string into a {@link DocumentFragment} of safely-built block
+ * elements. Append it to the message bubble; do not stringify it back to HTML.
+ */
+export declare function renderMarkdown(source: string): DocumentFragment;
+
 /**
  * Options for sending a message
  */

package/dist/widget.d.ts

@@ -516,11 +516,14 @@ export declare interface CreateFormCollectorOptions<V = Record<string, unknown>>
 declare type DynamicContextProvider = () => ContextEntry | null | undefined;
 
 /**
- * JSON-schema shape of a form's fields — identical to a client function's
- * `parameters`, so one schema feeds the store, the update function, and the
- * dynamic context with no second type.
+ * Shape of a form's fields. Mirrors a client function's `parameters` (so the same
+ * object feeds the store, the update function, and the dynamic context). Additionally allows the SDK-only per-field `requiredWhen`, which {@link toWireParameters} removes before the schema reaches the LLM.
  */
-declare type FormCollectorSchema = ClientFunctionSchema["parameters"];
+declare interface FormCollectorSchema {
+    type: "object";
+    properties: Record<string, FormFieldSchema>;
+    required?: string[];
+}
 
 declare interface FormField {
     type: "string" | "number" | "boolean" | "array";
@@ -530,6 +533,43 @@ declare interface FormField {
     default?: unknown;
 }
 
+/**
+ * A field's conditional-requiredness rule. The field becomes required exactly
+ * when the controlling `property` matches `value` against the answers collected
+ * so far:
+ * - a single `value`, no `op` — equality (compared as strings);
+ * - a single `value` with `op` — numeric comparison (both sides coerced to numbers);
+ * - an array `value`, no `op` — "one of": matches when the property equals any
+ *   listed value.
+ *
+ * SDK-only — it is stripped from the schema before it reaches the LLM tool
+ */
+declare interface FormFieldCondition {
+    /** The controlling field whose value the rule tests. */
+    property: string;
+    /** Comparison operator; omitted means equality. Ignored when `value` is an array. */
+    op?: ">=" | "<=" | ">" | "<";
+    /**
+     * The value(s) to test the controlling field against. A single value is an
+     * equality (or, with `op`, a numeric comparison); an array is an "is one of"
+     * membership test, e.g. `value: ["1", "2", "3"]`.
+     */
+    value: string | number | Array<string | number>;
+}
+
+/** A single field's schema: the wire-legal keys plus the SDK-only `requiredWhen`. */
+declare interface FormFieldSchema {
+    type: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+    /**
+     * Makes the field required only while this condition holds. Drives the dynamic
+     * `missing` list; stripped before the LLM tool — see {@link toWireParameters}.
+     */
+    requiredWhen?: FormFieldCondition;
+}
+
 /**
  * Form schema for tool calls requiring user input
  */
@@ -546,8 +586,9 @@ declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCEL
  * Vue, or Angular required. Mirrors the React `<ChatWidget>`: it streams replies,
  * renders clickable suggested replies, and installs conversational form collectors.
  *
- * Message content is rendered as plain text (no markdown) to stay dependency-free;
- * use the React `<Message>` component if you need GitHub-flavored markdown.
+ * Message content is rendered as GitHub-flavored markdown by a tiny built-in
+ * parser (no dependencies); all message text is HTML-escaped first (see
+ * {@link renderMarkdown}).
  *
  * ```ts
  * import { mountChatWidget } from "@useago/sdk/widget";
@@ -638,6 +679,34 @@ export declare interface MountChatWidgetOptions {
     }) => void;
 }
 
+/**
+ * Tiny, dependency-free markdown → DOM renderer for the vanilla chat widget.
+ *
+ * The React widget renders GitHub-flavored markdown via `react-markdown` +
+ * `remark-gfm`; bundling those into the framework-agnostic widget would defeat
+ * its "no dependencies" promise, so this is a hand-rolled subset that mirrors
+ * the visible styling of `react/components/Markdown.tsx`.
+ *
+ * Supported: paragraphs (single newline → `<br>`), ATX headings, **bold**,
+ * *italic*, ~~strikethrough~~, `inline code`, fenced code blocks, links,
+ * images, ordered/unordered (and nested) lists, blockquotes, horizontal rules,
+ * and GFM tables.
+ *
+ * ## Security
+ *
+ * The widget is embedded into third-party pages, so the agent's message content
+ * is untrusted. Every span of message text is HTML-escaped before it reaches the
+ * DOM; only a fixed set of safe tags is ever emitted, and `href`/`src` URLs are
+ * scheme-validated (see {@link safeUrl}) so `javascript:`/`data:` payloads can't
+ * slip through. Callers should append the returned fragment — never feed raw
+ * message content to `innerHTML` directly.
+ */
+/**
+ * Parse a markdown string into a {@link DocumentFragment} of safely-built block
+ * elements. Append it to the message bubble; do not stringify it back to HTML.
+ */
+export declare function renderMarkdown(source: string): DocumentFragment;
+
 /**
  * Options for sending a message
  */