@hasna/uptime 0.1.3 → 0.1.4

package/dist/index.js

@@ -825,9 +825,24 @@ import { dirname, join as join2 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 import { Database } from "bun:sqlite";
 var SECRET_URL_PARAM_PATTERN = /(token|secret|password|passwd|api[_-]?key|access[_-]?token|auth|credential|session)/i;
-var REQUIRED_TABLES = ["schema_migrations", "monitors", "check_results", "incidents", "check_leases", "monitor_provenance", "import_batches", "probe_identities", "probe_check_jobs", "probe_submissions"];
+var REQUIRED_TABLES = [
+  "schema_migrations",
+  "monitors",
+  "check_results",
+  "incidents",
+  "check_leases",
+  "monitor_provenance",
+  "import_batches",
+  "probe_identities",
+  "probe_check_jobs",
+  "probe_submissions",
+  "report_schedules",
+  "report_runs",
+  "audit_events"
+];
 var PROBE_TABLES = new Set(["probe_identities", "probe_check_jobs", "probe_submissions"]);
-var CURRENT_SCHEMA_VERSION = "2";
+var REPORT_AUDIT_TABLES = new Set(["report_schedules", "report_runs", "audit_events"]);
+var CURRENT_SCHEMA_VERSION = "3";
 
 class StaleCheckResultError extends Error {
   constructor(message) {
@@ -987,6 +1002,44 @@ class UptimeStore {
         acquired_at TEXT NOT NULL
       )
     `);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS report_schedules (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        enabled INTEGER NOT NULL DEFAULT 1,
+        interval_seconds INTEGER NOT NULL,
+        next_run_at TEXT NOT NULL,
+        last_run_at TEXT,
+        subject TEXT,
+        channels_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS report_runs (
+        id TEXT PRIMARY KEY,
+        schedule_id TEXT REFERENCES report_schedules(id) ON DELETE SET NULL,
+        status TEXT NOT NULL CHECK (status IN ('success', 'failed')),
+        started_at TEXT NOT NULL,
+        finished_at TEXT NOT NULL,
+        deliveries_json TEXT NOT NULL,
+        error TEXT,
+        report_json TEXT
+      )
+    `);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS audit_events (
+        id TEXT PRIMARY KEY,
+        action TEXT NOT NULL,
+        resource_type TEXT,
+        resource_id TEXT,
+        message TEXT,
+        metadata_json TEXT NOT NULL DEFAULT '{}',
+        actor TEXT,
+        created_at TEXT NOT NULL
+      )
+    `);
     this.db.run(`
       CREATE TABLE IF NOT EXISTS schema_migrations (
         key TEXT PRIMARY KEY,
@@ -1004,6 +1057,10 @@ class UptimeStore {
     this.db.run("CREATE INDEX IF NOT EXISTS idx_probe_submissions_probe_time ON probe_submissions(probe_id, submitted_at DESC)");
     this.db.run("CREATE INDEX IF NOT EXISTS idx_probe_submissions_monitor_time ON probe_submissions(monitor_id, checked_at DESC)");
     this.db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_probe_submissions_job ON probe_submissions(job_id) WHERE job_id IS NOT NULL AND job_id != ''");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_report_schedules_due ON report_schedules(enabled, next_run_at)");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_report_runs_schedule_time ON report_runs(schedule_id, started_at DESC)");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_audit_events_resource_time ON audit_events(resource_type, resource_id, created_at DESC)");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_audit_events_time ON audit_events(created_at DESC)");
   }
   backup(destinationPath) {
     if (this.dbPath === ":memory:" && !destinationPath) {
@@ -1300,6 +1357,136 @@ class UptimeStore {
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(receipt.id, receipt.probeId, receipt.jobId, receipt.monitorId, receipt.checkResultId, receipt.nonce, receipt.checkedAt, receipt.submittedAt);
     return receipt;
   }
+  createReportSchedule(input) {
+    const normalized = normalizeReportScheduleInput(input);
+    const now = new Date().toISOString();
+    const schedule = {
+      id: newId("rps"),
+      name: normalized.name,
+      enabled: normalized.enabled,
+      intervalSeconds: normalized.intervalSeconds,
+      nextRunAt: normalized.nextRunAt,
+      lastRunAt: null,
+      subject: normalized.subject,
+      channels: normalized.channels,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.db.query(`INSERT INTO report_schedules (
+          id, name, enabled, interval_seconds, next_run_at, last_run_at,
+          subject, channels_json, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(schedule.id, schedule.name, schedule.enabled ? 1 : 0, schedule.intervalSeconds, schedule.nextRunAt, schedule.lastRunAt, schedule.subject, JSON.stringify(schedule.channels), schedule.createdAt, schedule.updatedAt);
+    return schedule;
+  }
+  listReportSchedules(options = {}) {
+    const rows = options.includeDisabled ? this.db.query("SELECT * FROM report_schedules ORDER BY name ASC").all() : this.db.query("SELECT * FROM report_schedules WHERE enabled = 1 ORDER BY name ASC").all();
+    return rows.map(reportScheduleFromRow);
+  }
+  listDueReportSchedules(nowIso = new Date().toISOString()) {
+    assertIsoTimestamp(nowIso, "Report schedule due timestamp");
+    const rows = this.db.query("SELECT * FROM report_schedules WHERE enabled = 1 AND next_run_at <= ? ORDER BY next_run_at ASC, name ASC").all(nowIso);
+    return rows.map(reportScheduleFromRow);
+  }
+  getReportSchedule(idOrName) {
+    const row = this.db.query("SELECT * FROM report_schedules WHERE id = ? OR name = ?").get(idOrName, idOrName);
+    return row ? reportScheduleFromRow(row) : null;
+  }
+  updateReportSchedule(idOrName, input) {
+    const current = this.getReportSchedule(idOrName);
+    if (!current)
+      throw new Error(`Report schedule not found: ${idOrName}`);
+    const normalized = normalizeReportScheduleInput({
+      name: input.name ?? current.name,
+      intervalSeconds: input.intervalSeconds ?? current.intervalSeconds,
+      nextRunAt: input.nextRunAt ?? current.nextRunAt,
+      enabled: input.enabled ?? current.enabled,
+      subject: input.subject === undefined ? current.subject : input.subject,
+      channels: input.channels ?? current.channels
+    });
+    const updatedAt = new Date().toISOString();
+    this.db.query(`UPDATE report_schedules SET
+          name = ?, enabled = ?, interval_seconds = ?, next_run_at = ?,
+          subject = ?, channels_json = ?, updated_at = ?
+        WHERE id = ?`).run(normalized.name, normalized.enabled ? 1 : 0, normalized.intervalSeconds, normalized.nextRunAt, normalized.subject, JSON.stringify(normalized.channels), updatedAt, current.id);
+    return this.getReportSchedule(current.id);
+  }
+  deleteReportSchedule(idOrName) {
+    const current = this.getReportSchedule(idOrName);
+    if (!current)
+      return false;
+    this.db.query("DELETE FROM report_schedules WHERE id = ?").run(current.id);
+    return true;
+  }
+  recordReportRun(input) {
+    const startedAt = input.startedAt ?? new Date().toISOString();
+    const finishedAt = input.finishedAt ?? new Date().toISOString();
+    assertIsoTimestamp(startedAt, "Report run startedAt");
+    assertIsoTimestamp(finishedAt, "Report run finishedAt");
+    if (input.status !== "success" && input.status !== "failed") {
+      throw new Error("Report run status must be success or failed");
+    }
+    if (input.scheduleId && !this.getReportSchedule(input.scheduleId)) {
+      throw new Error(`Report schedule not found: ${input.scheduleId}`);
+    }
+    const run = {
+      id: newId("rpr"),
+      scheduleId: input.scheduleId ?? null,
+      status: input.status,
+      startedAt,
+      finishedAt,
+      deliveries: normalizeReportDeliveries(input.deliveries ?? []),
+      error: normalizeNullableRedactedText(input.error, "Report run error", 1000),
+      reportJson: input.reportJson ?? null
+    };
+    this.db.query(`INSERT INTO report_runs (
+          id, schedule_id, status, started_at, finished_at, deliveries_json,
+          error, report_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(run.id, run.scheduleId, run.status, run.startedAt, run.finishedAt, JSON.stringify(run.deliveries), run.error, run.reportJson ? JSON.stringify(run.reportJson) : null);
+    if (run.scheduleId) {
+      this.advanceReportSchedule(run.scheduleId, run.finishedAt);
+    }
+    return run;
+  }
+  listReportRuns(options = {}) {
+    const limit = clampLimit(options.limit ?? 50);
+    const rows = options.scheduleId ? this.db.query("SELECT * FROM report_runs WHERE schedule_id = ? ORDER BY started_at DESC, id DESC LIMIT ?").all(options.scheduleId, limit) : this.db.query("SELECT * FROM report_runs ORDER BY started_at DESC, id DESC LIMIT ?").all(limit);
+    return rows.map(reportRunFromRow);
+  }
+  recordAuditEvent(input) {
+    const action = normalizeAuditText(input.action, "Audit action", 160);
+    const createdAt = input.createdAt ?? new Date().toISOString();
+    assertIsoTimestamp(createdAt, "Audit event createdAt");
+    const event = {
+      id: newId("aud"),
+      action,
+      resourceType: normalizeNullableAuditText(input.resourceType, "Audit resourceType", 80),
+      resourceId: normalizeNullableAuditText(input.resourceId, "Audit resourceId", 160),
+      message: normalizeNullableAuditText(input.message, "Audit message", 500),
+      metadata: normalizeAuditMetadata(input.metadata ?? {}),
+      actor: normalizeNullableAuditText(input.actor, "Audit actor", 160),
+      createdAt
+    };
+    this.db.query(`INSERT INTO audit_events (
+          id, action, resource_type, resource_id, message, metadata_json, actor, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(event.id, event.action, event.resourceType, event.resourceId, event.message, JSON.stringify(event.metadata), event.actor, event.createdAt);
+    return event;
+  }
+  listAuditEvents(options = {}) {
+    const clauses = [];
+    const args = [];
+    if (options.resourceType) {
+      clauses.push("resource_type = ?");
+      args.push(options.resourceType);
+    }
+    if (options.resourceId) {
+      clauses.push("resource_id = ?");
+      args.push(options.resourceId);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    args.push(clampLimit(options.limit ?? 50));
+    const rows = this.db.query(`SELECT * FROM audit_events ${where} ORDER BY created_at DESC, id DESC LIMIT ?`).all(...args);
+    return rows.map(auditEventFromRow);
+  }
   acquireCheckLease(monitorId, owner, ttlMs) {
     const now = new Date;
     const nowIso = now.toISOString();
@@ -1482,6 +1669,18 @@ class UptimeStore {
   closeOpenIncident(monitorId, closedAt) {
     this.db.query("UPDATE incidents SET status = 'closed', closed_at = ? WHERE monitor_id = ? AND status = 'open'").run(closedAt, monitorId);
   }
+  advanceReportSchedule(scheduleId, finishedAt) {
+    const schedule = this.getReportSchedule(scheduleId);
+    if (!schedule)
+      throw new Error(`Report schedule not found: ${scheduleId}`);
+    const finishedMs = Date.parse(finishedAt);
+    let nextMs = Math.max(Date.parse(schedule.nextRunAt), finishedMs);
+    do {
+      nextMs += schedule.intervalSeconds * 1000;
+    } while (nextMs <= finishedMs);
+    const nextRunAt = new Date(nextMs).toISOString();
+    this.db.query("UPDATE report_schedules SET last_run_at = ?, next_run_at = ?, updated_at = ? WHERE id = ?").run(finishedAt, nextRunAt, finishedAt, schedule.id);
+  }
   ensureColumn(table, name, definition) {
     const columns = this.db.query(`PRAGMA table_info(${table})`).all();
     if (!columns.some((column) => column.name === name)) {
@@ -1560,9 +1759,10 @@ function verifyBackupFile(backupPath) {
     const missingTables = REQUIRED_TABLES.filter((table) => !tableExists(db, table));
     const schemaVersion = missingTables.includes("schema_migrations") ? null : db.query("SELECT value FROM schema_migrations WHERE key = 'schema_version'").get()?.value ?? null;
     const currentOk = missingTables.length === 0 && schemaVersion === CURRENT_SCHEMA_VERSION;
-    const restorableV1 = schemaVersion === "1" && missingTables.every((table) => PROBE_TABLES.has(table));
+    const restorableV1 = schemaVersion === "1" && missingTables.every((table) => PROBE_TABLES.has(table) || REPORT_AUDIT_TABLES.has(table));
+    const restorableV2 = schemaVersion === "2" && missingTables.every((table) => REPORT_AUDIT_TABLES.has(table));
     return {
-      ok: integrity === "ok" && (currentOk || restorableV1),
+      ok: integrity === "ok" && (currentOk || restorableV1 || restorableV2),
       backupPath,
       integrity,
       schemaVersion,
@@ -1726,6 +1926,175 @@ function normalizeScheduleSlot(value) {
   rejectControlCharacters2(slot, "Probe job scheduleSlot");
   return slot;
 }
+function normalizeReportScheduleInput(input) {
+  const name = input.name?.trim();
+  if (!name)
+    throw new Error("Report schedule name is required");
+  rejectControlCharacters2(name, "Report schedule name");
+  const intervalSeconds = boundedInteger2(input.intervalSeconds, "intervalSeconds", MIN_INTERVAL_SECONDS, MAX_INTERVAL_SECONDS);
+  const nextRunAt = input.nextRunAt ?? new Date().toISOString();
+  assertIsoTimestamp(nextRunAt, "Report schedule nextRunAt");
+  const enabled = normalizeEnabled(input.enabled);
+  const subject = normalizeNullableBoundedText(input.subject, "Report schedule subject", 200);
+  const channels = normalizeReportChannels(input.channels);
+  return { name, intervalSeconds, nextRunAt, enabled, subject, channels };
+}
+function normalizeReportChannels(channels) {
+  if (!channels || typeof channels !== "object")
+    throw new Error("Report schedule channels are required");
+  const normalized = {};
+  if (channels.email !== undefined)
+    normalized.email = normalizeChannelTarget(channels.email, "email", ["apiUrl", "from", "to", "subject", "providerId"]);
+  if (channels.sms !== undefined)
+    normalized.sms = normalizeChannelTarget(channels.sms, "sms", ["apiUrl", "from", "to"]);
+  if (channels.logs !== undefined)
+    normalized.logs = normalizeChannelTarget(channels.logs, "logs", ["apiUrl", "projectId", "environment", "service"]);
+  if (!normalized.email && !normalized.sms && !normalized.logs) {
+    throw new Error("Report schedule requires at least one channel");
+  }
+  return normalized;
+}
+function normalizeChannelTarget(value, channel, allowedKeys) {
+  if (value === false || value == null)
+    return false;
+  if (value === true)
+    return true;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Report schedule ${channel} channel must be true or an object`);
+  }
+  const record = value;
+  const normalized = {};
+  for (const [key, rawValue] of Object.entries(record)) {
+    if (!allowedKeys.includes(key)) {
+      if (/key|token|secret|password|credential|auth/i.test(key)) {
+        throw new Error("Report schedules must not persist API keys or tokens; use environment variables or cloud channel refs");
+      }
+      throw new Error(`Unsupported report schedule ${channel} channel field: ${key}`);
+    }
+    if (rawValue === undefined || rawValue === null || rawValue === "")
+      continue;
+    if (key === "apiUrl" && Array.isArray(rawValue)) {
+      throw new Error(`Report schedule ${channel}.${key} must be a string`);
+    }
+    if (Array.isArray(rawValue)) {
+      const items = rawValue.map((item) => normalizeBoundedText(String(item), `Report schedule ${channel}.${key}`, 300));
+      if (items.length > 0)
+        normalized[key] = items;
+    } else if (typeof rawValue === "string" || typeof rawValue === "number") {
+      normalized[key] = key === "apiUrl" ? normalizeHttpIntegrationUrl(String(rawValue)) : normalizeBoundedText(String(rawValue), `Report schedule ${channel}.${key}`, 500);
+    } else {
+      throw new Error(`Report schedule ${channel}.${key} must be a string or string array`);
+    }
+  }
+  return Object.keys(normalized).length > 0 ? normalized : true;
+}
+function normalizeHttpIntegrationUrl(value) {
+  const parsed = new URL(value.trim());
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Report schedule integration API URL must use http or https");
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("Report schedule integration API URL must not include credentials");
+  }
+  for (const key of parsed.searchParams.keys()) {
+    if (SECRET_URL_PARAM_PATTERN.test(key)) {
+      throw new Error("Report schedule integration API URL must not include secret query parameters");
+    }
+  }
+  parsed.hash = "";
+  return parsed.toString();
+}
+function normalizeReportDeliveries(deliveries) {
+  return deliveries.map((delivery) => {
+    if (delivery.channel !== "email" && delivery.channel !== "sms" && delivery.channel !== "logs") {
+      throw new Error("Report delivery channel must be email, sms, or logs");
+    }
+    return {
+      channel: delivery.channel,
+      ok: Boolean(delivery.ok),
+      status: delivery.status,
+      id: delivery.id === undefined ? undefined : normalizeRedactedText(String(delivery.id), "Report delivery id", 300),
+      error: delivery.error === undefined ? undefined : normalizeRedactedText(String(delivery.error), "Report delivery error", 1000)
+    };
+  });
+}
+function normalizeAuditText(value, label, maxLength) {
+  return normalizeBoundedText(value ?? "", label, maxLength);
+}
+function normalizeNullableAuditText(value, label, maxLength) {
+  return normalizeNullableBoundedText(value, label, maxLength);
+}
+function normalizeNullableBoundedText(value, label, maxLength) {
+  if (value == null)
+    return null;
+  const normalized = normalizeRedactedText(value, label, maxLength);
+  return normalized || null;
+}
+function normalizeBoundedText(value, label, maxLength) {
+  const normalized = value.trim();
+  rejectControlCharacters2(normalized, label);
+  if (normalized.length > maxLength)
+    throw new Error(`${label} is too long`);
+  return normalized;
+}
+function normalizeNullableRedactedText(value, label, maxLength) {
+  if (value == null)
+    return null;
+  const normalized = normalizeRedactedText(value, label, maxLength);
+  return normalized || null;
+}
+function normalizeRedactedText(value, label, maxLength) {
+  return normalizeBoundedText(redactSecretString(value), label, maxLength);
+}
+function normalizeAuditMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Audit metadata must be an object");
+  }
+  return redactAuditSecrets(JSON.parse(JSON.stringify(value)));
+}
+function redactAuditSecrets(value) {
+  if (Array.isArray(value))
+    return value.map(redactAuditSecrets);
+  if (typeof value === "string")
+    return redactSecretString(value);
+  if (!value || typeof value !== "object")
+    return value;
+  const output = {};
+  for (const [key, nested] of Object.entries(value)) {
+    output[key] = /key|token|secret|password|credential|auth/i.test(key) ? "[REDACTED]" : redactAuditSecrets(nested);
+  }
+  return output;
+}
+function redactSecretString(value) {
+  let output = value.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
+  output = output.replace(/https?:\/\/[^\s"'<>]+/gi, (match) => redactUrlString(match));
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(output))
+    return output;
+  return redactUrlString(output);
+}
+function redactUrlString(value) {
+  let trailing = "";
+  let candidate = value;
+  while (/[),.;\]]$/.test(candidate)) {
+    trailing = `${candidate.slice(-1)}${trailing}`;
+    candidate = candidate.slice(0, -1);
+  }
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.username)
+      parsed.username = "[REDACTED]";
+    if (parsed.password)
+      parsed.password = "[REDACTED]";
+    for (const key of [...parsed.searchParams.keys()]) {
+      if (SECRET_URL_PARAM_PATTERN.test(key))
+        parsed.searchParams.set(key, "[REDACTED]");
+    }
+    parsed.hash = "";
+    return `${parsed.toString()}${trailing}`;
+  } catch {
+    return value;
+  }
+}
 function assertIsoTimestamp(value, label) {
   if (!Number.isFinite(Date.parse(value))) {
     throw new Error(`${label} must be an ISO timestamp`);
@@ -1825,12 +2194,66 @@ function probeCheckJobFromRow(row) {
     updatedAt: row.updated_at
   };
 }
+function reportScheduleFromRow(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    enabled: Boolean(row.enabled),
+    intervalSeconds: row.interval_seconds,
+    nextRunAt: row.next_run_at,
+    lastRunAt: row.last_run_at,
+    subject: row.subject,
+    channels: parseReportChannels(row.channels_json),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function reportRunFromRow(row) {
+  return {
+    id: row.id,
+    scheduleId: row.schedule_id,
+    status: row.status,
+    startedAt: row.started_at,
+    finishedAt: row.finished_at,
+    deliveries: parseReportDeliveries(row.deliveries_json),
+    error: row.error,
+    reportJson: parseRecord(row.report_json)
+  };
+}
+function auditEventFromRow(row) {
+  return {
+    id: row.id,
+    action: row.action,
+    resourceType: row.resource_type,
+    resourceId: row.resource_id,
+    message: row.message,
+    metadata: parseRecord(row.metadata_json) ?? {},
+    actor: row.actor,
+    createdAt: row.created_at
+  };
+}
 function parseEvidence(value) {
   if (!value)
     return null;
   const parsed = parseJson(value);
   return parsed && typeof parsed === "object" ? parsed : null;
 }
+function parseReportChannels(value) {
+  const parsed = parseJson(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    return {};
+  return parsed;
+}
+function parseReportDeliveries(value) {
+  const parsed = parseJson(value);
+  return Array.isArray(parsed) ? parsed : [];
+}
+function parseRecord(value) {
+  if (!value)
+    return null;
+  const parsed = parseJson(value);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+}
 function parseJson(value) {
   try {
     return JSON.parse(value);
@@ -2153,6 +2576,7 @@ class UptimeService {
   checkRunner;
   leaseOwner = `svc_${randomUUID3().replace(/-/g, "").slice(0, 18)}`;
   inFlightChecks = new Set;
+  inFlightReportSchedules = new Set;
   constructor(options = {}) {
     this.store = options.store ?? new UptimeStore({ mode: "local", ...options });
     this.checkRunner = options.checkRunner ?? runMonitorCheck;
@@ -2246,6 +2670,115 @@ class UptimeService {
     }
     return sendUptimeReport(this.summary(), options);
   }
+  createReportSchedule(input) {
+    const store = this.reportStore();
+    const schedule = store.createReportSchedule(input);
+    this.audit("report_schedule.create", "report_schedule", schedule.id, `Created report schedule ${schedule.name}`, {
+      name: schedule.name,
+      enabled: schedule.enabled,
+      intervalSeconds: schedule.intervalSeconds,
+      channels: enabledReportChannels(schedule)
+    });
+    return schedule;
+  }
+  listReportSchedules(options = {}) {
+    return this.reportStore().listReportSchedules(options);
+  }
+  getReportSchedule(idOrName) {
+    return this.reportStore().getReportSchedule(idOrName);
+  }
+  updateReportSchedule(idOrName, input) {
+    const store = this.reportStore();
+    const schedule = store.updateReportSchedule(idOrName, input);
+    this.audit("report_schedule.update", "report_schedule", schedule.id, `Updated report schedule ${schedule.name}`, {
+      name: schedule.name,
+      enabled: schedule.enabled,
+      intervalSeconds: schedule.intervalSeconds,
+      channels: enabledReportChannels(schedule)
+    });
+    return schedule;
+  }
+  deleteReportSchedule(idOrName) {
+    const store = this.reportStore();
+    const schedule = store.getReportSchedule(idOrName);
+    const deleted = store.deleteReportSchedule(idOrName);
+    if (deleted && schedule) {
+      this.audit("report_schedule.delete", "report_schedule", schedule.id, `Deleted report schedule ${schedule.name}`, {
+        name: schedule.name
+      });
+    }
+    return deleted;
+  }
+  listReportRuns(options = {}) {
+    return this.reportStore().listReportRuns(options);
+  }
+  listAuditEvents(options = {}) {
+    return this.reportStore().listAuditEvents(options);
+  }
+  recordAuditEvent(input) {
+    return this.reportStore().recordAuditEvent(input);
+  }
+  async runReportSchedule(idOrName, options = {}) {
+    const store = this.reportStore();
+    const schedule = store.getReportSchedule(idOrName);
+    if (!schedule)
+      throw new Error(`Report schedule not found: ${idOrName}`);
+    if (!schedule.enabled)
+      throw new Error(`Report schedule is disabled: ${schedule.name}`);
+    if (this.inFlightReportSchedules.has(schedule.id))
+      throw new Error(`Report schedule already running: ${schedule.name}`);
+    this.inFlightReportSchedules.add(schedule.id);
+    try {
+      const startedAt = new Date().toISOString();
+      let deliveries = [];
+      let error = null;
+      let reportJson = null;
+      try {
+        const report = this.buildReport({ subject: schedule.subject ?? undefined });
+        reportJson = report.json;
+        deliveries = await this.sendReport({
+          subject: schedule.subject ?? undefined,
+          email: schedule.channels.email,
+          sms: schedule.channels.sms,
+          logs: schedule.channels.logs,
+          fetchImpl: options.fetchImpl
+        });
+        const failed = deliveries.filter((delivery) => !delivery.ok);
+        if (failed.length > 0) {
+          error = failed.map((delivery) => `${delivery.channel}: ${delivery.error ?? delivery.status ?? "failed"}`).join("; ");
+        }
+      } catch (caught) {
+        error = caught instanceof Error ? caught.message : String(caught);
+      }
+      const finishedAt = new Date().toISOString();
+      const run = store.recordReportRun({
+        scheduleId: schedule.id,
+        status: error ? "failed" : "success",
+        startedAt,
+        finishedAt,
+        deliveries,
+        error,
+        reportJson
+      });
+      this.audit("report_schedule.run", "report_schedule", schedule.id, `Ran report schedule ${schedule.name}`, {
+        runId: run.id,
+        status: run.status,
+        deliveryChannels: run.deliveries.map((delivery) => ({ channel: delivery.channel, ok: delivery.ok }))
+      });
+      return run;
+    } finally {
+      this.inFlightReportSchedules.delete(schedule.id);
+    }
+  }
+  async runDueReportSchedules(now = new Date, options = {}) {
+    const store = this.reportStore();
+    const schedules = store.listDueReportSchedules(now.toISOString());
+    const runs = [];
+    for (const schedule of schedules) {
+      runs.push(await this.runReportSchedule(schedule.id, options));
+    }
+    return runs;
+  }
   async checkMonitor(idOrName) {
     if (this.store.mode === "hosted")
       throw new Error("hosted checks require check_jobs and probes");
@@ -2304,6 +2837,9 @@ class UptimeService {
       this.runDueChecks().catch((error) => {
         console.error(error instanceof Error ? error.message : String(error));
       });
+      this.runDueReportSchedules(new Date, { fetchImpl: options.reportFetchImpl }).catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+      });
     }, tickMs);
     return {
       stop: () => clearInterval(timer)
@@ -2363,6 +2899,40 @@ class UptimeService {
     }
     return store;
   }
+  reportStore() {
+    if (this.store.mode === "hosted") {
+      throw new Error("hosted report schedules require cloud channel refs, workspace stores, and audit logging");
+    }
+    const store = this.store;
+    const required = [
+      "createReportSchedule",
+      "listReportSchedules",
+      "listDueReportSchedules",
+      "getReportSchedule",
+      "updateReportSchedule",
+      "deleteReportSchedule",
+      "recordReportRun",
+      "listReportRuns",
+      "recordAuditEvent",
+      "listAuditEvents"
+    ];
+    for (const method of required) {
+      if (typeof store[method] !== "function") {
+        throw new Error("report scheduling requires a report-capable store");
+      }
+    }
+    return store;
+  }
+  audit(action, resourceType, resourceId, message, metadata) {
+    this.reportStore().recordAuditEvent({
+      action,
+      resourceType,
+      resourceId,
+      message,
+      metadata,
+      actor: "local"
+    });
+  }
   submitProbeResultInTransaction(input) {
     const store = this.probeStore();
     const probe = store.getProbeIdentity(input.probeId);
@@ -2456,6 +3026,9 @@ class MonitorCheckBusyError extends Error {
     this.name = "MonitorCheckBusyError";
   }
 }
+function enabledReportChannels(schedule) {
+  return ["email", "sms", "logs"].filter((channel) => Boolean(schedule.channels[channel]));
+}
 function validateProbeSubmission(input) {
   if (!input.jobId.trim())
     throw new Error("Probe submission jobId is required");
@@ -2986,9 +3559,54 @@ async function handleApiRoute(service, request, url, apiPath, options, hosted) {
     const input = await jsonBody(request);
     return json(await service.sendReport({ ...input, fetchImpl: options.fetchImpl }));
   }
+  if (hosted && (apiPath.startsWith("/api/report-schedules") || apiPath.startsWith("/api/report-runs") || apiPath.startsWith("/api/audit-events"))) {
+    throw new ApiError("hosted report schedules require cloud channel refs, workspace stores, and audit logging", 501);
+  }
   if (hosted && apiPath.startsWith("/api/probes")) {
     throw new ApiError("hosted probe APIs require cloud check_jobs, workspace stores, and audit logging", 501);
   }
+  if (request.method === "GET" && apiPath === "/api/report-schedules") {
+    return json(service.listReportSchedules({ includeDisabled: url.searchParams.get("includeDisabled") === "true" }));
+  }
+  if (request.method === "POST" && apiPath === "/api/report-schedules") {
+    return json(service.createReportSchedule(await jsonBody(request)), 201);
+  }
+  if (request.method === "POST" && apiPath === "/api/report-schedules/run-due") {
+    const input = await jsonBody(request);
+    const now = input.now ? new Date(input.now) : new Date;
+    return json(await service.runDueReportSchedules(now, { fetchImpl: options.fetchImpl }));
+  }
+  const reportScheduleRunMatch = apiPath.match(/^\/api\/report-schedules\/([^/]+)\/run$/);
+  if (request.method === "POST" && reportScheduleRunMatch) {
+    return json(await service.runReportSchedule(decodeURIComponent(reportScheduleRunMatch[1]), { fetchImpl: options.fetchImpl }));
+  }
+  const reportScheduleMatch = apiPath.match(/^\/api\/report-schedules\/([^/]+)$/);
+  if (reportScheduleMatch) {
+    const id = decodeURIComponent(reportScheduleMatch[1]);
+    if (request.method === "GET") {
+      const schedule = service.getReportSchedule(id);
+      return schedule ? json(schedule) : json({ error: "not found" }, 404);
+    }
+    if (request.method === "PATCH") {
+      return json(service.updateReportSchedule(id, await jsonBody(request)));
+    }
+    if (request.method === "DELETE") {
+      return json({ deleted: service.deleteReportSchedule(id) });
+    }
+  }
+  if (request.method === "GET" && apiPath === "/api/report-runs") {
+    return json(service.listReportRuns({
+      scheduleId: url.searchParams.get("scheduleId") ?? undefined,
+      limit: numericParam(url, "limit", 50)
+    }));
+  }
+  if (request.method === "GET" && apiPath === "/api/audit-events") {
+    return json(service.listAuditEvents({
+      resourceType: url.searchParams.get("resourceType") ?? undefined,
+      resourceId: url.searchParams.get("resourceId") ?? undefined,
+      limit: numericParam(url, "limit", 50)
+    }));
+  }
   if (request.method === "GET" && apiPath === "/api/monitors") {
     return json(service.listMonitors({ includeDisabled: url.searchParams.get("includeDisabled") === "true" }));
   }
@@ -3084,6 +3702,10 @@ async function handleApiRoute(service, request, url, apiPath, options, hosted) {
 function hostedScopeFor(method, apiPath) {
   if (method === "POST" && apiPath === "/api/report")
     return "uptime:report";
+  if (apiPath.startsWith("/api/report-schedules") || apiPath.startsWith("/api/report-runs"))
+    return method === "GET" ? "uptime:read" : "uptime:report";
+  if (apiPath.startsWith("/api/audit-events"))
+    return method === "GET" ? "uptime:read" : "uptime:admin";
   if (apiPath.startsWith("/api/probes"))
     return method === "GET" ? "uptime:read" : "uptime:probe";
   if (method === "POST" && (apiPath === "/api/check-all" || /\/check$/.test(apiPath)))