@absolutejs/voice 0.0.22-beta.206 → 0.0.22-beta.208

package/README.md

@@ -27,6 +27,34 @@ Pick the path that matches what you are building:
 - Provider routing and fallback: use LLM/STT/TTS provider routers, provider health, provider simulation controls, and cost/latency-aware routing policies.
 - Evals and simulation: mount `createVoiceSimulationSuiteRoutes(...)` to run scenario fixtures, workflow contracts, tool contracts, outcome contracts, baseline comparisons, and saved benchmark artifacts before live traffic.
 
+## Buyer Paths
+
+These are the primitive-first paths a Vapi-style buyer usually needs. Each path stays inside your AbsoluteJS app; the package gives you route handlers, stores, reports, hooks, composables, services, widgets, and contracts instead of a hosted dashboard.
+
+| If you need | Start with | Add proof with | UI entrypoints |
+| --- | --- | --- | --- |
+| Web voice assistant | `voice(...)` or `createVoiceAssistant(...)` | trace timeline, turn quality, live latency, reconnect contract, operations record | React/Vue/Svelte/Angular voice stream helpers, HTML/HTMX/client helpers |
+| Phone voice assistant | `createVoicePhoneAgent(...)` | carrier matrix, setup instructions, phone smoke contract, production readiness, operations record | phone setup HTML/JSON, smoke HTML/JSON, framework status UI |
+| Multi-specialist support flow | `createVoiceAgentSquad(...)` | squad contract, handoff traces, context traces, operations record | Agent Squad status hooks/composables/services/widgets |
+| Business actions and tools | `createVoiceAgentTool(...)` plus agent tool runtime | tool contracts, audit events, integration events, outcome contracts | operations record, action center, contract routes |
+| Provider routing and fallback | provider routers, health checks, simulation controls | provider contract matrix, provider-stage traces, latency SLO reports | provider contract hooks/composables/services/widgets |
+| Production operations | ops status, ops recovery, production readiness, delivery runtime | readiness gates, recovery report, incident Markdown, delivery queues | ops action center, delivery runtime UI, operations record |
+| Outbound campaigns | `createVoiceCampaignRoutes(...)` | recipient validation, consent/dedupe, carrier dry-run, campaign readiness | campaign routes and operations-record-linked attempt proof |
+| Simulation before launch | `createVoiceSimulationSuiteRoutes(...)` | scenarios, evals, tool contracts, outcome contracts, baselines | simulation-suite HTML/JSON and linked operations records |
+| Compliance controls | runtime storage, audit logger, data-control routes | retention dry-run, redacted audit export, zero-retention policy, deploy gate | data-control HTML/JSON and audit/export routes |
+
+## Capability Matrix
+
+| Surface | Core package | Example/demo role | Not our lane |
+| --- | --- | --- | --- |
+| Browser voice | WebSocket voice route, client stream/controller/store primitives, reconnect, barge-in, latency, framework helpers | Prove the same mic/transcript/status workflow across React, Vue, Svelte, Angular, HTML, and HTMX | Hosted iframe widget that owns app UX |
+| Telephony | Twilio, Telnyx, Plivo route bridges, phone-agent wrapper, setup instructions, smoke contracts, carrier outcomes | Show setup/smoke/proof surfaces and call lifecycle debugging | Buying/provisioning phone numbers for the user |
+| Agents and tools | assistant, agent, tools, squads, handoff/context policies, contracts, audit hooks | Demonstrate realistic support/sales/workflow flows | Dashboard-only visual bot builder |
+| Provider layer | OpenAI/Anthropic/Gemini model paths, STT/TTS adapter seams, routing, fallback, health, simulation | Show provider switching and health in UI | Reselling provider minutes or hiding provider accounts |
+| Observability | traces, timelines, replay, operations records, incident Markdown, ops recovery, readiness | Make every failing proof link to a call/session record | Vendor dashboard as source of truth |
+| Evals and simulation | fixtures, eval routes, simulation suite, workflow/tool/outcome contracts, baselines | Prove flows before live traffic | Opaque hosted test runner |
+| Data and compliance controls | file/SQLite/Postgres/S3 storage paths, redaction, retention, audit exports, guarded deletion | Show customer-owned storage and export proof | Legal certification or compliance attestation |
+
 ## How This Differs From Hosted Voice Platforms
 
 Hosted voice-agent platforms are strongest when you want a managed dashboard, phone-number provisioning, hosted orchestration, and campaign tooling out of the box.
@@ -1744,6 +1772,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/package.json

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