@absolutejs/voice 0.0.22-beta.414 → 0.0.22-beta.416

package/dist/index.d.ts

@@ -206,6 +206,6 @@ export type { PlivoInboundMessage, PlivoMediaStreamBridge, PlivoMediaStreamBridg
 export type { VoiceTelephonyCarrierMatrix, VoiceTelephonyCarrierMatrixEntry, VoiceTelephonyCarrierMatrixInput, VoiceTelephonyCarrierMatrixOptions, VoiceTelephonyCarrierMatrixRoutesOptions, VoiceTelephonyCarrierMatrixStatus } from './telephony/matrix';
 export { shapeTelephonyAssistantText } from './telephony/response';
 export type { TelephonyResponseShapeMode, TelephonyResponseShapeOptions } from './telephony/response';
-export { buildVoiceProofPack, buildVoiceProofPackFromObservabilityExport, createVoiceProofPackArtifacts, createVoiceProofPackOperationsRecordSection, createVoiceProofPackProductionReadinessSection, createVoiceProofPackProviderSloSection, createVoiceProofPackRoutes, createVoiceProofPackSupportBundleSection, renderVoiceProofPackMarkdown, writeVoiceProofPack } from './proofPack';
-export type { VoiceProofPack, VoiceProofPackEvidence, VoiceProofPackInput, VoiceProofPackRoutesOptions, VoiceProofPackSection, VoiceProofPackStatus, VoiceProofPackWriteResult } from './proofPack';
+export { buildVoiceProofPack, buildVoiceProofPackFromObservabilityExport, createVoiceProofPackStaleWhileRefreshSource, createVoiceProofPackArtifacts, createVoiceProofPackOperationsRecordSection, createVoiceProofPackProductionReadinessSection, createVoiceProofPackProviderSloSection, createVoiceProofPackRoutes, createVoiceProofPackSupportBundleSection, renderVoiceProofPackMarkdown, writeVoiceProofPack } from './proofPack';
+export type { VoiceProofPack, VoiceProofPackEvidence, VoiceProofPackInput, VoiceProofPackRefreshState, VoiceProofPackRefreshStatus, VoiceProofPackRoutesOptions, VoiceProofPackSection, VoiceProofPackSourceValue, VoiceProofPackStatus, VoiceProofPackStaleWhileRefreshSource, VoiceProofPackStaleWhileRefreshSourceOptions, VoiceProofPackWriteResult } from './proofPack';
 export * from './types';

package/dist/index.js

@@ -39952,6 +39952,16 @@ import { Elysia as Elysia66 } from "elysia";
 import { mkdir as mkdir5 } from "fs/promises";
 import { dirname as dirname3, join as join4 } from "path";
 var toGeneratedAt = (value) => value === undefined ? new Date().toISOString() : typeof value === "number" ? new Date(value).toISOString() : value;
+var getProofPackMetadata = (proofPack) => {
+  const built = buildVoiceProofPack(proofPack);
+  const generatedAt = built.generatedAt;
+  const generatedAtMs = Date.parse(generatedAt);
+  return {
+    generatedAt,
+    generatedAtMs: Number.isFinite(generatedAtMs) ? generatedAtMs : 0,
+    runId: built.runId
+  };
+};
 var summarizeProofPackSections = (sections) => {
   let pass = 0;
   let warn = 0;
@@ -40163,6 +40173,98 @@ var buildVoiceProofPack = (input) => {
     summary
   };
 };
+var createVoiceProofPackStaleWhileRefreshSource = (options) => {
+  const maxAgeMs = options.maxAgeMs ?? 5 * 60000;
+  const now = options.now ?? Date.now;
+  let refreshPromise;
+  let status = {
+    maxAgeMs,
+    refreshing: false,
+    state: "missing"
+  };
+  const updateStatusFromProofPack = (proofPack, refreshing = Boolean(refreshPromise)) => {
+    const metadata = getProofPackMetadata(proofPack);
+    const ageMs = Math.max(0, now() - metadata.generatedAtMs);
+    status = {
+      ageMs,
+      generatedAt: metadata.generatedAt,
+      lastRefreshCompletedAt: status.lastRefreshCompletedAt,
+      lastRefreshStartedAt: status.lastRefreshStartedAt,
+      maxAgeMs,
+      refreshing,
+      runId: metadata.runId,
+      state: refreshing ? "refreshing" : ageMs <= maxAgeMs ? "fresh" : "stale"
+    };
+    return { ageMs, metadata };
+  };
+  const refresh = async () => {
+    const refreshed = await options.refresh();
+    const proofPack = refreshed ?? await options.read();
+    updateStatusFromProofPack(proofPack, false);
+    status = {
+      ...status,
+      lastRefreshCompletedAt: now(),
+      lastRefreshStartedAt: status.lastRefreshStartedAt,
+      refreshing: false,
+      state: "fresh"
+    };
+    return proofPack;
+  };
+  const startRefresh = () => {
+    if (!refreshPromise) {
+      status = {
+        ...status,
+        lastRefreshStartedAt: now(),
+        refreshing: true,
+        state: "refreshing"
+      };
+    }
+    refreshPromise ??= refresh().finally(() => {
+      refreshPromise = undefined;
+    });
+    return refreshPromise;
+  };
+  const source = async () => {
+    let current;
+    try {
+      current = await options.read();
+    } catch (error) {
+      status = {
+        ...status,
+        error: error instanceof Error ? error.message : String(error),
+        refreshing: Boolean(refreshPromise),
+        state: refreshPromise ? "refreshing" : "missing"
+      };
+      return startRefresh().catch((refreshError) => {
+        status = {
+          ...status,
+          error: refreshError instanceof Error ? refreshError.message : String(refreshError),
+          lastRefreshCompletedAt: now(),
+          refreshing: false,
+          state: "failed"
+        };
+        throw refreshError;
+      });
+    }
+    const { ageMs } = updateStatusFromProofPack(current);
+    if (ageMs <= maxAgeMs) {
+      return current;
+    }
+    startRefresh().catch((error) => {
+      status = {
+        ...status,
+        error: error instanceof Error ? error.message : String(error),
+        lastRefreshCompletedAt: now(),
+        refreshing: false,
+        state: "failed"
+      };
+      options.onRefreshError?.(error);
+    });
+    return current;
+  };
+  source.getStatus = () => status;
+  return source;
+};
 var buildVoiceProofPackFromObservabilityExport = (report, input = {}) => buildVoiceProofPack({
   ...input,
   artifacts: report.artifacts,
@@ -40725,6 +40827,7 @@ export {
   createVoiceProofTrendRecommendationRoutes,
   createVoiceProofTraceStore,
   createVoiceProofPackSupportBundleSection,
+  createVoiceProofPackStaleWhileRefreshSource,
   createVoiceProofPackRoutes,
   createVoiceProofPackProviderSloSection,
   createVoiceProofPackProductionReadinessSection,

package/dist/proofPack.d.ts

@@ -53,12 +53,35 @@ export type VoiceProofPackWriteResult = {
     markdownPath: string;
     proofPack: VoiceProofPack;
 };
+export type VoiceProofPackSourceValue = VoiceProofPack | VoiceProofPackInput;
+export type VoiceProofPackStaleWhileRefreshSourceOptions = {
+    maxAgeMs?: number;
+    now?: () => number;
+    onRefreshError?: (error: unknown) => void;
+    read: () => VoiceProofPackSourceValue | Promise<VoiceProofPackSourceValue>;
+    refresh: () => VoiceProofPackSourceValue | void | Promise<VoiceProofPackSourceValue | void>;
+};
+export type VoiceProofPackRefreshState = 'failed' | 'fresh' | 'missing' | 'refreshing' | 'stale';
+export type VoiceProofPackRefreshStatus = {
+    ageMs?: number;
+    error?: string;
+    generatedAt?: string;
+    lastRefreshCompletedAt?: number;
+    lastRefreshStartedAt?: number;
+    maxAgeMs: number;
+    refreshing: boolean;
+    runId?: string;
+    state: VoiceProofPackRefreshState;
+};
+export type VoiceProofPackStaleWhileRefreshSource = ((...args: []) => Promise<VoiceProofPackSourceValue>) & {
+    getStatus: () => VoiceProofPackRefreshStatus;
+};
 export type VoiceProofPackRoutesOptions = {
     headers?: HeadersInit;
     jsonPath?: false | string;
     markdownPath?: false | string;
     name?: string;
-    source: VoiceProofPack | VoiceProofPackInput | (() => VoiceProofPack | VoiceProofPackInput | Promise<VoiceProofPack | VoiceProofPackInput>);
+    source: VoiceProofPackSourceValue | (() => VoiceProofPackSourceValue | Promise<VoiceProofPackSourceValue>);
 };
 export declare const createVoiceProofPackProviderSloSection: (report: VoiceProviderSloReport, options?: {
     href?: string;
@@ -77,6 +100,7 @@ export declare const createVoiceProofPackSupportBundleSection: (input: {
     title?: string;
 }) => VoiceProofPackSection;
 export declare const buildVoiceProofPack: (input: VoiceProofPackInput | VoiceProofPack) => VoiceProofPack;
+export declare const createVoiceProofPackStaleWhileRefreshSource: (options: VoiceProofPackStaleWhileRefreshSourceOptions) => VoiceProofPackStaleWhileRefreshSource;
 export declare const buildVoiceProofPackFromObservabilityExport: (report: VoiceObservabilityExportReport, input?: Omit<VoiceProofPackInput, "artifacts" | "sections">) => VoiceProofPack;
 export declare const renderVoiceProofPackMarkdown: (proofPack: VoiceProofPack) => string;
 export declare const writeVoiceProofPack: (input: VoiceProofPackInput | VoiceProofPack, options?: {

package/package.json

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