watchfor 0.22.1 → 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"];
@@ -329,11 +330,12 @@ export declare class WatchFor {
329
330
  fresh?: boolean;
330
331
  }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept | IntegrityBaselineAcceptPending>;
331
332
  /** MCP monitors: release marker — call it from a deploy pipeline
332
- * before the rollout. For `window` minutes (1–60, default 15) the
333
- * monitor's drift rules (Tool Inventory Changed) are silenced — only
334
- * those, downtime still pages — and drift incidents opened inside
335
- * the window resolve within a minute. Markers stack; 12 per hour per
336
- * 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
337
339
  * `acceptBaseline(id, { fresh: true })` after the deploy); no enabled
338
340
  * drift rule → 409. */
339
341
  setExpectedChangeWindow: (id: string, opts?: {
@@ -368,6 +370,11 @@ export declare class WatchFor {
368
370
  uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d", opts?: {
369
371
  series?: boolean;
370
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>;
371
378
  /** Recent probe results, newest first. Page with `next_cursor` →
372
379
  * `cursor` (keep the same `hours`/`success`); `locations` is the
373
380
  * per-location breakdown for the whole window. */
package/dist/client.js CHANGED
@@ -274,11 +274,12 @@ export class WatchFor {
274
274
  idempotencyKey,
275
275
  }),
276
276
  /** MCP monitors: release marker — call it from a deploy pipeline
277
- * before the rollout. For `window` minutes (1–60, default 15) the
278
- * monitor's drift rules (Tool Inventory Changed) are silenced — only
279
- * those, downtime still pages — and drift incidents opened inside
280
- * the window resolve within a minute. Markers stack; 12 per hour per
281
- * 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
282
283
  * `acceptBaseline(id, { fresh: true })` after the deploy); no enabled
283
284
  * drift rule → 409. */
284
285
  setExpectedChangeWindow: (id, opts = {}, idempotencyKey) => this.request("POST", `/monitors/${id}/expected-change`, {
@@ -301,6 +302,11 @@ export class WatchFor {
301
302
  uptime: (id, period, opts) => this.request("GET", `/monitors/${id}/uptime`, {
302
303
  query: { period, series: opts?.series ? true : undefined },
303
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`),
304
310
  /** Recent probe results, newest first. Page with `next_cursor` →
305
311
  * `cursor` (keep the same `hours`/`success`); `locations` is the
306
312
  * per-location breakdown for the whole window. */
package/dist/schema.d.ts CHANGED
@@ -471,8 +471,8 @@ export interface paths {
471
471
  get?: never;
472
472
  put?: never;
473
473
  /**
474
- * Release marker — drift on this monitor doesn't page 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: 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).
476
476
  */
477
477
  post: operations["setMonitorExpectedChange"];
478
478
  delete?: never;
@@ -481,6 +481,26 @@ export interface paths {
481
481
  patch?: never;
482
482
  trace?: never;
483
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
+ };
484
504
  "/monitors/{id}/uptime": {
485
505
  parameters: {
486
506
  query?: never;
@@ -2731,6 +2751,52 @@ export interface components {
2731
2751
  status: "dispatched";
2732
2752
  message: string;
2733
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
+ };
2734
2800
  Uptime: {
2735
2801
  /** @constant */
2736
2802
  object?: "uptime";
@@ -2904,7 +2970,7 @@ export interface components {
2904
2970
  failure_threshold?: number;
2905
2971
  min_failed_probes?: number;
2906
2972
  duration_window_seconds?: number;
2907
- /** @description Regions the rule is judged from. Empty = all regions. 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. */
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. */
2908
2974
  regions?: (
2909
2975
  | "europe"
2910
2976
  | "north-america"
@@ -2949,7 +3015,7 @@ export interface components {
2949
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.
2950
3016
  */
2951
3017
  contactGroupId?: string | null;
2952
- /** @description Game server monitors only: judge this rule only from checks made in these regions (e.g. a latency threshold for Europe only). Omit or [] for all regions. 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. */
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. */
2953
3019
  regions?: (
2954
3020
  | "europe"
2955
3021
  | "north-america"
@@ -3179,7 +3245,7 @@ export interface components {
3179
3245
  already_accepted: boolean;
3180
3246
  incident: components["schemas"]["Incident"];
3181
3247
  };
3182
- /** @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". */
3183
3249
  ExpectedChangeWindow: {
3184
3250
  /** @constant */
3185
3251
  object: "expected_change_window";
@@ -3537,7 +3603,7 @@ export interface components {
3537
3603
  minFailedProbes?: number;
3538
3604
  /** @description Seconds */
3539
3605
  durationWindow?: number;
3540
- /** @description Game server monitors only. Omit to keep the rule's regions; null or [] = all regions; otherwise the regions the rule is judged from. */
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. */
3541
3607
  regions?:
3542
3608
  | (
3543
3609
  | "europe"
@@ -5668,6 +5734,38 @@ export interface operations {
5668
5734
  };
5669
5735
  };
5670
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
+ };
5671
5769
  getMonitorUptime: {
5672
5770
  parameters: {
5673
5771
  query?: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.22.1",
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",