watchfor 0.17.1 → 0.18.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
@@ -48,6 +48,11 @@ await wf.monitors.reset(monitor.id!);
48
48
  // Page integrity: after a deploy, check the pages and accept what that check saw.
49
49
  await wf.monitors.acceptBaseline(integrityMonitorId, { fresh: true });
50
50
 
51
+ // MCP servers: before a release, keep tool drift quiet for 30 minutes (downtime still pages);
52
+ // a drift incident the user confirms was theirs is accepted as an expected change.
53
+ await wf.monitors.setExpectedChangeWindow(mcpMonitorId, { window: 30, note: "v2.4 release" });
54
+ await wf.incidents.acceptExpectedChange(19352, { note: "New search tool shipped in v2.4" });
55
+
51
56
  // Browser checks: try a Playwright script once (nothing saved), then read the result.
52
57
  const { id } = await wf.playwright.testRun({ script, target: "https://shop.example.com" });
53
58
  const run = await wf.playwright.getTestRun(id); // status: queued | running | done | error
@@ -102,7 +107,8 @@ const dns = await wf.diagnostics.run("dns-lookup", {
102
107
  target: "example.com",
103
108
  options: { recordType: "A", resolver: "8.8.8.8" },
104
109
  });
105
- // A closed port / NXDOMAIN / failed handshake does NOT throw:
110
+ // A closed port, NXDOMAIN, expired certificate or unresolvable host does NOT
111
+ // throw — `success` is false and `error` says why (`result` keeps the raw answer):
106
112
  if (!dns.success) console.log("finding:", dns.error);
107
113
  console.log("runs left this hour:", dns.remaining);
108
114
 
@@ -133,7 +139,13 @@ Toolbox. Details: https://watchfor.io/docs/api/diagnostics
133
139
 
134
140
  - Fully typed from the [OpenAPI spec](https://watchfor.io/openapi.json)
135
141
  - Zero runtime dependencies (uses global `fetch`, Node ≥ 18)
136
- - `WatchForError` carries `status`, `code` and `retryAfterSeconds`
142
+ - `WatchForError` carries `status`, `code` and `retryAfterSeconds`; a
143
+ non-JSON answer (an HTML page from a wrong base URL or a proxy) is a
144
+ short `http_error` / `invalid_response` pointing at the base URL
145
+ - `baseUrl` (and the CLI's `WATCHFOR_BASE_URL`) takes the origin
146
+ (`https://watchfor.io`) or the full base (`https://watchfor.io/api/v1`) —
147
+ the same value works for the Python and Ruby SDKs
148
+ - CLI: `watchfor --version`; `report --period` accepts only `7d` or `30d`
137
149
  - Pass an idempotency key as the second argument of any `create` call for safe retries
138
150
 
139
151
  ## Organizations
@@ -199,5 +211,5 @@ WATCHFOR_ORGANIZATION=<organization-id> npx watchfor summary
199
211
  ## Links
200
212
 
201
213
  - API docs: https://watchfor.io/docs/api
202
- - MCP server for AI agents (61 tools): https://watchfor.io/docs/api/mcp
214
+ - MCP server for AI agents (63 tools): https://watchfor.io/docs/api/mcp
203
215
  - Create an API key: dashboard → Settings → API keys (`read` or `read+write` scope)
package/dist/cli.js CHANGED
@@ -1,5 +1,9 @@
1
1
  #!/usr/bin/env node
2
+ import { createRequire } from "node:module";
2
3
  import { WatchFor, WatchForError } from "./client.js";
4
+ /** The package version (dist/cli.js and src/cli.ts both sit next to
5
+ * ../package.json, which npm always ships). */
6
+ const VERSION = createRequire(import.meta.url)("../package.json").version;
3
7
  /**
4
8
  * `watchfor` CLI — quick terminal access to the monitoring API.
5
9
  *
@@ -29,6 +33,7 @@ Commands:
29
33
  watchfor metrics [--tag t] [--type t]
30
34
  Prometheus text format (Pro plan and above)
31
35
  watchfor help
36
+ watchfor --version Print the CLI/SDK version
32
37
 
33
38
  Global options:
34
39
  --organization <id> Organization to act on (X-WatchFor-Organization). OAuth
@@ -38,7 +43,7 @@ Global options:
38
43
  Environment:
39
44
  WATCHFOR_API_KEY API key (dashboard → Settings → API keys) or an OAuth access token
40
45
  WATCHFOR_ORGANIZATION Default for --organization
41
- WATCHFOR_BASE_URL Override (default https://watchfor.io)
46
+ WATCHFOR_BASE_URL Override (default https://watchfor.io; the origin or …/api/v1)
42
47
  `;
43
48
  function flag(args, name) {
44
49
  const i = args.indexOf(`--${name}`);
@@ -73,6 +78,10 @@ async function main() {
73
78
  process.stdout.write(HELP);
74
79
  return 0;
75
80
  }
81
+ if (cmd === "--version" || cmd === "-v" || cmd === "version") {
82
+ console.log(`watchfor ${VERSION}`);
83
+ return 0;
84
+ }
76
85
  const apiKey = process.env.WATCHFOR_API_KEY;
77
86
  if (!apiKey) {
78
87
  console.error("WATCHFOR_API_KEY is not set. Create a key in the dashboard (Settings → API keys).");
@@ -129,10 +138,14 @@ async function main() {
129
138
  return 0;
130
139
  }
131
140
  case "report": {
132
- const idx = args.indexOf("--period");
133
- const period = idx !== -1 && (args[idx + 1] === "30d" || args[idx + 1] === "7d")
134
- ? args[idx + 1]
135
- : "7d";
141
+ // An invalid --period is an error, never silently replaced (same
142
+ // as the Python and Ruby CLIs).
143
+ const given = flag(args, "period");
144
+ if (given !== undefined && given !== "7d" && given !== "30d") {
145
+ console.error(`--period must be 7d or 30d (got "${given === "true" ? "" : given}")`);
146
+ return 2;
147
+ }
148
+ const period = (given ?? "7d");
136
149
  const r = (await wf.report({ period }));
137
150
  const sm = r.summary ?? {};
138
151
  const up = sm.uptimePct?.current;
package/dist/client.d.ts CHANGED
@@ -28,6 +28,12 @@ export type IntegrityBaseline = components["schemas"]["IntegrityBaseline"];
28
28
  export type IntegrityBaselineAccept = components["schemas"]["IntegrityBaselineAccept"];
29
29
  /** A fresh accept whose check has not landed yet (HTTP 202). */
30
30
  export type IntegrityBaselineAcceptPending = components["schemas"]["IntegrityBaselineAcceptPending"];
31
+ /** `monitors.setExpectedChangeWindow()` — a release marker on an MCP
32
+ * monitor: drift does not page until `ends_at`. */
33
+ export type ExpectedChangeWindow = components["schemas"]["ExpectedChangeWindow"];
34
+ /** `incidents.acceptExpectedChange()` — a drift incident recorded as an
35
+ * intended change. */
36
+ export type ExpectedChangeAccept = components["schemas"]["ExpectedChangeAccept"];
31
37
  export type PlaywrightTestRunAccepted = components["schemas"]["PlaywrightTestRunAccepted"];
32
38
  export type PlaywrightTestRun = components["schemas"]["PlaywrightTestRun"];
33
39
  export type PlaywrightRun = components["schemas"]["PlaywrightRun"];
@@ -125,6 +131,13 @@ export interface List<T> {
125
131
  next_cursor?: string | null;
126
132
  total?: number;
127
133
  }
134
+ /**
135
+ * The API origin, whichever form was given: `https://watchfor.io`,
136
+ * `https://watchfor.io/`, `https://watchfor.io/api/v1` and
137
+ * `https://watchfor.io/api/v1/` all normalise to `https://watchfor.io`
138
+ * (the client appends `/api/v1`). Exported for tests.
139
+ */
140
+ export declare function normalizeBaseUrl(baseUrl?: string): string;
128
141
  export declare class WatchForError extends Error {
129
142
  readonly status: number;
130
143
  readonly code: string;
@@ -143,7 +156,12 @@ export interface WatchForOptions {
143
156
  * or set that same id — any other id is 403 `forbidden`.
144
157
  */
145
158
  organization?: string;
146
- /** Override for self-hosted / testing. Default https://watchfor.io */
159
+ /**
160
+ * Override for self-hosted / testing. Default https://watchfor.io —
161
+ * the origin or the full API base: `https://watchfor.io` and
162
+ * `https://watchfor.io/api/v1` are the same (as in the Python and Ruby
163
+ * SDKs).
164
+ */
147
165
  baseUrl?: string;
148
166
  fetch?: typeof fetch;
149
167
  }
@@ -305,6 +323,18 @@ export declare class WatchFor {
305
323
  pages?: string[];
306
324
  fresh?: boolean;
307
325
  }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept | IntegrityBaselineAcceptPending>;
326
+ /** MCP monitors: release marker — call it from a deploy pipeline
327
+ * before the rollout. For `window` minutes (1–60, default 15) the
328
+ * monitor's drift rules (Tool Inventory Changed) are silenced — only
329
+ * those, downtime still pages — and drift incidents opened inside
330
+ * the window resolve within a minute. Markers stack; 12 per hour per
331
+ * monitor (429). Page integrity monitors → 400 (use
332
+ * `acceptBaseline(id, { fresh: true })` after the deploy); no enabled
333
+ * drift rule → 409. */
334
+ setExpectedChangeWindow: (id: string, opts?: {
335
+ window?: number;
336
+ note?: string;
337
+ }, idempotencyKey?: string) => Promise<ExpectedChangeWindow>;
308
338
  /** Browser checks: runs, newest first (`status` failed | flaky). */
309
339
  runs: (id: string, params?: {
310
340
  status?: "all" | "failed" | "flaky";
@@ -405,6 +435,16 @@ export declare class WatchFor {
405
435
  * it (marking again returns the same one); delete that window to
406
436
  * undo. */
407
437
  markMaintenance: (id: number, idempotencyKey?: string) => Promise<MaintenanceMarking>;
438
+ /** Drift incidents only (an MCP monitor's Tool Inventory Changed;
439
+ * others → 400): mark the change as intended. An open incident is
440
+ * resolved asynchronously (`resolve_requested`; poll `get()`), and
441
+ * the accept is recorded on the incident and drift timelines and in
442
+ * the Activity log. Accepting again returns the first accept with
443
+ * `already_accepted: true`. `note` (≤ 500 chars) says why. Only call
444
+ * it when the user confirms the change was theirs. */
445
+ acceptExpectedChange: (id: number, body?: {
446
+ note?: string;
447
+ }, idempotencyKey?: string) => Promise<ExpectedChangeAccept>;
408
448
  /** The incident's post-mortem. 404 when it has none yet —
409
449
  * `updatePostmortem` creates it. */
410
450
  getPostmortem: (id: number) => Promise<Postmortem>;
package/dist/client.js CHANGED
@@ -13,6 +13,20 @@
13
13
  */
14
14
  /** The request header that selects the organization an OAuth token acts on. */
15
15
  export const ORGANIZATION_HEADER = "X-WatchFor-Organization";
16
+ /**
17
+ * The API origin, whichever form was given: `https://watchfor.io`,
18
+ * `https://watchfor.io/`, `https://watchfor.io/api/v1` and
19
+ * `https://watchfor.io/api/v1/` all normalise to `https://watchfor.io`
20
+ * (the client appends `/api/v1`). Exported for tests.
21
+ */
22
+ export function normalizeBaseUrl(baseUrl) {
23
+ const trimmed = (baseUrl?.trim() || "https://watchfor.io").replace(/\/+$/, "");
24
+ return trimmed.replace(/\/api\/v1$/i, "");
25
+ }
26
+ /** A short, actionable message for a response that isn't API JSON. */
27
+ function notApiMessage(status, url) {
28
+ return `HTTP ${status} from ${url} — the response is not WatchFor API JSON. Is the base URL right? Use the origin, e.g. https://watchfor.io (WATCHFOR_BASE_URL).`;
29
+ }
16
30
  export class WatchForError extends Error {
17
31
  status;
18
32
  code;
@@ -39,7 +53,7 @@ export class WatchFor {
39
53
  this.options = opts;
40
54
  this.apiKey = opts.apiKey;
41
55
  this.organization = opts.organization?.trim() || undefined;
42
- this.base = (opts.baseUrl ?? "https://watchfor.io").replace(/\/$/, "");
56
+ this.base = normalizeBaseUrl(opts.baseUrl);
43
57
  this.fetchImpl = opts.fetch ?? fetch;
44
58
  }
45
59
  /**
@@ -78,18 +92,29 @@ export class WatchFor {
78
92
  return undefined;
79
93
  if (opts.text && res.ok)
80
94
  return (await res.text());
95
+ const raw = await res.text();
81
96
  let json = null;
82
- try {
83
- json = await res.json();
84
- }
85
- catch {
86
- /* non-JSON body */
97
+ let parsed = raw.trim() === "";
98
+ if (!parsed) {
99
+ try {
100
+ json = JSON.parse(raw);
101
+ parsed = true;
102
+ }
103
+ catch {
104
+ /* non-JSON body — an HTML page from a wrong base URL or a proxy */
105
+ }
87
106
  }
88
107
  if (!res.ok) {
89
108
  const err = json
90
109
  ?.error;
91
110
  const retry = res.headers.get("Retry-After");
92
- throw new WatchForError(res.status, err?.code ?? "http_error", err?.message ?? `HTTP ${res.status}`, retry ? Number(retry) : undefined);
111
+ throw new WatchForError(res.status, err?.code ?? "http_error", err?.message ??
112
+ (parsed
113
+ ? `HTTP ${res.status}`
114
+ : notApiMessage(res.status, url.toString())), retry ? Number(retry) : undefined);
115
+ }
116
+ if (!parsed) {
117
+ throw new WatchForError(res.status, "invalid_response", notApiMessage(res.status, url.toString()));
93
118
  }
94
119
  return json;
95
120
  }
@@ -243,6 +268,19 @@ export class WatchFor {
243
268
  body: body ?? {},
244
269
  idempotencyKey,
245
270
  }),
271
+ /** MCP monitors: release marker — call it from a deploy pipeline
272
+ * before the rollout. For `window` minutes (1–60, default 15) the
273
+ * monitor's drift rules (Tool Inventory Changed) are silenced — only
274
+ * those, downtime still pages — and drift incidents opened inside
275
+ * the window resolve within a minute. Markers stack; 12 per hour per
276
+ * monitor (429). Page integrity monitors → 400 (use
277
+ * `acceptBaseline(id, { fresh: true })` after the deploy); no enabled
278
+ * drift rule → 409. */
279
+ setExpectedChangeWindow: (id, opts = {}, idempotencyKey) => this.request("POST", `/monitors/${id}/expected-change`, {
280
+ query: { window: opts.window },
281
+ body: opts.note === undefined ? {} : { note: opts.note },
282
+ idempotencyKey,
283
+ }),
246
284
  /** Browser checks: runs, newest first (`status` failed | flaky). */
247
285
  runs: (id, params = {}) => this.request("GET", `/monitors/${id}/runs`, { query: params }),
248
286
  /** Browser checks: one run — steps, errors, Web Vitals, screenshot
@@ -318,6 +356,17 @@ export class WatchFor {
318
356
  markMaintenance: (id, idempotencyKey) => this.request("POST", `/incidents/${id}/mark-maintenance`, {
319
357
  idempotencyKey,
320
358
  }),
359
+ /** Drift incidents only (an MCP monitor's Tool Inventory Changed;
360
+ * others → 400): mark the change as intended. An open incident is
361
+ * resolved asynchronously (`resolve_requested`; poll `get()`), and
362
+ * the accept is recorded on the incident and drift timelines and in
363
+ * the Activity log. Accepting again returns the first accept with
364
+ * `already_accepted: true`. `note` (≤ 500 chars) says why. Only call
365
+ * it when the user confirms the change was theirs. */
366
+ acceptExpectedChange: (id, body, idempotencyKey) => this.request("POST", `/incidents/${id}/expected-change`, {
367
+ body: body ?? {},
368
+ idempotencyKey,
369
+ }),
321
370
  /** The incident's post-mortem. 404 when it has none yet —
322
371
  * `updatePostmortem` creates it. */
323
372
  getPostmortem: (id) => this.request("GET", `/incidents/${id}/postmortem`),
package/dist/index.d.ts CHANGED
@@ -1 +1 @@
1
- export { type ActivityEvent, type AlertingState, type AlertRule, type Announcement, type AnnouncementCreate, type AnnouncementUpdate, type ApiErrorBody, type BatchOperation, type BatchResult, type BulkResult, 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 MaintenanceMarking, type MaintenanceWindow, type Me, type Monitor, type MonitorDetail, type MonitorReset, type Notification, ORGANIZATION_HEADER, type Organization, type Plan, type PlaywrightRun, type PlaywrightRunSummary, type PlaywrightTestRun, type PlaywrightTestRunAccepted, type PlaywrightTestRunRequest, type Postmortem, type PostmortemUpdate, type ReportFilters, type ResponseTimeBucket, type ScriptVersion, type ScriptVersionSummary, type StatusPage, type StatusPageComponentCreate, type StatusPageCreate, type StatusPageUpdate, type Summary, type Uptime, type Variable, type VariableDeleted, WatchFor, WatchForError, type WatchForGrade, type WatchForOptions, } from "./client.js";
1
+ export { type ActivityEvent, type AlertingState, type AlertRule, type Announcement, type AnnouncementCreate, type AnnouncementUpdate, type ApiErrorBody, type BatchOperation, type BatchResult, type BulkResult, type Check, type CheckList, type CheckNowAck, type Contact, type ContactGroup, type Deleted, type DiagnosticCatalog, type DiagnosticCatalogEntry, type DiagnosticReport, type DiagnosticRun, type DiagnosticSlug, type ExpectedChangeAccept, type ExpectedChangeWindow, type Incident, type IncidentStats, type IntegrityBaseline, type IntegrityBaselineAccept, type IntegrityBaselineAcceptPending, type List, type MaintenanceMarking, type MaintenanceWindow, type Me, type Monitor, type MonitorDetail, type MonitorReset, type Notification, ORGANIZATION_HEADER, type Organization, type Plan, type PlaywrightRun, type PlaywrightRunSummary, type PlaywrightTestRun, type PlaywrightTestRunAccepted, type PlaywrightTestRunRequest, type Postmortem, type PostmortemUpdate, type ReportFilters, type ResponseTimeBucket, type ScriptVersion, type ScriptVersionSummary, type StatusPage, type StatusPageComponentCreate, type StatusPageCreate, type StatusPageUpdate, type Summary, type Uptime, type Variable, type VariableDeleted, WatchFor, WatchForError, type WatchForGrade, type WatchForOptions, } from "./client.js";
package/dist/schema.d.ts CHANGED
@@ -398,7 +398,10 @@ export interface paths {
398
398
  };
399
399
  get?: never;
400
400
  put?: never;
401
- /** Dispatch one immediate check (plan-budgeted per hour) */
401
+ /**
402
+ * Dispatch one immediate check (plan-budgeted per hour)
403
+ * @description Asynchronous: 202, and the result lands in GET /monitors/{id}/checks within the probe timeout. Budgeted per monitor by the plan's check-now allowance (shared with the dashboard). Over that budget → 429 `rate_limited` whose `error.next_allowed_at` (and `Retry-After`) say when the next check-now is allowed — distinct from the API rate limit the X-RateLimit-* headers describe. Send an `Idempotency-Key` to retry safely: a retry with the same key replays the original 202 (with `Idempotency-Replay: true`) instead of spending, or being refused by, the hourly budget.
404
+ */
402
405
  post: operations["runMonitorCheckNow"];
403
406
  delete?: never;
404
407
  options?: never;
@@ -452,6 +455,26 @@ export interface paths {
452
455
  patch?: never;
453
456
  trace?: never;
454
457
  };
458
+ "/monitors/{id}/expected-change": {
459
+ parameters: {
460
+ query?: never;
461
+ header?: never;
462
+ path?: never;
463
+ cookie?: never;
464
+ };
465
+ get?: never;
466
+ put?: never;
467
+ /**
468
+ * Release marker — drift on this monitor doesn't page for the next N minutes (call before a deploy)
469
+ * @description MCP monitors (drift = the Tool Inventory Changed rule). Call it from a deploy pipeline before the rollout starts: for the window, the monitor's drift rules are silenced — only those, so downtime and every other rule still page — the drift incidents opened inside the window are resolved within a minute (timeline: "Resolved — expected change (release marker)"), and the drift timeline marks those changes "Expected — release marker". The dashboard shows "Expected change window until HH:MM" on the monitor. Markers stack (each its own window). Pick a window longer than the rollout plus one check interval: drift first seen after it pages as usual. 12 per hour per monitor (429 + `Retry-After`). Page integrity monitors → 400 (they use `POST /v1/monitors/{id}/baseline?fresh=true` after the deploy); no enabled drift rule → 409. Optional body: `{"note": "v2.4 release"}` (and `window`, when not in the query).
470
+ */
471
+ post: operations["setMonitorExpectedChange"];
472
+ delete?: never;
473
+ options?: never;
474
+ head?: never;
475
+ patch?: never;
476
+ trace?: never;
477
+ };
455
478
  "/monitors/{id}/uptime": {
456
479
  parameters: {
457
480
  query?: never;
@@ -631,6 +654,26 @@ export interface paths {
631
654
  patch?: never;
632
655
  trace?: never;
633
656
  };
657
+ "/incidents/{id}/expected-change": {
658
+ parameters: {
659
+ query?: never;
660
+ header?: never;
661
+ path?: never;
662
+ cookie?: never;
663
+ };
664
+ get?: never;
665
+ put?: never;
666
+ /**
667
+ * Mark a drift incident as an expected change — resolves it and records it as intended
668
+ * @description Drift incidents only (an MCP monitor's Tool Inventory Changed; others → 400). The change was intended: an open incident is resolved through the manual-resolve path (asynchronous — 202; the channels get "resolved — accepted as an expected change by <key>"), and the accept is recorded on the incident timeline and the monitor's drift timeline ("Accepted as expected by <key>") and in the Activity log. A drift incident that already auto-resolved is only recorded (200). Accepting again returns the first accept with `already_accepted: true`. Optional body: `{"note": "why"}` (up to 500 characters).
669
+ */
670
+ post: operations["acceptIncidentExpectedChange"];
671
+ delete?: never;
672
+ options?: never;
673
+ head?: never;
674
+ patch?: never;
675
+ trace?: never;
676
+ };
634
677
  "/incidents/{id}/exclude": {
635
678
  parameters: {
636
679
  query?: never;
@@ -1862,6 +1905,10 @@ export interface components {
1862
1905
  object: "playwright_run";
1863
1906
  /** Format: uuid */
1864
1907
  run_id: string;
1908
+ /**
1909
+ * Format: date-time
1910
+ * @description When the run happened — RFC 3339 / ISO 8601 UTC, e.g. 2026-10-17T14:31:29.000Z
1911
+ */
1865
1912
  timestamp?: string;
1866
1913
  location?: string;
1867
1914
  /** @enum {string} */
@@ -1891,6 +1938,10 @@ export interface components {
1891
1938
  object: "playwright_run";
1892
1939
  /** Format: uuid */
1893
1940
  run_id: string;
1941
+ /**
1942
+ * Format: date-time
1943
+ * @description When the run happened — RFC 3339 / ISO 8601 UTC, e.g. 2026-10-17T14:31:29.000Z
1944
+ */
1894
1945
  timestamp: string;
1895
1946
  status: string;
1896
1947
  duration_ms?: number;
@@ -2171,8 +2222,9 @@ export interface components {
2171
2222
  | "ntp-test"
2172
2223
  | "email-health";
2173
2224
  target: string;
2174
- /** @description Whether the check itself succeeded. false is a normal, billable answer (e.g. a closed port, NXDOMAIN, a failed handshake) — read `error` for what happened. */
2225
+ /** @description Whether the check itself succeeded — the finding, not the transport. false is a normal, billable answer: a closed port, an NXDOMAIN, an expired or untrusted certificate, a host that doesn't resolve, a failed handshake, or a target the prober refuses (an internal address). Read `error` for what happened; `result` keeps the probe's raw answer. */
2175
2226
  success: boolean;
2227
+ /** @description Readable reason when `success` is false (e.g. "No records found (NXDOMAIN)", "The certificate … has expired"); null when the check succeeded. */
2176
2228
  error: string | null;
2177
2229
  location: components["schemas"]["DiagnosticLocation"];
2178
2230
  duration_ms: number;
@@ -2219,7 +2271,10 @@ export interface components {
2219
2271
  | "ntp-test"
2220
2272
  | "email-health";
2221
2273
  label: string;
2222
- /** @enum {string} */
2274
+ /**
2275
+ * @description ok = the check ran and answered (read `success` for what it found); failed = it could not run or the probe did not answer; skipped = see `reason`.
2276
+ * @enum {string}
2277
+ */
2223
2278
  status: "ok" | "failed" | "skipped";
2224
2279
  /**
2225
2280
  * @description Why the check was skipped, when it was.
@@ -2229,6 +2284,7 @@ export interface components {
2229
2284
  detail?: string;
2230
2285
  location?: components["schemas"]["DiagnosticLocation"];
2231
2286
  duration_ms?: number | null;
2287
+ /** @description Whether the check succeeded (same meaning as DiagnosticRun.success); null when skipped. */
2232
2288
  success?: boolean | null;
2233
2289
  error?: string | null;
2234
2290
  result?: unknown;
@@ -2398,6 +2454,8 @@ export interface components {
2398
2454
  } | null;
2399
2455
  /** @description PATCH /monitors/{id} responses only: true when the update changed how the check connects (target, port, credentials, TLS, request, record type, script…) and one immediate check was dispatched, so the result reflects the new settings within seconds instead of after a full interval. It does not use the plan's Run-now budget; saves are capped at 10 such checks per monitor per hour. false for alert-rule-only or cosmetic changes and for paused, heartbeat and host monitors. */
2400
2456
  check_queued?: boolean;
2457
+ /** @description POST /monitors and PATCH /monitors/{id} responses only: the `config` keys you sent that this monitor type doesn't use — dropped, not stored ([] when everything was kept). Check it after every write: a misspelt key otherwise leaves the setting unset. Obvious aliases are renamed instead of dropped: `login` / `user` → `username` and `pass` → `password` on imap, pop3, smtp, ftp and sftp; `username` / `login` / `user` → `authUsername` and `password` / `pass` → `authPassword` on http and api; a snake_case spelling of a camelCase key (`timeout_seconds` → `timeoutSeconds`) on every type. Config keys per type: GET /meta/monitor-types. */
2458
+ ignored_config_keys?: string[];
2401
2459
  /** @description The open (firing or acknowledged) incident, or null. When several are open: the critical one, then the earliest started. */
2402
2460
  current_incident?: components["schemas"]["MonitorCurrentIncident"] | null;
2403
2461
  /** @description A silence (dashboard Mute) suppresses notifications; incidents still open and close and checks continue. */
@@ -2472,6 +2530,7 @@ export interface components {
2472
2530
  latest?: components["schemas"]["MonitorLatest"] | null;
2473
2531
  available_metrics: components["schemas"]["CatalogAlertMetric"][];
2474
2532
  };
2533
+ /** @description Unknown top-level fields are rejected with 400 naming the accepted ones (like PATCH) — type-specific settings go in `config`. */
2475
2534
  MonitorCreate: {
2476
2535
  name: string;
2477
2536
  /**
@@ -2509,7 +2568,7 @@ export interface components {
2509
2568
  | "imap"
2510
2569
  | "pop3"
2511
2570
  | "email_roundtrip";
2512
- /** @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. */
2571
+ /** @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. heartbeat: the server assigns the ping path — send any placeholder (or omit target); read ping_url from the response. smtp: hostname only, the port goes in config.port. */
2513
2572
  target: string;
2514
2573
  /** @description Seconds; validated against the plan's per-type minimum */
2515
2574
  interval: number;
@@ -2524,7 +2583,7 @@ export interface components {
2524
2583
  /** @description Lowercase alphanumeric with hyphens or colons, e.g. prod, team:web */
2525
2584
  tags?: string[];
2526
2585
  description?: string | null;
2527
- /** @description Type-specific settings — the keys and types are listed per type under config_fields in GET /meta/monitor-types. Validated against the monitor type: a wrong value returns 400 naming the field (e.g. `config.timeoutSeconds`); keys the type does not use are dropped. Config that drives an alert preset (dns expectedValues, cdn expectedProvider, cms expectedCms, tcp/udp expectMatchRegexp, websocket expectPattern, mcp expectedProtocolVersion, http failIfBody*Regexp) also creates that preset's alert rule. Credential keys (marked secret in the catalog: password, smtpPassword, receivePassword, privateKey, …) are write-only and stored encrypted; responses return them as "[redacted]". */
2586
+ /** @description Type-specific settings — the keys and types are listed per type under config_fields in GET /meta/monitor-types. Validated against the monitor type: a wrong value returns 400 naming the field (e.g. `config.timeoutSeconds`); keys the type does not use are dropped and listed in the response's `ignored_config_keys` (obvious aliases such as `login` → `username` are renamed instead). Config that drives an alert preset (dns expectedValues, cdn expectedProvider, cms expectedCms, tcp/udp expectMatchRegexp, websocket expectPattern, mcp expectedProtocolVersion, http failIfBody*Regexp) also creates that preset's alert rule. Credential keys (marked secret in the catalog: password, smtpPassword, receivePassword, privateKey, …) are write-only and stored encrypted; responses return them as "[redacted]". */
2528
2587
  config?: {
2529
2588
  [key: string]: unknown;
2530
2589
  };
@@ -2586,6 +2645,10 @@ export interface components {
2586
2645
  min_response_time_ms?: number | null;
2587
2646
  /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded */
2588
2647
  max_response_time_ms?: number | null;
2648
+ /**
2649
+ * Format: date-time
2650
+ * @description The newest failed check in the window (RFC 3339 / ISO 8601 UTC); null when none failed
2651
+ */
2589
2652
  last_failure_at?: string | null;
2590
2653
  /** @description Incident-based headline uptime for the last 24 hours */
2591
2654
  uptime_24h?: number | null;
@@ -2622,6 +2685,10 @@ export interface components {
2622
2685
  object?: "check";
2623
2686
  /** @description Addresses this exact probe run */
2624
2687
  run_id?: string;
2688
+ /**
2689
+ * Format: date-time
2690
+ * @description When the check ran — RFC 3339 / ISO 8601 UTC, e.g. 2026-10-17T14:31:29.000Z
2691
+ */
2625
2692
  timestamp?: string;
2626
2693
  success?: boolean;
2627
2694
  duration_ms?: number;
@@ -2660,6 +2727,10 @@ export interface components {
2660
2727
  run_id?: string;
2661
2728
  /** Format: uuid */
2662
2729
  monitor_id?: string;
2730
+ /**
2731
+ * Format: date-time
2732
+ * @description When the check ran — RFC 3339 / ISO 8601 UTC, e.g. 2026-10-17T14:31:29.000Z
2733
+ */
2663
2734
  timestamp?: string;
2664
2735
  location?: string;
2665
2736
  target?: string;
@@ -2951,6 +3022,45 @@ export interface components {
2951
3022
  expires_at: string;
2952
3023
  message?: string;
2953
3024
  };
3025
+ /** @description A drift incident accepted as an intended change. `resolve_requested` = this call asked the alert-manager to resolve it (asynchronous — `incident` may still read firing; poll GET /v1/incidents/{id}). */
3026
+ ExpectedChangeAccept: {
3027
+ /** @constant */
3028
+ object: "expected_change";
3029
+ /** @constant */
3030
+ kind: "accepted";
3031
+ incident_id: number;
3032
+ /** Format: uuid */
3033
+ monitor_id: string;
3034
+ /** @description Who accepted it (dashboard user or API key) */
3035
+ accepted_by: string;
3036
+ /** Format: date-time */
3037
+ accepted_at: string;
3038
+ note?: string | null;
3039
+ resolve_requested: boolean;
3040
+ /** @description true = accepted before; nothing changed */
3041
+ already_accepted: boolean;
3042
+ incident: components["schemas"]["Incident"];
3043
+ };
3044
+ /** @description A release marker: until `ends_at`, drift on the monitor (the listed rules only) does not page, and drift incidents opened in the window are resolved within a minute. */
3045
+ ExpectedChangeWindow: {
3046
+ /** @constant */
3047
+ object: "expected_change_window";
3048
+ /** Format: uuid */
3049
+ monitor_id: string;
3050
+ window_minutes: number;
3051
+ /** Format: date-time */
3052
+ starts_at: string;
3053
+ /** Format: date-time */
3054
+ ends_at: string;
3055
+ /** @description The drift alert rules the window covers */
3056
+ rules: {
3057
+ /** Format: uuid */
3058
+ id: string;
3059
+ name: string;
3060
+ }[];
3061
+ note?: string | null;
3062
+ created_by: string;
3063
+ };
2954
3064
  MonitorReset: {
2955
3065
  /** @constant */
2956
3066
  object?: "monitor_reset";
@@ -3547,7 +3657,14 @@ export interface components {
3547
3657
  name?: string;
3548
3658
  /** @description -1 = unlimited, 0 = feature disabled */
3549
3659
  limits?: Record<string, never> | null;
3550
- usage?: Record<string, never>;
3660
+ /** @description Live usage. `monitors_by_type` counts monitors per type and matches `limits.max_monitors_by_type` (`browser` = page-speed / Core Web Vitals monitors, `playwright` = scripted browser checks). `browser_checks` is kept for compatibility and equals the playwright count. */
3661
+ usage?: {
3662
+ monitors_by_type?: {
3663
+ [key: string]: number;
3664
+ };
3665
+ /** @description Playwright (scripted browser check) monitors */
3666
+ browser_checks?: number;
3667
+ };
3551
3668
  };
3552
3669
  Notification: {
3553
3670
  id?: number;
@@ -3589,7 +3706,8 @@ export interface components {
3589
3706
  /** @description Current display name of the entity (from the create/delete snapshot when it no longer exists) */
3590
3707
  entity_name?: string | null;
3591
3708
  action?: string;
3592
- changes?: Record<string, never>;
3709
+ /** @description What changed, as recorded with the event (e.g. {field: {from, to}} for updates, a snapshot for creates/deletes); null for events that record no details (post-mortem created/deleted/completed, incident acknowledged…) */
3710
+ changes?: Record<string, never> | null;
3593
3711
  actor?: {
3594
3712
  name?: string | null;
3595
3713
  email?: string | null;
@@ -3830,7 +3948,12 @@ export interface components {
3830
3948
  toMs?: number;
3831
3949
  label?: string;
3832
3950
  };
3833
- previousPeriod?: Record<string, never>;
3951
+ /** @description The equal-length period before `period` that compared values are measured against */
3952
+ previousPeriod?: {
3953
+ fromMs?: number;
3954
+ toMs?: number;
3955
+ label?: string;
3956
+ };
3834
3957
  /** @enum {string} */
3835
3958
  depth?: "basic" | "advanced";
3836
3959
  typesPresent?: string[];
@@ -3844,8 +3967,9 @@ export interface components {
3844
3967
  monitorId?: string;
3845
3968
  name?: string;
3846
3969
  type?: string;
3970
+ target?: string;
3847
3971
  /** @description Incident-based, same formula as the monitor's Uptime card */
3848
- uptimePct?: Record<string, never>;
3972
+ uptimePct?: components["schemas"]["ReportCompared"];
3849
3973
  downtimeMs?: number;
3850
3974
  /** @description Reachability, not health: share of this monitor's checks that reached the target and got a response; null when the period has no checks */
3851
3975
  checkSuccessPct?: number | null;
@@ -3877,6 +4001,14 @@ export interface components {
3877
4001
  /** @description Insights withheld beyond the plan's cap (0 on advanced depth) */
3878
4002
  gatedInsightCount?: number;
3879
4003
  };
4004
+ /** @description A report value paired with its previous-period counterpart */
4005
+ ReportCompared: {
4006
+ current: number;
4007
+ /** @description null when the previous period has no data */
4008
+ previous: number | null;
4009
+ /** @description current - previous; null when no baseline */
4010
+ delta: number | null;
4011
+ };
3880
4012
  /** @description name/email are null for a member who has since left the organization */
3881
4013
  OncallPerson: {
3882
4014
  id?: string;
@@ -4239,7 +4371,7 @@ export interface components {
4239
4371
  DiagnosticOptionsCdnCheck: Record<string, never>;
4240
4372
  /** @description Options for the `sitemap-check` diagnostic. Does this domain publish a valid sitemap, is it reachable from robots.txt, and do its URLs resolve? */
4241
4373
  DiagnosticOptionsSitemapCheck: Record<string, never>;
4242
- /** @description Options for the `brotli-check` diagnostic. Does this domain serve Brotli or gzip compression, and how much bandwidth is it saving? */
4374
+ /** @description Options for the `brotli-check` diagnostic. Does this domain serve Brotli and gzip compression — which Content-Encoding comes back when a client offers only br, and when it offers only gzip? */
4243
4375
  DiagnosticOptionsBrotliCheck: Record<string, never>;
4244
4376
  /** @description Options for the `redirect-chain` diagnostic. Where does this URL end up — every redirect hop with its status code and Location, the final URL, and whether the chain is longer, slower or less secure than it should be? */
4245
4377
  DiagnosticOptionsRedirectChain: {
@@ -5298,6 +5430,51 @@ export interface operations {
5298
5430
  };
5299
5431
  };
5300
5432
  };
5433
+ setMonitorExpectedChange: {
5434
+ parameters: {
5435
+ query?: {
5436
+ /** @description Minutes the window stays open (1–60, default 15). Out of range → 400, never clamped. */
5437
+ window?: number;
5438
+ };
5439
+ header?: {
5440
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
5441
+ "Idempotency-Key"?: string;
5442
+ };
5443
+ path: {
5444
+ /** @description Resource id (UUID) */
5445
+ id: string;
5446
+ };
5447
+ cookie?: never;
5448
+ };
5449
+ requestBody?: {
5450
+ content: {
5451
+ "application/json": {
5452
+ window?: number;
5453
+ note?: string;
5454
+ };
5455
+ };
5456
+ };
5457
+ responses: {
5458
+ /** @description Window opened */
5459
+ 201: {
5460
+ headers: {
5461
+ [name: string]: unknown;
5462
+ };
5463
+ content: {
5464
+ "application/json": components["schemas"]["ExpectedChangeWindow"];
5465
+ };
5466
+ };
5467
+ /** @description Error */
5468
+ default: {
5469
+ headers: {
5470
+ [name: string]: unknown;
5471
+ };
5472
+ content: {
5473
+ "application/json": components["schemas"]["Error"];
5474
+ };
5475
+ };
5476
+ };
5477
+ };
5301
5478
  getMonitorUptime: {
5302
5479
  parameters: {
5303
5480
  query?: {
@@ -5768,6 +5945,57 @@ export interface operations {
5768
5945
  };
5769
5946
  };
5770
5947
  };
5948
+ acceptIncidentExpectedChange: {
5949
+ parameters: {
5950
+ query?: never;
5951
+ header?: {
5952
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
5953
+ "Idempotency-Key"?: string;
5954
+ };
5955
+ path: {
5956
+ /** @description Incident id (integer) */
5957
+ id: string;
5958
+ };
5959
+ cookie?: never;
5960
+ };
5961
+ requestBody?: {
5962
+ content: {
5963
+ "application/json": {
5964
+ /** @description Why the change was expected */
5965
+ note?: string;
5966
+ };
5967
+ };
5968
+ };
5969
+ responses: {
5970
+ /** @description Recorded (the incident was already resolved, or accepted before) */
5971
+ 200: {
5972
+ headers: {
5973
+ [name: string]: unknown;
5974
+ };
5975
+ content: {
5976
+ "application/json": components["schemas"]["ExpectedChangeAccept"];
5977
+ };
5978
+ };
5979
+ /** @description Recorded; resolution requested */
5980
+ 202: {
5981
+ headers: {
5982
+ [name: string]: unknown;
5983
+ };
5984
+ content: {
5985
+ "application/json": components["schemas"]["ExpectedChangeAccept"];
5986
+ };
5987
+ };
5988
+ /** @description Error */
5989
+ default: {
5990
+ headers: {
5991
+ [name: string]: unknown;
5992
+ };
5993
+ content: {
5994
+ "application/json": components["schemas"]["Error"];
5995
+ };
5996
+ };
5997
+ };
5998
+ };
5771
5999
  excludeIncidentFromUptime: {
5772
6000
  parameters: {
5773
6001
  query?: never;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.17.1",
3
+ "version": "0.18.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",