@waniwani/sdk 0.4.3 → 0.4.4

package/dist/mcp/index.d.ts

@@ -313,11 +313,225 @@ type RegisteredResource = {
     register: (server: McpServer) => Promise<void>;
 };
 
+interface SearchResult {
+    source: string;
+    heading: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, string>;
+}
+/** A file to ingest into the knowledge base */
+interface KbIngestFile {
+    /** Filename (used as chunk source identifier) */
+    filename: string;
+    /** Markdown content of the file */
+    content: string;
+    /** Arbitrary key-value metadata attached to all chunks from this file */
+    metadata?: Record<string, string>;
+}
+/** Response from the ingest endpoint */
+interface KbIngestResult {
+    /** Number of chunks created from the ingested files */
+    chunksIngested: number;
+    /** Number of files successfully processed */
+    filesProcessed: number;
+}
+/** Options for the search method */
+interface KbSearchOptions {
+    /** Number of results to return (1-20, default 5) */
+    topK?: number;
+    /** Minimum similarity score threshold (0-1, default 0.3) */
+    minScore?: number;
+    /** Filter results to chunks whose metadata contains all these key-value pairs (exact match) */
+    metadata?: Record<string, string>;
+}
+/** A source entry in the knowledge base */
+interface KbSource {
+    /** Source filename */
+    source: string;
+    /** Number of chunks from this source */
+    chunkCount: number;
+    /** ISO timestamp of when the source was first ingested */
+    createdAt: string;
+}
+/** KB client for server-side knowledge base operations */
+interface KbClient {
+    /**
+     * Ingest files into the knowledge base.
+     *
+     * **Warning**: This is destructive — it deletes ALL existing chunks
+     * for the environment before ingesting the new files.
+     */
+    ingest(files: KbIngestFile[]): Promise<KbIngestResult>;
+    /** Search the knowledge base for relevant chunks */
+    search(query: string, options?: KbSearchOptions): Promise<SearchResult[]>;
+    /** List all sources in the knowledge base */
+    sources(): Promise<KbSource[]>;
+}
+
+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" | "user.identified";
+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) | ({
+    event: "user.identified";
+} & 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 {
+    /**
+     * Send a one-shot identify event for a user.
+     * userId can be any string: an email, an internal ID, etc.
+     */
+    identify: (userId: string, properties?: Record<string, unknown>, meta?: Record<string, unknown>) => Promise<{
+        eventId: string;
+    }>;
+    /**
+     * 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>;
+}
+
+/**
+ * A request-scoped WaniWani client with meta pre-attached.
+ *
+ * Available as `context.waniwani` inside `createTool` handlers and flow nodes
+ * when the server is wrapped with `withWaniwani()`.
+ */
+interface ScopedWaniWaniClient {
+    /** Track an event — request meta is automatically merged. */
+    track(event: TrackInput): Promise<{
+        eventId: string;
+    }>;
+    /** Identify a user — request meta is automatically merged. */
+    identify(userId: string, properties?: Record<string, unknown>): Promise<{
+        eventId: string;
+    }>;
+    /** Knowledge base client (no meta needed). */
+    readonly kb: KbClient;
+}
+
 type ToolHandlerContext = {
     /** Raw MCP request extra data (includes _meta for session extraction) */
     extra?: {
         _meta?: Record<string, unknown>;
     };
+    /** Session-scoped WaniWani client — available when the server is wrapped with withWaniwani() */
+    waniwani?: ScopedWaniWaniClient;
 };
 type ToolConfig<TInput extends ZodRawShapeCompat> = {
     /** The resource (HTML template) this tool renders. When present, tool returns structuredContent + widget _meta. */
@@ -498,6 +712,8 @@ type NodeContext<TState> = {
     interrupt: TypedInterrupt<TState>;
     /** Create a widget signal — pause and show a UI widget */
     showWidget: TypedShowWidget<TState>;
+    /** Session-scoped WaniWani client — available when the server is wrapped with withWaniwani() */
+    waniwani?: ScopedWaniWaniClient;
 };
 /**
  * Node handler — receives a context object and returns a signal or state updates.
@@ -585,10 +801,7 @@ type InterruptQuestionData = {
     suggestions?: string[];
     context?: string;
 };
-type FlowContentBase = {
-    flowToken?: string;
-};
-type FlowInterruptContent = FlowContentBase & {
+type FlowInterruptContent = {
     status: "interrupt";
     /** Single-question shorthand */
     question?: string;
@@ -598,7 +811,7 @@ type FlowInterruptContent = FlowContentBase & {
     questions?: InterruptQuestionData[];
     context?: string;
 };
-type FlowWidgetContent = FlowContentBase & {
+type FlowWidgetContent = {
     status: "widget";
     /** Display tool to call */
     tool: string;
@@ -608,10 +821,10 @@ type FlowWidgetContent = FlowContentBase & {
     /** Whether the widget expects user interaction before continuing */
     interactive?: boolean;
 };
-type FlowCompleteContent = FlowContentBase & {
+type FlowCompleteContent = {
     status: "complete";
 };
-type FlowErrorContent = FlowContentBase & {
+type FlowErrorContent = {
     status: "error";
     error: string;
 };
@@ -701,22 +914,6 @@ declare function createFlow<const TSchema extends Record<string, z.ZodType>>(con
     state: TSchema;
 }): StateGraph<InferFlowState<TSchema>>;
 
-/**
- * Opaque compressed token for flow state round-tripping.
- *
- * Flow state is compressed (zlib deflate) then base64-encoded. This produces
- * a token that:
- * 1. Looks like random noise — models can't mentally decode it
- * 2. Is smaller than raw base64 (~30% compression on typical state)
- * 3. The model treats it as an opaque string and passes it back unchanged
- *
- * Only encoded/decoded on the server (Node.js). Browser code should never
- * need to decode flow tokens.
- */
-
-declare function encodeFlowToken(data: FlowTokenContent): string;
-declare function decodeFlowToken(token: string): FlowTokenContent | null;
-
 type WithDecodedState = {
     decodedState: FlowTokenContent | null;
 };
@@ -814,215 +1011,6 @@ interface TrackingRouteOptions {
  */
 declare function createTrackingRoute(options?: TrackingRouteOptions): (request: Request) => Promise<Response>;
 
-interface SearchResult {
-    source: string;
-    heading: string;
-    content: string;
-    score: number;
-}
-/** A file to ingest into the knowledge base */
-interface KbIngestFile {
-    /** Filename (used as chunk source identifier) */
-    filename: string;
-    /** Markdown content of the file */
-    content: string;
-}
-/** Response from the ingest endpoint */
-interface KbIngestResult {
-    /** Number of chunks created from the ingested files */
-    chunksIngested: number;
-    /** Number of files successfully processed */
-    filesProcessed: number;
-}
-/** Options for the search method */
-interface KbSearchOptions {
-    /** Number of results to return (1-20, default 5) */
-    topK?: number;
-    /** Minimum similarity score threshold (0-1, default 0.3) */
-    minScore?: number;
-}
-/** A source entry in the knowledge base */
-interface KbSource {
-    /** Source filename */
-    source: string;
-    /** Number of chunks from this source */
-    chunkCount: number;
-    /** ISO timestamp of when the source was first ingested */
-    createdAt: string;
-}
-/** KB client for server-side knowledge base operations */
-interface KbClient {
-    /**
-     * Ingest files into the knowledge base.
-     *
-     * **Warning**: This is destructive — it deletes ALL existing chunks
-     * for the environment before ingesting the new files.
-     */
-    ingest(files: KbIngestFile[]): Promise<KbIngestResult>;
-    /** Search the knowledge base for relevant chunks */
-    search(query: string, options?: KbSearchOptions): Promise<SearchResult[]>;
-    /** List all sources in the knowledge base */
-    sources(): Promise<KbSource[]>;
-}
-
-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" | "user.identified";
-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) | ({
-    event: "user.identified";
-} & 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 {
-    /**
-     * Send a one-shot identify event for a user.
-     * userId can be any string: an email, an internal ID, etc.
-     */
-    identify: (userId: string, properties?: Record<string, unknown>) => Promise<{
-        eventId: string;
-    }>;
-    /**
-     * 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
  *
@@ -1044,21 +1032,18 @@ interface InternalConfig {
     tracking: Required<TrackingConfig>;
 }
 
-type WaniwaniTracker = Pick<WaniWaniClient, "flush" | "track" | "_config">;
+type WaniwaniTracker = Pick<WaniWaniClient, "flush" | "track" | "identify" | "kb" | "_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.
+     * The WaniWani client instance. All tracking calls made through this client
+     * during tool execution will automatically include session metadata.
      */
-    config?: WaniWaniConfig;
+    client: WaniwaniTracker;
     /**
      * Optional explicit tool type. Defaults to `"other"`.
      */
@@ -1096,6 +1081,6 @@ type WithWaniwaniOptions = {
  * 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;
+declare function withWaniwani(server: McpServer, options: WithWaniwaniOptions): McpServer;
 
-export { type ConditionFn, END, type FlowConfig, type FlowTestResult, type HostContext, type InferFlowState, type InterruptSignal, type NodeContext, 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 TypedInterrupt, type TypedShowWidget, type UnifiedWidgetClient, type WidgetCSP, type WidgetPlatform, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createResource, createTool, createTrackingRoute, decodeFlowToken, detectPlatform, encodeFlowToken, isMCPApps, isOpenAI, registerTools, withWaniwani };
+export { type ConditionFn, END, type FlowConfig, type FlowTestResult, type HostContext, type InferFlowState, type InterruptSignal, type NodeContext, type NodeHandler, type RegisteredFlow, type RegisteredResource, type RegisteredTool, type ResourceConfig, START, type ScopedWaniWaniClient, StateGraph, type ToolCallResult, type ToolConfig, type ToolHandler, type ToolHandlerContext, type ToolResult, type ToolToolCallback, type TrackingRouteOptions, type TypedInterrupt, type TypedShowWidget, type UnifiedWidgetClient, type WidgetCSP, type WidgetPlatform, type WidgetSignal, type WithWaniwaniOptions, createFlow, createFlowTestHarness, createResource, createTool, createTrackingRoute, detectPlatform, isMCPApps, isOpenAI, registerTools, withWaniwani };