@absolutejs/voice 0.0.22-beta.205 → 0.0.22-beta.207

package/README.md

@@ -851,7 +851,30 @@ The wrapper mounts selected carrier routes plus two proof surfaces:
 - `/api/voice/phone/smoke-contract?sessionId=...`: trace-backed production smoke contract.
 - `/voice/phone/smoke-contract?sessionId=...`: HTML production smoke contract.
 
-The setup page tells you exactly what to copy into the carrier dashboard:
+The setup JSON includes `setupInstructions`, so your own admin UI can render copy-ready carrier fields without scraping HTML:
+
+```ts
+const setup = await fetch('/api/voice/phone/setup').then((response) =>
+	response.json()
+);
+
+for (const carrier of setup.setupInstructions) {
+	console.log(carrier.carrierName, carrier.status);
+	console.log(carrier.steps.join('\n'));
+}
+```
+
+Each instruction includes:
+
+- `answerLabel`: `TwiML URL`, `TeXML URL`, or `Answer URL`.
+- `answerUrl`: the URL to paste into the carrier's inbound voice/answer field.
+- `webhookUrl`: the status callback or webhook URL.
+- `streamUrl`: the `wss://` media stream URL the carrier must reach.
+- `setupPath` and `smokePath`: package-mounted proof pages for that carrier.
+- `steps`: ordered copy/paste guidance for the carrier dashboard.
+- `issues`: contract errors or warnings from the carrier matrix.
+
+The setup page renders the same instructions and tells you exactly what to copy into the carrier dashboard:
 
 - Twilio: set the phone number voice webhook/TwiML URL to the reported TwiML URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
 - Telnyx: set the connection TeXML URL to the reported TeXML URL, set the status webhook to the reported webhook URL, and allow the reported `wss://` media stream.
@@ -1721,6 +1744,91 @@ Mounted routes:
 
 `createVoiceZeroRetentionPolicy(...)` intentionally defaults to `dryRun: true`; callers must explicitly apply the generated policy after reviewing the deletion proof. This gives compliance-sensitive deployments a concrete zero-retention recipe without making accidental deletion easy.
 
+### Compliance Recipes
+
+These are recipes, not compliance certifications. AbsoluteJS Voice gives you the self-hosted controls and proof surfaces; your legal/security team still owns the actual HIPAA, SOC 2, GDPR, or customer-contract process.
+
+Zero-retention sensitive call:
+
+```ts
+const policy = createVoiceZeroRetentionPolicy({
+	...runtimeStorage,
+	audit: runtimeStorage.audit,
+	auditDeliveries: runtimeStorage.auditDeliveries,
+	traceDeliveries: runtimeStorage.traceDeliveries
+});
+
+const dryRun = await buildVoiceDataRetentionPlan(policy);
+if (dryRun.deletedCount > 0) {
+	await applyVoiceDataRetentionPolicy({
+		...policy,
+		dryRun: false
+	});
+}
+```
+
+This removes sessions, traces, reviews, tasks, integration events, campaigns, incident bundles, and delivery queues that match the policy selectors. The generated policy starts as a dry run so a zero-retention mode cannot accidentally wipe data without explicit application.
+
+Redacted support export:
+
+```ts
+const auditExport = await exportVoiceAuditTrail({
+	redact: voiceComplianceRedactionDefaults,
+	store: runtimeStorage.audit
+});
+const auditMarkdown = renderVoiceAuditMarkdown(auditExport.events);
+
+const traceMarkdown = renderVoiceTraceMarkdown(events, {
+	redact: voiceComplianceRedactionDefaults
+});
+```
+
+Use this for support tickets, customer escalations, incident reviews, or vendor handoffs where transcripts, tool payloads, provider metadata, or audit events may contain personal data.
+
+Customer-owned storage:
+
+```ts
+const runtimeStorage = createVoicePostgresRuntimeStorage({
+	connectionString: process.env.DATABASE_URL!,
+	schemaName: 'voice_ops',
+	tablePrefix: 'support'
+});
+
+app.use(
+	createVoiceDataControlRoutes({
+		...runtimeStorage,
+		audit: runtimeStorage.audit,
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		redact: voiceComplianceRedactionDefaults,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+```
+
+Use file storage for local demos, SQLite for small self-hosted installs, Postgres for production app-owned records, and S3 delivery for exported audit/trace evidence. The important point is that sessions, traces, reviews, tasks, campaigns, audit, and delivery queues remain in infrastructure the app owner controls.
+
+Deploy gate for compliance evidence:
+
+```ts
+app.use(
+	createVoiceProductionReadinessRoutes({
+		audit: {
+			require: [
+				{ type: 'provider.call' },
+				{ type: 'operator.action' },
+				{ type: 'retention.policy', maxAgeMs: 7 * 24 * 60 * 60 * 1000 }
+			],
+			store: runtimeStorage.audit
+		},
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		traceDeliveries: runtimeStorage.traceDeliveries,
+		store: runtimeStorage.traces
+	})
+);
+```
+
+This makes provider-call audit evidence, operator interventions, recent retention-policy proof, and export-queue health part of release readiness instead of a manual dashboard check.
+
 Use `createVoiceAuditLogger(...)` when you need append-only compliance evidence outside call traces. The logger records provider calls, tool calls, handoffs, retention runs, and operator actions into `runtimeStorage.audit`, so self-hosted teams can prove who changed what, which provider ran, which tool fired, and what data-control policy deleted.
 
 Pass `audit` directly to `createVoiceAgent(...)` to record model calls as provider-call audit events and tool executions as tool-call audit events. Pass it to `createVoiceAgentSquad(...)` to record squad handoffs automatically. Use `auditProvider` and `auditModel` on agents when you want readiness and compliance reports to show the actual model provider instead of the agent id.

package/dist/index.js

@@ -19096,6 +19096,41 @@ var loadCarrierMatrixInputs = async (input) => {
   }
   return entries;
 };
+var carrierAnswerLabel = (provider) => provider === "telnyx" ? "TeXML URL" : provider === "plivo" ? "Answer URL" : "TwiML URL";
+var findCarrierMatrixEntry = (matrix, carrier) => matrix?.entries.find((candidate) => candidate.provider === carrier.provider && (candidate.name === carrier.name || candidate.name === (carrier.name ?? carrier.provider)));
+var buildVoicePhoneAgentSetupInstructions = (input) => input.carriers.map((carrier) => {
+  const entry = findCarrierMatrixEntry(input.matrix, carrier);
+  const urls = entry?.setup.urls;
+  const answerLabel = carrierAnswerLabel(carrier.provider);
+  const urlRecord = urls ?? {};
+  const answerUrl = urlRecord.twiml ?? urlRecord.texml ?? urlRecord.answer;
+  const webhookUrl = urls?.webhook;
+  const streamUrl = urls?.stream;
+  const setupPath = typeof carrier.setupPath === "string" ? `${carrier.setupPath}?format=html` : undefined;
+  const smokePath = typeof carrier.smokePath === "string" ? `${carrier.smokePath}?format=html` : undefined;
+  const productionSmokePath = input.productionSmokePath ? `${input.productionSmokePath.replace("/api/", "/")}?sessionId=` : undefined;
+  const steps = [
+    `Set ${answerLabel} to ${answerUrl ?? "missing"}.`,
+    `Set status webhook to ${webhookUrl ?? "missing"}.`,
+    `Allow media stream URL ${streamUrl ?? "missing"}.`,
+    ...setupPath ? [`Open setup report ${setupPath}.`] : [],
+    ...smokePath ? [`Run carrier smoke ${smokePath}.`] : [],
+    ...productionSmokePath ? [`Certify production smoke traces at ${productionSmokePath}.`] : []
+  ];
+  return {
+    answerLabel,
+    answerUrl,
+    carrierName: carrier.name ?? carrier.provider,
+    issues: entry?.issues.map((issue) => `${issue.severity}: ${issue.message}`) ?? [],
+    provider: carrier.provider,
+    setupPath: carrier.setupPath,
+    smokePath: carrier.smokePath,
+    status: entry?.status ?? "unknown",
+    steps,
+    streamUrl,
+    webhookUrl
+  };
+});
 var resolveCarrierContract = async (input) => {
   const matrixInputs = await loadCarrierMatrixInputs({
     app: input.app,
@@ -19111,7 +19146,7 @@ var resolveCarrierContract = async (input) => {
 };
 var renderVoicePhoneAgentSetupHTML = (report) => {
   const carrierRows = report.carriers.map((carrier) => {
-    const entry = report.matrix?.entries.find((candidate) => candidate.provider === carrier.provider && (candidate.name === carrier.name || candidate.name === (carrier.name ?? carrier.provider)));
+    const entry = findCarrierMatrixEntry(report.matrix, carrier);
     const urls = entry?.setup.urls;
     const primaryUrl = carrier.provider === "plivo" ? urls?.twiml : urls?.twiml;
     return `<tr><td>${escapeHtml33(carrier.name ?? carrier.provider)}</td><td>${escapeHtml33(carrier.provider)}</td><td><code>${escapeHtml33(carrier.setupPath || "disabled")}</code></td><td><code>${escapeHtml33(carrier.smokePath || "disabled")}</code></td><td>${entry ? `<span class="${escapeHtml33(entry.status)}">${escapeHtml33(entry.status.toUpperCase())}</span>` : "unknown"}</td><td>${primaryUrl ? `<code>${escapeHtml33(primaryUrl)}</code>` : '<span class="muted">missing</span>'}</td><td>${urls?.webhook ? `<code>${escapeHtml33(urls.webhook)}</code>` : '<span class="muted">missing</span>'}</td><td>${urls?.stream ? `<code>${escapeHtml33(urls.stream)}</code>` : '<span class="muted">missing</span>'}</td></tr>`;
@@ -19150,12 +19185,10 @@ app.use(
 	})
 );`);
   const checklist = report.carriers.map((carrier) => {
-    const entry = report.matrix?.entries.find((candidate) => candidate.provider === carrier.provider && (candidate.name === carrier.name || candidate.name === (carrier.name ?? carrier.provider)));
-    const urls = entry?.setup.urls;
-    const answerLabel = carrier.provider === "telnyx" ? "TeXML URL" : carrier.provider === "plivo" ? "Answer URL" : "TwiML URL";
-    const answerUrl = urls?.twiml;
-    const issueList = entry?.issues.map((issue) => `<li>${escapeHtml33(issue.severity)}: ${escapeHtml33(issue.message)}</li>`).join("") ?? "";
-    return `<article><h3>${escapeHtml33(carrier.name ?? carrier.provider)}</h3><ol><li>Set ${escapeHtml33(answerLabel)} to <code>${escapeHtml33(answerUrl ?? "missing")}</code>.</li><li>Set status webhook to <code>${escapeHtml33(urls?.webhook ?? "missing")}</code>.</li><li>Allow media stream URL <code>${escapeHtml33(urls?.stream ?? "missing")}</code>.</li><li>Open setup: ${carrier.setupPath ? `<a href="${escapeHtml33(carrier.setupPath)}?format=html">${escapeHtml33(carrier.setupPath)}</a>` : '<span class="muted">disabled</span>'}.</li><li>Run smoke: ${carrier.smokePath ? `<a href="${escapeHtml33(carrier.smokePath)}?format=html">${escapeHtml33(carrier.smokePath)}</a>` : '<span class="muted">disabled</span>'}.</li>${report.productionSmokePath ? `<li>Certify production smoke traces: <a href="${escapeHtml33(report.productionSmokePath.replace("/api/", "/"))}?sessionId=">${escapeHtml33(report.productionSmokePath)}</a>.</li>` : ""}</ol>${issueList ? `<ul class="issues">${issueList}</ul>` : '<p class="pass">No carrier contract issues.</p>'}</article>`;
+    const instruction = report.setupInstructions.find((candidate) => candidate.provider === carrier.provider && candidate.carrierName === (carrier.name ?? carrier.provider));
+    const issueList = instruction?.issues.map((issue) => `<li>${escapeHtml33(issue)}</li>`).join("") ?? "";
+    const steps = instruction?.steps.map((step) => `<li>${escapeHtml33(step)}</li>`).join("") ?? "";
+    return `<article><h3>${escapeHtml33(carrier.name ?? carrier.provider)}</h3><ol>${steps}</ol>${issueList ? `<ul class="issues">${issueList}</ul>` : '<p class="pass">No carrier contract issues.</p>'}</article>`;
   }).join("");
   return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml33(report.title)}</title><style>body{background:#10151c;color:#f8f3e7;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1180px;padding:32px}.hero,.primitive{background:linear-gradient(135deg,rgba(20,184,166,.2),rgba(245,158,11,.12));border:1px solid #283544;border-radius:28px;margin-bottom:18px;padding:28px}.primitive{background:#151d27;border-color:#365a60}.eyebrow{color:#5eead4;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.3rem,6vw,4.8rem);line-height:.92;margin:.2rem 0 1rem}.badge{border:1px solid #3f3f46;border-radius:999px;display:inline-flex;padding:8px 12px}.pass{color:#86efac}.fail{color:#fca5a5}.warn{color:#fde68a}.muted{color:#aab5c0}table{background:#151d27;border:1px solid #283544;border-collapse:collapse;border-radius:18px;display:block;overflow:auto;width:100%}td,th{border-bottom:1px solid #283544;padding:12px;text-align:left;vertical-align:top}code{color:#fde68a;overflow-wrap:anywhere}.primitive p{color:#cbd5de;line-height:1.55}.primitive pre{background:#0b1118;border:1px solid #283544;border-radius:18px;color:#fef3c7;overflow:auto;padding:16px}.checklist{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));margin:18px 0}.checklist article{background:#151d27;border:1px solid #283544;border-radius:18px;padding:18px}.checklist ol{padding-left:20px}.issues{color:#fca5a5}.stages{display:grid;gap:8px;grid-template-columns:repeat(auto-fit,minmax(180px,1fr));padding-left:18px}a{color:#5eead4}</style></head><body><main><section class="hero"><p class="eyebrow">Phone agent setup</p><h1>${escapeHtml33(report.title)}</h1><p>One self-hosted entrypoint for carrier routes, setup reports, smoke checks, and normalized call lifecycle stages.</p><p class="badge ${report.ready ? "pass" : "fail"}">Ready: ${String(report.ready)}</p>${report.matrixPath ? `<p><a href="${escapeHtml33(report.matrixPath)}?format=html">Open carrier matrix</a></p>` : ""}</section><section class="primitive"><p class="eyebrow">Copy into your app</p><h2><code>createVoicePhoneAgent(...)</code> builds this carrier control plane</h2><p>Mount carrier routes once, expose setup and smoke proof, then feed the same carrier matrix and phone-agent smoke reports into production readiness so carrier regressions block deploys.</p><pre><code>${snippet}</code></pre></section><h2>Carrier Setup Checklist</h2><section class="checklist">${checklist}</section><h2>Carrier URLs</h2><table><thead><tr><th>Name</th><th>Provider</th><th>Setup</th><th>Smoke</th><th>Status</th><th>Answer/TwiML/TeXML</th><th>Webhook</th><th>Stream</th></tr></thead><tbody>${carrierRows}</tbody></table><h2>Lifecycle Schema</h2><ul class="stages">${stageList}</ul></main></body></html>`;
 };
@@ -19230,6 +19263,11 @@ var createVoicePhoneAgent = (options) => {
         matrixPath,
         productionSmokePath,
         ready: matrix ? matrix.pass : carrierSummaries.length > 0,
+        setupInstructions: buildVoicePhoneAgentSetupInstructions({
+          carriers: carrierSummaries,
+          matrix,
+          productionSmokePath
+        }),
         setupPath,
         title: setupTitle
       };

package/dist/phoneAgent.d.ts

@@ -40,6 +40,19 @@ export type VoicePhoneAgentCarrierSummary = {
     setupPath?: false | string;
     smokePath?: false | string;
 };
+export type VoicePhoneAgentSetupInstruction = {
+    answerLabel: string;
+    answerUrl?: string;
+    carrierName: string;
+    issues: string[];
+    provider: 'plivo' | 'telnyx' | 'twilio';
+    setupPath?: false | string;
+    smokePath?: false | string;
+    status: 'fail' | 'pass' | 'unknown' | 'warn';
+    steps: string[];
+    streamUrl?: string;
+    webhookUrl?: string;
+};
 export type VoicePhoneAgentRoutes = {
     carriers: VoicePhoneAgentCarrierSummary[];
     matrixPath?: string;
@@ -55,6 +68,7 @@ export type VoicePhoneAgentSetupReport = {
     matrixPath?: string;
     productionSmokePath?: string;
     ready: boolean;
+    setupInstructions: VoicePhoneAgentSetupInstruction[];
     setupPath?: string;
     title: string;
 };

package/package.json

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