@vimoxshah/tokenflow 1.1.0

package/src/core/budget.js

@@ -0,0 +1,142 @@
+/**
+ * Budget forecasting alerts — projected month-end spend vs a configured
+ * budget, with persisted alert state to prevent notification spam.
+ *
+ * Config (config.yaml):
+ *
+ *   budget:
+ *     monthly: 200          # USD — your monthly cap
+ *     warnAtPct: 80         # alert when PROJECTED month-end >= 80% of budget
+ *
+ * States (monotonic per month, tracked in $TOKENFLOW_HOME/data/budget-state.json):
+ *   safe          — projection < warn threshold
+ *   approaching   — projection >= warnAtPct% of budget (fires once per month)
+ *   over_budget_projected — projection >= 100% of budget (fires once per month)
+ *   over_budget_actual    — measured MTD spend >= budget (fires once per month)
+ *
+ * Honesty rules:
+ *  - "projected" is always labelled as a projection; never shown as charged.
+ *  - If there is insufficient history for a forecast (< 3 days of data this
+ *    month), the state is "unknown" and no alert fires. Never fabricate $0.
+ *  - State resets when the calendar month changes, so each month can fire
+ *    its own approaching/over alerts exactly once.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// State file resolves from TOKENFLOW_HOME at CALL time (not import time) so
+// tests can isolate state via env without fighting module-level caching.
+const STATE_FILE = () => {
+  const home = process.env.TOKENFLOW_HOME || path.join(os.homedir(), '.tokenflow');
+  return path.join(home, 'data', 'budget-state.json');
+};
+
+/**
+ * Compute the current budget state from a live status snapshot.
+ * @param {object} status live status (usage.monthToDate, velocity, forecast)
+ * @param {{monthly:number, warnAtPct?:number}} budget config.budget
+ * @param {string} today YYYY-MM-DD
+ */
+export function computeBudgetState(status, budget, today) {
+  if (!budget?.monthly || !(budget.monthly > 0)) return null;
+  const mtd = status.usage?.monthToDate;
+  if (!mtd) return null;
+
+  const spent = mtd.cost ?? null;                    // estimated; measured kept separate
+  if (spent == null) return { state: 'unknown', reason: 'no priced usage yet this month' };
+
+  const warnPct = (budget.warnAtPct ?? 80) / 100;
+  const monthKey = today.slice(0, 7);
+
+  // Actual overage is checkable immediately and needs no forecast.
+  if (spent >= budget.monthly) {
+    return {
+      state: 'over_budget_actual', monthKey,
+      spent, budget: budget.monthly,
+      message: `Month-to-date spend ${fmt(spent)} has reached your ${fmt(budget.monthly)} budget.`,
+    };
+  }
+
+  // Projected month-end: prefer the engine's linear-trend forecast cost;
+  // fall back to pace-based extrapolation only if velocity exists.
+  const projected = status.forecast?.monthEndCost ?? projectFromPace(status, today);
+  if (projected == null) {
+    return {
+      state: 'unknown', monthKey,
+      spent, budget: budget.monthly,
+      reason: 'not enough history this month for a forecast',
+    };
+  }
+
+  const pct = projected / budget.monthly;
+  if (pct >= 1) {
+    return {
+      state: 'over_budget_projected', monthKey,
+      spent, projected, budget: budget.monthly,
+      message: `Projected month-end spend ${fmt(projected)} exceeds your ${fmt(budget.monthly)} budget (projection, not an actual charge).`,
+    };
+  }
+  if (pct >= warnPct) {
+    return {
+      state: 'approaching', monthKey,
+      spent, projected, budget: budget.monthly,
+      message: `Projected month-end spend ${fmt(projected)} is ${Math.round(pct * 100)}% of your ${fmt(budget.monthly)} budget.`,
+    };
+  }
+  return { state: 'safe', monthKey, spent, projected, budget: budget.monthly };
+}
+
+function projectFromPace(status, today) {
+  const v = status.velocity;
+  if (!v?.todayTokensPerHour || !status.usage?.monthToDate?.cost) return null;
+  // Pace-based cost projection needs cost-per-token which we do not track
+  // here; defer to the engine's forecast rather than inventing a rate.
+  return null;
+}
+
+function fmt(n) { return `$${(Math.round(n * 100) / 100).toLocaleString('en-US')}`; }
+
+/**
+ * Decide whether an alert should FIRE now, given persisted state.
+ * Dedup: each state fires once per calendar month. Escalation
+ * (approaching → over_budget_projected / over_budget_actual) re-fires because
+ * it is strictly more urgent than what was already sent.
+ * @returns {{fire: boolean, state: object}}
+ */
+export function shouldAlert(newState, opt = {}) {
+  if (!newState || newState.state === 'safe' || newState.state === 'unknown') {
+    persist({ state: newState?.state || 'safe', monthKey: newState?.monthKey });
+    return { fire: false, state: newState };
+  }
+  const prev = loadState();
+  const sameMonth = prev?.monthKey === newState.monthKey;
+  const RANK = { safe: 0, unknown: 0, approaching: 1, over_budget_projected: 2, over_budget_actual: 3 };
+
+  let fire;
+  if (!sameMonth) {
+    fire = true;                                   // new month → alert again
+  } else if ((RANK[newState.state] ?? 0) > (RANK[prev.state] ?? 0)) {
+    fire = true;                                   // escalated urgency
+  } else {
+    fire = false;                                  // already alerted at this level
+  }
+
+  if (opt.force) fire = true;
+  if (fire) persist({ state: newState.state, monthKey: newState.monthKey });
+  return { fire, state: newState };
+}
+
+function loadState() {
+  try { return JSON.parse(fs.readFileSync(STATE_FILE(), 'utf8')); } catch { return null; }
+}
+function persist(s) {
+  try {
+    const file = STATE_FILE();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ ...s, updatedAt: new Date().toISOString() }));
+  } catch { /* best-effort */ }
+}
+
+/** Reset state (new month detected by callers, or user command). */
+export function resetBudgetState() { try { fs.unlinkSync(STATE_FILE()); } catch { /* absent */ } }

package/src/core/bundle.js

@@ -0,0 +1,191 @@
+/**
+ * The data bundle handed to a dashboard (browser or snapshot).
+ *
+ * It is deliberately small: the pre-aggregated cube, one row per session, the
+ * daily work-activity rollup, and metadata. Request-level records stay on disk
+ * and are streamed on demand by the Data Explorer, so opening the dashboard
+ * never means shipping a gigabyte into a browser tab.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { Store, readJson } from './store.js';
+import { paths, loadConfig } from './config.js';
+import { summarizeQuality } from './validate.js';
+import { tzOffsetMinutes } from './schema.js';
+import { PRICING_TABLE_VERSION, PRICING_SOURCES, TIER_MULTIPLIERS } from './pricing.js';
+
+export function buildBundle({ config = loadConfig() } = {}) {
+  const store = new Store();
+  const p = paths();
+  const cube = store.cube();
+  const sessions = store.sessionList();
+  const activity = store.activity();
+  const pricing = readJson(p.pricing, {});
+  const health = summarizeQuality(cube, store.sessions(), store.state);
+
+  // Per-adapter date coverage, so "Date range" is never read as if every
+  // source covered all of it.
+  const perSource = new Map();
+  for (const s of sessions) {
+    const e = perSource.get(s.so) || { from: null, to: null, sessions: 0, tokens: 0 };
+    if (e.from === null || s.d < e.from) e.from = s.d;
+    if (e.to === null || s.d > e.to) e.to = s.d;
+    e.sessions++;
+    e.tokens += s.total || 0;
+    perSource.set(s.so, e);
+  }
+  const providersState = Object.entries(store.state.sources || {}).map(([id, s]) => ({
+    id,
+    records: s.records || 0,
+    files: Object.keys(s.files || {}).length,
+    lastRefresh: s.lastRefresh || null,
+    coverage: perSource.get(id) ? { from: perSource.get(id).from, to: perSource.get(id).to } : null,
+    sessions: perSource.get(id)?.sessions ?? 0,
+    tokens: perSource.get(id)?.tokens ?? 0,
+  }));
+
+  const demo = sessions.some((s) => s.so === 'mock') || cube.rows.some((r) => r[6] === 'mock');
+  const coverage = health.coverage;
+  const tz = cube.tz || config.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+  return {
+    meta: {
+      generatedAt: new Date().toISOString(),
+      appVersion: readJson(path.join(rootDir(), 'package.json'), {}).version || '0.0.0',
+      cubeVersion: cube.version,
+      timezone: tz,
+      today: localToday(tz),
+      // Wall-clock offset of the dataset's timezone right now. Capacity reset
+      // countdowns and burn-rate hours are computed against this, so a limit
+      // resets when the *user's* calendar rolls over.
+      tzOffsetMinutes: tzOffsetMinutes(new Date(), tz),
+      pricingTableVersion: PRICING_TABLE_VERSION,
+      pricingSources: PRICING_SOURCES,
+      tierMultipliers: TIER_MULTIPLIERS,
+      lastRefresh: store.state.lastRefresh,
+      lastRefreshDurationMs: store.state.lastRefreshDurationMs,
+      coverage,
+      demo,
+      includeOverlayDefault: !!config.analytics?.includeOverlaySources,
+      defaultRange: config.ui?.defaultRange || 'all',
+      defaultFrom: config.ui?.defaultFrom || null,
+      // Theme defaults from config; the browser's own choice wins once set.
+      skin: config.ui?.skin || 'aurora',
+      mode: config.ui?.mode || config.ui?.theme || 'dark',
+      builtAt: cube.builtAt || store.state.lastRefresh || null,
+      dataHome: p.root,
+      sources: providersState,
+    },
+    cube,
+    sessions,
+    activity,
+    pricing,
+    // User-declared quota/budget caps; analytics/capacity.js evaluates them
+    // against the same cube every other surface reads.
+    limits: Array.isArray(config.limits) ? config.limits : [],
+    health,
+  };
+}
+
+/** Records for the Data Explorer, filtered and paginated server-side. */
+export function queryRecords(q = {}) {
+  const store = new Store();
+  const limit = Math.min(Number(q.limit) || 100, 5000);
+  const offset = Number(q.offset) || 0;
+  const search = (q.search || '').toLowerCase();
+  const sortKey = q.sort || 'ts';
+  const desc = q.dir !== 'asc';
+  const wanted = {
+    from: q.from || null, to: q.to || null,
+    p: split(q.provider), m: split(q.model), c: split(q.client),
+    i: split(q.interface), pj: split(q.project), so: split(q.source),
+    ms: split(q.measurement),
+  };
+  const months = monthsBetween(wanted.from, wanted.to);
+  const matched = [];
+  let scanned = 0;
+  let total = 0;
+
+  // Keep only what a page could need, plus enough to sort: a bounded top-K
+  // buffer means a 100-record page never materialises a million objects.
+  const cap = offset + limit;
+  store.scanRecords((o) => {
+    scanned++;
+    if (wanted.from && o.d < wanted.from) return;
+    if (wanted.to && o.d > wanted.to) return;
+    for (const k of ['p', 'm', 'c', 'i', 'pj', 'so', 'ms']) {
+      if (wanted[k] && !wanted[k].includes(o[k])) return;
+    }
+    if (search) {
+      const hay = `${o.m} ${o.p} ${o.c} ${o.pj} ${o.s} ${o.i} ${o.rq || ''} ${o.br || ''}`.toLowerCase();
+      if (!hay.includes(search)) return;
+    }
+    total++;
+    matched.push(o);
+    if (matched.length > cap * 4 + 4000) {
+      matched.sort(cmp(sortKey, desc));
+      matched.length = cap;
+    }
+  }, { months });
+
+  matched.sort(cmp(sortKey, desc));
+  return {
+    total,
+    scanned,
+    offset,
+    limit,
+    rows: matched.slice(offset, offset + limit),
+  };
+}
+
+function cmp(key, desc) {
+  return (a, b) => {
+    const x = a[key];
+    const y = b[key];
+    if (x === y) return 0;
+    if (x === undefined || x === null) return 1;
+    if (y === undefined || y === null) return -1;
+    const r = x < y ? -1 : 1;
+    return desc ? -r : r;
+  };
+}
+
+function split(v) {
+  if (!v) return null;
+  const a = Array.isArray(v) ? v : String(v).split(',');
+  const out = a.map((s) => String(s).trim()).filter(Boolean);
+  return out.length ? out : null;
+}
+
+function monthsBetween(from, to) {
+  if (!from || !to) return null;
+  const out = [];
+  let y = Number(from.slice(0, 4));
+  let m = Number(from.slice(5, 7));
+  const ey = Number(to.slice(0, 4));
+  const em = Number(to.slice(5, 7));
+  let guard = 0;
+  while ((y < ey || (y === ey && m <= em)) && guard++ < 600) {
+    out.push(`${y}-${String(m).padStart(2, '0')}`);
+    m++;
+    if (m > 12) { m = 1; y++; }
+  }
+  return out;
+}
+
+function localToday(tz) {
+  try {
+    const f = new Intl.DateTimeFormat('en-CA', { timeZone: tz || undefined, year: 'numeric', month: '2-digit', day: '2-digit' });
+    const p = {};
+    for (const x of f.formatToParts(new Date())) p[x.type] = x.value;
+    return `${p.year}-${p.month}-${p.day}`;
+  } catch {
+    return new Date().toISOString().slice(0, 10);
+  }
+}
+
+export function rootDir() {
+  // src/core -> project root
+  return path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..', '..');
+}

package/src/core/config.js

@@ -0,0 +1,202 @@
+/**
+ * Portable configuration.
+ *
+ *   ~/.tokenflow/
+ *     config.yaml        providers, sources, preferences  (config.json also read)
+ *     pricing.json       user-defined pricing overrides
+ *     mappings/          saved generic-import field mappings
+ *     data/              normalized records, cube, sessions, ingest state
+ *     cache/             adapter scratch
+ *
+ * Override the root with TOKENFLOW_HOME. Everything is local; nothing here is
+ * ever transmitted.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { parseYaml, stringifyYaml } from './yaml.js';
+
+export const CONFIG_VERSION = 1;
+
+/**
+ * Where everything lives.
+ *
+ * `TOKENFLOW_HOME` wins, then `~/.tokenflow`. The two legacy names are still
+ * honoured so an install that predates the rename keeps its ingested data
+ * instead of silently starting from an empty store — which, with an incremental
+ * engine keyed on per-file offsets, would look like "all my history vanished".
+ * Legacy is only used when the current location does not exist yet.
+ */
+export function homeDir() {
+  if (process.env.TOKENFLOW_HOME) return process.env.TOKENFLOW_HOME;
+  if (process.env.AI_USAGE_HOME) return process.env.AI_USAGE_HOME;
+  const current = path.join(os.homedir(), '.tokenflow');
+  if (fs.existsSync(current)) return current;
+  const legacy = path.join(os.homedir(), '.ai-usage-dashboard');
+  if (fs.existsSync(legacy)) return legacy;
+  return current;
+}
+
+export const paths = () => {
+  const root = homeDir();
+  return {
+    root,
+    configYaml: path.join(root, 'config.yaml'),
+    configJson: path.join(root, 'config.json'),
+    pricing: path.join(root, 'pricing.json'),
+    mappings: path.join(root, 'mappings'),
+    data: path.join(root, 'data'),
+    records: path.join(root, 'data', 'records'),
+    cube: path.join(root, 'data', 'cube.json'),
+    sessions: path.join(root, 'data', 'sessions.json'),
+    activity: path.join(root, 'data', 'activity.json'),
+    state: path.join(root, 'data', 'state.json'),
+    // Written by `tokenflow watch`, read by every live surface (menu bar,
+    // CLI --live, dashboard header). Atomic tmp+rename writes only.
+    status: path.join(root, 'data', 'status.json'),
+    watchPid: path.join(root, 'data', 'watch.pid'),
+    cache: path.join(root, 'cache'),
+    prefs: path.join(root, 'preferences.json'),
+  };
+};
+
+export const DEFAULT_CONFIG = {
+  version: CONFIG_VERSION,
+  timezone: null, // null = this machine's zone
+  identity: { user: null, machine: null, team: null },
+  providers: [], // populated by `tokenflow setup` / `provider add`
+  sources: {}, // per-provider source options; `{type: auto}` by default
+  store: {
+    keepRaw: true, // keep request-level records for the Data Explorer + full export
+    rawRetentionDays: null, // null = forever
+  },
+  analytics: {
+    includeOverlaySources: false, // proxy/gateway views excluded from totals by default
+    minSessionGapMinutes: 30, // used only for sources without a session id
+  },
+  modelMappings: [], // user rules, prepended to the built-ins
+  interfaceOverrides: {}, // { "<client>": "CLI" }
+  // User-declared quota / budget caps, evaluated by analytics/capacity.js.
+  // TokenFlow never invents vendor quota data; a limit exists only if you
+  // declared it here (or via the dashboard's Live tab).
+  limits: [],
+  // Monthly spend budget with forecast alerts. OFF until `monthly` is set.
+  //   budget: { monthly: 200, warnAtPct: 80 }
+  // Alerts fire once per state per month (approaching / over-projected /
+  // over-actual), persisted in data/budget-state.json to avoid spam.
+  budget: {
+    monthly: null,
+    warnAtPct: 80,
+    notify: false, // opt-in OS/delivery notification; state tracking always on
+  },
+  // Digest delivery channels. Each is OFF until configured. Credentials live
+  // only in this local file and are never logged or transmitted elsewhere.
+  delivery: {
+    telegram: { botToken: null, chatId: null },
+    email: { smtpUrl: null, to: null },
+    webhook: { url: null },
+  },
+  // Optional multi-machine aggregation. OFF by default: nothing leaves this
+  // machine until you point sync.dir at a folder shared between your machines
+  // (iCloud/Dropbox/Syncthing) and set enabled: true. Only daily totals are
+  // exchanged — never prompts, code, or credentials. See src/core/sync.js.
+  sync: {
+    enabled: false,
+    dir: null,            // e.g. ~/Sync/TokenFlow
+    machineName: null,    // friendly label; defaults to hostname
+  },
+  // Prompt-level analytics. STRICTLY opt-in and OFF by default. Even when
+  // enabled, only one-way hashes + categories are stored — raw prompt text is
+  // captured only if storeRaw is separately set to true.
+  promptAnalytics: {
+    enabled: false,
+    storeRaw: false,
+  },
+  // The background refresher (`tokenflow watch`). It runs only while you
+  // explicitly started it; nothing is installed or auto-started.
+  watch: {
+    intervalSeconds: 120, // between incremental refresh passes
+    notifications: false, // opt-in OS notifications on threshold crossings
+    staleAfterSeconds: 600, // when live surfaces should call the data stale
+  },
+  ui: {
+    // Visual theme: skin restyles the chrome, mode flips light/dark. The series
+    // colours belong to the mode and are validated per surface, so a skin never
+    // changes what a colour means.
+    skin: 'aurora', // aurora | terminal | editorial
+    mode: 'dark', // dark | light
+    theme: 'dark', // legacy single-axis alias, kept for older configs
+    // Port the local dashboard binds to (and the port a saved snapshot probes
+    // when it looks for a live dashboard to hand over to).
+    port: 7799,
+    // Which quick range the dashboard opens on: all | 7d | 30d | 90d | mtd
+    defaultRange: 'all',
+    // Optional hard floor for the default view (YYYY-MM-DD), for when the store
+    // holds older records you don't normally want in scope.
+    defaultFrom: null,
+  },
+};
+
+export function loadConfig() {
+  const p = paths();
+  let cfg = structuredClone(DEFAULT_CONFIG);
+  try {
+    if (fs.existsSync(p.configYaml)) {
+      cfg = merge(cfg, parseYaml(fs.readFileSync(p.configYaml, 'utf8')) || {});
+    } else if (fs.existsSync(p.configJson)) {
+      cfg = merge(cfg, JSON.parse(fs.readFileSync(p.configJson, 'utf8')));
+    }
+  } catch (err) {
+    const e = /** @type {Error & {hint?:string}} */ (new Error(`Could not read config at ${p.configYaml}: ${err.message}`));
+    e.hint = 'Fix the syntax, or delete the file and re-run `tokenflow setup`.';
+    throw e;
+  }
+  return cfg;
+}
+
+export function saveConfig(cfg) {
+  const p = paths();
+  ensureDirs();
+  const header = [
+    '# tokenflow configuration',
+    '# Local-first: nothing in this directory is uploaded anywhere.',
+    '# Docs: docs/providers.md   Regenerate: tokenflow setup',
+    '',
+  ].join('\n');
+  fs.writeFileSync(p.configYaml, header + stringifyYaml(cfg) + '\n');
+  return p.configYaml;
+}
+
+export function ensureDirs() {
+  const p = paths();
+  for (const d of [p.root, p.data, p.records, p.cache, p.mappings]) {
+    fs.mkdirSync(d, { recursive: true });
+  }
+  return p;
+}
+
+export function loadPrefs() {
+  const p = paths();
+  try {
+    return JSON.parse(fs.readFileSync(p.prefs, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function savePrefs(prefs) {
+  const p = paths();
+  ensureDirs();
+  fs.writeFileSync(p.prefs, JSON.stringify(prefs, null, 2));
+}
+
+/** Deep merge where arrays replace and plain objects merge. */
+export function merge(base, over) {
+  if (over === null || over === undefined) return base;
+  if (Array.isArray(over) || typeof over !== 'object') return over;
+  const out = Array.isArray(base) ? [...base] : { ...(base || {}) };
+  for (const [k, v] of Object.entries(over)) {
+    out[k] = v !== null && typeof v === 'object' && !Array.isArray(v) ? merge(out[k], v) : v;
+  }
+  return out;
+}

package/src/core/delivery.js

@@ -0,0 +1,109 @@
+/**
+ * Digest delivery adapters — strictly opt-in, configured in config.yaml.
+ *
+ *   delivery:
+ *     telegram:
+ *       botToken: <from @BotFather>      # stored locally, never logged
+ *       chatId: "<your chat id>"
+ *     email:
+ *       smtpUrl: smtp://user:pass@smtp.gmail.com:465
+ *       to: you@example.com
+ *     webhook:
+ *       url: https://example.com/hook
+ *
+ * Every channel is OFF until its block exists. Credentials live only in
+ * $TOKENFLOW_HOME/config.yaml (0600 by umask); they are never logged, never
+ * echoed in errors, and never included in packaged files.
+ *
+ * Zero dependencies: Telegram + webhook use node:https; SMTP is delegated to
+ * the local `sendmail`-compatible binary if present (most macOS/Linux boxes
+ * have one via postfix) — if not, email reports "transport unavailable"
+ * instead of failing silently.
+ */
+import https from 'node:https';
+import { execFile } from 'node:child_process';
+
+/**
+ * Deliver markdown text via every configured channel.
+ * Returns per-channel results; never throws for a channel that isn't configured.
+ * @param {object} cfg parsed TokenFlow config
+ * @param {string} text markdown digest
+ * @param {{subject?: string}} opt
+ */
+export async function deliverAll(cfg, text, opt = {}) {
+  const d = cfg?.delivery || {};
+  const results = [];
+  const subject = opt.subject || 'TokenFlow digest';
+
+  if (d.telegram?.botToken && d.telegram?.chatId) {
+    results.push({ channel: 'telegram', ...(await sendTelegram(d.telegram.botToken, d.telegram.chatId, text)) });
+  } else {
+    results.push({ channel: 'telegram', skipped: 'not configured' });
+  }
+
+  if (d.email?.smtpUrl && d.email?.to) {
+    results.push({ channel: 'email', ...(await sendEmail(d.email.smtpUrl, d.email.to, subject, text)) });
+  } else {
+    results.push({ channel: 'email', skipped: 'not configured' });
+  }
+
+  if (d.webhook?.url) {
+    results.push({ channel: 'webhook', ...(await sendWebhook(d.webhook.url, { subject, text })) });
+  } else {
+    results.push({ channel: 'webhook', skipped: 'not configured' });
+  }
+  return results;
+}
+
+async function sendTelegram(botToken, chatId, text) {
+  try {
+    // Markdown digest → Telegram MarkdownV2 needs escaping; send as plain
+    // text with disabled preview instead — honest and robust over pretty.
+    const body = JSON.stringify({ chat_id: String(chatId), text, disable_web_page_preview: true });
+    const status = await postJSON(`api.telegram.org`, `/bot${botToken}/sendMessage`, body);
+    return status === 200 ? { ok: true } : { ok: false, error: `HTTP ${status}` };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function postJSON(host, reqPath, body) {
+  return new Promise((resolve) => {
+    const req = https.request(
+      { host, path: reqPath, method: 'POST', timeout: 15000,
+        headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) } },
+      (res) => { res.resume(); res.on('end', () => resolve(res.statusCode)); });
+    req.on('timeout', () => { req.destroy(); resolve(0); });
+    req.on('error', () => resolve(0));
+    req.write(body);
+    req.end();
+  });
+}
+
+async function sendWebhook(url, payload) {
+  try {
+    const u = new URL(url);
+    const status = await postJSON(u.host, u.pathname + u.search, JSON.stringify(payload));
+    return status >= 200 && status < 300 ? { ok: true } : { ok: false, error: `HTTP ${status}` };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+/**
+ * Email via local sendmail-compatible transport (postfix on macOS).
+ * The smtpUrl is used only to decide transport viability today; credentials
+ * inside it are NOT parsed or logged. A future version can add direct SMTP
+ * AUTH without changing the config shape.
+ */
+async function sendEmail(smtpUrl, to, subject, text) {
+  const u = new URL(smtpUrl);
+  const host = u.hostname || 'localhost';
+  return new Promise((resolve) => {
+    // sendmail -t reads recipients from headers; universally available via postfix
+    execFile('/usr/sbin/sendmail', ['-t'], { timeout: 20000 }, (err) => {
+      if (err) { resolve({ ok: false, error: `local sendmail unavailable (${err.code || err.message})` }); return; }
+      resolve({ ok: true });
+    }).stdin?.end?.(`To: ${to}\nSubject: ${subject}\nContent-Type: text/plain; charset=utf-8\nX-TokenFlow-Transport: ${host}\n\n${text}\n`);
+  });
+}