@voctiv/agent-sdk 0.2.6 → 0.2.8

package/dist/types/mixer.d.ts

@@ -10,13 +10,15 @@ import type { LegacySavePhraseOptions } from './legacy-phrase';
  */
 export type TtsStrategy = 'sentence' | 'streaming' | 'full';
 /**
- * Internal TTS vendor code used by the connector factory.
+ * TTS vendor alias understood by ScriptEngine.
  *
- * - **`A`**: default / Neuro-style path.
- * - **`E`** / **`ES`**: ElevenLabs (`ES` = persistent streaming session where supported).
- * - **`V`**, **`G`**: host-specific vendors (e.g. Voctiv, Google).
+ * Dedicated TTS connectors are selected by aliases such as **`"elevenlabs"`**,
+ * **`"google"`**, and **`"voctiv"`**. The default TTS path can also accept
+ * compatible aliases such as **`"azure"`** or **`"neuro_v3"`**, depending on
+ * deployment configuration. The open string form keeps the SDK compatible with
+ * deployment-specific aliases.
  */
-export type TtsVendor = 'A' | 'E' | 'ES' | 'V' | 'G';
+export type TtsVendor = 'elevenlabs' | 'google' | 'azure' | 'yandex' | 'sber' | 'viettel' | 'voctiv' | 'neuro' | 'neuro_v2' | 'neuro_v3' | 'neuro_service' | 'async_azure' | 'stc' | (string & Record<never, never>);
 /**
  * Options for {@link import('./media-channel').ChannelAudio.say},
  * {@link import('./media-channel').ChannelAudio.play}, and

package/dist/types/mixer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mixer.d.ts","sourceRoot":"","sources":["../../src/types/mixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf"}
+{"version":3,"file":"mixer.d.ts","sourceRoot":"","sources":["../../src/types/mixer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,GACT,QAAQ,GACR,OAAO,GACP,UAAU,GACV,UAAU,GACV,eAAe,GACf,aAAa,GACb,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1C,yFAAyF;IACzF,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC;IAEvC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/types/platform.d.ts

@@ -0,0 +1,164 @@
+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 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>;
+}
+/** 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[]>;
+}
+//# sourceMappingURL=platform.d.ts.map

package/dist/types/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/types/platform.ts"],"names":[],"mappings":"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"}

package/dist/types/platform.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=platform.js.map

package/dist/types/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/types/platform.ts"],"names":[],"mappings":""}

package/dist/types/script-context.d.ts

@@ -0,0 +1,170 @@
+import type { BehaviorSubject } from 'rxjs';
+import type { InboundMessage } from './platform';
+/**
+ * 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('./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('./asr-handle').AsrConfig} /
+     * {@link import('./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>;
+}
+//# sourceMappingURL=script-context.d.ts.map

package/dist/types/script-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-context.d.ts","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":"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"}

package/dist/types/script-context.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=script-context.js.map

package/dist/types/script-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-context.js","sourceRoot":"","sources":["../../src/types/script-context.ts"],"names":[],"mappings":""}