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

package/dist/index.d.ts

@@ -207,5 +207,5 @@ export type { VoiceTelephonyCarrierMatrix, VoiceTelephonyCarrierMatrixEntry, Voi
 export { shapeTelephonyAssistantText } from './telephony/response';
 export type { TelephonyResponseShapeMode, TelephonyResponseShapeOptions } from './telephony/response';
 export { buildVoiceProofPack, buildVoiceProofPackFromObservabilityExport, createVoiceProofPackStaleWhileRefreshSource, createVoiceProofPackArtifacts, createVoiceProofPackOperationsRecordSection, createVoiceProofPackProductionReadinessSection, createVoiceProofPackProviderSloSection, createVoiceProofPackRoutes, createVoiceProofPackSupportBundleSection, renderVoiceProofPackMarkdown, writeVoiceProofPack } from './proofPack';
-export type { VoiceProofPack, VoiceProofPackEvidence, VoiceProofPackInput, VoiceProofPackRoutesOptions, VoiceProofPackSection, VoiceProofPackSourceValue, VoiceProofPackStatus, VoiceProofPackStaleWhileRefreshSourceOptions, VoiceProofPackWriteResult } 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,10 +39952,15 @@ 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 getProofPackGeneratedAtMs = (proofPack) => {
-  const generatedAt = buildVoiceProofPack(proofPack).generatedAt;
+var getProofPackMetadata = (proofPack) => {
+  const built = buildVoiceProofPack(proofPack);
+  const generatedAt = built.generatedAt;
   const generatedAtMs = Date.parse(generatedAt);
-  return Number.isFinite(generatedAtMs) ? generatedAtMs : 0;
+  return {
+    generatedAt,
+    generatedAtMs: Number.isFinite(generatedAtMs) ? generatedAtMs : 0,
+    runId: built.runId
+  };
 };
 var summarizeProofPackSections = (sections) => {
   let pass = 0;
@@ -40172,29 +40177,93 @@ 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();
-    return refreshed ?? options.read();
+    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;
   };
-  return async () => {
+  const source = async () => {
     let current;
     try {
       current = await options.read();
-    } catch {
-      return startRefresh();
+    } 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;
+      });
     }
-    if (now() - getProofPackGeneratedAtMs(current) <= maxAgeMs) {
+    const { ageMs } = updateStatusFromProofPack(current);
+    if (ageMs <= maxAgeMs) {
       return current;
     }
-    startRefresh().catch((error) => options.onRefreshError?.(error));
+    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,

package/dist/proofPack.d.ts

@@ -61,6 +61,21 @@ export type VoiceProofPackStaleWhileRefreshSourceOptions = {
     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;
@@ -85,7 +100,7 @@ export declare const createVoiceProofPackSupportBundleSection: (input: {
     title?: string;
 }) => VoiceProofPackSection;
 export declare const buildVoiceProofPack: (input: VoiceProofPackInput | VoiceProofPack) => VoiceProofPack;
-export declare const createVoiceProofPackStaleWhileRefreshSource: (options: VoiceProofPackStaleWhileRefreshSourceOptions) => () => Promise<VoiceProofPackSourceValue>;
+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.415",
+	"version": "0.0.22-beta.416",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",