watchfor 0.3.0 → 0.5.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
@@ -31,6 +31,13 @@ await wf.alertRules.create(monitor.id!, {
31
31
  value: "2000",
32
32
  severity: "warning",
33
33
  });
34
+
35
+ // False positive? Keep the resolved incident on record but drop it from
36
+ // uptime, SLA, reports and the status page (include() undoes it).
37
+ await wf.incidents.exclude(19351, { reason: "Probe-side DNS hiccup" });
38
+
39
+ // Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset".
40
+ await wf.monitors.reset(monitor.id!);
34
41
  ```
35
42
 
36
43
  - Fully typed from the [OpenAPI spec](https://watchfor.io/openapi.json)
@@ -52,5 +59,5 @@ npx watchfor report --period 30d
52
59
  ## Links
53
60
 
54
61
  - API docs: https://watchfor.io/docs/api
55
- - MCP server for AI agents (37 tools): https://watchfor.io/docs/api/mcp
62
+ - MCP server for AI agents (42 tools): https://watchfor.io/docs/api/mcp
56
63
  - Create an API key: dashboard → Settings → API keys (`read` or `read+write` scope)
package/dist/cli.js CHANGED
@@ -50,7 +50,7 @@ async function main() {
50
50
  const s = await wf.summary();
51
51
  const m = s.monitors;
52
52
  const i = s.incidents;
53
- console.log(`monitors: ${m.total} total · ${m.up} up · ${m.down} down · ${m.paused} paused · health ${m.health_score}%`);
53
+ console.log(`monitors: ${m.total} total · ${m.up} up · ${m.degraded ?? 0} degraded · ${m.down} down · ${m.paused} paused · health ${m.health_score}%`);
54
54
  console.log(`incidents: ${i.firing} firing (${i.firing_critical} critical) · ${i.acknowledged} acknowledged · ${i.started_24h} started in 24h`);
55
55
  return 0;
56
56
  }
package/dist/client.d.ts CHANGED
@@ -7,6 +7,7 @@ import type { components } from "./schema.js";
7
7
  * const summary = await wf.summary();
8
8
  */
9
9
  export type Monitor = components["schemas"]["Monitor"];
10
+ export type MonitorReset = components["schemas"]["MonitorReset"];
10
11
  export type Incident = components["schemas"]["Incident"];
11
12
  export type AlertRule = components["schemas"]["AlertRule"];
12
13
  export type Contact = components["schemas"]["Contact"];
@@ -86,7 +87,7 @@ export declare class WatchFor {
86
87
  list: (q?: {
87
88
  q?: string;
88
89
  type?: string;
89
- status?: "up" | "down" | "paused" | "unknown";
90
+ status?: "up" | "degraded" | "down" | "paused" | "unknown";
90
91
  tag?: string;
91
92
  limit?: number;
92
93
  cursor?: string;
@@ -98,6 +99,10 @@ export declare class WatchFor {
98
99
  pause: (id: string) => Promise<Monitor>;
99
100
  resume: (id: string) => Promise<Monitor>;
100
101
  checkNow: (id: string) => Promise<unknown>;
102
+ /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
103
+ * the monitor and start uptime over ("since reset"). The monitor and
104
+ * its configuration, alert rules, tags and locations stay. */
105
+ reset: (id: string) => Promise<MonitorReset>;
101
106
  uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d") => Promise<Uptime>;
102
107
  checks: (id: string, q?: {
103
108
  hours?: number;
@@ -125,6 +130,14 @@ export declare class WatchFor {
125
130
  get: (id: number) => Promise<Incident>;
126
131
  acknowledge: (id: number) => Promise<Incident>;
127
132
  resolve: (id: number) => Promise<Incident>;
133
+ /** Mark a RESOLVED incident as a false positive: kept on record, left
134
+ * out of uptime, SLA, reports and the public status page. 409 while
135
+ * the incident is still open. */
136
+ exclude: (id: number, body?: {
137
+ reason?: string;
138
+ }) => Promise<Incident>;
139
+ /** Undo `exclude` — the incident counts as downtime again. */
140
+ include: (id: number) => Promise<Incident>;
128
141
  };
129
142
  readonly maintenanceWindows: {
130
143
  list: (q?: {
package/dist/client.js CHANGED
@@ -122,6 +122,10 @@ export class WatchFor {
122
122
  pause: (id) => this.request("POST", `/monitors/${id}/pause`),
123
123
  resume: (id) => this.request("POST", `/monitors/${id}/resume`),
124
124
  checkNow: (id) => this.request("POST", `/monitors/${id}/check-now`),
125
+ /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
126
+ * the monitor and start uptime over ("since reset"). The monitor and
127
+ * its configuration, alert rules, tags and locations stay. */
128
+ reset: (id) => this.request("POST", `/monitors/${id}/reset`),
125
129
  uptime: (id, period) => this.request("GET", `/monitors/${id}/uptime`, { query: { period } }),
126
130
  checks: (id, q) => this.request("GET", `/monitors/${id}/checks`, { query: q }),
127
131
  };
@@ -144,6 +148,12 @@ export class WatchFor {
144
148
  get: (id) => this.request("GET", `/incidents/${id}`),
145
149
  acknowledge: (id) => this.request("POST", `/incidents/${id}/acknowledge`),
146
150
  resolve: (id) => this.request("POST", `/incidents/${id}/resolve`),
151
+ /** Mark a RESOLVED incident as a false positive: kept on record, left
152
+ * out of uptime, SLA, reports and the public status page. 409 while
153
+ * the incident is still open. */
154
+ exclude: (id, body) => this.request("POST", `/incidents/${id}/exclude`, { body: body ?? {} }),
155
+ /** Undo `exclude` — the incident counts as downtime again. */
156
+ include: (id) => this.request("POST", `/incidents/${id}/include`),
147
157
  };
148
158
  // ── Maintenance windows ───────────────────────────────────────
149
159
  maintenanceWindows = {
package/dist/index.d.ts CHANGED
@@ -1 +1 @@
1
- export { type ActivityEvent, type AlertRule, type ApiErrorBody, type Check, type Contact, type ContactGroup, type Incident, type IncidentStats, type List, type MaintenanceWindow, type Monitor, type Notification, type Plan, type StatusPage, type Summary, type Uptime, WatchFor, WatchForError, type WatchForOptions, } from "./client.js";
1
+ export { type ActivityEvent, type AlertRule, type ApiErrorBody, type Check, type Contact, type ContactGroup, type Incident, type IncidentStats, type List, type MaintenanceWindow, type Monitor, type MonitorReset, type Notification, type Plan, type StatusPage, type Summary, type Uptime, WatchFor, WatchForError, type WatchForOptions, } from "./client.js";
package/dist/schema.d.ts CHANGED
@@ -180,6 +180,26 @@ export interface paths {
180
180
  patch?: never;
181
181
  trace?: never;
182
182
  };
183
+ "/monitors/{id}/reset": {
184
+ parameters: {
185
+ query?: never;
186
+ header?: never;
187
+ path?: never;
188
+ cookie?: never;
189
+ };
190
+ get?: never;
191
+ put?: never;
192
+ /**
193
+ * Reset history — delete every check, incident, note and post-mortem of the monitor and start uptime over (irreversible)
194
+ * @description The monitor keeps its id, configuration, alert rules, tags, locations and status-page membership. Everything it recorded is deleted: check and latency history, incidents with their timelines and delivery history, internal notes, post-mortems and the auto-published status-page incidents. Uptime is measured from the reset (the dashboard says 'since reset'). Owner/admin action in the dashboard; write scope here.
195
+ */
196
+ post: operations["resetMonitorHistory"];
197
+ delete?: never;
198
+ options?: never;
199
+ head?: never;
200
+ patch?: never;
201
+ trace?: never;
202
+ };
183
203
  "/monitors/{id}/uptime": {
184
204
  parameters: {
185
205
  query?: never;
@@ -187,7 +207,7 @@ export interface paths {
187
207
  path?: never;
188
208
  cookie?: never;
189
209
  };
190
- /** Uptime % and response-time stats (maintenance excluded) */
210
+ /** Uptime (confirmed critical incidents only), check success and response-time stats (maintenance excluded) */
191
211
  get: operations["getMonitorUptime"];
192
212
  put?: never;
193
213
  post?: never;
@@ -243,7 +263,7 @@ export interface paths {
243
263
  get: operations["getAlertRule"];
244
264
  put?: never;
245
265
  post?: never;
246
- /** Delete an alert rule (system rules → 409) */
266
+ /** Delete an alert rule (system rules → 403) */
247
267
  delete: operations["deleteAlertRule"];
248
268
  options?: never;
249
269
  head?: never;
@@ -336,6 +356,40 @@ export interface paths {
336
356
  patch?: never;
337
357
  trace?: never;
338
358
  };
359
+ "/incidents/{id}/exclude": {
360
+ parameters: {
361
+ query?: never;
362
+ header?: never;
363
+ path?: never;
364
+ cookie?: never;
365
+ };
366
+ get?: never;
367
+ put?: never;
368
+ /** Mark a resolved incident as a false positive — kept on record, excluded from uptime, SLA, reports and the public status page */
369
+ post: operations["excludeIncidentFromUptime"];
370
+ delete?: never;
371
+ options?: never;
372
+ head?: never;
373
+ patch?: never;
374
+ trace?: never;
375
+ };
376
+ "/incidents/{id}/include": {
377
+ parameters: {
378
+ query?: never;
379
+ header?: never;
380
+ path?: never;
381
+ cookie?: never;
382
+ };
383
+ get?: never;
384
+ put?: never;
385
+ /** Undo a false-positive mark — the incident counts as downtime again */
386
+ post: operations["includeIncidentInUptime"];
387
+ delete?: never;
388
+ options?: never;
389
+ head?: never;
390
+ patch?: never;
391
+ trace?: never;
392
+ };
339
393
  "/incidents/{id}/mark-maintenance": {
340
394
  parameters: {
341
395
  query?: never;
@@ -657,6 +711,40 @@ export interface paths {
657
711
  patch?: never;
658
712
  trace?: never;
659
713
  };
714
+ "/reports/schedules": {
715
+ parameters: {
716
+ query?: never;
717
+ header?: never;
718
+ path?: never;
719
+ cookie?: never;
720
+ };
721
+ /** The organization's two report-email cadences (weekly + monthly) with their recipients and enabled state */
722
+ get: operations["listReportSchedules"];
723
+ put?: never;
724
+ post?: never;
725
+ delete?: never;
726
+ options?: never;
727
+ head?: never;
728
+ patch?: never;
729
+ trace?: never;
730
+ };
731
+ "/reports/schedules/{frequency}": {
732
+ parameters: {
733
+ query?: never;
734
+ header?: never;
735
+ path?: never;
736
+ cookie?: never;
737
+ };
738
+ get?: never;
739
+ put?: never;
740
+ post?: never;
741
+ delete?: never;
742
+ options?: never;
743
+ head?: never;
744
+ /** Enable/disable the weekly or monthly report email and/or set its recipients (up to 5). Enabling needs at least one recipient; clearing the list disables the cadence; adding the first recipient to an empty, disabled cadence enables it automatically. */
745
+ patch: operations["updateReportSchedule"];
746
+ trace?: never;
747
+ };
660
748
  }
661
749
  export type webhooks = Record<string, never>;
662
750
  export interface components {
@@ -688,8 +776,11 @@ export interface components {
688
776
  target?: string;
689
777
  description?: string | null;
690
778
  interval_seconds?: number;
691
- /** @enum {string} */
692
- status?: "up" | "down" | "paused" | "unknown";
779
+ /**
780
+ * @description Effective status. down = a confirmed critical incident is open (firing or acknowledged); degraded = a failed check not yet confirmed, or an open warning incident; unknown = no check data yet. paused always wins.
781
+ * @enum {string}
782
+ */
783
+ status?: "up" | "degraded" | "down" | "paused" | "unknown";
693
784
  active?: boolean;
694
785
  /** @enum {string} */
695
786
  scheduling_strategy?: "roundrobin" | "random" | "parallel";
@@ -699,22 +790,29 @@ export interface components {
699
790
  config?: Record<string, never>;
700
791
  /** Format: date-time */
701
792
  created_at?: string;
793
+ /**
794
+ * Format: date-time
795
+ * @description Set by POST /monitors/{id}/reset; uptime windows start here instead of at created_at
796
+ */
797
+ history_reset_at?: string | null;
702
798
  /** Format: date-time */
703
799
  updated_at?: string;
704
800
  };
705
801
  MonitorCreate: {
706
802
  name: string;
803
+ /** @description http, api, dns, tcp, ssl, udp, icmp, mtr, smtp, ftp, sftp, websocket, rdap, blacklist, ntp, email_policy, sitemap, favicon, cdn, breach, brotli, cms, browser, heartbeat, mcp */
707
804
  type: string;
708
805
  target: string;
709
- /** @description Seconds */
806
+ /** @description Seconds; validated against the plan's per-type minimum */
710
807
  interval: number;
711
- /** @description Location ids from GET /locations; required except for heartbeat */
808
+ /** @description Location ids from GET /locations; at least one is required except for heartbeat (which takes none) */
712
809
  locations?: string[];
713
810
  /**
714
811
  * @default roundrobin
715
812
  * @enum {string}
716
813
  */
717
814
  schedulingStrategy: "roundrobin" | "random" | "parallel";
815
+ /** @description Lowercase alphanumeric with hyphens or colons, e.g. prod, team:web */
718
816
  tags?: string[];
719
817
  description?: string;
720
818
  config?: Record<string, never>;
@@ -726,7 +824,8 @@ export interface components {
726
824
  target?: string;
727
825
  description?: string;
728
826
  interval?: number;
729
- schedulingStrategy?: string;
827
+ /** @enum {string} */
828
+ schedulingStrategy?: "roundrobin" | "random" | "parallel";
730
829
  locations?: string[];
731
830
  tags?: string[];
732
831
  config?: Record<string, never>;
@@ -738,7 +837,12 @@ export interface components {
738
837
  monitor_id?: string;
739
838
  /** @enum {string} */
740
839
  period?: "1h" | "24h" | "7d" | "30d" | "90d";
840
+ /** @description Incident-based uptime: 100 − share of the period inside confirmed critical incidents; scheduled maintenance is neutral and the window is clamped to the monitor's creation time. Failed checks that never became a confirmed incident do not reduce it. null only before the monitor existed. */
741
841
  uptime_percent?: number | null;
842
+ /** @description Milliseconds inside confirmed critical incidents this period, maintenance excluded */
843
+ downtime_ms?: number;
844
+ /** @description Successful ÷ total checks over the period (maintenance excluded); null when the period has no checks */
845
+ check_success_percent?: number | null;
742
846
  total_checks?: number;
743
847
  successful_checks?: number;
744
848
  failed_checks?: number;
@@ -746,6 +850,7 @@ export interface components {
746
850
  min_response_time_ms?: number | null;
747
851
  max_response_time_ms?: number | null;
748
852
  last_failure_at?: string | null;
853
+ /** @description Incident-based headline uptime for the last 24 hours */
749
854
  uptime_24h?: number | null;
750
855
  uptime_7d?: number | null;
751
856
  uptime_30d?: number | null;
@@ -780,7 +885,7 @@ export interface components {
780
885
  operator?: string;
781
886
  value?: string;
782
887
  /** @enum {string} */
783
- severity?: "critical" | "warning" | "info";
888
+ severity?: "critical" | "warning";
784
889
  failure_threshold?: number;
785
890
  min_failed_probes?: number;
786
891
  duration_window_seconds?: number;
@@ -804,7 +909,7 @@ export interface components {
804
909
  * @default critical
805
910
  * @enum {string}
806
911
  */
807
- severity: "critical" | "warning" | "info";
912
+ severity: "critical" | "warning";
808
913
  /** @default 1 */
809
914
  failureThreshold: number;
810
915
  /** @default 1 */
@@ -836,7 +941,15 @@ export interface components {
836
941
  status?: "firing" | "acknowledged" | "resolved";
837
942
  /** @enum {string} */
838
943
  severity?: "warning" | "critical";
944
+ /** @description Human-readable explanation of what failed, derived from the rule that fired (e.g. 'Received an unexpected HTTP status code (expected: 2xx, 3xx)'); the raw engine message only when no rule snapshot exists */
839
945
  message?: string;
946
+ /** @description Fire-time alert-rule snapshot — frozen when the incident opened, so later edits to the rule do not rewrite history. null only for old incidents without a snapshot. */
947
+ rule?: {
948
+ name?: string;
949
+ metric?: string;
950
+ operator?: string;
951
+ value?: string;
952
+ } | null;
840
953
  monitor?: {
841
954
  /** Format: uuid */
842
955
  id?: string;
@@ -846,6 +959,29 @@ export interface components {
846
959
  started_at?: string;
847
960
  acknowledged_at?: string | null;
848
961
  resolved_at?: string | null;
962
+ /** @description started_at → resolved_at in seconds; null while open */
963
+ duration_seconds?: number | null;
964
+ /** @description Marked as a false positive: the incident stays on record but is left out of uptime, SLA, reports and the public status page (POST /incidents/{id}/exclude) */
965
+ excluded_from_uptime?: boolean;
966
+ exclusion_reason?: string | null;
967
+ excluded_by?: string | null;
968
+ /** Format: date-time */
969
+ excluded_at?: string | null;
970
+ };
971
+ MonitorReset: {
972
+ /** @constant */
973
+ object?: "monitor_reset";
974
+ /** Format: uuid */
975
+ monitor_id?: string;
976
+ /** Format: date-time */
977
+ reset_at?: string;
978
+ incidents_deleted?: number;
979
+ postmortems_deleted?: number;
980
+ comments_deleted?: number;
981
+ status_page_incidents_deleted?: number;
982
+ check_history_deleted?: boolean;
983
+ /** @description Best-effort steps that failed (e.g. clickhouse); the reset marker is set regardless */
984
+ warnings?: string[];
849
985
  };
850
986
  MaintenanceWindow: {
851
987
  /** Format: uuid */
@@ -869,39 +1005,59 @@ export interface components {
869
1005
  /** Format: date-time */
870
1006
  created_at?: string;
871
1007
  };
1008
+ /** @description At least one of monitorIds / monitorTags is required. Status-page publishing (statusPageIds, autoPublish) is dashboard-only — sending either field returns 400 invalid_request. */
872
1009
  MaintenanceWindowCreate: {
873
1010
  name: string;
874
1011
  /** Format: date-time */
875
1012
  startsAt: string;
1013
+ /** @description 5 minutes to 30 days */
876
1014
  durationMinutes: number;
1015
+ /** @description Ids outside your organization are dropped, not rejected */
877
1016
  monitorIds?: string[];
1017
+ /** @description Tag targeting also covers monitors that get the tag later; unions with monitorIds */
878
1018
  monitorTags?: string[];
879
1019
  description?: string;
880
- /** @default UTC */
1020
+ /**
1021
+ * @description IANA name used to interpret recurring start times
1022
+ * @default UTC
1023
+ */
881
1024
  timezone: string;
882
1025
  /**
883
1026
  * @default once
884
1027
  * @enum {string}
885
1028
  */
886
1029
  recurrence: "once" | "daily" | "weekly" | "monthly";
887
- /** Format: date-time */
1030
+ /**
1031
+ * Format: date-time
1032
+ * @description Must be after startsAt
1033
+ */
888
1034
  recurrenceUntil?: string;
889
1035
  /** @default true */
890
1036
  suppressAlerts: boolean;
891
- /** @default true */
1037
+ /**
1038
+ * @description Show the Maintenance badge on covered monitors while active
1039
+ * @default true
1040
+ */
1041
+ markMaintenance: boolean;
1042
+ /**
1043
+ * @description Exclude the window's time from uptime/SLA
1044
+ * @default true
1045
+ */
892
1046
  excludeFromSla: boolean;
893
1047
  };
1048
+ /** @description Partial update. timezone and recurrence cannot be changed after creation — delete and recreate the window instead. */
894
1049
  MaintenanceWindowUpdate: {
895
1050
  name?: string;
1051
+ description?: string | null;
896
1052
  /** Format: date-time */
897
1053
  startsAt?: string;
898
1054
  durationMinutes?: number;
899
1055
  monitorIds?: string[];
900
1056
  monitorTags?: string[];
901
- description?: string;
902
- timezone?: string;
903
- /** @enum {string} */
904
- recurrence?: "once" | "daily" | "weekly" | "monthly";
1057
+ suppressAlerts?: boolean;
1058
+ excludeFromSla?: boolean;
1059
+ /** @description false disables the window without deleting it (no further occurrences activate) */
1060
+ enabled?: boolean;
905
1061
  };
906
1062
  AlertRuleUpdate: {
907
1063
  name?: string;
@@ -909,7 +1065,7 @@ export interface components {
909
1065
  operator?: string;
910
1066
  value?: string;
911
1067
  /** @enum {string} */
912
- severity?: "critical" | "warning" | "info";
1068
+ severity?: "critical" | "warning";
913
1069
  failureThreshold?: number;
914
1070
  minFailedProbes?: number;
915
1071
  /** @description Seconds */
@@ -931,68 +1087,76 @@ export interface components {
931
1087
  name?: string;
932
1088
  contactIds?: string[];
933
1089
  };
1090
+ /** @description Password protection, logo upload and custom subdomains are dashboard-only. */
934
1091
  StatusPageCreate: {
1092
+ /** @description Lowercase letters, numbers and dashes; globally unique across WatchFor (409 when taken) */
935
1093
  slug: string;
936
1094
  name: string;
937
1095
  description?: string;
938
1096
  /** @default true */
939
1097
  isPublic: boolean;
940
- password?: string | null;
941
- /** @default true */
1098
+ /**
1099
+ * @description Confirmed incidents on component monitors appear on the page automatically
1100
+ * @default true
1101
+ */
942
1102
  autoPublishIncidents: boolean;
943
1103
  /** @default false */
944
1104
  dimUntrackedDays: boolean;
945
- logoPath?: string;
946
- /**
947
- * @default left
948
- * @enum {string}
949
- */
950
- logoPosition: "left" | "center" | "right";
951
1105
  /**
952
1106
  * @default auto
953
1107
  * @enum {string}
954
1108
  */
955
1109
  theme: "light" | "dark" | "auto";
1110
+ /**
1111
+ * @description Components in display order (position = array index); monitor ids outside your organization are dropped, not rejected
1112
+ * @default []
1113
+ */
1114
+ components: {
1115
+ name: string;
1116
+ description?: string;
1117
+ /** @default [] */
1118
+ monitorIds: string[];
1119
+ /** @default [] */
1120
+ monitorTags: string[];
1121
+ }[];
956
1122
  };
1123
+ /** @description Partial update. Component editing, password protection and logo upload are dashboard-only. A slug change re-checks uniqueness (409) and the old URL stops serving immediately. */
957
1124
  StatusPageUpdate: {
958
1125
  slug?: string;
959
1126
  name?: string;
960
1127
  description?: string | null;
961
1128
  isPublic?: boolean;
962
- password?: string | null;
963
1129
  autoPublishIncidents?: boolean;
964
1130
  dimUntrackedDays?: boolean;
965
- logoPath?: string | null;
966
- /** @enum {string} */
967
- logoPosition?: "left" | "center" | "right";
968
1131
  /** @enum {string} */
969
1132
  theme?: "light" | "dark" | "auto";
970
1133
  };
1134
+ /** @description Manual incident notice on the page (type is always incident; maintenance notices come from maintenance windows). */
971
1135
  AnnouncementCreate: {
972
1136
  title: string;
1137
+ /** @description Becomes the first timeline entry */
973
1138
  body: string;
974
1139
  /**
975
- * @default incident
1140
+ * @default investigating
976
1141
  * @enum {string}
977
1142
  */
978
- type: "incident" | "maintenance";
1143
+ status: "investigating" | "identified" | "monitoring" | "resolved";
979
1144
  /**
980
1145
  * @default minor
981
1146
  * @enum {string}
982
1147
  */
983
1148
  severity: "minor" | "major" | "critical";
984
- affectedComponentIds?: string[];
985
- affectedMonitorIds?: string[];
1149
+ /**
1150
+ * @description Component ids of this page; any other id returns 400
1151
+ * @default []
1152
+ */
1153
+ affectedComponentIds: string[];
986
1154
  };
1155
+ /** @description PATCH = post an update: appends an entry to the public timeline and moves the announcement to `status`; resolved closes it and sets resolved_at. Title and severity edits are dashboard-only. */
987
1156
  AnnouncementUpdate: {
988
- title?: string;
989
- body?: string;
990
- /** @enum {string} */
991
- type?: "incident" | "maintenance";
1157
+ body: string;
992
1158
  /** @enum {string} */
993
- severity?: "minor" | "major" | "critical";
994
- affectedComponentIds?: string[];
995
- affectedMonitorIds?: string[];
1159
+ status: "investigating" | "identified" | "monitoring" | "resolved";
996
1160
  };
997
1161
  Contact: {
998
1162
  /** Format: uuid */
@@ -1186,10 +1350,24 @@ export interface components {
1186
1350
  Summary: {
1187
1351
  /** @constant */
1188
1352
  object?: "summary";
1189
- /** @description Status counts (up/down/paused/unknown) + health_score 0-100 */
1190
- monitors?: Record<string, never>;
1191
- /** @description Active incident counts (firing/acknowledged, by severity) + started_24h */
1192
- incidents?: Record<string, never>;
1353
+ /** @description Effective-status counts — same rule as the dashboard: an open critical incident flips a stale up/unknown to down; an open warning incident or an unconfirmed failed check counts as degraded; paused always wins. health_score is 0-100 (share of active, non-paused monitors that are up). */
1354
+ monitors?: {
1355
+ total?: number;
1356
+ up?: number;
1357
+ degraded?: number;
1358
+ down?: number;
1359
+ paused?: number;
1360
+ unknown?: number;
1361
+ health_score?: number;
1362
+ };
1363
+ /** @description Open incident counts (firing, split by severity, and acknowledged) plus incidents started in the last 24h */
1364
+ incidents?: {
1365
+ firing?: number;
1366
+ firing_critical?: number;
1367
+ firing_warning?: number;
1368
+ acknowledged?: number;
1369
+ started_24h?: number;
1370
+ };
1193
1371
  open_maintenance_windows?: number;
1194
1372
  };
1195
1373
  IncidentStats: {
@@ -1208,7 +1386,17 @@ export interface components {
1208
1386
  counts?: Record<string, never>[];
1209
1387
  top_unstable_monitors?: Record<string, never>[];
1210
1388
  };
1211
- /** @description Org report for a period, always compared with the equal-length previous period. `compared` values carry {current, previous, delta}; previous/delta are null with no baseline. Depth follows the plan: basic omits type-aware sections (listed in gated_sections) and truncates monitors. */
1389
+ /** @description Scheduled report-email cadence (weekly or monthly). Every organization has exactly these two; recipients are capped at 5. suppressed_recipients lists addresses that unsubscribed themselves — kept on the list but skipped at send time. */
1390
+ ReportSchedule: {
1391
+ /** @constant */
1392
+ object?: "report_schedule";
1393
+ /** @enum {string} */
1394
+ frequency?: "weekly" | "monthly";
1395
+ enabled?: boolean;
1396
+ recipients?: string[];
1397
+ suppressed_recipients?: string[];
1398
+ };
1399
+ /** @description Org report for a period, always compared with the equal-length previous period. Compared values carry {current, previous, delta}; previous/delta are null with no baseline. Depth follows the plan: basic omits the type-aware sections (listed in gatedSections), withholds insights beyond a cap (gatedInsightCount) and truncates the monitors table. Field names are camelCase (the dashboard's report document), unlike the rest of the API. */
1212
1400
  Report: {
1213
1401
  /** @constant */
1214
1402
  object?: "report";
@@ -1226,7 +1414,7 @@ export interface components {
1226
1414
  depth?: "basic" | "advanced";
1227
1415
  typesPresent?: string[];
1228
1416
  };
1229
- /** @description uptimePct/incidents/criticalIncidents/downtimeMs as compared values; mttrMs/mtbfMs nullable; longestIncident; totalChecks; monitorsCovered */
1417
+ /** @description uptimePct (incident-based: confirmed critical incidents only, maintenance neutral, weighted by observed time) / checkSuccessPct (successful ÷ total checks) / incidents / criticalIncidents / downtimeMs as compared values; mttrMs/mttaMs/mtbfMs nullable; longestIncident; totalChecks; monitorsCovered */
1230
1418
  summary?: Record<string, never>;
1231
1419
  /** @description Fleet avg/min/max ms + slow-check count over latency-style monitor types */
1232
1420
  responseTime?: Record<string, never> | null;
@@ -1235,23 +1423,36 @@ export interface components {
1235
1423
  monitorId?: string;
1236
1424
  name?: string;
1237
1425
  type?: string;
1426
+ /** @description Incident-based, same formula as the monitor's Uptime card */
1238
1427
  uptimePct?: Record<string, never>;
1428
+ downtimeMs?: number;
1429
+ checkSuccessPct?: number;
1239
1430
  avgMs?: number;
1240
1431
  p95Ms?: number;
1241
1432
  incidents?: number;
1242
1433
  hadMaintenance?: boolean;
1243
1434
  }[];
1244
1435
  totalMonitors?: number;
1245
- /** @description Type-aware sections keyed ssl/domains/cwv/heartbeat/blacklist/mcp — only for types the org monitors, advanced depth only */
1436
+ /** @description Type-aware sections keyed locations/ssl/domains/cwv/heartbeat/blacklist/mcp — only the keys the org's monitors produce (locations needs latency-style monitors), advanced depth only */
1246
1437
  sections?: Record<string, never>;
1247
- /** @description Sections that exist but are locked by the plan */
1248
- gated_sections?: string[];
1438
+ /** @description Sections that exist for this org's monitors but are locked by the plan (empty on advanced depth) */
1439
+ gatedSections?: (
1440
+ | "locations"
1441
+ | "ssl"
1442
+ | "domains"
1443
+ | "cwv"
1444
+ | "heartbeat"
1445
+ | "blacklist"
1446
+ | "mcp"
1447
+ )[];
1249
1448
  /** @description Plain-language findings, most severe first, tone good|warning|critical|neutral */
1250
1449
  insights?: {
1251
1450
  tone?: string;
1252
1451
  text?: string;
1253
1452
  monitorId?: string;
1254
1453
  }[];
1454
+ /** @description Insights withheld beyond the plan's cap (0 on advanced depth) */
1455
+ gatedInsightCount?: number;
1255
1456
  };
1256
1457
  OncallSchedule: {
1257
1458
  id?: number;
@@ -1355,6 +1556,12 @@ export interface components {
1355
1556
  data: components["schemas"]["ActivityEvent"][];
1356
1557
  has_more: boolean;
1357
1558
  };
1559
+ ReportScheduleList: {
1560
+ /** @constant */
1561
+ object: "list";
1562
+ data: components["schemas"]["ReportSchedule"][];
1563
+ has_more: boolean;
1564
+ };
1358
1565
  };
1359
1566
  responses: never;
1360
1567
  parameters: never;
@@ -1471,7 +1678,8 @@ export interface operations {
1471
1678
  limit?: number;
1472
1679
  cursor?: string;
1473
1680
  type?: string;
1474
- status?: string;
1681
+ /** @description Effective status: down = confirmed critical incident open; degraded = failed check not yet confirmed, or an open warning incident */
1682
+ status?: "up" | "degraded" | "down" | "paused" | "unknown";
1475
1683
  tag?: string;
1476
1684
  /** @description Case-insensitive substring search over name and target */
1477
1685
  q?: string;
@@ -1783,6 +1991,41 @@ export interface operations {
1783
1991
  };
1784
1992
  };
1785
1993
  };
1994
+ resetMonitorHistory: {
1995
+ parameters: {
1996
+ query?: never;
1997
+ header?: {
1998
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
1999
+ "Idempotency-Key"?: string;
2000
+ };
2001
+ path: {
2002
+ /** @description Resource id (UUID) */
2003
+ id: string;
2004
+ };
2005
+ cookie?: never;
2006
+ };
2007
+ requestBody?: never;
2008
+ responses: {
2009
+ /** @description History deleted; counts of what went */
2010
+ 200: {
2011
+ headers: {
2012
+ [name: string]: unknown;
2013
+ };
2014
+ content: {
2015
+ "application/json": components["schemas"]["MonitorReset"];
2016
+ };
2017
+ };
2018
+ /** @description Error */
2019
+ default: {
2020
+ headers: {
2021
+ [name: string]: unknown;
2022
+ };
2023
+ content: {
2024
+ "application/json": components["schemas"]["Error"];
2025
+ };
2026
+ };
2027
+ };
2028
+ };
1786
2029
  getMonitorUptime: {
1787
2030
  parameters: {
1788
2031
  query?: {
@@ -1822,6 +2065,8 @@ export interface operations {
1822
2065
  query?: {
1823
2066
  hours?: number;
1824
2067
  limit?: number;
2068
+ /** @description true = only passing checks, false = only failed checks (one-call failure forensics); omit for all. The per-location breakdown ignores this filter. */
2069
+ success?: boolean;
1825
2070
  };
1826
2071
  header?: never;
1827
2072
  path: {
@@ -2210,6 +2455,92 @@ export interface operations {
2210
2455
  };
2211
2456
  };
2212
2457
  };
2458
+ excludeIncidentFromUptime: {
2459
+ parameters: {
2460
+ query?: never;
2461
+ header?: {
2462
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
2463
+ "Idempotency-Key"?: string;
2464
+ };
2465
+ path: {
2466
+ /** @description Incident id (integer) */
2467
+ id: string;
2468
+ };
2469
+ cookie?: never;
2470
+ };
2471
+ requestBody?: {
2472
+ content: {
2473
+ "application/json": {
2474
+ /** @description Why this was not real downtime */
2475
+ reason?: string;
2476
+ };
2477
+ };
2478
+ };
2479
+ responses: {
2480
+ /** @description Incident with excluded_from_uptime = true */
2481
+ 200: {
2482
+ headers: {
2483
+ [name: string]: unknown;
2484
+ };
2485
+ content: {
2486
+ "application/json": components["schemas"]["Incident"];
2487
+ };
2488
+ };
2489
+ /** @description Incident is still open — resolve it first */
2490
+ 409: {
2491
+ headers: {
2492
+ [name: string]: unknown;
2493
+ };
2494
+ content: {
2495
+ "application/json": components["schemas"]["Error"];
2496
+ };
2497
+ };
2498
+ /** @description Error */
2499
+ default: {
2500
+ headers: {
2501
+ [name: string]: unknown;
2502
+ };
2503
+ content: {
2504
+ "application/json": components["schemas"]["Error"];
2505
+ };
2506
+ };
2507
+ };
2508
+ };
2509
+ includeIncidentInUptime: {
2510
+ parameters: {
2511
+ query?: never;
2512
+ header?: {
2513
+ /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
2514
+ "Idempotency-Key"?: string;
2515
+ };
2516
+ path: {
2517
+ /** @description Incident id (integer) */
2518
+ id: string;
2519
+ };
2520
+ cookie?: never;
2521
+ };
2522
+ requestBody?: never;
2523
+ responses: {
2524
+ /** @description Incident with excluded_from_uptime = false */
2525
+ 200: {
2526
+ headers: {
2527
+ [name: string]: unknown;
2528
+ };
2529
+ content: {
2530
+ "application/json": components["schemas"]["Incident"];
2531
+ };
2532
+ };
2533
+ /** @description Error */
2534
+ default: {
2535
+ headers: {
2536
+ [name: string]: unknown;
2537
+ };
2538
+ content: {
2539
+ "application/json": components["schemas"]["Error"];
2540
+ };
2541
+ };
2542
+ };
2543
+ };
2213
2544
  markIncidentMaintenance: {
2214
2545
  parameters: {
2215
2546
  query?: never;
@@ -3081,7 +3412,7 @@ export interface operations {
3081
3412
  };
3082
3413
  cookie?: never;
3083
3414
  };
3084
- requestBody?: {
3415
+ requestBody: {
3085
3416
  content: {
3086
3417
  "application/json": components["schemas"]["AnnouncementUpdate"];
3087
3418
  };
@@ -3312,6 +3643,20 @@ export interface operations {
3312
3643
  from?: string;
3313
3644
  /** @description Custom period end (ISO 8601 or Unix epoch) */
3314
3645
  to?: string;
3646
+ /** @description Comma-separated monitor IDs to scope the report to (advanced-reports plans). Combined with `tags` as a union. */
3647
+ monitor_ids?: string;
3648
+ /** @description Comma-separated monitor tags to scope the report to (advanced-reports plans) */
3649
+ tags?: string;
3650
+ /** @description Comma-separated subset of type-aware sections to generate: locations,ssl,domains,cwv,heartbeat,blacklist,mcp (advanced-reports plans; omit for all) */
3651
+ sections?: string;
3652
+ /** @description Set false to drop the response-time block */
3653
+ response_time?: boolean;
3654
+ /** @description Set false to drop the per-monitor table */
3655
+ monitors_table?: boolean;
3656
+ /** @description Set false to drop the insights block */
3657
+ insights?: boolean;
3658
+ /** @description Comma-separated subset of acknowledged, resolved, open (or `all`). Filters incident aggregates (counts, MTTR/MTTA, downtime, per-monitor column) to incidents in any selected state; uptime stays check-based (advanced-reports plans) */
3659
+ incident_status?: string;
3315
3660
  };
3316
3661
  header?: never;
3317
3662
  path?: never;
@@ -3339,4 +3684,71 @@ export interface operations {
3339
3684
  };
3340
3685
  };
3341
3686
  };
3687
+ listReportSchedules: {
3688
+ parameters: {
3689
+ query?: never;
3690
+ header?: never;
3691
+ path?: never;
3692
+ cookie?: never;
3693
+ };
3694
+ requestBody?: never;
3695
+ responses: {
3696
+ /** @description Both cadences, weekly first */
3697
+ 200: {
3698
+ headers: {
3699
+ [name: string]: unknown;
3700
+ };
3701
+ content: {
3702
+ "application/json": components["schemas"]["ReportScheduleList"];
3703
+ };
3704
+ };
3705
+ /** @description Error */
3706
+ default: {
3707
+ headers: {
3708
+ [name: string]: unknown;
3709
+ };
3710
+ content: {
3711
+ "application/json": components["schemas"]["Error"];
3712
+ };
3713
+ };
3714
+ };
3715
+ };
3716
+ updateReportSchedule: {
3717
+ parameters: {
3718
+ query?: never;
3719
+ header?: never;
3720
+ path: {
3721
+ frequency: "weekly" | "monthly";
3722
+ };
3723
+ cookie?: never;
3724
+ };
3725
+ requestBody: {
3726
+ content: {
3727
+ "application/json": {
3728
+ enabled?: boolean;
3729
+ recipients?: string[];
3730
+ };
3731
+ };
3732
+ };
3733
+ responses: {
3734
+ /** @description OK */
3735
+ 200: {
3736
+ headers: {
3737
+ [name: string]: unknown;
3738
+ };
3739
+ content: {
3740
+ "application/json": components["schemas"]["ReportSchedule"];
3741
+ };
3742
+ };
3743
+ /** @description Error */
3744
+ default: {
3745
+ headers: {
3746
+ [name: string]: unknown;
3747
+ };
3748
+ content: {
3749
+ "application/json": components["schemas"]["Error"];
3750
+ };
3751
+ };
3752
+ };
3753
+ };
3342
3754
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Official TypeScript SDK + CLI for WatchFor \u2014 uptime & infrastructure monitoring (monitors, alert rules, incidents, maintenance windows) over the REST API.",
5
5
  "keywords": [
6
6
  "watchfor",
@@ -40,7 +40,8 @@
40
40
  "scripts": {
41
41
  "build": "tsc -p tsconfig.json && cp src/schema.d.ts dist/schema.d.ts",
42
42
  "prepublishOnly": "npm run build",
43
- "regen-types": "openapi-typescript https://watchfor.io/openapi.json -o src/schema.d.ts"
43
+ "regen-types": "openapi-typescript ${SPEC:-https://watchfor.io/openapi.json} -o src/schema.d.ts",
44
+ "regen-types:local": "node scripts/dump-spec.mjs > /tmp/watchfor-openapi.json && openapi-typescript /tmp/watchfor-openapi.json -o src/schema.d.ts"
44
45
  },
45
46
  "devDependencies": {
46
47
  "@types/node": "^22.0.0",