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

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, 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 { buildVoiceProofPack, buildVoiceProofPackFromObservabilityExport, createVoiceProofPackBuildContext, createVoiceProofPackStaleWhileRefreshSource, createVoiceProofPackArtifacts, createVoiceProofPackOperationsRecordSection, createVoiceProofPackProductionReadinessSection, createVoiceProofPackProviderSloSection, createVoiceProofPackRoutes, createVoiceProofPackSupportBundleSection, renderVoiceProofPackMarkdown, writeVoiceProofPack } from './proofPack';
+export type { VoiceProofPack, VoiceProofPackBuildContext, VoiceProofPackBuildContextOptions, VoiceProofPackBuildTiming, 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;
@@ -39976,6 +39981,48 @@ var summarizeProofPackSections = (sections) => {
   }
   return { fail, pass, sections: sections.length, warn };
 };
+var createVoiceProofPackBuildContext = (options = {}) => {
+  const now = options.now ?? Date.now;
+  const cachedValues = new Map;
+  const timings = [];
+  const time = async (label, run) => {
+    const startedAt = now();
+    try {
+      return await run();
+    } finally {
+      const endedAt = now();
+      const timing = {
+        durationMs: Math.max(0, endedAt - startedAt),
+        endedAt,
+        label,
+        startedAt
+      };
+      timings.push(timing);
+      options.onTiming?.(timing);
+    }
+  };
+  const cache = (key, loader) => {
+    const cached = cachedValues.get(key);
+    if (cached) {
+      return cached;
+    }
+    const value = Promise.resolve(loader());
+    cachedValues.set(key, value);
+    return value;
+  };
+  return {
+    cache,
+    clear: (key) => {
+      if (key === undefined) {
+        cachedValues.clear();
+        return;
+      }
+      cachedValues.delete(key);
+    },
+    getTimings: () => [...timings],
+    time
+  };
+};
 var toProofPackStatus = (status) => {
   if (status === "fail" || status === "failed") {
     return "fail";
@@ -40172,29 +40219,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,
@@ -40763,6 +40874,7 @@ export {
   createVoiceProofPackProviderSloSection,
   createVoiceProofPackProductionReadinessSection,
   createVoiceProofPackOperationsRecordSection,
+  createVoiceProofPackBuildContext,
   createVoiceProofPackArtifacts,
   createVoiceProofAssertion,
   createVoiceProfileTraceTagger,

package/dist/proofPack.d.ts

@@ -53,6 +53,22 @@ export type VoiceProofPackWriteResult = {
     markdownPath: string;
     proofPack: VoiceProofPack;
 };
+export type VoiceProofPackBuildTiming = {
+    durationMs: number;
+    endedAt: number;
+    label: string;
+    startedAt: number;
+};
+export type VoiceProofPackBuildContext = {
+    cache: <TValue>(key: string, loader: () => Promise<TValue> | TValue) => Promise<TValue>;
+    clear: (key?: string) => void;
+    getTimings: () => VoiceProofPackBuildTiming[];
+    time: <TValue>(label: string, run: () => Promise<TValue> | TValue) => Promise<TValue>;
+};
+export type VoiceProofPackBuildContextOptions = {
+    now?: () => number;
+    onTiming?: (timing: VoiceProofPackBuildTiming) => void;
+};
 export type VoiceProofPackSourceValue = VoiceProofPack | VoiceProofPackInput;
 export type VoiceProofPackStaleWhileRefreshSourceOptions = {
     maxAgeMs?: number;
@@ -61,6 +77,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;
@@ -68,6 +99,7 @@ export type VoiceProofPackRoutesOptions = {
     name?: string;
     source: VoiceProofPackSourceValue | (() => VoiceProofPackSourceValue | Promise<VoiceProofPackSourceValue>);
 };
+export declare const createVoiceProofPackBuildContext: (options?: VoiceProofPackBuildContextOptions) => VoiceProofPackBuildContext;
 export declare const createVoiceProofPackProviderSloSection: (report: VoiceProviderSloReport, options?: {
     href?: string;
     title?: string;
@@ -85,7 +117,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.417",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",