watchfor 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9af0dcb3158ef210d30f76f4535fa1af2febdd195c1e89c3356492839326d008
-  data.tar.gz: fc12ab07a54877f0d098ac7ac76612c31d37188ed3b9f9283819b078e6f2caed
+  metadata.gz: 0fa3724c68935a0f14be699f9b232640b29b75811132dcf9e96cdec986d17132
+  data.tar.gz: 27b90a62ac79058fb401d4c0f75e7fbb59bc0c5622cb33b41fed8bb71ea49d2d
 SHA512:
-  metadata.gz: de5374a23086013159a4526dc02f0c262525902a2a00ebdcf515797459c8ef26b52d351ff603705187674e5710c3b3097f3fffa98390dfdb745aa794475c20b3
-  data.tar.gz: 0ccb9565903bca08b71d857ab9604357e6f337655bddb2d200d7f7015d501403ebf867eb9aee7074b95f496f46ce35198f145de9d41afd2ea95ac951433638f7
+  metadata.gz: 8fdfa7930ac0000827e8f5325e08bd5e99a10ec8ef0409b04144273e284cd16cbb6f1c9f37aaa2fda22df74998711c860bf1b93ac4e53136ca5acd5cd4daf114
+  data.tar.gz: 0a326ed15feab7394d1ab2f159cdab8a3bc2f402f3b47c0302dc8b1b5868ccfbe749860ca5ac70f83f5130d8f21a6248f4370df738f33a8cd220a73f05c016f4

data/README.md

@@ -39,10 +39,45 @@ wf.incidents.exclude(19351, reason: "Probe-side DNS hiccup")
 
 # Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset"
 wf.monitors.reset(mon["id"])
+
+# Older checks: pass next_cursor back as cursor (keep the same hours/success)
+page = wf.monitors.checks(mon["id"], hours: 24, limit: 100)
+wf.monitors.checks(mon["id"], hours: 24, limit: 100, cursor: page["next_cursor"]) if page["next_cursor"]
+
+# Delete a contact group that alert rules still use (409 without force)
+wf.contact_groups.delete("<group-id>", force: true)
+```
+
+### Live diagnostics
+
+Run any of 18 checks from WatchFor's probe fleet against **any public
+target**, monitored or not — this measures right now, rather than reading
+what WatchFor recorded:
+
+```ruby
+# What can I run, and how much budget is left?
+catalog = wf.diagnostics.list
+
+# One check, optionally from a location you choose (plan-gated)
+dns = wf.diagnostics.run("dns-lookup", "example.com",
+                         options: { recordType: "A", resolver: "8.8.8.8" })
+# A closed port / NXDOMAIN / failed handshake does NOT raise:
+puts "finding: #{dns['error']}" unless dns["success"]
+puts "runs left this hour: #{dns['remaining']}"
+
+# The whole picture in one call: DNS + propagation + TLS + HTTP + ping
+# from up to 3 regions, aggregated into one verdict
+report = wf.diagnostics.diagnose_target("example.com")
+puts "#{report['verdict']['status']}: #{report['verdict']['summary']}"
 ```
 
+Runs need a `write` key (a probe sends real traffic from WatchFor's IPs)
+and spend the same per-plan hourly allowance as the dashboard Toolbox.
+Details: <https://watchfor.io/docs/api/diagnostics>
+
 Namespaces: `wf.monitors`, `wf.alert_rules`, `wf.incidents`,
-`wf.maintenance_windows`, `wf.contacts`, `wf.contact_groups`. Top-level:
+`wf.maintenance_windows`, `wf.contacts`, `wf.contact_groups`,
+`wf.diagnostics`. Top-level:
 `wf.summary`, `wf.plan`, `wf.me`, `wf.locations`, `wf.monitor_types`,
 `wf.incident_stats(period)`, `wf.notifications`, `wf.activity`. Errors raise
 `Watchfor::Error` with `#status`, `#code`, `#message`.
@@ -54,7 +89,7 @@ export WATCHFOR_API_KEY=wf_live_...
 watchfor summary
 watchfor monitors
 watchfor incidents
-watchfor checks <monitor_id>
+watchfor checks <monitor_id> [--cursor <next_cursor>]
 watchfor report --period 30d
 ```
 

data/exe/watchfor

@@ -31,10 +31,13 @@ begin
     when "locations" then wf.locations
     when "monitor-types" then wf.monitor_types
     when "incidents" then wf.incidents.list
-    when "checks" then wf.monitors.checks(args.shift)
+    when "checks"
+      monitor_id = args.shift
+      cursor = args.include?("--cursor") ? args[args.index("--cursor") + 1] : nil
+      wf.monitors.checks(monitor_id, cursor: cursor)
     when "report" then wf.report(period: args.include?("--period") ? args[args.index("--period") + 1] : nil)
     else
-      warn "Usage: watchfor [summary|plan|monitors|locations|monitor-types|incidents|checks <monitor_id>|report [--period 7d|30d]]"
+      warn "Usage: watchfor [summary|plan|monitors|locations|monitor-types|incidents|checks <monitor_id> [--cursor c]|report [--period 7d|30d]]"
       exit 2
     end
   puts JSON.pretty_generate(result)

data/lib/watchfor/client.rb

@@ -26,7 +26,8 @@ module Watchfor
   #   wf.monitors.list["data"].each { |m| puts "#{m['name']} #{m['status']}" }
   class Client
     attr_reader :monitors, :alert_rules, :incidents,
-                :maintenance_windows, :contacts, :contact_groups
+                :maintenance_windows, :contacts, :contact_groups,
+                :diagnostics
 
     def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30)
       raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
@@ -40,6 +41,7 @@ module Watchfor
       @maintenance_windows = MaintenanceWindows.new(self)
       @contacts = Contacts.new(self)
       @contact_groups = ContactGroups.new(self)
+      @diagnostics = Diagnostics.new(self)
     end
 
     # Core request. +query+ and +body+ are optional hashes.
@@ -113,19 +115,26 @@ module Watchfor
 
     class Monitors < Namespace
       def list(**query) = @c.request("GET", "/monitors", query: query)
+      # The monitor plus available_metrics (alert metrics valid for its type).
       def get(id) = @c.request("GET", "/monitors/#{id}")
       def create(body, idempotency_key: nil) = @c.request("POST", "/monitors", body: body, idempotency_key: idempotency_key)
       def update(id, body) = @c.request("PATCH", "/monitors/#{id}", body: body)
       def delete(id) = @c.request("DELETE", "/monitors/#{id}")
       def pause(id) = @c.request("POST", "/monitors/#{id}/pause")
       def resume(id) = @c.request("POST", "/monitors/#{id}/resume")
+      # Dispatch one out-of-schedule check now (202); the result lands in #checks moments later.
       def check_now(id) = @c.request("POST", "/monitors/#{id}/check-now")
       # IRREVERSIBLE: deletes every check, incident, note and post-mortem of the
       # monitor and starts uptime over ("since reset"); the monitor and its
       # configuration, alert rules, tags and locations stay.
       def reset(id) = @c.request("POST", "/monitors/#{id}/reset")
       def uptime(id, period = nil) = @c.request("GET", "/monitors/#{id}/uptime", query: { period: period })
-      def checks(id, **query) = @c.request("GET", "/monitors/#{id}/checks", query: query)
+      # Recent probe results, newest first. Page with the response's next_cursor -> cursor:
+      # (keep the same hours/success); "locations" is the per-location breakdown for the whole window.
+      def checks(id, hours: nil, limit: nil, success: nil, cursor: nil, **query)
+        @c.request("GET", "/monitors/#{id}/checks",
+                   query: { hours: hours, limit: limit, success: success, cursor: cursor, **query })
+      end
     end
 
     class AlertRules < Namespace
@@ -139,6 +148,7 @@ module Watchfor
     class Incidents < Namespace
       def list(**query) = @c.request("GET", "/incidents", query: query)
       def get(id) = @c.request("GET", "/incidents/#{id}")
+      # Every action returns the full, updated incident.
       def acknowledge(id) = @c.request("POST", "/incidents/#{id}/acknowledge")
       def resolve(id) = @c.request("POST", "/incidents/#{id}/resolve")
       # Mark a RESOLVED incident as a false positive: kept on record, left out of
@@ -169,7 +179,48 @@ module Watchfor
       def get(id) = @c.request("GET", "/contact-groups/#{id}")
       def create(body, idempotency_key: nil) = @c.request("POST", "/contact-groups", body: body, idempotency_key: idempotency_key)
       def update(id, body) = @c.request("PATCH", "/contact-groups/#{id}", body: body)
-      def delete(id) = @c.request("DELETE", "/contact-groups/#{id}")
+      # 409 for the default group, and 409 while alert rules, monitors or notification channels
+      # still route through it; force: true deletes anyway (references are removed; affected
+      # alert rules fall back to their monitor's notification groups).
+      def delete(id, force: false) = @c.request("DELETE", "/contact-groups/#{id}", query: force ? { force: true } : nil)
+    end
+
+    # Live checks run from WatchFor's probe fleet against any public target,
+    # monitored or not — these MEASURE right now, unlike the rest of the
+    # client, which reads what WatchFor already recorded.
+    #
+    # +run+ and +diagnose_target+ need a write-scope key: a probe sends real
+    # traffic from WatchFor's IPs and spends a metered, per-plan allowance
+    # (the same hourly budget the dashboard Toolbox spends). Every response
+    # carries "remaining" and "distinct_targets" so a long investigation can
+    # pace itself. A check that ran and found a problem (closed port,
+    # NXDOMAIN, failed handshake) returns normally with "success" => false;
+    # only calls that could not run raise.
+    class Diagnostics < Namespace
+      # Every check, the question it answers, its options and this
+      # organization's remaining allowance. Read scope.
+      def list = @c.request("GET", "/diagnostics")
+
+      # Run one check (dns-lookup, ping, tls-grade, ...). +location_id+ is
+      # honoured on plans whose location_select is true; otherwise the
+      # nearest probe answers and the response says which. Write scope.
+      def run(slug, target, options: nil, location_id: nil, idempotency_key: nil)
+        body = { target: target }
+        body[:options] = options unless options.nil?
+        body[:location_id] = location_id unless location_id.nil?
+        @c.request("POST", "/diagnostics/#{slug}", body: body, idempotency_key: idempotency_key)
+      end
+
+      # DNS, propagation, TLS grade, HTTP headers and ping from up to 3
+      # regions in one call, aggregated into a single verdict. Each
+      # underlying check spends its own allowance; needs a plan with
+      # location selection. Write scope.
+      def diagnose_target(target, max_locations: nil, location_ids: nil, idempotency_key: nil)
+        body = { target: target }
+        body[:max_locations] = max_locations unless max_locations.nil?
+        body[:location_ids] = location_ids unless location_ids.nil?
+        @c.request("POST", "/diagnostics/diagnose-target", body: body, idempotency_key: idempotency_key)
+      end
     end
   end
 end

data/lib/watchfor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Watchfor
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: watchfor
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - WatchFor
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies: []
 description: Zero-dependency Ruby client for the WatchFor REST API (monitors, alert
   rules, incidents, maintenance windows) plus a `watchfor` CLI.