@absolutejs/voice 0.0.22-beta.29 → 0.0.22-beta.30

package/dist/handoffHealth.d.ts

@@ -0,0 +1,94 @@
+import { Elysia } from 'elysia';
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore } from './trace';
+export type VoiceHandoffHealthStatus = 'delivered' | 'failed' | 'skipped';
+export type VoiceHandoffHealthDelivery = {
+    adapterId: string;
+    adapterKind?: string;
+    deliveredAt?: number;
+    deliveredTo?: string;
+    error?: string;
+    status: VoiceHandoffHealthStatus;
+};
+export type VoiceHandoffHealthEvent = {
+    action?: string;
+    at: number;
+    deliveries: VoiceHandoffHealthDelivery[];
+    reason?: string;
+    replayHref?: string;
+    sessionId: string;
+    status: VoiceHandoffHealthStatus;
+    target?: string;
+};
+export type VoiceHandoffHealthSummary = {
+    byAction: Record<string, number>;
+    byAdapter: Record<string, Record<VoiceHandoffHealthStatus, number>>;
+    byStatus: Record<VoiceHandoffHealthStatus, number>;
+    events: VoiceHandoffHealthEvent[];
+    failed: number;
+    total: number;
+};
+export type VoiceHandoffHealthSummaryOptions = {
+    events?: StoredVoiceTraceEvent[];
+    limit?: number;
+    q?: string;
+    replayHref?: false | string | ((event: Omit<VoiceHandoffHealthEvent, 'replayHref'>) => string);
+    status?: VoiceHandoffHealthStatus | 'all';
+    store?: VoiceTraceEventStore;
+};
+export type VoiceHandoffHealthHTMLHandlerOptions = VoiceHandoffHealthSummaryOptions & {
+    headers?: HeadersInit;
+    render?: (summary: VoiceHandoffHealthSummary) => string | Promise<string>;
+};
+export type VoiceHandoffHealthRoutesOptions = VoiceHandoffHealthHTMLHandlerOptions & {
+    htmlPath?: false | string;
+    name?: string;
+    path?: string;
+};
+export declare const summarizeVoiceHandoffHealth: (options?: VoiceHandoffHealthSummaryOptions) => Promise<VoiceHandoffHealthSummary>;
+export declare const renderVoiceHandoffHealthHTML: (summary: VoiceHandoffHealthSummary) => string;
+export declare const createVoiceHandoffHealthJSONHandler: (options?: VoiceHandoffHealthSummaryOptions) => ({ query }: {
+    query?: Record<string, string | undefined>;
+}) => Promise<VoiceHandoffHealthSummary>;
+export declare const createVoiceHandoffHealthHTMLHandler: (options?: VoiceHandoffHealthHTMLHandlerOptions) => ({ query }: {
+    query?: Record<string, string | undefined>;
+}) => Promise<Response>;
+export declare const createVoiceHandoffHealthRoutes: (options?: VoiceHandoffHealthRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceHandoffHealthSummary;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { createVoiceMemoryStore } from './memoryStore';
 export { createVoiceCRMActivitySink, createVoiceHelpdeskTicketSink, createVoiceIntegrationHTTPSink, createVoiceHubSpotTaskSink, createVoiceHubSpotTaskSyncSinks, createVoiceHubSpotTaskUpdateSink, createVoiceLinearIssueSink, createVoiceLinearIssueSyncSinks, createVoiceLinearIssueUpdateSink, createVoiceZendeskTicketSink, createVoiceZendeskTicketSyncSinks, createVoiceZendeskTicketUpdateSink, deliverVoiceIntegrationEventToSinks } from './opsSinks';
 export { createVoiceOpsWebhookEnvelope, createVoiceOpsWebhookReceiverRoutes, createVoiceOpsWebhookSink, verifyVoiceOpsWebhookSignature } from './opsWebhook';
 export { createVoiceTwilioRedirectHandoffAdapter, createVoiceWebhookHandoffAdapter, deliverVoiceHandoff } from './handoff';
+export { createVoiceHandoffHealthHTMLHandler, createVoiceHandoffHealthJSONHandler, createVoiceHandoffHealthRoutes, renderVoiceHandoffHealthHTML, summarizeVoiceHandoffHealth } from './handoffHealth';
 export { createVoiceIntegrationSinkWorker, createVoiceIntegrationSinkWorkerLoop, createVoiceOpsTaskWorker, createVoiceOpsTaskProcessorWorker, createVoiceOpsTaskProcessorWorkerLoop, createVoiceRedisIdempotencyStore, createVoiceRedisTaskLeaseCoordinator, createVoiceTraceSinkDeliveryWorker, createVoiceTraceSinkDeliveryWorkerLoop, createVoiceWebhookDeliveryWorker, createVoiceWebhookDeliveryWorkerLoop, summarizeVoiceTraceSinkDeliveries, summarizeVoiceOpsTaskQueue, summarizeVoiceIntegrationEvents } from './queue';
 export { assignVoiceOpsTask, applyVoiceOpsTaskAssignmentRule, applyVoiceOpsTaskPolicy, buildVoiceOpsTaskFromReview, buildVoiceOpsTaskFromSLABreach, claimVoiceOpsTask, completeVoiceOpsTask, createVoiceExternalObjectMap, createVoiceExternalObjectMapId, createVoiceCallCompletedEvent, createVoiceTaskSLABreachedEvent, deadLetterVoiceOpsTask, deliverVoiceIntegrationEvent, failVoiceOpsTask, hasVoiceOpsTaskSLABreach, heartbeatVoiceOpsTask, isVoiceOpsTaskOverdue, markVoiceOpsTaskSLABreached, matchesVoiceOpsTaskAssignmentRule, resolveVoiceOpsTaskAgeBucket, createVoiceIntegrationEvent, createVoiceReviewSavedEvent, resolveVoiceOpsTaskAssignment, resolveVoiceOpsTaskPolicy, requeueVoiceOpsTask, createVoiceTaskCreatedEvent, createVoiceTaskUpdatedEvent, listVoiceOpsTasks, reopenVoiceOpsTask, startVoiceOpsTask, summarizeVoiceOpsTaskAnalytics, summarizeVoiceOpsTasks, withVoiceIntegrationEventId, withVoiceOpsTaskId } from './ops';
 export { createVoiceSession } from './session';
@@ -42,6 +43,7 @@ export type { VoiceOutcomeRecipe, VoiceOutcomeRecipeName, VoiceOutcomeRecipeOpti
 export type { VoiceCRMActivitySinkOptions, VoiceHubSpotTaskSinkOptions, VoiceHubSpotTaskUpdateSinkOptions, VoiceHelpdeskTicketSinkOptions, VoiceIntegrationHTTPSinkOptions, VoiceIntegrationSink, VoiceIntegrationSinkDeliveryResult, VoiceLinearIssueSinkOptions, VoiceLinearIssueUpdateSinkOptions, VoiceZendeskTicketSinkOptions, VoiceZendeskTicketUpdateSinkOptions } from './opsSinks';
 export type { VoiceOpsWebhookEnvelope, VoiceOpsWebhookEntity, VoiceOpsWebhookLinkResolver, VoiceOpsWebhookReceiverRoutesOptions, VoiceOpsWebhookSinkOptions, VoiceOpsWebhookVerificationResult } from './opsWebhook';
 export type { VoiceHandoffDelivery, VoiceHandoffFanoutResult, VoiceTwilioRedirectHandoffAdapterOptions, VoiceWebhookHandoffAdapterOptions } from './handoff';
+export type { VoiceHandoffHealthDelivery, VoiceHandoffHealthEvent, VoiceHandoffHealthHTMLHandlerOptions, VoiceHandoffHealthRoutesOptions, VoiceHandoffHealthStatus, VoiceHandoffHealthSummary, VoiceHandoffHealthSummaryOptions } from './handoffHealth';
 export type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewConfig, VoiceCallReviewPostCallSummary, VoiceCallReviewRecorder, VoiceCallReviewRecorderOptions, VoiceCallReviewStore, VoiceCallReviewSummary, VoiceCallReviewTimelineEvent } from './testing/review';
 export type { VoiceFileRuntimeStorage, VoiceFileStoreOptions } from './fileStore';
 export type { StoredVoiceTraceEvent, VoiceTraceEvaluation, VoiceTraceEvaluationOptions, VoiceTraceEvent, VoiceTraceEventFilter, VoiceTraceEventStore, VoiceTraceEventType, VoiceTraceIssue, VoiceTraceIssueSeverity, VoiceTraceHTTPSinkOptions, VoiceTracePruneFilter, VoiceTracePruneOptions, VoiceTracePruneResult, VoiceTraceRedactionConfig, VoiceTraceRedactionOptions, VoiceTraceRedactionReplacement, VoiceResolvedTraceRedactionOptions, VoiceTraceSink, VoiceTraceSinkDeliveryQueueStatus, VoiceTraceSinkDeliveryRecord, VoiceTraceSinkDeliveryResult, VoiceTraceSinkDeliveryStatus, VoiceTraceSinkDeliveryStore, VoiceTraceSinkFanoutResult, VoiceTraceSinkStoreOptions, VoiceTraceSummary } from './trace';

package/dist/index.js

@@ -9362,6 +9362,198 @@ var createVoiceOpsWebhookReceiverRoutes = (options = {}) => {
     parse: "text"
   });
 };
+// src/handoffHealth.ts
+import { Elysia as Elysia6 } from "elysia";
+var escapeHtml7 = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+var getString4 = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
+var isStatus = (value) => value === "delivered" || value === "failed" || value === "skipped";
+var increment3 = (record, key) => {
+  record[key] = (record[key] ?? 0) + 1;
+};
+var normalizeDelivery = (adapterId, value) => {
+  const record = value && typeof value === "object" ? value : {};
+  return {
+    adapterId: getString4(record.adapterId) ?? adapterId,
+    adapterKind: getString4(record.adapterKind),
+    deliveredAt: typeof record.deliveredAt === "number" ? record.deliveredAt : undefined,
+    deliveredTo: getString4(record.deliveredTo),
+    error: getString4(record.error),
+    status: isStatus(record.status) ? record.status : "failed"
+  };
+};
+var normalizeDeliveries = (payload) => {
+  const deliveries = payload.deliveries;
+  if (!deliveries || typeof deliveries !== "object") {
+    return [];
+  }
+  return Object.entries(deliveries).map(([adapterId, value]) => normalizeDelivery(adapterId, value));
+};
+var resolveReplayHref = (event, replayHref) => {
+  if (replayHref === false) {
+    return;
+  }
+  if (typeof replayHref === "function") {
+    return replayHref(event);
+  }
+  return `${replayHref ?? "/api/voice-sessions"}/${encodeURIComponent(event.sessionId)}/replay/htmx`;
+};
+var summarizeVoiceHandoffHealth = async (options = {}) => {
+  const sourceEvents = options.events ?? await options.store?.list() ?? [];
+  const search = options.q?.trim().toLowerCase();
+  const byAction = {};
+  const byAdapter = {};
+  const byStatus = {
+    delivered: 0,
+    failed: 0,
+    skipped: 0
+  };
+  const events = sourceEvents.filter((event) => event.type === "call.handoff").map((event) => {
+    const status = isStatus(event.payload.status) ? event.payload.status : "failed";
+    const deliveries = normalizeDeliveries(event.payload);
+    const item = {
+      action: getString4(event.payload.action),
+      at: event.at,
+      deliveries,
+      reason: getString4(event.payload.reason),
+      sessionId: event.sessionId,
+      status,
+      target: getString4(event.payload.target)
+    };
+    return {
+      ...item,
+      replayHref: resolveReplayHref(item, options.replayHref)
+    };
+  }).filter((event) => {
+    if (options.status && options.status !== "all" && event.status !== options.status) {
+      return false;
+    }
+    if (!search) {
+      return true;
+    }
+    return [
+      event.action,
+      event.reason,
+      event.sessionId,
+      event.status,
+      event.target,
+      ...event.deliveries.flatMap((delivery) => [
+        delivery.adapterId,
+        delivery.adapterKind,
+        delivery.deliveredTo,
+        delivery.error,
+        delivery.status
+      ])
+    ].some((value) => value?.toLowerCase().includes(search));
+  }).sort((left, right) => right.at - left.at).slice(0, options.limit ?? 50);
+  for (const event of events) {
+    byStatus[event.status] += 1;
+    if (event.action) {
+      increment3(byAction, event.action);
+    }
+    for (const delivery of event.deliveries) {
+      byAdapter[delivery.adapterId] ??= {
+        delivered: 0,
+        failed: 0,
+        skipped: 0
+      };
+      byAdapter[delivery.adapterId][delivery.status] += 1;
+    }
+  }
+  return {
+    byAction,
+    byAdapter,
+    byStatus,
+    events,
+    failed: byStatus.failed,
+    total: events.length
+  };
+};
+var renderMetricGrid = (summary) => [
+  '<section class="voice-handoff-health-grid">',
+  `<article><span>Total</span><strong>${String(summary.total)}</strong></article>`,
+  `<article><span>Delivered</span><strong>${String(summary.byStatus.delivered)}</strong></article>`,
+  `<article><span>Failed</span><strong>${String(summary.byStatus.failed)}</strong></article>`,
+  `<article><span>Skipped</span><strong>${String(summary.byStatus.skipped)}</strong></article>`,
+  "</section>"
+].join("");
+var renderActionSummary = (summary) => {
+  const actions = Object.entries(summary.byAction).sort((left, right) => right[1] - left[1]);
+  const adapters = Object.entries(summary.byAdapter).sort(([left], [right]) => left.localeCompare(right));
+  return [
+    '<section class="voice-handoff-health-columns">',
+    "<article><h3>Actions</h3>",
+    actions.length === 0 ? "<p>No handoff actions yet.</p>" : `<ul>${actions.map(([action, count]) => `<li>${escapeHtml7(action)}: ${String(count)}</li>`).join("")}</ul>`,
+    "</article>",
+    "<article><h3>Adapters</h3>",
+    adapters.length === 0 ? "<p>No adapter deliveries yet.</p>" : `<ul>${adapters.map(([adapterId, counts]) => `<li>${escapeHtml7(adapterId)}: ${String(counts.delivered)} delivered / ${String(counts.failed)} failed / ${String(counts.skipped)} skipped</li>`).join("")}</ul>`,
+    "</article>",
+    "</section>"
+  ].join("");
+};
+var renderVoiceHandoffHealthHTML = (summary) => [
+  '<div class="voice-handoff-health">',
+  renderMetricGrid(summary),
+  renderActionSummary(summary),
+  "<section>",
+  "<h3>Recent Handoffs</h3>",
+  summary.events.length === 0 ? '<p class="voice-handoff-health-empty">No handoffs found.</p>' : [
+    '<div class="voice-handoff-health-events">',
+    ...summary.events.map((event) => [
+      `<article class="${escapeHtml7(event.status)}">`,
+      '<div class="voice-handoff-health-event-header">',
+      `<strong>${escapeHtml7(event.action ?? "handoff")}</strong>`,
+      `<span>${escapeHtml7(event.status)}</span>`,
+      "</div>",
+      `<p><small>${escapeHtml7(event.sessionId)}</small></p>`,
+      event.target ? `<p>Target: ${escapeHtml7(event.target)}</p>` : "",
+      event.reason ? `<p>Reason: ${escapeHtml7(event.reason)}</p>` : "",
+      event.deliveries.length ? `<ul>${event.deliveries.map((delivery) => [
+        "<li>",
+        `${escapeHtml7(delivery.adapterId)}: ${escapeHtml7(delivery.status)}`,
+        delivery.deliveredTo ? ` to ${escapeHtml7(delivery.deliveredTo)}` : "",
+        delivery.error ? ` (${escapeHtml7(delivery.error)})` : "",
+        "</li>"
+      ].join("")).join("")}</ul>` : "",
+      event.replayHref ? `<p><a href="${escapeHtml7(event.replayHref)}">Open replay</a></p>` : "",
+      "</article>"
+    ].join("")),
+    "</div>"
+  ].join(""),
+  "</section>",
+  "</div>"
+].join("");
+var createVoiceHandoffHealthJSONHandler = (options = {}) => async ({ query }) => summarizeVoiceHandoffHealth({
+  ...options,
+  limit: typeof query?.limit === "string" ? Number(query.limit) : options.limit,
+  q: query?.q ?? options.q,
+  status: query?.status === "delivered" || query?.status === "failed" || query?.status === "skipped" || query?.status === "all" ? query.status : options.status
+});
+var createVoiceHandoffHealthHTMLHandler = (options = {}) => async ({ query }) => {
+  const summary = await summarizeVoiceHandoffHealth({
+    ...options,
+    limit: typeof query?.limit === "string" ? Number(query.limit) : options.limit,
+    q: query?.q ?? options.q,
+    status: query?.status === "delivered" || query?.status === "failed" || query?.status === "skipped" || query?.status === "all" ? query.status : options.status
+  });
+  const body = await (options.render?.(summary) ?? renderVoiceHandoffHealthHTML(summary));
+  return new Response(body, {
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+      ...options.headers
+    }
+  });
+};
+var createVoiceHandoffHealthRoutes = (options = {}) => {
+  const path = options.path ?? "/api/voice-handoffs";
+  const htmlPath = options.htmlPath === undefined ? `${path}/htmx` : options.htmlPath;
+  const routes = new Elysia6({
+    name: options.name ?? "absolutejs-voice-handoff-health"
+  }).get(path, createVoiceHandoffHealthJSONHandler(options));
+  if (htmlPath) {
+    routes.get(htmlPath, createVoiceHandoffHealthHTMLHandler(options));
+  }
+  return routes;
+};
 // src/queue.ts
 var releaseLeaseScript = `
 if redis.call("GET", KEYS[1]) == ARGV[1] then
@@ -11339,6 +11531,7 @@ export {
   summarizeVoiceOpsTaskQueue,
   summarizeVoiceOpsTaskAnalytics,
   summarizeVoiceIntegrationEvents,
+  summarizeVoiceHandoffHealth,
   summarizeVoiceAssistantRuns,
   summarizeVoiceAssistantHealth,
   startVoiceOpsTask,
@@ -11361,6 +11554,7 @@ export {
   renderVoiceTraceHTML,
   renderVoiceSessionsHTML,
   renderVoiceProviderHealthHTML,
+  renderVoiceHandoffHealthHTML,
   renderVoiceCallReviewMarkdown,
   renderVoiceCallReviewHTML,
   renderVoiceAssistantHealthHTML,
@@ -11459,6 +11653,9 @@ export {
   createVoiceHubSpotTaskSyncSinks,
   createVoiceHubSpotTaskSink,
   createVoiceHelpdeskTicketSink,
+  createVoiceHandoffHealthRoutes,
+  createVoiceHandoffHealthJSONHandler,
+  createVoiceHandoffHealthHTMLHandler,
   createVoiceFileTraceSinkDeliveryStore,
   createVoiceFileTraceEventStore,
   createVoiceFileTaskStore,

package/package.json

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