@firststep-studio/sdk 0.1.0

package/dist/types-Bm98aHcd.d.ts

@@ -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 };