/** * WatchDiff - high-level public facade. * * Usage: * import { WatchDiff } from "watchdiff-core"; * * const wd = new WatchDiff(); * wd.watch("https://example.com/product", { target: ".price", interval: 60 }); * wd.onChange((report) => console.log(report)); * wd.start(); */ import { type ActiveBetween, type BrowserOptions, type DiffMode, type DiffReport, type FailurePolicy, type IStore, type MaintenanceWindow, type SilenceInfo, type SpikeInfo, type StatusChangeInfo, type Snapshot, type WatchConfig, type WatcherStatus } from "./models.js"; import { type DbDiffMode, type DbDiffReport, type DbWatchConfig, type SchemaChangeInfo, type ThresholdInfo } from "./db-models.js"; import { type CertExpiryInfo, type CertChangeInfo, type CertWatchConfig, type CertWatcherStatus } from "./cert-models.js"; import { type SitemapDiffReport, type SitemapEntry } from "./sitemap-models.js"; import { type DbWatcherStatus } from "./db-scheduler/index.js"; import { type SitemapWatcherStatus } from "./sitemap-scheduler/index.js"; export interface WatchOptions { /** Stable watcher identity key. Allows multiple watchers on the same URL and targeted pause/resume. */ id?: string; /** CSS selector or XPath expression - undefined = full page. */ target?: string; /** Seconds between checks (default 300). */ interval?: number; /** Human-readable label. */ label?: string; /** Extra HTTP headers. */ headers?: Record; /** Cookies to send with every request (merged into the Cookie header). */ cookies?: Record; /** HTTP timeout in milliseconds (default 15000). */ timeout?: number; /** CSS selectors to strip before diffing. */ ignoreSelectors?: string[]; /** Regex patterns to strip from text before diffing. */ ignorePatterns?: RegExp[]; /** Use a headless browser (Playwright) for JS-heavy pages. */ browser?: boolean; /** Options for the headless browser. */ browserOptions?: BrowserOptions; /** List of proxy URLs to rotate through. */ proxies?: string[]; /** List of User-Agent strings to rotate through. */ userAgents?: string[]; /** Diff granularity: "line" (default), "semantic", "word", or "json". */ diffMode?: DiffMode; /** Callback(s) invoked with a DiffReport on each change. */ onChange?: ((report: DiffReport) => void | Promise) | Array<(report: DiffReport) => void | Promise>; /** Webhook URLs (Discord / Slack / Telegram / Teams / ntfy.sh / custom). */ webhooks?: string[]; /** Minimum changes required to trigger an alert. */ minChanges?: number; /** Minimum seconds between two consecutive alerts for this URL (anti-spam). */ cooldown?: number; /** Number of fetch retries on error before giving up (default 0). */ retries?: number; /** Base delay in milliseconds between retries - doubles on each attempt (default 1000). */ retryDelay?: number; /** Interval randomisation factor 0-1. 0.2 = ±20% variance (default 0). */ jitter?: number; /** When true: fetch and diff but do not save snapshots or fire alerts. */ dryRun?: boolean; /** Keep only the last N snapshots per URL (undefined = keep all). */ maxSnapshots?: number; /** Minimum fraction 0-1 of content that must change before alerting (default 0). */ changeThreshold?: number; /** Strip standalone numbers from text before diffing to ignore counter/date noise. */ ignoreNumbers?: boolean; /** Fire onSilence after this many seconds without a detected change (undefined = disabled). */ alertIfNoChangeAfter?: number; /** Called on every fetch or parse error. */ onError?: (err: Error, config: WatchConfig) => void; /** Called when alertIfNoChangeAfter seconds have elapsed without a detected change. */ onSilence?: (info: SilenceInfo) => void; /** Number of retry attempts for failed webhook deliveries (default 3, 0 = no retry). */ webhookRetries?: number; /** Save the full-page HTML to disk whenever a change is detected. */ archiveHtml?: boolean; /** Capture a PNG screenshot on change (requires browser: true). */ screenshotOnChange?: boolean; /** Spike detection: time window in seconds to count changes. */ changeSpikeWindow?: number; /** Spike detection: alert when this many changes occur inside changeSpikeWindow. */ changeSpikeThreshold?: number; /** Called when a change spike is detected. */ onSpike?: (info: SpikeInfo) => void; /** Alert when the HTTP status code changes (e.g. 200 → 503 or 503 → 200). */ alertOnStatusChange?: boolean; /** Called when the HTTP status code changes. */ onStatusChange?: (info: StatusChangeInfo) => void; /** Only fire alerts when this custom condition returns true. */ alertIf?: (report: DiffReport) => boolean; /** Generate an AI-powered natural language summary of detected changes. */ aiSummary?: boolean; /** * AI provider for summary generation. * When omitted, auto-detected from ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY env vars. * Use type "custom" with a callAi function for any other provider or local model. */ aiProvider?: import("./ai-summarizer/index.js").AiProvider; /** Expected HTTP status code - fire onError when actual status differs. */ expectedStatus?: number; /** Record HTTP response time on every check (stored in DiffReport). */ trackResponseTime?: boolean; /** Cron expression (5-field) that overrides interval-based scheduling. */ schedule?: string; /** Seconds to wait before confirming a change is real (flapping detection). */ confirmAfter?: number; /** JSON path to extract a sub-value before diffing (e.g. "$.data.price"). */ jsonPath?: string; /** Custom prompt sent to the AI instead of the default template. */ aiPrompt?: string | ((report: DiffReport) => string | Promise); /** Time windows during which checks are skipped entirely. */ maintenanceWindows?: MaintenanceWindow[]; /** Restrict monitoring to specific hours/days of the week. */ activeBetween?: ActiveBetween; /** Policy controlling consecutive failures/recoveries before alerting. */ failurePolicy?: FailurePolicy; /** Called when a watcher recovers after a consecutive-failure streak. */ onRecovery?: (config: WatchConfig) => void; /** Cap on exponential backoff delay in ms (default: Infinity). */ maxRetryDelay?: number; /** Fire onChange on the very first snapshot capture (default false). */ alertOnFirstCheck?: boolean; /** Extra headers merged into every outgoing webhook POST. */ webhookHeaders?: Record; /** Auto-delete snapshots older than N days after each save. */ retentionDays?: number; /** HTTP Basic Auth credentials - adds an Authorization: Basic header. */ auth?: { user: string; pass: string; }; /** Async callback fired before every fetch tick. A thrown error logs a warning but does not skip the check. */ onBeforeCheck?: (config: WatchConfig) => void | Promise; /** When set, switches the fetcher to POST. String bodies are sent as-is; objects are JSON-serialised. */ requestBody?: string | Record; /** Tags for grouping watchers (e.g. ["prod", "prices"]). Use wd.pause("prod") to pause by group. */ tags?: string[]; /** Minimum seconds between two consecutive checks (floor on interval/jitter). */ minInterval?: number; /** When true, skip SSRF checks for URLs pointing to private/loopback addresses (for internal monitoring). */ allowPrivateUrls?: boolean; /** Maximum response body size in bytes (default: 10MB). */ maxResponseSize?: number; } export interface WatchFileOptions { interval?: number; label?: string; diffMode?: DiffMode; ignorePatterns?: RegExp[]; cooldown?: number; dryRun?: boolean; maxSnapshots?: number; changeThreshold?: number; ignoreNumbers?: boolean; onChange?: ((report: DiffReport) => void | Promise) | Array<(report: DiffReport) => void | Promise>; webhooks?: string[]; webhookRetries?: number; alertIf?: (report: DiffReport) => boolean; aiSummary?: boolean; aiProvider?: import("./ai-summarizer/index.js").AiProvider; aiPrompt?: string | ((report: DiffReport) => string | Promise); onError?: (err: Error, config: WatchConfig) => void; schedule?: string; confirmAfter?: number; jsonPath?: string; } export interface WatchApiOptions extends WatchOptions { /** Expected HTTP status code - alert when response differs (default 200). */ expectedStatus?: number; /** Record and expose HTTP response time in DiffReport. */ trackResponseTime?: boolean; } export interface WatchCertOptions { port?: number; interval?: number; label?: string; warnDaysBeforeExpiry?: number; alertOnExpiry?: boolean; alertOnChange?: boolean; cooldown?: number; dryRun?: boolean; webhooks?: string[]; webhookRetries?: number; onExpiry?: (info: CertExpiryInfo) => void | Promise; onChange?: (info: CertChangeInfo) => void | Promise; onError?: (err: Error, config: CertWatchConfig) => void; } export interface WatchSitemapOptions { label?: string; interval?: number; onAdded?: (entries: SitemapEntry[]) => void; onRemoved?: (entries: SitemapEntry[]) => void; onChange?: (report: SitemapDiffReport) => void; onError?: (err: Error) => void; } export interface DbWatchOptions { /** Custom SELECT query : overrides the default `SELECT * FROM `. */ query?: string; /** Column(s) that uniquely identify a row (default: first column). */ primaryKey?: string[]; /** Columns to exclude from comparison. */ ignoreColumns?: string[]; /** Diff strategy: "row" (default), "schema", "aggregate", or "value". */ diffMode?: DbDiffMode; /** Seconds between checks (default 300). */ interval?: number; /** Human-readable label. */ label?: string; dryRun?: boolean; cooldown?: number; maxSnapshots?: number; alertOnInsert?: boolean; alertOnDelete?: boolean; alertOnUpdate?: boolean; /** Alert threshold % for aggregate mode (0 = any change). */ threshold?: number; webhooks?: string[]; webhookRetries?: number; onChange?: (report: DbDiffReport) => void | Promise; onError?: (err: Error, config: DbWatchConfig) => void; onSchemaChange?: (info: SchemaChangeInfo) => void; onThreshold?: (info: ThresholdInfo) => void; /** Generate an AI-powered summary of detected DB changes. */ aiSummary?: boolean; /** AI provider - auto-detected from env vars when omitted. */ aiProvider?: import("./ai-summarizer/index.js").AiProvider; } export interface WatchDiffOptions { /** Directory for JSON storage (default ".watchdiff"). Ignored when a custom store is provided. */ storageDir?: string; /** Custom store (e.g. SqliteStore). Overrides storageDir. */ store?: IStore; /** Maximum number of simultaneous in-flight checks (default: unlimited). */ concurrency?: number; /** Global floor on minimum seconds between checks. Applied to all watchers that don't set their own minInterval. */ minInterval?: number; /** Maximum number of watchers allowed. Throws when exceeded (default: no limit). Recommended max: 1000. */ maxWatchers?: number; } export declare class WatchDiff { private readonly store; private readonly concurrency; private readonly minInterval; private readonly maxWatchers; private readonly configs; private readonly dbConfigs; private readonly certConfigs; private readonly sitemapConfigs; private readonly globalCallbacks; private scheduler; private dbScheduler; private certScheduler; private sitemapScheduler; private stopFn; private dbStopFn; private certStopFn; private sitemapStopFn; private statusServer; /** * @param optsOrStorageDir - WatchDiffOptions object, or storage dir string for backward compat. * @param store - Custom store (e.g. SqliteStore). Only used when first arg is a string. * * @example * new WatchDiff() // defaults * new WatchDiff(".watchdiff") // backward-compat string * new WatchDiff({ concurrency: 10 }) // options object * new WatchDiff({ storageDir: ".wd", store }) // full options */ constructor(optsOrStorageDir?: WatchDiffOptions | string, store?: IStore); /** * Register a URL to monitor. Returns `this` for chaining. */ watch(url: string, opts?: WatchOptions): this; /** * Register a local file or directory to monitor for changes. Returns `this` for chaining. * Uses `file://` prefix internally; no HTTP request is made. */ watchFile(path: string, opts?: WatchFileOptions): this; /** * Register a REST/JSON API endpoint to monitor. Returns `this` for chaining. * Defaults to JSON diff mode, tracks response time, and validates expected HTTP status. */ watchApi(url: string, opts?: WatchApiOptions): this; /** * Register an SSL/TLS certificate to monitor. Returns `this` for chaining. * Alerts when the certificate is about to expire or when the fingerprint changes. */ watchCert(hostname: string, opts?: WatchCertOptions): this; /** * Register a sitemap URL to monitor for added/removed URLs. Returns `this` for chaining. */ watchSitemap(url: string, options?: WatchSitemapOptions): this; /** * Register a database table to monitor for changes. Returns `this` for chaining. * * Supported connection strings: * sqlite://./path/to/db.sqlite * postgresql://user:pass@host:5432/dbname * mysql://user:pass@host:3306/dbname */ watchDb(connectionString: string, table: string, opts?: DbWatchOptions): this; /** * Register a global callback fired whenever ANY watched URL changes. * Returns `this` for chaining. */ onChange(callback: (report: DiffReport) => void | Promise): this; /** * Start continuous monitoring. * * Returns a `stop()` function. The process will keep running until * `stop()` is called or the process is killed. */ start(): () => void; /** * Stop all watchers. */ stop(): void; /** * Run a single immediate check for a registered URL. * * @throws Error if the URL is not registered. */ checkOnce(url: string): Promise; /** * Pause a watcher by URL, stable ID, or tag. * When the argument matches a tag, all watchers with that tag are paused. * No-op if monitoring has not started yet. */ pause(urlOrIdOrTag: string): void; /** * Resume a previously paused watcher by URL, stable ID, or tag. * When the argument matches a tag, all watchers with that tag are resumed. */ resume(urlOrIdOrTag: string): void; /** * Return runtime status for all registered watchers. */ status(): WatcherStatus[]; /** * Return runtime status for all registered DB watchers. */ getDbStatuses(): DbWatcherStatus[]; /** * Return runtime status for all registered certificate watchers. */ getCertStatuses(): CertWatcherStatus[]; /** * Return runtime status for all registered sitemap watchers. */ getSitemapStatuses(): SitemapWatcherStatus[]; history(url: string, limit?: number): Snapshot[]; reports(url: string, limit?: number): Record[]; clear(url: string): void; /** * Export diff reports for a URL to CSV string. */ exportReportsCsv(url: string, limit?: number): string; /** * Export snapshot history for a URL to CSV string. */ exportSnapshotsCsv(url: string, limit?: number): string; /** * Export diff reports for a URL as a JSON string. */ exportReportsJson(url: string, limit?: number): string; /** * Export snapshot history for a URL as a JSON string. */ exportSnapshotsJson(url: string, limit?: number): string; /** * Export diff reports for a URL to an XLSX Buffer. * Requires: npm install exceljs */ exportReportsXlsx(url: string, limit?: number): Promise; /** * Export snapshot history for a URL to an XLSX Buffer. * Requires: npm install exceljs */ exportSnapshotsXlsx(url: string, limit?: number): Promise; /** * Start a built-in HTTP status server. * Endpoints: GET /health, /status, /metrics (Prometheus). */ startStatusServer(port?: number, bindHost?: string): void; stopStatusServer(): void; /** * Fetch and diff two arbitrary URLs without any persistent storage. * Uses dynamic imports to load internal modules lazily. */ compareUrls(urlA: string, urlB: string, opts?: WatchOptions): Promise; private findConfig; } //# sourceMappingURL=core.d.ts.map