@waniwani/sdk 0.15.2 → 0.17.0

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

@@ -62,7 +62,14 @@ interface KbClient {
     sources(): Promise<KbSource[]>;
 }
 
-type EventType = "session.started" | "page.viewed" | "tool.called" | "quote.requested" | "quote.succeeded" | "quote.failed" | "link.clicked" | "purchase.completed" | "widget_render" | "widget_click" | "widget_link_click" | "widget_error" | "widget_scroll" | "widget_form_field" | "widget_form_submit" | "user.identified" | "price_shown" | "prices_compared" | "option_selected" | "lead_qualified" | "converted";
+/**
+ * Every event name in the typed taxonomy, as a runtime list. Single source of
+ * truth for {@link EventType} and for surfaces that need to recognize
+ * 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"];
+type EventType = (typeof EVENT_TYPES)[number];
 /**
  * Properties for `page.viewed` — emitted once when the chat widget initializes
  * on a host page (the top of the funnel). Attributed to the anonymous
@@ -160,6 +167,13 @@ interface TrackingContext {
     requestId?: string;
     correlationId?: string;
     externalUserId?: string;
+    /**
+     * Anonymous visitor id (the analytics "device id"). Counts as identity on
+     * its own: the ingest API accepts `sessionId`, `externalUserId`, or
+     * `visitorId`. The chat widget uses it for pre-session events like
+     * `page.viewed`.
+     */
+    visitorId?: string;
     /** Optional explicit envelope fields. */
     eventId?: string;
     timestamp?: string | Date;
@@ -195,6 +209,8 @@ type TrackEvent = ({
     properties?: PurchaseCompletedProperties;
 } & BaseTrackEvent) | ({
     event: "user.identified";
+} & BaseTrackEvent) | ({
+    event: "widget_render";
 } & BaseTrackEvent) | ({
     event: "price_shown";
     properties?: PriceShownProperties;
@@ -262,13 +278,6 @@ interface RevenueTrackingApi {
     leadQualified: (input?: RevenueLeadQualifiedInput) => Promise<{
         eventId: string;
     }>;
-    /**
-     * @deprecated Renamed in 0.15.0. Use `track.leadQualified()` instead; this
-     * alias emits a `lead_qualified` event and will be removed in 0.16.0.
-     */
-    lead: (input?: RevenueLeadQualifiedInput) => Promise<{
-        eventId: string;
-    }>;
     converted: (input: RevenueConvertedInput) => Promise<{
         eventId: string;
     }>;

package/dist/chat/index.d.ts

@@ -3,6 +3,250 @@ import * as ai from 'ai';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 
+interface SearchResult {
+    source: string;
+    heading: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, string>;
+}
+interface KbSearchTrace {
+    query: string;
+    resultCount: number;
+    results: Array<Pick<SearchResult, "source" | "heading" | "score">>;
+}
+
+/**
+ * Every event name in the typed taxonomy, as a runtime list. Single source of
+ * truth for {@link EventType} and for surfaces that need to recognize
+ * 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"];
+type EventType = (typeof EVENT_TYPES)[number];
+/**
+ * Properties for `page.viewed` — emitted once when the chat widget initializes
+ * on a host page (the top of the funnel). Attributed to the anonymous
+ * `visitorId` (mapped to `externalUserId`), never to a session: a page view
+ * must not create a session, otherwise sessions would equal page views and the
+ * "landed → started a conversation" funnel collapses.
+ */
+interface PageViewedProperties {
+    /** Full URL of the host page the widget loaded on. */
+    url?: string;
+    /** Referrer of the host page, if any. */
+    referrer?: string;
+    /** Embed mode the widget initialized in. */
+    mode?: "inline" | "floating";
+    /** Resolved device type from the visitor context. */
+    deviceType?: "mobile" | "tablet" | "desktop";
+    /** Primary browser language (BCP-47). */
+    language?: string;
+    /** IANA timezone of the visitor. */
+    timezone?: string;
+}
+interface ToolCalledProperties {
+    name?: string;
+    type?: "pricing" | "product_info" | "availability" | "support" | "other";
+    /** 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;
+    itemId?: string;
+    label?: string;
+}
+interface ComparedPriceOption {
+    id: string;
+    amount: number;
+    currency: string;
+}
+interface PricesComparedProperties {
+    options: ComparedPriceOption[];
+}
+interface OptionSelectedProperties {
+    id: string;
+    amount: number;
+    currency: string;
+}
+/**
+ * Properties for `lead_qualified` — your code declaring that a person met your
+ * qualification bar (finished the qualifying questions, requested a demo,
+ * matched your target profile). Sharing an email mid-conversation is
+ * `identify(userId, { email })`, not a qualified lead.
+ */
+interface LeadQualifiedProperties {
+    /**
+     * Your own lead id (e.g. the record id your lead-gen API returns). The
+     * strongest dedup key and the stable reference back to your system.
+     */
+    externalId?: string;
+    /** The lead's email, if known. */
+    email?: string;
+    /** The lead's name, if known. */
+    name?: string;
+}
+interface ConvertedProperties {
+    amount: number;
+    currency: string;
+    /** When the conversion actually happened — for backdated off-platform sales. */
+    occurredAt?: string;
+}
+interface TrackingContext {
+    /**
+     * MCP request metadata passed through to the API.
+     *
+     * Location varies by MCP library:
+     * - `@vercel/mcp-handler`: `extra._meta`
+     * - `@modelcontextprotocol/sdk`: `request.params._meta`
+     */
+    meta?: Record<string, unknown>;
+    /** Legacy metadata field supported for backward compatibility. */
+    metadata?: Record<string, unknown>;
+    /** Optional explicit correlation fields. */
+    sessionId?: string;
+    traceId?: string;
+    requestId?: string;
+    correlationId?: string;
+    externalUserId?: string;
+    /**
+     * Anonymous visitor id (the analytics "device id"). Counts as identity on
+     * its own: the ingest API accepts `sessionId`, `externalUserId`, or
+     * `visitorId`. The chat widget uses it for pre-session events like
+     * `page.viewed`.
+     */
+    visitorId?: string;
+    /** Optional explicit envelope fields. */
+    eventId?: string;
+    timestamp?: string | Date;
+    source?: string;
+}
+/**
+ * Modern tracking shape (preferred).
+ */
+interface BaseTrackEvent extends TrackingContext {
+    event: EventType;
+    properties?: Record<string, unknown>;
+}
+type TrackEvent = ({
+    event: "session.started";
+} & BaseTrackEvent) | ({
+    event: "page.viewed";
+    properties?: PageViewedProperties;
+} & 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) | ({
+    event: "widget_render";
+} & BaseTrackEvent) | ({
+    event: "price_shown";
+    properties?: PriceShownProperties;
+} & BaseTrackEvent) | ({
+    event: "prices_compared";
+    properties?: PricesComparedProperties;
+} & BaseTrackEvent) | ({
+    event: "option_selected";
+    properties?: OptionSelectedProperties;
+} & BaseTrackEvent) | ({
+    event: "lead_qualified";
+    properties?: LeadQualifiedProperties;
+} & BaseTrackEvent) | ({
+    event: "converted";
+    properties?: ConvertedProperties;
+} & BaseTrackEvent);
+/**
+ * Legacy tracking shape supported for existing integrations.
+ */
+interface LegacyTrackEvent extends TrackingContext {
+    eventType: EventType;
+    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()`.
+ */
+type TrackInput = TrackEvent | LegacyTrackEvent;
+interface RevenuePriceShownInput extends TrackingContext, PriceShownProperties {
+}
+interface RevenuePricesComparedInput extends TrackingContext, PricesComparedProperties {
+}
+interface RevenueOptionSelectedInput extends TrackingContext, OptionSelectedProperties {
+}
+/**
+ * Input for `track.leadQualified()` — identity only (`externalId`, `email`,
+ * `name`) plus the shared tracking context. There is no acquisition-source
+ * property; the envelope `source` (the origin channel) is set automatically.
+ */
+interface RevenueLeadQualifiedInput extends TrackingContext, LeadQualifiedProperties {
+}
+interface RevenueConvertedInput extends TrackingContext, ConvertedProperties {
+}
+/**
+ * Revenue-oriented helpers, flat on `client.track.*` (e.g.
+ * `client.track.priceShown()`, `client.track.converted()`). Decoupled from
+ * product primitives — each maps to a typed first-class revenue event.
+ */
+interface RevenueTrackingApi {
+    priceShown: (input: RevenuePriceShownInput) => Promise<{
+        eventId: string;
+    }>;
+    pricesCompared: (input: RevenuePricesComparedInput) => Promise<{
+        eventId: string;
+    }>;
+    optionSelected: (input: RevenueOptionSelectedInput) => Promise<{
+        eventId: string;
+    }>;
+    leadQualified: (input?: RevenueLeadQualifiedInput) => Promise<{
+        eventId: string;
+    }>;
+    converted: (input: RevenueConvertedInput) => Promise<{
+        eventId: string;
+    }>;
+}
+/**
+ * `client.track` — callable for generic events (`track(event)`), with the
+ * revenue helpers attached flat: `track.priceShown()`, `track.leadQualified()`,
+ * `track.converted()`, etc.
+ */
+interface TrackFn extends RevenueTrackingApi {
+    (event: TrackInput): Promise<{
+        eventId: string;
+    }>;
+}
+
 /**
  * Chat widget translation types.
  *
@@ -113,6 +357,13 @@ interface ChatAppearance {
     theme?: ThemePreset;
     /** Per-property overrides applied on top of the preset. */
     variables?: ChatTheme;
+    /**
+     * Render assistant messages inside a filled bubble (background + padding +
+     * radius), styled by `variables.assistantBubbleColor` /
+     * `assistantBubbleTextColor`. Defaults to `false` — assistant messages
+     * render as plain text. Opt in for a "both sides bubbled" chat style.
+     */
+    assistantBubble?: boolean;
 }
 /**
  * Tool-call activity rendering mode. Steps are grouped into one collapsible
@@ -162,6 +413,20 @@ interface ChatTheme {
     statusColor?: string;
     /** Tool call JSON section background. Defaults to light gray / #262626 in dark. */
     toolCardColor?: string;
+    /** Text color inside the user message bubble. Falls back to `primaryForeground`. */
+    userBubbleTextColor?: string;
+    /** Text color inside the assistant message bubble (only visible when `appearance.assistantBubble` is enabled). Falls back to `textColor`. */
+    assistantBubbleTextColor?: string;
+    /** Horizontal padding inside message bubbles (px). Defaults to 16. */
+    messagePaddingX?: number;
+    /** Vertical padding inside message bubbles (px). Defaults to 12. */
+    messagePaddingY?: number;
+    /** Max width of a message bubble as a CSS length/percentage. Defaults to `"80%"`. */
+    messageMaxWidth?: string;
+    /** Base font size for message text (px). When unset, messages use the CSS default of `1rem` (16px at the standard root font size). */
+    fontSize?: number;
+    /** Base line height for message text (unitless string, e.g. `"1.5"`). Defaults to `"1.5"`. */
+    lineHeight?: string;
 }
 interface WelcomeConfig {
     /** Icon displayed above the title. Accepts any React node (e.g. an SVG or img). */
@@ -185,6 +450,27 @@ interface SuggestionsConfig {
      */
     dynamic?: boolean;
 }
+/**
+ * Per-slot class name overrides for the chat widget. Each string is appended
+ * to the slot's own classes (merged with `tailwind-merge`, `ww` prefix). Use
+ * with your own (prefixed or plain) CSS to restyle any element. In the React
+ * path these reach into internals directly; in the `<script>` embed, prefer
+ * the stable `.ww-*` semantic classes with a `data-css` stylesheet.
+ */
+interface ChatClassNames {
+    /** Root chat container. */
+    root?: string;
+    /** Sticky header bar. */
+    header?: string;
+    /** Every message wrapper (both roles). */
+    message?: string;
+    /** The user message bubble content. */
+    userBubble?: string;
+    /** The assistant message bubble content. */
+    assistantBubble?: string;
+    /** The input bar container. */
+    input?: string;
+}
 interface ChatBaseProps {
     /** Waniwani project API key */
     apiKey?: string;
@@ -206,6 +492,8 @@ interface ChatBaseProps {
      * See `ChatAppearance` for the shape.
      */
     appearance?: ChatAppearance;
+    /** Per-slot class name overrides. See {@link ChatClassNames}. */
+    classNames?: ChatClassNames;
     /** Additional headers to send with chat API requests */
     headers?: Record<string, string>;
     /** Additional body fields to send with each chat request */
@@ -409,6 +697,21 @@ interface ChatHandle {
     messages: ai.UIMessage[];
     /** Session ID used for event correlation. Available after the first message. */
     sessionId: string | undefined;
+    /**
+     * Track a funnel event from the host page with the chat session attached
+     * automatically. Same surface as the server client: callable with a typed
+     * event, plus the flat revenue helpers (`track.converted({ ... })`, ...).
+     * Present on `WaniwaniChat` (hosted); absent on the bare `ChatEmbed`
+     * primitive, which has no Waniwani credential to send events with.
+     */
+    track?: TrackFn;
+    /**
+     * Tie the visitor to a stable user id (emits `user.identified`).
+     * Present on `WaniwaniChat` only, like `track`.
+     */
+    identify?: (userId: string, traits?: Record<string, unknown>) => Promise<{
+        eventId: string;
+    }>;
 }
 
 /** @deprecated Use `WaniwaniChat` (hosted, React) or the `<script>` embed for new code. `ChatCard` is preserved for back-compat only and lives under `@waniwani/sdk/legacy`. */
@@ -567,6 +870,8 @@ interface WaniwaniChatOverrides {
      * ```
      */
     appearance?: ChatAppearance;
+    /** Per-slot class name overrides. See `ChatClassNames`. */
+    classNames?: ChatClassNames;
     /** Chat API URL. Defaults to `https://app.waniwani.ai/api/mcp/chat`. */
     api?: string;
     /** Override the MCP server URL (rarely needed). */