Event schema

import type { TrackInput } from "@waniwani/sdk";

type TrackEvent = {
  event: EventType;                     // required, one of the built-in names
  properties?: Record<string, unknown>; // typed per event name
  meta?: Record<string, unknown>;       // MCP request _meta
  metadata?: Record<string, unknown>;   // free-form metadata on the envelope
  sessionId?: string;                   // explicit override, usually omit
  traceId?: string;
  requestId?: string;
  correlationId?: string;
  externalUserId?: string;
  visitorId?: string;                   // anonymous device id, counts as identity
  eventId?: string;                     // supply your own id (idempotency)
  timestamp?: string | Date;            // defaults to now
  source?: string;                      // defaults to "@waniwani/sdk"
};

import type {
  ToolCalledProperties,
  SessionErrorProperties,
  LinkClickedProperties,
  PriceShownProperties,
  PricesComparedProperties,
  OptionSelectedProperties,
  LeadQualifiedProperties,
  ConvertedProperties,
} from "@waniwani/sdk";

interface ToolCalledProperties {
  name?: string;
  type?: "pricing" | "product_info" | "availability" | "support" | "other";
  /** Retrieval traces for kb.search() calls made inside this tool handler. */
  kbSearch?: KbSearchTrace[];
  /** Stamped when the handler throws. Absent when it returns `{ isError: true }`. */
  cause?: SessionErrorProperties["cause"];
}

interface SessionErrorProperties {
  /**
   * agent_failed: a flow step failed (unknown node, missing edge, throwing
   * handler, iteration cap). upstream_failed: a flow state store read or
   * write failed. tool_failed: reserved, not emitted by the SDK yet.
   */
  code: "agent_failed" | "tool_failed" | "upstream_failed";
  cause:
    | "timeout"
    | "rate_limited"
    | "upstream_4xx"
    | "upstream_5xx"
    | "network"
    | "invalid_output"
    | "flow_dead_end"
    | "flow_unknown_node"
    | "flow_loop"
    | "unknown";
  /** The tool the failure is attributed to, if any. */
  tool?: string;
  /** The flow node that failed, if any. */
  node?: string;
}

interface LinkClickedProperties {
  url?: string;
}

interface PriceShownProperties {
  amount: number;
  currency: string;
  itemId?: string;
  label?: string;
}

interface PricesComparedProperties {
  options: Array<{ id: string; amount: number; currency: string }>;
}

interface OptionSelectedProperties {
  id: string;
  amount: number;
  currency: string;
}

interface LeadQualifiedProperties {
  /** Your own lead id (e.g. the record id your CRM returns). The strongest dedup key. */
  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;
}