@waniwani/sdk 0.14.20 → 0.15.0

package/dist/legacy/index.d.ts

@@ -83,6 +83,11 @@ interface SearchResult {
     score: number;
     metadata?: Record<string, string>;
 }
+interface KbSearchTrace {
+    query: string;
+    resultCount: number;
+    results: Array<Pick<SearchResult, "source" | "heading" | "score">>;
+}
 /** A file to ingest into the knowledge base */
 interface KbIngestFile {
     /** Filename (used as chunk source identifier) */
@@ -132,7 +137,7 @@ 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" | "converted";
+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";
 /**
  * Properties for `page.viewed` — emitted once when the chat widget initializes
  * on a host page (the top of the funnel). Attributed to the anonymous
@@ -157,6 +162,8 @@ interface PageViewedProperties {
 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;
@@ -188,7 +195,23 @@ interface OptionSelectedProperties {
     amount: number;
     currency: string;
 }
-interface LeadProperties {
+/**
+ * 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;
+    /** Acquisition source of the lead (e.g. "newsletter"). */
     source?: string;
 }
 interface ConvertedProperties {
@@ -259,8 +282,8 @@ type TrackEvent = ({
     event: "option_selected";
     properties?: OptionSelectedProperties;
 } & BaseTrackEvent) | ({
-    event: "lead";
-    properties?: LeadProperties;
+    event: "lead_qualified";
+    properties?: LeadQualifiedProperties;
 } & BaseTrackEvent) | ({
     event: "converted";
     properties?: ConvertedProperties;
@@ -290,12 +313,12 @@ interface RevenuePricesComparedInput extends TrackingContext, PricesComparedProp
 interface RevenueOptionSelectedInput extends TrackingContext, OptionSelectedProperties {
 }
 /**
- * Input for `track.lead()`. `source` is the lead's acquisition source
- * (the `lead` 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", … })`.
+ * 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", … })`.
  */
-interface RevenueLeadInput extends TrackingContext, LeadProperties {
+interface RevenueLeadQualifiedInput extends TrackingContext, LeadQualifiedProperties {
 }
 interface RevenueConvertedInput extends TrackingContext, ConvertedProperties {
 }
@@ -314,7 +337,7 @@ interface RevenueTrackingApi {
     optionSelected: (input: RevenueOptionSelectedInput) => Promise<{
         eventId: string;
     }>;
-    lead: (input?: RevenueLeadInput) => Promise<{
+    leadQualified: (input?: RevenueLeadQualifiedInput) => Promise<{
         eventId: string;
     }>;
     converted: (input: RevenueConvertedInput) => Promise<{
@@ -323,7 +346,7 @@ interface RevenueTrackingApi {
 }
 /**
  * `client.track` — callable for generic events (`track(event)`), with the
- * revenue helpers attached flat: `track.priceShown()`, `track.lead()`,
+ * revenue helpers attached flat: `track.priceShown()`, `track.leadQualified()`,
  * `track.converted()`, etc.
  */
 interface TrackFn extends RevenueTrackingApi {
@@ -372,7 +395,7 @@ interface TrackingClient {
      * Returns a deterministic event id immediately after enqueue.
      *
      * Also exposes the revenue helpers flat: `client.track.priceShown()`,
-     * `client.track.lead()`, `client.track.converted()`, etc.
+     * `client.track.leadQualified()`, `client.track.converted()`, etc.
      */
     track: TrackFn;
     /**