@waniwani/sdk 0.1.20-beta.2 → 0.1.20-beta.21

package/dist/mcp/index.d.ts

@@ -1,3 +1,4 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -112,23 +113,11 @@ declare global {
 /**
  * Result from calling a tool
  */
-type ToolCallResult = {
-    content?: Array<{
-        type: string;
-        text?: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
-};
+type ToolCallResult = CallToolResult;
 /**
  * Tool result notification (what the host pushes to the widget)
  */
-type ToolResult = {
-    content?: Array<{
-        type: string;
-        text?: string;
-    }>;
-    structuredContent?: Record<string, unknown>;
-};
+type ToolResult = CallToolResult;
 /**
  * Host context - all values available from the host.
  */
@@ -245,14 +234,14 @@ interface UnifiedWidgetClient {
     onMaxHeightChange(callback: (maxHeight: number | null) => void): () => void;
     /**
      * Get the tool response metadata.
-     * OpenAI-only: returns metadata from window.openai.toolResponseMetadata.
-     * MCP Apps: returns null.
+     * OpenAI: returns metadata from window.openai.toolResponseMetadata.
+     * MCP Apps: returns `_meta` from the latest `ui/notifications/tool-result`, if provided by host.
      */
     getToolResponseMetadata(): UnknownObject | null;
     /**
      * Subscribe to tool response metadata changes.
-     * OpenAI-only: subscribes to toolResponseMetadata changes.
-     * MCP Apps: callback is never called.
+     * OpenAI: subscribes to toolResponseMetadata changes.
+     * MCP Apps: fires when tool result `_meta` changes.
      */
     onToolResponseMetadataChange(callback: (metadata: UnknownObject | null) => void): () => void;
     /**
@@ -316,15 +305,26 @@ declare const START: "__start__";
 declare const END: "__end__";
 declare const INTERRUPT: unique symbol;
 declare const WIDGET: unique symbol;
-type InterruptSignal = {
-    readonly __type: typeof INTERRUPT;
+/** A single question within an interrupt step */
+type InterruptQuestion = {
     /** Question to ask the user */
     question: string;
     /** State key where the answer will be stored */
     field: string;
     /** Optional suggestions to present as options */
     suggestions?: string[];
-    /** Hidden context/instructions for the assistant (not shown to user directly) */
+    /** Hidden context/instructions for this specific question (not shown to user directly) */
+    context?: string;
+};
+/**
+ * Interrupt signal — pauses the flow and asks the user one or more questions.
+ * Single-question and multi-question interrupts use the same type.
+ */
+type InterruptSignal = {
+    readonly __type: typeof INTERRUPT;
+    /** Questions to ask — ask all in one conversational message */
+    questions: InterruptQuestion[];
+    /** Overall hidden context/instructions for the assistant (not shown to user directly) */
     context?: string;
 };
 type WidgetSignal = {
@@ -335,36 +335,94 @@ type WidgetSignal = {
     data: Record<string, unknown>;
     /** Description of what the widget does (for the AI's context) */
     description?: string;
+    /**
+     * State key this widget fills — enables auto-skip when the field is already in state.
+     * Pass this so the engine can skip the widget step when the answer is already known.
+     */
+    field?: string;
 };
 /**
- * Create an interrupt signal — pauses the flow and asks the user a text question.
+ * Create an interrupt signal — pauses the flow and asks the user a question.
+ *
+ * Accepts a single question (shorthand) or multiple questions (array form).
+ * Both produce the same signal type.
+ *
+ * @example Single question
+ * ```ts
+ * return interrupt({ question: "Your email?", field: "email" })
+ * ```
+ *
+ * @example Multiple questions (asked together in one message)
+ * ```ts
+ * return interrupt({ questions: [
+ *   { question: "How many employees?", field: "headcount" },
+ *   { question: "Average age?", field: "averageAge" },
+ * ]})
+ * ```
  */
 declare function interrupt(config: {
     question: string;
     field: string;
     suggestions?: string[];
     context?: string;
+} | {
+    questions: InterruptQuestion[];
+    context?: string;
 }): InterruptSignal;
 /**
  * Create a widget signal — pauses the flow and renders a widget UI.
+ *
+ * Pass `field` to enable auto-skip: if the field is already in state, the widget
+ * step will be skipped automatically.
  */
 declare function showWidget(resource: RegisteredResource, config: {
     data: Record<string, unknown>;
     description?: string;
+    field?: string;
 }): WidgetSignal;
 type MaybePromise<T> = T | Promise<T>;
-/** Configuration for a flow node */
+/**
+ * Optional config for handler-based nodes.
+ * Provides metadata used by the engine (e.g., auto-skip on widget steps).
+ *
+ * For declarative nodes, config is inferred automatically — no need to pass this.
+ */
 type NodeConfig<TState extends Record<string, unknown> = Record<string, unknown>> = {
-    /** Resource to display when this node returns a WidgetSignal */
-    resource?: RegisteredResource;
-    /** State key this node fills — enables auto-skip when the field is already in state via `initialState` */
+    /**
+     * State key this node fills.
+     * When set on a handler-based widget node and the field is already in state,
+     * the node is auto-skipped. (Alternatively, pass `field` to `showWidget()`.)
+     */
+    field?: Extract<keyof TState, string>;
+};
+/**
+ * Declarative widget node config — show a widget without writing a handler.
+ * Eliminates duplicate resource references: declare it once, not in both addNode and showWidget.
+ *
+ * `data` can be a static object or a function receiving current state for dynamic data.
+ * `field` enables auto-skip when the field is already in state.
+ *
+ * @example
+ * ```ts
+ * .addNode("show_pricing", {
+ *   resource: pricingTableResource,
+ *   field: "selectedPlan",
+ *   description: "Show the 3 pricing tiers.",
+ *   data: (state) => ({ ccnName: state.ccnName, offers: computeOffers(state.idcc) }),
+ * })
+ * ```
+ */
+type WidgetNodeConfig<TState extends Record<string, unknown> = Record<string, unknown>> = {
+    resource: RegisteredResource;
     field?: Extract<keyof TState, string>;
+    description?: string;
+    data?: Record<string, unknown> | ((state: Partial<TState>) => Record<string, unknown>);
 };
 /**
  * Node handler — a single function type for all node kinds.
  * The return value determines behavior:
  * - `Partial<TState>` → action node (state merged, auto-advance)
- * - `InterruptSignal` → interrupt (pause, ask user)
+ * - `InterruptSignal` → interrupt (pause, ask user one or more questions)
  * - `WidgetSignal` → widget step (pause, show widget)
  */
 type NodeHandler<TState> = (state: Partial<TState>, meta?: Record<string, unknown>) => MaybePromise<Partial<TState> | InterruptSignal | WidgetSignal>;
@@ -381,20 +439,24 @@ type FlowConfig = {
     /** Description for the AI (explains when to use this flow) */
     description: string;
     /**
-     * Describe the flow's state fields so the AI can pre-fill answers
-     * from the user's message via `initialState`.
-     * Keys are the field names used in `interrupt({ field })`,
+     * Define the flow's state — each field the flow collects.
+     * Keys are the field names used in `interrupt({ field })` or `NodeConfig.field`,
      * values are Zod schemas with `.describe()`.
      *
+     * The state definition serves two purposes:
+     * 1. Type inference — `TState` is automatically derived, no explicit generic needed
+     * 2. AI protocol — field names, types, and descriptions are included in the tool
+     *    description so the AI can pre-fill answers via `_meta.flow.state`
+     *
      * @example
      * ```ts
-     * fields: {
+     * state: {
      *   country: z.string().describe("Country the business is based in"),
      *   status: z.enum(["registered", "unregistered"]).describe("Business registration status"),
      * }
      * ```
      */
-    fields?: Record<string, z.ZodType>;
+    state: Record<string, z.ZodType>;
     /** Optional tool annotations */
     annotations?: {
         readOnlyHint?: boolean;
@@ -403,6 +465,24 @@ type FlowConfig = {
         destructiveHint?: boolean;
     };
 };
+/**
+ * Infer the runtime state type from a flow's state schema definition.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   state: {
+ *     country: z.enum(["FR", "DE"]),
+ *     status: z.enum(["registered", "unregistered"]),
+ *   }
+ * };
+ * type MyState = InferFlowState<typeof config.state>;
+ * // { country: "FR" | "DE"; status: "registered" | "unregistered" }
+ * ```
+ */
+type InferFlowState<T extends Record<string, z.ZodType>> = {
+    [K in keyof T]: z.infer<T[K]>;
+};
 /**
  * A compiled flow — can be registered on an McpServer.
  */
@@ -423,7 +503,7 @@ type RegisteredFlow = {
  *   title: "User Onboarding",
  *   description: "Guides users through onboarding",
  * })
- *   .addNode("ask_name", () => interrupt({ question: "What's your name?", field: "name" }))
+ *   .addNode("ask_name", (state) => interrupt({ question: "What's your name?", field: "name" }))
  *   .addNode("greet", (state) => ({ greeting: `Hello ${state.name}!` }))
  *   .addEdge(START, "ask_name")
  *   .addEdge("ask_name", "greet")
@@ -436,15 +516,32 @@ declare class StateGraph<TState extends Record<string, unknown>> {
     private nodeConfigs;
     private edges;
     private config;
+    private resources;
     constructor(config: FlowConfig);
     /**
      * Add a node with just a handler.
      */
     addNode(name: string, handler: NodeHandler<TState>): this;
     /**
-     * Add a node with config (e.g., resource, field) and a handler.
+     * Add a node with config and a handler.
+     * Pass `field` to enable auto-skip on widget nodes.
      */
     addNode(name: string, config: NodeConfig<TState>, handler: NodeHandler<TState>): this;
+    /**
+     * Declarative widget node — show a widget without writing a handler.
+     * Resource is declared once; no `showWidget()` call needed.
+     *
+     * @example
+     * ```ts
+     * .addNode("show_pricing", {
+     *   resource: pricingResource,
+     *   field: "selectedPlan",
+     *   description: "Show the pricing tiers.",
+     *   data: (state) => ({ offers: computeOffers(state.idcc) }),
+     * })
+     * ```
+     */
+    addNode(name: string, config: WidgetNodeConfig<TState>): this;
     /**
      * Add a direct edge between two nodes.
      *
@@ -470,16 +567,22 @@ declare class StateGraph<TState extends Record<string, unknown>> {
 /**
  * Create a new flow graph — convenience factory for `new StateGraph()`.
  *
+ * The state type is automatically inferred from the `state` definition —
+ * no explicit generic parameter needed.
+ *
  * @example
  * ```ts
  * import { createFlow, interrupt, START, END } from "@waniwani/sdk/mcp";
+ * import { z } from "zod";
  *
- * type MyState = { name: string; email: string };
- *
- * const flow = createFlow<MyState>({
+ * const flow = createFlow({
  *   id: "onboarding",
  *   title: "User Onboarding",
  *   description: "Guides users through onboarding. Use when a user wants to get started.",
+ *   state: {
+ *     name: z.string().describe("The user's name"),
+ *     email: z.string().describe("The user's email address"),
+ *   },
  * })
  *   .addNode("ask_name", () => interrupt({ question: "What's your name?", field: "name" }))
  *   .addNode("ask_email", () => interrupt({ question: "What's your email?", field: "email" }))
@@ -489,7 +592,9 @@ declare class StateGraph<TState extends Record<string, unknown>> {
  *   .compile();
  * ```
  */
-declare function createFlow<TState extends Record<string, unknown>>(config: FlowConfig): StateGraph<TState>;
+declare function createFlow<const TSchema extends Record<string, z.ZodType>>(config: Omit<FlowConfig, "state"> & {
+    state: TSchema;
+}): StateGraph<InferFlowState<TSchema>>;
 
 /**
  * Creates a reusable UI resource (HTML template) that can be attached
@@ -591,4 +696,257 @@ declare function createTool<TInput extends z.ZodRawShape>(config: ToolConfig<TIn
  */
 declare function registerTools(server: McpServer, tools: RegisteredTool[]): Promise<void>;
 
-export { type ConditionFn, END, type FlowConfig, type HostContext, type InterruptSignal, type NodeConfig, type NodeHandler, type RegisteredFlow, type RegisteredResource, type RegisteredTool, type ResourceConfig, START, StateGraph, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type UnifiedWidgetClient, type WidgetCSP, type WidgetPlatform, type WidgetSignal, createFlow, createResource, createTool, detectPlatform, interrupt, isMCPApps, isOpenAI, registerTools, showWidget };
+/**
+ * Server-side API route handler for widget tracking events.
+ *
+ * Receives batched events from the `useWaniwani` React hook and forwards them
+ * to the WaniWani backend using the server-side SDK.
+ *
+ * @example Next.js App Router
+ * ```typescript
+ * // app/api/waniwani/track/route.ts
+ * import { createTrackingRoute } from "@waniwani/sdk/mcp";
+ *
+ * const handler = createTrackingRoute({
+ *   apiKey: process.env.WANIWANI_API_KEY,
+ *   baseUrl: process.env.WANIWANI_BASE_URL,
+ * });
+ *
+ * export { handler as POST };
+ * ```
+ */
+interface TrackingRouteOptions {
+    /** API key for the WaniWani backend. Defaults to WANIWANI_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL for the WaniWani backend. Defaults to https://app.waniwani.ai. */
+    baseUrl?: string;
+}
+/**
+ * Creates a POST handler that receives tracking events from `useWaniwani`
+ * and forwards them to the WaniWani backend.
+ */
+declare function createTrackingRoute(options?: TrackingRouteOptions): (request: Request) => Promise<Response>;
+
+type EventType = "session.started" | "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";
+interface ToolCalledProperties {
+    name?: string;
+    type?: "pricing" | "product_info" | "availability" | "support" | "other";
+}
+interface QuoteSucceededProperties {
+    amount?: number;
+    currency?: string;
+}
+interface LinkClickedProperties {
+    url?: string;
+}
+interface PurchaseCompletedProperties {
+    amount?: number;
+    currency?: 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;
+    /** 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: "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);
+/**
+ * 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 TrackingConfig {
+    /** Events API V2 endpoint path. */
+    endpointPath?: string;
+    /** Periodic flush interval for buffered events. */
+    flushIntervalMs?: number;
+    /** Max events per HTTP batch send. */
+    maxBatchSize?: number;
+    /** Max in-memory buffer size before oldest items are dropped. */
+    maxBufferSize?: number;
+    /** Number of retries for retryable failures. */
+    maxRetries?: number;
+    /** Retry backoff base delay. */
+    retryBaseDelayMs?: number;
+    /** Retry backoff max delay. */
+    retryMaxDelayMs?: number;
+    /** Default shutdown timeout when none is provided. */
+    shutdownTimeoutMs?: number;
+}
+interface TrackingShutdownOptions {
+    timeoutMs?: number;
+}
+interface TrackingShutdownResult {
+    timedOut: boolean;
+    pendingEvents: number;
+}
+/**
+ * Tracking module methods for WaniWaniClient.
+ */
+interface TrackingClient {
+    /**
+     * Track an event using modern or legacy input shape.
+     * Returns a deterministic event id immediately after enqueue.
+     */
+    track: (event: TrackInput) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * Flush all currently buffered events.
+     */
+    flush: () => Promise<void>;
+    /**
+     * Flush and stop the transport.
+     */
+    shutdown: (options?: TrackingShutdownOptions) => Promise<TrackingShutdownResult>;
+}
+
+interface WaniWaniConfig {
+    /**
+     * Your MCP environment API key
+     *
+     * Defaults to process.env.WANIWANI_API_KEY if not provided
+     *
+     * To create one, visit:
+     * https://app.waniwani.com/mcp/environments
+     */
+    apiKey?: string;
+    /**
+     * The base URL of the WaniWani API
+     *
+     * Defaults to https://app.waniwani.ai
+     */
+    baseUrl?: string;
+    /**
+     * Tracking transport behavior.
+     */
+    tracking?: TrackingConfig;
+}
+/**
+ * WaniWani SDK Client
+ *
+ * Extends with each module:
+ * - TrackingClient: track(), flush(), shutdown()
+ *
+ * Pass this client to framework adapters:
+ * - `toNextJsHandler(wani, { ... })` for Next.js route handlers
+ */
+interface WaniWaniClient extends TrackingClient {
+    /** @internal Resolved config — used by framework adapters */
+    readonly _config: InternalConfig;
+}
+interface InternalConfig {
+    baseUrl: string;
+    apiKey: string | undefined;
+    tracking: Required<TrackingConfig>;
+}
+
+type WaniwaniTracker = Pick<WaniWaniClient, "flush" | "track" | "_config">;
+type UnknownRecord = Record<string, unknown>;
+/**
+ * Options for withWaniwani().
+ */
+type WithWaniwaniOptions = {
+    /**
+     * Optional pre-built WaniWani client.
+     * When omitted, a new client is created from `config`.
+     */
+    client?: WaniwaniTracker;
+    /**
+     * WaniWani client config used when `client` is omitted.
+     */
+    config?: WaniWaniConfig;
+    /**
+     * Optional explicit tool type. Defaults to `"other"`.
+     */
+    toolType?: ToolCalledProperties["type"] | ((toolName: string) => ToolCalledProperties["type"] | undefined);
+    /**
+     * Optional metadata merged into every tracked event.
+     */
+    metadata?: UnknownRecord;
+    /**
+     * Flush tracking transport after each tool call.
+     */
+    flushAfterToolCall?: boolean;
+    /**
+     * Optional error callback for non-fatal tracking errors.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Inject widget tracking config into tool response `_meta.waniwani` so browser
+     * widgets can send events directly to the WaniWani backend.
+     *
+     * Always injects `endpoint`. Injects `token` when an API key is configured
+     * and token minting succeeds.
+     *
+     * @default true
+     */
+    injectWidgetToken?: boolean;
+};
+/**
+ * Wrap an MCP server so tool handlers automatically emit `tool.called` events.
+ *
+ * The wrapper intercepts `server.registerTool(...)`, tracks each invocation,
+ * then forwards execution to the original tool handler.
+ *
+ * When `injectWidgetToken` is enabled (default), tracking config is injected
+ * into tool response `_meta.waniwani` so browser widgets can post events
+ * directly to the WaniWani backend without a server-side proxy.
+ */
+declare function withWaniwani(server: McpServer, options?: WithWaniwaniOptions): McpServer;
+
+export { type ConditionFn, END, type FlowConfig, type HostContext, type InferFlowState, type InterruptSignal, type NodeConfig, type NodeHandler, type RegisteredFlow, type RegisteredResource, type RegisteredTool, type ResourceConfig, START, StateGraph, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type TrackingRouteOptions, type UnifiedWidgetClient, type WidgetCSP, type WidgetPlatform, type WidgetSignal, type WithWaniwaniOptions, createFlow, createResource, createTool, createTrackingRoute, detectPlatform, interrupt, isMCPApps, isOpenAI, registerTools, showWidget, withWaniwani };