@absolutejs/voice 0.0.22-beta.111 → 0.0.22-beta.113

package/dist/campaign.d.ts

@@ -1,4 +1,5 @@
 import { Elysia } from 'elysia';
+import type { VoiceRedisTaskLeaseCoordinator } from './queue';
 export type VoiceCampaignStatus = 'canceled' | 'completed' | 'draft' | 'paused' | 'running';
 export type VoiceCampaignRecipientStatus = 'canceled' | 'completed' | 'failed' | 'pending' | 'queued';
 export type VoiceCampaignAttemptStatus = 'canceled' | 'failed' | 'queued' | 'running' | 'succeeded';
@@ -153,17 +154,116 @@ export type VoiceCampaignRuntime = {
 export type VoiceCampaignRoutesOptions = VoiceCampaignRuntimeOptions & {
     headers?: HeadersInit;
     htmlPath?: false | string;
+    observability?: VoiceCampaignObservabilityOptions;
     name?: string;
     path?: string;
     title?: string;
 };
+export type VoiceCampaignWorkerOptions = {
+    campaignIds?: string[];
+    leaseMs?: number;
+    leases: VoiceRedisTaskLeaseCoordinator;
+    maxCampaigns?: number;
+    runtime?: VoiceCampaignRuntime;
+    statuses?: VoiceCampaignStatus[];
+    store?: VoiceCampaignStore;
+    workerId: string;
+};
+export type VoiceCampaignWorkerResult = {
+    attempted: number;
+    campaigns: number;
+    errors: Array<{
+        campaignId: string;
+        error: string;
+    }>;
+    skipped: number;
+    started: VoiceCampaignAttempt[];
+};
+export type VoiceCampaignWorker = {
+    drain: () => Promise<VoiceCampaignWorkerResult>;
+};
+export type VoiceCampaignWorkerLoopOptions = {
+    onError?: (error: unknown) => void | Promise<void>;
+    pollIntervalMs?: number;
+    worker: VoiceCampaignWorker;
+};
+export type VoiceCampaignWorkerLoop = {
+    isRunning: () => boolean;
+    start: () => void;
+    stop: () => void;
+    tick: () => Promise<VoiceCampaignWorkerResult>;
+};
+export type VoiceCampaignObservabilityOptions = {
+    leases?: VoiceRedisTaskLeaseCoordinator;
+    now?: number;
+    rateWindowMs?: number;
+    stuckAfterMs?: number;
+};
+export type VoiceCampaignObservabilityReport = {
+    attemptRate: {
+        failed: number;
+        started: number;
+        succeeded: number;
+        windowMs: number;
+    };
+    campaigns: Array<{
+        activeAttempts: number;
+        campaignId: string;
+        lease?: {
+            expiresAt: number;
+            workerId: string;
+        };
+        name: string;
+        queueDepth: number;
+        status: VoiceCampaignStatus;
+        stuckAttempts: number;
+        stuckRecipients: number;
+        updatedAt: number;
+    }>;
+    failureReasons: Array<{
+        count: number;
+        reason: string;
+    }>;
+    generatedAt: number;
+    leases: {
+        active: number;
+        known: boolean;
+    };
+    queue: {
+        activeAttempts: number;
+        queuedRecipients: number;
+        runningCampaigns: number;
+    };
+    stuck: {
+        attempts: Array<{
+            attemptId: string;
+            campaignId: string;
+            recipientId: string;
+            status: VoiceCampaignAttemptStatus;
+            updatedAt: number;
+        }>;
+        recipients: Array<{
+            campaignId: string;
+            recipientId: string;
+            status: VoiceCampaignRecipientStatus;
+            updatedAt: number;
+        }>;
+    };
+    summary: VoiceCampaignSummary;
+};
 export declare const createVoiceMemoryCampaignStore: () => VoiceCampaignStore;
 export declare const summarizeVoiceCampaigns: (records: VoiceCampaignRecord[]) => VoiceCampaignSummary;
+export declare const buildVoiceCampaignObservabilityReport: (records: VoiceCampaignRecord[], options?: VoiceCampaignObservabilityOptions) => Promise<VoiceCampaignObservabilityReport>;
 export declare const createVoiceCampaign: (options: VoiceCampaignRuntimeOptions) => VoiceCampaignRuntime;
+export declare const createVoiceCampaignWorker: (options: VoiceCampaignWorkerOptions) => VoiceCampaignWorker;
+export declare const createVoiceCampaignWorkerLoop: (options: VoiceCampaignWorkerLoopOptions) => VoiceCampaignWorkerLoop;
 export declare const runVoiceCampaignProof: (options?: VoiceCampaignProofOptions) => Promise<VoiceCampaignProofReport>;
 export declare const renderVoiceCampaignsHTML: (records: VoiceCampaignRecord[], options?: {
     title?: string;
 }) => string;
+export declare const renderVoiceCampaignObservabilityHTML: (report: VoiceCampaignObservabilityReport, options?: {
+    title?: string;
+}) => string;
 export declare const createVoiceCampaignRoutes: (options: VoiceCampaignRoutesOptions) => Elysia<"", {
     decorator: {};
     store: {};
@@ -194,6 +294,20 @@ export declare const createVoiceCampaignRoutes: (options: VoiceCampaignRoutesOpt
             };
         };
     };
+} & {
+    [x: string]: {
+        observability: {
+            get: {
+                body: unknown;
+                params: {};
+                query: unknown;
+                headers: unknown;
+                response: {
+                    200: VoiceCampaignObservabilityReport;
+                };
+            };
+        };
+    };
 } & {
     [x: string]: {
         post: {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { voice } from './plugin';
 export { createVoiceAppKit, createVoiceAppKitRoutes, summarizeVoiceAppKitStatus } from './appKit';
-export { createVoiceCampaign, createVoiceCampaignRoutes, createVoiceMemoryCampaignStore, renderVoiceCampaignsHTML, runVoiceCampaignProof, summarizeVoiceCampaigns } from './campaign';
+export { buildVoiceCampaignObservabilityReport, createVoiceCampaign, createVoiceCampaignRoutes, createVoiceCampaignWorker, createVoiceCampaignWorkerLoop, createVoiceMemoryCampaignStore, renderVoiceCampaignObservabilityHTML, renderVoiceCampaignsHTML, runVoiceCampaignProof, summarizeVoiceCampaigns } from './campaign';
 export { createVoiceAssistant, createVoiceExperiment, summarizeVoiceAssistantRuns } from './assistant';
 export { createVoiceAssistantHealthHTMLHandler, createVoiceAssistantHealthJSONHandler, createVoiceAssistantHealthRoutes, renderVoiceAssistantHealthHTML, summarizeVoiceAssistantHealth } from './assistantHealth';
 export { createVoiceBargeInRoutes, renderVoiceBargeInHTML, summarizeVoiceBargeIn } from './bargeInRoutes';

package/dist/index.js

@@ -10628,6 +10628,112 @@ var summarizeVoiceCampaigns = (records) => {
   }
   return summary;
 };
+var buildVoiceCampaignObservabilityReport = async (records, options = {}) => {
+  const now = options.now ?? Date.now();
+  const stuckAfterMs = Math.max(1, options.stuckAfterMs ?? 15 * 60000);
+  const rateWindowMs = Math.max(1, options.rateWindowMs ?? 60 * 60000);
+  const rateWindowStart = now - rateWindowMs;
+  const failureReasons = new Map;
+  const report = {
+    attemptRate: {
+      failed: 0,
+      started: 0,
+      succeeded: 0,
+      windowMs: rateWindowMs
+    },
+    campaigns: [],
+    failureReasons: [],
+    generatedAt: now,
+    leases: {
+      active: 0,
+      known: Boolean(options.leases)
+    },
+    queue: {
+      activeAttempts: 0,
+      queuedRecipients: 0,
+      runningCampaigns: 0
+    },
+    stuck: {
+      attempts: [],
+      recipients: []
+    },
+    summary: summarizeVoiceCampaigns(records)
+  };
+  for (const record of records) {
+    const campaignId = record.campaign.id;
+    const queuedRecipients = record.recipients.filter((recipient) => recipient.status === "queued");
+    const activeAttempts = record.attempts.filter((attempt) => attempt.status === "queued" || attempt.status === "running");
+    const campaignReport = {
+      activeAttempts: activeAttempts.length,
+      campaignId,
+      name: record.campaign.name,
+      queueDepth: queuedRecipients.length,
+      status: record.campaign.status,
+      stuckAttempts: 0,
+      stuckRecipients: 0,
+      updatedAt: record.campaign.updatedAt
+    };
+    if (record.campaign.status === "running") {
+      report.queue.runningCampaigns += 1;
+    }
+    report.queue.queuedRecipients += queuedRecipients.length;
+    report.queue.activeAttempts += activeAttempts.length;
+    for (const recipient of record.recipients) {
+      if ((recipient.status === "pending" || recipient.status === "queued") && now - recipient.updatedAt >= stuckAfterMs) {
+        campaignReport.stuckRecipients += 1;
+        report.stuck.recipients.push({
+          campaignId,
+          recipientId: recipient.id,
+          status: recipient.status,
+          updatedAt: recipient.updatedAt
+        });
+      }
+      if (recipient.error) {
+        failureReasons.set(recipient.error, (failureReasons.get(recipient.error) ?? 0) + 1);
+      }
+    }
+    for (const attempt of record.attempts) {
+      if ((attempt.startedAt ?? attempt.createdAt) >= rateWindowStart) {
+        report.attemptRate.started += 1;
+      }
+      if (attempt.status === "failed" && attempt.updatedAt >= rateWindowStart) {
+        report.attemptRate.failed += 1;
+      }
+      if (attempt.status === "succeeded" && attempt.updatedAt >= rateWindowStart) {
+        report.attemptRate.succeeded += 1;
+      }
+      if (attempt.error) {
+        failureReasons.set(attempt.error, (failureReasons.get(attempt.error) ?? 0) + 1);
+      }
+      if ((attempt.status === "queued" || attempt.status === "running") && now - attempt.updatedAt >= stuckAfterMs) {
+        campaignReport.stuckAttempts += 1;
+        report.stuck.attempts.push({
+          attemptId: attempt.id,
+          campaignId,
+          recipientId: attempt.recipientId,
+          status: attempt.status,
+          updatedAt: attempt.updatedAt
+        });
+      }
+    }
+    if (options.leases) {
+      const lease = await options.leases.get(getCampaignLeaseTaskId(campaignId));
+      if (lease) {
+        report.leases.active += 1;
+        campaignReport.lease = {
+          expiresAt: lease.expiresAt,
+          workerId: lease.workerId
+        };
+      }
+    }
+    report.campaigns.push(campaignReport);
+  }
+  report.failureReasons = [...failureReasons.entries()].map(([reason, count]) => ({ count, reason })).sort((left, right) => right.count === left.count ? left.reason.localeCompare(right.reason) : right.count - left.count);
+  report.campaigns.sort((left, right) => right.updatedAt - left.updatedAt);
+  report.stuck.attempts.sort((left, right) => left.updatedAt - right.updatedAt);
+  report.stuck.recipients.sort((left, right) => left.updatedAt - right.updatedAt);
+  return report;
+};
 var createVoiceCampaign = (options) => {
   const { store } = options;
   return {
@@ -10794,6 +10900,90 @@ var createVoiceCampaign = (options) => {
     }
   };
 };
+var getCampaignLeaseTaskId = (campaignId) => `voice-campaign:${campaignId}`;
+var createVoiceCampaignWorker = (options) => {
+  const leaseMs = Math.max(1, options.leaseMs ?? 30000);
+  const runtime = options.runtime ?? createVoiceCampaign({
+    store: options.store ?? createVoiceMemoryCampaignStore()
+  });
+  const statuses = options.statuses ?? ["running"];
+  const campaignIds = new Set(options.campaignIds);
+  const maxCampaigns = Math.max(1, options.maxCampaigns ?? Number.MAX_SAFE_INTEGER);
+  return {
+    drain: async () => {
+      const result = {
+        attempted: 0,
+        campaigns: 0,
+        errors: [],
+        skipped: 0,
+        started: []
+      };
+      const campaigns = [...await runtime.list()].filter((record) => (campaignIds.size === 0 || campaignIds.has(record.campaign.id)) && statuses.includes(record.campaign.status)).sort((left, right) => left.campaign.createdAt - right.campaign.createdAt).slice(0, maxCampaigns);
+      for (const record of campaigns) {
+        const campaignId = record.campaign.id;
+        const taskId = getCampaignLeaseTaskId(campaignId);
+        const claimed = await options.leases.claim({
+          leaseMs,
+          taskId,
+          workerId: options.workerId
+        });
+        if (!claimed) {
+          result.skipped += 1;
+          continue;
+        }
+        try {
+          const tick = await runtime.tick(campaignId);
+          result.campaigns += 1;
+          result.attempted += tick.attempted;
+          result.started.push(...tick.started);
+          result.errors.push(...tick.errors.map((error) => ({
+            campaignId,
+            error: error.error
+          })));
+        } catch (error) {
+          result.errors.push({
+            campaignId,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        } finally {
+          await options.leases.release({
+            taskId,
+            workerId: options.workerId
+          });
+        }
+      }
+      return result;
+    }
+  };
+};
+var createVoiceCampaignWorkerLoop = (options) => {
+  const pollIntervalMs = Math.max(1, options.pollIntervalMs ?? 1000);
+  let timer;
+  let running = false;
+  const tick = async () => options.worker.drain();
+  return {
+    isRunning: () => running,
+    start: () => {
+      if (timer) {
+        return;
+      }
+      running = true;
+      timer = setInterval(() => {
+        tick().catch((error) => {
+          options.onError?.(error);
+        });
+      }, pollIntervalMs);
+    },
+    stop: () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      running = false;
+    },
+    tick
+  };
+};
 var defaultProofRecipients = () => [
   {
     id: "campaign-proof-recipient-1",
@@ -10869,6 +11059,12 @@ var renderVoiceCampaignsHTML = (records, options = {}) => {
   const summary = summarizeVoiceCampaigns(records);
   return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml18(title)}</title><style>body{background:#111827;color:#f9fafb;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1080px;padding:32px}.hero{background:linear-gradient(135deg,rgba(251,146,60,.18),rgba(45,212,191,.12));border:1px solid #334155;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#fdba74;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,5rem);line-height:.9;margin:.2rem 0 1rem}.grid{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));margin:18px 0}.grid article,table{background:#172033;border:1px solid #334155;border-radius:18px}.grid article{padding:16px}.grid span{color:#aab5c0}.grid strong{display:block;font-size:2rem;margin:.25rem 0}table{border-collapse:collapse;overflow:hidden;width:100%}td,th{border-bottom:1px solid #334155;padding:12px;text-align:left}</style></head><body><main><section class="hero"><p class="eyebrow">Self-hosted outbound</p><h1>${escapeHtml18(title)}</h1><p>Campaign orchestration, recipients, attempts, retries, and outcomes without a hosted dialer dashboard.</p><section class="grid"><article><span>Campaigns</span><strong>${String(summary.campaigns.total)}</strong></article><article><span>Recipients</span><strong>${String(summary.recipients.total)}</strong></article><article><span>Attempts</span><strong>${String(summary.attempts.total)}</strong></article><article><span>Running</span><strong>${String(summary.campaigns.running)}</strong></article></section></section><table><thead><tr><th>Name</th><th>Status</th><th>Recipients</th><th>Attempts</th><th>Updated</th></tr></thead><tbody>${rows || '<tr><td colspan="5">No campaigns yet.</td></tr>'}</tbody></table></main></body></html>`;
 };
+var renderVoiceCampaignObservabilityHTML = (report, options = {}) => {
+  const title = options.title ?? "Voice Campaign Observability";
+  const campaignRows = report.campaigns.map((campaign) => `<tr><td>${escapeHtml18(campaign.name)}</td><td>${escapeHtml18(campaign.status)}</td><td>${String(campaign.queueDepth)}</td><td>${String(campaign.activeAttempts)}</td><td>${String(campaign.stuckRecipients + campaign.stuckAttempts)}</td><td>${campaign.lease ? escapeHtml18(campaign.lease.workerId) : "none"}</td></tr>`).join("");
+  const failureRows = report.failureReasons.map((failure) => `<tr><td>${escapeHtml18(failure.reason)}</td><td>${String(failure.count)}</td></tr>`).join("");
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml18(title)}</title><style>body{background:#0b1220;color:#e5edf7;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1120px;padding:32px}.hero{background:linear-gradient(135deg,rgba(20,184,166,.2),rgba(251,146,60,.14));border:1px solid #334155;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#5eead4;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.2rem,5vw,4.6rem);line-height:.95;margin:.2rem 0 1rem}.grid{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));margin:18px 0}.card,table{background:#111c2f;border:1px solid #334155;border-radius:18px}.card{padding:16px}.card span{color:#9fb0c5}.card strong{display:block;font-size:2rem;margin:.25rem 0}table{border-collapse:collapse;margin-top:18px;overflow:hidden;width:100%}td,th{border-bottom:1px solid #334155;padding:12px;text-align:left}.warn{color:#fde68a}.bad{color:#fecaca}</style></head><body><main><section class="hero"><p class="eyebrow">Campaign ops</p><h1>${escapeHtml18(title)}</h1><p>Queue depth, active leases, attempt rates, failure reasons, and stuck work for self-hosted outbound voice.</p><section class="grid"><article class="card"><span>Queued recipients</span><strong>${String(report.queue.queuedRecipients)}</strong></article><article class="card"><span>Active attempts</span><strong>${String(report.queue.activeAttempts)}</strong></article><article class="card"><span>Running campaigns</span><strong>${String(report.queue.runningCampaigns)}</strong></article><article class="card"><span>Active leases</span><strong>${report.leases.known ? String(report.leases.active) : "n/a"}</strong></article><article class="card"><span>Attempts/window</span><strong>${String(report.attemptRate.started)}</strong></article><article class="card"><span>Stuck work</span><strong class="${report.stuck.attempts.length + report.stuck.recipients.length > 0 ? "bad" : ""}">${String(report.stuck.attempts.length + report.stuck.recipients.length)}</strong></article></section></section><h2>Campaigns</h2><table><thead><tr><th>Name</th><th>Status</th><th>Queued</th><th>Active</th><th>Stuck</th><th>Lease</th></tr></thead><tbody>${campaignRows || '<tr><td colspan="6">No campaigns yet.</td></tr>'}</tbody></table><h2>Failure Reasons</h2><table><thead><tr><th>Reason</th><th>Count</th></tr></thead><tbody>${failureRows || '<tr><td colspan="2">No failures recorded.</td></tr>'}</tbody></table></main></body></html>`;
+};
 var readJsonBody = async (request) => {
   const text = await request.text();
   return text.trim() ? JSON.parse(text) : {};
@@ -10880,7 +11076,7 @@ var createVoiceCampaignRoutes = (options) => {
   const app = new Elysia17({ name: options.name ?? "absolutejs-voice-campaigns" }).get(path, async () => ({
     campaigns: await runtime.list(),
     summary: await runtime.summarize()
-  })).post(path, async ({ request }) => runtime.create(await readJsonBody(request))).get(`${path}/:campaignId`, ({ params }) => runtime.get(params.campaignId)).delete(`${path}/:campaignId`, async ({ params }) => {
+  })).get(`${path}/observability`, async () => buildVoiceCampaignObservabilityReport(await runtime.list(), options.observability)).post(path, async ({ request }) => runtime.create(await readJsonBody(request))).get(`${path}/:campaignId`, ({ params }) => runtime.get(params.campaignId)).delete(`${path}/:campaignId`, async ({ params }) => {
     await runtime.remove(params.campaignId);
     return { ok: true };
   }).post(`${path}/:campaignId/recipients`, async ({ params, request }) => {
@@ -10899,6 +11095,14 @@ var createVoiceCampaignRoutes = (options) => {
           ...options.headers
         }
       });
+    }).get(`${htmlPath}/observability`, async () => {
+      const report = await buildVoiceCampaignObservabilityReport(await runtime.list(), options.observability);
+      return new Response(renderVoiceCampaignObservabilityHTML(report, options), {
+        headers: {
+          "content-type": "text/html; charset=utf-8",
+          ...options.headers
+        }
+      });
     });
   }
   return app;
@@ -18949,6 +19153,7 @@ export {
   renderVoiceEvalHTML,
   renderVoiceEvalBaselineHTML,
   renderVoiceCampaignsHTML,
+  renderVoiceCampaignObservabilityHTML,
   renderVoiceCallReviewMarkdown,
   renderVoiceCallReviewHTML,
   renderVoiceBargeInHTML,
@@ -19123,6 +19328,8 @@ export {
   createVoiceExperiment,
   createVoiceEvalRoutes,
   createVoiceDiagnosticsRoutes,
+  createVoiceCampaignWorkerLoop,
+  createVoiceCampaignWorker,
   createVoiceCampaignRoutes,
   createVoiceCampaign,
   createVoiceCallReviewRecorder,
@@ -19176,6 +19383,7 @@ export {
   buildVoiceOpsTaskFromReview,
   buildVoiceOpsConsoleReport,
   buildVoiceDiagnosticsMarkdown,
+  buildVoiceCampaignObservabilityReport,
   assignVoiceOpsTask,
   applyVoiceTelephonyOutcome,
   applyVoiceOpsTaskPolicy,

package/package.json

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