watchfor 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # watchfor
2
2
 
3
3
  Official TypeScript SDK + CLI for [WatchFor](https://watchfor.io) —
4
- uptime & infrastructure monitoring (25 check types, confirmed alerting,
4
+ uptime & infrastructure monitoring (26 check types, confirmed alerting,
5
5
  status pages, on-call).
6
6
 
7
7
  ```bash
@@ -39,6 +39,9 @@ await wf.incidents.exclude(19351, { reason: "Probe-side DNS hiccup" });
39
39
  // Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset".
40
40
  await wf.monitors.reset(monitor.id!);
41
41
 
42
+ // Page integrity: after a deploy, accept what the newest check saw as the new baseline.
43
+ await wf.monitors.acceptBaseline(integrityMonitorId);
44
+
42
45
  // Older checks: pass next_cursor back as cursor (keep the same hours/success).
43
46
  const page = await wf.monitors.checks(monitor.id!, { hours: 24, limit: 100 });
44
47
  if (page.next_cursor) {
@@ -97,5 +100,5 @@ npx watchfor report --period 30d
97
100
  ## Links
98
101
 
99
102
  - API docs: https://watchfor.io/docs/api
100
- - MCP server for AI agents (54 tools): https://watchfor.io/docs/api/mcp
103
+ - MCP server for AI agents (56 tools): https://watchfor.io/docs/api/mcp
101
104
  - Create an API key: dashboard → Settings → API keys (`read` or `read+write` scope)
package/dist/client.d.ts CHANGED
@@ -10,6 +10,8 @@ export type Monitor = components["schemas"]["Monitor"];
10
10
  /** Monitor + `available_metrics` (GET /monitors/{id} only). */
11
11
  export type MonitorDetail = components["schemas"]["MonitorDetail"];
12
12
  export type MonitorReset = components["schemas"]["MonitorReset"];
13
+ export type IntegrityBaseline = components["schemas"]["IntegrityBaseline"];
14
+ export type IntegrityBaselineAccept = components["schemas"]["IntegrityBaselineAccept"];
13
15
  export type Incident = components["schemas"]["Incident"];
14
16
  export type AlertRule = components["schemas"]["AlertRule"];
15
17
  export type Contact = components["schemas"]["Contact"];
@@ -124,6 +126,16 @@ export declare class WatchFor {
124
126
  * the monitor and start uptime over ("since reset"). The monitor and
125
127
  * its configuration, alert rules, tags and locations stay. */
126
128
  reset: (id: string) => Promise<MonitorReset>;
129
+ /** Page integrity monitors: the accepted baseline of every watched
130
+ * page (whether it has one, when and how it was captured). */
131
+ getBaseline: (id: string) => Promise<IntegrityBaseline>;
132
+ /** Page integrity monitors: accept what the newest check saw as the
133
+ * new baseline — all pages, or only `pages`. Call it from a deploy
134
+ * pipeline a minute after the release; unfetched pages come back in
135
+ * `skipped`. */
136
+ acceptBaseline: (id: string, body?: {
137
+ pages?: string[];
138
+ }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept>;
127
139
  uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d") => Promise<Uptime>;
128
140
  /** Recent probe results, newest first. Page with `next_cursor` →
129
141
  * `cursor` (keep the same `hours`/`success`); `locations` is the
package/dist/client.js CHANGED
@@ -130,6 +130,17 @@ export class WatchFor {
130
130
  * the monitor and start uptime over ("since reset"). The monitor and
131
131
  * its configuration, alert rules, tags and locations stay. */
132
132
  reset: (id) => this.request("POST", `/monitors/${id}/reset`),
133
+ /** Page integrity monitors: the accepted baseline of every watched
134
+ * page (whether it has one, when and how it was captured). */
135
+ getBaseline: (id) => this.request("GET", `/monitors/${id}/baseline`),
136
+ /** Page integrity monitors: accept what the newest check saw as the
137
+ * new baseline — all pages, or only `pages`. Call it from a deploy
138
+ * pipeline a minute after the release; unfetched pages come back in
139
+ * `skipped`. */
140
+ acceptBaseline: (id, body, idempotencyKey) => this.request("POST", `/monitors/${id}/baseline`, {
141
+ body: body ?? {},
142
+ idempotencyKey,
143
+ }),
133
144
  uptime: (id, period) => this.request("GET", `/monitors/${id}/uptime`, { query: { period } }),
134
145
  /** Recent probe results, newest first. Page with `next_cursor` →
135
146
  * `cursor` (keep the same `hours`/`success`); `locations` is the
package/dist/index.d.ts CHANGED
@@ -1 +1 @@
1
- export { type ActivityEvent, type AlertRule, type ApiErrorBody, type Check, type CheckList, type CheckNowAck, type Contact, type ContactGroup, type Deleted, type DiagnosticCatalog, type DiagnosticCatalogEntry, type DiagnosticReport, type DiagnosticRun, type DiagnosticSlug, type Incident, type IncidentStats, type List, type MaintenanceWindow, type Monitor, type MonitorDetail, type MonitorReset, type Notification, type Plan, type StatusPage, type Summary, type Uptime, WatchFor, WatchForError, type WatchForOptions, } from "./client.js";
1
+ export { type ActivityEvent, type AlertRule, type ApiErrorBody, type Check, type CheckList, type CheckNowAck, type Contact, type ContactGroup, type Deleted, type DiagnosticCatalog, type DiagnosticCatalogEntry, type DiagnosticReport, type DiagnosticRun, type DiagnosticSlug, type Incident, type IncidentStats, type IntegrityBaseline, type IntegrityBaselineAccept, type List, type MaintenanceWindow, type Monitor, type MonitorDetail, type MonitorReset, type Notification, type Plan, type StatusPage, type Summary, type Uptime, WatchFor, WatchForError, type WatchForOptions, } from "./client.js";
package/dist/schema.d.ts CHANGED
@@ -260,6 +260,30 @@ export interface paths {
260
260
  patch?: never;
261
261
  trace?: never;
262
262
  };
263
+ "/monitors/{id}/baseline": {
264
+ parameters: {
265
+ query?: never;
266
+ header?: never;
267
+ path?: never;
268
+ cookie?: never;
269
+ };
270
+ /**
271
+ * Page integrity baseline — what each watched page is compared against
272
+ * @description Page integrity monitors only (404 for other types). One row per watched page: whether it has an accepted baseline, when it was captured, and how (auto = recorded from the first check, manual = accepted in the dashboard, api = this endpoint, timer = accepted automatically after the monitor's autoAcceptAfterHours).
273
+ */
274
+ get: operations["getMonitorBaseline"];
275
+ put?: never;
276
+ /**
277
+ * Accept the latest state of the watched pages as the new baseline — call it after a deploy
278
+ * @description Page integrity monitors only. Takes the newest checked fingerprint (and text) of every watched page — or only `pages` — as the accepted baseline, so an intended change stops alerting and the next check compares against it. Pages no check has fetched yet are returned in `skipped`. Typical use: the last step of a deploy pipeline, a minute after the release (so a check has seen the new version).
279
+ */
280
+ post: operations["acceptMonitorBaseline"];
281
+ delete?: never;
282
+ options?: never;
283
+ head?: never;
284
+ patch?: never;
285
+ trace?: never;
286
+ };
263
287
  "/monitors/{id}/uptime": {
264
288
  parameters: {
265
289
  query?: never;
@@ -1196,7 +1220,7 @@ export interface components {
1196
1220
  CatalogConfigField: {
1197
1221
  key: string;
1198
1222
  /** @enum {string} */
1199
- type: "string" | "number" | "boolean" | "enum" | "array";
1223
+ type: "string" | "number" | "boolean" | "enum" | "array" | "object";
1200
1224
  enum?: string[];
1201
1225
  default?: unknown;
1202
1226
  /** @description Write-only credential; read back as [redacted] */
@@ -1235,7 +1259,8 @@ export interface components {
1235
1259
  | "browser"
1236
1260
  | "heartbeat"
1237
1261
  | "mcp"
1238
- | "api";
1262
+ | "api"
1263
+ | "integrity";
1239
1264
  target?: string;
1240
1265
  description?: string | null;
1241
1266
  interval_seconds?: number;
@@ -1398,7 +1423,8 @@ export interface components {
1398
1423
  | "browser"
1399
1424
  | "heartbeat"
1400
1425
  | "mcp"
1401
- | "api";
1426
+ | "api"
1427
+ | "integrity";
1402
1428
  /** @description Format per type (see GET /meta/monitor-types). Targets in private, loopback, link-local or cloud-metadata address space (and internal hostnames such as localhost, *.internal) are rejected with 400. */
1403
1429
  target: string;
1404
1430
  /** @description Seconds; validated against the plan's per-type minimum */
@@ -1626,6 +1652,8 @@ export interface components {
1626
1652
  region?: string;
1627
1653
  country?: string;
1628
1654
  country_code?: string;
1655
+ /** @description The location can run real-browser checks (Core Web Vitals, Page integrity in browser mode). */
1656
+ browser?: boolean;
1629
1657
  };
1630
1658
  Incident: {
1631
1659
  id?: number;
@@ -1660,12 +1688,23 @@ export interface components {
1660
1688
  expected?: string;
1661
1689
  detected?: string;
1662
1690
  metric_failure?: boolean;
1691
+ /** @description Page integrity monitors in browser mode, single-incident responses only: the screenshots the check that opened the incident took (a page is photographed only when it differs from its baseline). `url` is a signed link valid for `expires_in` seconds — fetch the incident again for a fresh one. Absent for other monitor types; empty when the check took none. */
1692
+ screenshots?: {
1693
+ /** Format: uri */
1694
+ page_url?: string;
1695
+ /** Format: uri */
1696
+ url?: string;
1697
+ /** Format: date-time */
1698
+ taken_at?: string | null;
1699
+ expires_in?: number;
1700
+ }[];
1663
1701
  } | null;
1664
1702
  /** @description The fire-time snapshot the alerting engine stored: the metrics the probe reported (http.status_code, response_time_ms, ssl.days_until_expiry, …), an optional response excerpt, the rule expression, the failure threshold, which prober fired and which probers confirmed. Values under sensitive keys are redacted. */
1665
1703
  trigger?: {
1666
1704
  metrics?: {
1667
1705
  [key: string]: unknown;
1668
1706
  } | null;
1707
+ /** @description The response excerpt the probe kept (status, headers, body_snippet) plus page_title and visible_text — the readable part of an HTML body — and, from newer probes, final_url and redirect_chain. */
1669
1708
  response?: {
1670
1709
  [key: string]: unknown;
1671
1710
  } | null;
@@ -1688,6 +1727,9 @@ export interface components {
1688
1727
  at?: string;
1689
1728
  type?: string;
1690
1729
  source?: string | null;
1730
+ /** @description On the resolved event: exact seconds from start to resolution */
1731
+ duration_seconds?: number;
1732
+ /** @description The event payload without the fire-time snapshot (that is `trigger`) */
1691
1733
  detail?: {
1692
1734
  [key: string]: unknown;
1693
1735
  } | null;
@@ -1703,6 +1745,46 @@ export interface components {
1703
1745
  /** Format: date-time */
1704
1746
  excluded_at?: string | null;
1705
1747
  };
1748
+ /** @description The accepted baseline of a page integrity monitor */
1749
+ IntegrityBaseline: {
1750
+ /** @constant */
1751
+ object: "integrity_baseline";
1752
+ /** Format: uuid */
1753
+ monitor_id: string;
1754
+ pages: {
1755
+ /** Format: uri */
1756
+ url: string;
1757
+ has_baseline: boolean;
1758
+ /** Format: date-time */
1759
+ captured_at: string | null;
1760
+ /**
1761
+ * @description auto = recorded from the first check, manual = accepted in the dashboard, api = accepted via this API, timer = accepted automatically because nobody reviewed the change within the monitor's autoAcceptAfterHours
1762
+ * @enum {string|null}
1763
+ */
1764
+ source: "auto" | "manual" | "api" | "timer" | null;
1765
+ /** @description User or API key name; null for auto and timer */
1766
+ accepted_by?: string | null;
1767
+ }[];
1768
+ trusted_origins?: string[];
1769
+ text_change_threshold?: number;
1770
+ };
1771
+ IntegrityBaselineAcceptRequest: {
1772
+ /** @description Accept only these watched pages; omit for all */
1773
+ pages?: string[];
1774
+ };
1775
+ IntegrityBaselineAccept: {
1776
+ /** @constant */
1777
+ object: "integrity_baseline_accept";
1778
+ /** Format: uuid */
1779
+ monitor_id: string;
1780
+ accepted: string[];
1781
+ skipped: {
1782
+ url: string;
1783
+ reason: string;
1784
+ }[];
1785
+ /** Format: date-time */
1786
+ captured_at?: string | null;
1787
+ };
1706
1788
  MonitorReset: {
1707
1789
  /** @constant */
1708
1790
  object?: "monitor_reset";
@@ -1718,7 +1800,7 @@ export interface components {
1718
1800
  /** @description Best-effort steps that failed (e.g. clickhouse); the reset marker is set regardless */
1719
1801
  warnings?: string[];
1720
1802
  };
1721
- /** @description A server running watchfor-agent. `status` is the agent's liveness (online = a batch in the last 90 s, stale = none for 90 s, offline = none for 10 min, never = not reported yet). `monitor_id` is the host's internal monitor — use it wherever a monitor id is asked for (status-page components, maintenance windows, incidents). `metrics` are the latest gauges from the last five minutes, null when the host is silent. */
1803
+ /** @description A server running watchfor-agent. `status` is the agent's liveness (online = a batch within three push intervals and never less than 90 s, stale = none for that long, offline = none for 10 min, never = not reported yet). `monitor_id` is the host's internal monitor — use it wherever a monitor id is asked for (status-page components, maintenance windows, incidents). `metrics` are the latest gauges from the last five minutes, null when the host is silent. */
1722
1804
  Host: {
1723
1805
  /** Format: uuid */
1724
1806
  id?: string;
@@ -1736,6 +1818,7 @@ export interface components {
1736
1818
  os?: string | null;
1737
1819
  kernel?: string | null;
1738
1820
  arch?: string | null;
1821
+ /** @description The agent's tags as key=value strings, sorted (e.g. env=prod, role=db) */
1739
1822
  tags?: string[];
1740
1823
  push_interval_seconds?: number;
1741
1824
  /** Format: uuid */
@@ -2087,6 +2170,11 @@ export interface components {
2087
2170
  position?: number;
2088
2171
  /** @enum {string} */
2089
2172
  display_mode?: "rolled_up" | "expanded" | "collapsible_group";
2173
+ /**
2174
+ * @description How much an auto-published incident notice says about why this component's monitors or hosts fail: hidden = generic 'service disruption'; cause = a plain-words category ('Disk space running low', 'Returning errors'), no values; full = the category plus the detected value ('Disk / is 92.0% full'), for internal pages. A notice covering several components uses the most private level among them. Set in the dashboard component editor.
2175
+ * @enum {string}
2176
+ */
2177
+ public_cause?: "hidden" | "cause" | "full";
2090
2178
  monitor_ids?: string[];
2091
2179
  monitor_tags?: string[];
2092
2180
  /**
@@ -2284,7 +2372,8 @@ export interface components {
2284
2372
  | "browser"
2285
2373
  | "heartbeat"
2286
2374
  | "mcp"
2287
- | "api";
2375
+ | "api"
2376
+ | "integrity";
2288
2377
  label?: string;
2289
2378
  description?: string;
2290
2379
  target_format?: string;
@@ -2325,7 +2414,7 @@ export interface components {
2325
2414
  started_24h?: number;
2326
2415
  };
2327
2416
  open_maintenance_windows?: number;
2328
- /** @description Servers running the agent (revoked ones excluded) by liveness — the same rule as GET /hosts: online = reported within 90 s, stale = 90 s–10 min, offline = longer, never = has not reported yet */
2417
+ /** @description Servers running the agent (revoked ones excluded) by liveness — the same rule as GET /hosts: online = reported within three push intervals (at least 90 s), stale = longer but under 10 min, offline = longer, never = has not reported yet */
2329
2418
  hosts?: {
2330
2419
  total?: number;
2331
2420
  online?: number;
@@ -3382,6 +3471,77 @@ export interface operations {
3382
3471
  };
3383
3472
  };
3384
3473
  };
3474
+ getMonitorBaseline: {
3475
+ parameters: {
3476
+ query?: never;
3477
+ header?: never;
3478
+ path: {
3479
+ /** @description Resource id (UUID) */
3480
+ id: string;
3481
+ };
3482
+ cookie?: never;
3483
+ };
3484
+ requestBody?: never;
3485
+ responses: {
3486
+ /** @description OK */
3487
+ 200: {
3488
+ headers: {
3489
+ [name: string]: unknown;
3490
+ };
3491
+ content: {
3492
+ "application/json": components["schemas"]["IntegrityBaseline"];
3493
+ };
3494
+ };
3495
+ /** @description Error */
3496
+ default: {
3497
+ headers: {
3498
+ [name: string]: unknown;
3499
+ };
3500
+ content: {
3501
+ "application/json": components["schemas"]["Error"];
3502
+ };
3503
+ };
3504
+ };
3505
+ };
3506
+ acceptMonitorBaseline: {
3507
+ parameters: {
3508
+ query?: never;
3509
+ header?: {
3510
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
3511
+ "Idempotency-Key"?: string;
3512
+ };
3513
+ path: {
3514
+ /** @description Resource id (UUID) */
3515
+ id: string;
3516
+ };
3517
+ cookie?: never;
3518
+ };
3519
+ requestBody?: {
3520
+ content: {
3521
+ "application/json": components["schemas"]["IntegrityBaselineAcceptRequest"];
3522
+ };
3523
+ };
3524
+ responses: {
3525
+ /** @description The pages accepted and the ones skipped */
3526
+ 200: {
3527
+ headers: {
3528
+ [name: string]: unknown;
3529
+ };
3530
+ content: {
3531
+ "application/json": components["schemas"]["IntegrityBaselineAccept"];
3532
+ };
3533
+ };
3534
+ /** @description Error */
3535
+ default: {
3536
+ headers: {
3537
+ [name: string]: unknown;
3538
+ };
3539
+ content: {
3540
+ "application/json": components["schemas"]["Error"];
3541
+ };
3542
+ };
3543
+ };
3544
+ };
3385
3545
  getMonitorUptime: {
3386
3546
  parameters: {
3387
3547
  query?: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Official TypeScript SDK + CLI for WatchFor — uptime & infrastructure monitoring (monitors, alert rules, incidents, maintenance windows) over the REST API.",
5
5
  "keywords": [
6
6
  "watchfor",