/**
 * SwmlBuilder - Builds SWML (SignalWire Markup Language) documents.
 *
 * Produces `{ version: "1.0.0", sections: { main: [...verbs] } }`.
 *
 * Verb methods (`.answer()`, `.hangup()`, `.play()`, etc.) are auto-installed
 * at construction from the bundled schema.json. All verb methods support
 * fluent chaining and call `addVerb()` internally.
 */
import { SchemaUtils } from './SchemaUtils.js';
import './SwmlVerbMethods.generated.js';
/** Options for constructing a SwmlBuilder. */
export interface SwmlBuilderOptions {
    /** An initial SWML document to seed the builder with, enabling document injection.
     *  When provided, the builder uses this document instead of creating an empty one.
     *  This mirrors the Python SDK's pattern of injecting an SWMLService instance. */
    initialDocument?: {
        version?: string;
        sections?: Record<string, unknown[]>;
    };
    /** When false, disables verb schema validation.
     *  Defaults to true unless `SWML_SKIP_SCHEMA_VALIDATION=true` is set in the environment. */
    enableValidation?: boolean;
    /** Optional path to a custom SWML schema JSON file. When set, the builder uses
     *  a per-instance SchemaUtils loaded from this path instead of the bundled schema.
     *  Mirrors Python's `schema_path` constructor parameter on `SWMLService`/`AgentBase`. */
    schemaPath?: string;
}
/**
 * Builds SWML documents composed of verb instructions organized into named sections.
 *
 * Verb methods (`.answer()`, `.play()`, `.hangup()`, `.transfer()`, etc.) are
 * auto-installed from the bundled SWML schema and all return `this` for fluent chaining.
 *
 * Most users don't instantiate `SwmlBuilder` directly — `AgentBase` uses it internally
 * and exposes higher-level helpers. Use this class directly for `SWMLService` (non-AI
 * call flows) or to hand-craft SWML returned from a route handler.
 *
 * @example Simple SWML document
 * ```ts
 * import { SwmlBuilder } from '@signalwire/sdk';
 *
 * const swml = new SwmlBuilder()
 *   .answer()
 *   .play({ url: 'https://cdn.example.com/greeting.mp3' })
 *   .hangup()
 *   .build();
 *
 * // swml is JSON ready to return from a SignalWire webhook.
 * ```
 *
 * @see {@link SWMLService} — HTTP service that serves a built SWML document
 * @see {@link AgentBase} — for AI-driven call flows
 */
export declare class SwmlBuilder {
    private _document;
    private static _schemaUtils;
    /** Per-instance SchemaUtils used when a custom `schemaPath` was supplied. */
    private _instanceSchemaUtils;
    private enableValidation;
    /**
     * Creates a new SwmlBuilder.
     * @param opts - Optional configuration.
     *   - `initialDocument`: inject an existing document (mirrors Python SDK's `SWMLService` injection pattern).
     *   - `enableValidation`: explicit override for verb schema validation (falls back to env var).
     *   - `schemaPath`: load SWML schema from a custom JSON file instead of the bundled one.
     */
    constructor(opts?: SwmlBuilderOptions);
    /** Returns the SchemaUtils for this builder — per-instance if a custom
     *  `schemaPath` was supplied, otherwise the shared singleton. */
    private getSchemaUtils;
    /**
     * Public read-only accessor for the underlying SWML document.
     * Provides direct access to the document, equivalent to the Python SDK's
     * `service` property on `SWMLBuilder`.
     */
    get document(): {
        version: string;
        sections: Record<string, unknown[]>;
    };
    /**
     * Enable or disable verb schema validation at runtime.
     * Matches the Python `schema_validation` constructor parameter on AgentBase.
     * @param enabled - True to enable validation, false to disable.
     */
    setValidation(enabled: boolean): void;
    private createEmpty;
    /**
     * Get or create the shared SchemaUtils singleton.
     * Exposed for use by the type generator and tests.
     */
    static getSchemaUtils(): SchemaUtils;
    /**
     * Install verb methods on this instance for every verb defined in the schema.
     * Uses a closure factory so each method captures the correct verb name.
     * Mirrors Python SDK's `_create_verb_methods()`.
     */
    private _installVerbMethods;
    /**
     * Resets the document to an empty SWML structure.
     * @returns this for fluent chaining.
     */
    reset(): this;
    /**
     * Appends a verb to the main section.
     * Validates the verb config against the schema when validation is enabled.
     * @param verbName - The SWML verb name (e.g., "answer", "ai").
     * @param config - The verb's configuration payload.
     */
    addVerb(verbName: string, config: unknown): void;
    /**
     * Appends a verb to a named section, creating the section if it does not exist.
     * @param sectionName - The target section name.
     * @param verbName - The SWML verb name.
     * @param config - The verb's configuration payload.
     */
    addVerbToSection(sectionName: string, verbName: string, config: unknown): void;
    /**
     * Add a 'play' verb with say: prefix for text-to-speech.
     * Convenience wrapper matching Python SDK's `say()` method.
     *
     * @param text - Text to speak.
     * @param opts - Optional TTS parameters (voice, language, gender, volume).
     * @returns this for fluent chaining.
     */
    say(text: string, opts?: {
        voice?: string;
        language?: string;
        gender?: string;
        volume?: number;
    }): this;
    /**
     * Creates a new empty named section in the document.
     * If the section already exists, this is a no-op.
     * Matches Python SDK's `add_section(section_name)`.
     *
     * @param sectionName - The name of the section to create.
     * @returns this for fluent chaining.
     */
    addSection(sectionName: string): this;
    /**
     * Returns the raw SWML document object.
     * @returns The document with version and sections.
     */
    getDocument(): Record<string, unknown>;
    /**
     * Alias for {@link getDocument}. Matches the Python SDK's `build()` method.
     * Build and return the SWML document as a dictionary/object.
     *
     * @returns The document with version and sections.
     */
    build(): Record<string, unknown>;
    /**
     * Serializes the SWML document to a JSON string.
     * @returns The JSON-encoded SWML document.
     */
    renderDocument(): string;
    /**
     * Alias for {@link renderDocument}. Matches the Python SDK's `render()` method.
     * Build and render the SWML document as a JSON string.
     *
     * @returns The JSON-encoded SWML document.
     */
    render(): string;
}