import type { Observable } from 'rxjs';
import type { NluExtractOptions, NluInferResult } from './nlu';
import type { LegacyGetRecordsParams, LegacyPhraseRecord } from './legacy-phrase';
/**
 * NLU (Natural Language Understanding) API.
 *
 * Provides intent/entity extraction through the pool-local nlu-engine
 * (`POST /nlu_engine?agent_id=…`), same path as logic-executor
 * `NeuroNluClient.recognize_with_proxy`.
 * ScriptEngine allows this API when `context.legacyV3Compat` is `true` and NLU
 * runtime settings are configured (`NLU_ENGINE_BASE_URL` plus a resolved numeric
 * agent id). Calls fail fast with a descriptive error otherwise.
 *
 * Compatible with logic-executor `nn.extract()` request/response shape.
 */
export interface NluScriptApi {
    /**
     * Extract intents and entities from one user utterance.
     *
     * The runtime sends a logic-executor-compatible recognition request to
     * nlu-engine (`/nlu_engine?agent_id=…`). Pass `options.context` explicitly when
     * needed (same as LE `nlu.extract(..., context=flag)`).
     *
     * @param utterance - User input text to analyze.
     * @param options - Optional NLU filters and flags. `entities`, `intents`,
     *   `language` / `lang`, `use_neuro_api`, and `use_synonyms` are forwarded by ScriptEngine.
     * @returns logic-executor-compatible {@link NluInferResult} (`entity()`, `has_entities()`, …).
     */
    extract(utterance: string, options?: NluExtractOptions): Promise<NluInferResult>;
    /**
     * Observable wrapper around {@link extract}.
     *
     * This is not a streaming NLU session: every subscription performs one
     * `extract()` call and emits exactly one result or one error.
     */
    extract$(utterance: string, options?: NluExtractOptions): Observable<NluInferResult>;
}
/** Options for scheduling an outbound call via {@link PlatformApi.call}. */
export interface ScheduleCallOptions {
    /** When to place the call. Defaults to now. */
    date?: string | Date;
    /** Deadline — don't call after this time. */
    dateEnd?: string | Date;
    /**
     * Optional label stored on the **call** row as `call.params.entry_point` (LE DB compatibility)
     * at schedule time. This is not the same as assigning {@link DialogApi.entryPoint} mid-script
     * (that writes `dialog.params.entry_point`).
     *
     * The host always runs your single `defineScript` export — it does **not** invoke a
     * separate function by this name (unlike logic-executor Python `run_unit(entry_point=...)`).
     * Use {@link import('./script-context').ScriptDialogContext.entryPoint} inside the handler
     * if you branch manually (e.g. headless after-call via
     * {@link import('./script-context').getScriptPhase}).
     */
    entryPoint?: string;
    /**
     * Legacy compatibility field for old callers.
     *
     * Outbound calls can be scheduled without a legacy `script_id`; the dialer can
     * resolve the runtime script from the agent UUID. This field is not used to
     * resolve script names or paths.
     */
    script?: string;
    /**
     * Legacy trunk id as string or number (same as LE `call.trunk_id`) when `trunkId` is not set.
     * Forwarded to the dialer for `X-Via-Trunk` / gateway routing.
     */
    channel?: string | number;
    /**
     * Max failed-call retries. Stored as `recall_count` in call params.
     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallCount}
     * only if {@link onFailedCall} is not configured for this scheduled call.
     *
     * Activates **automatic recall**: on each failed outbound the dialer schedules another call after
     * {@link recallDelay} and increments `context.attempt`. Mutually exclusive with {@link onFailedCall}
     * — if both are present, the host keeps {@link onFailedCall} and drops recall. Requires both
     * `recallCount` and `recallDelay` on the `call` row when used alone.
     */
    recallCount?: number;
    /**
     * Delay before the next recall attempt, in **seconds**.
     * Stored as `recall_delay` in call params (numeric seconds from SDK; LE may also
     * use `HH:MM:SS` strings in legacy rows — the host normalizes both on schedule).
     *
     * When omitted, the host defaults from {@link import('./script-context').ScriptDialogContext.recallDelay}
     * only if {@link onFailedCall} is not configured for this scheduled call.
     *
     * Mutually exclusive with {@link onFailedCall}.
     */
    recallDelay?: number;
    /**
     * Headless handler name after a successful call. Stored as `on_success_call`.
     * On shutdown the host may set `dialog.result = null` and `dialog.params.entry_point` to this
     * value so the dialog re-enters the offline queue for continuation.
     */
    onSuccessCall?: string;
    /**
     * Headless handler after a failed outbound. Stored as `on_failed_call`.
     *
     * Activates **after-call continuation**: the host sets `dialog.params.entry_point` (and typically
     * `dialog.result = null`) and re-runs this script with
     * {@link import('./script-context').getScriptPhase} → `after_call_failed`. Mutually exclusive
     * with automatic recall ({@link recallCount} + {@link recallDelay}) on the same `platform.call()`.
     * If both are present, the host keeps this option and drops recall. When set (including via Omni
     * `scheduleOutbound` defaults), CMS recall is not auto-copied onto the `call` row.
     */
    onFailedCall?: string;
    /** Call priority (higher = processed sooner by dialer). */
    priority?: number;
    /** Timezone offset passed to the legacy call row as `timeZone`. */
    timezone?: number;
    /** Extra SIP headers or protocol-level params. Stored as `proto_additional` in call params. */
    protoAdditional?: Record<string, string>;
    /**
     * LE `call.trunk_id` — required for the legacy mass outbound dialer to originate SIP.
     * If omitted, the scheduler tries `channel` (numeric), `dialog.params.trunk_id`,
     * `agent.trunk_id`, then env `LEGACY_V3_SCHEDULED_CALL_DEFAULT_TRUNK_ID`.
     */
    trunkId?: number;
    /** LE `call.pool_id` when absent from dialog params. */
    poolId?: number;
    /** LE `call.bulk_uuid` when absent from the dialog row. */
    bulkUuid?: string;
}
/**
 * LE **dialog row** helpers — lifecycle status (`result`) and routing (`entryPoint`).
 *
 * These fields map to the Voctiv platform `dialog` table, not to SIP media.
 * Setting `entryPoint` or `result` updates the local value immediately and asks
 * the database to persist asynchronously (worker RPC or direct session). Setters
 * are not awaitable — do not use them for transactional flow.
 *
 * Do **not** confuse with {@link import('./sip').ChannelSip.hangup}, SIP
 * `call.result`, or {@link import('./script-context').ScriptResult}.
 */
export interface DialogApi {
    /**
     * Writable routing hint persisted as `dialog.params.entry_point`.
     *
     * Distinct from the read-only snapshot
     * {@link import('./script-context').ScriptDialogContext.entryPoint} taken at
     * script start. Assigning here does **not** select a different script export —
     * the host always runs the same `defineScript` handler; branch with
     * {@link import('./script-context').getScriptPhase} / `context.entryPoint`.
     */
    entryPoint: string | undefined;
    /**
     * Lifecycle status of the LE **`dialog.result`** column (queue / CMS), not the
     * SIP call outcome.
     *
     * Typical values: `"pending"` (in progress), `"queued"` (offline queue),
     * `"done"` / `"error"` (terminal), or `null` (e.g. after-call continuation so
     * the dialog re-enters the queue). The host also sets these on live session
     * start and shutdown.
     *
     * Does **not** hang up SIP or change `channel.sip.state`. Not
     * {@link import('./script-context').ScriptResult}, not `call.result` (per-leg
     * SIP code/phrase for CMS logs).
     */
    result: string | undefined;
    /** Same dialog UUID as {@link import('./script-context').ScriptDialogContext.dialogUuid}. */
    readonly uuid: string;
    /** Same caller identity as {@link import('./script-context').ScriptDialogContext.msisdn}. */
    readonly msisdn: string;
}
/** Options for sending an outbound message via {@link MessagingApi.send}. */
export interface SendMessageOptions {
    /** Sender identifier (service id, bot id, or phone number expected by the MA consumer). */
    src: string;
    /** Recipient identifier (phone number, user id, or channel-specific address). */
    destination: string;
    /** Text body of the message. When present in legacy mode, it is also mirrored to dialog stats. */
    text?: string;
    /** URL of an attachment (image, document, etc.). */
    attachment?: string;
    /** Quick-reply button labels. */
    buttons?: string[];
}
/** Inbound message received from an external messaging channel. */
export interface InboundMessage {
    /** Sender identifier (who sent the message). */
    src: string;
    /** Recipient identifier (your service endpoint). */
    dst: string;
    /** Channel type, e.g. `"api"`. */
    channelType: string;
    /** Full raw payload from the messaging transport. */
    payload: Record<string, unknown>;
}
/**
 * Messaging API — send and receive messages through external channels.
 *
 * Outbound messages are transported via Redis Streams (`ma_send` / `ma_receive`),
 * compatible with the old LE messaging architecture. `message$` is currently a
 * one-shot replay of the inbound message that started a headless messaging script,
 * not a live subscription to all future Redis messages.
 */
export interface MessagingApi {
    /**
     * Send an outbound message.
     * Published to Redis stream for delivery by external consumer.
     */
    send(options: SendMessageOptions): Promise<void>;
    /**
     * Observable of inbound messages.
     * Emits the triggering message when the script is started by an incoming message
     * (entry point `on_message_api_received`).
     */
    readonly message$: Observable<InboundMessage>;
}
/**
 * Platform API — Voctiv platform–compatible operations available to scripts.
 *
 * Provides access to NLU, dialog state management, outbound call scheduling,
 * phrase records, and messaging. These operations are legacy-platform backed and
 * require `context.legacyV3Compat === true`.
 *
 * `platform.call(msisdn)` may be called without options. The host fills omitted
 * scheduling/routing fields from agent/dialog settings when available; explicit
 * `options` always win over those defaults.
 */
export interface PlatformApi {
    /** NLU intent/entity extraction API; throws outside legacy V3 compatibility mode. */
    readonly nlu: NluScriptApi;
    /**
     * LE dialog lifecycle and routing ({@link DialogApi.result}, {@link DialogApi.entryPoint}).
     * Not SIP hangup / media — see {@link import('./sip').ChannelSip}.
     */
    readonly dialog: DialogApi;
    /** Messaging API — send and receive external messages. */
    readonly messaging: MessagingApi;
    /**
     * Schedule an outbound call.
     * Creates a record in the `call` table; the dialer picks it up and originates the SIP call.
     * @param msisdn - Destination phone number (E.164).
     * @param options - Scheduling, routing, and retry options.
     */
    call(msisdn: string, options?: ScheduleCallOptions): Promise<void>;
    /**
     * Voctiv platform only: load `record_phrase` / `record_phrase_file` rows from the LE PostgreSQL database
     * (same filters as old `RecordPhrase.get_records`). Returns playable phrase record objects.
     * Requires a resolved numeric LE `agent.id` (dialog / leAgentId / Omni nlu.agentId).
     * Optional dev fallback: `NLU_DEFAULT_AGENT_ID`.
     * `LEGACY_V3_RECORD_PHRASE_ROOT` pointing at the phrase file storage root.
     */
    getRecords?(params: LegacyGetRecordsParams): Promise<LegacyPhraseRecord[]>;
}
//# sourceMappingURL=platform.d.ts.map