@voctiv/agent-sdk 0.3.1 → 0.3.3

package/examples/custom-media-providers.ts

@@ -1,22 +1,25 @@
 /**
- * Custom ASR / TTS from a trusted logic package.
+ * Host-only custom ASR / TTS module.
  *
- * Export `mediaProviders` next to `defineScript`. The host loads that export
- * outside the sandbox and wires vendors into `createAsr` / `createTts` with the
- * same warm TCP/WS reuse as built-in engines.
+ * Ship as `dist/media-providers/index.js` next to the sandboxed script entry.
+ * The host `require`s this file outside the script VM (full Node: `ws`, `process`, …).
+ *
+ * Do **not** re-export `mediaProviders` from `dist/index.js` — the sandbox has no
+ * `process`, so loading `ws` there fails. Keep `defineScript` in a separate file
+ * (see `custom-media-providers-script.ts`).
  *
  * Batch and streaming TTS share one class (`supportsStreaming()` + streaming
- * lifecycle methods). Do not register a separate streaming map.
+ * lifecycle). Do not register a separate streaming map.
  */
 import { Readable } from 'stream';
 import { Subject } from 'rxjs';
 import {
-  defineScript,
   defineMediaProviders,
   type MediaConnectorContext,
   type MediaProviderShared,
   type ScriptAsrConnector,
   type ScriptTtsConnector,
+  type ScriptTtsSynthesisContext,
 } from '@voctiv/agent-sdk';
 
 type SharedSession = MediaProviderShared & {
@@ -38,7 +41,8 @@ class EchoAsr implements ScriptAsrConnector {
   }
 
   send(_audio: ArrayBufferLike): void {
-    // Forward PCM to your vendor here.
+    // Forward PCM (S16LE mono 16 kHz) to your vendor here.
+    void this.ctx;
   }
 
   speech(_active: boolean): void {}
@@ -71,7 +75,10 @@ class BatchOrStreamTts implements ScriptTtsConnector {
     return false;
   }
 
-  async textToSpeechStream(rawtext: string): Promise<Readable> {
+  async textToSpeechStream(
+    rawtext: string,
+    _ctx?: ScriptTtsSynthesisContext,
+  ): Promise<Readable> {
     void this.ctx;
     void this.shared;
     // Replace with HTTP keep-alive synthesis that returns a PCM stream.
@@ -103,26 +110,3 @@ export const mediaProviders = defineMediaProviders({
       new BatchOrStreamTts(ctx, shared as SharedSession),
   },
 });
-
-export default defineScript(async ({ channel, logger }) => {
-  channel.sip.answer();
-
-  const asr = await channel.createAsr({ vendor: 'my-asr' });
-  const tts = await channel.createTts({ vendor: 'my-tts' });
-
-  await tts.say('Hello from a custom TTS connector.');
-
-  tts.say$('One. Two.', { alias: 'reply' }).subscribe({
-    next: (ev) => {
-      logger.log('tts utterance', { state: ev.state, alias: ev.itemAlias });
-    },
-    error: (err) => logger.error('tts failed', err),
-  });
-
-  // Same warm handle via audio.say:
-  await channel.audio.say('Reuse handle', { tts });
-
-  asr.destroy();
-  tts.destroy();
-  channel.sip.hangup();
-});

package/examples/outbound-from-invite.ts

@@ -0,0 +1,30 @@
+/**
+ * Campaign outbound that starts at INVITE (`outboundCallMode: 'from_invite'`).
+ *
+ * The host raises the script first, then dials the campaign number on the same
+ * `channel`. 1xx lands on `progress$`; a 4xx/5xx rejects `waitForAnswer()`.
+ * Gate the greeting on the answer so it does not play into ringback.
+ *
+ * `getScriptPhase` stays `'early'` for the whole live run. Read
+ * `channel.sip.isAnswered` for the live state. Billing stays on the 200 OK.
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async ({ channel, logger, context }) => {
+    if (getScriptPhase(context) === 'early') {
+      channel.sip.progress$.subscribe(({ statusCode }) => {
+        logger.log('progress', { statusCode });
+      });
+      try {
+        await channel.sip.waitForAnswer();
+      } catch (err) {
+        logger.warn('outbound failed', { err });
+        return;
+      }
+    }
+
+    await channel.audio.say('Hello!');
+  },
+  { outboundCallMode: 'from_invite' },
+);

package/examples/outbound-on-answer.ts

@@ -0,0 +1,18 @@
+/**
+ * Campaign outbound that starts on the 200 OK (`outboundCallMode: 'on_answer'`).
+ *
+ * This is the default: omit the second argument of `defineScript` and you get
+ * the same timing. The host dials first and holds the script until answer.
+ * Busy / no-answer / 4xx never reach this handler.
+ *
+ * Talk on `channel`. Do not `makeCall()` the campaign number — the host
+ * already did. Billing stays on the 200 OK.
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(async ({ channel, context }) => {
+  // Live outbound: always 'online'. Headless before_call / after_call_* still apply.
+  if (getScriptPhase(context) !== 'online') return;
+
+  await channel.audio.say('Hello!');
+});

package/examples/outbound-script-dial.ts

@@ -0,0 +1,20 @@
+/**
+ * Campaign outbound where the script opens the leg (`outboundCallMode: 'script_dial'`).
+ *
+ * The host does not send an INVITE. Phase is `'dialing'`; the starting `channel`
+ * can only dial. Conversation is on the channel `makeCall()` returns.
+ * `makeCall({})` uses the campaign msisdn + the call row's trunk.
+ *
+ * The first successful dial is the campaign row (result, `answer_date`, recording).
+ */
+import { defineScript, getScriptPhase } from '@voctiv/agent-sdk';
+
+export default defineScript(
+  async (ctx) => {
+    const phase = getScriptPhase(ctx.context);
+    const channel =
+      phase === 'dialing' ? await ctx.channel.sip.makeCall({}) : ctx.channel;
+    await channel.audio.say('Hello!');
+  },
+  { outboundCallMode: 'script_dial' },
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",