watchfor 0.13.0 → 0.15.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
@@ -39,8 +39,8 @@ await wf.incidents.exclude(19351, { reason: "Probe-side DNS hiccup" });
39
39
  // Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset".
40
40
  await wf.monitors.reset(monitor.id!);
41
41
 
42
- // Page integrity: after a deploy, accept what the newest check saw as the new baseline.
43
- await wf.monitors.acceptBaseline(integrityMonitorId);
42
+ // Page integrity: after a deploy, check the pages and accept what that check saw.
43
+ await wf.monitors.acceptBaseline(integrityMonitorId, { fresh: true });
44
44
 
45
45
  // Browser checks: try a Playwright script once (nothing saved), then read the result.
46
46
  const { id } = await wf.playwright.testRun({ script, target: "https://shop.example.com" });
@@ -61,11 +61,29 @@ if (page.next_cursor) {
61
61
 
62
62
  // Delete a contact group that alert rules still use (409 without force).
63
63
  await wf.contactGroups.delete("<group-id>", { force: true });
64
+
65
+ // What the alerting engine sees right now: alerted, recovering 1/3, confirming 2 of 3…
66
+ const { alerting_state } = await wf.monitors.get(monitor.id!);
67
+
68
+ // Response times on a real time axis (5-min buckets for 24h, 15 min for 7d).
69
+ const uptime = await wf.monitors.uptime(monitor.id!, "24h", { series: true });
70
+ for (const b of uptime.response_time_series ?? []) console.log(b.at, b.avg_ms);
71
+
72
+ // Pause up to 100 monitors at once; post a status-page announcement.
73
+ await wf.monitors.bulk("pause", ["<id-1>", "<id-2>"]);
74
+ const notice = await wf.statusPages.createAnnouncement("<page-id>", {
75
+ title: "Checkout errors",
76
+ body: "We are looking into failed payments.",
77
+ });
78
+ await wf.statusPages.updateAnnouncement("<page-id>", notice.id!, {
79
+ body: "Fixed.",
80
+ status: "resolved",
81
+ });
64
82
  ```
65
83
 
66
84
  ### Live diagnostics
67
85
 
68
- Run any of 23 checks from WatchFor's probe fleet against **any public
86
+ Run any of 24 checks from WatchFor's probe fleet against **any public
69
87
  target**, monitored or not — this measures right now, rather than reading
70
88
  what WatchFor recorded:
71
89
 
@@ -82,6 +100,21 @@ const dns = await wf.diagnostics.run("dns-lookup", {
82
100
  if (!dns.success) console.log("finding:", dns.error);
83
101
  console.log("runs left this hour:", dns.remaining);
84
102
 
103
+ // Graded checks (tls-grade, http-headers, cwv-check, mcp-check, email-health,
104
+ // mail-server-check, cdn-check, smart-audit, dns-health) also return the
105
+ // dashboard's WatchFor Grade: letter, rubric id and what holds it down.
106
+ const headers = await wf.diagnostics.run("http-headers", {
107
+ target: "https://example.com",
108
+ });
109
+ if (headers.grade?.letter) {
110
+ console.log(`grade ${headers.grade.letter} (${headers.grade.rubric})`);
111
+ for (const c of headers.grade.capped_by) {
112
+ console.log(` max ${c.cap}: ${c.title} — fix: ${c.fix}`);
113
+ }
114
+ } else {
115
+ console.log("not graded:", headers.grade?.not_graded_reason);
116
+ }
117
+
85
118
  // The whole picture in one call: DNS + propagation + TLS + HTTP + ping
86
119
  // from up to 3 regions, aggregated into one verdict.
87
120
  const report = await wf.diagnostics.diagnoseTarget({ target: "example.com" });
@@ -97,6 +130,32 @@ Toolbox. Details: https://watchfor.io/docs/api/diagnostics
97
130
  - `WatchForError` carries `status`, `code` and `retryAfterSeconds`
98
131
  - Pass an idempotency key as the second argument of any `create` call for safe retries
99
132
 
133
+ ## Organizations
134
+
135
+ An API key belongs to one organization. An **OAuth access token** acts as
136
+ the user who approved it, so it reaches every organization that user
137
+ belongs to; choose one with `organization` — the SDK sends it as the
138
+ `X-WatchFor-Organization` header on every request:
139
+
140
+ ```ts
141
+ const acme = new WatchFor({ apiKey: oauthAccessToken, organization: "<organization-id>" });
142
+ await acme.me(); // { organization: { id, name, slug }, scope }
143
+ const other = acme.withOrganization("<another-organization-id>"); // new client, same token
144
+ await other.monitors.list();
145
+ ```
146
+
147
+ - Without `organization`, an OAuth token acts on the user's oldest owned
148
+ organization (else their oldest membership).
149
+ - The user must be a member of that organization (otherwise `403
150
+ forbidden`), and their role there applies: members read, acknowledge
151
+ incidents and run diagnostics; changes need owner or admin.
152
+ - With an API key leave it unset; it may only repeat the key's own
153
+ organization id, and any other id is `403 forbidden` (a key never
154
+ switches organization).
155
+ - `withOrganization(null)` drops the header again.
156
+
157
+ Details: https://watchfor.io/docs/api/authentication#how-oauth-maps-to-your-data
158
+
100
159
  ## Prometheus metrics (Pro plan and above)
101
160
 
102
161
  ```ts
@@ -114,6 +173,12 @@ npx watchfor incidents --status firing
114
173
  npx watchfor monitors example.com
115
174
  npx watchfor checks <monitor-id> --failed # add --cursor <next_cursor> for older pages
116
175
  npx watchfor report --period 30d
176
+ npx watchfor me # which organization + scope
177
+
178
+ # OAuth token: pick the organization per call or via the environment
179
+ export WATCHFOR_API_KEY=<oauth-access-token>
180
+ npx watchfor --organization <organization-id> monitors
181
+ WATCHFOR_ORGANIZATION=<organization-id> npx watchfor summary
117
182
  ```
118
183
 
119
184
  ## Links
package/dist/cli.js CHANGED
@@ -8,10 +8,15 @@ import { WatchFor, WatchForError } from "./client.js";
8
8
  * watchfor incidents --status firing
9
9
  * watchfor monitors [search]
10
10
  * watchfor checks <monitor-id> --failed
11
+ * watchfor --organization <org-id> monitors (OAuth tokens)
11
12
  */
12
13
  const HELP = `watchfor — WatchFor monitoring CLI (https://watchfor.io)
13
14
 
14
15
  Usage:
16
+ watchfor [--organization <id>] <command> [options]
17
+
18
+ Commands:
19
+ watchfor me Which organization and scope the credential acts with
15
20
  watchfor summary Org snapshot: what's up/down right now
16
21
  watchfor incidents [--status s] List incidents (firing|acknowledged|resolved)
17
22
  watchfor monitors [query] List monitors (optional name/target search)
@@ -23,9 +28,15 @@ Usage:
23
28
  Prometheus text format (Pro plan and above)
24
29
  watchfor help
25
30
 
31
+ Global options:
32
+ --organization <id> Organization to act on (X-WatchFor-Organization). OAuth
33
+ tokens reach every organization their user belongs to;
34
+ an API key only accepts its own organization's id.
35
+
26
36
  Environment:
27
- WATCHFOR_API_KEY API key (dashboard → Settings → API keys)
28
- WATCHFOR_BASE_URL Override (default https://watchfor.io)
37
+ WATCHFOR_API_KEY API key (dashboard → Settings → API keys) or an OAuth access token
38
+ WATCHFOR_ORGANIZATION Default for --organization
39
+ WATCHFOR_BASE_URL Override (default https://watchfor.io)
29
40
  `;
30
41
  function flag(args, name) {
31
42
  const i = args.indexOf(`--${name}`);
@@ -33,8 +44,29 @@ function flag(args, name) {
33
44
  return undefined;
34
45
  return args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : "true";
35
46
  }
47
+ /** Removes a global `--name <value>` / `--name=<value>` from argv, wherever
48
+ * it appears, and returns its value. */
49
+ function takeGlobal(argv, name) {
50
+ let value;
51
+ for (let i = 0; i < argv.length; i++) {
52
+ const a = argv[i];
53
+ if (a === `--${name}`) {
54
+ value = argv[i + 1] ?? "";
55
+ argv.splice(i, 2);
56
+ i--;
57
+ }
58
+ else if (a.startsWith(`--${name}=`)) {
59
+ value = a.slice(name.length + 3);
60
+ argv.splice(i, 1);
61
+ i--;
62
+ }
63
+ }
64
+ return value;
65
+ }
36
66
  async function main() {
37
- const [cmd, ...args] = process.argv.slice(2);
67
+ const argv = process.argv.slice(2);
68
+ const organizationFlag = takeGlobal(argv, "organization");
69
+ const [cmd, ...args] = argv;
38
70
  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
39
71
  process.stdout.write(HELP);
40
72
  return 0;
@@ -44,11 +76,23 @@ async function main() {
44
76
  console.error("WATCHFOR_API_KEY is not set. Create a key in the dashboard (Settings → API keys).");
45
77
  return 1;
46
78
  }
79
+ const organization = organizationFlag ?? process.env.WATCHFOR_ORGANIZATION ?? undefined;
80
+ if (organizationFlag !== undefined && !organizationFlag.trim()) {
81
+ console.error("--organization needs an organization id");
82
+ return 1;
83
+ }
47
84
  const wf = new WatchFor({
48
85
  apiKey,
86
+ organization,
49
87
  baseUrl: process.env.WATCHFOR_BASE_URL,
50
88
  });
51
89
  switch (cmd) {
90
+ case "me": {
91
+ const me = await wf.me();
92
+ const org = me.organization;
93
+ console.log(`organization: ${org ? `${org.name} (${org.id})` : "none"} · scope ${me.scope ?? "?"}`);
94
+ return 0;
95
+ }
52
96
  case "summary": {
53
97
  const s = await wf.summary();
54
98
  const m = s.monitors;
package/dist/client.d.ts CHANGED
@@ -5,14 +5,29 @@ import type { components } from "./schema.js";
5
5
  *
6
6
  * const wf = new WatchFor({ apiKey: process.env.WATCHFOR_API_KEY! });
7
7
  * const summary = await wf.summary();
8
+ *
9
+ * An OAuth access token reaches every organization its user belongs to;
10
+ * pick one with `organization` (sent as `X-WatchFor-Organization`):
11
+ *
12
+ * const acme = new WatchFor({ apiKey: oauthToken, organization: "<org id>" });
13
+ * const other = acme.withOrganization("<another org id>");
8
14
  */
15
+ /** The request header that selects the organization an OAuth token acts on. */
16
+ export declare const ORGANIZATION_HEADER = "X-WatchFor-Organization";
9
17
  export type Monitor = components["schemas"]["Monitor"];
10
- /** Monitor + `available_metrics` (GET /monitors/{id} only). */
18
+ /** Monitor + `available_metrics` and `alerting_state` — what the alerting
19
+ * engine sees right now (GET /monitors/{id} only). */
11
20
  export type MonitorDetail = components["schemas"]["MonitorDetail"];
21
+ /** `alerting_state` of a monitor detail: alerted / recovering (n of m) /
22
+ * failing below the confirmation threshold (confirming n of m), or null. */
23
+ export type AlertingState = NonNullable<Monitor["alerting_state"]>;
24
+ /** Result of `monitors.bulk()` — which ids were acted on, which skipped. */
25
+ export type BulkResult = components["schemas"]["BulkResult"];
12
26
  export type MonitorReset = components["schemas"]["MonitorReset"];
13
27
  export type IntegrityBaseline = components["schemas"]["IntegrityBaseline"];
14
28
  export type IntegrityBaselineAccept = components["schemas"]["IntegrityBaselineAccept"];
15
- export type PlaywrightTestRunRequest = components["schemas"]["PlaywrightTestRunRequest"];
29
+ /** A fresh accept whose check has not landed yet (HTTP 202). */
30
+ export type IntegrityBaselineAcceptPending = components["schemas"]["IntegrityBaselineAcceptPending"];
16
31
  export type PlaywrightTestRunAccepted = components["schemas"]["PlaywrightTestRunAccepted"];
17
32
  export type PlaywrightTestRun = components["schemas"]["PlaywrightTestRun"];
18
33
  export type PlaywrightRun = components["schemas"]["PlaywrightRun"];
@@ -26,15 +41,51 @@ export type AlertRule = components["schemas"]["AlertRule"];
26
41
  export type Contact = components["schemas"]["Contact"];
27
42
  export type ContactGroup = components["schemas"]["ContactGroup"];
28
43
  export type MaintenanceWindow = components["schemas"]["MaintenanceWindow"];
44
+ /** `incidents.markMaintenance()` — the window that now covers the outage. */
45
+ export interface MaintenanceMarking {
46
+ object: "maintenance_marking";
47
+ incident_id: number;
48
+ maintenance_window: MaintenanceWindow;
49
+ }
29
50
  export type Host = components["schemas"]["Host"];
30
51
  export type HostMetrics = components["schemas"]["HostMetrics"];
31
52
  export type StatusPage = components["schemas"]["StatusPage"];
53
+ /** Request bodies: fields the server defaults may be left out (the
54
+ * generated types mark every defaulted field as required). */
55
+ type Defaulted<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
56
+ type RawStatusPageCreate = components["schemas"]["StatusPageCreate"];
57
+ /** A status-page component — `monitorIds` / `monitorTags` default to []. */
58
+ export type StatusPageComponentCreate = Defaulted<RawStatusPageCreate["components"][number], "monitorIds" | "monitorTags">;
59
+ export type StatusPageCreate = Defaulted<Omit<RawStatusPageCreate, "components">, "isPublic" | "autoPublishIncidents" | "dimUntrackedDays" | "theme"> & {
60
+ components?: StatusPageComponentCreate[];
61
+ };
62
+ export type StatusPageUpdate = components["schemas"]["StatusPageUpdate"];
63
+ export type Announcement = components["schemas"]["Announcement"];
64
+ /** `retry` defaults on the server, so it may be left out. */
65
+ export type PlaywrightTestRunRequest = Defaulted<components["schemas"]["PlaywrightTestRunRequest"], "retry">;
66
+ export type AnnouncementCreate = Defaulted<components["schemas"]["AnnouncementCreate"], "status" | "severity" | "affectedComponentIds">;
67
+ export type AnnouncementUpdate = components["schemas"]["AnnouncementUpdate"];
68
+ /** Uptime stats; with `series: true` also `response_time_series` and
69
+ * `series_bucket_seconds` (periods up to 7d). */
32
70
  export type Uptime = components["schemas"]["Uptime"];
71
+ /** One bucket of `Uptime.response_time_series`. */
72
+ export type ResponseTimeBucket = NonNullable<Uptime["response_time_series"]>[number];
33
73
  export type Check = components["schemas"]["Check"];
34
74
  export type CheckList = components["schemas"]["CheckList"];
35
75
  export type CheckNowAck = components["schemas"]["CheckNowAck"];
36
76
  export type Plan = components["schemas"]["Plan"];
37
77
  export type Summary = components["schemas"]["Summary"];
78
+ /** The credential's identity: scope + the organization it acts on. */
79
+ export type Me = components["schemas"]["Me"];
80
+ /** `batch()` results, in request order: `{ status, body }` per operation. */
81
+ export type BatchResult = components["schemas"]["BatchResult"];
82
+ /** One operation of a `batch()` call — a relative /api/v1 path. */
83
+ export interface BatchOperation {
84
+ method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
85
+ /** Relative /api/v1 sub-path, e.g. `/monitors/{id}`. */
86
+ path: string;
87
+ body?: Record<string, unknown>;
88
+ }
38
89
  export type IncidentStats = components["schemas"]["IncidentStats"];
39
90
  export type ActivityEvent = components["schemas"]["ActivityEvent"];
40
91
  export type Notification = components["schemas"]["Notification"];
@@ -48,6 +99,12 @@ export type DiagnosticCatalogEntry = components["schemas"]["DiagnosticCatalogEnt
48
99
  export type DiagnosticRun = components["schemas"]["DiagnosticRun"];
49
100
  /** The `diagnose-target` bundle: a verdict plus a status per check. */
50
101
  export type DiagnosticReport = components["schemas"]["DiagnosticReport"];
102
+ /**
103
+ * A WatchFor Grade (graded checks only): the dashboard's A+…F letter, its
104
+ * rubric id and `capped_by`, the findings that hold it down. `letter: null`
105
+ * = not graded (we could not measure), with `not_graded_reason`.
106
+ */
107
+ export type WatchForGrade = components["schemas"]["WatchForGrade"];
51
108
  /** Which check to run — short aliases (`dns`, `port-check`, …) also work. */
52
109
  export type DiagnosticSlug = components["schemas"]["DiagnosticRun"]["tool"];
53
110
  export interface List<T> {
@@ -64,20 +121,68 @@ export declare class WatchForError extends Error {
64
121
  constructor(status: number, code: string, message: string, retryAfterSeconds?: number);
65
122
  }
66
123
  export interface WatchForOptions {
67
- /** API key (wf_live_…) — dashboard Settings → API keys. */
124
+ /** API key (wf_live_…, dashboard Settings → API keys) or an OAuth
125
+ * access token. */
68
126
  apiKey: string;
127
+ /**
128
+ * Organization id to act on, sent as `X-WatchFor-Organization`. For
129
+ * OAuth tokens, which reach every organization their user belongs to
130
+ * (omitted: the user's oldest owned organization, else their oldest
131
+ * membership). An API key belongs to one organization: leave it unset,
132
+ * or set that same id — any other id is 403 `forbidden`.
133
+ */
134
+ organization?: string;
69
135
  /** Override for self-hosted / testing. Default https://watchfor.io */
70
136
  baseUrl?: string;
71
137
  fetch?: typeof fetch;
72
138
  }
139
+ /** Optional scoping/shape filters of `report()`; lists may be arrays or
140
+ * comma-separated strings. */
141
+ export interface ReportFilters {
142
+ /** Scope to these monitors (union with `tags`). */
143
+ monitor_ids?: string | string[];
144
+ /** Scope to monitors carrying these tags. */
145
+ tags?: string | string[];
146
+ /** Subset of type-aware sections: locations, ssl, domains, cwv,
147
+ * heartbeat, blacklist, mcp, hosts (omit for all). */
148
+ sections?: string | string[];
149
+ /** false drops the response-time block. */
150
+ response_time?: boolean;
151
+ /** false drops the per-monitor table. */
152
+ monitors_table?: boolean;
153
+ /** false drops the insights block. */
154
+ insights?: boolean;
155
+ /** Incident aggregates only over these states: acknowledged, resolved,
156
+ * open (or all). */
157
+ incident_status?: string | string[];
158
+ }
73
159
  export declare class WatchFor {
160
+ /** The organization id this client sends, or undefined (the
161
+ * credential's default organization). */
162
+ readonly organization: string | undefined;
163
+ private readonly options;
74
164
  private readonly apiKey;
75
165
  private readonly base;
76
166
  private readonly fetchImpl;
77
167
  constructor(opts: WatchForOptions);
168
+ /**
169
+ * A new client acting on another organization (same credential and
170
+ * settings); `null` drops the header so the credential's default
171
+ * organization applies. This client is left unchanged.
172
+ */
173
+ withOrganization(organization: string | null): WatchFor;
78
174
  private request;
79
- /** Current API key + organization. */
80
- me(): Promise<unknown>;
175
+ /** The credential's scope and the organization it acts on — with an
176
+ * OAuth token, the one `organization` selected. */
177
+ me(): Promise<Me>;
178
+ /**
179
+ * Run up to 20 operations in one request. Each runs against /api/v1 with
180
+ * the same credential and organization, so scopes, validation and rate
181
+ * limits apply per operation; results come back in request order.
182
+ */
183
+ batch(operations: BatchOperation[]): Promise<BatchResult>;
184
+ /** The OpenAPI 3.1 document this client is built from (no key needed). */
185
+ openApiSpec(): Promise<Record<string, unknown>>;
81
186
  /** One-call org snapshot: monitor status counts + active incidents. */
82
187
  summary(): Promise<Summary>;
83
188
  /**
@@ -100,14 +205,15 @@ export declare class WatchFor {
100
205
  * Org report for a period vs the previous one: uptime, incidents,
101
206
  * MTTR/MTBF, response-time trend, per-monitor rows, type-aware
102
207
  * sections and plain-language insights. Custom from/to (ISO 8601)
103
- * needs the advanced-reports plan capability.
208
+ * needs the advanced-reports plan capability, as do the scoping
209
+ * filters (`monitor_ids`, `tags`, `sections`, `incident_status`).
104
210
  */
105
- report(opts?: {
211
+ report(opts?: ({
106
212
  period?: "7d" | "30d";
107
213
  } | {
108
214
  from: string | Date;
109
215
  to: string | Date;
110
- }): Promise<Record<string, unknown>>;
216
+ }) & ReportFilters): Promise<Record<string, unknown>>;
111
217
  /** The org's two report-email cadences (weekly + monthly). */
112
218
  reportSchedules(): Promise<List<Record<string, unknown>>>;
113
219
  /**
@@ -133,8 +239,13 @@ export declare class WatchFor {
133
239
  cursor?: string;
134
240
  }) => Promise<List<Monitor>>;
135
241
  /** The monitor plus `available_metrics` — the alert metrics valid for
136
- * its type. */
242
+ * its type — and `alerting_state`: what the alerting engine sees right
243
+ * now (alerted, recovering n of m, failing/confirming n of m; null
244
+ * when every rule is healthy). */
137
245
  get: (id: string) => Promise<MonitorDetail>;
246
+ /** Pause, resume or delete up to 100 monitors in one call; ids that
247
+ * are not yours or need no change come back in `skipped`. */
248
+ bulk: (action: "pause" | "resume" | "delete", ids: string[], idempotencyKey?: string) => Promise<BulkResult>;
138
249
  /** Create a monitor; `config` keys per type come from `monitorTypes()`.
139
250
  * Credentials (catalog fields marked `secret` — mailbox/SMTP/FTP
140
251
  * passwords, SSH keys, HTTP/API/MCP auth passwords and bearer
@@ -146,7 +257,9 @@ export declare class WatchFor {
146
257
  * removes). A `"[redacted]"` credential is kept when omitted or sent
147
258
  * back unchanged; changing the server, port, TLS mode or login it is
148
259
  * used with (HTTP: the URL's host, port or scheme) needs it again in
149
- * the same call (else 400). */
260
+ * the same call (else 400). `check_queued: true` in the result means
261
+ * the change (target, port, credentials, TLS, request…) dispatched one
262
+ * immediate check, outside the Run-now budget. */
150
263
  update: (id: string, body: Record<string, unknown>) => Promise<Monitor>;
151
264
  delete: (id: string) => Promise<Deleted>;
152
265
  pause: (id: string) => Promise<Monitor>;
@@ -162,13 +275,16 @@ export declare class WatchFor {
162
275
  * page (whether it has one, when and how it was captured). */
163
276
  getBaseline: (id: string) => Promise<IntegrityBaseline>;
164
277
  /** Page integrity monitors: accept what the newest check saw as the
165
- * new baseline — all pages, or only `pages` — and start a check of
166
- * them (`check_requested`). In a deploy pipeline, run `checkNow` and
167
- * wait for a newer check first, so the release is what gets
168
- * accepted; unfetched pages come back in `skipped`. */
278
+ * new baseline — all pages, or only `pages`. Open integrity incidents
279
+ * resolve at once when nothing else differs (`incidents_resolved`).
280
+ * In a deploy pipeline pass `fresh: true`: the pages are checked
281
+ * first and that check is accepted (`status: "pending"` = still
282
+ * running, finishing on its own — see `getBaseline().fresh_accept`);
283
+ * unfetched pages come back in `skipped`. */
169
284
  acceptBaseline: (id: string, body?: {
170
285
  pages?: string[];
171
- }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept>;
286
+ fresh?: boolean;
287
+ }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept | IntegrityBaselineAcceptPending>;
172
288
  /** Browser checks: runs, newest first (`status` failed | flaky). */
173
289
  runs: (id: string, params?: {
174
290
  status?: "all" | "failed" | "flaky";
@@ -190,7 +306,13 @@ export declare class WatchFor {
190
306
  data: ScriptVersionSummary[];
191
307
  }>;
192
308
  scriptVersion: (id: string, version: number) => Promise<ScriptVersion>;
193
- uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d") => Promise<Uptime>;
309
+ /** Uptime (confirmed critical incidents only), check success and
310
+ * response-time stats. `series: true` (periods up to 7d) adds
311
+ * `response_time_series` — buckets of `series_bucket_seconds` (300
312
+ * for 24h, 900 for 7d) on a real time axis, oldest first. */
313
+ uptime: (id: string, period?: "1h" | "24h" | "7d" | "30d" | "90d", opts?: {
314
+ series?: boolean;
315
+ }) => Promise<Uptime>;
194
316
  /** Recent probe results, newest first. Page with `next_cursor` →
195
317
  * `cursor` (keep the same `hours`/`success`); `locations` is the
196
318
  * per-location breakdown for the whole window. */
@@ -200,9 +322,11 @@ export declare class WatchFor {
200
322
  success?: boolean;
201
323
  cursor?: string;
202
324
  }) => Promise<CheckList>;
325
+ /** One probe run in full, redacted server-side — run_id from checks(). */
326
+ checkDetail: (id: string, runId: string) => Promise<Record<string, unknown>>;
203
327
  };
204
328
  readonly alertRules: {
205
- /** One probe run in full, redacted server-side — run_id from checks(). */
329
+ /** @deprecated Use `monitors.checkDetail()` — same call. */
206
330
  checkDetail: (id: string, runId: string) => Promise<Record<string, unknown>>;
207
331
  list: (monitorId: string) => Promise<List<AlertRule>>;
208
332
  get: (monitorId: string, ruleId: string) => Promise<AlertRule>;
@@ -256,6 +380,11 @@ export declare class WatchFor {
256
380
  }) => Promise<Incident>;
257
381
  /** Undo `exclude` — the incident counts as downtime again. */
258
382
  include: (id: number) => Promise<Incident>;
383
+ /** Retroactively count a RESOLVED incident as planned maintenance: it
384
+ * leaves uptime and SLA. Returns the maintenance window recorded for
385
+ * it (marking again returns the same one); delete that window to
386
+ * undo. */
387
+ markMaintenance: (id: number, idempotencyKey?: string) => Promise<MaintenanceMarking>;
259
388
  };
260
389
  readonly statusPages: {
261
390
  list: (q?: {
@@ -263,10 +392,26 @@ export declare class WatchFor {
263
392
  cursor?: string;
264
393
  }) => Promise<List<StatusPage>>;
265
394
  get: (id: string) => Promise<StatusPage>;
395
+ /** Create a page, optionally with components. Password protection,
396
+ * logo upload and custom subdomains are dashboard-only. */
397
+ create: (body: StatusPageCreate, idempotencyKey?: string) => Promise<StatusPage>;
398
+ /** Partial update; a slug change frees the old URL at once. */
399
+ update: (id: string, body: StatusPageUpdate) => Promise<StatusPage>;
400
+ delete: (id: string) => Promise<Deleted>;
401
+ /** Announcements, newest first. */
266
402
  announcements: (id: string, q?: {
267
403
  limit?: number;
268
404
  cursor?: string;
269
- }) => Promise<List<Record<string, unknown>>>;
405
+ }) => Promise<List<Announcement>>;
406
+ getAnnouncement: (id: string, announcementId: string) => Promise<Announcement>;
407
+ /** Publish an incident notice; `body` becomes the first timeline
408
+ * entry. */
409
+ createAnnouncement: (id: string, body: AnnouncementCreate, idempotencyKey?: string) => Promise<Announcement>;
410
+ /** Post an update: appends to the public timeline and moves the
411
+ * status; `resolved` closes it. */
412
+ updateAnnouncement: (id: string, announcementId: string, body: AnnouncementUpdate) => Promise<Announcement>;
413
+ /** Remove from the public page (soft delete). */
414
+ deleteAnnouncement: (id: string, announcementId: string) => Promise<Deleted>;
270
415
  };
271
416
  readonly onCall: {
272
417
  get: () => Promise<Record<string, unknown>>;
@@ -289,9 +434,11 @@ export declare class WatchFor {
289
434
  metrics: (id: string, metrics: string[], range?: "1h" | "6h" | "24h" | "7d" | "30d") => Promise<HostMetrics>;
290
435
  };
291
436
  readonly maintenanceWindows: {
437
+ /** `state` keeps only live windows (active now / upcoming). */
292
438
  list: (q?: {
293
439
  limit?: number;
294
440
  cursor?: string;
441
+ state?: "active" | "upcoming";
295
442
  }) => Promise<List<MaintenanceWindow>>;
296
443
  get: (id: string) => Promise<MaintenanceWindow>;
297
444
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<MaintenanceWindow>;
@@ -381,3 +528,4 @@ export declare class WatchFor {
381
528
  cursor?: string;
382
529
  }): Promise<List<ActivityEvent>>;
383
530
  }
531
+ export {};
package/dist/client.js CHANGED
@@ -1,3 +1,18 @@
1
+ /**
2
+ * WatchFor API client — a thin, zero-dependency typed wrapper over
3
+ * https://watchfor.io/api/v1 (spec: https://watchfor.io/openapi.json).
4
+ *
5
+ * const wf = new WatchFor({ apiKey: process.env.WATCHFOR_API_KEY! });
6
+ * const summary = await wf.summary();
7
+ *
8
+ * An OAuth access token reaches every organization its user belongs to;
9
+ * pick one with `organization` (sent as `X-WatchFor-Organization`):
10
+ *
11
+ * const acme = new WatchFor({ apiKey: oauthToken, organization: "<org id>" });
12
+ * const other = acme.withOrganization("<another org id>");
13
+ */
14
+ /** The request header that selects the organization an OAuth token acts on. */
15
+ export const ORGANIZATION_HEADER = "X-WatchFor-Organization";
1
16
  export class WatchForError extends Error {
2
17
  status;
3
18
  code;
@@ -11,16 +26,33 @@ export class WatchForError extends Error {
11
26
  }
12
27
  }
13
28
  export class WatchFor {
29
+ /** The organization id this client sends, or undefined (the
30
+ * credential's default organization). */
31
+ organization;
32
+ options;
14
33
  apiKey;
15
34
  base;
16
35
  fetchImpl;
17
36
  constructor(opts) {
18
37
  if (!opts.apiKey)
19
38
  throw new Error("WatchFor: apiKey is required");
39
+ this.options = opts;
20
40
  this.apiKey = opts.apiKey;
41
+ this.organization = opts.organization?.trim() || undefined;
21
42
  this.base = (opts.baseUrl ?? "https://watchfor.io").replace(/\/$/, "");
22
43
  this.fetchImpl = opts.fetch ?? fetch;
23
44
  }
45
+ /**
46
+ * A new client acting on another organization (same credential and
47
+ * settings); `null` drops the header so the credential's default
48
+ * organization applies. This client is left unchanged.
49
+ */
50
+ withOrganization(organization) {
51
+ return new WatchFor({
52
+ ...this.options,
53
+ organization: organization ?? undefined,
54
+ });
55
+ }
24
56
  async request(method, path, opts = {}) {
25
57
  const url = new URL(`${this.base}/api/v1${path}`);
26
58
  for (const [k, v] of Object.entries(opts.query ?? {})) {
@@ -35,6 +67,8 @@ export class WatchFor {
35
67
  headers["Content-Type"] = "application/json";
36
68
  if (opts.idempotencyKey)
37
69
  headers["Idempotency-Key"] = opts.idempotencyKey;
70
+ if (this.organization)
71
+ headers[ORGANIZATION_HEADER] = this.organization;
38
72
  const res = await this.fetchImpl(url, {
39
73
  method,
40
74
  headers,
@@ -60,10 +94,23 @@ export class WatchFor {
60
94
  return json;
61
95
  }
62
96
  // ── Org overview ──────────────────────────────────────────────
63
- /** Current API key + organization. */
97
+ /** The credential's scope and the organization it acts on — with an
98
+ * OAuth token, the one `organization` selected. */
64
99
  me() {
65
100
  return this.request("GET", "/me");
66
101
  }
102
+ /**
103
+ * Run up to 20 operations in one request. Each runs against /api/v1 with
104
+ * the same credential and organization, so scopes, validation and rate
105
+ * limits apply per operation; results come back in request order.
106
+ */
107
+ batch(operations) {
108
+ return this.request("POST", "/batch", { body: { operations } });
109
+ }
110
+ /** The OpenAPI 3.1 document this client is built from (no key needed). */
111
+ openApiSpec() {
112
+ return this.request("GET", "/openapi.json");
113
+ }
67
114
  /** One-call org snapshot: monitor status counts + active incidents. */
68
115
  summary() {
69
116
  return this.request("GET", "/summary");
@@ -89,10 +136,20 @@ export class WatchFor {
89
136
  * Org report for a period vs the previous one: uptime, incidents,
90
137
  * MTTR/MTBF, response-time trend, per-monitor rows, type-aware
91
138
  * sections and plain-language insights. Custom from/to (ISO 8601)
92
- * needs the advanced-reports plan capability.
139
+ * needs the advanced-reports plan capability, as do the scoping
140
+ * filters (`monitor_ids`, `tags`, `sections`, `incident_status`).
93
141
  */
94
142
  report(opts) {
95
- const query = {};
143
+ const list = (v) => Array.isArray(v) ? v.join(",") : v;
144
+ const query = {
145
+ monitor_ids: list(opts?.monitor_ids),
146
+ tags: list(opts?.tags),
147
+ sections: list(opts?.sections),
148
+ incident_status: list(opts?.incident_status),
149
+ response_time: opts?.response_time,
150
+ monitors_table: opts?.monitors_table,
151
+ insights: opts?.insights,
152
+ };
96
153
  if (opts && "from" in opts) {
97
154
  query.from =
98
155
  opts.from instanceof Date ? opts.from.toISOString() : opts.from;
@@ -127,8 +184,16 @@ export class WatchFor {
127
184
  monitors = {
128
185
  list: (q) => this.request("GET", "/monitors", { query: q }),
129
186
  /** The monitor plus `available_metrics` — the alert metrics valid for
130
- * its type. */
187
+ * its type — and `alerting_state`: what the alerting engine sees right
188
+ * now (alerted, recovering n of m, failing/confirming n of m; null
189
+ * when every rule is healthy). */
131
190
  get: (id) => this.request("GET", `/monitors/${id}`),
191
+ /** Pause, resume or delete up to 100 monitors in one call; ids that
192
+ * are not yours or need no change come back in `skipped`. */
193
+ bulk: (action, ids, idempotencyKey) => this.request("POST", "/monitors/bulk", {
194
+ body: { action, ids },
195
+ idempotencyKey,
196
+ }),
132
197
  /** Create a monitor; `config` keys per type come from `monitorTypes()`.
133
198
  * Credentials (catalog fields marked `secret` — mailbox/SMTP/FTP
134
199
  * passwords, SSH keys, HTTP/API/MCP auth passwords and bearer
@@ -140,7 +205,9 @@ export class WatchFor {
140
205
  * removes). A `"[redacted]"` credential is kept when omitted or sent
141
206
  * back unchanged; changing the server, port, TLS mode or login it is
142
207
  * used with (HTTP: the URL's host, port or scheme) needs it again in
143
- * the same call (else 400). */
208
+ * the same call (else 400). `check_queued: true` in the result means
209
+ * the change (target, port, credentials, TLS, request…) dispatched one
210
+ * immediate check, outside the Run-now budget. */
144
211
  update: (id, body) => this.request("PATCH", `/monitors/${id}`, { body }),
145
212
  delete: (id) => this.request("DELETE", `/monitors/${id}`),
146
213
  pause: (id) => this.request("POST", `/monitors/${id}/pause`),
@@ -156,10 +223,12 @@ export class WatchFor {
156
223
  * page (whether it has one, when and how it was captured). */
157
224
  getBaseline: (id) => this.request("GET", `/monitors/${id}/baseline`),
158
225
  /** Page integrity monitors: accept what the newest check saw as the
159
- * new baseline — all pages, or only `pages` — and start a check of
160
- * them (`check_requested`). In a deploy pipeline, run `checkNow` and
161
- * wait for a newer check first, so the release is what gets
162
- * accepted; unfetched pages come back in `skipped`. */
226
+ * new baseline — all pages, or only `pages`. Open integrity incidents
227
+ * resolve at once when nothing else differs (`incidents_resolved`).
228
+ * In a deploy pipeline pass `fresh: true`: the pages are checked
229
+ * first and that check is accepted (`status: "pending"` = still
230
+ * running, finishing on its own — see `getBaseline().fresh_accept`);
231
+ * unfetched pages come back in `skipped`. */
163
232
  acceptBaseline: (id, body, idempotencyKey) => this.request("POST", `/monitors/${id}/baseline`, {
164
233
  body: body ?? {},
165
234
  idempotencyKey,
@@ -172,15 +241,23 @@ export class WatchFor {
172
241
  /** Browser checks: saved script versions (last 50). */
173
242
  scriptVersions: (id) => this.request("GET", `/monitors/${id}/script/versions`),
174
243
  scriptVersion: (id, version) => this.request("GET", `/monitors/${id}/script/versions/${version}`),
175
- uptime: (id, period) => this.request("GET", `/monitors/${id}/uptime`, { query: { period } }),
244
+ /** Uptime (confirmed critical incidents only), check success and
245
+ * response-time stats. `series: true` (periods up to 7d) adds
246
+ * `response_time_series` — buckets of `series_bucket_seconds` (300
247
+ * for 24h, 900 for 7d) on a real time axis, oldest first. */
248
+ uptime: (id, period, opts) => this.request("GET", `/monitors/${id}/uptime`, {
249
+ query: { period, series: opts?.series ? true : undefined },
250
+ }),
176
251
  /** Recent probe results, newest first. Page with `next_cursor` →
177
252
  * `cursor` (keep the same `hours`/`success`); `locations` is the
178
253
  * per-location breakdown for the whole window. */
179
254
  checks: (id, q) => this.request("GET", `/monitors/${id}/checks`, { query: q }),
255
+ /** One probe run in full, redacted server-side — run_id from checks(). */
256
+ checkDetail: (id, runId) => this.request("GET", `/monitors/${id}/checks/${runId}`),
180
257
  };
181
258
  // ── Alert rules ───────────────────────────────────────────────
182
259
  alertRules = {
183
- /** One probe run in full, redacted server-side — run_id from checks(). */
260
+ /** @deprecated Use `monitors.checkDetail()` — same call. */
184
261
  checkDetail: (id, runId) => this.request("GET", `/monitors/${id}/checks/${runId}`),
185
262
  list: (monitorId) => this.request("GET", `/monitors/${monitorId}/alert-rules`),
186
263
  get: (monitorId, ruleId) => this.request("GET", `/monitors/${monitorId}/alert-rules/${ruleId}`),
@@ -224,12 +301,38 @@ export class WatchFor {
224
301
  exclude: (id, body) => this.request("POST", `/incidents/${id}/exclude`, { body: body ?? {} }),
225
302
  /** Undo `exclude` — the incident counts as downtime again. */
226
303
  include: (id) => this.request("POST", `/incidents/${id}/include`),
304
+ /** Retroactively count a RESOLVED incident as planned maintenance: it
305
+ * leaves uptime and SLA. Returns the maintenance window recorded for
306
+ * it (marking again returns the same one); delete that window to
307
+ * undo. */
308
+ markMaintenance: (id, idempotencyKey) => this.request("POST", `/incidents/${id}/mark-maintenance`, {
309
+ idempotencyKey,
310
+ }),
227
311
  };
228
312
  // ── Status pages, on-call, channels ──────────────────────────
229
313
  statusPages = {
230
314
  list: (q) => this.request("GET", "/status-pages", { query: q }),
231
315
  get: (id) => this.request("GET", `/status-pages/${id}`),
316
+ /** Create a page, optionally with components. Password protection,
317
+ * logo upload and custom subdomains are dashboard-only. */
318
+ create: (body, idempotencyKey) => this.request("POST", "/status-pages", { body, idempotencyKey }),
319
+ /** Partial update; a slug change frees the old URL at once. */
320
+ update: (id, body) => this.request("PATCH", `/status-pages/${id}`, { body }),
321
+ delete: (id) => this.request("DELETE", `/status-pages/${id}`),
322
+ /** Announcements, newest first. */
232
323
  announcements: (id, q) => this.request("GET", `/status-pages/${id}/announcements`, { query: q }),
324
+ getAnnouncement: (id, announcementId) => this.request("GET", `/status-pages/${id}/announcements/${announcementId}`),
325
+ /** Publish an incident notice; `body` becomes the first timeline
326
+ * entry. */
327
+ createAnnouncement: (id, body, idempotencyKey) => this.request("POST", `/status-pages/${id}/announcements`, {
328
+ body,
329
+ idempotencyKey,
330
+ }),
331
+ /** Post an update: appends to the public timeline and moves the
332
+ * status; `resolved` closes it. */
333
+ updateAnnouncement: (id, announcementId, body) => this.request("PATCH", `/status-pages/${id}/announcements/${announcementId}`, { body }),
334
+ /** Remove from the public page (soft delete). */
335
+ deleteAnnouncement: (id, announcementId) => this.request("DELETE", `/status-pages/${id}/announcements/${announcementId}`),
233
336
  };
234
337
  onCall = {
235
338
  get: () => this.request("GET", "/on-call"),
@@ -249,6 +352,7 @@ export class WatchFor {
249
352
  };
250
353
  // ── Maintenance windows ───────────────────────────────────────
251
354
  maintenanceWindows = {
355
+ /** `state` keeps only live windows (active now / upcoming). */
252
356
  list: (q) => this.request("GET", "/maintenance-windows", { query: q }),
253
357
  get: (id) => this.request("GET", `/maintenance-windows/${id}`),
254
358
  create: (body, idempotencyKey) => this.request("POST", "/maintenance-windows", { body, idempotencyKey }),
package/dist/index.d.ts CHANGED
@@ -1 +1 @@
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 IntegrityBaseline, type IntegrityBaselineAccept, type List, type MaintenanceWindow, type Monitor, type MonitorDetail, type MonitorReset, type Notification, type Plan, type PlaywrightRun, type PlaywrightRunSummary, type PlaywrightTestRun, type PlaywrightTestRunAccepted, type PlaywrightTestRunRequest, type ScriptVersion, type ScriptVersionSummary, type StatusPage, type Summary, type Uptime, type Variable, type VariableDeleted, WatchFor, WatchForError, type WatchForOptions, } from "./client.js";
1
+ export { type ActivityEvent, type AlertingState, type AlertRule, type Announcement, type AnnouncementCreate, type AnnouncementUpdate, type ApiErrorBody, type BatchOperation, type BatchResult, type BulkResult, 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 IntegrityBaseline, type IntegrityBaselineAccept, type IntegrityBaselineAcceptPending, type List, type MaintenanceMarking, type MaintenanceWindow, type Me, type Monitor, type MonitorDetail, type MonitorReset, type Notification, ORGANIZATION_HEADER, type Plan, type PlaywrightRun, type PlaywrightRunSummary, type PlaywrightTestRun, type PlaywrightTestRunAccepted, type PlaywrightTestRunRequest, type ReportFilters, type ResponseTimeBucket, type ScriptVersion, type ScriptVersionSummary, type StatusPage, type StatusPageComponentCreate, type StatusPageCreate, type StatusPageUpdate, type Summary, type Uptime, type Variable, type VariableDeleted, WatchFor, WatchForError, type WatchForGrade, type WatchForOptions, } from "./client.js";
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- export { WatchFor, WatchForError, } from "./client.js";
1
+ export { ORGANIZATION_HEADER, WatchFor, WatchForError, } from "./client.js";
package/dist/schema.d.ts CHANGED
@@ -48,7 +48,10 @@ export interface paths {
48
48
  path?: never;
49
49
  cookie?: never;
50
50
  };
51
- /** A browser check's runs, newest first (404 for other monitor types) */
51
+ /**
52
+ * A browser check's runs, newest first (404 for other monitor types)
53
+ * @description Runs within the plan's check history (at most the 400 days runs are stored). History limits: reads follow the plan's data retention (/docs/organization/data-retention). A window reaching further is cut, not refused — the response carries X-History-Limit-Days (the plan's window or `unlimited`), X-History-Earliest (oldest timestamp returned, ISO 8601) and X-History-Clamped: true when the requested window was cut.
54
+ */
52
55
  get: operations["listMonitorRuns"];
53
56
  put?: never;
54
57
  post?: never;
@@ -65,7 +68,10 @@ export interface paths {
65
68
  path?: never;
66
69
  cookie?: never;
67
70
  };
68
- /** One browser-check run: steps, errors with code frames, Web Vitals, screenshots (presigned 15 min), trace link */
71
+ /**
72
+ * One browser-check run: steps, errors with code frames, Web Vitals, screenshots (presigned 15 min), trace link
73
+ * @description A run older than the plan's check history returns 404 not_found with a message naming the plan's window.
74
+ */
69
75
  get: operations["getMonitorRun"];
70
76
  put?: never;
71
77
  post?: never;
@@ -415,7 +421,9 @@ export interface paths {
415
421
  put?: never;
416
422
  /**
417
423
  * Accept the latest state of the watched pages as the new baseline — call it after a deploy
418
- * @description Page integrity monitors only. Takes the newest checked fingerprint (and text) of every watched page — or only `pages` — as the accepted baseline, so an intended change stops alerting. A check of the pages starts right away (`check_requested`), so open findings close on a clean check within a minute or two. Pages no check has fetched yet are returned in `skipped`. Typical use: the last step of a deploy pipeline — first `POST /v1/monitors/{id}/check-now`, wait until `GET /v1/monitors/{id}/checks` shows a check newer than the release, then accept, so the baseline is the new version and not the one before it.
424
+ * @description Page integrity monitors only. Takes the newest checked fingerprint (and text) of every watched page — or only `pages` — as the accepted baseline, so an intended change stops alerting. When the accept leaves nothing to fix, the monitor's open integrity incidents are resolved at once (`incidents_resolved`; the incident timeline says "baseline accepted by <key>"); otherwise a check of the pages starts right away (`check_requested`) and they close on clean checks. Pages no check has fetched yet are returned in `skipped`.
425
+ *
426
+ * Deploy hook: `POST /v1/monitors/{id}/baseline?fresh=true` (or `"fresh": true`) as the last step of a release. The server requests a check, waits for a result from that moment on (polling every ~3 s, at most ~85 s — under the 100 s proxy limit) and accepts from it, so the baseline is the new version and never the one before it; a page that check could not fetch is skipped, not taken from an older check. If the check takes longer you get **202** `pending` and the accept finishes in the background when the check lands (at most 5 minutes after the request) — poll `GET /v1/monitors/{id}/baseline` → `fresh_accept`. Fresh accepts share the accept's check budget (12 per hour per monitor, counting the check after each accept); over it → 429 with `Retry-After`. A paused monitor → 409.
419
427
  */
420
428
  post: operations["acceptMonitorBaseline"];
421
429
  delete?: never;
@@ -431,7 +439,10 @@ export interface paths {
431
439
  path?: never;
432
440
  cookie?: never;
433
441
  };
434
- /** Uptime (confirmed critical incidents only), check success (reachability, not health) and response-time stats (maintenance excluded) */
442
+ /**
443
+ * Uptime (confirmed critical incidents only), check success (reachability, not health) and response-time stats (maintenance excluded)
444
+ * @description Uptime and incidents cover any period on every plan. The check counts and response-time fields read the plan's charts & reports history. History limits: reads follow the plan's data retention (/docs/organization/data-retention). A window reaching further is cut, not refused — the response carries X-History-Limit-Days (the plan's window or `unlimited`), X-History-Earliest (oldest timestamp returned, ISO 8601) and X-History-Clamped: true when the requested window was cut.
445
+ */
435
446
  get: operations["getMonitorUptime"];
436
447
  put?: never;
437
448
  post?: never;
@@ -448,7 +459,10 @@ export interface paths {
448
459
  path?: never;
449
460
  cookie?: never;
450
461
  };
451
- /** Raw check history (cursor-paginated) + per-location breakdown */
462
+ /**
463
+ * Raw check history (cursor-paginated) + per-location breakdown
464
+ * @description History limits: reads follow the plan's data retention (/docs/organization/data-retention). A window reaching further is cut, not refused — the response carries X-History-Limit-Days (the plan's window or `unlimited`), X-History-Earliest (oldest timestamp returned, ISO 8601) and X-History-Clamped: true when the requested window was cut.
465
+ */
452
466
  get: operations["listMonitorChecks"];
453
467
  put?: never;
454
468
  post?: never;
@@ -982,7 +996,10 @@ export interface paths {
982
996
  path?: never;
983
997
  cookie?: never;
984
998
  };
985
- /** Organization audit trail (who changed what, when) */
999
+ /**
1000
+ * Organization audit trail (who changed what, when)
1001
+ * @description The log goes back as far as the plan's activity-log window; an earlier `since` is cut to it (X-History-Limit-Days, X-History-Earliest, X-History-Clamped headers).
1002
+ */
986
1003
  get: operations["listActivity"];
987
1004
  put?: never;
988
1005
  post?: never;
@@ -1053,7 +1070,10 @@ export interface paths {
1053
1070
  path?: never;
1054
1071
  cookie?: never;
1055
1072
  };
1056
- /** Org report for a period vs the previous one: uptime, incidents, MTTR/MTBF, response time, per-monitor rows, type-aware sections (SSL/domain expiry, Core Web Vitals, heartbeats, blocklists, MCP drift) and plain-language insights */
1073
+ /**
1074
+ * Org report for a period vs the previous one: uptime, incidents, MTTR/MTBF, response time, per-monitor rows, type-aware sections (SSL/domain expiry, Core Web Vitals, heartbeats, blocklists, MCP drift) and plain-language insights
1075
+ * @description Uptime and incidents cover any period. Check-based figures (check success, response time, p95, locations, host stats) read only the plan's charts & reports history: an earlier period start is counted from there, a comparison period reaching past it has no baseline, and meta.history ({chartHistoryDays, dataFromMs, clamped}) plus the X-History-* headers say so.
1076
+ */
1057
1077
  get: operations["getReport"];
1058
1078
  put?: never;
1059
1079
  post?: never;
@@ -1245,7 +1265,7 @@ export interface components {
1245
1265
  checks_updated?: number;
1246
1266
  };
1247
1267
  VariablePut: {
1248
- /** @description The value. For an existing secret, omit it to keep the stored one. */
1268
+ /** @description The value; a plain variable can't be empty (400). For an existing secret, omit it to keep the stored one. */
1249
1269
  value?: string;
1250
1270
  /**
1251
1271
  * @description Store encrypted and never show again; masked in logs, errors, traces and screenshots
@@ -1311,6 +1331,28 @@ export interface components {
1311
1331
  max: number;
1312
1332
  window_seconds: number;
1313
1333
  };
1334
+ /** @description A WatchFor Grade: the same A+ to F letter the dashboard shows for this check, from the same versioned rubric (https://watchfor.io/grades). Every grade starts at A+ and each finding can only cap it; `capped_by` lists the findings that hold it down, worst first. letter null = not graded (we could not measure — never a verdict on the target), with the reason in not_graded_reason. */
1335
+ WatchForGrade: {
1336
+ /** @enum {string|null} */
1337
+ letter: "A+" | "A" | "B" | "C" | "D" | "F" | null;
1338
+ /** @example Needs attention */
1339
+ label: string;
1340
+ /** @description Versioned rubric id, e.g. headers-2026.10. Changes whenever a rule changes. */
1341
+ rubric: string;
1342
+ /** @description Composite grades only (smart-audit, cdn-check): the weighted score behind the letter. */
1343
+ score?: number;
1344
+ /** @description Set when the grade covers less than everything, e.g. auth-discovery for an MCP server that requires sign-in. */
1345
+ scope?: string;
1346
+ capped_by: {
1347
+ /** @description Stable finding id, e.g. csp.missing. */
1348
+ id: string;
1349
+ title: string;
1350
+ /** @description The highest grade this finding allows; null = it costs points in a composite score instead. */
1351
+ cap: string | null;
1352
+ fix: string | null;
1353
+ }[];
1354
+ not_graded_reason?: string;
1355
+ };
1314
1356
  DiagnosticCatalogEntry: {
1315
1357
  /** @enum {string} */
1316
1358
  slug:
@@ -1318,6 +1360,7 @@ export interface components {
1318
1360
  | "cwv-check"
1319
1361
  | "dns-lookup"
1320
1362
  | "dns-propagation"
1363
+ | "dns-health"
1321
1364
  | "whois"
1322
1365
  | "ping"
1323
1366
  | "traceroute"
@@ -1348,6 +1391,8 @@ export interface components {
1348
1391
  composite: boolean;
1349
1392
  /** @description false = the answer is the same everywhere, so location_id is ignored. */
1350
1393
  location_aware: boolean;
1394
+ /** @description true = a run returns a WatchFor Grade in `grade`. */
1395
+ graded: boolean;
1351
1396
  target: {
1352
1397
  field: string;
1353
1398
  description: string;
@@ -1407,6 +1452,7 @@ export interface components {
1407
1452
  | "cwv-check"
1408
1453
  | "dns-lookup"
1409
1454
  | "dns-propagation"
1455
+ | "dns-health"
1410
1456
  | "whois"
1411
1457
  | "ping"
1412
1458
  | "traceroute"
@@ -1436,6 +1482,8 @@ export interface components {
1436
1482
  timed_out?: boolean;
1437
1483
  /** @description The probe's raw result — shape depends on the check (response, metrics, error). Composite checks return their aggregate here. */
1438
1484
  result: unknown;
1485
+ /** @description Graded checks only (tls-grade, http-headers, cwv-check, mcp-check, email-health with variant all, mail-server-check, cdn-check, smart-audit, dns-health): the dashboard's letter with the findings that set it. Omitted for other checks. */
1486
+ grade?: components["schemas"]["WatchForGrade"];
1439
1487
  /** @description Runs left for this check in the current window; null = unlimited. Pace long investigations by this. */
1440
1488
  remaining: number | null;
1441
1489
  allowance: components["schemas"]["DiagnosticAllowance"];
@@ -1452,6 +1500,7 @@ export interface components {
1452
1500
  | "cwv-check"
1453
1501
  | "dns-lookup"
1454
1502
  | "dns-propagation"
1503
+ | "dns-health"
1455
1504
  | "whois"
1456
1505
  | "ping"
1457
1506
  | "traceroute"
@@ -1485,6 +1534,7 @@ export interface components {
1485
1534
  success?: boolean | null;
1486
1535
  error?: string | null;
1487
1536
  result?: unknown;
1537
+ grade?: components["schemas"]["WatchForGrade"];
1488
1538
  };
1489
1539
  /** @description One machine-readable observation. `code` is stable and safe to branch on; `detail` is a sentence safe to relay verbatim. */
1490
1540
  DiagnosticFinding: {
@@ -1521,6 +1571,10 @@ export interface components {
1521
1571
  findings: components["schemas"]["DiagnosticFinding"][];
1522
1572
  };
1523
1573
  checks: components["schemas"]["DiagnosticCheck"][];
1574
+ /** @description WatchFor Grades of the graded checks in the bundle, keyed by check slug (tls-grade, http-headers). A skipped check has none. */
1575
+ grades: {
1576
+ [key: string]: components["schemas"]["WatchForGrade"];
1577
+ };
1524
1578
  locations_used: unknown[];
1525
1579
  location_select?: boolean;
1526
1580
  locations_available?: number;
@@ -1595,7 +1649,7 @@ export interface components {
1595
1649
  description?: string | null;
1596
1650
  interval_seconds?: number;
1597
1651
  /**
1598
- * @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.
1652
+ * @description Effective status. down = a confirmed critical incident is open (firing or acknowledged); degraded = an open warning incident, or a check failing without a confirmed incident yet — the latest check failed or any alert rule (availability, status code, response time, content, assertions…) is failing while its confirmation is in progress; unknown = no check data yet. paused always wins.
1599
1653
  * @enum {string}
1600
1654
  */
1601
1655
  status?: "up" | "degraded" | "down" | "paused" | "unknown";
@@ -1607,11 +1661,14 @@ export interface components {
1607
1661
  */
1608
1662
  ping_url?: string;
1609
1663
  active?: boolean;
1610
- /** @enum {string} */
1664
+ /**
1665
+ * @description Which locations run each check: roundrobin = one location per check, rotating through the selection; random = one location per check, picked at random from the selection (every plan, same load as roundrobin); parallel = every selected location on every check (plan-gated — GET /plan → limits.allowed_strategies and max_parallel_monitors). A strategy the plan does not include is refused with 403 forbidden.
1666
+ * @enum {string}
1667
+ */
1611
1668
  scheduling_strategy?: "roundrobin" | "random" | "parallel";
1612
1669
  locations?: string[];
1613
1670
  /**
1614
- * @description Why `status` is what it is: critical_incident = a confirmed critical incident is open (the only way to be down); warning_incident = an open warning incident; failed_check = the latest check failed, not yet confirmed (degraded); paused; no_data = nothing reported yet (unknown); ok. Present on GET/POST/PATCH/pause/resume responses.
1671
+ * @description Why `status` is what it is: critical_incident = a confirmed critical incident is open (the only way to be down); warning_incident = an open warning incident; failed_check = a check is failing (the latest check failed, or an alert rule such as status code or response time is failing) without a confirmed incident yet (degraded); paused; no_data = nothing reported yet (unknown); ok. Present on GET/POST/PATCH/pause/resume responses.
1615
1672
  * @enum {string}
1616
1673
  */
1617
1674
  status_reason?:
@@ -1626,6 +1683,23 @@ export interface components {
1626
1683
  * @description When the open incident behind a critical_incident / warning_incident started; null otherwise.
1627
1684
  */
1628
1685
  status_since?: string | null;
1686
+ /** @description GET /monitors/{id} only: what the alerting engine sees right now. alerted = a rule's incident is still open in the engine; recovering = every such rule has had healthy checks since, but not enough to resolve yet (count of threshold — 'Recovering 1/3'); while alerted and not recovering, the rule behind the incident is still failing. failing = a rule is failing below its confirmation threshold (no incident yet), confirming = how far it is ('2 of 3'). null when the engine reports nothing (every rule healthy, or it did not answer in time). */
1687
+ alerting_state?: {
1688
+ alerted?: boolean;
1689
+ recovering?: {
1690
+ count?: number;
1691
+ threshold?: number;
1692
+ } | null;
1693
+ failing?: boolean;
1694
+ /** Format: date-time */
1695
+ failing_since?: string | null;
1696
+ confirming?: {
1697
+ count?: number;
1698
+ threshold?: number;
1699
+ } | null;
1700
+ } | null;
1701
+ /** @description PATCH /monitors/{id} responses only: true when the update changed how the check connects (target, port, credentials, TLS, request, record type, script…) and one immediate check was dispatched, so the result reflects the new settings within seconds instead of after a full interval. It does not use the plan's Run-now budget; saves are capped at 10 such checks per monitor per hour. false for alert-rule-only or cosmetic changes and for paused, heartbeat and host monitors. */
1702
+ check_queued?: boolean;
1629
1703
  /** @description The open (firing or acknowledged) incident, or null. When several are open: the critical one, then the earliest started. */
1630
1704
  current_incident?: components["schemas"]["MonitorCurrentIncident"] | null;
1631
1705
  /** @description A silence (dashboard Mute) suppresses notifications; incidents still open and close and checks continue. */
@@ -1771,6 +1845,7 @@ export interface components {
1771
1845
  /** @description Location ids from GET /locations; at least one is required except for heartbeat, which takes none (a non-empty list on a heartbeat is a 400) */
1772
1846
  locations?: string[];
1773
1847
  /**
1848
+ * @description Which locations run each check: roundrobin = one location per check, rotating through the selection; random = one location per check, picked at random from the selection (every plan, same load as roundrobin); parallel = every selected location on every check (plan-gated — GET /plan → limits.allowed_strategies and max_parallel_monitors). A strategy the plan does not include is refused with 403 forbidden.
1774
1849
  * @default roundrobin
1775
1850
  * @enum {string}
1776
1851
  */
@@ -1797,7 +1872,10 @@ export interface components {
1797
1872
  /** @description null clears the description */
1798
1873
  description?: string | null;
1799
1874
  interval?: number;
1800
- /** @enum {string} */
1875
+ /**
1876
+ * @description Which locations run each check: roundrobin = one location per check, rotating through the selection; random = one location per check, picked at random from the selection (every plan, same load as roundrobin); parallel = every selected location on every check (plan-gated — GET /plan → limits.allowed_strategies and max_parallel_monitors). A strategy the plan does not include is refused with 403 forbidden.
1877
+ * @enum {string}
1878
+ */
1801
1879
  schedulingStrategy?: "roundrobin" | "random" | "parallel";
1802
1880
  locations?: string[];
1803
1881
  tags?: string[];
@@ -1831,8 +1909,11 @@ export interface components {
1831
1909
  total_checks?: number;
1832
1910
  successful_checks?: number;
1833
1911
  failed_checks?: number;
1912
+ /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded */
1834
1913
  avg_response_time_ms?: number | null;
1914
+ /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded */
1835
1915
  min_response_time_ms?: number | null;
1916
+ /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded */
1836
1917
  max_response_time_ms?: number | null;
1837
1918
  last_failure_at?: string | null;
1838
1919
  /** @description Incident-based headline uptime for the last 24 hours */
@@ -1852,6 +1933,17 @@ export interface components {
1852
1933
  resolved_at?: string | null;
1853
1934
  downtime_ms?: number;
1854
1935
  }[];
1936
+ /** @description Only with series=true: the width of each response_time_series bucket (300 for 24h, 900 for 7d). */
1937
+ series_bucket_seconds?: number;
1938
+ /** @description Only with series=true (periods up to 7d): the period on a real time axis, oldest first. Only buckets that held checks appear. avg_ms / max_ms cover the bucket's successful checks; null when every check in it failed (draw a gap). */
1939
+ response_time_series?: {
1940
+ /** Format: date-time */
1941
+ at?: string;
1942
+ checks?: number;
1943
+ failed?: number;
1944
+ avg_ms?: number | null;
1945
+ max_ms?: number | null;
1946
+ }[];
1855
1947
  };
1856
1948
  /** @description One probe run. Type-specific fields appear only when the probe recorded them (packet loss for ICMP, rcode and answer count for DNS, connect / TLS handshake times for TCP, relay and PTR checks for SMTP, sitemap counts). */
1857
1949
  Check: {
@@ -1917,7 +2009,7 @@ export interface components {
1917
2009
  sitemap_url_count?: number;
1918
2010
  sitemap_broken_urls?: number;
1919
2011
  sitemap_broken_percent?: number;
1920
- /** @description The stored output, redacted: a JSON object whose shape depends on the monitor type; a string when the probe recorded plain text; null when stored is false */
2012
+ /** @description The stored output, redacted: a JSON object whose shape depends on the monitor type; a string when the probe recorded plain text; null when stored is false. Failed checks always keep their output. For successful http, smtp, mtr, brotli and favicon checks the output is kept as a short-lived sample — about one successful check every 10 minutes per location, the last ~8 per location, for at most 2 days; other successful checks of those types return stored: false. */
1921
2013
  result?: Record<string, never> | string | null;
1922
2014
  /** @description Size of the stored output before redaction (0 when nothing is stored) */
1923
2015
  result_bytes?: number;
@@ -2110,10 +2202,37 @@ export interface components {
2110
2202
  }[];
2111
2203
  trusted_origins?: string[];
2112
2204
  text_change_threshold?: number;
2205
+ /** @description The latest fresh accept (`POST …/baseline?fresh=true`), kept for 24 hours; null when there was none. Poll it after a 202: `pending` until the check lands, then `accepted` (with what was accepted), `expired` (no check arrived within 5 minutes — nothing was accepted) or `failed`. */
2206
+ fresh_accept?: {
2207
+ /** @enum {string} */
2208
+ status: "pending" | "accepted" | "expired" | "failed";
2209
+ /** Format: date-time */
2210
+ requested_at: string;
2211
+ /**
2212
+ * Format: date-time
2213
+ * @description A pending accept that has not finished by now is expired
2214
+ */
2215
+ expires_at: string;
2216
+ /** Format: date-time */
2217
+ finished_at?: string | null;
2218
+ /** @description The pages asked for; null = all */
2219
+ pages?: string[] | null;
2220
+ accepted?: string[] | null;
2221
+ skipped?:
2222
+ | {
2223
+ url: string;
2224
+ reason: string;
2225
+ }[]
2226
+ | null;
2227
+ incidents_resolved?: number[] | null;
2228
+ message?: string | null;
2229
+ } | null;
2113
2230
  };
2114
2231
  IntegrityBaselineAcceptRequest: {
2115
2232
  /** @description Accept only these watched pages; omit for all */
2116
2233
  pages?: string[];
2234
+ /** @description Same as the `fresh` query parameter: check the pages first and accept what that check saw */
2235
+ fresh?: boolean;
2117
2236
  };
2118
2237
  IntegrityBaselineAccept: {
2119
2238
  /** @constant */
@@ -2127,8 +2246,34 @@ export interface components {
2127
2246
  }[];
2128
2247
  /** Format: date-time */
2129
2248
  captured_at?: string | null;
2249
+ /** @constant */
2250
+ status?: "accepted";
2130
2251
  /** @description A check of the pages was started right after the accept, so open findings close on it within a minute or two instead of at the next scheduled check */
2131
2252
  check_requested?: boolean;
2253
+ /** @description Open integrity incidents of the monitor resolved by this accept — nothing was left to fix (every watched page matches its baseline in the newest check). Empty when some page still differs or could not be fetched; those close on clean checks as usual */
2254
+ incidents_resolved?: number[];
2255
+ /**
2256
+ * Format: date-time
2257
+ * @description Fresh accepts: when the check was requested
2258
+ */
2259
+ requested_at?: string;
2260
+ };
2261
+ /** @description A fresh accept whose check has not landed yet — it finishes in the background; `GET /v1/monitors/{id}/baseline` → `fresh_accept` shows the outcome */
2262
+ IntegrityBaselineAcceptPending: {
2263
+ /** @constant */
2264
+ object: "integrity_baseline_accept";
2265
+ /** Format: uuid */
2266
+ monitor_id: string;
2267
+ /** @constant */
2268
+ status: "pending";
2269
+ /** Format: date-time */
2270
+ requested_at: string;
2271
+ /**
2272
+ * Format: date-time
2273
+ * @description The accept gives up (nothing accepted) if no check has landed by then
2274
+ */
2275
+ expires_at: string;
2276
+ message?: string;
2132
2277
  };
2133
2278
  MonitorReset: {
2134
2279
  /** @constant */
@@ -2240,6 +2385,12 @@ export interface components {
2240
2385
  /** Format: date-time */
2241
2386
  updated_at?: string;
2242
2387
  };
2388
+ MaintenanceMarking: {
2389
+ /** @enum {string} */
2390
+ object: "maintenance_marking";
2391
+ incident_id: number;
2392
+ maintenance_window: components["schemas"]["MaintenanceWindow"];
2393
+ };
2243
2394
  MaintenanceWindow: {
2244
2395
  /** Format: uuid */
2245
2396
  id?: string;
@@ -2376,7 +2527,10 @@ export interface components {
2376
2527
  * @default true
2377
2528
  */
2378
2529
  autoPublishIncidents: boolean;
2379
- /** @default false */
2530
+ /**
2531
+ * @description Days before a component's monitor existed show as no data instead of 100 % uptime
2532
+ * @default true
2533
+ */
2380
2534
  dimUntrackedDays: boolean;
2381
2535
  /**
2382
2536
  * @default auto
@@ -2747,7 +2901,7 @@ export interface components {
2747
2901
  Summary: {
2748
2902
  /** @constant */
2749
2903
  object?: "summary";
2750
- /** @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). */
2904
+ /** @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 a failing check or alert rule without a confirmed incident counts as degraded; paused always wins. health_score is 0-100 (share of active, non-paused monitors that are up). */
2751
2905
  monitors?: {
2752
2906
  total?: number;
2753
2907
  up?: number;
@@ -3004,9 +3158,12 @@ export interface components {
3004
3158
  * @description Alias of success_percent
3005
3159
  */
3006
3160
  uptime_percent?: number;
3007
- avg_response_time_ms?: number;
3008
- min_response_time_ms?: number;
3009
- max_response_time_ms?: number;
3161
+ /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded at this location */
3162
+ avg_response_time_ms?: number | null;
3163
+ /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded at this location */
3164
+ min_response_time_ms?: number | null;
3165
+ /** @description Latency over successful checks only (a failed check has no response time); null when no check succeeded at this location */
3166
+ max_response_time_ms?: number | null;
3010
3167
  }[];
3011
3168
  /** @description Pass as ?cursor= for the next (older) page; null on the last page */
3012
3169
  next_cursor?: string | null;
@@ -3154,6 +3311,16 @@ export interface components {
3154
3311
  */
3155
3312
  resolverMode: "fixed" | "random";
3156
3313
  };
3314
+ /** @description Options for the `dns-health` diagnostic. Is this domain's DNS set up well — at least two nameservers on separate networks, no lame delegation, parent and zone agreeing, SOA serials in sync, DNSSEC valid, CAA published — as an A+…F grade? Add propagation:true to also grade whether every probe location sees the same answer. */
3315
+ DiagnosticOptionsDnsHealth: {
3316
+ /** @default false */
3317
+ propagation: boolean;
3318
+ /**
3319
+ * @default A
3320
+ * @enum {string}
3321
+ */
3322
+ recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS";
3323
+ };
3157
3324
  /** @description Options for the `whois` diagnostic. Who owns this domain, when does it expire, which registrar and nameservers does the registry list (live RDAP, cache bypassed)? */
3158
3325
  DiagnosticOptionsWhois: Record<string, never>;
3159
3326
  /** @description Options for the `ping` diagnostic. Is this host reachable by ICMP from a given location, and what is the round-trip time and packet loss? */
@@ -3263,7 +3430,10 @@ export interface components {
3263
3430
  };
3264
3431
  };
3265
3432
  responses: never;
3266
- parameters: never;
3433
+ parameters: {
3434
+ /** @description OAuth tokens only: the id of the organization to act on. The token's user must be a member (otherwise 403 forbidden), and their role there applies — members can read, acknowledge incidents and run diagnostics; creating, changing and deleting needs owner or admin, as in the dashboard. Omitted: the user's oldest owned organization, else their oldest membership. With an API key the header may only repeat the key's own organization id (anything else is 403). */
3435
+ OrganizationHeader: string;
3436
+ };
3267
3437
  requestBodies: never;
3268
3438
  headers: never;
3269
3439
  pathItems: never;
@@ -3619,6 +3789,7 @@ export interface operations {
3619
3789
  | "cwv-check"
3620
3790
  | "dns-lookup"
3621
3791
  | "dns-propagation"
3792
+ | "dns-health"
3622
3793
  | "whois"
3623
3794
  | "ping"
3624
3795
  | "traceroute"
@@ -3812,7 +3983,7 @@ export interface operations {
3812
3983
  /** @description Opaque cursor from the previous page's next_cursor */
3813
3984
  cursor?: string;
3814
3985
  type?: string;
3815
- /** @description Effective status: down = confirmed critical incident open; degraded = failed check not yet confirmed, or an open warning incident */
3986
+ /** @description Effective status, the same value the rows carry: down = confirmed critical incident open; degraded = a failing check or alert rule not yet confirmed, or an open warning incident */
3816
3987
  status?: "up" | "degraded" | "down" | "paused" | "unknown";
3817
3988
  tag?: string;
3818
3989
  /** @description Case-insensitive substring search over name and target */
@@ -4194,7 +4365,10 @@ export interface operations {
4194
4365
  };
4195
4366
  acceptMonitorBaseline: {
4196
4367
  parameters: {
4197
- query?: never;
4368
+ query?: {
4369
+ /** @description Check the pages first, wait for that check (up to ~85 s) and accept what it saw — the deploy-hook mode. 202 `pending` when the check takes longer. */
4370
+ fresh?: boolean;
4371
+ };
4198
4372
  header?: {
4199
4373
  /** @description Unique key for safe retries (Stripe semantics, 24h window): the same key + body replays the original response instead of re-creating. */
4200
4374
  "Idempotency-Key"?: string;
@@ -4220,6 +4394,15 @@ export interface operations {
4220
4394
  "application/json": components["schemas"]["IntegrityBaselineAccept"];
4221
4395
  };
4222
4396
  };
4397
+ /** @description Fresh accept: the check is still running — the accept finishes in the background */
4398
+ 202: {
4399
+ headers: {
4400
+ [name: string]: unknown;
4401
+ };
4402
+ content: {
4403
+ "application/json": components["schemas"]["IntegrityBaselineAcceptPending"];
4404
+ };
4405
+ };
4223
4406
  /** @description Error */
4224
4407
  default: {
4225
4408
  headers: {
@@ -4235,6 +4418,8 @@ export interface operations {
4235
4418
  parameters: {
4236
4419
  query?: {
4237
4420
  period?: "1h" | "24h" | "7d" | "30d" | "90d";
4421
+ /** @description true adds response_time_series (bucketed response times on a real time axis) — periods up to 7d */
4422
+ series?: boolean;
4238
4423
  };
4239
4424
  header?: never;
4240
4425
  path: {
@@ -4268,6 +4453,7 @@ export interface operations {
4268
4453
  listMonitorChecks: {
4269
4454
  parameters: {
4270
4455
  query?: {
4456
+ /** @description Window in hours, cut to the plan's check history when it reaches further (see X-History-Clamped) */
4271
4457
  hours?: number;
4272
4458
  /** @description Page size, 1–100 (default 50). Any other value — 0, negative, non-integer — returns 400. A `sort` query parameter is not supported and returns 400 naming the fixed order. */
4273
4459
  limit?: number;
@@ -4312,7 +4498,7 @@ export interface operations {
4312
4498
  path: {
4313
4499
  /** @description Resource id (UUID) */
4314
4500
  id: string;
4315
- /** @description The check's run_id as listed by GET /monitors/{id}/checks (opaque; malformed → 400, unknown for this monitor → 404) */
4501
+ /** @description The check's run_id as listed by GET /monitors/{id}/checks (opaque; malformed → 400, unknown for this monitor or older than the plan's check history → 404) */
4316
4502
  run_id: string;
4317
4503
  };
4318
4504
  cookie?: never;
@@ -4799,21 +4985,23 @@ export interface operations {
4799
4985
  };
4800
4986
  requestBody?: never;
4801
4987
  responses: {
4802
- /** @description Incident marked as maintenance */
4988
+ /** @description Already marked: the existing maintenance window */
4803
4989
  200: {
4804
4990
  headers: {
4805
4991
  [name: string]: unknown;
4806
4992
  };
4807
4993
  content: {
4808
- "application/json": components["schemas"]["Incident"];
4994
+ "application/json": components["schemas"]["MaintenanceMarking"];
4809
4995
  };
4810
4996
  };
4811
- /** @description Marked; returns the maintenance window */
4997
+ /** @description Marked: the maintenance window created for it */
4812
4998
  201: {
4813
4999
  headers: {
4814
5000
  [name: string]: unknown;
4815
5001
  };
4816
- content?: never;
5002
+ content: {
5003
+ "application/json": components["schemas"]["MaintenanceMarking"];
5004
+ };
4817
5005
  };
4818
5006
  /** @description Error */
4819
5007
  default: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.13.0",
3
+ "version": "0.15.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",