/**
 * DataMap - Fluent builder for SWAIG data_map configurations.
 *
 * Creates server-side tool definitions that execute on SignalWire
 * without requiring webhook endpoints.
 */
import { FunctionResult } from './FunctionResult.js';
/**
 * Set the global allowed env var prefixes for `${ENV.*}` expansion.
 *
 * Only environment variables whose names start with one of these prefixes
 * will be expanded. An empty array allows all variables (escape hatch).
 *
 * @param prefixes - Array of prefix strings to allow.
 */
export declare function setAllowedEnvPrefixes(prefixes: string[]): void;
/**
 * Get the current global allowed env var prefixes.
 * @returns A copy of the current prefix list.
 */
export declare function getAllowedEnvPrefixes(): string[];
/**
 * Fluent builder for SWAIG data_map configurations.
 *
 * Creates server-side tool definitions that execute on SignalWire's infrastructure
 * **without** requiring a webhook endpoint in your application. Ideal for simple
 * third-party API integrations (REST calls + pattern-matched response shaping).
 *
 * @example Simple webhook-driven tool (no handler needed)
 * ```ts
 * import { DataMap, FunctionResult } from '@signalwire/sdk';
 *
 * const weather = new DataMap('get_weather')
 *   .purpose('Look up the current weather for a city')
 *   .parameter('city', 'string', 'The city name', true)
 *   .webhook('GET', 'https://api.example.com/weather?city=${args.city}')
 *   .output(new FunctionResult('In ${city} it is ${response.temp}°F and ${response.condition}.'));
 *
 * // Register onto an agent:
 * agent.registerSwaigFunction(weather.toSwaigFunction());
 * ```
 *
 * @example Expression-based tool (no webhook, pattern matching only)
 * ```ts
 * new DataMap('classify_intent')
 *   .purpose('Route callers to the right department.')
 *   .parameter('utterance', 'string', 'What the caller said', true)
 *   .expression('${args.utterance}', /billing|invoice|charge/i, new FunctionResult('billing'))
 *   .expression('${args.utterance}', /tech|broken|error/i, new FunctionResult('support'));
 * ```
 *
 * @see {@link FunctionResult} — response shape used in `.output()` / `.expression()`
 * @see {@link createSimpleApiTool} — one-liner helper for REST API tools
 * @see {@link AgentBase.defineTool} — alternative for tools that run in your process
 */
export declare class DataMap {
    /** The name of the SWAIG function this data map defines. */
    functionName: string;
    private _purpose;
    private _parameters;
    private _expressions;
    private _webhooks;
    private _output;
    private _errorKeys;
    private _expandEnv;
    private _allowedEnvPrefixes;
    /**
     * @param functionName - The unique name for this data map tool.
     */
    constructor(functionName: string);
    /**
     * Enable `${ENV.*}` variable expansion in URLs, bodies, and outputs.
     * @param enabled - Whether to enable expansion (defaults to true).
     * @returns This instance for chaining.
     */
    enableEnvExpansion(enabled?: boolean): this;
    /**
     * Set the allowed env var prefixes for this DataMap instance.
     *
     * Overrides the global defaults. Only env vars whose names start with
     * one of these prefixes will be expanded. An empty array allows all.
     *
     * @param prefixes - Array of prefix strings to allow.
     * @returns This instance for chaining.
     */
    setAllowedEnvPrefixes(prefixes: string[]): this;
    /**
     * Set the purpose (description) for this data-map tool — READ BY THE LLM.
     *
     * This string is rendered into the OpenAI tool schema `description`
     * field and sent to the model on every turn. The model uses it to
     * decide WHEN to call this tool. It is **prompt engineering**, not
     * developer documentation.
     *
     * A vague `purpose()` is the #1 cause of "the model has the right tool
     * but doesn't call it" failures with data-map tools.
     *
     * ### Bad vs good
     *
     * ```text
     * BAD : .purpose('weather api')
     * GOOD: .purpose('Get the current weather conditions and forecast for
     *       a specific city. Use this whenever the user asks about weather,
     *       temperature, rain, or similar conditions in a named location.')
     * ```
     *
     * @param description - Prompt-engineering description of when to call this tool.
     * @returns This instance for chaining.
     */
    purpose(description: string): this;
    /**
     * Alias for {@link purpose}; sets the LLM-facing tool description.
     *
     * This string is read by the model to decide WHEN to call this tool.
     * See {@link purpose} for bad-vs-good examples.
     *
     * @param description - Prompt-engineering description of when to call this tool.
     * @returns This instance for chaining.
     */
    description(description: string): this;
    /**
     * Define a parameter for this data-map tool — `description` is READ BY THE LLM.
     *
     * Each parameter `description` is rendered into the OpenAI tool schema
     * under `parameters.properties.<name>.description` and sent to the
     * model. The model uses it to decide HOW to fill in the argument from
     * user speech. It is **prompt engineering**, not developer FYI.
     *
     * ### Bad vs good
     *
     * ```text
     * BAD : .parameter('city', 'string', 'the city')
     * GOOD: .parameter('city', 'string',
     *         'The name of the city to get weather for, e.g. "San Francisco".
     *          Ask the user if they did not provide one. Include the state
     *          or country if the city name is ambiguous.')
     * ```
     *
     * @param name - The parameter name (JSON object key).
     * @param paramType - The JSON Schema type (e.g., "string", "number").
     * @param description - Prompt-engineering description telling the model
     *   how to extract this value from the user's utterance. Read by the LLM.
     * @param opts - Optional flags for required and enum constraints.
     * @returns This instance for chaining.
     */
    parameter(name: string, paramType: string, description: string, opts?: {
        required?: boolean;
        enum?: string[];
    }): this;
    /**
     * Add a pattern-matching expression that evaluates a test value against a regex.
     * @param testValue - The string or template variable to test.
     * @param pattern - A regex pattern (string or RegExp) to match against.
     * @param output - The result to return when the pattern matches.
     * @param nomatchOutput - Optional result to return when the pattern does not match.
     * @returns This instance for chaining.
     */
    expression(testValue: string, pattern: string | RegExp, output: FunctionResult, nomatchOutput?: FunctionResult): this;
    /**
     * Add a webhook that is called when this data map tool is invoked.
     * @param method - HTTP method (e.g., "GET", "POST").
     * @param url - The webhook URL to call.
     * @param opts - Optional headers, form parameter name, and argument settings.
     * @returns This instance for chaining.
     */
    webhook(method: string, url: string, opts?: {
        headers?: Record<string, string>;
        formParam?: string;
        inputArgsAsParams?: boolean;
        requireArgs?: string[];
    }): this;
    /**
     * Set pattern-matching expressions on the most recently added webhook.
     * @param expressions - Array of expression objects to evaluate against the webhook response.
     * @returns This instance for chaining.
     */
    webhookExpressions(expressions: Record<string, unknown>[]): this;
    /**
     * Set the JSON body for the most recently added webhook.
     * @param data - The request body object.
     * @returns This instance for chaining.
     */
    body(data: Record<string, unknown>): this;
    /**
     * Set query or form parameters for the most recently added webhook.
     * @param data - The parameters object.
     * @returns This instance for chaining.
     */
    params(data: Record<string, unknown>): this;
    /**
     * Configure iteration over an array in the webhook response.
     * @param config - Foreach configuration with input/output keys, append template, and optional max.
     * @returns This instance for chaining.
     */
    foreach(config: {
        input_key: string;
        output_key: string;
        append: string;
        max?: number;
    }): this;
    /**
     * Set the output template for the most recently added webhook.
     * @param result - The FunctionResult to use as the output template.
     * @returns This instance for chaining.
     */
    output(result: FunctionResult): this;
    /**
     * Set a fallback output used when no webhook or expression matches.
     * @param result - The FunctionResult to use as the fallback.
     * @returns This instance for chaining.
     */
    fallbackOutput(result: FunctionResult): this;
    /**
     * Set error keys on the most recently added webhook, or globally if no webhook exists.
     * @param keys - Response keys that indicate an error occurred.
     * @returns This instance for chaining.
     */
    errorKeys(keys: string[]): this;
    /**
     * Set error keys at the top-level data map scope, regardless of webhook context.
     * @param keys - Response keys that indicate an error occurred.
     * @returns This instance for chaining.
     */
    globalErrorKeys(keys: string[]): this;
    /**
     * Register this DataMap tool with an AgentBase instance.
     * @param agent - An object with a registerSwaigFunction method (typically an AgentBase).
     * @returns This instance for chaining.
     */
    registerWithAgent(agent: {
        registerSwaigFunction(fn: Record<string, unknown>): unknown;
    }): this;
    /**
     * Serialize this data map to a SWAIG function definition object.
     * @returns A plain object suitable for inclusion in the SWML SWAIG array.
     */
    toSwaigFunction(): Record<string, unknown>;
}
/**
 * Create a DataMap tool that calls a single API endpoint and formats the response.
 * @param opts - Configuration including name, URL, response template, and optional parameters.
 * @returns A configured DataMap instance ready for registration.
 */
export declare function createSimpleApiTool(opts: {
    name: string;
    url: string;
    responseTemplate: string;
    parameters?: Record<string, {
        type?: string;
        description?: string;
        required?: boolean;
    }>;
    method?: string;
    headers?: Record<string, string>;
    body?: Record<string, unknown>;
    errorKeys?: string[];
}): DataMap;
/**
 * Create a DataMap tool that evaluates expressions against patterns without making HTTP calls.
 * @param opts - Configuration including name, pattern-result pairs, and optional parameters.
 * @returns A configured DataMap instance ready for registration.
 */
export declare function createExpressionTool(opts: {
    name: string;
    patterns: Record<string, [string, FunctionResult]>;
    parameters?: Record<string, {
        type?: string;
        description?: string;
        required?: boolean;
    }>;
}): DataMap;