@waniwani/sdk 0.15.2 → 0.17.0

package/dist/mcp/react.d.ts

@@ -642,55 +642,287 @@ declare function isOpenAI(): boolean;
  */
 declare function isMCPApps(): boolean;
 
+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 {
+}
 /**
- * Opt-in toggles for the noisy auto-capture event types. Each defaults to
- * `false` so widget owners declare intent before the SDK starts emitting
- * coarse, high-volume events. Always-on capture covers widget_render,
- * widget_error, widget_link_click, and the labelled `data-ww-step` /
- * `data-ww-conversion` clicks.
+ * 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 AutoCaptureToggles {
-    click?: boolean;
-    scroll?: boolean;
-    formField?: boolean;
-    formSubmit?: boolean;
+interface TrackFn extends RevenueTrackingApi {
+    (event: TrackInput): Promise<{
+        eventId: string;
+    }>;
 }
 
 interface BaseUseWaniwaniOptions {
     /**
      * JWT widget token for authenticating directly with the Waniwani backend.
      * If omitted, the hook resolves from tool response metadata
-     * (`toolResponseMetadata.waniwani` or `toolResponseMetadata._meta.waniwani`).
+     * (`_meta["waniwani/widget"].token`).
      */
     token?: string;
     /**
      * Session ID to use for event correlation.
      * If omitted, the hook resolves from tool response metadata
-     * (`toolResponseMetadata.waniwani.sessionId`), then falls back to a random UUID.
+     * (`_meta["waniwani/widget"].sessionId`), then falls back to a random UUID
+     * so the widget's own events still group together.
      */
     sessionId?: string;
     /**
-     * Additional metadata to include with every tracked event.
+     * Additional fields merged into every tracked event's envelope metadata.
      */
     metadata?: Record<string, unknown>;
     /**
-     * Opt-in toggles for noisy auto-capture event types. Default: all off.
-     * Always-on capture: widget_render, widget_error, widget_link_click,
-     * `data-ww-step` / `data-ww-conversion` clicks.
+     * Tool response metadata from a host you already have a connection to
+     * (e.g. an MCP-Apps / skybridge host exposing `useToolInfo().responseMetadata`).
      *
-     * @example
-     * useWaniwani({ capture: { click: true, scroll: true } });
+     * The hook resolves its config (`endpoint`, `source`, `token`, `sessionId`)
+     * from `_meta["waniwani/widget"]` in this object. The hook never opens a host
+     * connection of its own — your app owns the host bridge and passes the
+     * metadata in. Ignored when an explicit `endpoint` is passed.
      */
-    capture?: AutoCaptureToggles;
+    toolResponseMetadata?: Record<string, unknown> | null;
 }
 /**
- * Context-driven options: `endpoint` and `source` are resolved from
- * `WidgetProvider`'s `toolResponseMetadata.waniwani`. `source` may be
- * overridden explicitly.
+ * Metadata-driven options: `endpoint` and `source` are resolved from the
+ * `toolResponseMetadata` you pass (`_meta["waniwani/widget"]`). `source` may
+ * be overridden explicitly.
  */
 interface ContextDrivenOptions extends BaseUseWaniwaniOptions {
     endpoint?: undefined;
-    /** Optional override; otherwise resolved from context. */
+    /** Optional override; otherwise resolved from `toolResponseMetadata`. */
     source?: string;
 }
 /**
@@ -704,8 +936,8 @@ interface ExplicitEndpointOptions extends BaseUseWaniwaniOptions {
     source: string;
 }
 /**
- * Options for the useWaniwani hook. Either rely on `WidgetProvider`
- * context (omit `endpoint`) or pass `endpoint` + `source` explicitly.
+ * Options for the useWaniwani hook. Either rely on the widget host
+ * (omit `endpoint`) or pass `endpoint` + `source` explicitly.
  */
 type UseWaniwaniOptions = ContextDrivenOptions | ExplicitEndpointOptions;
 /**
@@ -714,44 +946,57 @@ type UseWaniwaniOptions = ContextDrivenOptions | ExplicitEndpointOptions;
 interface WaniwaniWidget {
     /**
      * The session ID stamped on every event this widget emits, so hosts can
-     * correlate widget activity with server-side tracking without reaching into
-     * the internal `_meta` shape.
+     * correlate widget activity with server-side tracking.
      *
-     * Resolved from (1) the explicit `sessionId` option, (2)
-     * `toolResponseMetadata.waniwani.sessionId`, else a random UUID generated
-     * on mount. `undefined` until the widget initializes (same lifecycle as the
-     * tracking methods) and when no config resolves (no-op widget).
+     * Resolved from (1) the explicit `sessionId` option, (2) the widget config
+     * injected by `withWaniwani` (`_meta["waniwani/widget"].sessionId`), else a
+     * random UUID generated on mount. `undefined` until the widget initializes
+     * and when no config resolves (no-op widget).
      */
     readonly sessionId?: string;
-    /** Tie all subsequent widget events to this user. */
-    identify(userId: string, traits?: Record<string, unknown>): void;
-    /** Record a funnel step. Auto-incrementing sequence per session. */
-    step(name: string, meta?: Record<string, unknown>): void;
-    /** Record a generic custom event. */
-    track(event: string, properties?: Record<string, unknown>): void;
-    /** Record a conversion event. */
-    conversion(name: string, data?: Record<string, unknown>): void;
+    /**
+     * Track a typed event. The exact same surface as the server client:
+     * `track({ event: "quote.succeeded", properties })`,
+     * `track.priceShown({ amount, currency })`, `track.converted({ ... })`.
+     * Identity (session, trace, user) is stamped automatically.
+     */
+    track: TrackFn;
+    /** Tie all subsequent widget events to this user (emits `user.identified`). */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<{
+        eventId: string;
+    }>;
+    /** Flush buffered events immediately instead of waiting for the timer. */
+    flush(): Promise<void>;
 }
 /**
- * React hook for Waniwani widget tracking.
+ * React hook for tracking from inside an MCP-app widget. Returns the same
+ * `track` surface as the server client, with session identity stamped
+ * automatically from the config `withWaniwani` injects into tool responses.
  *
- * Auto-captures DOM events (clicks, link clicks, errors, scrolls, form
- * interactions) and provides manual tracking methods. Returns a singleton
- * instance shared across all consumers.
+ * The hook never opens a host connection of its own. Supply config one of
+ * two ways:
+ * 1. Explicit `endpoint` + `source` (plus optional `token` / `sessionId`)
+ * 2. `toolResponseMetadata` — the `_meta` object your host already exposes
+ *    (e.g. skybridge's `useToolInfo().responseMetadata`); the hook reads
+ *    `_meta["waniwani/widget"]` from it
  *
- * Config resolution order:
- * 1. Explicit `endpoint` / `token` / `sessionId` / `source` options
- * 2. `toolResponseMetadata.waniwani` from WidgetProvider context
- * 3. No-op if `endpoint` cannot be resolved or `source` is unknown
+ * No-op when neither resolves an `endpoint` and a `source`.
  *
  * @example
  * ```tsx
  * function MyWidget() {
- *   const wani = useWaniwani();
- *   // Auto-captures clicks, links, errors, scrolls, forms
- *   // Optionally call wani.track("custom_event") for manual events
- *   // Read wani.sessionId to correlate with server-side tracking
- *   return <a href="https://example.com">Visit</a>;
+ *   const { responseMetadata } = useToolInfo();
+ *   const wani = useWaniwani({ toolResponseMetadata: responseMetadata });
+ *   // wani.sessionId correlates with server-side tracking
+ *   return (
+ *     <button
+ *       onClick={() =>
+ *         wani.track.optionSelected({ id: "pro", amount: 49, currency: "EUR" })
+ *       }
+ *     >
+ *       Choose Pro
+ *     </button>
+ *   );
  * }
  * ```
  */