@firststep-studio/sdk 0.1.0

package/dist/server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts","../src/auth.ts"],"sourcesContent":["/**\n * FirstStep SDK Server\n *\n * Standalone HTTP server for protocol handlers.\n * Zero external dependencies, uses Node.js built-in `http` module.\n *\n * @example\n * ```typescript\n * import { createServer } from '@firststep-studio/sdk/server';\n * import type { ProtocolHandler } from '@firststep-studio/sdk';\n *\n * const handler: ProtocolHandler = {\n *   async handleMessage(request, context) {\n *     return {\n *       message: 'Hello from my handler!',\n *       sessionId: request.sessionId || 'new',\n *       agentId: 'main',\n *       sessionStatus: 'active',\n *     };\n *   },\n *   getCapabilities() {\n *     return { streaming: false, formQuestions: false, knowledgeActions: false, integrations: false };\n *   },\n * };\n *\n * const server = createServer(handler, {\n *   token: process.env.FIRSTSTEP_TOKEN!,\n *   port: 3001,\n * });\n *\n * server.start();\n * ```\n */\n\nimport { createServer as createHttpServer, IncomingMessage, ServerResponse } from 'http';\nimport type {\n  ProtocolHandler,\n  ProtocolRequest,\n  ProtocolContext,\n  ProtocolCapabilities,\n  ProtocolStreamChunk,\n} from './types';\nimport { verifyRequestSignature } from './auth';\n\n// ============================================\n// Configuration\n// ============================================\n\nexport interface ServerConfig {\n  /** API token (FIRSTSTEP_TOKEN). Used for request signature verification. */\n  token: string;\n\n  /** Port to listen on. Defaults to 3001, or the PORT env variable. */\n  port?: number;\n\n  /** Host to bind to. Defaults to '0.0.0.0'. */\n  host?: string;\n\n  /** Skip signature verification (for local development only). */\n  skipSignatureVerification?: boolean;\n}\n\n// ============================================\n// Server Instance\n// ============================================\n\nexport interface FirstStepServer {\n  /** Start the server */\n  start(): Promise<void>;\n\n  /** Stop the server gracefully */\n  stop(): Promise<void>;\n\n  /**\n   * Get the request handler function.\n   * Use this to integrate with Express, Fastify, or other frameworks.\n   *\n   * @example\n   * ```typescript\n   * // Express\n   * const server = createServer(handler, { token: '...' });\n   * app.post('/handshake', server.getRequestHandler());\n   * app.post('/message', server.getRequestHandler());\n   * ```\n   */\n  getRequestHandler(): (req: IncomingMessage, res: ServerResponse) => void;\n}\n\n// ============================================\n// Internal Helpers\n// ============================================\n\nfunction readBody(req: IncomingMessage): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const chunks: Buffer[] = [];\n    req.on('data', (chunk: Buffer) => chunks.push(chunk));\n    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));\n    req.on('error', reject);\n  });\n}\n\nfunction sendJson(res: ServerResponse, status: number, body: unknown): void {\n  const json = JSON.stringify(body);\n  res.writeHead(status, {\n    'Content-Type': 'application/json',\n    'Content-Length': Buffer.byteLength(json),\n    'Access-Control-Allow-Origin': '*',\n  });\n  res.end(json);\n}\n\nfunction parsePath(url: string | undefined): string {\n  if (!url) return '/';\n  const idx = url.indexOf('?');\n  return idx >= 0 ? url.substring(0, idx) : url;\n}\n\n/**\n * Build a stub ProtocolContext for external handlers.\n *\n * External handlers receive context data as plain JSON from the platform.\n * The stub provides no-op implementations for methods like session.getState()\n * since those will be handled by callback APIs to the FirstStep backend.\n *\n * When the platform sends a /message request, the request body includes\n * a `context` field with serialized context data. This function merges\n * that data with no-op method stubs.\n */\nfunction buildStubContext(data?: Partial<ProtocolContext>): ProtocolContext {\n  const noopAsync = async () => ({} as any);\n  const noop = () => {};\n\n  return {\n    session: {\n      sessionId: '',\n      getState: noopAsync,\n      updateState: noopAsync,\n      getHistory: async () => [],\n      saveMessage: noopAsync,\n      complete: noopAsync,\n      getFormData: async () => ({}),\n      updateFormField: noopAsync,\n      updateFormData: noopAsync,\n      ...data?.session,\n    },\n    knowledge: {\n      queryDatabase: noopAsync,\n      searchPages: noopAsync,\n      ...data?.knowledge,\n    },\n    integrations: {\n      execute: noopAsync,\n      ...data?.integrations,\n    },\n    analytics: {\n      logActionExecuted: noop,\n      logInteraction: noop,\n      logCustomEvent: noop,\n      ...data?.analytics,\n    },\n    logger: {\n      debug: noop,\n      info: noop,\n      warn: noop,\n      error: noop,\n      logRouting: noop,\n      logToolUse: noop,\n      ...data?.logger,\n    },\n    deployment: {\n      id: '',\n      slug: '',\n      name: '',\n      protocolType: 'external',\n      ...data?.deployment,\n    },\n    chatbot: data?.chatbot,\n  };\n}\n\n// ============================================\n// createServer\n// ============================================\n\n/**\n * Create a standalone HTTP server for a protocol handler.\n *\n * The server exposes three endpoints:\n * - `GET  /health`    - Health check (always 200)\n * - `POST /handshake` - Returns handler capabilities (signature verified)\n * - `POST /message`   - Handles a chat message (signature verified)\n */\nexport function createServer(\n  handler: ProtocolHandler,\n  config: ServerConfig\n): FirstStepServer {\n  const {\n    token,\n    port = parseInt(process.env.PORT || '3001', 10),\n    host = '0.0.0.0',\n    skipSignatureVerification = false,\n  } = config;\n\n  // Validate config\n  if (!token && !skipSignatureVerification) {\n    throw new Error(\n      'FIRSTSTEP_TOKEN is required. Pass it via config.token or set skipSignatureVerification for local dev.'\n    );\n  }\n\n  /**\n   * Core request router\n   */\n  async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {\n    const path = parsePath(req.url);\n    const method = (req.method || 'GET').toUpperCase();\n\n    // CORS preflight\n    if (method === 'OPTIONS') {\n      res.writeHead(204, {\n        'Access-Control-Allow-Origin': '*',\n        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',\n        'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-FirstStep-Signature',\n        'Access-Control-Max-Age': '86400',\n      });\n      res.end();\n      return;\n    }\n\n    // Health check\n    if (path === '/health' && method === 'GET') {\n      sendJson(res, 200, { status: 'ok', timestamp: Date.now() });\n      return;\n    }\n\n    // Handshake\n    if (path === '/handshake' && method === 'POST') {\n      const body = await readBody(req);\n\n      if (!skipSignatureVerification) {\n        const signature = req.headers['x-firststep-signature'] as string;\n        if (!signature || !verifyRequestSignature(token, body, signature)) {\n          sendJson(res, 401, { error: 'Invalid signature' });\n          return;\n        }\n      }\n\n      const capabilities: ProtocolCapabilities = handler.getCapabilities();\n      const handlerInfo = handler.getHandlerInfo?.();\n      sendJson(res, 200, { capabilities, handler: handlerInfo || undefined });\n      return;\n    }\n\n    // Message\n    if (path === '/message' && method === 'POST') {\n      const body = await readBody(req);\n\n      if (!skipSignatureVerification) {\n        const signature = req.headers['x-firststep-signature'] as string;\n        if (!signature || !verifyRequestSignature(token, body, signature)) {\n          sendJson(res, 401, { error: 'Invalid signature' });\n          return;\n        }\n      }\n\n      let parsed: { request: ProtocolRequest; context?: Partial<ProtocolContext> };\n      try {\n        parsed = JSON.parse(body);\n      } catch {\n        sendJson(res, 400, { error: 'Invalid JSON body' });\n        return;\n      }\n\n      const context = buildStubContext(parsed.context);\n\n      try {\n        const response = await handler.handleMessage(parsed.request, context);\n        sendJson(res, 200, response);\n      } catch (err: any) {\n        console.error('[firststep] Handler error:', err);\n        sendJson(res, 500, {\n          error: 'Handler error',\n          message: err?.message || 'Unknown error',\n        });\n      }\n      return;\n    }\n\n    // Message (streaming via SSE)\n    if (path === '/message/stream' && method === 'POST') {\n      const body = await readBody(req);\n\n      if (!skipSignatureVerification) {\n        const signature = req.headers['x-firststep-signature'] as string;\n        if (!signature || !verifyRequestSignature(token, body, signature)) {\n          sendJson(res, 401, { error: 'Invalid signature' });\n          return;\n        }\n      }\n\n      let parsed: { request: ProtocolRequest; context?: Partial<ProtocolContext> };\n      try {\n        parsed = JSON.parse(body);\n      } catch {\n        sendJson(res, 400, { error: 'Invalid JSON body' });\n        return;\n      }\n\n      if (!handler.handleStream) {\n        // Fallback: use non-streaming handleMessage, send as single SSE burst\n        const context = buildStubContext(parsed.context);\n        try {\n          const response = await handler.handleMessage(parsed.request, context);\n          res.writeHead(200, {\n            'Content-Type': 'text/event-stream',\n            'Cache-Control': 'no-cache',\n            'Connection': 'keep-alive',\n            'Access-Control-Allow-Origin': '*',\n          });\n          const sendSSE = (event: string, data: unknown) => {\n            res.write(`event: ${event}\\ndata: ${JSON.stringify(data)}\\n\\n`);\n          };\n          sendSSE('connected', { sessionId: response.sessionId });\n          sendSSE('text', { type: 'text', content: response.message, sessionId: response.sessionId });\n          if (response.metadata) {\n            sendSSE('metadata', { type: 'metadata', content: response.metadata, sessionId: response.sessionId });\n          }\n          if (response.form) {\n            sendSSE('form', { type: 'form', content: response.form, sessionId: response.sessionId });\n          }\n          sendSSE('status', { type: 'status', content: response.sessionStatus, sessionId: response.sessionId });\n          sendSSE('done', { sessionId: response.sessionId });\n          res.end();\n        } catch (err: any) {\n          console.error('[firststep] Handler error:', err);\n          sendJson(res, 500, { error: 'Handler error', message: err?.message || 'Unknown error' });\n        }\n        return;\n      }\n\n      const context = buildStubContext(parsed.context);\n\n      res.writeHead(200, {\n        'Content-Type': 'text/event-stream',\n        'Cache-Control': 'no-cache',\n        'Connection': 'keep-alive',\n        'Access-Control-Allow-Origin': '*',\n      });\n\n      const sendSSE = (event: string, data: unknown) => {\n        res.write(`event: ${event}\\ndata: ${JSON.stringify(data)}\\n\\n`);\n      };\n\n      const sessionId = parsed.request.sessionId || `ext-${Date.now()}`;\n      sendSSE('connected', { sessionId });\n\n      try {\n        for await (const chunk of handler.handleStream(parsed.request, context)) {\n          sendSSE(chunk.type, {\n            type: chunk.type,\n            content: chunk.content,\n            sessionId,\n          });\n        }\n        sendSSE('done', { sessionId });\n      } catch (err: any) {\n        console.error('[firststep] Stream error:', err);\n        sendSSE('error', { code: 'STREAM_ERROR', message: err?.message || 'Unknown error' });\n      }\n\n      res.end();\n      return;\n    }\n\n    // 404\n    sendJson(res, 404, { error: 'Not found' });\n  }\n\n  // Wrap in error boundary\n  function requestListener(req: IncomingMessage, res: ServerResponse): void {\n    handleRequest(req, res).catch((err) => {\n      console.error('[firststep] Unexpected error:', err);\n      if (!res.headersSent) {\n        sendJson(res, 500, { error: 'Internal server error' });\n      }\n    });\n  }\n\n  const httpServer = createHttpServer(requestListener);\n\n  return {\n    start() {\n      return new Promise<void>((resolve) => {\n        httpServer.listen(port, host, () => {\n          console.log(`[firststep] Handler server listening on ${host}:${port}`);\n          console.log(`[firststep] Endpoints:`);\n          console.log(`  GET  /health         - Health check`);\n          console.log(`  POST /handshake      - Capability exchange`);\n          console.log(`  POST /message        - Handle chat message`);\n          console.log(`  POST /message/stream - Handle chat message (SSE stream)`);\n          resolve();\n        });\n      });\n    },\n\n    stop() {\n      return new Promise<void>((resolve, reject) => {\n        httpServer.close((err) => {\n          if (err) reject(err);\n          else resolve();\n        });\n      });\n    },\n\n    getRequestHandler() {\n      return requestListener;\n    },\n  };\n}\n","import { createHmac, timingSafeEqual } from 'crypto';\n\nconst TOKEN_PREFIX = 'fst_';\nconst TOKEN_LENGTH = 44; // fst_ (4) + 40 hex chars\n\n/**\n * Verify an HMAC-SHA256 request signature.\n *\n * The handler server can use this to verify that incoming webhook\n * requests were signed by the FirstStep platform using the shared token.\n *\n * @param token - The API token (FIRSTSTEP_TOKEN)\n * @param payload - The raw request body string\n * @param signature - The signature from the X-FirstStep-Signature header\n * @returns true if the signature is valid\n *\n * @example\n * ```typescript\n * import { verifyRequestSignature } from '@firststep-studio/sdk';\n *\n * app.post('/webhook', (req, res) => {\n *   const signature = req.headers['x-firststep-signature'] as string;\n *   if (!verifyRequestSignature(process.env.FIRSTSTEP_TOKEN!, req.body, signature)) {\n *     return res.status(401).send('Invalid signature');\n *   }\n *   // Process the request...\n * });\n * ```\n */\nexport function verifyRequestSignature(\n  token: string,\n  payload: string,\n  signature: string\n): boolean {\n  try {\n    const expected = createHmac('sha256', token)\n      .update(payload)\n      .digest('hex');\n    const expectedBuffer = Buffer.from(expected, 'hex');\n    const signatureBuffer = Buffer.from(signature, 'hex');\n\n    if (expectedBuffer.length !== signatureBuffer.length) {\n      return false;\n    }\n\n    return timingSafeEqual(expectedBuffer, signatureBuffer);\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Create an HMAC-SHA256 signature for a payload.\n *\n * Used by the platform to sign outgoing requests to handler servers.\n *\n * @param token - The API token\n * @param payload - The request body string to sign\n * @returns The hex-encoded HMAC signature\n */\nexport function createRequestSignature(\n  token: string,\n  payload: string\n): string {\n  return createHmac('sha256', token).update(payload).digest('hex');\n}\n\n/**\n * Create an Authorization header value for API requests.\n *\n * @param token - The API token (fst_xxx)\n * @returns The header value, e.g. \"Bearer fst_xxx\"\n *\n * @example\n * ```typescript\n * import { createAuthHeader } from '@firststep-studio/sdk';\n *\n * const response = await fetch('https://api.firststep.ai/api/projects', {\n *   headers: {\n *     'Authorization': createAuthHeader(process.env.FIRSTSTEP_TOKEN!),\n *   },\n * });\n * ```\n */\nexport function createAuthHeader(token: string): string {\n  return `Bearer ${token}`;\n}\n\n/**\n * Validate that a token has the correct format (fst_ prefix + 40 hex chars).\n *\n * @param token - The token string to validate\n * @returns true if the token matches the expected format\n */\nexport function isValidToken(token: string): boolean {\n  return (\n    typeof token === 'string' &&\n    token.startsWith(TOKEN_PREFIX) &&\n    token.length === TOKEN_LENGTH\n  );\n}\n"],"mappings":"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","names":["context","sendSSE"]}

package/dist/types-Bm98aHcd.d.mts

@@ -0,0 +1,438 @@
+/**
+ * FirstStep Protocol SDK Types
+ *
+ * Implement this interface to communicate with FirstStep Studio.
+ * GuidedForm is the built-in implementation of this interface.
+ */
+interface ProtocolRequest {
+    /**
+     * User message.
+     * Optional - if not provided, this is a session initialization request
+     * and the handler should return the initial message (welcome/form).
+     */
+    message?: string;
+    /** Session ID (new session created if not provided) */
+    sessionId?: string;
+    /** Deployment slug */
+    deploymentSlug: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface ProtocolResponse {
+    /** AI response message */
+    message: string;
+    /** Session ID */
+    sessionId: string;
+    /** Current agent ID */
+    agentId: string;
+    /** Session status */
+    sessionStatus: SessionStatus;
+    /** Form rendering info (optional) */
+    form?: ProtocolForm;
+    /** Response metadata */
+    metadata?: Record<string, unknown>;
+}
+type SessionStatus = 'active' | 'completed' | 'error';
+interface ProtocolForm {
+    /** Form type */
+    type: 'question' | 'closing' | 'custom';
+    /** Question ID */
+    questionId?: string;
+    /** Form fields */
+    fields: ProtocolFormField[];
+    /** Form metadata */
+    metadata?: Record<string, unknown>;
+}
+interface ProtocolFormField {
+    /** Field ID */
+    id: string;
+    /** Field type */
+    type: 'text' | 'textarea' | 'select' | 'multiselect' | 'date' | 'number' | 'email' | 'phone';
+    /** Display label */
+    label: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Options for select/multiselect */
+    options?: ProtocolFormOption[];
+    /** Required flag */
+    required?: boolean;
+    /** Validation rules */
+    validation?: ProtocolFieldValidation;
+}
+interface ProtocolFormOption {
+    value: string;
+    label: string;
+}
+interface ProtocolFieldValidation {
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    message?: string;
+}
+interface ProtocolStreamChunk {
+    /** Chunk type */
+    type: 'text' | 'form' | 'status' | 'error' | 'metadata';
+    /** Chunk content */
+    content: string | ProtocolForm | SessionStatus | ProtocolError | Record<string, unknown>;
+}
+interface ProtocolError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Protocol Handler Interface
+ *
+ * Implement this interface to work as a FirstStep Studio Protocol.
+ * GuidedForm is the built-in implementation of this interface.
+ */
+interface ProtocolHandler {
+    /**
+     * Handle message (non-streaming)
+     */
+    handleMessage(request: ProtocolRequest, context: ProtocolContext): Promise<ProtocolResponse>;
+    /**
+     * Handle message (streaming)
+     */
+    handleStream?(request: ProtocolRequest, context: ProtocolContext): AsyncGenerator<ProtocolStreamChunk>;
+    /**
+     * Declare handler capabilities
+     */
+    getCapabilities(): ProtocolCapabilities;
+    /**
+     * Handler metadata returned during handshake.
+     * Used to auto-fill project name and description on registration.
+     */
+    getHandlerInfo?(): HandlerInfo;
+}
+interface HandlerInfo {
+    /** Handler display name */
+    name: string;
+    /** Handler description */
+    description?: string;
+}
+interface ProtocolCapabilities {
+    /** Streaming support */
+    streaming: boolean;
+    /** Form questions support */
+    formQuestions: boolean;
+    /** Knowledge actions usage */
+    knowledgeActions: boolean;
+    /** Integrations usage */
+    integrations: boolean;
+    /** Custom capabilities */
+    custom?: Record<string, boolean>;
+}
+/**
+ * Platform Context
+ *
+ * Interface for handlers to access FirstStep Studio features:
+ * - Session management
+ * - Knowledge base queries
+ * - Integration calls
+ * - Analytics tracking
+ * - Logging
+ */
+interface ProtocolContext {
+    /** Session management */
+    session: SessionContext;
+    /** Knowledge base access */
+    knowledge: KnowledgeContext;
+    /** Integration access */
+    integrations: IntegrationContext;
+    /** Analytics tracking */
+    analytics: AnalyticsContext;
+    /** Logging */
+    logger: LoggerContext;
+    /** Deployment info */
+    deployment: DeploymentInfo;
+    /** Chatbot info (for GuidedForm) */
+    chatbot?: ChatbotInfo;
+}
+interface SessionContext {
+    /** Session ID */
+    sessionId: string;
+    /** Get session state */
+    getState(): Promise<SessionState>;
+    /** Update session state */
+    updateState(updates: Partial<SessionState>): Promise<void>;
+    /** Get message history */
+    getHistory(): Promise<ChatMessage[]>;
+    /** Save message */
+    saveMessage(message: ChatMessage): Promise<void>;
+    /** Complete session */
+    complete(): Promise<void>;
+    /** Get all collected form data */
+    getFormData(): Promise<FormData>;
+    /** Update a single form field */
+    updateFormField(fieldId: string, value: FormFieldValue): Promise<void>;
+    /** Update multiple form fields */
+    updateFormData(fields: Record<string, FormFieldValue>): Promise<void>;
+}
+interface SessionState {
+    sessionId: string;
+    deploymentId: string;
+    currentAgentId?: string;
+    /** Current question being asked (for proper answer tracking) */
+    currentQuestionId?: string;
+    /** Internal form data storage (handler-specific format) */
+    formData?: Record<string, unknown>;
+    metadata?: SessionMetadata;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    agentId?: string;
+    timestamp?: Date;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * FormData - Collected user responses
+ *
+ * Standard format for all protocol handlers.
+ * Used for KPI calculation and session analytics.
+ */
+interface FormData {
+    [fieldId: string]: FormFieldValue;
+}
+interface FormFieldValue {
+    /** The collected value */
+    value: string | string[] | number | boolean | null;
+    /** When this field was answered */
+    answeredAt?: Date;
+    /** Which agent collected this (for GuidedForm) */
+    agentId?: string;
+    /** Raw user response before processing */
+    rawResponse?: string;
+}
+/**
+ * RoutingLog - Record of routing decisions
+ *
+ * Stored automatically when context.logger.logRouting() is called.
+ */
+interface RoutingLog {
+    /** When the routing decision was made */
+    timestamp: Date;
+    /** Decision type (e.g., 'FIRST_MESSAGE', 'CLASSIFIER_ROUTING') */
+    decision: string;
+    /** Human-readable reason */
+    reason: string;
+    /** Source agent */
+    fromAgent?: string;
+    /** Target agent */
+    toAgent: string;
+    /** Classification result if applicable */
+    classification?: {
+        category?: string;
+        level?: string;
+        confidence?: number;
+    };
+}
+/**
+ * SessionMetadata - Session-level analytics data
+ *
+ * Automatically tracked by the platform.
+ */
+interface SessionMetadata {
+    turnCount?: number;
+    totalMessages?: number;
+    userMessageCount?: number;
+    durationSeconds?: number;
+    startedAt?: Date;
+    endedAt?: Date;
+    lastActivityAt?: Date;
+    userAgent?: string;
+    ipAddress?: string;
+    referrer?: string;
+    source?: string;
+    language?: string;
+    timezone?: string;
+    knowledgeActionExecuted?: boolean;
+    helplineActionExecuted?: boolean;
+    executedKnowledgeIds?: string[];
+    helplineSmsClicked?: string;
+    helplineCallClicked?: string;
+    helplineWebsiteClicked?: string;
+    knowledgeLinkClicked?: string;
+    announcementCtaClicked?: boolean;
+    zendeskTicketId?: string;
+    zendeskTicketUrl?: string;
+    completed?: boolean;
+    completedAt?: string;
+    custom?: Record<string, unknown>;
+}
+interface KnowledgeContext {
+    /** Query database knowledge */
+    queryDatabase(knowledgeId: string, query: string): Promise<KnowledgeResult>;
+    /** Search page knowledge */
+    searchPages(knowledgeId: string, query: string): Promise<KnowledgeResult>;
+}
+interface KnowledgeResult {
+    success: boolean;
+    records?: Record<string, unknown>[];
+    error?: string;
+}
+interface IntegrationContext {
+    /** Execute integration */
+    execute(integrationId: string, params: Record<string, unknown>): Promise<IntegrationResult>;
+    /** Search helplines (Throughline) */
+    searchHelplines?(query: string, options?: HelplineSearchOptions): Promise<HelplineResult>;
+}
+interface IntegrationResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+}
+interface HelplineSearchOptions {
+    country?: string;
+    topics?: string[];
+    limit?: number;
+}
+interface HelplineResult {
+    success: boolean;
+    helplines?: Helpline[];
+    error?: string;
+}
+interface Helpline {
+    name: string;
+    phone?: string;
+    website?: string;
+    description?: string;
+}
+interface LoggerContext {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    /** Log routing decision */
+    logRouting(decision: RoutingDecision): void;
+    /** Log tool usage */
+    logToolUse(tool: string, params: Record<string, unknown>, result: unknown): void;
+}
+interface RoutingDecision {
+    decision: string;
+    reason: string;
+    fromAgent?: string;
+    toAgent: string;
+    timestamp: Date;
+}
+/**
+ * Analytics Context
+ *
+ * Track user interactions and action executions.
+ * Data is stored in SessionMetadata for KPI/reporting.
+ */
+interface AnalyticsContext {
+    /**
+     * Log action execution
+     * Tracks when knowledge, helpline, or integration actions are executed.
+     */
+    logActionExecuted(type: 'knowledge' | 'helpline' | 'integration', actionId: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log user interaction
+     * Tracks clicks on helplines, knowledge links, CTAs, etc.
+     */
+    logInteraction(event: InteractionEvent): void;
+    /**
+     * Log custom event
+     * For handler-specific analytics.
+     */
+    logCustomEvent(eventName: string, data?: Record<string, unknown>): void;
+}
+interface InteractionEvent {
+    /** Event type */
+    type: InteractionEventType;
+    /** Target identifier (e.g., helpline name, knowledge ID) */
+    targetId?: string;
+    /** Additional event data */
+    metadata?: Record<string, unknown>;
+    /** Event timestamp (auto-filled if not provided) */
+    timestamp?: Date;
+}
+type InteractionEventType = 'helpline_sms_click' | 'helpline_call_click' | 'helpline_website_click' | 'knowledge_link_click' | 'announcement_cta_click' | 'card_click' | 'form_submit' | 'custom';
+/**
+ * FormSchema - Defines what data a protocol handler collects
+ *
+ * Registered when a protocol is set up.
+ * Used for analytics, validation, and dashboard display.
+ */
+interface FormSchema {
+    /** Schema version for migrations */
+    version?: string;
+    /** Field definitions */
+    fields: FormFieldDefinition[];
+}
+interface FormFieldDefinition {
+    /** Unique field identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Field type */
+    type: FormFieldType;
+    /** Options for select/multiselect */
+    options?: string[];
+    /** Whether this field is required */
+    required?: boolean;
+    /** Which agent owns this field (for GuidedForm) */
+    agentId?: string;
+    /** Field description for documentation */
+    description?: string;
+    /** Display order */
+    order?: number;
+}
+type FormFieldType = 'text' | 'number' | 'date' | 'boolean' | 'select' | 'multiselect' | 'email' | 'phone' | 'url';
+/**
+ * Protocol Registration
+ *
+ * Configuration for registering a protocol handler.
+ */
+interface ProtocolRegistration {
+    /** Unique slug identifier */
+    slug: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** External handler endpoint URL (for external handlers) */
+    endpoint?: string;
+    /** Form schema - what data this handler collects */
+    formSchema?: FormSchema;
+    /** Handler capabilities */
+    capabilities?: ProtocolCapabilities;
+    /** Whether this is a built-in handler */
+    builtIn?: boolean;
+}
+interface DeploymentInfo {
+    id: string;
+    slug: string;
+    name: string;
+    protocolType: string;
+    metadata?: Record<string, unknown>;
+}
+interface ChatbotInfo {
+    id: string;
+    name: string;
+    /** GuidedForm only - full config including agents, questions, etc. */
+    config?: Record<string, unknown>;
+}
+/**
+ * Classifier configuration for protocol handlers
+ *
+ * Classifiers can be configured as:
+ * - Local: classifierId points to a classifier in the FirstStep database
+ * - Remote: classifierId is a full UCP endpoint URL
+ */
+interface ClassifierConfig {
+    /** Classifier ID or UCP endpoint URL */
+    classifierId: string;
+    /** API key for remote UCP endpoints (optional) */
+    apiKey?: string;
+    /** Whether classification is required for routing */
+    required?: boolean;
+}
+
+export type { AnalyticsContext as A, FormFieldType as B, ChatMessage as C, DeploymentInfo as D, ProtocolRegistration as E, FormData as F, HandlerInfo as H, IntegrationContext as I, KnowledgeContext as K, LoggerContext as L, ProtocolRequest as P, RoutingDecision as R, SessionStatus as S, ProtocolResponse as a, ProtocolForm as b, ProtocolFormField as c, ProtocolFormOption as d, ProtocolFieldValidation as e, ProtocolStreamChunk as f, ProtocolError as g, ProtocolHandler as h, ProtocolCapabilities as i, ProtocolContext as j, SessionContext as k, SessionState as l, KnowledgeResult as m, IntegrationResult as n, HelplineSearchOptions as o, HelplineResult as p, Helpline as q, ChatbotInfo as r, ClassifierConfig as s, FormFieldValue as t, RoutingLog as u, SessionMetadata as v, InteractionEvent as w, InteractionEventType as x, FormSchema as y, FormFieldDefinition as z };