@absolutejs/voice 0.0.22-beta.210 → 0.0.22-beta.211

package/README.md

@@ -479,6 +479,116 @@ The UI should keep the scheduling flow simple: microphone, transcript, selected
 
 This recipe covers the hosted-platform expectations that matter for appointment scheduling: scheduling tools, deterministic tool proof, post-call confirmation work, outcome validation, simulation proof, production readiness, and one call-log replacement for debugging.
 
+## Use-Case Recipe: Campaign Outreach
+
+Use this path when you need Retell/Bland-style outbound outreach without handing recipients, consent proof, attempt policy, carrier outcomes, or debugging records to a hosted campaign dashboard. The package gives you campaign primitives; your app decides who can upload recipients, when workers run, which carrier dials, and how campaign results sync back to your product.
+
+The production shape is:
+
+1. Store campaigns in app-owned storage.
+2. Import recipients with consent checks, phone validation, dedupe, variables, and rejected-row evidence.
+3. Configure campaign policy for max attempts, concurrency, attempt windows, quiet hours, rate limits, and retry backoff.
+4. Use a carrier dialer or your own dialer function, then apply Twilio/Telnyx/Plivo webhook outcomes back to attempts.
+5. Expose campaign routes, observability, readiness proof, production readiness, and operations-record links for every attempted call.
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	createVoiceCampaignRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceOperationsRecordRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceReadinessProfile,
+	createVoiceSQLiteCampaignStore,
+	runVoiceCampaignReadinessProof
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/campaign-outreach'
+});
+
+const campaigns = createVoiceSQLiteCampaignStore({
+	path: '.voice-runtime/campaigns.sqlite'
+});
+
+const app = new Elysia()
+	.use(
+		createVoiceCampaignRoutes({
+			htmlPath: '/voice/campaigns',
+			operationsRecordHref: '/voice-operations/:sessionId',
+			path: '/api/voice/campaigns',
+			store: campaigns,
+			title: 'Renewal Outreach'
+		})
+	)
+	.use(
+		createVoiceOperationsRecordRoutes({
+			htmlPath: '/voice-operations/:sessionId',
+			path: '/api/voice-operations/:sessionId',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			...createVoiceReadinessProfile('phone-agent', {
+				campaignReadiness: () =>
+					runVoiceCampaignReadinessProof({
+						store: campaigns
+					}),
+				explain: true
+			}),
+			links: {
+				campaigns: '/voice/campaigns',
+				operationsRecords: '/voice-operations/:sessionId'
+			},
+			store: runtime.traces
+		})
+	);
+
+await fetch('/api/voice/campaigns', {
+	body: JSON.stringify({
+		maxAttempts: 3,
+		maxConcurrentAttempts: 10,
+		name: 'Renewal outreach',
+		schedule: {
+			attemptWindow: { startHour: 9, endHour: 17 },
+			quietHours: { startHour: 12, endHour: 13 },
+			rateLimit: { maxAttempts: 60, windowMs: 60_000 },
+			retryPolicy: { backoffMs: [5 * 60_000, 30 * 60_000] }
+		}
+	}),
+	headers: { 'content-type': 'application/json' },
+	method: 'POST'
+});
+
+await fetch('/api/voice/campaigns/campaign-1/recipients/import', {
+	body: JSON.stringify({
+		csv: `id,name,phone,consent,segment
+recipient-1,Ada,+15550001001,yes,trial
+recipient-2,Grace,+15550001002,true,enterprise
+recipient-3,Linus,not-a-phone,yes,partner
+recipient-4,Barbara,+15550001004,no,trial`,
+		metadataColumns: ['segment'],
+		requireConsent: true,
+		variableColumns: ['segment']
+	}),
+	headers: { 'content-type': 'application/json' },
+	method: 'POST'
+});
+
+await fetch('/api/voice/campaigns/campaign-1/enqueue', {
+	method: 'POST'
+});
+```
+
+Use `/api/voice/campaigns/campaign-1/tick` for manual workers or `createVoiceCampaignWorkerLoop(...)` when the app should continuously drain eligible recipients. The runtime enforces the campaign policy on each tick, so parallel workers do not double-start recipients and attempts respect quiet hours, rate limits, retry backoff, and max attempts.
+
+For production carrier dialing, pass a `dialer` to `createVoiceCampaignRoutes(...)`: `createVoiceTwilioCampaignDialer(...)`, `createVoiceTelnyxCampaignDialer(...)`, `createVoicePlivoCampaignDialer(...)`, or a custom dialer that starts the call and returns an external call id. Run `runVoiceCampaignDialerProof(...)` before live traffic to dry-run carrier request metadata and webhook outcome application.
+
+The UI should show `/voice/campaigns`, `/voice/campaigns/observability`, `/api/voice/campaigns/readiness-proof`, `/production-readiness`, and operations-record links for recent attempts. If a recipient failed, the operator should open the campaign attempt, follow `/voice-operations/:sessionId`, and see the same trace/review/task/audit context used by support and phone-agent flows.
+
+This recipe covers the hosted-platform expectations that matter for campaign outreach: recipient import evidence, consent/dedupe checks, scheduling policy, worker-safe attempts, carrier dry-run proof, webhook outcome mapping, queue observability, readiness gating, and call-log replacement links.
+
 ## 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.

package/package.json

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