@easyoref/shared 1.21.1

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,SAAS,EACT,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,cAAc,CAAC;AAItB,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC;AAGvE,eAAO,MAAM,cAAc,UAAU,CAAC;AAKtC,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAWzD;AAOD,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAItD,CAAC;AAEF,yCAAyC;AACzC,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAI3D,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAI5D,CAAC;AAIF,wBAAsB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlE;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAIhC;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAI9D;AAID,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAI3E;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CASlD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAG9D;AAID,wBAAsB,cAAc,IAAI,OAAO,CAC3C;IACE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;CACtB,GACD,SAAS,CACZ,CAQA;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,EAAE,CAAC,CAExB;AAID,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5E;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC,CAMjE;AAMD,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAIvD;AAED,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG/D;AAMD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAS9B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/store.js

@@ -0,0 +1,162 @@
+/**
+ * Session-based alert state store — Redis operations.
+ *
+ * A "session" spans the lifecycle of one attack event:
+ *   early_warning → (optional red_alert) → resolved → +10 min tail
+ *
+ * Keys:
+ *   session:active        — ActiveSession JSON         TTL 45min
+ *   session:posts         — LPUSH list of ChannelPost  TTL 45min
+ *   session:ext_cache     — HASH {post_hash → extraction JSON} TTL 45min
+ *   alert:{alertId}:meta  — AlertMeta JSON             TTL 20min
+ *
+ * Only the LATEST alert's Telegram message gets enrichment edits.
+ * Posts accumulate across the entire session (shared context).
+ */
+import { getRedis } from "./redis.js";
+import { createEmptyEnrichmentData } from "./schemas.js";
+// Schema version for migration handling
+export const SCHEMA_VERSION = "2.0.0";
+const SCHEMA_VERSION_KEY = "schema:version";
+let schemaVersionChecked = false;
+export async function ensureSchemaVersion() {
+    if (schemaVersionChecked)
+        return;
+    schemaVersionChecked = true;
+    const redis = getRedis();
+    const stored = await redis.get(SCHEMA_VERSION_KEY);
+    if (stored !== SCHEMA_VERSION) {
+        await redis.flushall();
+        await redis.set(SCHEMA_VERSION_KEY, SCHEMA_VERSION);
+    }
+}
+const META_TTL_S = 20 * 60; // 20 minutes
+const SESSION_TTL_S = 45 * 60; // 45 min worst case
+// ── Session phase timeouts ─────────────────────────────
+/** Max duration (ms) for each phase before auto-expire */
+export const PHASE_TIMEOUT_MS = {
+    early_warning: 30 * 60 * 1000, // 30 min
+    red_alert: 15 * 60 * 1000, // 15 min
+    resolved: 10 * 60 * 1000, // 10 min tail
+};
+/** Enrichment interval (ms) per phase */
+export const PHASE_ENRICH_DELAY_MS = {
+    early_warning: 60_000, // 60s — channels need time to post; saves tokens
+    red_alert: 45_000, // 45s
+    resolved: 150_000, // 150s (2.5 min) — per user requirement: 10 min window, update every 2.5 min
+};
+/** Initial enrichment delay — first job after alert (channels need time to post) */
+export const PHASE_INITIAL_DELAY_MS = {
+    early_warning: 120_000, // 2 min — wait for launch reports
+    red_alert: 15_000, // 15s
+    resolved: 90_000, // 90s — wait for first wave of post-incident reports
+};
+// ──Alert Meta (per-alert) ─────────────────────────────
+export async function saveAlertMeta(meta) {
+    const redis = getRedis();
+    await redis.setex(`alert:${meta.alertId}:meta`, META_TTL_S, JSON.stringify(meta));
+}
+export async function getAlertMeta(alertId) {
+    const redis = getRedis();
+    const raw = await redis.get(`alert:${alertId}:meta`);
+    return raw ? JSON.parse(raw) : undefined;
+}
+// ── Session posts (shared across entire session) ───────
+export async function pushSessionPost(post) {
+    const redis = getRedis();
+    await redis.lpush("session:posts", JSON.stringify(post));
+    await redis.expire("session:posts", SESSION_TTL_S);
+}
+export async function getSessionPosts() {
+    const redis = getRedis();
+    const items = await redis.lrange("session:posts", 0, -1);
+    return items.map((i) => JSON.parse(i));
+}
+// ── Active session ─────────────────────────────────────
+export async function setActiveSession(session) {
+    const redis = getRedis();
+    await redis.setex("session:active", SESSION_TTL_S, JSON.stringify(session));
+}
+export async function getActiveSession() {
+    const redis = getRedis();
+    const raw = await redis.get("session:active");
+    return raw ? JSON.parse(raw) : undefined;
+}
+export async function clearSession() {
+    const redis = getRedis();
+    await redis.del("session:active", "session:posts", "session:enrichment", EXT_CACHE_KEY, LAST_UPDATE_KEY);
+}
+export function isPhaseExpired(session) {
+    const elapsed = Date.now() - session.phaseStartTs;
+    return elapsed >= PHASE_TIMEOUT_MS[session.phase];
+}
+// ── Compat shims (used by gramjs-monitor, graph) ───────
+export async function getActiveAlert() {
+    const s = await getActiveSession();
+    if (!s)
+        return undefined;
+    return {
+        alertId: s.latestAlertId,
+        alertTs: s.latestAlertTs,
+        alertType: s.phase,
+    };
+}
+export async function pushChannelPost(_alertId, post) {
+    await pushSessionPost(post);
+}
+export async function getChannelPosts(_alertId) {
+    return getSessionPosts();
+}
+// ── Enrichment data (cross-phase persistence) ──────────
+export async function saveEnrichmentData(data) {
+    const redis = getRedis();
+    await redis.setex("session:enrichment", SESSION_TTL_S, JSON.stringify(data));
+}
+export async function getEnrichmentData() {
+    const redis = getRedis();
+    const raw = await redis.get("session:enrichment");
+    return raw
+        ? JSON.parse(raw)
+        : createEmptyEnrichmentData();
+}
+// ── Last update timestamp (tracks when last enrichment job ran) ──
+const LAST_UPDATE_KEY = "session:last_update_ts";
+export async function getLastUpdateTs() {
+    const redis = getRedis();
+    const raw = await redis.get(LAST_UPDATE_KEY);
+    return raw ? Number(raw) : 0;
+}
+export async function setLastUpdateTs(ts) {
+    const redis = getRedis();
+    await redis.setex(LAST_UPDATE_KEY, SESSION_TTL_S, String(ts));
+}
+// ── Extraction cache (post-level dedup between jobs) ───
+const EXT_CACHE_KEY = "session:ext_cache";
+/**
+ * Get cached extraction results for a batch of post hashes.
+ * Returns a map: postHash → serialized ValidatedExtraction JSON.
+ */
+export async function getCachedExtractions(postHashes) {
+    if (postHashes.length === 0)
+        return new Map();
+    const redis = getRedis();
+    const results = await redis.hmget(EXT_CACHE_KEY, ...postHashes);
+    const map = new Map();
+    postHashes.forEach((hash, i) => {
+        if (results[i])
+            map.set(hash, results[i]);
+    });
+    return map;
+}
+/**
+ * Save new extraction results to cache.
+ * @param entries - Record of postHash → serialized ValidatedExtraction JSON
+ */
+export async function saveCachedExtractions(entries) {
+    if (Object.keys(entries).length === 0)
+        return;
+    const redis = getRedis();
+    await redis.hset(EXT_CACHE_KEY, entries);
+    await redis.expire(EXT_CACHE_KEY, SESSION_TTL_S);
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@easyoref/shared",
+  "version": "1.21.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "ioredis": "^5.3.0",
+    "zod": "^4.3.6",
+    "@langchain/langgraph": "^1.2.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,248 @@
+/**
+ * EasyOref — Centralized Configuration
+ *
+ * Primary: config.yaml (searched in cwd, /app, /etc/easyoref)
+ * Fallback: environment variables + Docker secrets (for backward compat)
+ *
+ * See config.yaml.example for all available options.
+ */
+
+import yaml from "js-yaml";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { isValidLanguage, type Language } from "./i18n.js";
+import { type AlertTypeConfig, type GifMode } from "./schemas.js";
+
+// ── Types ────────────────────────────────────────────────
+
+const VALID_GIF_MODES: GifMode[] = ["funny_cats", "none"];
+
+const ALL_ALERT_TYPES: AlertTypeConfig[] = ["early", "red_alert", "resolved"];
+
+/** Raw YAML schema */
+interface ConfigYaml {
+  alert_types?: AlertTypeConfig[];
+  city_ids?: number[];
+  language?: string;
+  gif_mode?: string;
+  emoji_override?: Partial<Record<AlertTypeConfig, string>>;
+  title_override?: Partial<Record<AlertTypeConfig, string>>;
+  description_override?: Partial<Record<AlertTypeConfig, string>>;
+  observability?: {
+    betterstack_token?: string;
+  };
+  telegram?: {
+    bot_token?: string;
+    chat_id?: string | string[];
+  };
+  health_port?: number;
+  poll_interval_ms?: number;
+  data_dir?: string;
+  oref_api_url?: string;
+  oref_history_url?: string;
+  ai?: ConfigYamlAi;
+}
+
+interface ConfigYamlAi {
+  enabled?: boolean;
+  openrouter_api_key?: string;
+  openrouter_filter_model?: string;
+  openrouter_extract_model?: string;
+  redis_url?: string;
+  socks5_proxy?: string;
+  enrich_delay_ms?: number;
+  confidence_threshold?: number;
+  window_minutes?: number;
+  timeout_minutes?: number;
+  /** Enable MCP tool calling for low-confidence clarification */
+  mcp_tools?: boolean;
+  /** Number of recent posts to fetch per channel during clarify (1-4) */
+  clarify_fetch_count?: number;
+  mtproto?: {
+    api_id?: number;
+    api_hash?: string;
+    session_string?: string;
+  };
+  channels?: string[];
+  /** Map monitored area prefix → human-readable region label */
+  area_labels?: Record<string, string>;
+}
+
+// ── YAML Loader ──────────────────────────────────────────
+
+/** Config dir in user home — ~/.easyoref/ */
+export const CONFIG_DIR = join(homedir(), ".easyoref");
+export const HOME_CONFIG_PATH = join(CONFIG_DIR, "config.yaml");
+
+const CONFIG_SEARCH_PATHS = [
+  HOME_CONFIG_PATH,
+  "config.yaml",
+  "config.yml",
+  "/app/config.yaml",
+  "/etc/easyoref/config.yaml",
+];
+
+function findConfigFile(): string | null {
+  const envPath = process.env.EASYOREF_CONFIG;
+  if (envPath && existsSync(envPath)) return envPath;
+  for (const p of CONFIG_SEARCH_PATHS) {
+    const abs = resolve(p);
+    if (existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+function loadYaml(): ConfigYaml {
+  const path = findConfigFile();
+  if (path) {
+    try {
+      const raw = readFileSync(path, "utf-8");
+      const parsed = yaml.load(raw) as ConfigYaml;
+      // eslint-disable-next-line no-console
+      console.log(`[config] Loaded from ${path}`);
+      return parsed ?? {};
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(`[config] Failed to parse ${path}:`, err);
+    }
+  }
+  return {};
+}
+
+// ── Helpers ──────────────────────────────────────────────
+
+function readSecret(envKey: string, secretPaths: string[]): string {
+  for (const p of secretPaths) {
+    if (existsSync(p)) return readFileSync(p, "utf-8").trim();
+  }
+  return process.env[envKey] ?? "";
+}
+
+function parseGifMode(raw: string): GifMode {
+  const lower = raw.toLowerCase() as GifMode;
+  return VALID_GIF_MODES.includes(lower) ? lower : "none";
+}
+
+function parseAlertTypes(raw?: AlertTypeConfig[]): AlertTypeConfig[] {
+  if (!raw || !Array.isArray(raw)) return ALL_ALERT_TYPES;
+  return raw.filter((t) => ALL_ALERT_TYPES.includes(t));
+}
+
+// ── Build Config ─────────────────────────────────────────
+
+const yml = loadYaml();
+
+const parsedChatIds: string[] = (() => {
+  const raw = yml.telegram?.chat_id ?? process.env.CHAT_ID ?? "";
+  if (Array.isArray(raw)) return raw.map(String).filter(Boolean);
+  return String(raw)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+})();
+
+export const config = {
+  /** Telegram bot token */
+  botToken:
+    yml.telegram?.bot_token ??
+    readSecret("BOT_TOKEN", ["/run/secrets/bot_token", "secrets/bot_token"]),
+
+  /** All Telegram chat IDs to broadcast to */
+  chatIds: parsedChatIds,
+
+  /** Primary Telegram chat ID (first in the list) */
+  chatId: parsedChatIds[0] ?? "",
+
+  /** City IDs to monitor (resolved to Hebrew names at startup via cities.json) */
+  cityIds: yml.city_ids ?? [],
+
+  /**
+   * Hebrew area names — legacy fallback for AREAS env var.
+   * Populated at startup from cityIds OR from AREAS env if no cityIds.
+   */
+  areas: [] as string[],
+
+  /** Which alert types to send */
+  alertTypes: parseAlertTypes(yml.alert_types),
+
+  /** Message language */
+  language: ((): Language => {
+    const raw = (yml.language ?? process.env.LANGUAGE ?? "ru").toLowerCase();
+    return isValidLanguage(raw) ? raw : "ru";
+  })(),
+
+  /** Emoji overrides per alert type */
+  emojiOverride: yml.emoji_override ?? {},
+
+  /** Title overrides per alert type */
+  titleOverride: yml.title_override ?? {},
+
+  /** Description overrides per alert type */
+  descriptionOverride: yml.description_override ?? {},
+
+  /** Oref API polling interval (ms) */
+  pollIntervalMs:
+    yml.poll_interval_ms ?? Number(process.env.OREF_POLL_INTERVAL_MS ?? "2000"),
+
+  /** Health endpoint port */
+  healthPort: yml.health_port ?? Number(process.env.HEALTH_PORT ?? "3100"),
+
+  /** Oref API URL */
+  orefApiUrl:
+    yml.oref_api_url ??
+    process.env.OREF_API_URL ??
+    "https://www.oref.org.il/WarningMessages/alert/alerts.json",
+
+  /** Oref alert history URL (base, without date params) */
+  orefHistoryUrl: yml.oref_history_url ?? process.env.OREF_HISTORY_URL ?? "",
+
+  /** Better Stack Logtail token */
+  logtailToken:
+    yml.observability?.betterstack_token ?? process.env.LOGTAIL_TOKEN ?? "",
+
+  /** GIF mode */
+  gifMode: parseGifMode(yml.gif_mode ?? process.env.GIF_MODE ?? "none"),
+
+  /** Path for persistent data */
+  dataDir: yml.data_dir ?? process.env.DATA_DIR ?? join(CONFIG_DIR, "data"),
+
+  /** AI enrichment config (YAML key: `ai`) */
+  agent: (() => {
+    const ai = yml.ai;
+    return {
+      enabled: ai?.enabled ?? false,
+      apiKey: ai?.openrouter_api_key ?? process.env.OPENROUTER_API_KEY ?? "",
+      filterModel:
+        ai?.openrouter_filter_model ?? "google/gemini-2.5-flash-lite",
+      extractModel:
+        ai?.openrouter_extract_model ?? "google/gemini-3.1-flash-lite-preview",
+      redisUrl:
+        ai?.redis_url ?? process.env.REDIS_URL ?? "redis://localhost:6379",
+      socks5Proxy: ai?.socks5_proxy ?? process.env.SOCKS5_PROXY ?? "",
+      enrichDelayMs: ai?.enrich_delay_ms ?? 20_000,
+      confidenceThreshold: ai?.confidence_threshold ?? 0.7,
+      windowMinutes: ai?.window_minutes ?? 2,
+      timeoutMinutes: ai?.timeout_minutes ?? 15,
+      mtproto: {
+        apiId: ai?.mtproto?.api_id ?? Number(process.env.TG_API_ID ?? "0"),
+        apiHash: ai?.mtproto?.api_hash ?? process.env.TG_API_HASH ?? "",
+        sessionString:
+          ai?.mtproto?.session_string ?? process.env.TG_SESSION ?? "",
+      },
+      channels: ai?.channels ?? [],
+      areaLabels: ai?.area_labels ?? {},
+      /** Enable MCP tool calling — deterministic fan-out on low confidence */
+      mcpTools: ai?.mcp_tools ?? false,
+      /** Posts per channel to fetch during clarify (1-4, default 3) */
+      clarifyFetchCount: Math.min(4, Math.max(1, ai?.clarify_fetch_count ?? 3)),
+    };
+  })(),
+};
+
+/** Exported for testing */
+export {
+  loadYaml as _loadYaml,
+  parseAlertTypes as _parseAlertTypes,
+  type ConfigYaml,
+};

package/src/helpers.ts

@@ -0,0 +1,17 @@
+/** Shared utility functions for the agent subsystem. */
+
+import { createHash } from "node:crypto";
+
+/** Format timestamp as HH:MM Israel time */
+export function toIsraelTime(ts: number): string {
+  return new Date(ts).toLocaleTimeString("he-IL", {
+    hour: "2-digit",
+    minute: "2-digit",
+    timeZone: "Asia/Jerusalem",
+  });
+}
+
+/** MD5 hash for dedup */
+export function textHash(text: string): string {
+  return createHash("md5").update(text).digest("hex");
+}