watchfor 0.21.0 → 0.23.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
@@ -80,6 +80,10 @@ const { alerting_state } = await wf.monitors.get(monitor.id!);
80
80
  const uptime = await wf.monitors.uptime(monitor.id!, "24h", { series: true });
81
81
  for (const b of uptime.response_time_series ?? []) console.log(b.at, b.avg_ms);
82
82
 
83
+ // Game server: latency thresholds suggested from the monitor's own checks.
84
+ const sug = await wf.monitors.suggestedThresholds("<game-monitor-id>");
85
+ for (const r of sug.regions ?? []) console.log(r.region, r.p95_ms, r.warning, r.critical);
86
+
83
87
  // Pause up to 100 monitors at once; post a status-page announcement.
84
88
  await wf.monitors.bulk("pause", ["<id-1>", "<id-2>"]);
85
89
  const notice = await wf.statusPages.createAnnouncement("<page-id>", {
@@ -212,5 +216,5 @@ WATCHFOR_ORGANIZATION=<organization-id> npx watchfor summary
212
216
  ## Links
213
217
 
214
218
  - API docs: https://watchfor.io/docs/api
215
- - MCP server for AI agents (63 tools): https://watchfor.io/docs/api/mcp
219
+ - MCP server for AI agents (64 tools): https://watchfor.io/docs/api/mcp
216
220
  - Create an API key: dashboard → Settings → API keys (`read` or `read+write` scope)
package/dist/client.d.ts CHANGED
@@ -29,7 +29,7 @@ export type IntegrityBaselineAccept = components["schemas"]["IntegrityBaselineAc
29
29
  /** A fresh accept whose check has not landed yet (HTTP 202). */
30
30
  export type IntegrityBaselineAcceptPending = components["schemas"]["IntegrityBaselineAcceptPending"];
31
31
  /** `monitors.setExpectedChangeWindow()` — a release marker on an MCP
32
- * monitor: drift does not page until `ends_at`. */
32
+ * monitor: until `ends_at`, drift doesn't open an incident. */
33
33
  export type ExpectedChangeWindow = components["schemas"]["ExpectedChangeWindow"];
34
34
  /** `incidents.acceptExpectedChange()` — a drift incident recorded as an
35
35
  * intended change. */
@@ -78,6 +78,7 @@ export type AnnouncementUpdate = components["schemas"]["AnnouncementUpdate"];
78
78
  /** Uptime stats; with `series: true` also `response_time_series` and
79
79
  * `series_bucket_seconds` (periods up to 7d). */
80
80
  export type Uptime = components["schemas"]["Uptime"];
81
+ export type SuggestedThresholds = components["schemas"]["SuggestedThresholds"];
81
82
  /** One bucket of `Uptime.response_time_series`. */
82
83
  export type ResponseTimeBucket = NonNullable<Uptime["response_time_series"]>[number];
83
84
  export type Check = components["schemas"]["Check"];
@@ -254,7 +255,10 @@ export declare class WatchFor {
254
255
  enabled?: boolean;
255
256
  recipients?: string[];
256
257
  }): Promise<Record<string, unknown>>;
257
- /** Probe locations for monitor creation. */
258
+ /** Probe locations for monitor creation. Each lists `capabilities`
259
+ * (`ipv6`, `port25`, `chromium`, `playwright`) as its probers report
260
+ * them; a monitor whose `required_capabilities` it lacks can't use it
261
+ * (400 on save). */
258
262
  locations(): Promise<List<Record<string, unknown>>>;
259
263
  /** Every monitor type with its exact alert metrics + config fields. */
260
264
  monitorTypes(): Promise<List<Record<string, unknown>>>;
@@ -297,13 +301,15 @@ export declare class WatchFor {
297
301
  * used with (HTTP: the URL's host, port or scheme) needs it again in
298
302
  * the same call (else 400). `check_queued: true` in the result means
299
303
  * the change (target, port, credentials, TLS, request…) dispatched one
300
- * immediate check, outside the Run-now budget. */
304
+ * immediate check, outside the Run-now budget; `check_blocked` says why
305
+ * it didn't run when no selected location can run the monitor now. */
301
306
  update: (id: string, body: Record<string, unknown>) => Promise<Monitor>;
302
307
  delete: (id: string) => Promise<Deleted>;
303
308
  pause: (id: string) => Promise<Monitor>;
304
309
  resume: (id: string) => Promise<Monitor>;
305
310
  /** Dispatch one out-of-schedule check now (202); the result lands in
306
- * `checks()` moments later. */
311
+ * `checks()` moments later. 409 when no selected location can run the
312
+ * monitor right now (e.g. it needs IPv6 and none of them has it). */
307
313
  checkNow: (id: string) => Promise<CheckNowAck>;
308
314
  /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
309
315
  * the monitor and start uptime over ("since reset"). The monitor and
@@ -324,11 +330,12 @@ export declare class WatchFor {
324
330
  fresh?: boolean;
325
331
  }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept | IntegrityBaselineAcceptPending>;
326
332
  /** 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
333
+ * before the rollout. During the window (`window` minutes, 1–60,
334
+ * default 15) tool-inventory drift doesn't open an incident; the
335
+ * change is recorded in the drift timeline as "Expected — release
336
+ * marker". Only the drift rules (Tool Inventory Changed) are covered
337
+ * — downtime still pages. Markers stack; 12 per hour per monitor
338
+ * (429). Page integrity monitors → 400 (use
332
339
  * `acceptBaseline(id, { fresh: true })` after the deploy); no enabled
333
340
  * drift rule → 409. */
334
341
  setExpectedChangeWindow: (id: string, opts?: {
@@ -363,6 +370,11 @@ export declare class WatchFor {
363
370
  uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d", opts?: {
364
371
  series?: boolean;
365
372
  }) => Promise<Uptime>;
373
+ /** Game server monitors: latency thresholds suggested from the
374
+ * monitor's own checks — per region its p95 (7 days, or the last 24 h
375
+ * for a newer region), warning / critical, and which regions need
376
+ * their own. Read-only. */
377
+ suggestedThresholds: (id: string) => Promise<SuggestedThresholds>;
366
378
  /** Recent probe results, newest first. Page with `next_cursor` →
367
379
  * `cursor` (keep the same `hours`/`success`); `locations` is the
368
380
  * per-location breakdown for the whole window. */
package/dist/client.js CHANGED
@@ -197,7 +197,10 @@ export class WatchFor {
197
197
  setReportSchedule(frequency, body) {
198
198
  return this.request("PATCH", `/reports/schedules/${frequency}`, { body });
199
199
  }
200
- /** Probe locations for monitor creation. */
200
+ /** Probe locations for monitor creation. Each lists `capabilities`
201
+ * (`ipv6`, `port25`, `chromium`, `playwright`) as its probers report
202
+ * them; a monitor whose `required_capabilities` it lacks can't use it
203
+ * (400 on save). */
201
204
  locations() {
202
205
  return this.request("GET", "/locations");
203
206
  }
@@ -242,13 +245,15 @@ export class WatchFor {
242
245
  * used with (HTTP: the URL's host, port or scheme) needs it again in
243
246
  * the same call (else 400). `check_queued: true` in the result means
244
247
  * the change (target, port, credentials, TLS, request…) dispatched one
245
- * immediate check, outside the Run-now budget. */
248
+ * immediate check, outside the Run-now budget; `check_blocked` says why
249
+ * it didn't run when no selected location can run the monitor now. */
246
250
  update: (id, body) => this.request("PATCH", `/monitors/${id}`, { body }),
247
251
  delete: (id) => this.request("DELETE", `/monitors/${id}`),
248
252
  pause: (id) => this.request("POST", `/monitors/${id}/pause`),
249
253
  resume: (id) => this.request("POST", `/monitors/${id}/resume`),
250
254
  /** Dispatch one out-of-schedule check now (202); the result lands in
251
- * `checks()` moments later. */
255
+ * `checks()` moments later. 409 when no selected location can run the
256
+ * monitor right now (e.g. it needs IPv6 and none of them has it). */
252
257
  checkNow: (id) => this.request("POST", `/monitors/${id}/check-now`),
253
258
  /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
254
259
  * the monitor and start uptime over ("since reset"). The monitor and
@@ -269,11 +274,12 @@ export class WatchFor {
269
274
  idempotencyKey,
270
275
  }),
271
276
  /** 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
+ * before the rollout. During the window (`window` minutes, 1–60,
278
+ * default 15) tool-inventory drift doesn't open an incident; the
279
+ * change is recorded in the drift timeline as "Expected — release
280
+ * marker". Only the drift rules (Tool Inventory Changed) are covered
281
+ * — downtime still pages. Markers stack; 12 per hour per monitor
282
+ * (429). Page integrity monitors → 400 (use
277
283
  * `acceptBaseline(id, { fresh: true })` after the deploy); no enabled
278
284
  * drift rule → 409. */
279
285
  setExpectedChangeWindow: (id, opts = {}, idempotencyKey) => this.request("POST", `/monitors/${id}/expected-change`, {
@@ -296,6 +302,11 @@ export class WatchFor {
296
302
  uptime: (id, period, opts) => this.request("GET", `/monitors/${id}/uptime`, {
297
303
  query: { period, series: opts?.series ? true : undefined },
298
304
  }),
305
+ /** Game server monitors: latency thresholds suggested from the
306
+ * monitor's own checks — per region its p95 (7 days, or the last 24 h
307
+ * for a newer region), warning / critical, and which regions need
308
+ * their own. Read-only. */
309
+ suggestedThresholds: (id) => this.request("GET", `/monitors/${id}/suggested-thresholds`),
299
310
  /** Recent probe results, newest first. Page with `next_cursor` →
300
311
  * `cursor` (keep the same `hours`/`success`); `locations` is the
301
312
  * per-location breakdown for the whole window. */
package/dist/schema.d.ts CHANGED
@@ -328,7 +328,10 @@ export interface paths {
328
328
  };
329
329
  get?: never;
330
330
  put?: never;
331
- /** Bulk pause/resume/delete (max 100 ids) */
331
+ /**
332
+ * Bulk pause/resume/delete (max 100 ids)
333
+ * @description Ids from other organizations or unknown ids are listed in `skipped`. A resume starts one immediate check per monitor for the first 20 per organization per minute (listed in `checks_queued`); the rest wait for their next scheduled check.
334
+ */
332
335
  post: operations["bulkMonitorAction"];
333
336
  delete?: never;
334
337
  options?: never;
@@ -381,7 +384,10 @@ export interface paths {
381
384
  };
382
385
  get?: never;
383
386
  put?: never;
384
- /** Resume checks (idempotent) */
387
+ /**
388
+ * Resume checks (idempotent; starts one immediate check)
389
+ * @description Restarts checks and dispatches one immediate check, so the monitor reports within seconds instead of after up to a full interval (`check_queued: true`). Pause/resume is not a way around Run now: the resume check is capped at one per monitor per 10 minutes and 20 per organization per minute, it never spends or resets the plan's check-now budget, and every pause closes open incidents and resets the alerting counters. Past the cap the resume still succeeds: `check_queued` is false and `next_check_at` says by when the first scheduled check runs. Resuming a monitor that is already running is a no-op (`check_queued: false`, `next_check_at: null`). Heartbeat and host monitors get no immediate check; they wait for the next ping.
390
+ */
385
391
  post: operations["resumeMonitor"];
386
392
  delete?: never;
387
393
  options?: never;
@@ -400,7 +406,7 @@ export interface paths {
400
406
  put?: never;
401
407
  /**
402
408
  * 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.
409
+ * @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. 409 `conflict` when no selected location can run the monitor right now — e.g. it needs IPv6 and none of its locations has it (`error.message` names what is missing; see GET /v1/locations → capabilities); nothing is spent.
404
410
  */
405
411
  post: operations["runMonitorCheckNow"];
406
412
  delete?: never;
@@ -465,8 +471,8 @@ export interface paths {
465
471
  get?: never;
466
472
  put?: never;
467
473
  /**
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).
474
+ * Release marker — drift on this monitor doesn't open an incident for the next N minutes (call before a deploy)
475
+ * @description MCP monitors (drift = the Tool Inventory Changed rule). Call it from a deploy pipeline before the rollout starts: during the window, tool-inventory drift on this monitor doesn't open an incident; the change is recorded in the drift timeline as "Expected — release marker". Only the monitor's drift rules are covered, so downtime and every other rule still open incidents and page; a drift incident already open when the window starts stays open. 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 from each of the monitor's locations: 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
476
  */
471
477
  post: operations["setMonitorExpectedChange"];
472
478
  delete?: never;
@@ -475,6 +481,26 @@ export interface paths {
475
481
  patch?: never;
476
482
  trace?: never;
477
483
  };
484
+ "/monitors/{id}/suggested-thresholds": {
485
+ parameters: {
486
+ query?: never;
487
+ header?: never;
488
+ path?: never;
489
+ cookie?: never;
490
+ };
491
+ /**
492
+ * Game server monitors: latency thresholds suggested from the monitor's own checks (per-region p95, warning and critical)
493
+ * @description Per region the monitor is checked from: the 95th percentile of game.query_rtt_ms over 7 days (the last 24 hours when the region has less history), warning = max(p95 × 1.3, p95 + 30 ms) and critical = max(p95 × 1.8, p95 + 80 ms), rounded up to 10 ms and kept within 20–5000 ms. The all-regions values come from the region with the most locations; a region more than 25% away gets own_thresholds: true. Read-only — nothing changes until you write the rules (POST/PATCH /monitors/{id}/alert-rules, regions for a region's own rule). 400 for a monitor that isn't a game server.
494
+ */
495
+ get: operations["getSuggestedThresholds"];
496
+ put?: never;
497
+ post?: never;
498
+ delete?: never;
499
+ options?: never;
500
+ head?: never;
501
+ patch?: never;
502
+ trace?: never;
503
+ };
478
504
  "/monitors/{id}/uptime": {
479
505
  parameters: {
480
506
  query?: never;
@@ -1359,7 +1385,7 @@ export interface components {
1359
1385
  /** @description Days until the certificate the latest check saw expires; null when it saw none (plain text, or failed before TLS). */
1360
1386
  cert_days_left: number | null;
1361
1387
  };
1362
- /** @description udp monitors — the latest check. */
1388
+ /** @description udp monitors — the latest check, including its packet train (loss, round trips, jitter) when config.packetLoss is on. */
1363
1389
  MonitorLatestUdp: {
1364
1390
  /**
1365
1391
  * @description discriminator enum property added by openapi-typescript
@@ -1374,6 +1400,22 @@ export interface components {
1374
1400
  response_received: boolean | null;
1375
1401
  bytes_received: number | null;
1376
1402
  first_byte_ms: number | null;
1403
+ /** @description Request packets the check sent a short gap apart (config.packetCount, default 5). null when the check sent no train: config.packetLoss off, a check held to one packet by the per-destination limit, an older check, or a TCP/HTTP game protocol. */
1404
+ packets_sent: number | null;
1405
+ /** @description Packets answered within the loss window. */
1406
+ packets_received: number | null;
1407
+ /** @description Lost / sent × 100 for this check; 100 when nothing answered (the check is then down). */
1408
+ packet_loss_pct: number | null;
1409
+ /** @description Fastest round trip of the answered packets. */
1410
+ rtt_min_ms: number | null;
1411
+ /** @description Mean round trip of the answered packets. */
1412
+ rtt_avg_ms: number | null;
1413
+ /** @description Slowest round trip of the answered packets. */
1414
+ rtt_max_ms: number | null;
1415
+ /** @description Mean absolute difference between the round trips of consecutive answered packets; null with fewer than 2 answers. */
1416
+ jitter_ms: number | null;
1417
+ /** @description Replies stopped after the same first packets on consecutive checks: the server limits queries, so the check is left out of loss figures and alerts. */
1418
+ rate_limited: boolean | null;
1377
1419
  };
1378
1420
  /** @description icmp (ping) monitors — the latest check. RTTs are null when no reply came back. */
1379
1421
  MonitorLatestIcmp: {
@@ -1830,7 +1872,7 @@ export interface components {
1830
1872
  dmarc_pass: boolean | null;
1831
1873
  spam_score: number | null;
1832
1874
  };
1833
- /** @description game monitors — the latest check: what the server's status query reported. Player counts are null when the server hides them. */
1875
+ /** @description game monitors — the latest check: what the server's status query reported, and, with config.packetLoss on, the packet train's loss, round trips and jitter on the UDP protocols (Steam/A2S, Minecraft Bedrock, SA-MP/open.mp, MTA). Player counts are null when the server hides them. */
1834
1876
  MonitorLatestGame: {
1835
1877
  /**
1836
1878
  * @description discriminator enum property added by openapi-typescript
@@ -1860,6 +1902,22 @@ export interface components {
1860
1902
  game: string | null;
1861
1903
  /** @description The monitor's config.preset. */
1862
1904
  preset: string | null;
1905
+ /** @description Request packets the check sent a short gap apart (config.packetCount, default 5). null when the check sent no train: config.packetLoss off, a check held to one packet by the per-destination limit, an older check, or a TCP/HTTP game protocol. */
1906
+ packets_sent: number | null;
1907
+ /** @description Packets answered within the loss window. */
1908
+ packets_received: number | null;
1909
+ /** @description Lost / sent × 100 for this check; 100 when nothing answered (the check is then down). */
1910
+ packet_loss_pct: number | null;
1911
+ /** @description Fastest round trip of the answered packets. */
1912
+ rtt_min_ms: number | null;
1913
+ /** @description Mean round trip of the answered packets. */
1914
+ rtt_avg_ms: number | null;
1915
+ /** @description Slowest round trip of the answered packets. */
1916
+ rtt_max_ms: number | null;
1917
+ /** @description Mean absolute difference between the round trips of consecutive answered packets; null with fewer than 2 answers. */
1918
+ jitter_ms: number | null;
1919
+ /** @description Replies stopped after the same first packets on consecutive checks: the server limits queries, so the check is left out of loss figures and alerts. */
1920
+ rate_limited: boolean | null;
1863
1921
  };
1864
1922
  /** @description Type-aware summary of the monitor page's top cards. `kind` is always the monitor's type; every field is present, null when unknown. */
1865
1923
  MonitorLatest:
@@ -2463,6 +2521,8 @@ export interface components {
2463
2521
  */
2464
2522
  scheduling_strategy?: "roundrobin" | "random" | "parallel";
2465
2523
  locations?: string[];
2524
+ /** @description Location capabilities this monitor needs, derived from its settings when it is saved: "ipv6" for ipVersion "ip6", an IPv6 address as target or a hostname with only IPv6 (AAAA) addresses; "port25" for an SMTP check on port 25 (the default) or a TCP check of port 25; "chromium" for Core Web Vitals and Page integrity in browser mode; "playwright" for browser checks. Every location in `locations` must list them in GET /v1/locations → capabilities; a save that picks one that does not is refused with 400. Checks never run from a location that lost one. */
2525
+ required_capabilities?: ("ipv6" | "port25" | "chromium" | "playwright")[];
2466
2526
  /**
2467
2527
  * @description Why `status` is what it is: critical_incident = a confirmed critical incident is open (the only way to be down); warning_incident = an open warning incident; failed_check = a check is failing (the latest check failed, or an alert rule such as status code or response time is failing) without a confirmed incident yet (degraded); paused; no_data = nothing reported yet (unknown); ok. Present on GET/POST/PATCH/pause/resume responses.
2468
2528
  * @enum {string}
@@ -2489,13 +2549,37 @@ export interface components {
2489
2549
  failing?: boolean;
2490
2550
  /** Format: date-time */
2491
2551
  failing_since?: string | null;
2552
+ /** @description The unconfirmed rule closest to confirming, as the dashboard's 'Confirming 2/3' chip shows it: which rule, what its latest failing check measured and where, and where the streak has failed so far. rule / last_value / last_location are null and confirmed_from is [] when the engine doesn't report them. */
2492
2553
  confirming?: {
2493
2554
  count?: number;
2494
2555
  threshold?: number;
2556
+ rule?: {
2557
+ name?: string;
2558
+ /** @enum {string} */
2559
+ severity?: "critical" | "warning";
2560
+ /** @description The rule's region slugs; [] = all regions. */
2561
+ regions?: string[];
2562
+ } | null;
2563
+ /** @description The latest failing check's value with its unit, e.g. "164 ms"; null for a non-numeric rule (e.g. the server not answering). */
2564
+ last_value?: string | null;
2565
+ last_location?: {
2566
+ /** @description City (or location name), e.g. Oregon. */
2567
+ name?: string;
2568
+ region?: string | null;
2569
+ } | null;
2570
+ /** @description Locations whose checks have failed in this streak so far, first first. */
2571
+ confirmed_from?: string[];
2495
2572
  } | null;
2496
2573
  } | null;
2497
- /** @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. */
2574
+ /** @description PATCH /monitors/{id} and POST /monitors/{id}/resume responses only. PATCH: 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; 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. Resume: true when the resume dispatched one immediate check; at most one per monitor per 10 minutes and 20 per organization per minute, false past those (the monitor waits for its schedule, see next_check_at), for heartbeat and host monitors, and when the monitor was already running. Neither uses or resets the plan's Run-now budget. */
2498
2575
  check_queued?: boolean;
2576
+ /**
2577
+ * Format: date-time
2578
+ * @description POST /monitors/{id}/resume responses only: the latest time the first scheduled check is due. It can come one interval slot earlier when the scheduler picks the resume up quickly. null for heartbeat and host monitors (they wait for the next ping) and when the monitor was already running.
2579
+ */
2580
+ next_check_at?: string | null;
2581
+ /** @description PATCH /monitors/{id} responses only: why the save's immediate check did not run — no selected location can run the monitor right now, e.g. "No selected location can run this check right now (needs IPv6)." (see GET /v1/locations → capabilities). null otherwise. */
2582
+ check_blocked?: string | null;
2499
2583
  /** @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. */
2500
2584
  ignored_config_keys?: string[];
2501
2585
  /** @description The open (firing or acknowledged) incident, or null. When several are open: the critical one, then the earliest started. */
@@ -2504,7 +2588,7 @@ export interface components {
2504
2588
  alerts_muted?: boolean;
2505
2589
  /** Format: date-time */
2506
2590
  alerts_muted_until?: string | null;
2507
- /** @description true when an alert rule is routed to a contact group or the monitor has its own notification groups; false = the dashboard's silent-monitor warning: an incident here would reach nobody. */
2591
+ /** @description true when an incident here would notify someone: at least one contact group from an alert rule or the monitor's own notification groups is served by an enabled notification channel whose severity filter takes critical incidents (an email channel also needs a member with an email address in one of its groups), or has an escalation policy that pages a person or an enabled channel. Members without a channel, turned-off or warnings-only channels and empty groups don't count. false = the dashboard's silent-monitor warning: an incident here would reach nobody. */
2508
2592
  has_notification_route?: boolean;
2509
2593
  tags?: string[];
2510
2594
  /** @description Type-specific config (keys per type under config_fields in GET /meta/monitor-types). Credentials (catalog fields marked secret) are write-only and read back as "[redacted]" */
@@ -2540,6 +2624,7 @@ export interface components {
2540
2624
  last_check?: {
2541
2625
  /** Format: date-time */
2542
2626
  at: string;
2627
+ /** @description Reachability, not health: true when the probe reached the target and got an answer. A response that then fails a rule (an HTTP 500, a failed assertion) is still true here and surfaces as an incident instead — read the monitor's status and current_incident for health. */
2543
2628
  success: boolean;
2544
2629
  duration_ms: number;
2545
2630
  /** @description Location name; the prober's name when it is not a listed location. */
@@ -2666,6 +2751,52 @@ export interface components {
2666
2751
  status: "dispatched";
2667
2752
  message: string;
2668
2753
  };
2754
+ /** @description Latency thresholds suggested from a game server monitor's own checks (the dashboard's Suggest from data). Read-only — apply them with the alert-rules endpoints. */
2755
+ SuggestedThresholds: {
2756
+ /** @constant */
2757
+ object?: "suggested_thresholds";
2758
+ /** Format: uuid */
2759
+ monitor_id?: string;
2760
+ /** @constant */
2761
+ metric?: "game.query_rtt_ms";
2762
+ /** @constant */
2763
+ unit?: "ms";
2764
+ /** @description false until at least one region has enough answered checks (method.min_answered_checks over method.min_span_seconds) */
2765
+ ready?: boolean;
2766
+ /**
2767
+ * @description simple = one threshold fits every region; table = some region needs thresholds of its own (region-scoped rules)
2768
+ * @enum {string}
2769
+ */
2770
+ mode?: "simple" | "table";
2771
+ /** @description The region the all-regions values come from: the one with the most locations, ties to the lowest p95 */
2772
+ default_region?: string | null;
2773
+ warning?: number | null;
2774
+ critical?: number | null;
2775
+ /** @description The regions the monitor is checked from */
2776
+ regions?: {
2777
+ region?: string;
2778
+ locations?: number;
2779
+ /** @description 95th percentile of answered checks over `window`; null = too few checks yet */
2780
+ p95_ms?: number | null;
2781
+ answered_checks?: number;
2782
+ /** @enum {string|null} */
2783
+ window?: "7d" | "24h" | null;
2784
+ warning?: number | null;
2785
+ critical?: number | null;
2786
+ is_default?: boolean;
2787
+ /** @description More than 25% away from the default — give this region its own rule */
2788
+ own_thresholds?: boolean;
2789
+ }[];
2790
+ /** @description How the values were computed, in words */
2791
+ method?: {
2792
+ warning?: string;
2793
+ critical?: string;
2794
+ window?: string;
2795
+ default?: string;
2796
+ min_answered_checks?: number;
2797
+ min_span_seconds?: number;
2798
+ };
2799
+ };
2669
2800
  Uptime: {
2670
2801
  /** @constant */
2671
2802
  object?: "uptime";
@@ -2681,6 +2812,7 @@ export interface components {
2681
2812
  check_success_percent?: number | null;
2682
2813
  total_checks?: number;
2683
2814
  successful_checks?: number;
2815
+ /** @description Checks where the probe did not reach the target or got no answer (same meaning as check_success_percent). A response that fails a rule is not counted here — it opens an incident. */
2684
2816
  failed_checks?: number;
2685
2817
  /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded */
2686
2818
  avg_response_time_ms?: number | null;
@@ -2690,7 +2822,7 @@ export interface components {
2690
2822
  max_response_time_ms?: number | null;
2691
2823
  /**
2692
2824
  * Format: date-time
2693
- * @description The newest failed check in the window (RFC 3339 / ISO 8601 UTC); null when none failed
2825
+ * @description The newest failed check in the window (RFC 3339 / ISO 8601 UTC), failed as in failed_checks; null when none failed — even when a rule failure opened an incident (see incidents)
2694
2826
  */
2695
2827
  last_failure_at?: string | null;
2696
2828
  /** @description Incident-based headline uptime for the last 24 hours */
@@ -2733,6 +2865,7 @@ export interface components {
2733
2865
  * @description When the check ran — RFC 3339 / ISO 8601 UTC, e.g. 2026-10-17T14:31:29.000Z
2734
2866
  */
2735
2867
  timestamp?: string;
2868
+ /** @description Reachability, not health: true when the probe reached the target and got an answer. A response that then fails a rule (an HTTP 500, a failed assertion) is still true here and surfaces as an incident instead — read the monitor's status and current_incident for health. */
2736
2869
  success?: boolean;
2737
2870
  duration_ms?: number;
2738
2871
  /** @description The probe location's system name */
@@ -2777,6 +2910,7 @@ export interface components {
2777
2910
  timestamp?: string;
2778
2911
  location?: string;
2779
2912
  target?: string;
2913
+ /** @description Reachability, not health: true when the probe reached the target and got an answer. A response that then fails a rule (an HTTP 500, a failed assertion) is still true here and surfaces as an incident instead — read the monitor's status and current_incident for health. */
2780
2914
  success?: boolean;
2781
2915
  duration_ms?: number;
2782
2916
  error?: string | null;
@@ -2817,6 +2951,8 @@ export interface components {
2817
2951
  action?: "pause" | "resume" | "delete";
2818
2952
  succeeded?: string[];
2819
2953
  skipped?: string[];
2954
+ /** @description resume only: the ids that got an immediate check. At most 20 per organization per minute (and one per monitor per 10 minutes); the rest of the resumed monitors wait for their next scheduled check. */
2955
+ checks_queued?: string[];
2820
2956
  };
2821
2957
  AlertRule: {
2822
2958
  /** Format: uuid */
@@ -2834,6 +2970,16 @@ export interface components {
2834
2970
  failure_threshold?: number;
2835
2971
  min_failed_probes?: number;
2836
2972
  duration_window_seconds?: number;
2973
+ /** @description Regions the rule is judged from. Empty = all regions. Only latency rules (`metrics['game.query_rtt_ms']`) of game server monitors are ever region-scoped; every other rule (Offline included) is judged from every region and always has []. Checks from probers in other regions are skipped by this rule: they neither count towards confirming nor reset the streak. A region-scoped rule takes precedence over an all-regions rule of the same metric and severity for checks from its regions. A region that no enabled rule of a severity covers is never alerted on at that severity (its checks are still recorded) — the dashboard's latency table stores a region with alerts off that way: the level's default rule lists the regions it judges. */
2974
+ regions?: (
2975
+ | "europe"
2976
+ | "north-america"
2977
+ | "south-america"
2978
+ | "asia"
2979
+ | "middle-east"
2980
+ | "africa"
2981
+ | "oceania"
2982
+ )[];
2837
2983
  enabled?: boolean;
2838
2984
  is_system?: boolean;
2839
2985
  contact_group?: {
@@ -2864,8 +3010,21 @@ export interface components {
2864
3010
  * @default 0
2865
3011
  */
2866
3012
  durationWindow: number;
2867
- /** Format: uuid */
3013
+ /**
3014
+ * Format: uuid
3015
+ * @description Contact group this rule notifies. Omit to inherit the monitor's notification group (the first of config.notificationGroupIds that still exists — the organization's default group unless the monitor names others); null for no rule-level group.
3016
+ */
2868
3017
  contactGroupId?: string | null;
3018
+ /** @description Game server latency rules only (`metrics['game.query_rtt_ms']`): judge this rule only from checks made in these regions (e.g. a latency threshold for Europe only). Omit or [] for all regions. Regions apply to latency thresholds only: a non-empty list on any other rule — Offline (`success`) included, which is always judged from every region — is refused with 400 invalid_request. Rules of the same metric and severity may coexist when their regions don't overlap; a region-scoped rule takes precedence over an all-regions one for its regions. */
3019
+ regions?: (
3020
+ | "europe"
3021
+ | "north-america"
3022
+ | "south-america"
3023
+ | "asia"
3024
+ | "middle-east"
3025
+ | "africa"
3026
+ | "oceania"
3027
+ )[];
2869
3028
  };
2870
3029
  Location: {
2871
3030
  /** Format: uuid */
@@ -2879,6 +3038,8 @@ export interface components {
2879
3038
  country_code?: string;
2880
3039
  /** @description The location can run real-browser checks (Core Web Vitals, Page integrity in browser mode). */
2881
3040
  browser?: boolean;
3041
+ /** @description What the location's network can do, as its probers report it: "ipv6" = reaches IPv6 targets, "port25" = outbound SMTP port 25 is not blocked, "chromium" = the real browser for Core Web Vitals / browser-mode Page integrity works, "playwright" = the browser-check runner works (both on browser locations only). A monitor that needs one (ipVersion "ip6", an IPv6 address or IPv6-only hostname as target, an SMTP check on port 25, a TCP check of port 25, a Core Web Vitals or browser-mode integrity check, a browser check) can only be saved with locations that list it — see the monitor's required_capabilities. */
3042
+ capabilities?: ("ipv6" | "port25" | "chromium" | "playwright")[];
2882
3043
  };
2883
3044
  Incident: {
2884
3045
  id?: number;
@@ -3084,7 +3245,7 @@ export interface components {
3084
3245
  already_accepted: boolean;
3085
3246
  incident: components["schemas"]["Incident"];
3086
3247
  };
3087
- /** @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. */
3248
+ /** @description A release marker: until `ends_at`, drift on the monitor (the listed rules only) doesn't open an incident; the change is recorded in the drift timeline as "Expected — release marker". */
3088
3249
  ExpectedChangeWindow: {
3089
3250
  /** @constant */
3090
3251
  object: "expected_change_window";
@@ -3442,6 +3603,18 @@ export interface components {
3442
3603
  minFailedProbes?: number;
3443
3604
  /** @description Seconds */
3444
3605
  durationWindow?: number;
3606
+ /** @description Game server latency rules only (`metrics['game.query_rtt_ms']`). Omit to keep the rule's regions; null or [] = all regions; otherwise the regions the rule is judged from. A non-empty list on any other rule — Offline included, which is always judged from every region — is refused with 400 invalid_request. */
3607
+ regions?:
3608
+ | (
3609
+ | "europe"
3610
+ | "north-america"
3611
+ | "south-america"
3612
+ | "asia"
3613
+ | "middle-east"
3614
+ | "africa"
3615
+ | "oceania"
3616
+ )[]
3617
+ | null;
3445
3618
  enabled?: boolean;
3446
3619
  };
3447
3620
  ContactUpdate: {
@@ -3923,7 +4096,7 @@ export interface components {
3923
4096
  };
3924
4097
  /** @description The dashboard's setup callout */
3925
4098
  attention?: {
3926
- /** @description Active monitors whose alerts would reach nobody (no alert rule with a contact group and no notification group) */
4099
+ /** @description Active monitors whose alerts would reach nobody: no contact group at all, or only groups that no enabled channel taking critical incidents or paging escalation policy delivers through (members without a channel don't count) */
3927
4100
  silent_monitors?: number;
3928
4101
  };
3929
4102
  /** @description Certificate (SSL monitors) and domain (RDAP monitors) expiry in one bulk lookup; null when it can't be read right now */
@@ -4454,7 +4627,7 @@ export interface components {
4454
4627
  /** @default 3 */
4455
4628
  count: number;
4456
4629
  };
4457
- /** @description Options for the `game-server-check` diagnostic. Is this game server online, and what does it report — name, players and slots, map, version, password and VAC, the player list, and the query ping from three regions? Finds the query port when the given one is silent. */
4630
+ /** @description Options for the `game-server-check` diagnostic. Is this game server online, and what does it report — name, players and slots, map, version, password and VAC, the player list, and the latency (status query round trip) from three regions? Finds the query port when the given one is silent. */
4458
4631
  DiagnosticOptionsGameServerCheck: {
4459
4632
  /** @enum {string} */
4460
4633
  game?:
@@ -5561,6 +5734,38 @@ export interface operations {
5561
5734
  };
5562
5735
  };
5563
5736
  };
5737
+ getSuggestedThresholds: {
5738
+ parameters: {
5739
+ query?: never;
5740
+ header?: never;
5741
+ path: {
5742
+ /** @description Resource id (UUID) */
5743
+ id: string;
5744
+ };
5745
+ cookie?: never;
5746
+ };
5747
+ requestBody?: never;
5748
+ responses: {
5749
+ /** @description OK */
5750
+ 200: {
5751
+ headers: {
5752
+ [name: string]: unknown;
5753
+ };
5754
+ content: {
5755
+ "application/json": components["schemas"]["SuggestedThresholds"];
5756
+ };
5757
+ };
5758
+ /** @description Error */
5759
+ default: {
5760
+ headers: {
5761
+ [name: string]: unknown;
5762
+ };
5763
+ content: {
5764
+ "application/json": components["schemas"]["Error"];
5765
+ };
5766
+ };
5767
+ };
5768
+ };
5564
5769
  getMonitorUptime: {
5565
5770
  parameters: {
5566
5771
  query?: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.21.0",
3
+ "version": "0.23.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",