watchfor 0.4.0 → 0.7.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
@@ -23,7 +23,7 @@ const monitor = await wf.monitors.create({
23
23
  target: "https://example.com",
24
24
  interval: 60,
25
25
  locations: ["<location-id from wf.locations()>"],
26
- });
26
+ }, "create-example-1"); // optional idempotency key — safe retries
27
27
  await wf.alertRules.create(monitor.id!, {
28
28
  name: "Slow response",
29
29
  metric: "response_time",
@@ -31,12 +31,57 @@ 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!);
41
+
42
+ // Older checks: pass next_cursor back as cursor (keep the same hours/success).
43
+ const page = await wf.monitors.checks(monitor.id!, { hours: 24, limit: 100 });
44
+ if (page.next_cursor) {
45
+ await wf.monitors.checks(monitor.id!, { hours: 24, limit: 100, cursor: page.next_cursor });
46
+ }
47
+
48
+ // Delete a contact group that alert rules still use (409 without force).
49
+ await wf.contactGroups.delete("<group-id>", { force: true });
50
+ ```
51
+
52
+ ### Live diagnostics
53
+
54
+ Run any of 18 checks from WatchFor's probe fleet against **any public
55
+ target**, monitored or not — this measures right now, rather than reading
56
+ what WatchFor recorded:
57
+
58
+ ```ts
59
+ // What can I run, and how much budget is left?
60
+ const catalog = await wf.diagnostics.list();
61
+
62
+ // One check, from a location you choose (plan-gated).
63
+ const dns = await wf.diagnostics.run("dns-lookup", {
64
+ target: "example.com",
65
+ options: { recordType: "A", resolver: "8.8.8.8" },
66
+ });
67
+ // A closed port / NXDOMAIN / failed handshake does NOT throw:
68
+ if (!dns.success) console.log("finding:", dns.error);
69
+ console.log("runs left this hour:", dns.remaining);
70
+
71
+ // The whole picture in one call: DNS + propagation + TLS + HTTP + ping
72
+ // from up to 3 regions, aggregated into one verdict.
73
+ const report = await wf.diagnostics.diagnoseTarget({ target: "example.com" });
74
+ console.log(report.verdict.status, report.verdict.summary);
34
75
  ```
35
76
 
77
+ Runs need a **read+write** key (a probe sends real traffic from WatchFor's
78
+ IPs) and spend the same per-plan hourly allowance as the dashboard
79
+ Toolbox. Details: https://watchfor.io/docs/api/diagnostics
80
+
36
81
  - Fully typed from the [OpenAPI spec](https://watchfor.io/openapi.json)
37
82
  - Zero runtime dependencies (uses global `fetch`, Node ≥ 18)
38
83
  - `WatchForError` carries `status`, `code` and `retryAfterSeconds`
39
- - Pass an `idempotencyKey` to any create call for safe retries
84
+ - Pass an idempotency key as the second argument of any `create` call for safe retries
40
85
 
41
86
  ## CLI
42
87
 
@@ -45,12 +90,12 @@ export WATCHFOR_API_KEY=wf_live_...
45
90
  npx watchfor summary
46
91
  npx watchfor incidents --status firing
47
92
  npx watchfor monitors example.com
48
- npx watchfor checks <monitor-id> --failed
93
+ npx watchfor checks <monitor-id> --failed # add --cursor <next_cursor> for older pages
49
94
  npx watchfor report --period 30d
50
95
  ```
51
96
 
52
97
  ## Links
53
98
 
54
99
  - API docs: https://watchfor.io/docs/api
55
- - MCP server for AI agents (40 tools): https://watchfor.io/docs/api/mcp
100
+ - MCP server for AI agents (45 tools): https://watchfor.io/docs/api/mcp
56
101
  - Create an API key: dashboard → Settings → API keys (`read` or `read+write` scope)
package/dist/cli.js CHANGED
@@ -15,8 +15,9 @@ Usage:
15
15
  watchfor summary Org snapshot: what's up/down right now
16
16
  watchfor incidents [--status s] List incidents (firing|acknowledged|resolved)
17
17
  watchfor monitors [query] List monitors (optional name/target search)
18
- watchfor checks <monitor-id> [--failed]
18
+ watchfor checks <monitor-id> [--failed] [--cursor c]
19
19
  Recent probe results for one monitor
20
+ (prints the next_cursor for older pages)
20
21
  watchfor report [--period 7d|30d] Org report vs the previous period
21
22
  watchfor help
22
23
 
@@ -95,13 +96,14 @@ async function main() {
95
96
  case "checks": {
96
97
  const id = args.find((a) => !a.startsWith("--"));
97
98
  if (!id) {
98
- console.error("Usage: watchfor checks <monitor-id> [--failed]");
99
+ console.error("Usage: watchfor checks <monitor-id> [--failed] [--cursor c]");
99
100
  return 1;
100
101
  }
101
102
  const failed = flag(args, "failed") === "true";
102
103
  const res = await wf.monitors.checks(id, {
103
104
  success: failed ? false : undefined,
104
105
  limit: 25,
106
+ cursor: flag(args, "cursor"),
105
107
  });
106
108
  for (const c of res.data) {
107
109
  const r = c;
@@ -109,6 +111,8 @@ async function main() {
109
111
  }
110
112
  if (res.data.length === 0)
111
113
  console.log("(no checks in window)");
114
+ if (res.next_cursor)
115
+ console.log(`older: --cursor ${res.next_cursor}`);
112
116
  return 0;
113
117
  }
114
118
  default:
package/dist/client.d.ts CHANGED
@@ -7,6 +7,9 @@ import type { components } from "./schema.js";
7
7
  * const summary = await wf.summary();
8
8
  */
9
9
  export type Monitor = components["schemas"]["Monitor"];
10
+ /** Monitor + `available_metrics` (GET /monitors/{id} only). */
11
+ export type MonitorDetail = components["schemas"]["MonitorDetail"];
12
+ export type MonitorReset = components["schemas"]["MonitorReset"];
10
13
  export type Incident = components["schemas"]["Incident"];
11
14
  export type AlertRule = components["schemas"]["AlertRule"];
12
15
  export type Contact = components["schemas"]["Contact"];
@@ -15,12 +18,25 @@ export type MaintenanceWindow = components["schemas"]["MaintenanceWindow"];
15
18
  export type StatusPage = components["schemas"]["StatusPage"];
16
19
  export type Uptime = components["schemas"]["Uptime"];
17
20
  export type Check = components["schemas"]["Check"];
21
+ export type CheckList = components["schemas"]["CheckList"];
22
+ export type CheckNowAck = components["schemas"]["CheckNowAck"];
18
23
  export type Plan = components["schemas"]["Plan"];
19
24
  export type Summary = components["schemas"]["Summary"];
20
25
  export type IncidentStats = components["schemas"]["IncidentStats"];
21
26
  export type ActivityEvent = components["schemas"]["ActivityEvent"];
22
27
  export type Notification = components["schemas"]["Notification"];
23
28
  export type ApiErrorBody = components["schemas"]["Error"];
29
+ /** Deletion confirmation — echoes the removed resource's id. */
30
+ export type Deleted = components["schemas"]["Deleted"];
31
+ /** Catalog of the live checks the probe fleet can run on demand. */
32
+ export type DiagnosticCatalog = components["schemas"]["DiagnosticCatalog"];
33
+ export type DiagnosticCatalogEntry = components["schemas"]["DiagnosticCatalogEntry"];
34
+ /** One completed diagnostic run — `success: false` is an answer, not an error. */
35
+ export type DiagnosticRun = components["schemas"]["DiagnosticRun"];
36
+ /** The `diagnose-target` bundle: a verdict plus a status per check. */
37
+ export type DiagnosticReport = components["schemas"]["DiagnosticReport"];
38
+ /** Which check to run — short aliases (`dns`, `port-check`, …) also work. */
39
+ export type DiagnosticSlug = components["schemas"]["DiagnosticRun"]["tool"];
24
40
  export interface List<T> {
25
41
  object: "list";
26
42
  data: T[];
@@ -91,26 +107,38 @@ export declare class WatchFor {
91
107
  limit?: number;
92
108
  cursor?: string;
93
109
  }) => Promise<List<Monitor>>;
94
- get: (id: string) => Promise<Monitor>;
110
+ /** The monitor plus `available_metrics` — the alert metrics valid for
111
+ * its type. */
112
+ get: (id: string) => Promise<MonitorDetail>;
95
113
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<Monitor>;
96
114
  update: (id: string, body: Record<string, unknown>) => Promise<Monitor>;
97
- delete: (id: string) => Promise<void>;
115
+ delete: (id: string) => Promise<Deleted>;
98
116
  pause: (id: string) => Promise<Monitor>;
99
117
  resume: (id: string) => Promise<Monitor>;
100
- checkNow: (id: string) => Promise<unknown>;
118
+ /** Dispatch one out-of-schedule check now (202); the result lands in
119
+ * `checks()` moments later. */
120
+ checkNow: (id: string) => Promise<CheckNowAck>;
121
+ /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
122
+ * the monitor and start uptime over ("since reset"). The monitor and
123
+ * its configuration, alert rules, tags and locations stay. */
124
+ reset: (id: string) => Promise<MonitorReset>;
101
125
  uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d") => Promise<Uptime>;
126
+ /** Recent probe results, newest first. Page with `next_cursor` →
127
+ * `cursor` (keep the same `hours`/`success`); `locations` is the
128
+ * per-location breakdown for the whole window. */
102
129
  checks: (id: string, q?: {
103
130
  hours?: number;
104
- success?: boolean;
105
131
  limit?: number;
106
- }) => Promise<List<Check>>;
132
+ success?: boolean;
133
+ cursor?: string;
134
+ }) => Promise<CheckList>;
107
135
  };
108
136
  readonly alertRules: {
109
137
  list: (monitorId: string) => Promise<List<AlertRule>>;
110
138
  get: (monitorId: string, ruleId: string) => Promise<AlertRule>;
111
139
  create: (monitorId: string, body: Record<string, unknown>, idempotencyKey?: string) => Promise<AlertRule>;
112
140
  update: (monitorId: string, ruleId: string, body: Record<string, unknown>) => Promise<AlertRule>;
113
- delete: (monitorId: string, ruleId: string) => Promise<void>;
141
+ delete: (monitorId: string, ruleId: string) => Promise<Deleted>;
114
142
  };
115
143
  readonly incidents: {
116
144
  list: (q?: {
@@ -123,8 +151,17 @@ export declare class WatchFor {
123
151
  cursor?: string;
124
152
  }) => Promise<List<Incident>>;
125
153
  get: (id: number) => Promise<Incident>;
154
+ /** Every action returns the full, updated Incident. */
126
155
  acknowledge: (id: number) => Promise<Incident>;
127
156
  resolve: (id: number) => Promise<Incident>;
157
+ /** Mark a RESOLVED incident as a false positive: kept on record, left
158
+ * out of uptime, SLA, reports and the public status page. 409 while
159
+ * the incident is still open. */
160
+ exclude: (id: number, body?: {
161
+ reason?: string;
162
+ }) => Promise<Incident>;
163
+ /** Undo `exclude` — the incident counts as downtime again. */
164
+ include: (id: number) => Promise<Incident>;
128
165
  };
129
166
  readonly maintenanceWindows: {
130
167
  list: (q?: {
@@ -134,7 +171,7 @@ export declare class WatchFor {
134
171
  get: (id: string) => Promise<MaintenanceWindow>;
135
172
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<MaintenanceWindow>;
136
173
  update: (id: string, body: Record<string, unknown>) => Promise<MaintenanceWindow>;
137
- delete: (id: string) => Promise<void>;
174
+ delete: (id: string) => Promise<Deleted>;
138
175
  };
139
176
  readonly contacts: {
140
177
  list: (q?: {
@@ -144,7 +181,7 @@ export declare class WatchFor {
144
181
  get: (id: string) => Promise<Contact>;
145
182
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<Contact>;
146
183
  update: (id: string, body: Record<string, unknown>) => Promise<Contact>;
147
- delete: (id: string) => Promise<void>;
184
+ delete: (id: string) => Promise<Deleted>;
148
185
  };
149
186
  readonly contactGroups: {
150
187
  list: (q?: {
@@ -154,7 +191,48 @@ export declare class WatchFor {
154
191
  get: (id: string) => Promise<ContactGroup>;
155
192
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<ContactGroup>;
156
193
  update: (id: string, body: Record<string, unknown>) => Promise<ContactGroup>;
157
- delete: (id: string) => Promise<void>;
194
+ /** 409 for the default group, and 409 while alert rules, monitors or
195
+ * notification channels still route through it — `force` deletes
196
+ * anyway (references are removed; affected alert rules fall back to
197
+ * their monitor's notification groups). */
198
+ delete: (id: string, opts?: {
199
+ force?: boolean;
200
+ }) => Promise<Deleted>;
201
+ };
202
+ /**
203
+ * Ad-hoc checks run from WatchFor's probe fleet against any public
204
+ * target — monitored or not. These MEASURE right now; the rest of the
205
+ * client reads what WatchFor already recorded.
206
+ *
207
+ * Runs need a **write**-scope key (a probe sends real traffic from
208
+ * WatchFor's IPs and spends a metered allowance) and each response
209
+ * carries `remaining` — the same per-plan hourly budget the dashboard
210
+ * Toolbox spends — plus `distinct_targets`, the hourly anti-scanner
211
+ * ceiling. A check that ran and found a problem (closed port,
212
+ * NXDOMAIN, failed handshake) resolves normally with
213
+ * `success: false`; only calls that could not run throw.
214
+ */
215
+ readonly diagnostics: {
216
+ /** Every check, the question it answers, its options and this org's
217
+ * remaining allowance. Read scope. */
218
+ list: () => Promise<DiagnosticCatalog>;
219
+ /** Run one check. `location_id` is honoured on plans whose
220
+ * `location_select` is true; otherwise the nearest probe is used
221
+ * and the response says which. Write scope. */
222
+ run: (slug: DiagnosticSlug | (string & {}), body: {
223
+ target: string;
224
+ options?: Record<string, unknown>;
225
+ location_id?: string;
226
+ }, idempotencyKey?: string) => Promise<DiagnosticRun>;
227
+ /** DNS, propagation, TLS grade, HTTP headers and ping from up to 3
228
+ * regions in one call, aggregated into a single verdict. Each
229
+ * underlying check spends its own allowance; needs a plan with
230
+ * location selection. Write scope. */
231
+ diagnoseTarget: (body: {
232
+ target: string;
233
+ max_locations?: number;
234
+ location_ids?: string[];
235
+ }, idempotencyKey?: string) => Promise<DiagnosticReport>;
158
236
  };
159
237
  /** Alerting delivery history — did the Slack/Telegram message go out? */
160
238
  notifications(q?: {
package/dist/client.js CHANGED
@@ -115,14 +115,25 @@ export class WatchFor {
115
115
  // ── Monitors ──────────────────────────────────────────────────
116
116
  monitors = {
117
117
  list: (q) => this.request("GET", "/monitors", { query: q }),
118
+ /** The monitor plus `available_metrics` — the alert metrics valid for
119
+ * its type. */
118
120
  get: (id) => this.request("GET", `/monitors/${id}`),
119
121
  create: (body, idempotencyKey) => this.request("POST", "/monitors", { body, idempotencyKey }),
120
122
  update: (id, body) => this.request("PATCH", `/monitors/${id}`, { body }),
121
123
  delete: (id) => this.request("DELETE", `/monitors/${id}`),
122
124
  pause: (id) => this.request("POST", `/monitors/${id}/pause`),
123
125
  resume: (id) => this.request("POST", `/monitors/${id}/resume`),
126
+ /** Dispatch one out-of-schedule check now (202); the result lands in
127
+ * `checks()` moments later. */
124
128
  checkNow: (id) => this.request("POST", `/monitors/${id}/check-now`),
129
+ /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
130
+ * the monitor and start uptime over ("since reset"). The monitor and
131
+ * its configuration, alert rules, tags and locations stay. */
132
+ reset: (id) => this.request("POST", `/monitors/${id}/reset`),
125
133
  uptime: (id, period) => this.request("GET", `/monitors/${id}/uptime`, { query: { period } }),
134
+ /** Recent probe results, newest first. Page with `next_cursor` →
135
+ * `cursor` (keep the same `hours`/`success`); `locations` is the
136
+ * per-location breakdown for the whole window. */
126
137
  checks: (id, q) => this.request("GET", `/monitors/${id}/checks`, { query: q }),
127
138
  };
128
139
  // ── Alert rules ───────────────────────────────────────────────
@@ -142,8 +153,15 @@ export class WatchFor {
142
153
  incidents = {
143
154
  list: (q) => this.request("GET", "/incidents", { query: q }),
144
155
  get: (id) => this.request("GET", `/incidents/${id}`),
156
+ /** Every action returns the full, updated Incident. */
145
157
  acknowledge: (id) => this.request("POST", `/incidents/${id}/acknowledge`),
146
158
  resolve: (id) => this.request("POST", `/incidents/${id}/resolve`),
159
+ /** Mark a RESOLVED incident as a false positive: kept on record, left
160
+ * out of uptime, SLA, reports and the public status page. 409 while
161
+ * the incident is still open. */
162
+ exclude: (id, body) => this.request("POST", `/incidents/${id}/exclude`, { body: body ?? {} }),
163
+ /** Undo `exclude` — the incident counts as downtime again. */
164
+ include: (id) => this.request("POST", `/incidents/${id}/include`),
147
165
  };
148
166
  // ── Maintenance windows ───────────────────────────────────────
149
167
  maintenanceWindows = {
@@ -166,7 +184,44 @@ export class WatchFor {
166
184
  get: (id) => this.request("GET", `/contact-groups/${id}`),
167
185
  create: (body, idempotencyKey) => this.request("POST", "/contact-groups", { body, idempotencyKey }),
168
186
  update: (id, body) => this.request("PATCH", `/contact-groups/${id}`, { body }),
169
- delete: (id) => this.request("DELETE", `/contact-groups/${id}`),
187
+ /** 409 for the default group, and 409 while alert rules, monitors or
188
+ * notification channels still route through it — `force` deletes
189
+ * anyway (references are removed; affected alert rules fall back to
190
+ * their monitor's notification groups). */
191
+ delete: (id, opts) => this.request("DELETE", `/contact-groups/${id}`, {
192
+ query: { force: opts?.force ? true : undefined },
193
+ }),
194
+ };
195
+ // ── Live diagnostics ──────────────────────────────────────────
196
+ /**
197
+ * Ad-hoc checks run from WatchFor's probe fleet against any public
198
+ * target — monitored or not. These MEASURE right now; the rest of the
199
+ * client reads what WatchFor already recorded.
200
+ *
201
+ * Runs need a **write**-scope key (a probe sends real traffic from
202
+ * WatchFor's IPs and spends a metered allowance) and each response
203
+ * carries `remaining` — the same per-plan hourly budget the dashboard
204
+ * Toolbox spends — plus `distinct_targets`, the hourly anti-scanner
205
+ * ceiling. A check that ran and found a problem (closed port,
206
+ * NXDOMAIN, failed handshake) resolves normally with
207
+ * `success: false`; only calls that could not run throw.
208
+ */
209
+ diagnostics = {
210
+ /** Every check, the question it answers, its options and this org's
211
+ * remaining allowance. Read scope. */
212
+ list: () => this.request("GET", "/diagnostics"),
213
+ /** Run one check. `location_id` is honoured on plans whose
214
+ * `location_select` is true; otherwise the nearest probe is used
215
+ * and the response says which. Write scope. */
216
+ run: (slug, body, idempotencyKey) => this.request("POST", `/diagnostics/${slug}`, { body, idempotencyKey }),
217
+ /** DNS, propagation, TLS grade, HTTP headers and ping from up to 3
218
+ * regions in one call, aggregated into a single verdict. Each
219
+ * underlying check spends its own allowance; needs a plan with
220
+ * location selection. Write scope. */
221
+ diagnoseTarget: (body, idempotencyKey) => this.request("POST", "/diagnostics/diagnose-target", {
222
+ body,
223
+ idempotencyKey,
224
+ }),
170
225
  };
171
226
  // ── Observability ─────────────────────────────────────────────
172
227
  /** Alerting delivery history — did the Slack/Telegram message go out? */
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 CheckList, type CheckNowAck, type Contact, type ContactGroup, type Deleted, type DiagnosticCatalog, type DiagnosticCatalogEntry, type DiagnosticReport, type DiagnosticRun, type DiagnosticSlug, type Incident, type IncidentStats, type List, type MaintenanceWindow, type Monitor, type MonitorDetail, type MonitorReset, type Notification, type Plan, type StatusPage, type Summary, type Uptime, WatchFor, WatchForError, type WatchForOptions, } from "./client.js";