txt: ## dist_zef-lizmat-Updown.md
  [![Actions Status](https://github.com/lizmat/Updown/actions/workflows/linux.yml/badge.svg)](https://github.com/lizmat/Updown/actions) [![Actions Status](https://github.com/lizmat/Updown/actions/workflows/macos.yml/badge.svg)](https://github.com/lizmat/Updown/actions)
  
  # NAME
  
  Updown - provide basic API to Updown.io
  
  # SYNOPSIS
  
  ```
  use Updown;
  
  my $ud = Updown.new;  # assume API key in UPDOWN_API_KEY
  
  my $ud = Updown.new(api-key => "secret-api-key");
  
  for $ud.checks -> (:key($check-id), :value($check)) {
      say "$check.apdex_t() $check.url()"
  }
  
  my $event = Updown::Event(%hash);  # inside a webhook
  
  ```
  
  # DESCRIPTION
  
  Updown provides a simple object-oriented interface to the API as provided by <Updown.io>, a website monitoring service.
  
  Access to functionality is provided through the `Updown` class, which has methods that perform the various functions and return objects in the `Updown::` hierarchy of classes.
  
  The [Updown API](https://updown.io/api) is basically followed to the letter, with a little caching and some minor functional sugar added.
  
  To be consistent with the names used in the API, all identifiers use underscores (snake\_case) in their names, rather then hyphens (kebab-case).
  
  # CLI
  
  This distribution also installs an `updown` command line interface. It (implicitely) takes an `--api-key` parameter (or if none specified, the one in the `UPDOWN_API_KEY` environment). It shows the status of all of the checks associated with that API key, and some more information about a check if a website is down.
  
  # COMPARING
  
  In order to allow you to compare the performance of "your" sites with other, more general sites, the methods accepting a `check_id` can also with one of these named arguments **instead** of a `check_id`:
  
  ```
  :booking     booking.com
  :duckduckgo  duckduckgo.com
  :facebook    facebook.com
  :github      github.com
  :google      google.com
  :raku        raku.org
  
  ```
  
  # MAIN CLASSES
  
  ## Updown
  
  The `Updown` object connects the code with all of the monitoring that has been configured for a user of the [Updown.io](https://updown.io) service.
  
  ### Parameters
  
  The following parameters can be specified when creating the `Updown` object:
  
  #### client
  
  A `Cro::HTTP::Client` object that will be used to access the API of `Updown`. Defaults to a default `Cro::HTTP::Client` object.
  
  #### api-key
  
  The API key that should be used to authenticate requests with the `Updown` API. Defaults to the `UPDOWN_API_KEY` environment variable.
  
  Any API key (implicitely) specified will be added to the headers of the `client` object used to facilitate authentication.
  
  ### Methods
  
  The following methods are available on the `Updown` object:
  
  #### check
  
  Return the `Updown::Check` object associated with the given "check\_id". Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### check\_ids
  
  Returns a list of "check\_id"s of the `Updown::Check`s that are being performed for the user associated with the given API key. Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### checks
  
  Returns a `Hash` with `Updown::Check` objects, keyed to their "check\_id". Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### downtimes
  
  Returns a list of up to 100 `Node::Downtime` objects for the given "check\_id". Takes an optional `:page` argument to indicate the "page": defaults to `1`.
  
  #### hourly\_metrics
  
  Returns an object `Hash` of `Updown::Metrics` objects for the given "check\_id" about overall metrics per hour, keyed to `DateTime` objects indicating the hour. Optionally takes two named arguments.
  
  `:from`, a `DateTime` object indicating the **start** of the period for which to provide overall metrics. Defaults to `DateTime.now.earlier(:1month)`.
  
  `:to`, a `DateTime` object indicating the **end** of the period for which to provide overal metrics. Defaults to `DateTime.now`.
  
  #### node
  
  Return the `Updown::Node` object associated with the given "node\_id". Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### node\_ids
  
  Returns a list of "node\_id"s of the monitoring servers of the `Updown.io` network. Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### node\_metrics
  
  Returns a `Hash` of `Updown::Metrics` objects for the given "check\_id" about overall metrics per monitoring server in the `Updown.io` network, keyed to "node\_id". Optionally takes two named arguments.
  
  `:from`, a `DateTime` object indicating the **start** of the period for which to provide overall metrics. Defaults to `DateTime.now.earlier(:1month)`.
  
  `:to`, a `DateTime` object indicating the **end** of the period for which to provide overal metrics. Defaults to `DateTime.now`.
  
  #### nodes
  
  Returns a `Hash` with `Updown::Node` objects, keyed to their "node\_id". Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### ipv4-nodes
  
  Returns a list of strings with the IPv4 numbers of the nodes in the `Updown.io` network that are executing the monitoring checks. Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### ipv6-nodes
  
  Returns a list of strings with the IPv6 numbers of the nodes in the `Updown.io` network that are executing the monitoring checks. Takes an optional named boolean argument `:update` to indicate that the information should be refreshed if it was already obtained before.
  
  #### overall\_metrics
  
  Returns a `Updown::Metric` object for the given "check\_id". Optionally takes two named arguments.
  
  `:from`, a `DateTime` object indicating the **start** of the period for which to provide overall metrics. Defaults to `DateTime.now.earlier(:1month)`.
  
  `:to`, a `DateTime` object indicating the **end** of the period for which to provide overal metrics. Defaults to `DateTime.now`.
  
  ## Updown::Event
  
  Objects of this type are **not** created automatically, but need to be created **directly** with the hash of the JSON received by a server that handles a webhook (so no `Updown` object needs to have been created).
  
  ### event
  
  A string indicating the type of event. Can be either "check.down" when a monitored website appears to be down, or "check.up" to indicate that a monitored website has become operational again.
  
  ### check
  
  The associated `Updown::Check` object.
  
  ### downtime
  
  The associated `Updown::Node` object.
  
  # AUTOMATICALLY CREATED CLASSES
  
  ## Updown::Check
  
  An object containing the configuration of the monitoring that the `Updown.io` network does for a given website.
  
  ### alias
  
  A string that describes the check, usually a human readable name of the website being monitored.
  
  ### apdex\_t
  
  A rational number indicating the [APDEX](https://updown.uservoice.com/knowledgebase/articles/915588) threshold.
  
  ### custom\_headers
  
  A hash of custom headers that will be sent to the monitored website.
  
  ### disabled\_locations
  
  An array of monitoring locations that have been disabled, indicated by `node_id`.
  
  ### down
  
  A boolean that will be true if the website is currently considered to be down.
  
  ### down\_since
  
  A `DateTime` object indicating when it was first discovered that the website was down, if down. Else, `Any`.
  
  ### enabled
  
  A boolean indicating whether the monitoring is currently active.
  
  ### error
  
  A string containing the error that was encountered if the website is considered down.
  
  ### favicon\_url
  
  The URL of the favicon small icon representing the website, if any.
  
  ### http\_body
  
  Unclear what the functionality is.
  
  ### http\_verb
  
  A string describing the HTTP method that will be used to monitor the website. Is one of "GET/HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS".
  
  ### last\_check\_at
  
  A `DateTime` object indicating when the last check was done.
  
  ### last\_status
  
  An integer indicating the last HTTP status that was received.
  
  ### mute\_until
  
  A string indicating until when notifications will be muted. Is either a string consisting of "recovery", "forever", or a `DateTime` object indicating until when notifications will be muted, or `Any` if no muting is in effect.
  
  ### next\_check\_at
  
  A `DateTime` object indicating when the next monitoring check will be performed.
  
  ### period
  
  An integer indicating the number of seconds between monitoring checks.
  
  ### published
  
  A boolean indicating whether the monitoring page is publicly accessible or not.
  
  ### ssl
  
  An `Updown::Check::SSL` object, indicating SSL certificate status of the monitored website.
  
  ### string\_match
  
  A string that should occur in the first 1MB of the body returned by the monitored website. An empty string indicates no content checking is done.
  
  #### title
  
  Returns a string consisting of either the `.alias`, or the `.url` if there is no alias specified.
  
  ### token
  
  A string indicating the identifier (check-id) of this monitoring check configuration.
  
  ### uptime
  
  A rational number between 0 and 100 indicating the percentage uptime of the monitored website.
  
  ### url
  
  A string consisting of the URL that will be fetched to assess whether the monitored website is up and running.
  
  ## Updown::Check::SSL
  
  This object generally occurs as the `ssl` method in the `Updown::Check` object.
  
  ### tested\_at
  
  A `DateTime` object indicating when the certificate of the monitored website was checked.
  
  ### expires\_at
  
  A `DateTime` object indicating when the certificate of the monitored website will expire.
  
  ### valid
  
  A boolean indicating whether the certificate of the monitored website was valid the last time it was checked.
  
  ### error
  
  A string indicating the error encountered when checking the validity of the certificate of the monitored server, if any.
  
  ## Updown::Downtime
  
  An object describing a downtime period as seen by at least one of the monitoring servers in the `Updown.io` network.
  
  ### duration
  
  An integer indicating the number of seconds of downtime, or `Any` if the downtime is not ended yet.
  
  ### ended\_at
  
  A `DateTime` object indicating the moment the downtime appeared to have ended, or `Any` if the downtime is not ended yet..
  
  ### error
  
  A string describing the reason the website appeared to be down, e.g. a HTTP status code like "500".
  
  ### id
  
  A string identifying this particular downtime.
  
  ### partial
  
  A boolean indicating whether the downtime was partial or complete (e.g. not being reachable by IPv6, but operating normally with IPv4).
  
  ### started\_at
  
  A `DateTime` object indicating the moment the downtime appeared to have started.
  
  ## Updown::Metrics
  
  A collection of statistical data applicable for the current situation, or for a certain period, or for a certain `Updown::Node`.
  
  ### apdex
  
  A rational number indicating the current [APDEX](https://updown.uservoice.com/knowledgebase/articles/915588) for this set of metrics.
  
  ### requests
  
  The associated `Updown::Metrics::Requests` object.
  
  ### timings
  
  The associated `Updown::Metrics::Timings` object.
  
  ## Updown::Metrics::Requests
  
  This object is usually returned by the "requests" method of the `Updown::Metrics` object.
  
  ### by\_response\_time
  
  The associated `Updown::Metrics::Timings::ByResponseTime` object.
  
  ### failures
  
  An integer indicating the number of monitoring requests that failed.
  
  ### samples
  
  An integer indicating the number of monitoring requests that were done.
  
  ### satisfied
  
  An integer indicating the number of monitoring requests that were processed to the user's [APDEX](https://updown.uservoice.com/knowledgebase/articles/915588) satisfaction.
  
  ### tolerated
  
  An integer indicating the number of monitoring requests that were processed to the user's [APDEX](https://updown.uservoice.com/knowledgebase/articles/915588) tolerance.
  
  ## Updown::Metrics::Requests::ByResponseTime
  
  This object is usually returned by the "by\_response\_time" method of the `Updown::Metrics::Request` object.
  
  ### under125
  
  An integer indicating the number of monitoring requests that were processed under 125 milliseconds.
  
  ### under250
  
  An integer indicating the number of monitoring requests that were processed under 250 milliseconds.
  
  ### under500
  
  An integer indicating the number of monitoring requests that were processed under 500 milliseconds.
  
  ### under1000
  
  An integer indicating the number of monitoring requests that were processed under 1 second.
  
  ### under2000
  
  An integer indicating the number of monitoring requests that were processed under 2 seconds.
  
  ### under4000
  
  An integer indicating the number of monitoring requests that were processed under 4 seconds.
  
  ## Updown::Metrics::Timings
  
  This object is usually returned by the "timings" method of the `Updown::Metrics` object.
  
  ### connection
  
  An integer indicating the average number of milliseconds it took to set up a connection with the monitored website.
  
  ### handshake
  
  An integer indicating the average number of milliseconds it took to do the TLS handshake with the monitored website.
  
  ### namelookup
  
  An integer indicating the average number of milliseconds it took to look up the name of the monitored website.
  
  ### redirect
  
  An integer indicating the average number of milliseconds it took to process any redirect that the monitored website did. Any value greater than 0 probably indicates a misconfigured URL of the monitored website.
  
  ### response
  
  An integer indicating the average number of milliseconds it took for the monitored website to initiate a response.
  
  ### total
  
  An integer indicating the average number of milliseconds it took for the monitored website to complete the monitoring request.
  
  ## Updown::Node
  
  An object containing information about a monitoring node in the `Updown.io` network.
  
  ### city
  
  A string with the name of the city where the monitoring node is located.
  
  ### country
  
  A string with the name of the country where the monitoring node is located.
  
  ### country\_code
  
  A string with the 2-letter code of the country where the monitoring node is located.
  
  ### ip
  
  A string indicating the IPv4 number of the monitoring node.
  
  ### ip6
  
  A string indicating the IPv6 number of the monitoring node.
  
  ### lat
  
  A rational number indicating the latitude of the monitoring node.
  
  ### lng
  
  A rational number indicating the longitude of the monitoring node.
  
  ### node\_id
  
  A string indicating the ID with which the monitoring node can be indicated.
  
  ## Updown::Webhook
  
  Objects returned by the `webhooks` method of the `Updown` object.
  
  ### id
  
  A string identifying this webhook.
  
  ### url
  
  A string with the URL to which any notifications should be sent.
  
  # AUTHOR
  
  Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)
  
  Source can be located at: <https://github.com/lizmat/Updown> . Comments and Pull Requests are welcome.
  
  If you like this module, or what I'm doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2021, 2022, 2024 Elizabeth Mattijsen
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  