watchfor 0.12.0 → 0.13.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
@@ -1,7 +1,7 @@
1
1
  # watchfor
2
2
 
3
3
  Official TypeScript SDK + CLI for [WatchFor](https://watchfor.io) —
4
- uptime & infrastructure monitoring (27 check types, confirmed alerting,
4
+ uptime & infrastructure monitoring (30 check types, confirmed alerting,
5
5
  status pages, on-call).
6
6
 
7
7
  ```bash
@@ -47,6 +47,12 @@ const { id } = await wf.playwright.testRun({ script, target: "https://shop.examp
47
47
  const run = await wf.playwright.getTestRun(id); // status: queued | running | done | error
48
48
  await wf.variables.put("LOGIN_PASSWORD", { value: process.env.PW!, secret: true });
49
49
 
50
+ // The same org secrets in HTTP/API/MCP checks: {{NAME}} in auth, a header or the body.
51
+ await wf.variables.put("API_TOKEN", { value: process.env.API_TOKEN!, secret: true });
52
+ await wf.monitors.update(apiMonitorId, {
53
+ config: { requestHeaders: [{ key: "Authorization", value: "Bearer {{API_TOKEN}}" }] },
54
+ });
55
+
50
56
  // Older checks: pass next_cursor back as cursor (keep the same hours/success).
51
57
  const page = await wf.monitors.checks(monitor.id!, { hours: 24, limit: 100 });
52
58
  if (page.next_cursor) {
@@ -59,7 +65,7 @@ await wf.contactGroups.delete("<group-id>", { force: true });
59
65
 
60
66
  ### Live diagnostics
61
67
 
62
- Run any of 22 checks from WatchFor's probe fleet against **any public
68
+ Run any of 23 checks from WatchFor's probe fleet against **any public
63
69
  target**, monitored or not — this measures right now, rather than reading
64
70
  what WatchFor recorded:
65
71
 
package/dist/client.d.ts CHANGED
@@ -121,7 +121,7 @@ export declare class WatchFor {
121
121
  }): Promise<Record<string, unknown>>;
122
122
  /** Probe locations for monitor creation. */
123
123
  locations(): Promise<List<Record<string, unknown>>>;
124
- /** All 25 monitor types with exact alert metrics + config fields. */
124
+ /** Every monitor type with its exact alert metrics + config fields. */
125
125
  monitorTypes(): Promise<List<Record<string, unknown>>>;
126
126
  readonly monitors: {
127
127
  list: (q?: {
@@ -135,7 +135,18 @@ export declare class WatchFor {
135
135
  /** The monitor plus `available_metrics` — the alert metrics valid for
136
136
  * its type. */
137
137
  get: (id: string) => Promise<MonitorDetail>;
138
+ /** Create a monitor; `config` keys per type come from `monitorTypes()`.
139
+ * Credentials (catalog fields marked `secret` — mailbox/SMTP/FTP
140
+ * passwords, SSH keys, HTTP/API/MCP auth passwords and bearer
141
+ * tokens, credential header values) are write-only: stored encrypted
142
+ * and returned as `"[redacted]"`. `{{NAME}}` in an auth field,
143
+ * header value or request body uses an org variable or secret. */
138
144
  create: (body: Record<string, unknown>, idempotencyKey?: string) => Promise<Monitor>;
145
+ /** Partial update; `config` is merged (omitted keys kept, `null`
146
+ * removes). A `"[redacted]"` credential is kept when omitted or sent
147
+ * back unchanged; changing the server, port, TLS mode or login it is
148
+ * used with (HTTP: the URL's host, port or scheme) needs it again in
149
+ * the same call (else 400). */
139
150
  update: (id: string, body: Record<string, unknown>) => Promise<Monitor>;
140
151
  delete: (id: string) => Promise<Deleted>;
141
152
  pause: (id: string) => Promise<Monitor>;
@@ -151,9 +162,10 @@ export declare class WatchFor {
151
162
  * page (whether it has one, when and how it was captured). */
152
163
  getBaseline: (id: string) => Promise<IntegrityBaseline>;
153
164
  /** Page integrity monitors: accept what the newest check saw as the
154
- * new baseline — all pages, or only `pages`. Call it from a deploy
155
- * pipeline a minute after the release; unfetched pages come back in
156
- * `skipped`. */
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`. */
157
169
  acceptBaseline: (id: string, body?: {
158
170
  pages?: string[];
159
171
  }, idempotencyKey?: string) => Promise<IntegrityBaselineAccept>;
@@ -207,7 +219,8 @@ export declare class WatchFor {
207
219
  getTestRun: (id: string) => Promise<PlaywrightTestRun>;
208
220
  };
209
221
  /**
210
- * Org variables and secrets browser checks read as process.env.NAME.
222
+ * Org variables and secrets — browser checks read them as
223
+ * process.env.NAME, HTTP/API/MCP checks as {{NAME}}.
211
224
  * Secrets are write-only: `list()` never returns their value.
212
225
  */
213
226
  readonly variables: {
package/dist/client.js CHANGED
@@ -119,7 +119,7 @@ export class WatchFor {
119
119
  locations() {
120
120
  return this.request("GET", "/locations");
121
121
  }
122
- /** All 25 monitor types with exact alert metrics + config fields. */
122
+ /** Every monitor type with its exact alert metrics + config fields. */
123
123
  monitorTypes() {
124
124
  return this.request("GET", "/meta/monitor-types");
125
125
  }
@@ -129,7 +129,18 @@ export class WatchFor {
129
129
  /** The monitor plus `available_metrics` — the alert metrics valid for
130
130
  * its type. */
131
131
  get: (id) => this.request("GET", `/monitors/${id}`),
132
+ /** Create a monitor; `config` keys per type come from `monitorTypes()`.
133
+ * Credentials (catalog fields marked `secret` — mailbox/SMTP/FTP
134
+ * passwords, SSH keys, HTTP/API/MCP auth passwords and bearer
135
+ * tokens, credential header values) are write-only: stored encrypted
136
+ * and returned as `"[redacted]"`. `{{NAME}}` in an auth field,
137
+ * header value or request body uses an org variable or secret. */
132
138
  create: (body, idempotencyKey) => this.request("POST", "/monitors", { body, idempotencyKey }),
139
+ /** Partial update; `config` is merged (omitted keys kept, `null`
140
+ * removes). A `"[redacted]"` credential is kept when omitted or sent
141
+ * back unchanged; changing the server, port, TLS mode or login it is
142
+ * used with (HTTP: the URL's host, port or scheme) needs it again in
143
+ * the same call (else 400). */
133
144
  update: (id, body) => this.request("PATCH", `/monitors/${id}`, { body }),
134
145
  delete: (id) => this.request("DELETE", `/monitors/${id}`),
135
146
  pause: (id) => this.request("POST", `/monitors/${id}/pause`),
@@ -145,9 +156,10 @@ export class WatchFor {
145
156
  * page (whether it has one, when and how it was captured). */
146
157
  getBaseline: (id) => this.request("GET", `/monitors/${id}/baseline`),
147
158
  /** Page integrity monitors: accept what the newest check saw as the
148
- * new baseline — all pages, or only `pages`. Call it from a deploy
149
- * pipeline a minute after the release; unfetched pages come back in
150
- * `skipped`. */
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`. */
151
163
  acceptBaseline: (id, body, idempotencyKey) => this.request("POST", `/monitors/${id}/baseline`, {
152
164
  body: body ?? {},
153
165
  idempotencyKey,
@@ -191,7 +203,8 @@ export class WatchFor {
191
203
  getTestRun: (id) => this.request("GET", `/playwright/test-runs/${id}`),
192
204
  };
193
205
  /**
194
- * Org variables and secrets browser checks read as process.env.NAME.
206
+ * Org variables and secrets — browser checks read them as
207
+ * process.env.NAME, HTTP/API/MCP checks as {{NAME}}.
195
208
  * Secrets are write-only: `list()` never returns their value.
196
209
  */
197
210
  variables = {
package/dist/schema.d.ts CHANGED
@@ -116,7 +116,7 @@ export interface paths {
116
116
  path?: never;
117
117
  cookie?: never;
118
118
  };
119
- /** Org variables and secrets browser checks read as process.env.NAME (secrets without values) */
119
+ /** Org variables and secrets — browser checks read them as process.env.NAME, HTTP/API/MCP checks as {{NAME}} (secrets without values) */
120
120
  get: operations["listVariables"];
121
121
  put?: never;
122
122
  post?: never;
@@ -415,7 +415,7 @@ export interface paths {
415
415
  put?: never;
416
416
  /**
417
417
  * 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 and the next check compares against it. Pages no check has fetched yet are returned in `skipped`. Typical use: the last step of a deploy pipeline, a minute after the release (so a check has seen the new version).
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.
419
419
  */
420
420
  post: operations["acceptMonitorBaseline"];
421
421
  delete?: never;
@@ -1334,6 +1334,7 @@ export interface components {
1334
1334
  | "redirect-chain"
1335
1335
  | "websocket-test"
1336
1336
  | "smtp-test"
1337
+ | "mail-server-check"
1337
1338
  | "ntp-test"
1338
1339
  | "email-health";
1339
1340
  label: string;
@@ -1422,6 +1423,7 @@ export interface components {
1422
1423
  | "redirect-chain"
1423
1424
  | "websocket-test"
1424
1425
  | "smtp-test"
1426
+ | "mail-server-check"
1425
1427
  | "ntp-test"
1426
1428
  | "email-health";
1427
1429
  target: string;
@@ -1466,6 +1468,7 @@ export interface components {
1466
1468
  | "redirect-chain"
1467
1469
  | "websocket-test"
1468
1470
  | "smtp-test"
1471
+ | "mail-server-check"
1469
1472
  | "ntp-test"
1470
1473
  | "email-health";
1471
1474
  label: string;
@@ -1543,7 +1546,7 @@ export interface components {
1543
1546
  type: "string" | "number" | "boolean" | "enum" | "array" | "object";
1544
1547
  enum?: string[];
1545
1548
  default?: unknown;
1546
- /** @description Write-only credential; read back as [redacted] */
1549
+ /** @description Write-only credential, stored encrypted; read back as "[redacted]". On update omit it, send "" or "[redacted]" to keep it, null to remove it */
1547
1550
  secret?: boolean;
1548
1551
  description?: string;
1549
1552
  };
@@ -1584,7 +1587,10 @@ export interface components {
1584
1587
  | "mcp"
1585
1588
  | "api"
1586
1589
  | "integrity"
1587
- | "playwright";
1590
+ | "playwright"
1591
+ | "imap"
1592
+ | "pop3"
1593
+ | "email_roundtrip";
1588
1594
  target?: string;
1589
1595
  description?: string | null;
1590
1596
  interval_seconds?: number;
@@ -1629,8 +1635,10 @@ export interface components {
1629
1635
  /** @description true when an alert rule is routed to a contact group or the monitor has its own notification groups; false = the dashboard's silent-monitor warning: an incident here would reach nobody. */
1630
1636
  has_notification_route?: boolean;
1631
1637
  tags?: string[];
1632
- /** @description Type-specific config; secret values are [redacted] */
1633
- config?: Record<string, never>;
1638
+ /** @description Type-specific config (keys per type under config_fields in GET /meta/monitor-types). Credentials (catalog fields marked secret) are write-only and read back as "[redacted]" */
1639
+ config?: {
1640
+ [key: string]: unknown;
1641
+ };
1634
1642
  /** Format: date-time */
1635
1643
  created_at?: string;
1636
1644
  /**
@@ -1752,7 +1760,10 @@ export interface components {
1752
1760
  | "mcp"
1753
1761
  | "api"
1754
1762
  | "integrity"
1755
- | "playwright";
1763
+ | "playwright"
1764
+ | "imap"
1765
+ | "pop3"
1766
+ | "email_roundtrip";
1756
1767
  /** @description Format per type (see GET /meta/monitor-types). Targets in private, loopback, link-local or cloud-metadata address space (and internal hostnames such as localhost, *.internal) are rejected with 400. */
1757
1768
  target: string;
1758
1769
  /** @description Seconds; validated against the plan's per-type minimum */
@@ -1767,8 +1778,10 @@ export interface components {
1767
1778
  /** @description Lowercase alphanumeric with hyphens or colons, e.g. prod, team:web */
1768
1779
  tags?: string[];
1769
1780
  description?: string | null;
1770
- /** @description Type-specific settings — the keys and types are listed per type under config_fields in GET /meta/monitor-types. Validated against the monitor type: a wrong value returns 400 naming the field (e.g. `config.timeoutSeconds`); keys the type does not use are dropped. Config that drives an alert preset (dns expectedValues, cdn expectedProvider, cms expectedCms, tcp/udp expectMatchRegexp, websocket expectPattern, mcp expectedProtocolVersion, http failIfBody*Regexp) also creates that preset's alert rule. */
1771
- config?: Record<string, never>;
1781
+ /** @description Type-specific settings — the keys and types are listed per type under config_fields in GET /meta/monitor-types. Validated against the monitor type: a wrong value returns 400 naming the field (e.g. `config.timeoutSeconds`); keys the type does not use are dropped. Config that drives an alert preset (dns expectedValues, cdn expectedProvider, cms expectedCms, tcp/udp expectMatchRegexp, websocket expectPattern, mcp expectedProtocolVersion, http failIfBody*Regexp) also creates that preset's alert rule. Credential keys (marked secret in the catalog: password, smtpPassword, receivePassword, privateKey, …) are write-only and stored encrypted; responses return them as "[redacted]". */
1782
+ config?: {
1783
+ [key: string]: unknown;
1784
+ };
1772
1785
  /** @default false */
1773
1786
  isPaused: boolean;
1774
1787
  /**
@@ -1788,8 +1801,10 @@ export interface components {
1788
1801
  schedulingStrategy?: "roundrobin" | "random" | "parallel";
1789
1802
  locations?: string[];
1790
1803
  tags?: string[];
1791
- /** @description Merged into the stored config: an omitted key is kept, a key set to null is removed, any other value replaces the stored one — arrays and nested objects are replaced whole (requestHeaders: [] clears all headers). The merged result is validated against the monitor type (400 with the field path on a bad value; unknown keys dropped). Alerting-owned keys (notificationGroupIds, confirmationThreshold, durationWindow, repeatIntervalSeconds, failIfBody*Regexp, …) follow the same rule. */
1792
- config?: Record<string, never>;
1804
+ /** @description Merged into the stored config: an omitted key is kept, a key set to null is removed, any other value replaces the stored one — arrays and nested objects are replaced whole (requestHeaders: [] clears all headers). The merged result is validated against the monitor type (400 with the field path on a bad value; unknown keys dropped). Alerting-owned keys (notificationGroupIds, confirmationThreshold, durationWindow, repeatIntervalSeconds, expiryReminderDays, failIfBody*Regexp, …) follow the same rule. expiryReminderDays (http, api, mcp, ssl, rdap only) takes whole days 1–365, at most 5, e.g. [14, 3]: an open, unacknowledged certificate- or domain-expiry incident is notified again once when that many days are left. Credentials (catalog fields marked secret — incl. HTTP/API/MCP authPassword and bearerToken — and the values of credential request headers such as Authorization, Cookie or X-API-Key) are write-only and stored encrypted: omitting one, sending "" or the "[redacted]" a read returned keeps the stored value (headers: same header name), null removes it, a new value replaces it; a mask on a header with nothing stored is a 400 naming the field. A requestBody read back as "[redacted]" and sent back unchanged keeps the stored body. {{NAME}} in an auth field, header value or request body references an org variable or secret (GET /v1/variables); it is stored as written and an unknown name is a 400. Changing the server, port, TLS mode or login a stored credential is used with (target, port, tlsMode, username, the round trip's smtp*\/receive* legs; for HTTP/API/MCP the URL's host, port or scheme and the basic-auth username) or turning verifyTls off requires sending the credential again in the same request — otherwise 400 `config.<field>: Re-enter the …`. */
1805
+ config?: {
1806
+ [key: string]: unknown;
1807
+ };
1793
1808
  };
1794
1809
  CheckNowAck: {
1795
1810
  /** @constant */
@@ -2049,7 +2064,7 @@ export interface components {
2049
2064
  /** @description Evaluations that fired before and during the incident */
2050
2065
  fire_count?: number;
2051
2066
  flapping?: boolean;
2052
- /** @description Only on GET /incidents/{id}: the incident's events in order (opened, notified, acknowledged, resolved, …). */
2067
+ /** @description Only on GET /incidents/{id}: the incident's events in order (opened, notified, acknowledged, resolved, …). A certificate- or domain-expiry incident also records a `reminder` event each time a reminder day is reached (detail: days_left, expires_on, milestone, kind, subject). */
2053
2068
  timeline?: {
2054
2069
  /** Format: date-time */
2055
2070
  at?: string;
@@ -2112,6 +2127,8 @@ export interface components {
2112
2127
  }[];
2113
2128
  /** Format: date-time */
2114
2129
  captured_at?: string | null;
2130
+ /** @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
+ check_requested?: boolean;
2115
2132
  };
2116
2133
  MonitorReset: {
2117
2134
  /** @constant */
@@ -2705,7 +2722,10 @@ export interface components {
2705
2722
  | "mcp"
2706
2723
  | "api"
2707
2724
  | "integrity"
2708
- | "playwright";
2725
+ | "playwright"
2726
+ | "imap"
2727
+ | "pop3"
2728
+ | "email_roundtrip";
2709
2729
  label?: string;
2710
2730
  description?: string;
2711
2731
  target_format?: string;
@@ -3220,6 +3240,11 @@ export interface components {
3220
3240
  /** @default true */
3221
3241
  checkPtr: boolean;
3222
3242
  };
3243
+ /** @description Options for the `mail-server-check` diagnostic. How secure are this domain's mail servers — an A+…F grade per service (inbound MX, SMTP submission, IMAP, POP3) for TLS, certificates, STARTTLS, plain-text login, open relay, MTA-STS, TLS-RPT and DANE, checked from three regions? */
3244
+ DiagnosticOptionsMailServerCheck: {
3245
+ /** @description Services to check: smtp (inbound MX on 25 + submission on 587/465), imap, pop3. Omit for Auto: every service, and for a single host only the ones that answer are graded. */
3246
+ services?: ("smtp" | "imap" | "pop3")[];
3247
+ };
3223
3248
  /** @description Options for the `ntp-test` diagnostic. Does this NTP server answer, and what stratum, clock offset, round-trip delay and leap indicator does it report per sample? */
3224
3249
  DiagnosticOptionsNtpTest: {
3225
3250
  /** @default 123 */
@@ -3610,6 +3635,7 @@ export interface operations {
3610
3635
  | "redirect-chain"
3611
3636
  | "websocket-test"
3612
3637
  | "smtp-test"
3638
+ | "mail-server-check"
3613
3639
  | "ntp-test"
3614
3640
  | "email-health";
3615
3641
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watchfor",
3
- "version": "0.12.0",
3
+ "version": "0.13.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",