@waniwani/sdk 0.15.1 → 0.16.0

package/dist/legacy/index.d.ts

@@ -137,7 +137,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
@@ -211,8 +218,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;
@@ -237,6 +242,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;
@@ -272,6 +284,8 @@ type TrackEvent = ({
     properties?: PurchaseCompletedProperties;
 } & BaseTrackEvent) | ({
     event: "user.identified";
+} & BaseTrackEvent) | ({
+    event: "widget_render";
 } & BaseTrackEvent) | ({
     event: "price_shown";
     properties?: PriceShownProperties;
@@ -313,10 +327,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 {
 }
@@ -340,13 +353,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;
     }>;
@@ -422,6 +428,13 @@ interface TrackingClient {
  * when the server is wrapped with `withWaniwani()`.
  */
 interface ScopedWaniWaniClient {
+    /**
+     * The session id this request's events correlate to, resolved from the
+     * request meta. Read it to link the session to your own records (store it
+     * on a lead, then send an off-platform `converted` with the same
+     * `sessionId` later). `undefined` when the host provided no session id.
+     */
+    readonly sessionId?: string;
     /**
      * Track an event — request meta is automatically merged. Also exposes the
      * revenue helpers flat (`track.priceShown()`, `track.converted()`, …), which
@@ -1656,6 +1669,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`. */