@absolutejs/voice 0.0.22-beta.472 → 0.0.22-beta.473

package/dist/index.d.ts

@@ -225,4 +225,6 @@ export { buildVoiceProofPackInput, buildVoiceProofPack, buildVoiceProofPackFromO
 export type { VoiceProofPack, VoiceProofPackBuildContext, VoiceProofPackBuildContextOptions, VoiceProofPackBuildTiming, VoiceProofPackEvidence, VoiceProofPackInput, VoiceProofPackInputBuilderLoaderInput, VoiceProofPackInputBuilderOperationsLoaderInput, VoiceProofPackInputBuilderOptions, VoiceProofPackInputBuilderSupportBundle, VoiceProofPackRefreshState, VoiceProofPackRefreshStatus, VoiceProofPackRoutesOptions, VoiceProofPackSection, VoiceProofPackSourceValue, VoiceProofPackStatus, VoiceProofPackStaleWhileRefreshSource, VoiceProofPackStaleWhileRefreshSourceOptions, VoiceProofPackWriteResult, VoiceProofRefreshSnapshot, VoiceProofRefreshSnapshotOptions, } from "./proofPack";
 export { buildVoiceMultilingualProofReadinessCheck, renderVoiceMultilingualProofMarkdown, runVoiceMultilingualProof, } from "./multilingualProof";
 export type { VoiceMultilingualLanguageCode, VoiceMultilingualProofAdapterEntry, VoiceMultilingualProofAdapterReport, VoiceMultilingualProofDefaultThresholds, VoiceMultilingualProofLanguageMetrics, VoiceMultilingualProofLanguageReport, VoiceMultilingualProofLanguageThresholds, VoiceMultilingualProofOptions, VoiceMultilingualProofReadinessCheck, VoiceMultilingualProofReadinessOptions, VoiceMultilingualProofReport, } from "./multilingualProof";
+export { buildVoiceMonitorPlan, createVoiceInMemoryMonitorRegistry, createVoiceLiveMonitorRoutes, createVoiceMonitorSession, } from "./monitor";
+export type { VoiceMonitorAudioEvent, VoiceMonitorAudioSource, VoiceMonitorAuthenticate, VoiceMonitorAuthenticateInput, VoiceMonitorControlAck, VoiceMonitorControlHandler, VoiceMonitorControlHandlerInput, VoiceMonitorControlMessage, VoiceMonitorMutableRegistry, VoiceMonitorPlan, VoiceMonitorPlanInput, VoiceMonitorRegistry, VoiceMonitorRegistryRegisterInput, VoiceLiveMonitorRoutesOptions, VoiceMonitorSessionRecord, } from "./monitor";
 export * from "./types";

package/dist/index.js

@@ -44454,6 +44454,415 @@ var buildVoiceMultilingualProofReadinessCheck = (report, options = {}) => {
     value: failedAdapters.length
   };
 };
+// src/monitor.ts
+import { Elysia as Elysia70 } from "elysia";
+var buildAudioFanout = () => {
+  const handlers = new Set;
+  return {
+    emit: (event) => {
+      for (const handler of handlers)
+        handler(event);
+    },
+    onAudio: (handler) => {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    }
+  };
+};
+var buildCloseFanout = () => {
+  const handlers = new Set;
+  return {
+    emitClose: (reason) => {
+      for (const handler of handlers)
+        handler(reason);
+    },
+    onClose: (handler) => {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    }
+  };
+};
+var createVoiceMonitorSession = (input) => {
+  const audio = buildAudioFanout();
+  const close = buildCloseFanout();
+  return {
+    emit: audio.emit,
+    emitClose: close.emitClose,
+    handle: input.handle,
+    metadata: input.metadata,
+    onAudio: audio.onAudio,
+    onClose: close.onClose,
+    sessionId: input.sessionId
+  };
+};
+var createVoiceInMemoryMonitorRegistry = () => {
+  const records = new Map;
+  return {
+    emit: (sessionId, event) => {
+      records.get(sessionId)?.emit(event);
+    },
+    emitClose: (sessionId, reason) => {
+      records.get(sessionId)?.emitClose(reason);
+    },
+    get: (sessionId) => records.get(sessionId),
+    list: () => Array.from(records.keys()).map((sessionId) => ({ sessionId })),
+    register: (record) => {
+      const existing = records.get(record.sessionId);
+      if (existing) {
+        throw new Error(`VoiceMonitorRegistry already has a session "${record.sessionId}"; deregister it before re-registering.`);
+      }
+      const wrapped = "emit" in record && typeof record.emit === "function" ? record : createVoiceMonitorSession({
+        handle: record.handle,
+        metadata: record.metadata,
+        sessionId: record.sessionId
+      });
+      if (wrapped !== record) {
+        record.onAudio((event) => wrapped.emit(event));
+        record.onClose((reason) => wrapped.emitClose(reason));
+      }
+      records.set(record.sessionId, wrapped);
+      return () => {
+        records.delete(record.sessionId);
+        wrapped.emitClose("deregistered");
+      };
+    }
+  };
+};
+var buildDefaultControlHandler = (type) => {
+  if (type === "transfer") {
+    return async ({ message, session }) => {
+      if (message.type !== "transfer") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.transfer({
+        metadata: message.metadata,
+        reason: message.reason,
+        target: message.target
+      });
+      return { detail: `Transferred to ${message.target}.`, ok: true, type };
+    };
+  }
+  if (type === "hangup") {
+    return async ({ message, session }) => {
+      if (message.type !== "hangup") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.complete();
+      return {
+        detail: message.reason ? `Hangup: ${message.reason}` : "Hangup.",
+        ok: true,
+        type
+      };
+    };
+  }
+  if (type === "escalate") {
+    return async ({ message, session }) => {
+      if (message.type !== "escalate") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.escalate({
+        metadata: message.metadata,
+        reason: message.reason ?? "monitor-requested-escalation"
+      });
+      return { detail: "Escalated.", ok: true, type };
+    };
+  }
+  if (type === "voicemail") {
+    return async ({ message, session }) => {
+      if (message.type !== "voicemail") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.markVoicemail({ metadata: message.metadata });
+      return { detail: "Voicemail marked.", ok: true, type };
+    };
+  }
+  if (type === "no-answer") {
+    return async ({ message, session }) => {
+      if (message.type !== "no-answer") {
+        return { error: "internal: type mismatch", ok: false, type };
+      }
+      await session.handle.markNoAnswer({ metadata: message.metadata });
+      return { detail: "Marked no-answer.", ok: true, type };
+    };
+  }
+  return;
+};
+var parseControlMessage = (raw) => {
+  if (!raw || typeof raw !== "object")
+    return;
+  const record = raw;
+  const type = record.type;
+  if (typeof type !== "string")
+    return;
+  if (type === "transfer") {
+    if (typeof record.target !== "string")
+      return;
+    return {
+      metadata: record.metadata,
+      reason: typeof record.reason === "string" ? record.reason : undefined,
+      target: record.target,
+      type
+    };
+  }
+  if (type === "hangup") {
+    return {
+      reason: typeof record.reason === "string" ? record.reason : undefined,
+      type
+    };
+  }
+  if (type === "escalate") {
+    return {
+      metadata: record.metadata,
+      reason: typeof record.reason === "string" ? record.reason : undefined,
+      type
+    };
+  }
+  if (type === "voicemail" || type === "no-answer") {
+    return {
+      metadata: record.metadata,
+      type
+    };
+  }
+  if (type === "mute") {
+    if (typeof record.muted !== "boolean" || record.target !== "assistant" && record.target !== "caller") {
+      return;
+    }
+    return { muted: record.muted, target: record.target, type };
+  }
+  if (type === "say") {
+    if (typeof record.text !== "string")
+      return;
+    return {
+      interrupt: typeof record.interrupt === "boolean" ? record.interrupt : undefined,
+      text: record.text,
+      type
+    };
+  }
+  if (type === "inject") {
+    if (typeof record.text !== "string" || record.role !== "assistant" && record.role !== "system" && record.role !== "user") {
+      return;
+    }
+    return { role: record.role, text: record.text, type };
+  }
+  return;
+};
+var DEFAULT_BASE_PATH = "/api/voice/monitor";
+var DEFAULT_LISTEN_PATH = ":sessionId/listen";
+var DEFAULT_CONTROL_PATH = ":sessionId/control";
+var joinPath = (...parts) => parts.filter((part) => part.length > 0).map((part) => part.replace(/^\/+|\/+$/g, "")).filter((part) => part.length > 0).reduce((path, part) => `${path}/${part}`, "");
+var substituteSessionId = (template, sessionId) => template.replace(":sessionId", encodeURIComponent(sessionId));
+var buildVoiceMonitorPlan = (input) => {
+  const basePath = input.basePath ?? DEFAULT_BASE_PATH;
+  const listenTemplate = input.listenPath ?? joinPath(basePath, DEFAULT_LISTEN_PATH);
+  const controlTemplate = input.controlPath ?? joinPath(basePath, DEFAULT_CONTROL_PATH);
+  const baseUrl = input.baseUrl.replace(/\/+$/, "");
+  return {
+    controlUrl: `${baseUrl}${substituteSessionId(controlTemplate, input.sessionId)}`,
+    listenUrl: `${baseUrl}${substituteSessionId(listenTemplate, input.sessionId)}`
+  };
+};
+var resolveSessionId3 = (ws) => {
+  const params = ws.data?.params;
+  if (!params)
+    return;
+  const value = params.sessionId;
+  if (typeof value !== "string" || value.length === 0)
+    return;
+  return value;
+};
+var resolveAuthenticate = async (authenticate, input) => {
+  if (!authenticate)
+    return true;
+  return await authenticate(input);
+};
+var createVoiceLiveMonitorRoutes = (options) => {
+  const basePath = options.basePath ?? DEFAULT_BASE_PATH;
+  const listenPath = options.listenPath === undefined ? joinPath(basePath, DEFAULT_LISTEN_PATH) : options.listenPath;
+  const controlPath = options.controlPath === undefined ? joinPath(basePath, DEFAULT_CONTROL_PATH) : options.controlPath;
+  const handlers = {
+    escalate: options.controlHandlers?.escalate ?? buildDefaultControlHandler("escalate"),
+    hangup: options.controlHandlers?.hangup ?? buildDefaultControlHandler("hangup"),
+    inject: options.controlHandlers?.inject,
+    mute: options.controlHandlers?.mute,
+    "no-answer": options.controlHandlers?.["no-answer"] ?? buildDefaultControlHandler("no-answer"),
+    say: options.controlHandlers?.say,
+    transfer: options.controlHandlers?.transfer ?? buildDefaultControlHandler("transfer"),
+    voicemail: options.controlHandlers?.voicemail ?? buildDefaultControlHandler("voicemail")
+  };
+  const app = new Elysia70({ name: "absolutejs-voice-monitor" });
+  const unsubscribers = new WeakMap;
+  if (listenPath !== false && listenPath.length > 0) {
+    app.ws(`/${listenPath.replace(/^\/+/, "")}`, {
+      close: (ws) => {
+        const subs = unsubscribers.get(ws);
+        if (subs) {
+          for (const unsub of subs)
+            unsub();
+          unsubscribers.delete(ws);
+        }
+      },
+      open: async (ws) => {
+        const webSocket = ws;
+        const sessionId = resolveSessionId3(webSocket);
+        if (!sessionId) {
+          webSocket.send(JSON.stringify({
+            error: "missing sessionId in path params",
+            type: "error"
+          }));
+          webSocket.close(4400, "missing sessionId");
+          return;
+        }
+        const authed = await resolveAuthenticate(options.authenticate, {
+          request: webSocket.raw?.request,
+          route: "listen",
+          sessionId
+        });
+        if (!authed) {
+          webSocket.send(JSON.stringify({ error: "unauthorized", type: "error" }));
+          webSocket.close(4401, "unauthorized");
+          return;
+        }
+        const record = options.registry.get(sessionId);
+        if (!record) {
+          webSocket.send(JSON.stringify({
+            error: `session "${sessionId}" not found`,
+            type: "error"
+          }));
+          webSocket.close(4404, "session not found");
+          return;
+        }
+        const subs = [];
+        webSocket.send(JSON.stringify({
+          sessionId,
+          type: "subscribed"
+        }));
+        subs.push(record.onAudio((event) => {
+          webSocket.send(event.chunk);
+        }));
+        subs.push(record.onClose((reason) => {
+          webSocket.send(JSON.stringify({
+            reason,
+            sessionId,
+            type: "session-closed"
+          }));
+          webSocket.close(1000, reason ?? "session-closed");
+        }));
+        unsubscribers.set(ws, subs);
+      }
+    });
+  }
+  if (controlPath !== false && controlPath.length > 0) {
+    app.ws(`/${controlPath.replace(/^\/+/, "")}`, {
+      close: (ws) => {
+        unsubscribers.delete(ws);
+      },
+      message: async (ws, raw) => {
+        const webSocket = ws;
+        const sessionId = resolveSessionId3(webSocket);
+        if (!sessionId) {
+          webSocket.send(JSON.stringify({
+            error: "missing sessionId in path params",
+            ok: false,
+            type: "error"
+          }));
+          return;
+        }
+        const message = parseControlMessage(raw);
+        if (!message) {
+          webSocket.send(JSON.stringify({
+            error: "invalid control message",
+            ok: false,
+            type: "error"
+          }));
+          return;
+        }
+        const record = options.registry.get(sessionId);
+        if (!record) {
+          webSocket.send(JSON.stringify({
+            error: `session "${sessionId}" not found`,
+            ok: false,
+            type: message.type
+          }));
+          return;
+        }
+        const handler = handlers[message.type];
+        if (!handler) {
+          webSocket.send(JSON.stringify({
+            error: `no handler registered for control type "${message.type}"`,
+            ok: false,
+            type: message.type
+          }));
+          return;
+        }
+        try {
+          const ack = await handler({
+            message,
+            raw,
+            session: record
+          });
+          webSocket.send(JSON.stringify(ack));
+        } catch (error) {
+          webSocket.send(JSON.stringify({
+            error: error instanceof Error ? error.message : String(error),
+            ok: false,
+            type: message.type
+          }));
+        }
+      },
+      open: async (ws) => {
+        const webSocket = ws;
+        const sessionId = resolveSessionId3(webSocket);
+        if (!sessionId) {
+          webSocket.send(JSON.stringify({
+            error: "missing sessionId in path params",
+            type: "error"
+          }));
+          webSocket.close(4400, "missing sessionId");
+          return;
+        }
+        const authed = await resolveAuthenticate(options.authenticate, {
+          request: webSocket.raw?.request,
+          route: "control",
+          sessionId
+        });
+        if (!authed) {
+          webSocket.send(JSON.stringify({ error: "unauthorized", type: "error" }));
+          webSocket.close(4401, "unauthorized");
+          return;
+        }
+        const record = options.registry.get(sessionId);
+        if (!record) {
+          webSocket.send(JSON.stringify({
+            error: `session "${sessionId}" not found`,
+            type: "error"
+          }));
+          webSocket.close(4404, "session not found");
+          return;
+        }
+        webSocket.send(JSON.stringify({
+          sessionId,
+          supports: Object.entries(handlers).filter(([, value]) => value !== undefined).map(([key]) => key),
+          type: "ready"
+        }));
+      }
+    });
+  }
+  if (options.htmlPath !== undefined && options.htmlPath !== false) {
+    const path = options.htmlPath;
+    app.get(path, () => {
+      const sessions = options.registry.list().map((entry) => `<li><code>${entry.sessionId}</code></li>`).join("");
+      const body = `<!doctype html><html lang="en"><head><meta charset="utf-8" /><title>Voice Monitor</title><style>body{background:#0b1216;color:#f6f1e7;font-family:ui-sans-serif,system-ui,sans-serif;margin:0;padding:32px}main{margin:auto;max-width:960px}h1{font-size:clamp(2rem,5vw,3.2rem);letter-spacing:-.04em;margin:.2rem 0 1rem}code{background:#171f25;border:1px solid #2c3a44;border-radius:8px;padding:2px 6px}ul{margin:8px 0;padding-left:18px}p.muted{color:#9aa8b2}</style></head><body><main><h1>Voice Monitor</h1><p class="muted">Active sessions registered with this monitor registry.</p><ul>${sessions || "<li><em>None.</em></li>"}</ul><p class="muted">Open <code>${listenPath}</code> and <code>${controlPath}</code> via WebSocket per session for live listen + control.</p></main></body></html>`;
+      return new Response(body, {
+        headers: { "content-type": "text/html; charset=utf-8" }
+      });
+    });
+  }
+  return app;
+};
 export {
   writeVoiceProofPack,
   writeVoiceMediaPipelineArtifacts,
@@ -44948,6 +45357,7 @@ export {
   createVoiceObservabilityExportRoutes,
   createVoiceObservabilityExportReplayRoutes,
   createVoiceMonitorWebhookNotifier,
+  createVoiceMonitorSession,
   createVoiceMonitorRunnerRoutes,
   createVoiceMonitorRunner,
   createVoiceMonitorRoutes,
@@ -44967,6 +45377,7 @@ export {
   createVoiceMediaPipelineRoutes,
   createVoiceLiveOpsRoutes,
   createVoiceLiveOpsController,
+  createVoiceLiveMonitorRoutes,
   createVoiceLiveLatencyRoutes,
   createVoiceLinearIssueUpdateSink,
   createVoiceLinearIssueSyncSinks,
@@ -44978,6 +45389,7 @@ export {
   createVoiceIncidentTimelineRoutes,
   createVoiceIncidentBundleRoutes,
   createVoiceInMemoryRealCallProfileRecoveryJobStore,
+  createVoiceInMemoryMonitorRegistry,
   createVoiceHubSpotTaskUpdateSink,
   createVoiceHubSpotTaskSyncSinks,
   createVoiceHubSpotTaskSink,
@@ -45153,6 +45565,7 @@ export {
   buildVoiceObservabilityArtifactIndex,
   buildVoiceMultilingualProofReadinessCheck,
   buildVoiceMonitorRunReport,
+  buildVoiceMonitorPlan,
   buildVoiceMediaPipelineReport,
   buildVoiceMediaPipelineReadinessChecks,
   buildVoiceMediaPipelineIncidentEvents,

package/dist/monitor.d.ts

@@ -0,0 +1,138 @@
+import { Elysia } from "elysia";
+import type { AudioFormat, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceMonitorAudioSource = "assistant" | "caller" | (string & {});
+export type VoiceMonitorAudioEvent = {
+    at: number;
+    chunk: Uint8Array;
+    format: AudioFormat;
+    source: VoiceMonitorAudioSource;
+};
+export type VoiceMonitorSessionRecord = {
+    handle: VoiceSessionHandle<unknown, VoiceSessionRecord, unknown>;
+    metadata?: Record<string, unknown>;
+    onAudio: (handler: (event: VoiceMonitorAudioEvent) => void) => () => void;
+    onClose: (handler: (reason?: string) => void) => () => void;
+    sessionId: string;
+};
+export type VoiceMonitorRegistry = {
+    get: (sessionId: string) => VoiceMonitorSessionRecord | undefined;
+    list: () => readonly {
+        sessionId: string;
+    }[];
+};
+export type VoiceMonitorMutableRegistry = VoiceMonitorRegistry & {
+    emit: (sessionId: string, event: VoiceMonitorAudioEvent) => void;
+    emitClose: (sessionId: string, reason?: string) => void;
+    register: (record: VoiceMonitorSessionRecord) => () => void;
+};
+export type VoiceMonitorRegistryRegisterInput = {
+    handle: VoiceSessionHandle<unknown, VoiceSessionRecord, unknown>;
+    metadata?: Record<string, unknown>;
+    sessionId: string;
+};
+export declare const createVoiceMonitorSession: (input: VoiceMonitorRegistryRegisterInput) => VoiceMonitorSessionRecord & {
+    emit: (event: VoiceMonitorAudioEvent) => void;
+    emitClose: (reason?: string) => void;
+};
+export declare const createVoiceInMemoryMonitorRegistry: () => VoiceMonitorMutableRegistry;
+export type VoiceMonitorControlMessage = {
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    target: string;
+    type: "transfer";
+} | {
+    reason?: string;
+    type: "hangup";
+} | {
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    type: "escalate";
+} | {
+    metadata?: Record<string, unknown>;
+    type: "voicemail";
+} | {
+    metadata?: Record<string, unknown>;
+    type: "no-answer";
+} | {
+    muted: boolean;
+    target: "assistant" | "caller";
+    type: "mute";
+} | {
+    interrupt?: boolean;
+    text: string;
+    type: "say";
+} | {
+    role: "assistant" | "system" | "user";
+    text: string;
+    type: "inject";
+};
+export type VoiceMonitorControlAck = {
+    detail?: string;
+    ok: true;
+    type: VoiceMonitorControlMessage["type"];
+} | {
+    error: string;
+    ok: false;
+    type: VoiceMonitorControlMessage["type"];
+};
+export type VoiceMonitorControlHandlerInput = {
+    message: VoiceMonitorControlMessage;
+    raw: unknown;
+    session: VoiceMonitorSessionRecord;
+};
+export type VoiceMonitorControlHandler = (input: VoiceMonitorControlHandlerInput) => Promise<VoiceMonitorControlAck> | VoiceMonitorControlAck;
+export type VoiceMonitorAuthenticateInput = {
+    request: unknown;
+    route: "control" | "listen";
+    sessionId: string;
+};
+export type VoiceMonitorAuthenticate = (input: VoiceMonitorAuthenticateInput) => boolean | Promise<boolean>;
+export type VoiceLiveMonitorRoutesOptions = {
+    authenticate?: VoiceMonitorAuthenticate;
+    basePath?: string;
+    controlHandlers?: Partial<Record<VoiceMonitorControlMessage["type"], VoiceMonitorControlHandler>>;
+    controlPath?: false | string;
+    htmlPath?: false | string;
+    listenPath?: false | string;
+    registry: VoiceMonitorRegistry;
+};
+export type VoiceMonitorPlanInput = {
+    basePath?: string;
+    baseUrl: string;
+    controlPath?: string;
+    listenPath?: string;
+    sessionId: string;
+};
+export type VoiceMonitorPlan = {
+    controlUrl: string;
+    listenUrl: string;
+};
+export declare const buildVoiceMonitorPlan: (input: VoiceMonitorPlanInput) => VoiceMonitorPlan;
+export declare const createVoiceLiveMonitorRoutes: (options: VoiceLiveMonitorRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.472",
+  "version": "0.0.22-beta.473",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",