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 +68 -3
- package/dist/cli.js +47 -3
- package/dist/client.d.ts +166 -18
- package/dist/client.js +115 -11
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/schema.d.ts +214 -26
- package/package.json +1 -1
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,
|
|
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
|
|
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
|
|
28
|
-
|
|
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
|
|
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`
|
|
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
|
-
|
|
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_
|
|
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
|
-
/**
|
|
80
|
-
|
|
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
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
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<
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
160
|
-
*
|
|
161
|
-
*
|
|
162
|
-
*
|
|
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
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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.
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
/**
|
|
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,
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
-
|
|
3008
|
-
|
|
3009
|
-
|
|
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:
|
|
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 =
|
|
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?:
|
|
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
|
|
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"]["
|
|
4994
|
+
"application/json": components["schemas"]["MaintenanceMarking"];
|
|
4809
4995
|
};
|
|
4810
4996
|
};
|
|
4811
|
-
/** @description Marked
|
|
4997
|
+
/** @description Marked: the maintenance window created for it */
|
|
4812
4998
|
201: {
|
|
4813
4999
|
headers: {
|
|
4814
5000
|
[name: string]: unknown;
|
|
4815
5001
|
};
|
|
4816
|
-
content
|
|
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.
|
|
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",
|