watchfor 0.13.0 → 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 23 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"
@@ -1348,6 +1373,8 @@ export interface components {
1348
1373
  composite: boolean;
1349
1374
  /** @description false = the answer is the same everywhere, so location_id is ignored. */
1350
1375
  location_aware: boolean;
1376
+ /** @description true = a run returns a WatchFor Grade in `grade`. */
1377
+ graded: boolean;
1351
1378
  target: {
1352
1379
  field: string;
1353
1380
  description: string;
@@ -1407,6 +1434,7 @@ export interface components {
1407
1434
  | "cwv-check"
1408
1435
  | "dns-lookup"
1409
1436
  | "dns-propagation"
1437
+ | "dns-health"
1410
1438
  | "whois"
1411
1439
  | "ping"
1412
1440
  | "traceroute"
@@ -1436,6 +1464,8 @@ export interface components {
1436
1464
  timed_out?: boolean;
1437
1465
  /** @description The probe's raw result — shape depends on the check (response, metrics, error). Composite checks return their aggregate here. */
1438
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"];
1439
1469
  /** @description Runs left for this check in the current window; null = unlimited. Pace long investigations by this. */
1440
1470
  remaining: number | null;
1441
1471
  allowance: components["schemas"]["DiagnosticAllowance"];
@@ -1452,6 +1482,7 @@ export interface components {
1452
1482
  | "cwv-check"
1453
1483
  | "dns-lookup"
1454
1484
  | "dns-propagation"
1485
+ | "dns-health"
1455
1486
  | "whois"
1456
1487
  | "ping"
1457
1488
  | "traceroute"
@@ -1485,6 +1516,7 @@ export interface components {
1485
1516
  success?: boolean | null;
1486
1517
  error?: string | null;
1487
1518
  result?: unknown;
1519
+ grade?: components["schemas"]["WatchForGrade"];
1488
1520
  };
1489
1521
  /** @description One machine-readable observation. `code` is stable and safe to branch on; `detail` is a sentence safe to relay verbatim. */
1490
1522
  DiagnosticFinding: {
@@ -1521,6 +1553,10 @@ export interface components {
1521
1553
  findings: components["schemas"]["DiagnosticFinding"][];
1522
1554
  };
1523
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
+ };
1524
1560
  locations_used: unknown[];
1525
1561
  location_select?: boolean;
1526
1562
  locations_available?: number;
@@ -2110,10 +2146,37 @@ export interface components {
2110
2146
  }[];
2111
2147
  trusted_origins?: string[];
2112
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;
2113
2174
  };
2114
2175
  IntegrityBaselineAcceptRequest: {
2115
2176
  /** @description Accept only these watched pages; omit for all */
2116
2177
  pages?: string[];
2178
+ /** @description Same as the `fresh` query parameter: check the pages first and accept what that check saw */
2179
+ fresh?: boolean;
2117
2180
  };
2118
2181
  IntegrityBaselineAccept: {
2119
2182
  /** @constant */
@@ -2127,8 +2190,34 @@ export interface components {
2127
2190
  }[];
2128
2191
  /** Format: date-time */
2129
2192
  captured_at?: string | null;
2193
+ /** @constant */
2194
+ status?: "accepted";
2130
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 */
2131
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;
2132
2221
  };
2133
2222
  MonitorReset: {
2134
2223
  /** @constant */
@@ -3154,6 +3243,16 @@ export interface components {
3154
3243
  */
3155
3244
  resolverMode: "fixed" | "random";
3156
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
+ };
3157
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)? */
3158
3257
  DiagnosticOptionsWhois: Record<string, never>;
3159
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? */
@@ -3619,6 +3718,7 @@ export interface operations {
3619
3718
  | "cwv-check"
3620
3719
  | "dns-lookup"
3621
3720
  | "dns-propagation"
3721
+ | "dns-health"
3622
3722
  | "whois"
3623
3723
  | "ping"
3624
3724
  | "traceroute"
@@ -4194,7 +4294,10 @@ export interface operations {
4194
4294
  };
4195
4295
  acceptMonitorBaseline: {
4196
4296
  parameters: {
4197
- 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
+ };
4198
4301
  header?: {
4199
4302
  /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
4200
4303
  "Idempotency-Key"?: string;
@@ -4220,6 +4323,15 @@ export interface operations {
4220
4323
  "application/json": components["schemas"]["IntegrityBaselineAccept"];
4221
4324
  };
4222
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
+ };
4223
4335
  /** @description Error */
4224
4336
  default: {
4225
4337
  headers: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.13.0",
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",