watchfor 0.12.1 → 0.14.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
@@ -39,8 +39,8 @@ 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);
42
+ // Page integrity: after a deploy, check the pages and accept what that check saw.
43
+ await wf.monitors.acceptBaseline(integrityMonitorId, { fresh: true });
44
44
 
45
45
  // Browser checks: try a Playwright script once (nothing saved), then read the result.
46
46
  const { id } = await wf.playwright.testRun({ script, target: "https://shop.example.com" });
@@ -65,7 +65,7 @@ await wf.contactGroups.delete("<group-id>", { force: true });
65
65
 
66
66
  ### Live diagnostics
67
67
 
68
- Run any of 22 checks from WatchFor's probe fleet against **any public
68
+ Run any of 24 checks from WatchFor's probe fleet against **any public
69
69
  target**, monitored or not — this measures right now, rather than reading
70
70
  what WatchFor recorded:
71
71
 
@@ -82,6 +82,21 @@ const dns = await wf.diagnostics.run("dns-lookup", {
82
82
  if (!dns.success) console.log("finding:", dns.error);
83
83
  console.log("runs left this hour:", dns.remaining);
84
84
 
85
+ // Graded checks (tls-grade, http-headers, cwv-check, mcp-check, email-health,
86
+ // mail-server-check, cdn-check, smart-audit, dns-health) also return the
87
+ // dashboard's WatchFor Grade: letter, rubric id and what holds it down.
88
+ const headers = await wf.diagnostics.run("http-headers", {
89
+ target: "https://example.com",
90
+ });
91
+ if (headers.grade?.letter) {
92
+ console.log(`grade ${headers.grade.letter} (${headers.grade.rubric})`);
93
+ for (const c of headers.grade.capped_by) {
94
+ console.log(` max ${c.cap}: ${c.title} — fix: ${c.fix}`);
95
+ }
96
+ } else {
97
+ console.log("not graded:", headers.grade?.not_graded_reason);
98
+ }
99
+
85
100
  // The whole picture in one call: DNS + propagation + TLS + HTTP + ping
86
101
  // from up to 3 regions, aggregated into one verdict.
87
102
  const report = await wf.diagnostics.diagnoseTarget({ target: "example.com" });
package/dist/client.d.ts CHANGED
@@ -12,6 +12,8 @@ export type MonitorDetail = components["schemas"]["MonitorDetail"];
12
12
  export type MonitorReset = components["schemas"]["MonitorReset"];
13
13
  export type IntegrityBaseline = components["schemas"]["IntegrityBaseline"];
14
14
  export type IntegrityBaselineAccept = components["schemas"]["IntegrityBaselineAccept"];
15
+ /** A fresh accept whose check has not landed yet (HTTP 202). */
16
+ export type IntegrityBaselineAcceptPending = components["schemas"]["IntegrityBaselineAcceptPending"];
15
17
  export type PlaywrightTestRunRequest = components["schemas"]["PlaywrightTestRunRequest"];
16
18
  export type PlaywrightTestRunAccepted = components["schemas"]["PlaywrightTestRunAccepted"];
17
19
  export type PlaywrightTestRun = components["schemas"]["PlaywrightTestRun"];
@@ -48,6 +50,12 @@ export type DiagnosticCatalogEntry = components["schemas"]["DiagnosticCatalogEnt
48
50
  export type DiagnosticRun = components["schemas"]["DiagnosticRun"];
49
51
  /** The `diagnose-target` bundle: a verdict plus a status per check. */
50
52
  export type DiagnosticReport = components["schemas"]["DiagnosticReport"];
53
+ /**
54
+ * A WatchFor Grade (graded checks only): the dashboard's A+…F letter, its
55
+ * rubric id and `capped_by`, the findings that hold it down. `letter: null`
56
+ * = not graded (we could not measure), with `not_graded_reason`.
57
+ */
58
+ export type WatchForGrade = components["schemas"]["WatchForGrade"];
51
59
  /** Which check to run — short aliases (`dns`, `port-check`, …) also work. */
52
60
  export type DiagnosticSlug = components["schemas"]["DiagnosticRun"]["tool"];
53
61
  export interface List<T> {
@@ -162,13 +170,16 @@ export declare class WatchFor {
162
170
  * page (whether it has one, when and how it was captured). */
163
171
  getBaseline: (id: string) => Promise<IntegrityBaseline>;
164
172
  /** Page integrity monitors: accept what the newest check saw as the
165
- * new baseline — all pages, or only `pages` — and start a check of
166
- * them (`check_requested`). In a deploy pipeline, run `checkNow` and
167
- * wait for a newer check first, so the release is what gets
168
- * accepted; unfetched pages come back in `skipped`. */
173
+ * new baseline — all pages, or only `pages`. Open integrity incidents
174
+ * resolve at once when nothing else differs (`incidents_resolved`).
175
+ * In a deploy pipeline pass `fresh: true`: the pages are checked
176
+ * first and that check is accepted (`status: "pending"` = still
177
+ * running, finishing on its own — see `getBaseline().fresh_accept`);
178
+ * unfetched pages come back in `skipped`. */
169
179
  acceptBaseline: (id: string, body?: {
170
180
  pages?: string[];
171
- }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept>;
181
+ fresh?: boolean;
182
+ }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept | IntegrityBaselineAcceptPending>;
172
183
  /** Browser checks: runs, newest first (`status` failed | flaky). */
173
184
  runs: (id: string, params?: {
174
185
  status?: "all" | "failed" | "flaky";
package/dist/client.js CHANGED
@@ -156,10 +156,12 @@ export class WatchFor {
156
156
  * page (whether it has one, when and how it was captured). */
157
157
  getBaseline: (id) => this.request("GET", `/monitors/${id}/baseline`),
158
158
  /** Page integrity monitors: accept what the newest check saw as the
159
- * new baseline — all pages, or only `pages` — and start a check of
160
- * them (`check_requested`). In a deploy pipeline, run `checkNow` and
161
- * wait for a newer check first, so the release is what gets
162
- * accepted; unfetched pages come back in `skipped`. */
159
+ * new baseline — all pages, or only `pages`. Open integrity incidents
160
+ * resolve at once when nothing else differs (`incidents_resolved`).
161
+ * In a deploy pipeline pass `fresh: true`: the pages are checked
162
+ * first and that check is accepted (`status: "pending"` = still
163
+ * running, finishing on its own — see `getBaseline().fresh_accept`);
164
+ * unfetched pages come back in `skipped`. */
163
165
  acceptBaseline: (id, body, idempotencyKey) => this.request("POST", `/monitors/${id}/baseline`, {
164
166
  body: body ?? {},
165
167
  idempotencyKey,
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 IntegrityBaseline, type IntegrityBaselineAccept, type List, type MaintenanceWindow, type Monitor, type MonitorDetail, type MonitorReset, type Notification, type Plan, type PlaywrightRun, type PlaywrightRunSummary, type PlaywrightTestRun, type PlaywrightTestRunAccepted, type PlaywrightTestRunRequest, type ScriptVersion, type ScriptVersionSummary, type StatusPage, type Summary, type Uptime, type Variable, type VariableDeleted, 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 IntegrityBaselineAcceptPending, type List, type MaintenanceWindow, type Monitor, type MonitorDetail, type MonitorReset, type Notification, type Plan, type PlaywrightRun, type PlaywrightRunSummary, type PlaywrightTestRun, type PlaywrightTestRunAccepted, type PlaywrightTestRunRequest, type ScriptVersion, type ScriptVersionSummary, type StatusPage, type Summary, type Uptime, type Variable, type VariableDeleted, WatchFor, WatchForError, type WatchForGrade, type WatchForOptions, } from "./client.js";
package/dist/schema.d.ts CHANGED
@@ -415,7 +415,9 @@ export interface paths {
415
415
  put?: never;
416
416
  /**
417
417
  * Accept the latest state of the watched pages as the new baseline — call it after a deploy
418
- * @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. A check of the pages starts right away (`check_requested`), so open findings close on a clean check within a minute or two. Pages no check has fetched yet are returned in `skipped`. Typical use: the last step of a deploy pipeline — first `POST /v1/monitors/{id}/check-now`, wait until `GET /v1/monitors/{id}/checks` shows a check newer than the release, then accept, so the baseline is the new version and not the one before it.
418
+ * @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. When the accept leaves nothing to fix, the monitor's open integrity incidents are resolved at once (`incidents_resolved`; the incident timeline says "baseline accepted by <key>"); otherwise a check of the pages starts right away (`check_requested`) and they close on clean checks. Pages no check has fetched yet are returned in `skipped`.
419
+ *
420
+ * Deploy hook: `POST /v1/monitors/{id}/baseline?fresh=true` (or `"fresh": true`) as the last step of a release. The server requests a check, waits for a result from that moment on (polling every ~3 s, at most ~85 s — under the 100 s proxy limit) and accepts from it, so the baseline is the new version and never the one before it; a page that check could not fetch is skipped, not taken from an older check. If the check takes longer you get **202** `pending` and the accept finishes in the background when the check lands (at most 5 minutes after the request) — poll `GET /v1/monitors/{id}/baseline` → `fresh_accept`. Fresh accepts share the accept's check budget (12 per hour per monitor, counting the check after each accept); over it → 429 with `Retry-After`. A paused monitor → 409.
419
421
  */
420
422
  post: operations["acceptMonitorBaseline"];
421
423
  delete?: never;
@@ -1311,6 +1313,28 @@ export interface components {
1311
1313
  max: number;
1312
1314
  window_seconds: number;
1313
1315
  };
1316
+ /** @description A WatchFor Grade: the same A+ to F letter the dashboard shows for this check, from the same versioned rubric (https://watchfor.io/grades). Every grade starts at A+ and each finding can only cap it; `capped_by` lists the findings that hold it down, worst first. letter null = not graded (we could not measure — never a verdict on the target), with the reason in not_graded_reason. */
1317
+ WatchForGrade: {
1318
+ /** @enum {string|null} */
1319
+ letter: "A+" | "A" | "B" | "C" | "D" | "F" | null;
1320
+ /** @example Needs attention */
1321
+ label: string;
1322
+ /** @description Versioned rubric id, e.g. headers-2026.10. Changes whenever a rule changes. */
1323
+ rubric: string;
1324
+ /** @description Composite grades only (smart-audit, cdn-check): the weighted score behind the letter. */
1325
+ score?: number;
1326
+ /** @description Set when the grade covers less than everything, e.g. auth-discovery for an MCP server that requires sign-in. */
1327
+ scope?: string;
1328
+ capped_by: {
1329
+ /** @description Stable finding id, e.g. csp.missing. */
1330
+ id: string;
1331
+ title: string;
1332
+ /** @description The highest grade this finding allows; null = it costs points in a composite score instead. */
1333
+ cap: string | null;
1334
+ fix: string | null;
1335
+ }[];
1336
+ not_graded_reason?: string;
1337
+ };
1314
1338
  DiagnosticCatalogEntry: {
1315
1339
  /** @enum {string} */
1316
1340
  slug:
@@ -1318,6 +1342,7 @@ export interface components {
1318
1342
  | "cwv-check"
1319
1343
  | "dns-lookup"
1320
1344
  | "dns-propagation"
1345
+ | "dns-health"
1321
1346
  | "whois"
1322
1347
  | "ping"
1323
1348
  | "traceroute"
@@ -1334,6 +1359,7 @@ export interface components {
1334
1359
  | "redirect-chain"
1335
1360
  | "websocket-test"
1336
1361
  | "smtp-test"
1362
+ | "mail-server-check"
1337
1363
  | "ntp-test"
1338
1364
  | "email-health";
1339
1365
  label: string;
@@ -1347,6 +1373,8 @@ export interface components {
1347
1373
  composite: boolean;
1348
1374
  /** @description false = the answer is the same everywhere, so location_id is ignored. */
1349
1375
  location_aware: boolean;
1376
+ /** @description true = a run returns a WatchFor Grade in `grade`. */
1377
+ graded: boolean;
1350
1378
  target: {
1351
1379
  field: string;
1352
1380
  description: string;
@@ -1406,6 +1434,7 @@ export interface components {
1406
1434
  | "cwv-check"
1407
1435
  | "dns-lookup"
1408
1436
  | "dns-propagation"
1437
+ | "dns-health"
1409
1438
  | "whois"
1410
1439
  | "ping"
1411
1440
  | "traceroute"
@@ -1422,6 +1451,7 @@ export interface components {
1422
1451
  | "redirect-chain"
1423
1452
  | "websocket-test"
1424
1453
  | "smtp-test"
1454
+ | "mail-server-check"
1425
1455
  | "ntp-test"
1426
1456
  | "email-health";
1427
1457
  target: string;
@@ -1434,6 +1464,8 @@ export interface components {
1434
1464
  timed_out?: boolean;
1435
1465
  /** @description The probe's raw result — shape depends on the check (response, metrics, error). Composite checks return their aggregate here. */
1436
1466
  result: unknown;
1467
+ /** @description Graded checks only (tls-grade, http-headers, cwv-check, mcp-check, email-health with variant all, mail-server-check, cdn-check, smart-audit, dns-health): the dashboard's letter with the findings that set it. Omitted for other checks. */
1468
+ grade?: components["schemas"]["WatchForGrade"];
1437
1469
  /** @description Runs left for this check in the current window; null = unlimited. Pace long investigations by this. */
1438
1470
  remaining: number | null;
1439
1471
  allowance: components["schemas"]["DiagnosticAllowance"];
@@ -1450,6 +1482,7 @@ export interface components {
1450
1482
  | "cwv-check"
1451
1483
  | "dns-lookup"
1452
1484
  | "dns-propagation"
1485
+ | "dns-health"
1453
1486
  | "whois"
1454
1487
  | "ping"
1455
1488
  | "traceroute"
@@ -1466,6 +1499,7 @@ export interface components {
1466
1499
  | "redirect-chain"
1467
1500
  | "websocket-test"
1468
1501
  | "smtp-test"
1502
+ | "mail-server-check"
1469
1503
  | "ntp-test"
1470
1504
  | "email-health";
1471
1505
  label: string;
@@ -1482,6 +1516,7 @@ export interface components {
1482
1516
  success?: boolean | null;
1483
1517
  error?: string | null;
1484
1518
  result?: unknown;
1519
+ grade?: components["schemas"]["WatchForGrade"];
1485
1520
  };
1486
1521
  /** @description One machine-readable observation. `code` is stable and safe to branch on; `detail` is a sentence safe to relay verbatim. */
1487
1522
  DiagnosticFinding: {
@@ -1518,6 +1553,10 @@ export interface components {
1518
1553
  findings: components["schemas"]["DiagnosticFinding"][];
1519
1554
  };
1520
1555
  checks: components["schemas"]["DiagnosticCheck"][];
1556
+ /** @description WatchFor Grades of the graded checks in the bundle, keyed by check slug (tls-grade, http-headers). A skipped check has none. */
1557
+ grades: {
1558
+ [key: string]: components["schemas"]["WatchForGrade"];
1559
+ };
1521
1560
  locations_used: unknown[];
1522
1561
  location_select?: boolean;
1523
1562
  locations_available?: number;
@@ -2107,10 +2146,37 @@ export interface components {
2107
2146
  }[];
2108
2147
  trusted_origins?: string[];
2109
2148
  text_change_threshold?: number;
2149
+ /** @description The latest fresh accept (`POST …/baseline?fresh=true`), kept for 24 hours; null when there was none. Poll it after a 202: `pending` until the check lands, then `accepted` (with what was accepted), `expired` (no check arrived within 5 minutes — nothing was accepted) or `failed`. */
2150
+ fresh_accept?: {
2151
+ /** @enum {string} */
2152
+ status: "pending" | "accepted" | "expired" | "failed";
2153
+ /** Format: date-time */
2154
+ requested_at: string;
2155
+ /**
2156
+ * Format: date-time
2157
+ * @description A pending accept that has not finished by now is expired
2158
+ */
2159
+ expires_at: string;
2160
+ /** Format: date-time */
2161
+ finished_at?: string | null;
2162
+ /** @description The pages asked for; null = all */
2163
+ pages?: string[] | null;
2164
+ accepted?: string[] | null;
2165
+ skipped?:
2166
+ | {
2167
+ url: string;
2168
+ reason: string;
2169
+ }[]
2170
+ | null;
2171
+ incidents_resolved?: number[] | null;
2172
+ message?: string | null;
2173
+ } | null;
2110
2174
  };
2111
2175
  IntegrityBaselineAcceptRequest: {
2112
2176
  /** @description Accept only these watched pages; omit for all */
2113
2177
  pages?: string[];
2178
+ /** @description Same as the `fresh` query parameter: check the pages first and accept what that check saw */
2179
+ fresh?: boolean;
2114
2180
  };
2115
2181
  IntegrityBaselineAccept: {
2116
2182
  /** @constant */
@@ -2124,8 +2190,34 @@ export interface components {
2124
2190
  }[];
2125
2191
  /** Format: date-time */
2126
2192
  captured_at?: string | null;
2193
+ /** @constant */
2194
+ status?: "accepted";
2127
2195
  /** @description A check of the pages was started right after the accept, so open findings close on it within a minute or two instead of at the next scheduled check */
2128
2196
  check_requested?: boolean;
2197
+ /** @description Open integrity incidents of the monitor resolved by this accept — nothing was left to fix (every watched page matches its baseline in the newest check). Empty when some page still differs or could not be fetched; those close on clean checks as usual */
2198
+ incidents_resolved?: number[];
2199
+ /**
2200
+ * Format: date-time
2201
+ * @description Fresh accepts: when the check was requested
2202
+ */
2203
+ requested_at?: string;
2204
+ };
2205
+ /** @description A fresh accept whose check has not landed yet — it finishes in the background; `GET /v1/monitors/{id}/baseline` → `fresh_accept` shows the outcome */
2206
+ IntegrityBaselineAcceptPending: {
2207
+ /** @constant */
2208
+ object: "integrity_baseline_accept";
2209
+ /** Format: uuid */
2210
+ monitor_id: string;
2211
+ /** @constant */
2212
+ status: "pending";
2213
+ /** Format: date-time */
2214
+ requested_at: string;
2215
+ /**
2216
+ * Format: date-time
2217
+ * @description The accept gives up (nothing accepted) if no check has landed by then
2218
+ */
2219
+ expires_at: string;
2220
+ message?: string;
2129
2221
  };
2130
2222
  MonitorReset: {
2131
2223
  /** @constant */
@@ -3151,6 +3243,16 @@ export interface components {
3151
3243
  */
3152
3244
  resolverMode: "fixed" | "random";
3153
3245
  };
3246
+ /** @description Options for the `dns-health` diagnostic. Is this domain's DNS set up well — at least two nameservers on separate networks, no lame delegation, parent and zone agreeing, SOA serials in sync, DNSSEC valid, CAA published — as an A+…F grade? Add propagation:true to also grade whether every probe location sees the same answer. */
3247
+ DiagnosticOptionsDnsHealth: {
3248
+ /** @default false */
3249
+ propagation: boolean;
3250
+ /**
3251
+ * @default A
3252
+ * @enum {string}
3253
+ */
3254
+ recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS";
3255
+ };
3154
3256
  /** @description Options for the `whois` diagnostic. Who owns this domain, when does it expire, which registrar and nameservers does the registry list (live RDAP, cache bypassed)? */
3155
3257
  DiagnosticOptionsWhois: Record<string, never>;
3156
3258
  /** @description Options for the `ping` diagnostic. Is this host reachable by ICMP from a given location, and what is the round-trip time and packet loss? */
@@ -3237,6 +3339,11 @@ export interface components {
3237
3339
  /** @default true */
3238
3340
  checkPtr: boolean;
3239
3341
  };
3342
+ /** @description Options for the `mail-server-check` diagnostic. How secure are this domain's mail servers — an A+…F grade per service (inbound MX, SMTP submission, IMAP, POP3) for TLS, certificates, STARTTLS, plain-text login, open relay, MTA-STS, TLS-RPT and DANE, checked from three regions? */
3343
+ DiagnosticOptionsMailServerCheck: {
3344
+ /** @description Services to check: smtp (inbound MX on 25 + submission on 587/465), imap, pop3. Omit for Auto: every service, and for a single host only the ones that answer are graded. */
3345
+ services?: ("smtp" | "imap" | "pop3")[];
3346
+ };
3240
3347
  /** @description Options for the `ntp-test` diagnostic. Does this NTP server answer, and what stratum, clock offset, round-trip delay and leap indicator does it report per sample? */
3241
3348
  DiagnosticOptionsNtpTest: {
3242
3349
  /** @default 123 */
@@ -3611,6 +3718,7 @@ export interface operations {
3611
3718
  | "cwv-check"
3612
3719
  | "dns-lookup"
3613
3720
  | "dns-propagation"
3721
+ | "dns-health"
3614
3722
  | "whois"
3615
3723
  | "ping"
3616
3724
  | "traceroute"
@@ -3627,6 +3735,7 @@ export interface operations {
3627
3735
  | "redirect-chain"
3628
3736
  | "websocket-test"
3629
3737
  | "smtp-test"
3738
+ | "mail-server-check"
3630
3739
  | "ntp-test"
3631
3740
  | "email-health";
3632
3741
  };
@@ -4185,7 +4294,10 @@ export interface operations {
4185
4294
  };
4186
4295
  acceptMonitorBaseline: {
4187
4296
  parameters: {
4188
- query?: never;
4297
+ query?: {
4298
+ /** @description Check the pages first, wait for that check (up to ~85 s) and accept what it saw — the deploy-hook mode. 202 `pending` when the check takes longer. */
4299
+ fresh?: boolean;
4300
+ };
4189
4301
  header?: {
4190
4302
  /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
4191
4303
  "Idempotency-Key"?: string;
@@ -4211,6 +4323,15 @@ export interface operations {
4211
4323
  "application/json": components["schemas"]["IntegrityBaselineAccept"];
4212
4324
  };
4213
4325
  };
4326
+ /** @description Fresh accept: the check is still running — the accept finishes in the background */
4327
+ 202: {
4328
+ headers: {
4329
+ [name: string]: unknown;
4330
+ };
4331
+ content: {
4332
+ "application/json": components["schemas"]["IntegrityBaselineAcceptPending"];
4333
+ };
4334
+ };
4214
4335
  /** @description Error */
4215
4336
  default: {
4216
4337
  headers: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.12.1",
3
+ "version": "0.14.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",