/**
 * SurveyAgent - A prefab agent that conducts surveys with branching logic,
 * scoring, and conditional question flow.
 *
 * Ported from the Python SDK `signalwire.prefabs.survey.SurveyAgent`. Keeps
 * TS-specific enhancements (per-call session state, branching via
 * `nextQuestion`, answer scoring via `points`) alongside the Python surface.
 */
import { AgentBase } from '../AgentBase.js';
import type { AgentOptions } from '../types.js';
/** A single survey question consumed by {@link SurveyAgent}. */
export interface SurveyQuestion {
    /** Unique question identifier. */
    id: string;
    /** The question text to ask the caller. */
    text: string;
    /** Question type determines validation and display. */
    type: 'multiple_choice' | 'open_ended' | 'rating' | 'yes_no';
    /** Options for multiple_choice questions. */
    options?: string[];
    /**
     * For `rating` questions, the upper bound of the scale (1..scale).
     * Defaults to 5 (matching the Python prefab) when unspecified.
     */
    scale?: number;
    /**
     * Whether the question requires an answer. Defaults to `true`.
     * Mirrors the Python `required` flag on each question dict.
     */
    required?: boolean;
    /**
     * Next question ID after this one.
     * - string: always go to that question
     * - Record<string, string>: map from answer value to next question ID
     * - undefined: proceed to next question in array order
     */
    nextQuestion?: string | Record<string, string>;
    /**
     * Points awarded for answers.
     * - number: fixed points for any answer
     * - Record<string, number>: points per specific answer value
     */
    points?: number | Record<string, number>;
}
/** Configuration for the {@link SurveyAgent}. */
export interface SurveyConfig {
    /** Human-readable survey name, used in prompts and global data. */
    surveyName: string;
    /** Ordered list of survey questions. */
    questions: SurveyQuestion[];
    /** Opening message before the first question (matches Python `introduction`). */
    introduction?: string;
    /** Message after the survey is complete (matches Python `conclusion`). */
    conclusion?: string;
    /** Brand or company name the agent represents (matches Python `brand_name`). */
    brandName?: string;
    /** Maximum number of times to retry invalid answers. Defaults to 2. */
    maxRetries?: number;
    /** Agent display name (defaults to `"survey"`). */
    name?: string;
    /** HTTP route for this agent (defaults to `"/survey"`). */
    route?: string;
    /** Callback fired when the survey is finished. */
    onComplete?: (responses: Record<string, unknown>, score: number) => void | Promise<void>;
    /** Additional AgentBase options forwarded to super(). */
    agentOptions?: Partial<AgentOptions>;
}
/**
 * Prefab agent that conducts surveys with branching logic, answer scoring, and conditional question flow.
 *
 * Each survey question declares its response type (rating, yes/no, open text, etc.), an optional
 * set of conditional follow-ups, and a scoring map. The agent walks the question tree, tallies a
 * total score, and exposes the full response map at call end via `onSummary()`.
 *
 * @example Customer satisfaction survey
 * ```ts
 * import { SurveyAgent } from '@signalwire/sdk';
 *
 * const agent = new SurveyAgent({
 *   surveyName: 'CSAT',
 *   brandName: 'Acme Co',
 *   questions: [
 *     { id: 'q1', text: 'How satisfied were you with our service?', type: 'rating', scale: 5 },
 *     { id: 'q2', text: 'Would you recommend us to a friend?', type: 'yesno' },
 *     { id: 'q3', text: 'Anything else you want to share?', type: 'open' },
 *   ],
 * });
 *
 * await agent.serve({ port: 3000 });
 * ```
 */
export declare class SurveyAgent extends AgentBase {
    /** Human-readable survey name. */
    surveyName: string;
    /** The configured survey questions (public, matching Python). */
    questions: SurveyQuestion[];
    /** Brand/company name used in prompts. */
    brandName: string;
    /** Maximum number of times to retry invalid answers. */
    maxRetries: number;
    /** Opening message before the first question. */
    introduction: string;
    /** Closing message shown when the survey completes. */
    conclusion: string;
    private questionMap;
    private onCompleteCallback?;
    private sessions;
    /**
     * Create a SurveyAgent with the specified questions and callbacks.
     * @param config - Configuration including questions, messages, and completion callback.
     */
    constructor(config: SurveyConfig);
    private validateQuestions;
    private setupSurveyAgent;
    private getSession;
    private resolveNextQuestion;
    private calculatePoints;
    /**
     * Validate an answer against the question's type and constraints.
     * Mirrors the Python `validate_response` tool body.
     * @returns error message string if invalid, or `null` if valid.
     */
    private validateAnswer;
    private normalizeAnswer;
    /**
     * Register SWAIG tools:
     *   - Python-parity tools: `validate_response`, `log_response`
     *   - TS-specific session tools: `answer_question`, `get_current_question`, `get_survey_progress`
     */
    protected defineTools(): void;
    /**
     * Process the survey results summary returned at the end of a call.
     * Mirrors Python `on_summary`: structured (dict-like) summaries are logged
     * as JSON; unstructured summaries are logged verbatim.
     *
     * The parameter type widens the base `AgentBase.onSummary` signature to
     * accept string payloads as well, matching Python's `isinstance(summary, dict)`
     * branch even though the current framework only surfaces object summaries.
     */
    onSummary(summary: Record<string, unknown> | string | null, _rawData: Record<string, unknown>): void | Promise<void>;
}
/**
 * Factory function that creates and returns a new SurveyAgent.
 * @param config - Configuration for the survey agent.
 * @returns A configured SurveyAgent instance.
 */
export declare function createSurveyAgent(config: SurveyConfig): SurveyAgent;
export default SurveyAgent;