@absolutejs/voice 0.0.22-beta.222 → 0.0.22-beta.224

package/README.md

@@ -2756,6 +2756,19 @@ app.use(
 		artifactIntegrity: {
 			maxAgeMs: 15 * 60 * 1000
 		},
+		deliveryDestinations: [
+			{
+				directory: '.voice-runtime/observability-exports',
+				kind: 'file',
+				label: 'Local customer-owned observability archive'
+			},
+			{
+				bucket: process.env.VOICE_OBSERVABILITY_EXPORT_S3_BUCKET,
+				keyPrefix: 'voice/observability-exports',
+				kind: 's3',
+				label: 'S3 customer-owned observability archive'
+			}
+		],
 		artifacts: [
 			{
 				id: 'latest-proof-pack',
@@ -2791,7 +2804,7 @@ const exportReport = await buildVoiceObservabilityExport({
 });
 ```
 
-The route helper exposes JSON at `/api/voice/observability-export`, an artifact index at `/api/voice/observability-export/artifacts`, per-artifact downloads at `/api/voice/observability-export/artifacts/:artifactId`, Markdown at `/voice/observability-export.md`, and HTML at `/voice/observability-export`. Path-backed artifacts are hashed with SHA-256 by default, include byte size and freshness metadata, and can fail the export when required evidence is missing or stale. Failed trace/audit deliveries fail the export report, pending deliveries warn, and every trace/audit envelope includes the linked operations-record URL when one is configured. This is the primitive to use when customers ask how voice evidence leaves the app without going through a hosted vendor dashboard.
+The route helper exposes JSON at `/api/voice/observability-export`, an artifact index at `/api/voice/observability-export/artifacts`, per-artifact downloads at `/api/voice/observability-export/artifacts/:artifactId`, delivery at `POST /api/voice/observability-export/deliveries`, Markdown at `/voice/observability-export.md`, and HTML at `/voice/observability-export`. Path-backed artifacts are hashed with SHA-256 by default, include byte size and freshness metadata, and can fail the export when required evidence is missing or stale. File delivery writes `manifest.json`, `artifact-index.json`, and artifact files into a customer-owned archive directory; webhook delivery posts the manifest and artifact index to a buyer-owned collector, SIEM bridge, or warehouse endpoint; S3 delivery writes the same manifest, index, and artifact files through Bun's native S3 client. Failed trace/audit deliveries fail the export report, pending deliveries warn, and every trace/audit envelope includes the linked operations-record URL when one is configured. This is the primitive to use when customers ask how voice evidence leaves the app without going through a hosted vendor dashboard.
 
 Pass the same report into production readiness when export health should block deploys:
 

package/dist/index.d.ts

@@ -53,7 +53,7 @@ export { createVoiceReadinessProfile, recommendVoiceReadinessProfile } from './r
 export { buildVoiceProviderContractMatrix, createVoiceProviderContractMatrixHTMLHandler, createVoiceProviderContractMatrixJSONHandler, createVoiceProviderContractMatrixPreset, createVoiceProviderContractMatrixRoutes, evaluateVoiceProviderStackGaps, renderVoiceProviderContractMatrixHTML, recommendVoiceProviderStack } from './providerStackRecommendations';
 export { buildVoiceOpsConsoleReport, createVoiceOpsConsoleRoutes, renderVoiceOpsConsoleHTML } from './opsConsoleRoutes';
 export { buildVoiceOperationsRecord, createVoiceOperationsRecordRoutes, renderVoiceOperationsRecordHTML, renderVoiceOperationsRecordIncidentMarkdown } from './operationsRecord';
-export { buildVoiceObservabilityArtifactIndex, buildVoiceObservabilityExport, createVoiceObservabilityExportRoutes, renderVoiceObservabilityExportMarkdown } from './observabilityExport';
+export { buildVoiceObservabilityArtifactIndex, buildVoiceObservabilityExport, createVoiceObservabilityExportRoutes, deliverVoiceObservabilityExport, renderVoiceObservabilityExportMarkdown } from './observabilityExport';
 export { buildVoiceOpsRecoveryReadinessCheck, buildVoiceOpsRecoveryReport, createVoiceOpsRecoveryRoutes, renderVoiceOpsRecoveryHTML, renderVoiceOpsRecoveryMarkdown } from './opsRecovery';
 export { buildVoiceIncidentBundle, createStoredVoiceIncidentBundleArtifact, createVoiceIncidentBundleRoutes, createVoiceMemoryIncidentBundleStore, pruneVoiceIncidentBundleArtifacts, saveVoiceIncidentBundleArtifact } from './incidentBundle';
 export { summarizeVoiceOpsStatus } from './opsStatus';
@@ -118,7 +118,7 @@ export type { VoiceProductionReadinessAction, VoiceProductionReadinessAuditOptio
 export type { VoiceReadinessProfileName, VoiceReadinessProfileOptions, VoiceReadinessProfileRecommendation, VoiceReadinessProfileRecommendationScore, VoiceReadinessProfileRoutesOptions } from './readinessProfiles';
 export type { VoiceProviderStackChoice, VoiceProviderStackCapabilities, VoiceProviderStackCapabilityGap, VoiceProviderStackCapabilityGapInput, VoiceProviderStackCapabilityGapReport, VoiceProviderContractCheck, VoiceProviderContractCheckStatus, VoiceProviderContractDefinition, VoiceProviderContractMatrixHandlerOptions, VoiceProviderContractMatrixHTMLHandlerOptions, VoiceProviderContractMatrixInput, VoiceProviderContractMatrixPresetOptions, VoiceProviderContractMatrixReport, VoiceProviderContractMatrixRoutesOptions, VoiceProviderContractMatrixRow, VoiceProviderStackInput, VoiceProviderStackKind, VoiceProviderStackRecommendation } from './providerStackRecommendations';
 export type { VoiceOperationsRecord, VoiceOperationsRecordAgentHandoff, VoiceOperationsRecordAuditSummary, VoiceOperationsRecordIntegrationEventSummary, VoiceOperationsRecordOptions, VoiceOperationsRecordOutcome, VoiceOperationsRecordProviderDecision, VoiceOperationsRecordReviewSummary, VoiceOperationsRecordRoutesOptions, VoiceOperationsRecordStatus, VoiceOperationsRecordTaskSummary, VoiceOperationsRecordTranscriptTurn, VoiceOperationsRecordTool } from './operationsRecord';
-export type { VoiceObservabilityExportArtifact, VoiceObservabilityExportArtifactChecksum, VoiceObservabilityExportArtifactFreshness, VoiceObservabilityExportArtifactIndex, VoiceObservabilityExportArtifactIndexItem, VoiceObservabilityExportArtifactKind, VoiceObservabilityExportDeliverySummary, VoiceObservabilityExportEnvelope, VoiceObservabilityExportIssue, VoiceObservabilityExportIssueCode, VoiceObservabilityExportOptions, VoiceObservabilityExportRedactionSummary, VoiceObservabilityExportReport, VoiceObservabilityExportRoutesOptions, VoiceObservabilityExportStatus } from './observabilityExport';
+export type { VoiceObservabilityExportArtifact, VoiceObservabilityExportArtifactChecksum, VoiceObservabilityExportArtifactFreshness, VoiceObservabilityExportArtifactIndex, VoiceObservabilityExportArtifactIndexItem, VoiceObservabilityExportArtifactKind, VoiceObservabilityExportDeliverySummary, VoiceObservabilityExportDeliveryDestination, VoiceObservabilityExportDeliveryDestinationResult, VoiceObservabilityExportDeliveryOptions, VoiceObservabilityExportDeliveryReport, VoiceObservabilityExportEnvelope, VoiceObservabilityExportIssue, VoiceObservabilityExportIssueCode, VoiceObservabilityExportOptions, VoiceObservabilityExportRedactionSummary, VoiceObservabilityExportReport, VoiceObservabilityExportRoutesOptions, VoiceObservabilityExportStatus } from './observabilityExport';
 export type { VoiceOpsRecoveryFailedSession, VoiceOpsRecoveryInterventionSummary, VoiceOpsRecoveryIssue, VoiceOpsRecoveryIssueCode, VoiceOpsRecoveryLinks, VoiceOpsRecoveryProviderSummary, VoiceOpsRecoveryReport, VoiceOpsRecoveryReportOptions, VoiceOpsRecoveryRoutesOptions, VoiceOpsRecoveryStatus } from './opsRecovery';
 export type { StoredVoiceIncidentBundleArtifact, VoiceIncidentBundle, VoiceIncidentBundleArtifactOptions, VoiceIncidentBundleFormat, VoiceIncidentBundleOptions, VoiceIncidentBundleRetentionOptions, VoiceIncidentBundleRetentionReport, VoiceIncidentBundleRoutesOptions, VoiceIncidentBundleStore, VoiceIncidentBundleStoreFilter, VoiceIncidentBundleSummary } from './incidentBundle';
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';

package/dist/index.js

@@ -6972,14 +6972,14 @@ var createProofFetch = (provider, requests) => {
   };
 };
 var createProofDialer = (input) => {
-  const fetch = createProofFetch(input.provider, input.requests);
+  const fetch2 = createProofFetch(input.provider, input.requests);
   if (input.provider === "twilio") {
     return createVoiceTwilioCampaignDialer({
       accountSid: "AC_dry_run",
       answerUrl: joinUrlPath(input.baseUrl, "/api/twilio/voice"),
       apiBaseUrl: "https://twilio.dry-run.absolutejs.local",
       authToken: "dry-run-token",
-      fetch,
+      fetch: fetch2,
       from: input.from,
       statusCallbackEvents: ["answered", "completed"],
       statusCallbackUrl: joinUrlPath(input.baseUrl, "/api/telephony-webhook")
@@ -6990,7 +6990,7 @@ var createProofDialer = (input) => {
       apiBaseUrl: "https://telnyx.dry-run.absolutejs.local",
       apiKey: "dry-run-token",
       connectionId: "dry-run-connection",
-      fetch,
+      fetch: fetch2,
       from: input.from,
       webhookUrl: joinUrlPath(input.baseUrl, "/api/telnyx/webhook")
     });
@@ -7001,7 +7001,7 @@ var createProofDialer = (input) => {
     authId: "dry-run-auth-id",
     authToken: "dry-run-token",
     callbackUrl: joinUrlPath(input.baseUrl, "/api/plivo/webhook"),
-    fetch,
+    fetch: fetch2,
     from: input.from
   });
 };
@@ -24943,7 +24943,8 @@ var createVoiceOperationsRecordRoutes = (options) => {
 // src/observabilityExport.ts
 import { Elysia as Elysia42 } from "elysia";
 import { createHash } from "crypto";
-import { readFile as readFile2, stat } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile2, stat } from "fs/promises";
+import { join as join3 } from "path";
 var isDeliveryStore = (value) => !Array.isArray(value) && typeof value.list === "function";
 var getString18 = (value) => typeof value === "string" ? value : undefined;
 var getProviderKind = (payload) => getString18(payload.kind) ?? getString18(payload.providerKind);
@@ -24982,6 +24983,19 @@ var checksumFile = async (path) => {
   const buffer = await readFile2(path);
   return createHash("sha256").update(buffer).digest("hex");
 };
+var byteLength = (value) => new TextEncoder().encode(value).byteLength;
+var safeArtifactFileName = (artifact) => {
+  const extension = artifact.contentType === "image/png" ? ".png" : artifact.contentType?.includes("markdown") ? ".md" : artifact.contentType?.includes("json") ? ".json" : "";
+  return `${artifact.id.replace(/[^a-z0-9_.-]/gi, "-")}${extension}`;
+};
+var normalizeExportS3KeyPrefix = (prefix) => prefix?.trim().replace(/^\/+|\/+$/g, "") ?? "voice/observability-exports";
+var joinS3Key = (...parts) => parts.map((part) => part.trim().replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+var writeS3Object = async (input) => {
+  const file = input.client.file(input.key, input.options);
+  await file.write(input.value, {
+    type: input.contentType
+  });
+};
 var inferContentType = (artifact) => {
   if (artifact.contentType) {
     return artifact.contentType;
@@ -25310,10 +25324,152 @@ var buildVoiceObservabilityArtifactIndex = (report) => {
     }
   };
 };
+var deliverVoiceObservabilityExport = async (options) => {
+  const checkedAt = Date.now();
+  const runId = options.runId ?? new Date(checkedAt).toISOString().replaceAll(":", "-");
+  const artifactIndex = buildVoiceObservabilityArtifactIndex(options.report);
+  const manifest = `${JSON.stringify(options.report, null, 2)}
+`;
+  const index = `${JSON.stringify(artifactIndex, null, 2)}
+`;
+  const destinations = await Promise.all(options.destinations.map(async (destination) => {
+    const destinationId = destination.id ?? `${destination.kind}-${destination.label ?? "export"}`;
+    const label = destination.label ?? (destination.kind === "file" ? "File observability export" : "Webhook observability export");
+    try {
+      if (destination.kind === "file") {
+        const target = join3(destination.directory, runId);
+        await mkdir4(join3(target, "artifacts"), { recursive: true });
+        await Bun.write(join3(target, "manifest.json"), manifest);
+        await Bun.write(join3(target, "artifact-index.json"), index);
+        if (destination.includeArtifacts !== false) {
+          for (const artifact of options.report.artifacts) {
+            if (!artifact.path) {
+              continue;
+            }
+            await Bun.write(join3(target, "artifacts", safeArtifactFileName(artifact)), await readFile2(stripArtifactPathAnchor(artifact.path)));
+          }
+        }
+        return {
+          artifactCount: destination.includeArtifacts === false ? 0 : options.report.artifacts.filter((artifact) => artifact.path).length,
+          deliveredAt: Date.now(),
+          destinationId,
+          destinationKind: destination.kind,
+          label,
+          manifestBytes: byteLength(manifest),
+          status: "delivered",
+          target
+        };
+      }
+      if (destination.kind === "s3") {
+        const keyPrefix = normalizeExportS3KeyPrefix(destination.keyPrefix);
+        const rootKey = joinS3Key(keyPrefix, runId);
+        const client = destination.client ?? new Bun.S3Client(destination);
+        const s3Options = destination;
+        await writeS3Object({
+          client,
+          contentType: "application/json",
+          key: joinS3Key(rootKey, "manifest.json"),
+          options: s3Options,
+          value: manifest
+        });
+        await writeS3Object({
+          client,
+          contentType: "application/json",
+          key: joinS3Key(rootKey, "artifact-index.json"),
+          options: s3Options,
+          value: index
+        });
+        if (destination.includeArtifacts !== false) {
+          for (const artifact of options.report.artifacts) {
+            if (!artifact.path) {
+              continue;
+            }
+            await writeS3Object({
+              client,
+              contentType: artifact.contentType ?? inferContentType(artifact),
+              key: joinS3Key(rootKey, "artifacts", safeArtifactFileName(artifact)),
+              options: s3Options,
+              value: await readFile2(stripArtifactPathAnchor(artifact.path))
+            });
+          }
+        }
+        return {
+          artifactCount: destination.includeArtifacts === false ? 0 : options.report.artifacts.filter((artifact) => artifact.path).length,
+          deliveredAt: Date.now(),
+          destinationId,
+          destinationKind: destination.kind,
+          label,
+          manifestBytes: byteLength(manifest),
+          status: "delivered",
+          target: destination.bucket ? `s3://${destination.bucket}/${rootKey}` : rootKey
+        };
+      }
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), destination.timeoutMs ?? 1e4);
+      try {
+        const response = await (destination.fetch ?? fetch)(destination.url, {
+          body: JSON.stringify({
+            artifactIndex,
+            artifacts: destination.includeArtifacts === false ? [] : options.report.artifacts,
+            manifest: options.report,
+            runId,
+            source: "absolutejs-voice"
+          }),
+          headers: {
+            "content-type": "application/json",
+            ...destination.headers ?? {}
+          },
+          method: "POST",
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          throw new Error(`Webhook returned HTTP ${response.status}`);
+        }
+      } finally {
+        clearTimeout(timeout);
+      }
+      return {
+        artifactCount: destination.includeArtifacts === false ? 0 : options.report.artifacts.length,
+        deliveredAt: Date.now(),
+        destinationId,
+        destinationKind: destination.kind,
+        label,
+        manifestBytes: byteLength(manifest),
+        status: "delivered",
+        target: destination.url
+      };
+    } catch (error) {
+      return {
+        artifactCount: 0,
+        deliveredAt: Date.now(),
+        destinationId,
+        destinationKind: destination.kind,
+        error: error instanceof Error ? error.message : String(error),
+        label,
+        manifestBytes: byteLength(manifest),
+        status: "failed",
+        target: destination.kind === "file" ? destination.directory : destination.kind === "s3" ? destination.bucket ? `s3://${destination.bucket}/${normalizeExportS3KeyPrefix(destination.keyPrefix)}` : normalizeExportS3KeyPrefix(destination.keyPrefix) : destination.url
+      };
+    }
+  }));
+  const failed = destinations.filter((destination) => destination.status === "failed").length;
+  return {
+    checkedAt,
+    destinations,
+    exportStatus: options.report.status,
+    status: failed > 0 || options.report.status === "fail" ? "fail" : options.report.status === "warn" ? "warn" : "pass",
+    summary: {
+      delivered: destinations.length - failed,
+      failed,
+      total: destinations.length
+    }
+  };
+};
 var createVoiceObservabilityExportRoutes = (options = {}) => {
   const path = options.path ?? "/api/voice/observability-export";
   const artifactIndexPath = options.artifactIndexPath ?? `${path}/artifacts`;
   const artifactDownloadPath = options.artifactDownloadPath ?? `${path}/artifacts`;
+  const deliveryPath = options.deliveryPath ?? `${path}/deliveries`;
   const markdownPath = options.markdownPath ?? "/voice/observability-export.md";
   const htmlPath = options.htmlPath ?? "/voice/observability-export";
   const headers = {
@@ -25363,6 +25519,12 @@ var createVoiceObservabilityExportRoutes = (options = {}) => {
       }
     });
   }
+  if (deliveryPath !== false && options.deliveryDestinations) {
+    app.post(deliveryPath, async () => Response.json(await deliverVoiceObservabilityExport({
+      destinations: options.deliveryDestinations ?? [],
+      report: await buildReport()
+    }), { headers }));
+  }
   if (markdownPath !== false) {
     app.get(markdownPath, async () => {
       const report = await buildReport();
@@ -27157,7 +27319,7 @@ var createVoiceOpsRuntime = (config) => {
       pollIntervalMs: _pollIntervalMs,
       backoffMs,
       eventTypes,
-      fetch,
+      fetch: fetch2,
       headers,
       retries,
       signingSecret,
@@ -27171,7 +27333,7 @@ var createVoiceOpsRuntime = (config) => {
       webhook: {
         backoffMs,
         eventTypes,
-        fetch,
+        fetch: fetch2,
         headers,
         retries,
         signingSecret,
@@ -28113,6 +28275,7 @@ export {
   evaluateVoiceProviderStackGaps,
   encodeTwilioMulawBase64,
   deliverVoiceTraceEventsToSinks,
+  deliverVoiceObservabilityExport,
   deliverVoiceIntegrationEventToSinks,
   deliverVoiceIntegrationEvent,
   deliverVoiceHandoffDelivery,

package/dist/observabilityExport.d.ts

@@ -1,4 +1,5 @@
 import { Elysia } from 'elysia';
+import type { S3Client, S3Options } from 'bun';
 import { type VoiceAuditSinkDeliveryQueueSummary, type VoiceAuditSinkDeliveryRecord, type VoiceAuditSinkDeliveryStore } from './auditSinks';
 import type { VoiceAuditEventStore, VoiceAuditEventType } from './audit';
 import { type VoiceOperationsRecord } from './operationsRecord';
@@ -107,6 +108,57 @@ export type VoiceObservabilityExportArtifactIndex = {
         warn: number;
     };
 };
+export type VoiceObservabilityExportDeliveryDestination = {
+    directory: string;
+    id?: string;
+    includeArtifacts?: boolean;
+    kind: 'file';
+    label?: string;
+} | (S3Options & {
+    bucket?: string;
+    client?: Pick<S3Client, 'file'>;
+    id?: string;
+    includeArtifacts?: boolean;
+    keyPrefix?: string;
+    kind: 's3';
+    label?: string;
+}) | {
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    id?: string;
+    includeArtifacts?: boolean;
+    kind: 'webhook';
+    label?: string;
+    timeoutMs?: number;
+    url: string;
+};
+export type VoiceObservabilityExportDeliveryDestinationResult = {
+    artifactCount: number;
+    deliveredAt: number;
+    destinationId: string;
+    destinationKind: VoiceObservabilityExportDeliveryDestination['kind'];
+    error?: string;
+    label: string;
+    manifestBytes: number;
+    status: 'delivered' | 'failed';
+    target: string;
+};
+export type VoiceObservabilityExportDeliveryReport = {
+    checkedAt: number;
+    destinations: VoiceObservabilityExportDeliveryDestinationResult[];
+    exportStatus: VoiceObservabilityExportStatus;
+    status: VoiceObservabilityExportStatus;
+    summary: {
+        delivered: number;
+        failed: number;
+        total: number;
+    };
+};
+export type VoiceObservabilityExportDeliveryOptions = {
+    destinations: VoiceObservabilityExportDeliveryDestination[];
+    report: VoiceObservabilityExportReport;
+    runId?: string;
+};
 export type VoiceObservabilityExportOptions = {
     artifacts?: VoiceObservabilityExportArtifact[];
     artifactIntegrity?: {
@@ -134,6 +186,8 @@ export type VoiceObservabilityExportRoutesOptions = VoiceObservabilityExportOpti
     headers?: HeadersInit;
     artifactDownloadPath?: false | string;
     artifactIndexPath?: false | string;
+    deliveryDestinations?: VoiceObservabilityExportDeliveryDestination[];
+    deliveryPath?: false | string;
     htmlPath?: false | string;
     markdownPath?: false | string;
     name?: string;
@@ -146,6 +200,7 @@ export declare const renderVoiceObservabilityExportMarkdown: (report: VoiceObser
     title?: string;
 }) => string;
 export declare const buildVoiceObservabilityArtifactIndex: (report: VoiceObservabilityExportReport) => VoiceObservabilityExportArtifactIndex;
+export declare const deliverVoiceObservabilityExport: (options: VoiceObservabilityExportDeliveryOptions) => Promise<VoiceObservabilityExportDeliveryReport>;
 export declare const createVoiceObservabilityExportRoutes: (options?: VoiceObservabilityExportRoutesOptions) => Elysia<"", {
     decorator: {};
     store: {};

package/package.json

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