@waniwani/sdk 0.15.1 → 0.16.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
@@ -136,8 +143,6 @@ interface LeadQualifiedProperties {
     email?: string;
     /** The lead's name, if known. */
     name?: string;
-    /** Acquisition source of the lead (e.g. "newsletter"). */
-    source?: string;
 }
 interface ConvertedProperties {
     amount: number;
@@ -162,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;
@@ -197,6 +209,8 @@ type TrackEvent = ({
     properties?: PurchaseCompletedProperties;
 } & BaseTrackEvent) | ({
     event: "user.identified";
+} & BaseTrackEvent) | ({
+    event: "widget_render";
 } & BaseTrackEvent) | ({
     event: "price_shown";
     properties?: PriceShownProperties;
@@ -238,10 +252,9 @@ interface RevenuePricesComparedInput extends TrackingContext, PricesComparedProp
 interface RevenueOptionSelectedInput extends TrackingContext, OptionSelectedProperties {
 }
 /**
- * Input for `track.leadQualified()`. `source` is the lead's acquisition source
- * (the event property, e.g. "newsletter") — on this helper it shadows the
- * envelope `source` from the tracking context. To set a custom envelope source
- * on a lead, use the generic `track({ event: "lead_qualified", … })`.
+ * 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 {
 }
@@ -265,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.
  *
@@ -409,6 +653,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`. */