@voctiv/agent-sdk 0.2.7 → 0.2.9

package/README.md

@@ -89,7 +89,7 @@ export default defineScript(async ({ channel, logger, context }) => {
 - `channel.audio` controls TTS, raw playback, pre-synthesis, and mixer queues.
 - `channel.sip` controls SIP state, pre-answer media, DTMF, hold/mute/hangup, outbound calls, and bridging.
 - `channel.llm` talks to the Omni LLM backend.
-- `channel.events` exposes speech, interrupt, termination, and WS data message observables.
+- `channel.events` exposes speech, interrupt, termination, WS data message, and media error observables.
 - `channel.textInput` injects synthetic ASR results for tests and debug clients.
 
 ## SIP And Pre-Answer Media
@@ -194,7 +194,7 @@ Create ASR with `channel.createAsr(config?)`.
 
 ```ts
 const asr = await channel.createAsr({
-  vendor: 'Y',
+  vendor: 'yandex',
   name: 'main-yandex-key',
   language: 'ru-RU',
   vad: {
@@ -217,19 +217,50 @@ const asr = await channel.createAsr({
 - `speechStart$` / `speechEnd$`: VAD speech boundaries.
 - `interrupt$`: barge-in / interrupt events where the host supports them.
 - `vadProbability$`: normalized VAD probability when available.
+- `error$`: runtime errors from the ASR provider (see [Error Handling](#error-handling)).
 - `pause()` / `resume()` to stop or resume forwarding new audio frames.
 - `finalize()` to force the current utterance to flush.
 - `destroy()` to close connector streams and subscriptions.
 
 SIP sessions use the call-level telephony VAD when it is available. WS sessions create one VAD/SmartTurn instance for the socket session on the first `createAsr()` call. Headless sessions return an inert ASR handle with empty observables.
 
-If ASR connector creation fails, SIP/WS return a degraded handle. VAD observables still mirror the channel where possible, but no real STT results are emitted.
+If ASR connector creation fails, SIP/WS return a degraded handle. VAD observables still mirror the channel where possible, but no real STT results are emitted. The creation failure is reported on `channel.events.error$`.
 
 ## ASR Credentials And Vendors
 
-`AsrConfig.vendor` is an engine hint, for example `"Y"`, `"D"`, `"yandex"`, or `"neuro_v3"`, resolved by the host vendor alias mapping.
+`AsrConfig.vendor` is an engine hint, for example `"yandex"`, `"deepgram"`, `"azure"`, `"elevenlabs"`, or `"neuro_v3"`, resolved by the host vendor alias mapping.
 
-In Voctiv legacy compatibility mode, ASR credentials can be selected by logic-executor `key_storage.name`:
+### Direct ASR Vendor Parameters
+
+Pass vendor-native credentials and settings directly through `AsrConfig.data`. These values are forwarded to the connector as-is and override any defaults or platform-resolved credentials.
+
+```ts
+const asr = await channel.createAsr({
+  vendor: 'azure',
+  language: 'ru-RU',
+  data: {
+    subscription_key: 'your-azure-key',
+    region: 'swedencentral',
+  },
+});
+```
+
+Each vendor connector accepts its native parameter names:
+
+| Vendor | Accepted `data` keys |
+| --- | --- |
+| **Azure** | `subscription_key` or `api_key`, `region` |
+| **Yandex** | `api_key` or `token`, `folder_id` |
+| **ElevenLabs** | `api_key` (or `xi_api_key`), `model` |
+| **Deepgram** | `api_key` |
+| **Google** | `email`, `private_key`, `project_id` |
+| **Whisper** | `url`, `rate`, `toFloat` |
+
+All vendors also accept the env-style names (`AZURE_SPEECH_KEY`, `ELEVENLABS_API_KEY`, etc.) for backwards compatibility, but vendor-native names are checked first and are preferred.
+
+### Voctiv Platform ASR Key Selection
+
+In Voctiv legacy compatibility mode, ASR credentials can also be selected by logic-executor `key_storage.name`:
 
 ```ts
 const asr = await channel.createAsr({
@@ -238,7 +269,9 @@ const asr = await channel.createAsr({
 });
 ```
 
-The runtime looks in `channel.params.authentication_data.legacyAsrKeysByName[name]` for the current dialog agent and company. If `name` is omitted, `channel.params.defaultAsrName` may be used. Vendor-specific overrides go into `data`; primitives are stringified and objects/arrays are JSON-serialized before connector config is built.
+The runtime looks in `channel.params.authentication_data.legacyAsrKeysByName[name]` for the current dialog agent and company. If `name` is omitted, `channel.params.defaultAsrName` may be used.
+
+When both `name` (platform key) and explicit `data` are provided, `data` values win — they are applied last and override anything resolved from the platform.
 
 ## TTS, Playback, And Mixer Queues
 
@@ -248,15 +281,22 @@ The runtime looks in `channel.params.authentication_data.legacyAsrKeysByName[nam
 await channel.audio.say('Please wait while I check that.', {
   queue: 0,
   alias: 'main-response',
-  ttsVendor: 'E',
+  ttsVendor: 'elevenlabs',
   ttsStrategy: 'sentence',
   ttsConfig: {
-    voice_id: 'voice-id',
+    api_key: 'sk_your-key',
+    voice_id: 'bBLRWT6MSWBFAm76ZWXY',
+    model_id: 'eleven_turbo_v2_5',
+    base_url: 'https://api.eu.residency.elevenlabs.io',
     output_format: 'pcm_16000',
   },
 });
 ```
 
+Use full vendor names for `ttsVendor`. Dedicated TTS vendors include `"elevenlabs"`, `"google"`, and `"voctiv"`. The default TTS path can also accept compatible aliases such as `"azure"` or `"neuro_v3"`, depending on how ScriptEngine is configured.
+
+Vendor-native parameter names (`api_key`, `voice_id`, `model_id`, `base_url`) are passed directly to the connector and override any platform defaults. See [TTS Credentials And Vendor Parameters](#tts-credentials-and-vendor-parameters) for the full list of accepted keys per vendor.
+
 `channel.audio.play(source, options?)` plays raw audio from a URL/path or a `LegacyPhraseRecord`.
 
 ```ts
@@ -301,9 +341,37 @@ channel.audio.stop(2);
 
 For sentence-split TTS, queue item aliases are suffixed as `alias-0`, `alias-1`, and so on. Raw `play()` and direct streaming TTS use the alias exactly.
 
-## TTS Credentials And Saved Phrases
+## TTS Credentials And Vendor Parameters
 
-In Voctiv legacy compatibility mode, TTS credentials can be selected by `PlayOptions.name` or `ttsConfig.name`.
+### Direct TTS Vendor Parameters
+
+Pass vendor-native credentials and settings directly through `PlayOptions.ttsConfig`. These values are forwarded to the TTS connector as-is and override any defaults or platform-resolved credentials.
+
+```ts
+await channel.audio.say('Hello!', {
+  ttsVendor: 'elevenlabs',
+  ttsStrategy: 'streaming',
+  ttsConfig: {
+    api_key: 'sk_your-elevenlabs-key',
+    voice_id: 'bBLRWT6MSWBFAm76ZWXY',
+    model_id: 'eleven_turbo_v2_5',
+    base_url: 'https://api.eu.residency.elevenlabs.io',
+  },
+});
+```
+
+Each TTS vendor connector accepts its native parameter names:
+
+| Vendor | Accepted `ttsConfig` keys |
+| --- | --- |
+| **ElevenLabs** | `api_key` (or `xi_api_key`), `voice_id`, `model_id` (or `model`), `base_url`, `output_format`, `language_code`, `voice_settings_stability`, `voice_settings_similarity_boost`, `voice_settings_style`, `voice_settings_speed` |
+| **Voctiv** | `url`, `voice_id`, `language`, `emotion`, `speaking_rate`, `chunk_schedule` |
+
+All vendors also accept the env-style names (`ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID`, etc.) for backwards compatibility, but vendor-native names are checked first and are preferred.
+
+### Voctiv Platform TTS Key Selection
+
+In Voctiv legacy compatibility mode, TTS credentials can also be selected by `PlayOptions.name` or `ttsConfig.name`.
 
 ```ts
 await channel.audio.say('Здравствуйте!', {
@@ -316,11 +384,20 @@ await channel.audio.say('Здравствуйте!', {
 
 The runtime looks in `channel.params.authentication_data.legacyTtsKeysByName[name]`. If `name` is omitted, `channel.params.defaultTtsName` may be used.
 
-`legacySavePhrase` stores synthesized audio under the Voctiv record phrase storage root and inserts phrase metadata so it can later be loaded with `platform.getRecords()`.
+When both `name` (platform key) and explicit `ttsConfig` values are provided, `ttsConfig` values win — they are applied last and override anything resolved from the platform.
+
+`cache` enables TTS result caching for `say()` and `presay()`:
+
+- **`cache: true`** — read/write TTS file cache only (Redis + filesystem + DB).
+- **`cache: { phraseName, flag?, language? }`** — TTS cache **plus** persist into Voctiv platform `record_phrase` / `record_phrase_file` so `platform.getRecords()` can retrieve the audio later.
 
 ```ts
+// Cache only (no platform persist):
+await channel.audio.say('Hello!', { cache: true });
+
+// Cache + persist to platform phrase storage:
 await channel.audio.say('Welcome back.', {
-  legacySavePhrase: {
+  cache: {
     phraseName: 'welcome_back',
     flag: context.flag,
     language: context.language,
@@ -340,6 +417,72 @@ if (records?.[0]) {
 
 This requires legacy compatibility mode, a trusted LE agent id/UUID, TTS cache, and `LEGACY_V3_RECORD_PHRASE_ROOT`.
 
+## Error Handling
+
+ASR and TTS errors are propagated to the script. Unhandled errors are always logged server-side, but scripts can catch them to react: fall back to a different vendor, notify the caller, or abort the dialog.
+
+### TTS Errors — Promise Rejection
+
+`say()` and `play()` reject their promises when TTS/playback fails:
+
+```ts
+try {
+  await channel.audio.say('Hello!', {
+    ttsVendor: 'elevenlabs',
+    ttsConfig: { api_key: 'invalid-key', voice_id: 'abc' },
+  });
+} catch (err) {
+  logger.error('TTS failed', { error: String(err) });
+  await channel.audio.say('Fallback message.'); // try default TTS
+}
+```
+
+### ASR Errors — `error$` Observable
+
+Runtime ASR errors (gRPC disconnect, auth failure, quota exceeded) are emitted on `AsrHandle.error$`:
+
+```ts
+const asr = await channel.createAsr({
+  vendor: 'yandex',
+  data: { api_key: 'my-key' },
+});
+
+asr.error$.subscribe((err) => {
+  logger.error('ASR provider error', {
+    message: err.message,
+    code: err.code,
+    vendor: err.vendor,
+  });
+});
+```
+
+A degraded handle (returned when connector creation itself failed) has an inert `error$` that never emits — the creation failure is reported on `channel.events.error$` instead.
+
+### Channel Error Stream
+
+`channel.events.error$` is a unified stream of all media errors — both ASR and TTS:
+
+```ts
+channel.events.error$.subscribe((err) => {
+  logger.warn(`[${err.source}] ${err.message}`, {
+    code: err.code,
+    vendor: err.vendor,
+  });
+});
+```
+
+`MediaError` fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `source` | `'asr' \| 'tts' \| 'sip' \| 'channel'` | Which subsystem produced the error. |
+| `message` | `string` | Human-readable description. |
+| `code` | `number?` | HTTP status, gRPC status, or WebSocket close code. |
+| `vendor` | `string?` | Vendor identifier, e.g. `"yandex"`, `"elevenlabs"`, `"azure"`. |
+| `details` | `unknown?` | Arbitrary provider-specific payload. |
+
+Subscribing to `error$` is optional. Old scripts that do not subscribe are not affected — the observables simply go unobserved.
+
 ## LLM API
 
 `channel.llm` talks to the Omni LLM backend.
@@ -693,5 +836,5 @@ npm run build
 The package exports only the public SDK entry point:
 
 ```ts
-import { defineScript, type MediaChannel, type AsrHandle } from '@voctiv/agent-sdk';
+import { defineScript, type MediaChannel, type AsrHandle, type MediaError } from '@voctiv/agent-sdk';
 ```

package/dist/define-script.d.ts

@@ -1,335 +1,7 @@
-import type { BehaviorSubject, Observable } from 'rxjs';
 import type { MediaChannel } from './types/media-channel';
-import { ScriptLogger } from './types/logger';
-import type { NluExtractOptions, NluInferResult } from './types/nlu';
-import type { LegacyGetRecordsParams, LegacyPhraseRecord } from './types/legacy-phrase';
-/**
- * NLU (Natural Language Understanding) API.
- *
- * Provides intent/entity extraction through the legacy NLU v3 `/infer` endpoint.
- * ScriptEngine allows this API when `context.legacyV3Compat` is `true` and NLU
- * runtime settings are configured (`NLU_V3_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 `{ phrase, context, agent_id }` to NLU v3. If
-     * `options.context` is omitted, it serializes the current dialog params
-     * (`context.dialogParams`, then legacy fallbacks) as the request context.
-     *
-     * @param utterance - User input text to analyze.
-     * @param options - Optional NLU filters and flags. `entities`, `intents`,
-     *   `use_neuro_api`, and `use_synonyms` are forwarded by ScriptEngine.
-     * @returns Raw parsed JSON response from the NLU `/infer` endpoint.
-     */
-    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>;
-}
-/**
- * First-level **`context`** passed to every **`defineScript`** handler.
- *
- * Combines **identity** (dialog, script, agent), **telephony** (caller/destination),
- * **payload** (**`initialData`** vs **`dialogParams`**), **Voctiv platform** rows (**`dialogEntity`**),
- * and **runtime** (**`env$`**, **`runTime`**). The index signature allows extra host-specific keys.
- */
-export interface ScriptDialogContext {
-    /** Short language code, e.g. `"ru"`, `"en"`. */
-    lang: string;
-    /** Full BCP-47 language tag, e.g. `"ru-RU"`, `"en-US"`. */
-    language: string;
-    /** Business flag for routing (e.g. `"default"`, `"vip"`). */
-    flag: string;
-    /** Unique dialog identifier (UUID). */
-    dialogUuid: string;
-    /** Caller phone number or messaging source ID. */
-    msisdn: string;
-    /** Inbound caller ID (same as msisdn for inbound calls). */
-    callerId: string;
-    /** Called number (DID / destination for inbound calls). */
-    destinationNumber: string;
-    /** Script record ID in the system. */
-    scriptId: string;
-    /** Human-readable script name. */
-    scriptName: string;
-    /** Agent UUID from Omni platform (links script to an NLU agent). */
-    agentUuid?: string;
-    /**
-     * Numeric NLU agent id used for `platform.nlu.extract()` and legacy DB operations.
-     *
-     * Resolved by the server from Omni/LE mapping or env (`NLU_DEFAULT_AGENT_ID` /
-     * `AGENT_ID`). Client/session params named `agent_id`, `agentId`, `agentUuid`,
-     * and `agent_uuid` are stripped before context construction and cannot spoof it.
-     * May be `0` when no agent id is configured; NLU and `platform.call()` will then fail.
-     */
-    agentId: number;
-    /**
-     * **Snapshot** of dialog/session payload when the script run started.
-     *
-     * Shallow copy of the merge **`channelParams` + `sessionParams`** after the server removes
-     * untrusted keys (e.g. client cannot spoof **`agentUuid`** here). **Do not mutate** — use
-     * **`dialogParams`** for the live map. Compare with **`dialogParams`** to see what changed
-     * during the call (if the host updates the live object).
-     */
-    initialData: Record<string, unknown>;
-    /**
-     * **Live** dialog/session parameter map for this run (same merge as **`initialData`** at start).
-     *
-     * The host may add or overwrite keys while the session progresses. For media scripts this
-     * aligns with {@link import('./types/media-channel').MediaChannel.params} (Omni defaults, route,
-     * Voctiv platform ASR/TTS: **`defaultAsrName`**, **`defaultTtsName`**, **`asrVendor`**, **`ttsVendor`**,
-     * **`asrConfig`**, **`ttsConfig`**, **`authentication_data`**, **`legacyAsrKeysByName`** /
-     * **`legacyTtsKeysByName`**, etc.). **Read/write** according to your integration; scripts should
-     * treat unknown keys as opaque.
-     */
-    dialogParams: Record<string, unknown>;
-    /** Whether Voctiv platform compatibility mode is active. */
-    legacyV3Compat: boolean;
-    /**
-     * `true` when the script runs without a real media channel (offline / queue / messaging).
-     *
-     * In this mode ASR/TTS/audio/SIP operations are inert or synthetic. Use text payloads,
-     * `platform.nlu`, `platform.messaging`, `platform.call`, `channel.llm`, and `env$`
-     * for background dialog logic.
-     */
-    headless: boolean;
-    /**
-     * Persisted dialog environment for this conversation. ScriptEngine converts the
-     * plain persisted `env` snapshot into this `BehaviorSubject` before invoking the script.
-     * On the first call the value is `undefined`.
-     *
-     * **Read/write only via `env$`:** use `env$.getValue()`, `env$.next(partialOrNext)`, or
-     * `env$.subscribe(...)`. Do not use a plain `context.env` — it is not provided.
-     *
-     * **Persistence:** On script completion (success or error), the runtime snapshots `env$` and
-     * attaches it to the persisted result; the script return value must not carry env
-     * (see {@link ScriptResult}).
-     *
-     * Session runners decide where that snapshot is stored. In Voctiv platform compatibility
-     * mode it is used as the LE-style dialog environment.
-     */
-    env$?: BehaviorSubject<Record<string, unknown> | undefined>;
-    /** Raw `dialog` table row from the Voctiv platform database. */
-    dialogEntity?: Record<string, unknown>;
-    /** Raw `call` table row from the Voctiv platform database. */
-    callEntity?: Record<string, unknown>;
-    /**
-     * Optional catalog of media keys exposed to the script (Voctiv platform / Omni), e.g. UUIDs or labels
-     * for UI or logging. **Credentials** still come from **`dialogParams.authentication_data`**
-     * (and the channel mirror); use **`name`** on {@link import('./types/asr-handle').AsrConfig} /
-     * {@link import('./types/mixer').PlayOptions} to select **`key_storage.name`** when LE credential maps exist.
-     */
-    availableMediaKeys?: string[];
-    /** Script entry point for routing (e.g. `"on_recall"`, `"on_message_api_received"`). */
-    entryPoint?: string;
-    /** Current recall attempt number (starts at 0). */
-    attempt?: number;
-    /** Max recall attempts configured for this dialog. */
-    recallCount?: number;
-    /** Delay in seconds between recall attempts. */
-    recallDelay?: number;
-    /**
-     * Inbound message that triggered this headless session.
-     *
-     * Present for messaging-driven offline runs, commonly with
-     * `entryPoint === "on_message_api_received"`. The `payload` field is the raw
-     * provider payload; normalize text defensively because transports may use
-     * different keys such as `text`, `message`, `body`, or `content`.
-     */
-    inboundMessage?: InboundMessage;
-    /**
-     * Async-phase execution budget: remaining time, extension pool, {@link ScriptRunTime.extend}.
-     * Injected by the runtime; absent only in tests or non-standard hosts.
-     */
-    runTime?: ScriptRunTime;
-    /** Opaque NLU runtime config managed by ScriptEngine. */
-    _nlu?: unknown;
-    [key: string]: unknown;
-}
-/**
- * Time budget for the script async phase (after VM load). Lets scripts check remaining time
- * and request limited extensions (capped by the runtime).
- */
-export interface ScriptRunTime {
-    /** Initial budget in ms before any {@link extend}. */
-    readonly budgetMs: number;
-    /** Maximum total extra ms grantable across all {@link extend} calls for this session. */
-    readonly maxExtendMs: number;
-    /** Milliseconds left until the runtime stops the async script phase. */
-    remainingMs(): number;
-    /** Extension quota not yet granted (ms). */
-    remainingExtendMs(): number;
-    /**
-     * Grants up to `requestedMs` additional runtime, limited by remaining extension quota.
-     * @returns Granted milliseconds (0 if nothing could be granted).
-     */
-    extend(requestedMs: number): number;
-}
-/** Error info attached to {@link ScriptResult} when a script fails. */
-export interface ScriptError {
-    /**
-     * Machine-readable category, e.g. `script_error`, `script_load_failed`, `time_limit_exceeded`.
-     */
-    code: string;
-    /** Human-readable error description. */
-    message: string;
-    /** Stack trace (when available). */
-    stack?: string;
-}
-/**
- * Value returned by a script function. Only `output` and `error` are valid fields.
- * Session state is updated via `context.env$`; the runtime snapshots it separately.
- */
-export interface ScriptResult {
-    /** Output data to store in dialog_stats. */
-    output?: Record<string, unknown>;
-    /** Error details (auto-populated on script crash, or set manually). */
-    error?: ScriptError;
-}
-/**
- * Result after the runtime attaches the final `env$` snapshot (Voctiv platform persistence).
- * Scripts never construct this type — use {@link ScriptResult} from `defineScript` handlers.
- */
-export interface PersistedScriptResult extends ScriptResult {
-    env?: Record<string, unknown>;
-}
-/** 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;
-    /**
-     * Entry point to pass to the script when the call connects.
-     *
-     * Stored in the created call params as `entry_point`.
-     */
-    entryPoint?: string;
-    /**
-     * Legacy compatibility field for callers that schedule without a current `scriptId`.
-     *
-     * ScriptEngine uses this to allow scheduling when the current script id is not
-     * available. It does not resolve script names or paths from this field.
-     */
-    script?: string;
-    /** Reserved SIP channel/trunk hint. Not used by the default ScriptEngine scheduler. */
-    channel?: string;
-    /** How many times to retry on failure. Stored as `recall_count` in call params. */
-    recallCount?: number;
-    /** Delay in seconds between retries. Stored as `recall_delay` in call params. */
-    recallDelay?: number;
-    /** Entry point to use after a successful call. Stored as `on_success_call`. */
-    onSuccessCall?: string;
-    /** Entry point to use after a failed call. Stored as `on_failed_call`. */
-    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>;
-}
-/**
- * Dialog state API — read and update dialog routing metadata.
- *
- * Setting `entryPoint` or `result` updates the local value immediately and asks
- * the Voctiv platform database to persist the change asynchronously. In worker
- * sessions the setter sends an RPC to the main thread; in direct sessions errors
- * are logged. There is no awaitable setter, so do not use it for transactional flow.
- */
-export interface DialogApi {
-    /** Current script entry point (e.g. `"on_recall"`). Set to change routing for the next call. */
-    entryPoint: string | undefined;
-    /** Dialog outcome (e.g. `"done"`, `"busy"`, `"no_answer"`). Set to finalize dialog. */
-    result: string | undefined;
-    /** Dialog UUID (read-only). */
-    readonly uuid: string;
-    /** Caller msisdn (read-only). */
-    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`.
- */
-export interface PlatformApi {
-    /** NLU intent/entity extraction API; throws outside legacy V3 compatibility mode. */
-    readonly nlu: NluScriptApi;
-    /** Dialog state — read/write entry point and result. */
-    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 numeric `agent_id` on the dialog (params or `NLU_DEFAULT_AGENT_ID`) and
-     * `LEGACY_V3_RECORD_PHRASE_ROOT` pointing at the phrase file storage root.
-     */
-    getRecords?(params: LegacyGetRecordsParams): Promise<LegacyPhraseRecord[]>;
-}
+import type { ScriptLogger } from './types/logger';
+import type { ScriptDialogContext, ScriptResult } from './types/script-context';
+import type { PlatformApi } from './types/platform';
 /**
  * Top-level context passed to every script function.
  *
@@ -374,7 +46,8 @@ export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<voi
  * 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 ScriptDialogContext.env$} according to Voctiv platform rules.
+ * {@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},
@@ -384,12 +57,12 @@ export type ScriptFn = (ctx: ScriptContext) => void | ScriptResult | Promise<voi
  *
  * @example
  * ```ts
- * import { defineScript } from '@lib/scripting-sdk';
+ * import { defineScript } from '@voctiv/agent-sdk';
  *
  * export default defineScript(async ({ channel, logger, context, platform }) => {
  *   const asr = await channel.createAsr({
  *     name: 'my-yandex-key',
- *     vendor: 'Y',
+ *     vendor: 'yandex',
  *     language: 'ru-RU',
  *   });
  * });

package/dist/define-script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-script.d.ts","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-script.d.ts","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,MAAM,EAAE,YAAY,CAAC;IACrB,wFAAwF;IACxF,OAAO,EAAE,mBAAmB,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CACrB,GAAG,EAAE,aAAa,KACf,IAAI,GAAG,YAAY,GAAG,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,QAAQ,CAEnD"}

package/dist/define-script.js

@@ -5,7 +5,8 @@ exports.defineScript = defineScript;
  * 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 ScriptDialogContext.env$} according to Voctiv platform rules.
+ * {@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},
@@ -15,12 +16,12 @@ exports.defineScript = defineScript;
  *
  * @example
  * ```ts
- * import { defineScript } from '@lib/scripting-sdk';
+ * import { defineScript } from '@voctiv/agent-sdk';
  *
  * export default defineScript(async ({ channel, logger, context, platform }) => {
  *   const asr = await channel.createAsr({
  *     name: 'my-yandex-key',
- *     vendor: 'Y',
+ *     vendor: 'yandex',
  *     language: 'ru-RU',
  *   });
  * });

package/dist/define-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-script.js","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":";;AAobA,oCAEC;AA3BD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,YAAY,CAAC,EAAY;IACvC,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"define-script.js","sourceRoot":"","sources":["../src/define-script.ts"],"names":[],"mappings":";;AA2EA,oCAEC;AA5BD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,YAAY,CAAC,EAAY;IACvC,OAAO,EAAE,CAAC;AACZ,CAAC"}