import type { MediaChannel } from './types/media-channel';
import type { ScriptLogger } from './types/logger';
import type { ScriptCallOptions } from './types/call-options';
import type { ScriptDialogContext, ScriptResult } from './types/script-context';
import type { PlatformApi } from './types/platform';
/**
 * Top-level context passed to every script function.
 *
 * @example
 * ```ts
 * export default defineScript(async ({ channel, logger, context, platform }) => {
 *   logger.log('Script started', { dialog: context.dialogUuid });
 *
 *   // Voice interaction
 *   await channel.audio.say('Hello!');
 *
 *   // NLU
 *   const result = await platform.nlu.extract('I want to buy');
 *
 *   // Messaging
 *   await platform.messaging.send({ src: 'bot', destination: '+7900...', text: 'Hi' });
 *
 *   // Schedule a callback
 *   await platform.call('+7900...', { date: new Date(Date.now() + 3600000) });
 * });
 * ```
 */
export interface ScriptContext {
    /**
     * Media channel for voice/audio interaction (TTS, ASR, SIP, LLM).
     * In headless mode most audio methods are no-ops.
     */
    channel: MediaChannel;
    /** Structured logger — writes to system log and optionally to `dialog_stats` DB table. */
    logger: ScriptLogger;
    /** Dialog context with session metadata, routing params, and Voctiv platform fields. */
    context: ScriptDialogContext;
    /** Platform API — NLU, dialog state, messaging, outbound calls. */
    platform: PlatformApi;
}
/**
 * Script function signature.
 * Return {@link ScriptResult} to persist output (and optional error), or void.
 */
export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<void | ScriptResult>;
/**
 * A {@link ScriptFn} carrying the {@link ScriptCallOptions} passed to
 * {@link defineScript}. The host reads them off the default export **before**
 * the script runs, which is why they live on the function rather than in the
 * returned {@link ScriptResult}.
 */
export type ScriptFnWithCallOptions = ScriptFn & {
    readonly callOptions?: ScriptCallOptions;
};
/**
 * Mark the default export as a typed script entry point (identity wrapper; no runtime transform).
 *
 * The host loads this module, invokes the function with {@link ScriptContext}, and persists
 * {@link ScriptResult} / {@link import('./types/script-context').ScriptDialogContext.env$}
 * according to Voctiv platform rules.
 *
 * @param fn - Handler receiving **`{ channel, logger, context, platform }`**.
 *   - Use **`channel`** for ASR/TTS (see {@link import('./types/asr-handle').AsrConfig.name},
 *     {@link import('./types/mixer').PlayOptions.name} for LE **`key_storage.name`** selection).
 *   - Use **`context.dialogParams`** / **`context.dialogUuid`** for routing; **`platform`** for NLU, calls, messaging.
 * @param options - Optional {@link ScriptCallOptions}. Unlike everything else in the
 *   SDK these are read by the host **before** the script runs — they decide *when*
 *   the session starts — so they are attached to the returned function instead of
 *   being read from the handler.
 * @returns The same **`fn`** reference, with `options` attached as `callOptions`.
 *
 * @example
 * ```ts
 * import { defineScript } from '@voctiv/agent-sdk';
 *
 * export default defineScript(async ({ channel, logger, context, platform }) => {
 *   const asr = await channel.createAsr({
 *     name: 'my-yandex-key',
 *     vendor: 'yandex',
 *     language: 'ru-RU',
 *   });
 * });
 * ```
 *
 * @example Pick up the outbound leg from the INVITE — see {@link ScriptCallOptions.outboundCallMode}
 * ```ts
 * import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
 *
 * export default defineScript(
 *   async ({ channel, context }) => {
 *     if (getScriptPhase(context) === 'early') {
 *       await channel.sip.waitForAnswer();
 *     }
 *     await channel.audio.say('Hello!');
 *   },
 *   { outboundCallMode: 'from_invite' },
 * );
 * ```
 */
export declare function defineScript(fn: ScriptFn, options?: ScriptCallOptions): ScriptFnWithCallOptions;
//# sourceMappingURL=define-script.d.ts.map