@waniwani/sdk 0.18.0 → 0.19.1

package/dist/chat/express-js/index.d.ts

@@ -68,7 +68,7 @@ interface KbClient {
  * first-class names at runtime (the widget transport passes these through
  * verbatim instead of namespacing them as custom widget events).
  */
-declare const EVENT_TYPES: readonly ["session.started", "page.viewed", "tool.called", "quote.requested", "quote.succeeded", "quote.failed", "link.clicked", "purchase.completed", "widget_render", "user.identified", "price_shown", "prices_compared", "option_selected", "lead_qualified", "converted"];
+declare const EVENT_TYPES: readonly ["session.started", "page.viewed", "tool.called", "link.clicked", "widget_render", "user.identified", "price_shown", "prices_compared", "option_selected", "lead_qualified", "converted"];
 type EventType = (typeof EVENT_TYPES)[number];
 /**
  * Properties for `page.viewed` — emitted once when the chat widget initializes
@@ -97,17 +97,9 @@ interface ToolCalledProperties {
     /** Retrieval traces for kb.search() calls made inside this tool handler. */
     kbSearch?: KbSearchTrace[];
 }
-interface QuoteSucceededProperties {
-    amount?: number;
-    currency?: string;
-}
 interface LinkClickedProperties {
     url?: string;
 }
-interface PurchaseCompletedProperties {
-    amount?: number;
-    currency?: string;
-}
 interface PriceShownProperties {
     amount: number;
     currency: string;
@@ -194,19 +186,9 @@ type TrackEvent = ({
 } & BaseTrackEvent) | ({
     event: "tool.called";
     properties?: ToolCalledProperties;
-} & BaseTrackEvent) | ({
-    event: "quote.requested";
-} & BaseTrackEvent) | ({
-    event: "quote.succeeded";
-    properties?: QuoteSucceededProperties;
-} & BaseTrackEvent) | ({
-    event: "quote.failed";
 } & BaseTrackEvent) | ({
     event: "link.clicked";
     properties?: LinkClickedProperties;
-} & BaseTrackEvent) | ({
-    event: "purchase.completed";
-    properties?: PurchaseCompletedProperties;
 } & BaseTrackEvent) | ({
     event: "user.identified";
 } & BaseTrackEvent) | ({
@@ -235,11 +217,7 @@ interface LegacyTrackEvent extends TrackingContext {
     properties?: Record<string, unknown>;
     toolName?: string;
     toolType?: ToolCalledProperties["type"];
-    quoteAmount?: number;
-    quoteCurrency?: string;
     linkUrl?: string;
-    purchaseAmount?: number;
-    purchaseCurrency?: string;
 }
 /**
  * Public track input accepted by `client.track()`.

package/dist/chat/index.d.ts

@@ -22,7 +22,7 @@ interface KbSearchTrace {
  * first-class names at runtime (the widget transport passes these through
  * verbatim instead of namespacing them as custom widget events).
  */
-declare const EVENT_TYPES: readonly ["session.started", "page.viewed", "tool.called", "quote.requested", "quote.succeeded", "quote.failed", "link.clicked", "purchase.completed", "widget_render", "user.identified", "price_shown", "prices_compared", "option_selected", "lead_qualified", "converted"];
+declare const EVENT_TYPES: readonly ["session.started", "page.viewed", "tool.called", "link.clicked", "widget_render", "user.identified", "price_shown", "prices_compared", "option_selected", "lead_qualified", "converted"];
 type EventType = (typeof EVENT_TYPES)[number];
 /**
  * Properties for `page.viewed` — emitted once when the chat widget initializes
@@ -51,17 +51,9 @@ interface ToolCalledProperties {
     /** Retrieval traces for kb.search() calls made inside this tool handler. */
     kbSearch?: KbSearchTrace[];
 }
-interface QuoteSucceededProperties {
-    amount?: number;
-    currency?: string;
-}
 interface LinkClickedProperties {
     url?: string;
 }
-interface PurchaseCompletedProperties {
-    amount?: number;
-    currency?: string;
-}
 interface PriceShownProperties {
     amount: number;
     currency: string;
@@ -148,19 +140,9 @@ type TrackEvent = ({
 } & BaseTrackEvent) | ({
     event: "tool.called";
     properties?: ToolCalledProperties;
-} & BaseTrackEvent) | ({
-    event: "quote.requested";
-} & BaseTrackEvent) | ({
-    event: "quote.succeeded";
-    properties?: QuoteSucceededProperties;
-} & BaseTrackEvent) | ({
-    event: "quote.failed";
 } & BaseTrackEvent) | ({
     event: "link.clicked";
     properties?: LinkClickedProperties;
-} & BaseTrackEvent) | ({
-    event: "purchase.completed";
-    properties?: PurchaseCompletedProperties;
 } & BaseTrackEvent) | ({
     event: "user.identified";
 } & BaseTrackEvent) | ({
@@ -189,11 +171,7 @@ interface LegacyTrackEvent extends TrackingContext {
     properties?: Record<string, unknown>;
     toolName?: string;
     toolType?: ToolCalledProperties["type"];
-    quoteAmount?: number;
-    quoteCurrency?: string;
     linkUrl?: string;
-    purchaseAmount?: number;
-    purchaseCurrency?: string;
 }
 /**
  * Public track input accepted by `client.track()`.
@@ -336,6 +314,66 @@ type DeepPartial<T> = T extends (...args: never[]) => unknown ? T : T extends ob
 } : T;
 type MessageOverrides = DeepPartial<Messages>;
 
+/**
+ * A visitor id to apply, or a resolver that produces one. The resolver may be
+ * sync (`() => posthog.get_distinct_id()`) or async
+ * (`async () => (await sdk.ready()).id`), for analytics SDKs whose id is only
+ * available after they bootstrap.
+ */
+type VisitorIdInput = string | (() => string | undefined | null | Promise<string | undefined | null>);
+
+/** Surface the widget is mounted on. */
+type WidgetMode = "inline" | "floating";
+interface WidgetEventBase {
+    /** Surface the widget is mounted on. */
+    mode: WidgetMode;
+    /**
+     * Conversation session id, when one exists. Assigned on the first
+     * exchange, so it is `undefined` for events that precede it.
+     */
+    sessionId?: string;
+    /** Epoch milliseconds at emit time. */
+    timestamp: number;
+}
+/**
+ * Per-event discriminant and extra properties. Events in the first branch
+ * carry no `properties` object.
+ */
+type WidgetEventDetail = {
+    name: "chat.ready" | "chat.opened" | "chat.closed" | "message.sent" | "message.received";
+} | {
+    name: "session.started";
+    properties: {
+        sessionId: string;
+    };
+} | {
+    name: "thread.changed";
+    properties: {
+        threadId: string;
+    };
+} | {
+    name: "chat.error";
+    properties: {
+        message: string;
+    };
+} | {
+    name: "suggestion.clicked";
+    properties: {
+        text: string;
+        index: number;
+        /** Which provider supplied the clicked pill: `"channel"` (starter prompts), `"page"` (per-URL starter prompts), `"flow"` (an MCP flow's `interrupt({ suggestions })`), or `"followup"` (generated from the conversation). */
+        origin: SuggestionOrigin;
+    };
+} | {
+    name: "link.clicked";
+    properties: {
+        url: string;
+    };
+};
+/** Payload handed to `onEvent` subscribers. Discriminated on `name`. */
+type WidgetEvent = WidgetEventBase & WidgetEventDetail;
+type WidgetEventName = WidgetEventDetail["name"];
+
 /**
  * Built-in theme presets. `auto` follows the host's `prefers-color-scheme`
  * and switches at runtime without re-rendering.
@@ -438,6 +476,15 @@ interface WelcomeConfig {
     /** Suggestion cards shown in the welcome screen. Disappear after the first message. */
     suggestions?: string[];
 }
+/** Where a suggestion pill came from. */
+/**
+ * Every place a suggestion pill can come from. The single source of truth:
+ * {@link SuggestionOrigin} derives from it, and runtime validation reads it,
+ * so adding an origin is a one-line change.
+ */
+declare const SUGGESTION_ORIGINS: readonly ["channel", "page", "flow", "followup"];
+/** Where a suggestion pill came from. */
+type SuggestionOrigin = (typeof SUGGESTION_ORIGINS)[number];
 interface SuggestionsConfig {
     /**
      * Initial suggestions to show before the user sends their first message.
@@ -445,8 +492,14 @@ interface SuggestionsConfig {
      */
     initial?: string[];
     /**
-     * Enable AI-generated suggestions after each response.
-     * Defaults to `true` when suggestions config is provided.
+     * Which providers may fill the pill row. Omitted, this defaults to
+     * `["channel", "page", "followup"]`: starter prompts and generated
+     * follow-ups render, flow-driven pills stay opt-in.
+     */
+    origins?: SuggestionOrigin[];
+    /**
+     * @deprecated Use `origins`. `true` maps to every origin, `false` to none.
+     * Will be removed in a future minor release.
      */
     dynamic?: boolean;
 }
@@ -494,6 +547,21 @@ interface ChatBaseProps {
     appearance?: ChatAppearance;
     /** Per-slot class name overrides. See {@link ChatClassNames}. */
     classNames?: ChatClassNames;
+    /**
+     * Override the anonymous visitor id the widget generates with one you
+     * already track (a PostHog / Amplitude / Segment distinct id, your own
+     * cookie, etc.). The chat sends it on every request, so Waniwani sessions
+     * and events correlate to the same visitor, and server-side MCP tools and
+     * flows read it back as `context.waniwani.visitorId`.
+     *
+     * A string, or a resolver that returns one — sync
+     * (`() => posthog.get_distinct_id()`) or async
+     * (`async () => (await sdk.ready()).id`), for analytics SDKs whose id is
+     * only ready after they bootstrap. A blank / failed result is ignored, so
+     * the auto-generated, `localStorage`-persisted id is kept. Leave unset to
+     * always use the auto id.
+     */
+    visitorId?: VisitorIdInput;
     /** Additional headers to send with chat API requests */
     headers?: Record<string, string>;
     /** Additional body fields to send with each chat request */
@@ -513,8 +581,11 @@ interface ChatBaseProps {
     /** Callback fired when a response is received */
     onResponseReceived?: () => void;
     /**
-     * Enable AI-generated suggestions after each response.
-     * `true` enables with defaults (3 suggestions), object allows config, `false`/undefined disables.
+     * Suggestion pill configuration. Unset: no suggestions. An object sets
+     * starter prompts (`initial`) and which origins may fill the per-turn
+     * pill row (`origins`); `origins: ["flow"]` (or any list including
+     * `"flow"`) opts into flow-driven pills. `true` enables every origin with
+     * defaults; `false` hides the pill row entirely.
      */
     suggestions?: boolean | SuggestionsConfig;
     /**
@@ -852,6 +923,15 @@ interface WaniwaniChatOverrides {
     placeholder?: string;
     /** Initial suggestion chips. */
     suggestions?: string[];
+    /**
+     * Which providers may fill the per-turn pill row. Defaults to
+     * `["channel", "page", "followup"]` when unset: starter prompts and
+     * generated follow-ups render, flow-driven pills stay opt-in — include
+     * `"flow"` to render the pills a flow drives via
+     * `interrupt({ suggestions })`. Starter prompts (`suggestions`) are
+     * unaffected by this field and show either way.
+     */
+    suggestionOrigins?: SuggestionOrigin[];
     /** Persist conversations across reloads in IndexedDB. */
     enableThreadHistory?: boolean;
     /**
@@ -945,6 +1025,22 @@ interface WaniwaniChatProps {
     token: string;
     /** Agent channel ID — routes the conversation to the right agent. */
     channelId?: string;
+    /**
+     * Override the anonymous visitor id the widget generates with one you
+     * already track (a PostHog / Amplitude / Segment distinct id, your own
+     * cookie, etc.). The chat sends it on every request, so Waniwani sessions
+     * and events correlate to the same visitor, and server-side MCP tools and
+     * flows read it back as `context.waniwani.visitorId`.
+     *
+     * A string, or a resolver that returns one — sync
+     * (`() => posthog.get_distinct_id()`) or async
+     * (`async () => (await sdk.ready()).id`), for analytics SDKs whose id is only
+     * ready after they bootstrap. Read live on each request, so updating it
+     * applies to the next message. A blank / failed result is ignored, keeping
+     * the auto-generated, `localStorage`-persisted id. Leave unset to always use
+     * the auto id.
+     */
+    visitorId?: VisitorIdInput;
     /** Additional class names applied to the root element. */
     className?: string;
     /**
@@ -954,6 +1050,16 @@ interface WaniwaniChatProps {
      * can't be serialized to the dashboard).
      */
     overrides?: WaniwaniChatOverrides;
+    /**
+     * Callback fired on chat lifecycle events (`chat.ready`, `message.sent`,
+     * `message.received`, `session.started`, `thread.changed`, `chat.error`,
+     * `suggestion.clicked`, `link.clicked`; `chat.opened`/`chat.closed` are
+     * floating-embed-only and never fire here). Message events never include
+     * the message text. Use it to mirror widget activity into the host page's
+     * analytics. Exceptions thrown by the callback are swallowed and never
+     * break the chat.
+     */
+    onEvent?: (event: WidgetEvent) => void;
 }
 declare const WaniwaniChat: react.ForwardRefExoticComponent<WaniwaniChatProps & react.RefAttributes<ChatHandle>>;
 
@@ -969,4 +1075,4 @@ declare function mergeTheme(userTheme?: ChatTheme): Required<ChatTheme>;
  */
 declare function themeToCSSProperties(theme: ChatTheme): Record<string, string>;
 
-export { type ChatAppearance, type ChatBaseProps, ChatCard, type ChatCardProps, ChatEmbed, type ChatEmbedMcpConfig, type ChatEmbedProps, type ChatHandle, type ChatTheme, DARK_THEME, DEFAULT_THEME, type McpAppDisplayMode, McpAppFrame, type McpAppFrameProps, type ShowToolCalls, type SuggestionsConfig, type ThemePreset, WaniwaniChat, type WaniwaniChatOverrides, type WaniwaniChatProps, type WelcomeConfig, mergeTheme, themeToCSSProperties };
+export { type ChatAppearance, type ChatBaseProps, ChatCard, type ChatCardProps, ChatEmbed, type ChatEmbedMcpConfig, type ChatEmbedProps, type ChatHandle, type ChatTheme, DARK_THEME, DEFAULT_THEME, type McpAppDisplayMode, McpAppFrame, type McpAppFrameProps, type ShowToolCalls, type SuggestionsConfig, type ThemePreset, WaniwaniChat, type WaniwaniChatOverrides, type WaniwaniChatProps, type WelcomeConfig, type WidgetEvent, type WidgetEventName, type WidgetMode, mergeTheme, themeToCSSProperties };