@flame0510/project-aether 1.1.9

package/lib/patterns/SessionFactory.ts

@@ -0,0 +1,117 @@
+// Factory pattern: creates canonical Session objects from unknown raw input
+import type { Session, SessionEvent, TreeNode } from '../types';
+import { adaptSession, adaptEvent } from './ApiAdapter';
+import { nodeLabel, shortLabel } from './sessionPresentation';
+
+/** Produces normalized Session instances from arbitrary raw data. */
+export class SessionFactory {
+  static create(raw: unknown): Session {
+    if (!raw || typeof raw !== 'object') {
+      return {
+        session_id: '',
+        status: 'idle',
+      };
+    }
+    return adaptSession(raw as Record<string, unknown>);
+  }
+
+  static createMany(raws: unknown[]): Session[] {
+    return raws.map(SessionFactory.create);
+  }
+}
+
+/** Produces normalized SessionEvent instances from arbitrary raw data. */
+export class EventFactory {
+  static create(raw: unknown): SessionEvent {
+    if (!raw || typeof raw !== 'object') return {};
+    return adaptEvent(raw as Record<string, unknown>);
+  }
+
+  static createMany(raws: unknown[]): SessionEvent[] {
+    return raws.map(EventFactory.create);
+  }
+}
+
+// ── Helpers used by tree building ──────────────────────────────────────────
+
+export function extractAgentId(sessionId: string): string {
+  return sessionId.split(':')[1] ?? 'unknown';
+}
+
+
+export function isCronSession(sessionId: string): boolean {
+  return sessionId.includes(':cron:');
+}
+
+/** Builds the D3 tree hierarchy from a flat session list. */
+export function buildSessionTree(sessions: Session[], filter: string): TreeNode {
+  const normalizedFilter = filter.toLowerCase();
+  const filtered =
+    normalizedFilter === 'all'
+      ? sessions
+      : sessions.filter((s) => extractAgentId(s.session_id) === normalizedFilter);
+
+  const root: TreeNode = {
+    session_id: '__root__',
+    name: 'Argus',
+    status: 'idle',
+    _virtualRoot: true,
+    children: [],
+  };
+
+  const byId = new Map<string, TreeNode>();
+  const groups = new Map<string, Session[]>();
+
+  for (const session of filtered) {
+    if (!session.session_id) continue;
+    const node: TreeNode & { lineage_label?: string | null; task_preview?: string | null } = {
+      session_id: session.session_id,
+      name: session.label ?? shortLabel(session.session_id),
+      lineage_label: session.lineage_label ?? (session.label !== session.session_id ? session.label : null) ?? null,
+      task_preview: session.task_preview ?? null,
+      status: session.status,
+      model: session.model,
+      cost_usd: session.cost_usd ?? 0,
+      children: [],
+    };
+    byId.set(session.session_id, node);
+    const aid = extractAgentId(session.session_id);
+    if (!groups.has(aid)) groups.set(aid, []);
+    groups.get(aid)!.push(session);
+  }
+
+  const hasChild = (parent: TreeNode, childId: string) =>
+    (parent.children ?? []).some((c) => c.session_id === childId);
+
+  for (const [aid, agentSessions] of groups.entries()) {
+    const mainId = `agent:${aid}:main`;
+    const mainNode = byId.get(mainId);
+
+    const agentNode: TreeNode =
+      mainNode ?? {
+        session_id: `__agent__:${aid}`,
+        name: aid,
+        status: 'idle',
+        _agentNode: true,
+        children: [],
+      };
+
+    root.children!.push(agentNode);
+
+    for (const s of agentSessions) {
+      const sid = s.session_id;
+      if (!sid) continue;
+      if (mainNode && sid === mainId) continue;
+
+      const node = byId.get(sid);
+      if (!node) continue;
+
+      const parentNode = s.parent_id ? byId.get(s.parent_id) : undefined;
+      const fallbackParent = parentNode && !parentNode._virtualRoot ? parentNode : agentNode;
+      fallbackParent.children = fallbackParent.children ?? [];
+      if (!hasChild(fallbackParent, sid)) fallbackParent.children.push(node);
+    }
+  }
+
+  return root;
+}

package/lib/patterns/sessionPresentation.ts

@@ -0,0 +1,117 @@
+import type { Session, TreeNode } from '../types';
+import { ACTIVE_STATUSES } from '../types';
+
+function normalizeDisplayLabel(value: string | null | undefined): string {
+  const label = String(value ?? '').trim();
+  if (!label) return '';
+  if (/^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(label)) return '';
+  if (/^(agent:[^\s]+:subagent:[0-9a-f-]+|subagent:[0-9a-f-]{8,}|session:[0-9a-f-]{8,})$/i.test(label)) return '';
+  if (/^agent:[a-z0-9_-]+(:[a-z0-9_-]+)*$/i.test(label)) return ''; // agent:ops:main, agent:ops:telegram:...
+  if (/^sub\s*agent\b[:\s-]*[a-z0-9-]+$/i.test(label)) return '';
+  return label;
+}
+
+function prettifyAgentName(value: string): string {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+export function shortLabel(sessionId: string): string {
+  if (!sessionId) return 'session';
+  const parts = sessionId.split(':');
+  if (parts.length >= 4) return `${parts[2]}:${parts[3].slice(0, 6)}`;
+  if (parts.length >= 2) return `${parts[1]}:${parts[parts.length - 1].slice(0, 6)}`;
+  return sessionId.slice(0, 14);
+}
+
+function stripTaskBoilerplate(value: string): string {
+  return value
+    .replace(/^\[Subagent Task\]\s*/i, '')
+    .replace(/^Task richiesto da .*?:\s*/i, '')
+    .replace(/^Sei [^.\n]+\.\s*/i, '')
+    .replace(/^Begin\.?\s*/i, '')
+    .trim();
+}
+
+function summarizeTaskPreview(taskPreview: string | null | undefined): string {
+  const raw = String(taskPreview ?? '').replace(/\s+/g, ' ').trim();
+  if (!raw) return '';
+
+  const lines = String(taskPreview ?? '')
+    .split(/\r?\n/)
+    .map((line) => stripTaskBoilerplate(line.trim()))
+    .filter(Boolean);
+
+  const candidate = lines.find((line) => line.length >= 6 && !/^[-*#0-9.)\s]+$/.test(line)) ?? stripTaskBoilerplate(raw);
+  if (!candidate) return '';
+
+  const cleaned = candidate
+    .replace(/^[\-•*]\s*/, '')
+    .replace(/^\d+[.)]\s*/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (!cleaned) return '';
+  return cleaned.length > 48 ? `${cleaned.slice(0, 45).trimEnd()}…` : cleaned;
+}
+
+function isSubagentSessionId(sessionId: string): boolean {
+  return sessionId.includes(':subagent:') || sessionId.startsWith('subagent:');
+}
+
+function subagentFallback(sessionId: string): string {
+  // es. agent:ops:subagent:UUID → "Ops Agent"
+  // es. agent:ops:cron:UUID → "Ops Cron"
+  const parts = sessionId.split(':');
+  const agentName = parts[1] ? prettifyAgentName(parts[1]) : '';
+  const kind = parts[2] ?? 'subagent';
+  if (kind === 'cron') return agentName ? `${agentName} Cron` : 'Cron';
+  const suffix = parts[3]?.replace(/[^a-z0-9]/gi, '').slice(0, 6) ?? '';
+  return agentName ? `${agentName} · ${suffix}` : suffix ? `Task ${suffix}` : 'Task';
+}
+
+const ACTIVE_WINDOW_MS = 5 * 60_000; // 5 minutes
+
+export function isSessionActive(session: Pick<Session, 'status' | 'updated_at' | 'session_id'>): boolean {
+  if (ACTIVE_STATUSES.has(session.status)) return true;
+  // Also consider recently-updated sessions as active (just finished / heartbeat)
+  if (session.updated_at && Date.now() - session.updated_at < ACTIVE_WINDOW_MS) return true;
+  return false;
+}
+
+export function deriveSessionDisplayLabel(session: Pick<Session, 'session_id' | 'label' | 'lineage_label' | 'task_preview'>): string {
+  const sid = session.session_id || '';
+  const lineageLabel = normalizeDisplayLabel(session.lineage_label);
+  const directLabel = normalizeDisplayLabel(session.label);
+  const taskLabel = summarizeTaskPreview(session.task_preview);
+
+  if (lineageLabel) return lineageLabel;
+  if (directLabel && !directLabel.startsWith('agent:')) return directLabel;
+  if (taskLabel) return taskLabel;
+
+  if (sid.endsWith(':main')) {
+    const agent = sid.split(':')[1] ?? '';
+    if (agent) return prettifyAgentName(agent);
+  }
+
+  if (isSubagentSessionId(sid)) return subagentFallback(sid);
+  return shortLabel(sid);
+}
+
+export function nodeLabel(session: TreeNode & { lineage_label?: string | null; task_preview?: string | null }): string {
+  if (session._virtualRoot) return '';
+  if (session._agentNode) {
+    const raw = normalizeDisplayLabel((session as TreeNode & { name: string }).name);
+    return raw ? prettifyAgentName(raw) : 'Agent';
+  }
+
+  return deriveSessionDisplayLabel({
+    session_id: session.session_id,
+    label: session.name,
+    lineage_label: session.lineage_label,
+    task_preview: session.task_preview,
+  });
+}

package/lib/provider-balance.ts

@@ -0,0 +1,163 @@
+/**
+ * Provider Balance — fetch account balance/credits from upstream AI providers.
+ *
+ * Each provider has its own non-standard endpoint and response format.
+ * We normalize them all to a common {balance, currency, raw} shape.
+ *
+ * Currently supported: deepseek, openrouter, glm (Z.AI)
+ * Not supported via API key: openai (needs cookie), anthropic, groq, qwen
+ */
+import { readProviderKeys } from '@/app/api/gateway/provider/keys';
+
+export interface BalanceResult {
+  /** Human-readable balance string, e.g. "$23.45" or "¥156.00" */
+  balance: string;
+  /** ISO currency code */
+  currency: string;
+  /** Raw value as number */
+  value: number;
+  /** Provider-specific extra info (optional) */
+  label?: string;
+}
+
+interface BalanceInfo {
+  currency: string;
+  total_balance: string;
+  topped_up_balance?: string;
+  granted_balance?: string;
+}
+
+/* ------------------------------------------------------------------ */
+/*  DeepSeek                                                            */
+/* ------------------------------------------------------------------ */
+
+async function fetchDeepSeekBalance(apiKey: string): Promise<BalanceResult> {
+  const resp = await fetch('https://api.deepseek.com/user/balance', {
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+  });
+  if (!resp.ok) {
+    throw new Error(`DeepSeek balance API returned ${resp.status}`);
+  }
+  const json = await resp.json() as {
+    is_available: boolean;
+    balance_infos: BalanceInfo[];
+  };
+
+  const infos = json.balance_infos ?? [];
+  // Prefer CNY if available, else first entry
+  const cny = infos.find((i) => i.currency === 'CNY') ?? infos[0];
+  if (!cny) throw new Error('DeepSeek returned no balance info');
+
+  const value = parseFloat(cny.total_balance);
+  const currency = cny.currency;
+  const balance = `${currency === 'CNY' ? '¥' : '$'}${value.toFixed(2)}`;
+  return { balance, currency, value, label: 'Total balance' };
+}
+
+/* ------------------------------------------------------------------ */
+/*  OpenRouter                                                          */
+/* ------------------------------------------------------------------ */
+
+interface OpenRouterCredits {
+  data: {
+    total_credits: number;
+    total_usage: number;
+  };
+}
+
+async function fetchOpenRouterBalance(apiKey: string): Promise<BalanceResult> {
+  const resp = await fetch('https://openrouter.ai/api/v1/credits', {
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+  });
+  if (!resp.ok) {
+    throw new Error(`OpenRouter credits API returned ${resp.status}`);
+  }
+  const json = (await resp.json()) as OpenRouterCredits;
+  const value = Math.max(0, Math.round((json.data.total_credits - json.data.total_usage) * 100) / 100);
+  return { balance: `$${value.toFixed(2)}`, currency: 'USD', value, label: 'Available' };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Z.AI / GLM                                                          */
+/* ------------------------------------------------------------------ */
+
+interface ZAILimit {
+  /** e.g. "TOKENS_LIMIT" */
+  limitType: string;
+  limitValue: number;
+  /** remaining tokens */
+  remaining: number;
+  usage: number;
+  percentage: number;
+  nextResetTime?: string;
+}
+
+async function fetchZAIBalance(apiKey: string): Promise<BalanceResult> {
+  const resp = await fetch('https://api.z.ai/api/monitor/usage/quota/limit', {
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+  });
+  if (!resp.ok) {
+    throw new Error(`Z.AI quota API returned ${resp.status}`);
+  }
+  const json = await resp.json() as { limits?: ZAILimit[] };
+
+  const tokenLimit = json.limits?.find((l) => l.limitType === 'TOKENS_LIMIT');
+  if (tokenLimit) {
+    const usage = tokenLimit.usage ?? 0;
+    const limit = tokenLimit.limitValue ?? 0;
+    const remaining = tokenLimit.remaining ?? limit - usage;
+    const value = remaining;
+    // Show remaining + percentage
+    return {
+      balance: `${(remaining / 1_000_000).toFixed(1)}M tokens`,
+      currency: 'TOKENS',
+      value,
+      label: `${tokenLimit.percentage?.toFixed(0) ?? 0}% used of ${(limit / 1_000_000).toFixed(1)}M`,
+    };
+  }
+
+  // Fallback: sum all limits
+  const totalRemaining = (json.limits ?? []).reduce(
+    (sum, l) => sum + (l.remaining ?? l.limitValue - l.usage),
+    0,
+  );
+  return {
+    balance: `${(totalRemaining / 1_000_000).toFixed(1)}M tokens`,
+    currency: 'TOKENS',
+    value: totalRemaining,
+    label: 'Remaining',
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Public API                                                          */
+/* ------------------------------------------------------------------ */
+
+export type BalanceProvider = 'deepseek' | 'openrouter' | 'glm';
+
+const BALANCE_FETCHERS: Record<
+  BalanceProvider,
+  (apiKey: string) => Promise<BalanceResult>
+> = {
+  deepseek: fetchDeepSeekBalance,
+  openrouter: fetchOpenRouterBalance,
+  glm: fetchZAIBalance,
+};
+
+/** Fetch balance for a single provider. Throws if not supported or API key missing. */
+export async function fetchProviderBalance(
+  provider: BalanceProvider,
+): Promise<BalanceResult> {
+  const keys = readProviderKeys();
+  const apiKey = keys[provider];
+  if (!apiKey) {
+    throw new Error(`No API key configured for ${provider}`);
+  }
+
+  const fetcher = BALANCE_FETCHERS[provider];
+  if (!fetcher) {
+    throw new Error(`Balance fetching not supported for ${provider}`);
+  }
+
+  return fetcher(apiKey);
+}

package/lib/requireAuth.tsx

@@ -0,0 +1,38 @@
+import { cookies } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { jwtVerify } from 'jose';
+import * as fs from 'fs';
+import { ENV_FILE } from './rev4a-paths';
+
+function getJwtSecret(): Uint8Array {
+  const fromEnv = process.env.REV4A_JWT_SECRET;
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) {
+    return new TextEncoder().encode(fromEnv);
+  }
+  // Fallback: read from persistent .env
+  try {
+    if (fs.existsSync(ENV_FILE)) {
+      const content = fs.readFileSync(ENV_FILE, 'utf-8');
+      const match = content.match(/^REV4A_JWT_SECRET=(.*)$/m);
+      if (match && match[1].trim()) {
+        return new TextEncoder().encode(match[1].trim());
+      }
+    }
+  } catch { /* ignore */ }
+  return new TextEncoder().encode('');
+}
+
+export async function requireAuth(): Promise<void> {
+  const cookieStore = await cookies();
+  const token = cookieStore.get('rev4a_token')?.value;
+
+  if (token) {
+    try {
+      await jwtVerify(token, getJwtSecret());
+      return;
+    } catch {
+      // Invalid — redirect
+    }
+  }
+  redirect('/login');
+}

package/lib/rev4a-auth.d.ts

@@ -0,0 +1,3 @@
+import { NextResponse } from "next/server";
+export function requireAuth(request: Request): NextResponse | null;
+export function requireAuthJWT(request: Request): Promise<NextResponse | null>;

package/lib/rev4a-auth.js

@@ -0,0 +1,36 @@
+import { NextResponse } from "next/server";
+import { jwtVerify } from "jose";
+
+function getExpectedToken() {
+  const token = process.env.REV4A_TOKEN || process.env.NEXT_PUBLIC_REV4A_TOKEN || '';
+  if (!token) console.warn('REV4A_TOKEN is not set — auth will reject all requests');
+  return token;
+}
+
+export function requireAuth(request) {
+  const auth = request.headers.get("authorization");
+  if (!auth || auth !== `Bearer ${getExpectedToken()}`) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  return null;
+}
+
+const JWT_SECRET = new TextEncoder().encode(
+  process.env.REV4A_JWT_SECRET || ''
+);
+
+export async function requireAuthJWT(request) {
+  const cookieToken = request.cookies?.get?.("rev4a_token")?.value;
+  if (cookieToken) {
+    try {
+      await jwtVerify(cookieToken, JWT_SECRET);
+      return null;
+    } catch {}
+  }
+
+  const auth = request.headers.get("authorization");
+  const expectedToken = process.env.REV4A_TOKEN || process.env.NEXT_PUBLIC_REV4A_TOKEN || '';
+  if (auth === `Bearer ${expectedToken}`) return null;
+
+  return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+}

package/lib/rev4a-paths.ts

@@ -0,0 +1,145 @@
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+
+/**
+ * Centralised Rev4a data directory.
+ *
+ * Cross-platform policy:
+ *   Linux/macOS: ~/.config/rev4a/
+ *   Windows:     %APPDATA%/rev4a/
+ *
+ * All persistent files live here so npm reinstall / update
+ * never destroys configuration, databases, or secrets.
+ */
+function rev4aDataDir(): string {
+  if (process.env.REV4A_DATA_DIR) return process.env.REV4A_DATA_DIR;
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'rev4a');
+  }
+  return path.join(os.homedir(), '.config', 'rev4a');
+}
+
+export const REV4A_DATA = rev4aDataDir();
+
+/* ── File locations ─────────────────────────────────────────────── */
+
+/** Persistent environment file (~/.config/rev4a/.env) */
+export const ENV_FILE = path.join(REV4A_DATA, '.env');
+
+/** SQLite events database */
+export const DB_FILE = path.join(REV4A_DATA, 'data', 'events.db');
+
+/** Credentials vault database */
+export const CREDENTIALS_DB = path.join(REV4A_DATA, 'data', 'credentials.db');
+
+/** Shared gateway token for agent containers */
+export const AGENTS_TOKEN_FILE = path.join(REV4A_DATA, 'data', 'agents-token.json');
+
+/** Provider API keys JSON */
+export const PROVIDER_KEYS_FILE = path.join(REV4A_DATA, 'data', 'provider-keys.json');
+
+/**
+ * Model catalogue — read-only, shipped with the package.
+ * Resolved at module load from the package root (alongside bin/rev4a.js).
+ */
+function resolvePackageFile(filename: string): string {
+  // cwd in dev (workspace checkout)
+  const cwdPath = path.join(process.cwd(), filename);
+  if (fs.existsSync(cwdPath)) return cwdPath;
+
+  // Installed package: this file is at <pkgRoot>/lib/rev4a-paths.js
+  const pkgRoot = path.resolve(__dirname, '..');
+  const pkgPath = path.join(pkgRoot, filename);
+  if (fs.existsSync(pkgPath)) return pkgPath;
+
+  // Last resort: accept that it may not exist (will throw at read time)
+  return cwdPath;
+}
+
+/** Static model catalogue — read-only, inside the package repo */
+export const MODELS_CONFIG_FILE = resolvePackageFile('models.config.json');
+
+/** Top-level .next build directory (kept inside npm package for now — built by rev4a serve) */
+export function nextDir(pkgRoot: string): string {
+  return path.join(pkgRoot, '.next');
+}
+
+/** Agent template directory (inside npm package — read-only) */
+export function templatesDir(pkgRoot: string): string {
+  return path.join(pkgRoot, 'agent-templates');
+}
+
+/** Docker base image dir */
+export function dockerfileDir(pkgRoot: string): string {
+  return path.join(pkgRoot, 'agent-templates', 'base-image');
+}
+
+/* ── Helpers ────────────────────────────────────────────────────── */
+
+/** Ensure the data directory tree exists. */
+export function ensurePaths(): void {
+  for (const dir of [REV4A_DATA, path.dirname(ENV_FILE), path.dirname(DB_FILE)]) {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Read REV4A_* env vars from the persistent .env file.
+ * Returns a plain object suitable for spreading into child process env.
+ */
+export function loadEnvVars(): Record<string, string> {
+  const vars: Record<string, string> = {};
+  if (!fs.existsSync(ENV_FILE)) return vars;
+
+  const content = fs.readFileSync(ENV_FILE, 'utf-8');
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const val = trimmed.slice(eq + 1).trim();
+    if (key.startsWith('REV4A_') || key.startsWith('PROVIDER_')) {
+      vars[key] = val;
+    }
+  }
+  return vars;
+}
+
+/**
+ * Write a key-value pair to the persistent .env file.
+ * Replaces existing value for the same key, appends if missing.
+ */
+export function writeEnvVar(key: string, value: string): void {
+  ensurePaths();
+  let content = '';
+  if (fs.existsSync(ENV_FILE)) {
+    content = fs.readFileSync(ENV_FILE, 'utf-8');
+  }
+
+  const lines = content.split('\n');
+  let found = false;
+  const updated = lines.map((line) => {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(`${key}=`)) {
+      found = true;
+      return `${key}=${value}`;
+    }
+    return line;
+  });
+
+  if (!found) {
+    updated.push(`${key}=${value}`);
+  }
+
+  fs.writeFileSync(ENV_FILE, updated.join('\n').trim() + '\n', {
+    encoding: 'utf-8',
+    mode: 0o600,
+  });
+
+  // Also set in process.env so current process picks it up immediately
+  process.env[key] = value;
+}

package/lib/timezone.ts

@@ -0,0 +1,46 @@
+export const DEFAULT_REV4A_TIMEZONE = 'Europe/Rome';
+
+let timezoneCache: string | null = null;
+let timezonePromise: Promise<string> | null = null;
+
+export function normalizeRev4aTimezone(value: unknown): string {
+  return typeof value === 'string' && value ? value : DEFAULT_REV4A_TIMEZONE;
+}
+
+export async function fetchRev4aTimezone(): Promise<string> {
+  if (timezoneCache) return timezoneCache;
+  if (!timezonePromise) {
+    timezonePromise = fetch('/api/tools-config', {
+      cache: 'no-store',
+      credentials: 'same-origin',
+    })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const data = (await response.json()) as { timezone?: string };
+        const timezone = normalizeRev4aTimezone(data.timezone);
+        timezoneCache = timezone;
+        return timezone;
+      })
+      .catch(() => DEFAULT_REV4A_TIMEZONE)
+      .finally(() => {
+        timezonePromise = null;
+      });
+  }
+  return timezonePromise;
+}
+
+export function setCachedRev4aTimezone(timezone: string): void {
+  timezoneCache = normalizeRev4aTimezone(timezone);
+}
+
+export function formatDateTimeInTimezone(
+  value: string | number | Date,
+  options: Intl.DateTimeFormatOptions,
+  timezone = DEFAULT_REV4A_TIMEZONE,
+  locale = 'it-IT',
+): string {
+  return new Date(value).toLocaleString(locale, {
+    ...options,
+    timeZone: normalizeRev4aTimezone(timezone),
+  });
+}