@kodelyth/voice-call 2026.5.42 → 2026.6.1

package/src/types.ts

@@ -1,311 +0,0 @@
-import { z } from "zod";
-import type { CallMode } from "./config.js";
-
-// -----------------------------------------------------------------------------
-// Provider Identifiers
-// -----------------------------------------------------------------------------
-
-const ProviderNameSchema = z.enum(["telnyx", "twilio", "plivo", "mock"]);
-export type ProviderName = z.infer<typeof ProviderNameSchema>;
-
-// -----------------------------------------------------------------------------
-// Core Call Identifiers
-// -----------------------------------------------------------------------------
-
-/** Internal call identifier (UUID) */
-export type CallId = string;
-
-/** Provider-specific call identifier */
-type ProviderCallId = string;
-
-// -----------------------------------------------------------------------------
-// Call Lifecycle States
-// -----------------------------------------------------------------------------
-
-const CallStateSchema = z.enum([
-  // Non-terminal states
-  "initiated",
-  "ringing",
-  "answered",
-  "active",
-  "speaking",
-  "listening",
-  // Terminal states
-  "completed",
-  "hangup-user",
-  "hangup-bot",
-  "timeout",
-  "error",
-  "failed",
-  "no-answer",
-  "busy",
-  "voicemail",
-]);
-export type CallState = z.infer<typeof CallStateSchema>;
-
-export const TerminalStates = new Set<CallState>([
-  "completed",
-  "hangup-user",
-  "hangup-bot",
-  "timeout",
-  "error",
-  "failed",
-  "no-answer",
-  "busy",
-  "voicemail",
-]);
-
-const EndReasonSchema = z.enum([
-  "completed",
-  "hangup-user",
-  "hangup-bot",
-  "timeout",
-  "error",
-  "failed",
-  "no-answer",
-  "busy",
-  "voicemail",
-]);
-export type EndReason = z.infer<typeof EndReasonSchema>;
-
-// -----------------------------------------------------------------------------
-// Normalized Call Events
-// -----------------------------------------------------------------------------
-
-const BaseEventSchema = z.object({
-  id: z.string(),
-  // Stable provider-derived key for idempotency/replay dedupe.
-  dedupeKey: z.string().optional(),
-  callId: z.string(),
-  providerCallId: z.string().optional(),
-  timestamp: z.number(),
-  // Optional per-turn nonce for speech events (Twilio <Gather> replay hardening).
-  turnToken: z.string().optional(),
-  // Optional fields for inbound call detection
-  direction: z.enum(["inbound", "outbound"]).optional(),
-  from: z.string().optional(),
-  to: z.string().optional(),
-});
-
-const NormalizedEventSchema = z.discriminatedUnion("type", [
-  BaseEventSchema.extend({
-    type: z.literal("call.initiated"),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.ringing"),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.answered"),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.active"),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.speaking"),
-    text: z.string(),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.speech"),
-    transcript: z.string(),
-    isFinal: z.boolean(),
-    confidence: z.number().min(0).max(1).optional(),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.silence"),
-    durationMs: z.number(),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.dtmf"),
-    digits: z.string(),
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.ended"),
-    reason: EndReasonSchema,
-  }),
-  BaseEventSchema.extend({
-    type: z.literal("call.error"),
-    error: z.string(),
-    retryable: z.boolean().optional(),
-  }),
-]);
-export type NormalizedEvent = z.infer<typeof NormalizedEventSchema>;
-
-// -----------------------------------------------------------------------------
-// Call Direction
-// -----------------------------------------------------------------------------
-
-const CallDirectionSchema = z.enum(["outbound", "inbound"]);
-
-// -----------------------------------------------------------------------------
-// Call Record
-// -----------------------------------------------------------------------------
-
-const TranscriptEntrySchema = z.object({
-  timestamp: z.number(),
-  speaker: z.enum(["bot", "user"]),
-  text: z.string(),
-  isFinal: z.boolean().default(true),
-});
-export type TranscriptEntry = z.infer<typeof TranscriptEntrySchema>;
-
-export const CallRecordSchema = z.object({
-  callId: z.string(),
-  providerCallId: z.string().optional(),
-  provider: ProviderNameSchema,
-  direction: CallDirectionSchema,
-  state: CallStateSchema,
-  from: z.string(),
-  to: z.string(),
-  sessionKey: z.string().optional(),
-  startedAt: z.number(),
-  answeredAt: z.number().optional(),
-  endedAt: z.number().optional(),
-  endReason: EndReasonSchema.optional(),
-  transcript: z.array(TranscriptEntrySchema).default([]),
-  processedEventIds: z.array(z.string()).default([]),
-  metadata: z.record(z.string(), z.unknown()).optional(),
-});
-export type CallRecord = z.infer<typeof CallRecordSchema>;
-
-// -----------------------------------------------------------------------------
-// Webhook Types
-// -----------------------------------------------------------------------------
-
-export type WebhookVerificationResult = {
-  ok: boolean;
-  reason?: string;
-  /** Signature is valid, but request was seen before within replay window. */
-  isReplay?: boolean;
-  /** Stable key derived from authenticated request material. */
-  verifiedRequestKey?: string;
-};
-
-export type WebhookParseOptions = {
-  /** Stable request key from verifyWebhook. */
-  verifiedRequestKey?: string;
-};
-
-export type WebhookContext = {
-  headers: Record<string, string | string[] | undefined>;
-  rawBody: string;
-  url: string;
-  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-  query?: Record<string, string | string[] | undefined>;
-  remoteAddress?: string;
-};
-
-export type ProviderWebhookParseResult = {
-  events: NormalizedEvent[];
-  providerResponseBody?: string;
-  providerResponseHeaders?: Record<string, string>;
-  statusCode?: number;
-};
-
-// -----------------------------------------------------------------------------
-// Provider Method Types
-// -----------------------------------------------------------------------------
-
-export type InitiateCallInput = {
-  callId: CallId;
-  from: string;
-  to: string;
-  webhookUrl: string;
-  clientState?: Record<string, string>;
-  /** Inline TwiML to execute without fetching webhook TwiML. */
-  inlineTwiml?: string;
-  /** TwiML to serve once before normal webhook-driven call handling resumes. */
-  preConnectTwiml?: string;
-  /**
-   * Optional `wss://` URL the carrier should open for bidirectional Media
-   * Streaming on call connect. Used by carriers (e.g. Telnyx) that attach
-   * streaming at dial time. Twilio learns the URL from TwiML so it ignores
-   * this field.
-   */
-  streamUrl?: string;
-  /** Per-call auth token the carrier echoes back on the WS upgrade. */
-  streamAuthToken?: string;
-};
-
-export type InitiateCallResult = {
-  providerCallId: ProviderCallId;
-  status: "initiated" | "queued";
-};
-
-export type HangupCallInput = {
-  callId: CallId;
-  providerCallId: ProviderCallId;
-  reason: EndReason;
-};
-
-export type AnswerCallInput = {
-  callId: CallId;
-  providerCallId: ProviderCallId;
-  /**
-   * Optional `wss://` URL the carrier should open for bidirectional Media
-   * Streaming on answer. Used by carriers (e.g. Telnyx) that attach
-   * streaming at answer time. Twilio learns the URL from TwiML so it ignores
-   * this field.
-   */
-  streamUrl?: string;
-  /** Per-call auth token the carrier echoes back on the WS upgrade. */
-  streamAuthToken?: string;
-};
-
-export type PlayTtsInput = {
-  callId: CallId;
-  providerCallId: ProviderCallId;
-  text: string;
-  voice?: string;
-  locale?: string;
-};
-
-export type SendDtmfInput = {
-  callId: CallId;
-  providerCallId: ProviderCallId;
-  digits: string;
-};
-
-export type StartListeningInput = {
-  callId: CallId;
-  providerCallId: ProviderCallId;
-  language?: string;
-  /** Optional per-turn nonce for provider callbacks (replay hardening). */
-  turnToken?: string;
-};
-
-export type StopListeningInput = {
-  callId: CallId;
-  providerCallId: ProviderCallId;
-};
-
-// -----------------------------------------------------------------------------
-// Call Status Verification (used on restart to verify persisted calls)
-// -----------------------------------------------------------------------------
-
-export type GetCallStatusInput = {
-  providerCallId: ProviderCallId;
-};
-
-export type GetCallStatusResult = {
-  /** Provider-specific status string (e.g. "completed", "in-progress") */
-  status: string;
-  /** True when the provider confirms the call has ended */
-  isTerminal: boolean;
-  /** True when the status could not be determined (transient error) */
-  isUnknown?: boolean;
-};
-
-// -----------------------------------------------------------------------------
-// Outbound Call Options
-// -----------------------------------------------------------------------------
-
-export type OutboundCallOptions = {
-  /** Message to speak when call connects */
-  message?: string;
-  /** Call mode (overrides config default) */
-  mode?: CallMode;
-  /** DTMF digits to send after the call is connected */
-  dtmfSequence?: string;
-  /** Session that initiated the call, used for agent context/delegated message routing */
-  requesterSessionKey?: string;
-};

package/src/utils.test.ts

@@ -1,17 +0,0 @@
-import os from "node:os";
-import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { resolveUserPath } from "./utils.js";
-
-describe("resolveUserPath", () => {
-  it("returns trimmed empty input unchanged", () => {
-    expect(resolveUserPath("   ")).toBe("");
-  });
-
-  it("expands tildes and resolves relative paths", () => {
-    expect(resolveUserPath("~/voice-call/config.json")).toBe(
-      path.resolve(os.homedir(), "voice-call/config.json"),
-    );
-    expect(resolveUserPath("./voice-call")).toBe(path.resolve("./voice-call"));
-  });
-});

package/src/utils.ts

@@ -1,14 +0,0 @@
-import os from "node:os";
-import path from "node:path";
-
-export function resolveUserPath(input: string): string {
-  const trimmed = input.trim();
-  if (!trimmed) {
-    return trimmed;
-  }
-  if (trimmed.startsWith("~")) {
-    const expanded = trimmed.replace(/^~(?=$|[\\/])/, os.homedir());
-    return path.resolve(expanded);
-  }
-  return path.resolve(trimmed);
-}

package/src/voice-mapping.test.ts

@@ -1,32 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_POLLY_VOICE,
-  escapeXml,
-  getOpenAiVoiceNames,
-  isOpenAiVoice,
-  mapVoiceToPolly,
-} from "./voice-mapping.js";
-
-describe("voice mapping", () => {
-  it("escapes xml-special characters", () => {
-    expect(escapeXml(`5 < 6 & "quote" 'apostrophe' > 4`)).toBe(
-      "5 &lt; 6 &amp; &quot;quote&quot; &apos;apostrophe&apos; &gt; 4",
-    );
-  });
-
-  it("maps openai voices, passes through provider voices, and falls back to default", () => {
-    expect(mapVoiceToPolly("alloy")).toBe("Polly.Joanna");
-    expect(mapVoiceToPolly("ECHO")).toBe("Polly.Matthew");
-    expect(mapVoiceToPolly("Polly.Brian")).toBe("Polly.Brian");
-    expect(mapVoiceToPolly("Google.en-US-Standard-C")).toBe("Google.en-US-Standard-C");
-    expect(mapVoiceToPolly("unknown")).toBe(DEFAULT_POLLY_VOICE);
-    expect(mapVoiceToPolly(undefined)).toBe(DEFAULT_POLLY_VOICE);
-  });
-
-  it("detects known openai voices and lists them", () => {
-    expect(isOpenAiVoice("nova")).toBe(true);
-    expect(isOpenAiVoice("NOVA")).toBe(true);
-    expect(isOpenAiVoice("Polly.Joanna")).toBe(false);
-    expect(getOpenAiVoiceNames()).toEqual(["alloy", "echo", "fable", "onyx", "nova", "shimmer"]);
-  });
-});

package/src/voice-mapping.ts

@@ -1,65 +0,0 @@
-import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
-
-/**
- * Escape XML special characters for TwiML and other XML responses.
- */
-export function escapeXml(text: string): string {
-  return text
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
-/**
- * Map of OpenAI voice names to similar Twilio Polly voices.
- */
-const OPENAI_TO_POLLY_MAP: Record<string, string> = {
-  alloy: "Polly.Joanna", // neutral, warm
-  echo: "Polly.Matthew", // male, warm
-  fable: "Polly.Amy", // British, expressive
-  onyx: "Polly.Brian", // deep male
-  nova: "Polly.Salli", // female, friendly
-  shimmer: "Polly.Kimberly", // female, clear
-};
-
-/**
- * Default Polly voice when no mapping is found.
- */
-export const DEFAULT_POLLY_VOICE = "Polly.Joanna";
-
-/**
- * Map OpenAI voice names to Twilio Polly equivalents.
- * Falls through if already a valid Polly/Google voice.
- *
- * @param voice - OpenAI voice name (alloy, echo, etc.) or Polly voice name
- * @returns Polly voice name suitable for Twilio TwiML
- */
-export function mapVoiceToPolly(voice: string | undefined): string {
-  if (!voice) {
-    return DEFAULT_POLLY_VOICE;
-  }
-
-  // Already a Polly/Google voice - pass through
-  if (voice.startsWith("Polly.") || voice.startsWith("Google.")) {
-    return voice;
-  }
-
-  // Map OpenAI voices to Polly equivalents
-  return OPENAI_TO_POLLY_MAP[normalizeLowercaseStringOrEmpty(voice)] || DEFAULT_POLLY_VOICE;
-}
-
-/**
- * Check if a voice name is a known OpenAI voice.
- */
-export function isOpenAiVoice(voice: string): boolean {
-  return normalizeLowercaseStringOrEmpty(voice) in OPENAI_TO_POLLY_MAP;
-}
-
-/**
- * Get all supported OpenAI voice names.
- */
-export function getOpenAiVoiceNames(): string[] {
-  return Object.keys(OPENAI_TO_POLLY_MAP);
-}

package/src/webhook/realtime-audio-pacer.test.ts

@@ -1,146 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import {
-  RealtimeAudioPacer,
-  RealtimeMulawSpeechStartDetector,
-  calculateMulawRms,
-  type RealtimeAudioSerializer,
-} from "./realtime-audio-pacer.js";
-
-function createTwilioSerializer(streamSid: string): RealtimeAudioSerializer {
-  return {
-    media: (payload) => JSON.stringify({ event: "media", streamSid, media: { payload } }),
-    clear: () => JSON.stringify({ event: "clear", streamSid }),
-    mark: (name) => JSON.stringify({ event: "mark", streamSid, mark: { name } }),
-  };
-}
-
-function createTelnyxSerializer(): RealtimeAudioSerializer {
-  return {
-    media: (payload) => JSON.stringify({ event: "media", media: { payload } }),
-    clear: () => JSON.stringify({ event: "clear" }),
-    mark: (name) => JSON.stringify({ event: "mark", mark: { name } }),
-  };
-}
-
-describe("RealtimeAudioPacer", () => {
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("paces realtime audio as 20ms telephony frames before marks (Twilio shape)", async () => {
-    vi.useFakeTimers();
-    const sent: unknown[] = [];
-    const pacer = new RealtimeAudioPacer({
-      serializer: createTwilioSerializer("MZ-test"),
-      send: (message) => {
-        sent.push(JSON.parse(message));
-        return true;
-      },
-    });
-
-    pacer.sendAudio(Buffer.alloc(320, 0x7f));
-    pacer.sendMark("audio-1");
-
-    expect(sent).toHaveLength(1);
-    expect(
-      Buffer.from((sent[0] as { media: { payload: string } }).media.payload, "base64"),
-    ).toHaveLength(160);
-
-    await vi.advanceTimersByTimeAsync(20);
-    expect(sent).toHaveLength(2);
-    expect(
-      Buffer.from((sent[1] as { media: { payload: string } }).media.payload, "base64"),
-    ).toHaveLength(160);
-
-    await vi.advanceTimersByTimeAsync(20);
-    expect(sent[2]).toEqual({
-      event: "mark",
-      streamSid: "MZ-test",
-      mark: { name: "audio-1" },
-    });
-  });
-
-  it("clears queued audio immediately (Twilio shape)", async () => {
-    vi.useFakeTimers();
-    const sent: unknown[] = [];
-    const pacer = new RealtimeAudioPacer({
-      serializer: createTwilioSerializer("MZ-test"),
-      send: (message) => {
-        sent.push(JSON.parse(message));
-        return true;
-      },
-    });
-
-    pacer.sendAudio(Buffer.alloc(480, 0x7f));
-    pacer.clearAudio();
-    await vi.advanceTimersByTimeAsync(100);
-
-    expect(sent).toHaveLength(2);
-    expect(sent[1]).toEqual({ event: "clear", streamSid: "MZ-test" });
-  });
-
-  it("stops instead of buffering unbounded realtime audio", async () => {
-    vi.useFakeTimers();
-    const sent: unknown[] = [];
-    const onBackpressure = vi.fn();
-    const pacer = new RealtimeAudioPacer({
-      serializer: createTwilioSerializer("MZ-test"),
-      maxQueuedAudioBytes: 320,
-      onBackpressure,
-      send: (message) => {
-        sent.push(JSON.parse(message));
-        return true;
-      },
-    });
-
-    pacer.sendAudio(Buffer.alloc(480, 0x7f));
-    pacer.sendMark("after-overflow");
-    await vi.advanceTimersByTimeAsync(100);
-
-    expect(onBackpressure).toHaveBeenCalledOnce();
-    expect(sent).toStrictEqual([]);
-  });
-
-  it("paces audio in Telnyx envelope shape (no streamSid)", async () => {
-    vi.useFakeTimers();
-    const sent: unknown[] = [];
-    const pacer = new RealtimeAudioPacer({
-      serializer: createTelnyxSerializer(),
-      send: (message) => {
-        sent.push(JSON.parse(message));
-        return true;
-      },
-    });
-
-    pacer.sendAudio(Buffer.alloc(160, 0x7f));
-    pacer.clearAudio();
-    await vi.advanceTimersByTimeAsync(100);
-
-    expect(sent).toEqual([
-      { event: "media", media: { payload: Buffer.alloc(160, 0x7f).toString("base64") } },
-      { event: "clear" },
-    ]);
-  });
-});
-
-describe("RealtimeMulawSpeechStartDetector", () => {
-  it("detects a speech start after consecutive loud chunks and resets after quiet", () => {
-    const detector = new RealtimeMulawSpeechStartDetector({
-      requiredLoudChunks: 2,
-      requiredQuietChunks: 2,
-      rmsThreshold: 0.02,
-    });
-    const silence = Buffer.alloc(160, 0xff);
-    const speech = Buffer.alloc(160, 0x00);
-
-    expect(calculateMulawRms(silence)).toBeLessThan(0.02);
-    expect(calculateMulawRms(speech)).toBeGreaterThan(0.02);
-    expect(detector.accept(speech)).toBe(false);
-    expect(detector.accept(speech)).toBe(true);
-    expect(detector.accept(speech)).toBe(false);
-    expect(detector.accept(silence)).toBe(false);
-    expect(detector.accept(silence)).toBe(false);
-    expect(detector.accept(speech)).toBe(false);
-    expect(detector.accept(speech)).toBe(true);
-  });
-});