watchfor 0.5.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",
@@ -38,12 +38,50 @@ await wf.incidents.exclude(19351, { reason: "Probe-side DNS hiccup" });
38
38
 
39
39
  // Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset".
40
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);
41
75
  ```
42
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
+
43
81
  - Fully typed from the [OpenAPI spec](https://watchfor.io/openapi.json)
44
82
  - Zero runtime dependencies (uses global `fetch`, Node ≥ 18)
45
83
  - `WatchForError` carries `status`, `code` and `retryAfterSeconds`
46
- - 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
47
85
 
48
86
  ## CLI
49
87
 
@@ -52,12 +90,12 @@ export WATCHFOR_API_KEY=wf_live_...
52
90
  npx watchfor summary
53
91
  npx watchfor incidents --status firing
54
92
  npx watchfor monitors example.com
55
- npx watchfor checks <monitor-id> --failed
93
+ npx watchfor checks <monitor-id> --failed # add --cursor <next_cursor> for older pages
56
94
  npx watchfor report --period 30d
57
95
  ```
58
96
 
59
97
  ## Links
60
98
 
61
99
  - API docs: https://watchfor.io/docs/api
62
- - MCP server for AI agents (42 tools): https://watchfor.io/docs/api/mcp
100
+ - MCP server for AI agents (45 tools): https://watchfor.io/docs/api/mcp
63
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,8 @@ 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"];
10
12
  export type MonitorReset = components["schemas"]["MonitorReset"];
11
13
  export type Incident = components["schemas"]["Incident"];
12
14
  export type AlertRule = components["schemas"]["AlertRule"];
@@ -16,12 +18,25 @@ export type MaintenanceWindow = components["schemas"]["MaintenanceWindow"];
16
18
  export type StatusPage = components["schemas"]["StatusPage"];
17
19
  export type Uptime = components["schemas"]["Uptime"];
18
20
  export type Check = components["schemas"]["Check"];
21
+ export type CheckList = components["schemas"]["CheckList"];
22
+ export type CheckNowAck = components["schemas"]["CheckNowAck"];
19
23
  export type Plan = components["schemas"]["Plan"];
20
24
  export type Summary = components["schemas"]["Summary"];
21
25
  export type IncidentStats = components["schemas"]["IncidentStats"];
22
26
  export type ActivityEvent = components["schemas"]["ActivityEvent"];
23
27
  export type Notification = components["schemas"]["Notification"];
24
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"];
25
40
  export interface List<T> {
26
41
  object: "list";
27
42
  data: T[];
@@ -92,30 +107,38 @@ export declare class WatchFor {
92
107
  limit?: number;
93
108
  cursor?: string;
94
109
  }) => Promise<List<Monitor>>;
95
- 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>;
96
113
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<Monitor>;
97
114
  update: (id: string, body: Record<string, unknown>) => Promise<Monitor>;
98
- delete: (id: string) => Promise<void>;
115
+ delete: (id: string) => Promise<Deleted>;
99
116
  pause: (id: string) => Promise<Monitor>;
100
117
  resume: (id: string) => Promise<Monitor>;
101
- 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>;
102
121
  /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
103
122
  * the monitor and start uptime over ("since reset"). The monitor and
104
123
  * its configuration, alert rules, tags and locations stay. */
105
124
  reset: (id: string) => Promise<MonitorReset>;
106
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. */
107
129
  checks: (id: string, q?: {
108
130
  hours?: number;
109
- success?: boolean;
110
131
  limit?: number;
111
- }) => Promise<List<Check>>;
132
+ success?: boolean;
133
+ cursor?: string;
134
+ }) => Promise<CheckList>;
112
135
  };
113
136
  readonly alertRules: {
114
137
  list: (monitorId: string) => Promise<List<AlertRule>>;
115
138
  get: (monitorId: string, ruleId: string) => Promise<AlertRule>;
116
139
  create: (monitorId: string, body: Record<string, unknown>, idempotencyKey?: string) => Promise<AlertRule>;
117
140
  update: (monitorId: string, ruleId: string, body: Record<string, unknown>) => Promise<AlertRule>;
118
- delete: (monitorId: string, ruleId: string) => Promise<void>;
141
+ delete: (monitorId: string, ruleId: string) => Promise<Deleted>;
119
142
  };
120
143
  readonly incidents: {
121
144
  list: (q?: {
@@ -128,6 +151,7 @@ export declare class WatchFor {
128
151
  cursor?: string;
129
152
  }) => Promise<List<Incident>>;
130
153
  get: (id: number) => Promise<Incident>;
154
+ /** Every action returns the full, updated Incident. */
131
155
  acknowledge: (id: number) => Promise<Incident>;
132
156
  resolve: (id: number) => Promise<Incident>;
133
157
  /** Mark a RESOLVED incident as a false positive: kept on record, left
@@ -147,7 +171,7 @@ export declare class WatchFor {
147
171
  get: (id: string) => Promise<MaintenanceWindow>;
148
172
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<MaintenanceWindow>;
149
173
  update: (id: string, body: Record<string, unknown>) => Promise<MaintenanceWindow>;
150
- delete: (id: string) => Promise<void>;
174
+ delete: (id: string) => Promise<Deleted>;
151
175
  };
152
176
  readonly contacts: {
153
177
  list: (q?: {
@@ -157,7 +181,7 @@ export declare class WatchFor {
157
181
  get: (id: string) => Promise<Contact>;
158
182
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<Contact>;
159
183
  update: (id: string, body: Record<string, unknown>) => Promise<Contact>;
160
- delete: (id: string) => Promise<void>;
184
+ delete: (id: string) => Promise<Deleted>;
161
185
  };
162
186
  readonly contactGroups: {
163
187
  list: (q?: {
@@ -167,7 +191,48 @@ export declare class WatchFor {
167
191
  get: (id: string) => Promise<ContactGroup>;
168
192
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<ContactGroup>;
169
193
  update: (id: string, body: Record<string, unknown>) => Promise<ContactGroup>;
170
- 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>;
171
236
  };
172
237
  /** Alerting delivery history — did the Slack/Telegram message go out? */
173
238
  notifications(q?: {
package/dist/client.js CHANGED
@@ -115,18 +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`),
125
129
  /** IRREVERSIBLE: delete every check, incident, note and post-mortem of
126
130
  * the monitor and start uptime over ("since reset"). The monitor and
127
131
  * its configuration, alert rules, tags and locations stay. */
128
132
  reset: (id) => this.request("POST", `/monitors/${id}/reset`),
129
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. */
130
137
  checks: (id, q) => this.request("GET", `/monitors/${id}/checks`, { query: q }),
131
138
  };
132
139
  // ── Alert rules ───────────────────────────────────────────────
@@ -146,6 +153,7 @@ export class WatchFor {
146
153
  incidents = {
147
154
  list: (q) => this.request("GET", "/incidents", { query: q }),
148
155
  get: (id) => this.request("GET", `/incidents/${id}`),
156
+ /** Every action returns the full, updated Incident. */
149
157
  acknowledge: (id) => this.request("POST", `/incidents/${id}/acknowledge`),
150
158
  resolve: (id) => this.request("POST", `/incidents/${id}/resolve`),
151
159
  /** Mark a RESOLVED incident as a false positive: kept on record, left
@@ -176,7 +184,44 @@ export class WatchFor {
176
184
  get: (id) => this.request("GET", `/contact-groups/${id}`),
177
185
  create: (body, idempotencyKey) => this.request("POST", "/contact-groups", { body, idempotencyKey }),
178
186
  update: (id, body) => this.request("PATCH", `/contact-groups/${id}`, { body }),
179
- 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
+ }),
180
225
  };
181
226
  // ── Observability ─────────────────────────────────────────────
182
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 MonitorReset, 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";