watchfor 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 980b1fdcb72ae50da30b5abf19101018add41e1d1b840ef9c6378211abb07f58
-  data.tar.gz: '099d81bbfe131ceac6031c37078304a11673cd6c40219ac3b101bdf88a71ecf5'
+  metadata.gz: f5ad40afc1187be8bcdf41c4c418b3c18b304b097a901219edfe777ae41087d1
+  data.tar.gz: b4da046bc763240825953b51a69e13e50838272d7e642bf78f450b4f7914810d
 SHA512:
-  metadata.gz: 040a75ce5d87d1d7ef6855edae019724e4247a3b823fdad13873611888ce98e464c2e494d4bc83682a148390c429fa01350d910cc04182ca590d2dff8da51653
-  data.tar.gz: 6b5b2506e0da8ebec2aedcf1340520287ac7456ed7ff67b800154a2591872b70c683ee2e833e49a7b48753a0c1953d593edef8803d0b46399acfe77f5a32add2
+  metadata.gz: 73e41e8dc6673385ab4bfca74bb41a6e2d83d08429b88ff1bf826c835201295eda5c5b1edd76cf32518cb86ba9829b4b8d9b4641e9f1ee0f5a50743e2fe848e6
+  data.tar.gz: 1a4951d407a131eec5206d4b909de80a26f4833aaa916a08aa914846c6f71b8b6161cb5ceb90b982c3a0a2ce91fb465d5f7c297ce7bac2db92215e3b3481160d

data/README.md

@@ -40,8 +40,8 @@ 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"])
 
-# Page integrity: after a deploy, accept what the newest check saw as the new baseline
-wf.monitors.accept_baseline(integrity_monitor_id)
+# Page integrity: after a deploy, check the pages and accept what that check saw
+wf.monitors.accept_baseline(integrity_monitor_id, fresh: true)
 
 # Browser checks: try a Playwright script once (nothing saved), then read the result
 run = wf.playwright.test_run(script: script, target: "https://shop.example.com")
@@ -59,11 +59,24 @@ wf.monitors.checks(mon["id"], hours: 24, limit: 100, cursor: page["next_cursor"]
 
 # Delete a contact group that alert rules still use (409 without force)
 wf.contact_groups.delete("<group-id>", force: true)
+
+# What the alerting engine sees right now: alerted, recovering 1/3, confirming 2 of 3…
+state = wf.monitors.get(mon["id"])["alerting_state"]
+
+# Response times on a real time axis (5-min buckets for 24h, 15 min for 7d)
+up = wf.monitors.uptime(mon["id"], "24h", series: true)
+(up["response_time_series"] || []).each { |b| puts "#{b['at']} #{b['avg_ms']}" }
+
+# Pause up to 100 monitors at once; post a status-page announcement
+wf.monitors.bulk("pause", ["<id-1>", "<id-2>"])
+notice = wf.status_pages.create_announcement("<page-id>",
+                                             { title: "Checkout errors", body: "We are looking into it." })
+wf.status_pages.update_announcement("<page-id>", notice["id"], { body: "Fixed.", status: "resolved" })
 ```
 
 ### Live diagnostics
 
-Run any of 22 checks from WatchFor's probe fleet against **any public
+Run any of 24 checks from WatchFor's probe fleet against **any public
 target**, monitored or not — this measures right now, rather than reading
 what WatchFor recorded:
 
@@ -78,6 +91,18 @@ dns = wf.diagnostics.run("dns-lookup", "example.com",
 puts "finding: #{dns['error']}" unless dns["success"]
 puts "runs left this hour: #{dns['remaining']}"
 
+# Graded checks (tls-grade, http-headers, cwv-check, mcp-check, email-health,
+# mail-server-check, cdn-check, smart-audit, dns-health) also return the
+# dashboard's WatchFor Grade: letter, rubric id and what holds it down
+headers = wf.diagnostics.run("http-headers", "https://example.com")
+grade = headers["grade"] || {}
+if grade["letter"]
+  puts "grade #{grade['letter']} (#{grade['rubric']})"
+  grade["capped_by"].each { |c| puts "  max #{c['cap']}: #{c['title']} — fix: #{c['fix']}" }
+else
+  puts "not graded: #{grade['not_graded_reason']}"
+end
+
 # 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")
@@ -90,11 +115,38 @@ Details: <https://watchfor.io/docs/api/diagnostics>
 
 Namespaces: `wf.monitors`, `wf.alert_rules`, `wf.incidents`,
 `wf.hosts`, `wf.status_pages`, `wf.on_call`, `wf.notification_channels`, `wf.maintenance_windows`, `wf.contacts`, `wf.contact_groups`,
-`wf.diagnostics`. Top-level:
+`wf.diagnostics`, `wf.playwright`, `wf.variables`. Top-level:
 `wf.summary`, `wf.plan`, `wf.me`, `wf.locations`, `wf.monitor_types`,
-`wf.incident_stats(period)`, `wf.notifications`, `wf.activity`. Errors raise
+`wf.incident_stats(period)`, `wf.report`, `wf.notifications`, `wf.activity`,
+`wf.batch([...])`, `wf.metrics`. Errors raise
 `Watchfor::Error` with `#status`, `#code`, `#message`.
 
+## Organizations
+
+An API key belongs to one organization. An **OAuth access token** acts as
+the user who approved it, so it reaches every organization that user
+belongs to; choose one with `organization:` — the SDK sends it as the
+`X-WatchFor-Organization` header on every request:
+
+```ruby
+acme = Watchfor::Client.new(api_key: oauth_access_token, organization: "<organization-id>")
+acme.me # {"organization" => {"id", "name", "slug"}, "scope" => ...}
+other = acme.with_organization("<another-organization-id>") # new client, same token
+other.monitors.list
+```
+
+- Without `organization:`, an OAuth token acts on the user's oldest owned
+  organization (else their oldest membership).
+- The user must be a member of that organization (otherwise `403
+  forbidden`), and their role there applies: members read, acknowledge
+  incidents and run diagnostics; changes need owner or admin.
+- With an API key leave it unset; it may only repeat the key's own
+  organization id, and any other id is `403 forbidden` (a key never
+  switches organization).
+- `with_organization(nil)` drops the header again.
+
+Details: <https://watchfor.io/docs/api/authentication#how-oauth-maps-to-your-data>
+
 ## Prometheus metrics (Pro plan and above)
 
 ```ruby
@@ -112,6 +164,12 @@ watchfor monitors
 watchfor incidents
 watchfor checks <monitor_id> [--cursor <next_cursor>]
 watchfor report --period 30d
+watchfor me                       # which organization + scope
+
+# OAuth token: pick the organization per call or via the environment
+export WATCHFOR_API_KEY=<oauth-access-token>
+watchfor --organization <organization-id> monitors
+WATCHFOR_ORGANIZATION=<organization-id> watchfor summary
 ```
 
 Reference: <https://watchfor.io/openapi.json> · <https://watchfor.io/docs/api>

data/exe/watchfor

@@ -8,6 +8,22 @@ api_key = ENV["WATCHFOR_API_KEY"]
 base_url = ENV.fetch("WATCHFOR_BASE_URL", Watchfor::DEFAULT_BASE_URL)
 
 args = ARGV.dup
+
+# Global --organization <id> / --organization=<id>, anywhere on the line;
+# WATCHFOR_ORGANIZATION is the default. OAuth tokens reach every
+# organization their user belongs to; an API key only accepts its own id.
+organization = ENV.fetch("WATCHFOR_ORGANIZATION", nil)
+if (i = args.index("--organization"))
+  organization = args[i + 1].to_s
+  args.slice!(i, 2)
+  if organization.strip.empty?
+    warn "--organization needs an organization id"
+    exit 2
+  end
+elsif (i = args.index { |a| a.start_with?("--organization=") })
+  organization = args.delete_at(i).split("=", 2)[1].to_s
+end
+
 command = args.shift
 
 if command == "--version"
@@ -16,15 +32,16 @@ if command == "--version"
 end
 
 if api_key.nil? || api_key.empty?
-  warn "No API key. Set WATCHFOR_API_KEY."
+  warn "No API key. Set WATCHFOR_API_KEY (an API key or an OAuth access token)."
   exit 2
 end
 
-wf = Watchfor::Client.new(api_key: api_key, base_url: base_url)
+wf = Watchfor::Client.new(api_key: api_key, base_url: base_url, organization: organization)
 
 begin
   result =
     case command
+    when "me" then wf.me
     when "summary" then wf.summary
     when "plan" then wf.plan
     when "monitors" then wf.monitors.list
@@ -42,7 +59,10 @@ begin
       print wf.metrics(tag: tag, type: type)
       exit 0
     else
-      warn "Usage: watchfor [summary|plan|monitors|locations|monitor-types|incidents|checks <monitor_id> [--cursor c]|report [--period 7d|30d]|metrics [--tag t] [--type t]]"
+      warn "Usage: watchfor [--organization <id>] " \
+           "[me|summary|plan|monitors|locations|monitor-types|incidents|checks <monitor_id> [--cursor c]|" \
+           "report [--period 7d|30d]|metrics [--tag t] [--type t]]\n" \
+           "Env: WATCHFOR_API_KEY (API key or OAuth access token), WATCHFOR_ORGANIZATION, WATCHFOR_BASE_URL"
       exit 2
     end
   puts JSON.pretty_generate(result)

data/lib/watchfor/client.rb

@@ -6,6 +6,8 @@ require "uri"
 
 module Watchfor
   DEFAULT_BASE_URL = "https://watchfor.io/api/v1"
+  # The request header that selects the organization an OAuth token acts on.
+  ORGANIZATION_HEADER = "X-WatchFor-Organization"
 
   # Raised when the API returns a non-2xx response. Carries the HTTP
   # +status+ and the API's structured +code+ and +message+.
@@ -24,17 +26,28 @@ module Watchfor
   #   wf = Watchfor::Client.new(api_key: "wf_live_...")
   #   wf.summary
   #   wf.monitors.list["data"].each { |m| puts "#{m['name']} #{m['status']}" }
+  #
+  # An OAuth access token reaches every organization its user belongs to;
+  # pick one with +organization:+ (sent as X-WatchFor-Organization):
+  #
+  #   acme = Watchfor::Client.new(api_key: oauth_token, organization: "<org id>")
+  #   other = acme.with_organization("<another org id>")
+  #
+  # An API key belongs to one organization: leave +organization:+ unset, or
+  # pass that same id (any other id is 403 forbidden).
   class Client
     attr_reader :monitors, :alert_rules, :incidents, :hosts, :status_pages, :on_call, :notification_channels,
                 :maintenance_windows, :contacts, :contact_groups,
-                :diagnostics, :playwright, :variables
+                :diagnostics, :playwright, :variables, :organization
 
-    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30, organization: nil)
       raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
 
       @api_key = api_key
       @base_url = base_url.chomp("/")
       @timeout = timeout
+      org = organization.to_s.strip
+      @organization = org.empty? ? nil : org
       @monitors = Monitors.new(self)
       @alert_rules = AlertRules.new(self)
       @incidents = Incidents.new(self)
@@ -50,6 +63,14 @@ module Watchfor
       @variables = Variables.new(self)
     end
 
+    # A new client acting on another organization (same credential and
+    # settings); nil drops the header so the credential's default
+    # organization applies. This client is left unchanged.
+    def with_organization(organization)
+      self.class.new(api_key: @api_key, base_url: @base_url, timeout: @timeout,
+                     organization: organization)
+    end
+
     # Core request. +query+ and +body+ are optional hashes.
     def request(method, path, query: nil, body: nil, idempotency_key: nil, text: false)
       uri = URI("#{@base_url}#{path}")
@@ -68,6 +89,7 @@ module Watchfor
       req["Accept"] = text ? "text/plain, application/json" : "application/json"
       req["User-Agent"] = "watchfor-ruby/#{Watchfor::VERSION}"
       req["Idempotency-Key"] = idempotency_key if idempotency_key
+      req[ORGANIZATION_HEADER] = @organization if @organization
       unless body.nil?
         req["Content-Type"] = "application/json"
         req.body = JSON.generate(body)
@@ -92,7 +114,17 @@ module Watchfor
     end
 
     # Top-level reads
+    # The credential's scope and the organization it acts on (with an OAuth
+    # token, the one +organization:+ selected).
     def me = request("GET", "/me")
+
+    # Run up to 20 operations ({ method:, path:, body: } with a relative
+    # /api/v1 path) in one request, with the same credential and
+    # organization; "results" come back in request order as {status, body}.
+    def batch(operations) = request("POST", "/batch", body: { operations: operations })
+
+    # The OpenAPI 3.1 document this client wraps (no key needed).
+    def openapi_spec = request("GET", "/openapi.json")
     def summary = request("GET", "/summary")
 
     # The organization in Prometheus text format (Pro plan and above):
@@ -108,11 +140,24 @@ module Watchfor
     # Org report vs the previous period (period: "7d"/"30d", or from/to ISO 8601
     # on advanced-reports plans): uptime, incidents, MTTR/MTBF, response-time
     # trend, per-monitor rows, type-aware sections and plain-language insights.
-    def report(period: nil, from: nil, to: nil)
+    #
+    # Scoping (advanced-reports plans): monitor_ids:/tags: (union), sections:
+    # (locations, ssl, domains, cwv, heartbeat, blacklist, mcp, hosts),
+    # incident_status: (acknowledged, resolved, open) — arrays or
+    # comma-separated strings. false for response_time:/monitors_table:/
+    # insights: drops that block.
+    def report(period: nil, from: nil, to: nil, monitor_ids: nil, tags: nil, sections: nil,
+               response_time: nil, monitors_table: nil, insights: nil, incident_status: nil)
+      csv = ->(v) { v.is_a?(Array) ? v.join(",") : v }
+      query = { monitor_ids: csv.call(monitor_ids), tags: csv.call(tags), sections: csv.call(sections),
+                incident_status: csv.call(incident_status),
+                response_time: response_time.nil? ? nil : response_time.to_s,
+                monitors_table: monitors_table.nil? ? nil : monitors_table.to_s,
+                insights: insights.nil? ? nil : insights.to_s }
       if from || to
-        request("GET", "/reports", query: { from: from, to: to })
+        request("GET", "/reports", query: query.merge(from: from, to: to))
       else
-        request("GET", "/reports", query: { period: period })
+        request("GET", "/reports", query: query.merge(period: period))
       end
     end
     # The org's two report-email cadences (weekly + monthly); set toggles
@@ -131,8 +176,17 @@ 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).
+      # The monitor plus available_metrics (alert metrics valid for its type)
+      # and alerting_state — what the alerting engine sees right now (alerted,
+      # recovering n of m, failing/confirming n of m; nil when every rule is
+      # healthy).
       def get(id) = @c.request("GET", "/monitors/#{id}")
+      # Pause, resume or delete (+action+) up to 100 monitors in one call; ids
+      # that are not yours or need no change come back in "skipped".
+      def bulk(action, ids, idempotency_key: nil)
+        @c.request("POST", "/monitors/bulk", body: { action: action, ids: ids },
+                                             idempotency_key: idempotency_key)
+      end
       # Credentials (catalog fields marked secret: mailbox/SMTP/FTP passwords,
       # SSH keys, HTTP/API/MCP auth passwords, bearer tokens and credential
       # header values) are write-only: stored encrypted, returned as
@@ -142,7 +196,9 @@ module Watchfor
       # config is merged (omitted keys kept, nil removes). A "[redacted]"
       # credential is kept when omitted or sent back; changing the server,
       # port, TLS mode or login it is used with (HTTP: the URL's host, port
-      # or scheme) needs it again (else 400).
+      # or scheme) needs it again (else 400). "check_queued" => true in the
+      # result means the change dispatched one immediate check, outside the
+      # Run-now budget.
       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")
@@ -153,7 +209,13 @@ module Watchfor
       # 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 })
+      # Uptime (confirmed critical incidents only), check success and
+      # response-time stats. series: true (periods up to 7d) adds
+      # "response_time_series" — buckets of "series_bucket_seconds" (300 for
+      # 24h, 900 for 7d) on a real time axis, oldest first.
+      def uptime(id, period = nil, series: false)
+        @c.request("GET", "/monitors/#{id}/uptime", query: { period: period, series: series ? "true" : nil })
+      end
       # 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)
@@ -173,11 +235,18 @@ module Watchfor
       # Page integrity monitors: the accepted baseline of every watched page.
       def baseline(id) = @c.request("GET", "/monitors/#{id}/baseline")
       # Page integrity monitors: accept what the newest check saw as the new
-      # baseline — all pages, or only `pages:`. Call it from a deploy pipeline
-      # a minute after the release; unfetched pages come back in "skipped".
-      def accept_baseline(id, pages: nil, idempotency_key: nil)
+      # baseline — all pages, or only `pages:`. Open integrity incidents
+      # resolve at once when nothing else differs ("incidents_resolved").
+      # From a deploy pipeline pass `fresh: true`: the pages are checked first
+      # and that check is accepted ("status" "pending" = still running, it
+      # finishes on its own — see baseline(id)["fresh_accept"]); unfetched
+      # pages come back in "skipped".
+      def accept_baseline(id, pages: nil, idempotency_key: nil, fresh: false)
+        body = {}
+        body[:pages] = pages if pages
+        body[:fresh] = true if fresh
         @c.request("POST", "/monitors/#{id}/baseline",
-                   body: pages ? { pages: pages } : {}, idempotency_key: idempotency_key)
+                   body: body, idempotency_key: idempotency_key)
       end
     end
 
@@ -202,7 +271,9 @@ module Watchfor
     class AlertRules < Namespace
       def list(monitor_id) = @c.request("GET", "/monitors/#{monitor_id}/alert-rules")
       def get(monitor_id, rule_id) = @c.request("GET", "/monitors/#{monitor_id}/alert-rules/#{rule_id}")
-      def create(monitor_id, body) = @c.request("POST", "/monitors/#{monitor_id}/alert-rules", body: body)
+      def create(monitor_id, body, idempotency_key: nil)
+        @c.request("POST", "/monitors/#{monitor_id}/alert-rules", body: body, idempotency_key: idempotency_key)
+      end
       def update(monitor_id, rule_id, body) = @c.request("PATCH", "/monitors/#{monitor_id}/alert-rules/#{rule_id}", body: body)
       def delete(monitor_id, rule_id) = @c.request("DELETE", "/monitors/#{monitor_id}/alert-rules/#{rule_id}")
     end
@@ -218,12 +289,40 @@ module Watchfor
       def exclude(id, reason: nil) = @c.request("POST", "/incidents/#{id}/exclude", body: reason.nil? ? {} : { reason: reason })
       # Undo #exclude - the incident counts as downtime again.
       def include(id) = @c.request("POST", "/incidents/#{id}/include")
+      # Retroactively count a RESOLVED incident as planned maintenance: it
+      # leaves uptime and SLA. Returns the "maintenance_window" recorded for it
+      # (marking again returns the same one); delete that window to undo.
+      def mark_maintenance(id, idempotency_key: nil)
+        @c.request("POST", "/incidents/#{id}/mark-maintenance", idempotency_key: idempotency_key)
+      end
     end
 
     class StatusPages < Namespace
       def list(**query) = @c.request("GET", "/status-pages", query: query)
       def get(id) = @c.request("GET", "/status-pages/#{id}")
+      # Create a page (slug, name, optional components...). Password protection,
+      # logo upload and custom subdomains are dashboard-only.
+      def create(body, idempotency_key: nil) = @c.request("POST", "/status-pages", body: body, idempotency_key: idempotency_key)
+      # Partial update; a slug change frees the old URL at once.
+      def update(id, body) = @c.request("PATCH", "/status-pages/#{id}", body: body)
+      def delete(id) = @c.request("DELETE", "/status-pages/#{id}")
+      # Announcements, newest first.
       def announcements(id, **query) = @c.request("GET", "/status-pages/#{id}/announcements", query: query)
+      def get_announcement(id, announcement_id) = @c.request("GET", "/status-pages/#{id}/announcements/#{announcement_id}")
+      # Publish an incident notice (title, body, optional status, severity,
+      # affectedComponentIds); body becomes the first timeline entry.
+      def create_announcement(id, body, idempotency_key: nil)
+        @c.request("POST", "/status-pages/#{id}/announcements", body: body, idempotency_key: idempotency_key)
+      end
+      # Post an update (body + status): appends to the public timeline;
+      # "resolved" closes it.
+      def update_announcement(id, announcement_id, body)
+        @c.request("PATCH", "/status-pages/#{id}/announcements/#{announcement_id}", body: body)
+      end
+      # Remove from the public page (soft delete).
+      def delete_announcement(id, announcement_id)
+        @c.request("DELETE", "/status-pages/#{id}/announcements/#{announcement_id}")
+      end
     end
 
     class OnCall < Namespace
@@ -242,6 +341,7 @@ module Watchfor
     end
 
     class MaintenanceWindows < Namespace
+      # state: "active" / "upcoming" keeps only live windows.
       def list(**query) = @c.request("GET", "/maintenance-windows", query: query)
       def get(id) = @c.request("GET", "/maintenance-windows/#{id}")
       def create(body, idempotency_key: nil) = @c.request("POST", "/maintenance-windows", body: body, idempotency_key: idempotency_key)

data/lib/watchfor/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: watchfor
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - WatchFor
@@ -24,11 +24,11 @@ files:
 - lib/watchfor.rb
 - lib/watchfor/client.rb
 - lib/watchfor/version.rb
-homepage: https://watchfor.io/docs/api
+homepage: https://watchfor.io
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://watchfor.io/docs/api
+  homepage_uri: https://watchfor.io
   documentation_uri: https://watchfor.io/docs/api
   changelog_uri: https://watchfor.io/changelog
   rubygems_mfa_required: 'true'