watchfor 0.17.1 → 0.18.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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: adca636a4ce8ebb4b6aaee45ab0a42e0262c4b9c847f911a808c49d1f68281e1
4
- data.tar.gz: f8ad4ed618230b90ae7d1e23f7cd180a00654cd00d9fe2a06caed6df25be3de1
3
+ metadata.gz: c835dd76f2c36039e87bea1a5e1ab4ab75ed149e44bb3c9116b5935510e8057e
4
+ data.tar.gz: 30ee44bba34bc554e84164d37eed0c8d3c7acaf0534f15f1de3aedaf3ddb7f23
5
5
  SHA512:
6
- metadata.gz: 6ee33ffa4289dc52d756623fe13d333936cfc2e5644b7355f3db7f2c985d9ab72dd8636e11b845010c9e9586356113a96d108af6e1cad903dfa4e5e0670cd56e
7
- data.tar.gz: 33091b5356c72d746ee02852df174b843820f481040ec0e216c97613bf13e61f0db4545fc66f2bcbd368dfb95ac70de0383ccfb8dbb8752bbcff5a435e30505d
6
+ metadata.gz: b659336b1c55d9094fbbfc900a9f353904fd4b906c42e7a2a1da5e361118eaf914a0b61dc6ee4be8f2b7e452b5bb8fa84e5478c01a02239201284866e743c4d0
7
+ data.tar.gz: dcade75ce639ac261f5bfe5a65d97405b1f183d35aa8a4b23f8dcf2d9ffe35e399316d1216cfd370784b23380106078e040f6ba700cec3f37da33fd2c6b45384
data/README.md CHANGED
@@ -49,6 +49,11 @@ wf.monitors.reset(mon["id"])
49
49
  # Page integrity: after a deploy, check the pages and accept what that check saw
50
50
  wf.monitors.accept_baseline(integrity_monitor_id, fresh: true)
51
51
 
52
+ # MCP servers: before a release, keep tool drift quiet for 30 minutes (downtime still pages);
53
+ # a drift incident the user confirms was theirs is accepted as an expected change
54
+ wf.monitors.set_expected_change_window(mcp_monitor_id, window: 30, note: "v2.4 release")
55
+ wf.incidents.accept_expected_change(19352, note: "New search tool shipped in v2.4")
56
+
52
57
  # Browser checks: try a Playwright script once (nothing saved), then read the result
53
58
  run = wf.playwright.test_run(script: script, target: "https://shop.example.com")
54
59
  wf.playwright.get_test_run(run["id"]) # status: queued | running | done | error
@@ -93,7 +98,8 @@ catalog = wf.diagnostics.list
93
98
  # One check, optionally from a location you choose (plan-gated)
94
99
  dns = wf.diagnostics.run("dns-lookup", "example.com",
95
100
  options: { recordType: "A", resolver: "8.8.8.8" })
96
- # A closed port / NXDOMAIN / failed handshake does NOT raise:
101
+ # A closed port, NXDOMAIN, expired certificate or unresolvable host does NOT
102
+ # raise — "success" is false and "error" says why ("result" keeps the raw answer):
97
103
  puts "finding: #{dns['error']}" unless dns["success"]
98
104
  puts "runs left this hour: #{dns['remaining']}"
99
105
 
@@ -125,7 +131,12 @@ Namespaces: `wf.organizations`, `wf.monitors`, `wf.alert_rules`, `wf.incidents`,
125
131
  `wf.summary`, `wf.plan`, `wf.me`, `wf.locations`, `wf.monitor_types`,
126
132
  `wf.incident_stats(period)`, `wf.report`, `wf.notifications`, `wf.activity`,
127
133
  `wf.batch([...])`, `wf.metrics`. Errors raise
128
- `Watchfor::Error` with `#status`, `#code`, `#message`.
134
+ `Watchfor::Error` with `#status`, `#code`, `#message` and `#retry_after`
135
+ (seconds, on a 429). A non-JSON answer (an HTML page from a wrong base URL
136
+ or a proxy) is a short `http_error` / `invalid_response` pointing at the
137
+ base URL. `base_url:` (and the CLI's `WATCHFOR_BASE_URL`) takes the origin
138
+ (`https://watchfor.io`) or the full base (`https://watchfor.io/api/v1`) —
139
+ the same value works for the npm and Python SDKs.
129
140
 
130
141
  ## Organizations
131
142
 
@@ -12,15 +12,31 @@ module Watchfor
12
12
  # Raised when the API returns a non-2xx response. Carries the HTTP
13
13
  # +status+ and the API's structured +code+ and +message+.
14
14
  class Error < StandardError
15
- attr_reader :status, :code
15
+ attr_reader :status, :code, :retry_after
16
16
 
17
- def initialize(status, code, message)
17
+ def initialize(status, code, message, retry_after = nil)
18
18
  @status = status
19
19
  @code = code
20
+ @retry_after = retry_after
20
21
  super("[#{status}] #{code}: #{message}")
21
22
  end
22
23
  end
23
24
 
25
+ # The API base, whichever form was given: "https://watchfor.io" and
26
+ # "https://watchfor.io/api/v1" (with or without a trailing slash) both
27
+ # become "https://watchfor.io/api/v1" — the npm SDK takes the origin, so
28
+ # one WATCHFOR_BASE_URL works for all three SDKs.
29
+ def self.normalize_base_url(base_url)
30
+ base = base_url.to_s.strip.sub(%r{/+\z}, "")
31
+ base = "https://watchfor.io" if base.empty?
32
+ base.downcase.end_with?("/api/v1") ? base : "#{base}/api/v1"
33
+ end
34
+
35
+ def self.not_api_message(status, url)
36
+ "HTTP #{status} from #{url} — the response is not WatchFor API JSON. " \
37
+ "Is the base URL right? Use the origin, e.g. https://watchfor.io (WATCHFOR_BASE_URL)."
38
+ end
39
+
24
40
  # Client for the WatchFor REST API (/api/v1). Zero dependencies.
25
41
  #
26
42
  # wf = Watchfor::Client.new(api_key: "wf_live_...")
@@ -44,7 +60,7 @@ module Watchfor
44
60
  raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
45
61
 
46
62
  @api_key = api_key
47
- @base_url = base_url.chomp("/")
63
+ @base_url = Watchfor.normalize_base_url(base_url)
48
64
  @timeout = timeout
49
65
  org = organization.to_s.strip
50
66
  @organization = org.empty? ? nil : org
@@ -103,15 +119,22 @@ module Watchfor
103
119
  end
104
120
 
105
121
  raw = res.body.to_s
106
- return raw if text && res.code.to_i.between?(200, 299)
122
+ status = res.code.to_i
123
+ return raw if text && status.between?(200, 299)
107
124
 
108
- parsed = raw.empty? ? nil : (JSON.parse(raw) rescue nil)
109
- unless res.code.to_i.between?(200, 299)
125
+ blank = raw.strip.empty?
126
+ parsed = blank ? nil : (JSON.parse(raw) rescue :not_json)
127
+ unless status.between?(200, 299)
110
128
  err = parsed.is_a?(Hash) ? (parsed["error"] || {}) : {}
111
- raise Error.new(res.code.to_i, err["code"] || "http_error",
112
- err["message"] || "HTTP #{res.code}")
129
+ fallback = parsed == :not_json ? Watchfor.not_api_message(status, uri) : "HTTP #{res.code}"
130
+ retry_after = res["Retry-After"] ? Float(res["Retry-After"], exception: false) : nil
131
+ raise Error.new(status, err["code"] || "http_error", err["message"] || fallback, retry_after)
113
132
  end
114
- parsed.nil? ? { "ok" => true, "status" => res.code.to_i } : parsed
133
+ # An HTML page from a wrong base URL or a proxy: say so instead of
134
+ # returning nil.
135
+ raise Error.new(status, "invalid_response", Watchfor.not_api_message(status, uri)) if parsed == :not_json
136
+
137
+ parsed.nil? ? { "ok" => true, "status" => status } : parsed
115
138
  end
116
139
 
117
140
  # Top-level reads
@@ -249,6 +272,18 @@ module Watchfor
249
272
  @c.request("POST", "/monitors/#{id}/baseline",
250
273
  body: body, idempotency_key: idempotency_key)
251
274
  end
275
+ # MCP monitors: release marker - call it from a deploy pipeline before
276
+ # the rollout. For `window:` minutes (1-60, default 15) the monitor's
277
+ # drift rules (Tool Inventory Changed) are silenced - only those,
278
+ # downtime still pages - and drift incidents opened inside the window
279
+ # resolve within a minute. Markers stack; 12 per hour per monitor (429).
280
+ # Page integrity monitors -> 400 (use accept_baseline(id, fresh: true)
281
+ # after the deploy); no enabled drift rule -> 409.
282
+ def set_expected_change_window(id, window: nil, note: nil, idempotency_key: nil)
283
+ @c.request("POST", "/monitors/#{id}/expected-change",
284
+ query: { window: window }, body: note.nil? ? {} : { note: note },
285
+ idempotency_key: idempotency_key)
286
+ end
252
287
  end
253
288
 
254
289
  # Browser checks: run a Playwright script once without saving it.
@@ -305,6 +340,17 @@ module Watchfor
305
340
  def mark_maintenance(id, idempotency_key: nil)
306
341
  @c.request("POST", "/incidents/#{id}/mark-maintenance", idempotency_key: idempotency_key)
307
342
  end
343
+ # Drift incidents only (an MCP monitor's Tool Inventory Changed; others
344
+ # -> 400): mark the change as intended. An open incident is resolved
345
+ # asynchronously ("resolve_requested"; poll #get) and the accept is
346
+ # recorded on the incident and drift timelines and in the Activity log.
347
+ # Accepting again returns the first accept with "already_accepted".
348
+ # `note:` (up to 500 characters) says why. Only call it when the user
349
+ # confirms the change was theirs.
350
+ def accept_expected_change(id, note: nil, idempotency_key: nil)
351
+ @c.request("POST", "/incidents/#{id}/expected-change",
352
+ body: note.nil? ? {} : { note: note }, idempotency_key: idempotency_key)
353
+ end
308
354
  # The incident's post-mortem (404 when it has none yet - #update_postmortem creates it).
309
355
  def get_postmortem(id) = @c.request("GET", "/incidents/#{id}/postmortem")
310
356
  # Create the post-mortem draft on first use, then apply only what is given:
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Watchfor
4
- VERSION = "0.17.1"
4
+ VERSION = "0.18.0"
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: watchfor
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.17.1
4
+ version: 0.18.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - WatchFor