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 +5 -1
- package/dist/client.d.ts +21 -9
- package/dist/client.js +19 -8
- package/dist/schema.d.ts +219 -14
- package/package.json +1 -1
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 (
|
|
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
|
|
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.
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
331
|
-
*
|
|
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.
|
|
273
|
-
*
|
|
274
|
-
*
|
|
275
|
-
*
|
|
276
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
469
|
-
* @description MCP monitors (drift = the Tool Inventory Changed rule). Call it from a deploy pipeline before the rollout starts:
|
|
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
|
|
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
|
|
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
|
-
/**
|
|
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)
|
|
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
|
|
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
|
|
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.
|
|
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",
|