dregs 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4f2ed05bc7ad6b7f11275cd1433eb3289d2eb9e0591067bbf238bf65c614e1d
-  data.tar.gz: cdd0d2097662216dee63c3453ea925295f62710adbc546d3c3e8ee1e8ae96b9e
+  metadata.gz: bfd935e6538082a551734c1bfeeeb5fe76e8d348e96e3378ace99cf74b65425a
+  data.tar.gz: 32d8827024545f2b625f6150ca9601fd588d3b6a36c5b7b240fda3eefcb49c72
 SHA512:
-  metadata.gz: 5f41a1a52cdc61c9cdd50f8b8fcba9ebd635070946eeaea1330da0494f167138bc9f0c4ebd6b766181f779bf328a5ad221779cc4d72731a32687e1a1efc05271
-  data.tar.gz: 86d8d64737dabd2c619b94a45795b774cf5035bfed7dc7494be30f1255ff0c41b2269967e2f52f9941bfdd408baeb33cac6dabccd6b83224ce8ffbb2f84f3b89
+  metadata.gz: ebbeda4c7c941594f1d0ca31aa9b06f107fa59ea63b81e9ab4ac350e8fd39d64b5cc4b36881a23a591270fcd85dc46f06e263c01415eb491d74b837a6fe3b540
+  data.tar.gz: 13141efc8a036f336fbe7db855aaad71487c370c51110b3e70f89e1313ef3b880b4d4d7c57fe03affd7657577897dddd9a53a935802f04eaca3531835f758c3b

data/CHANGELOG.md

@@ -4,7 +4,30 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.0.0] - Unreleased
+
+The first stable release. It catches the SDK up with the public API: groups, the rest of the identity
+reads and writes, events, devices, and escalations, with paging throughout. Nothing from 0.1.0 changes,
+so upgrading needs no code changes.
+
+### Added
+
+- `groups:` on `track`: the organizations, teams, workspaces, or other groups the user is acting in,
+  each with an `id`, an optional `type` (`"organization"` by default), and optional `data`. Dregs makes
+  the identity a member of each.
+- `client.groups`: `list`, `list_all`, `get`, `create`, `update`, `add_member`, and `remove_member`.
+- `identities.list`, `list_all`, `update` (to disregard an identity or merge attributes), `history`,
+  `links`, `reviews`, and `review`, and a `cycle_id:` on `analysis` for a past cycle.
+- `client.events`: `list`, `list_all`, and `get`, with the groups each event was sent with.
+- `client.devices`: `list`, `list_all`, `get`, and `update` to disregard a device.
+- `client.escalations`: `list`, `list_all`, `get`, `update` to move an escalation along, and `summary`.
+- `Dregs::Page`, an `Enumerable` page of items with its position and totals, and a `list_all` on every
+  namespace that walks the pages for you.
+
+### Fixed
+
+- An error response without a message of its own now reads as the status's reason phrase, such as
+  "HTTP 404: Not Found", rather than "Request failed".
 
 ## [0.1.0] - 2026-09-22
 
@@ -23,5 +46,5 @@ The first release. A server-side client for tracking events and reading scores.
 - `Dregs::Webhooks.verify` for checking a webhook's signature and rejecting replays.
 - Lenient models with a `raw` escape hatch, and RBS signatures in `sig/`.
 
-[Unreleased]: https://github.com/dregs-sdk/dregs-sdk-ruby/compare/v0.1.0...HEAD
+[1.0.0]: https://github.com/dregs-sdk/dregs-sdk-ruby/compare/v0.1.0...v1.0.0
 [0.1.0]: https://github.com/dregs-sdk/dregs-sdk-ruby/releases/tag/v0.1.0

data/README.md

@@ -51,6 +51,26 @@ signature, so the identity is the only thing tying the event to a user.
 heavily, so send them whenever you have them. Name the keys the way your application already does and
 map them to Dregs's canonical fields under **Settings → Mappings**; the same goes for event names.
 
+### Groups
+
+If your application groups users into organizations, teams, workspaces, or the like, pass the groups the
+user is acting in. Dregs records each group and makes the identity a member of it. Each group has your
+own `id`, a `type` that is your own name for the kind of group (`"organization"` when omitted), and
+optional `data` that Dregs merges into the group, so later events can send the type and id alone. Dregs
+normalizes types to lower_snake_case, so `ParentCompany` and `parent-company` are the same type, and an
+event can carry one group of each type.
+
+```ruby
+client.track(
+  "user.login",
+  identity: "user_12345",
+  groups: [
+    { type: "organization", id: "org_678", data: { name: "Acme Inc", plan: "enterprise" } },
+    { type: "team", id: "team_42", data: { name: "Payments" } }
+  ]
+)
+```
+
 ### Idempotency
 
 Every event is sent with an `id`, which makes ingestion idempotent: reposting the same id returns the
@@ -133,6 +153,104 @@ client.identities.analyze("user_12345")
 This queues the work and returns; it does not wait for the cycle to finish. Dregs rescores on its own
 as events arrive, so you rarely need this outside of a support or backfill flow.
 
+### History, links, and past cycles
+
+```ruby
+history = client.identities.history("user_12345", limit: 10)
+
+history.each do |entry|
+  puts "#{entry.finished_at} #{entry.humanity} #{entry.behavior}"
+end
+
+older = client.identities.analysis("user_12345", cycle_id: history.last.cycle_id)  # a past cycle
+
+client.identities.links("user_12345").each do |link|
+  puts "#{link.identity_id} #{link.type} #{link.explanation}"  # e.g. "user_999 SAME_DEVICE ..."
+end
+```
+
+### Disregarding an identity
+
+Leave your own staff and test accounts out of scoring and escalations:
+
+```ruby
+client.identities.update("qa_bot_7", disregarded: true)
+```
+
+### Asking for a review
+
+When a score looks wrong, Dregs's AI reviewer will look over the analysis and say why. The review runs
+in the background, so read it back later with `reviews`.
+
+```ruby
+review = client.identities.review("user_12345", feedback: "This is a long-standing customer.")
+
+review.status  # "PENDING", then "FINISHED"
+```
+
+## Listing and paging
+
+Every namespace with a `list` returns one `Dregs::Page` at a time, numbered from 0, and a `list_all`
+that walks every page for you:
+
+```ruby
+page = client.identities.list(term: "example.com", page_size: 50)
+
+page.total_elements  # how many match in all
+page.has_next?       # whether another page follows
+
+client.identities.list_all(group: "org_678", sort: "humanityScore", order: :asc).each do |identity|
+  # ...
+end
+```
+
+A page is `Enumerable` over its items. `list_all` returns an `Enumerator` that fetches each page only
+when the items before it have been used up, so `list_all.first(10)` costs a single request; pass it a
+block instead and it yields every item. Filters you leave out are not sent. A page holds at most 100
+items.
+
+## Groups
+
+`track` records groups and memberships as events arrive. The `groups` namespace reads them back, and
+keeps Dregs in step when something changes outside an event, such as a user leaving a team:
+
+```ruby
+client.groups.create("org_678", attributes: { name: "Acme Inc", plan: "enterprise" })
+
+group = client.groups.get("organization", "org_678")
+group.identity_count  # 12
+
+client.groups.update("organization", "org_678", { plan: "business" })
+
+client.groups.add_member("team", "team_42", "user_12345")
+client.groups.remove_member("team", "team_42", "user_12345")
+
+client.groups.list_all(group_type: "team", identity: "user_12345").each do |team|
+  puts "#{team.id} #{team.display_name}"
+end
+```
+
+`create` merges into the group when one with the same type and id already exists, so it is safe to call
+on every sync. The type defaults to `"organization"`.
+
+## Events, devices, and escalations
+
+```ruby
+client.events.list_all(identity: "user_12345").each do |event|
+  puts "#{event.timestamp} #{event.name} #{event.canonical_type}"
+end
+
+client.devices.update("a1b2c3d4e5", disregarded: true)  # e.g. a shared office machine
+
+client.escalations.list_all(status: :open, severity: :critical).each do |escalation|
+  notify_on_call(escalation.identity.id)
+  client.escalations.update(escalation.id, status: :acknowledged)
+end
+
+summary = client.escalations.summary
+summary.open  # 3
+```
+
 ## Errors
 
 ```ruby
@@ -153,7 +271,7 @@ end
 | `Dregs::AuthenticationError` | 401, the secret key was not recognized |
 | `Dregs::QuotaExceededError` | 402, the account is over its monthly event limit |
 | `Dregs::PermissionDeniedError` | 403, the credential may not do this |
-| `Dregs::NotFoundError` | 404, no such identity, or it has not been analyzed |
+| `Dregs::NotFoundError` | 404, no such identity (or group, event, device, escalation), or it has not been analyzed |
 | `Dregs::RateLimitError` | 429, too many requests |
 | `Dregs::ServerError` | 5xx |
 | `Dregs::TimeoutError` | the request timed out |

data/lib/dregs/client.rb

@@ -7,7 +7,11 @@ require "securerandom"
 require "timeout"
 require "uri"
 
+require_relative "devices"
 require_relative "errors"
+require_relative "escalations"
+require_relative "events"
+require_relative "groups"
 require_relative "identities"
 require_relative "models"
 require_relative "version"
@@ -54,6 +58,9 @@ module Dregs
     STATUS_RATE_LIMITED = "rate_limited"
     STATUS_QUOTA_EXCEEDED = "quota_exceeded"
 
+    # The type a group is sent with when the caller does not name one.
+    DEFAULT_GROUP_TYPE = "organization"
+
     # @return [String] the API root every request is built against, without a trailing slash
     attr_reader :base_url
 
@@ -66,6 +73,18 @@ module Dregs
     # @return [Identities] read identities, their scores, and their analysis
     attr_reader :identities
 
+    # @return [Groups] read and manage groups and their members
+    attr_reader :groups
+
+    # @return [Events] read the events Dregs has recorded
+    attr_reader :events
+
+    # @return [Devices] read devices, and disregard them
+    attr_reader :devices
+
+    # @return [Escalations] read and work escalations
+    attr_reader :escalations
+
     # @param secret_key [String, nil] your credential's secret key; defaults to +$DREGS_SECRET_KEY+
     # @param base_url [String, nil] the API root; defaults to +$DREGS_BASE_URL+, then
     #   {DEFAULT_BASE_URL}
@@ -88,6 +107,10 @@ module Dregs
       @timeout = timeout
       @max_retries = max_retries
       @identities = Identities.new(self)
+      @groups = Groups.new(self)
+      @events = Events.new(self)
+      @devices = Devices.new(self)
+      @escalations = Escalations.new(self)
     end
 
     # Records a backend event against an identity.
@@ -96,7 +119,8 @@ module Dregs
     #     "user.signup",
     #     identity: "user_12345",
     #     data: { plan: "pro", referrer: "partner-x" },
-    #     identity_data: { email: "ada@example.com", name: "Ada Lovelace" }
+    #     identity_data: { email: "ada@example.com", name: "Ada Lovelace" },
+    #     groups: [{ type: "team", id: "team_42", data: { name: "Payments" } }]
     #   )
     #
     # @param event_type [String] your name for the event, such as +"user.signup"+. Map it to one
@@ -111,6 +135,11 @@ module Dregs
     #   Dregs merges these into the identity, and the analyzers lean on them heavily, so send them
     #   whenever you have them. Flat keys work best; name them as your application already does
     #   and map them under *Settings -> Mappings*.
+    # @param groups [Array<Hash>, nil] the groups the user is acting in, such as their organization
+    #   or team, if your application has them. Each is a hash with an +id+ (your own), an optional
+    #   +type+ (your own name for the kind of group, defaulting to +"organization"+), and optional
+    #   +data+ that Dregs merges into the group. Dregs makes the identity a member of each. At most
+    #   one group of each type. Keys may be symbols or strings.
     # @param event_id [String, nil] your own id for the event, which makes ingestion idempotent:
     #   reposting the same id returns the original event instead of recording a second one. Pass
     #   the id your application already has (the row id of the record that triggered the event,
@@ -124,13 +153,15 @@ module Dregs
     # @raise [RateLimitError] the credential is ingesting too fast
     # @raise [AuthenticationError] the secret key was not recognized
     # @raise [BadRequestError] the event was malformed
-    # @raise [ArgumentError] the event type, identity, or event id was unusable
-    def track(event_type, identity:, data: {}, identity_data: {}, event_id: nil, timestamp: nil, source: nil)
+    # @raise [ArgumentError] the event type, identity, event id, or groups were unusable
+    def track(event_type, identity:, data: {}, identity_data: {}, groups: nil, event_id: nil, timestamp: nil,
+              source: nil)
       body = track_body(
         event_type,
         identity: identity,
         data: data,
         identity_data: identity_data,
+        groups: groups,
         event_id: event_id,
         timestamp: timestamp,
         source: source
@@ -142,12 +173,17 @@ module Dregs
     # Performs a request, retrying the failures worth retrying.
     #
     # @api private
-    # @param method [Symbol] +:get+ or +:post+
-    # @param path [String] the path below the base URL, with a leading slash
-    # @param body [Hash, nil] a JSON body, for POSTs that carry one
+    # @param method [Symbol] +:get+, +:post+, +:put+, +:patch+, or +:delete+
+    # @param path [String] the path below the base URL, with a leading slash, its segments already
+    #   escaped
+    # @param body [Hash, nil] a JSON body, for the requests that carry one
+    # @param params [Hash, nil] query parameters. Those that are nil are left out, and booleans are
+    #   spelled +true+ and +false+ as the API's binder reads them.
     # @return [Hash, Array, nil] the parsed response body
-    def request(method, path, body: nil)
+    def request(method, path, body: nil, params: nil)
       uri = URI.parse(url_for(path))
+      query = query_string(params)
+      uri.query = query unless query.nil?
       attempt = 0
 
       loop do
@@ -208,7 +244,7 @@ module Dregs
     # An event id is always sent. When the caller has an id of their own it is used verbatim, so
     # reposting the same event is a no-op on the Dregs side; otherwise one is generated, which is
     # what makes this client's own retries safe to perform.
-    def track_body(event_type, identity:, data:, identity_data:, event_id:, timestamp:, source:)
+    def track_body(event_type, identity:, data:, identity_data:, groups:, event_id:, timestamp:, source:)
       raise ArgumentError, "event_type is required." if event_type.nil? || event_type.to_s.empty?
 
       if identity.nil? || identity.to_s.empty?
@@ -217,6 +253,7 @@ module Dregs
               "identity is the only thing tying the event to a user."
       end
 
+      resolved_groups = groups_body(groups)
       resolved_id = event_id || SecureRandom.uuid.delete("-")
 
       if resolved_id.start_with?("dregs-")
@@ -233,11 +270,63 @@ module Dregs
         "source" => source || "ruby-sdk"
       }
 
+      body["groups"] = resolved_groups unless resolved_groups.empty?
       body["timestamp"] = iso8601(timestamp) unless timestamp.nil?
 
       body
     end
 
+    # Builds the +groups+ array of a track body, refusing malformed entries before any request.
+    #
+    # Each group needs an +id+. Its +type+ defaults to +"organization"+, and Dregs normalizes it to
+    # lower_snake_case, so only one group of each type may go with an event.
+    def groups_body(groups)
+      return [] if groups.nil?
+
+      unless groups.is_a?(Array)
+        raise ArgumentError, "groups is an array of groups, such as [{ type: \"team\", id: \"team_42\" }]."
+      end
+
+      seen = []
+
+      groups.map do |group|
+        unless group.is_a?(Hash)
+          raise ArgumentError, "Each group must be a hash with an id, and optionally a type and data."
+        end
+
+        group_id = group_value(group, :id)
+
+        raise ArgumentError, "Each group needs an id." if group_id.nil? || group_id.to_s.empty?
+
+        group_type = group_value(group, :type)
+        group_type = DEFAULT_GROUP_TYPE if group_type.nil? || group_type == ""
+
+        unless group_type.is_a?(String)
+          raise ArgumentError, "A group's type must be a string, such as \"organization\" or \"team\"."
+        end
+
+        if seen.include?(group_type.downcase)
+          raise ArgumentError,
+                "Only one group of each type can go with an event; \"#{group_type}\" appears twice."
+        end
+
+        data = group_value(group, :data)
+
+        unless data.nil? || data.is_a?(Hash)
+          raise ArgumentError, "A group's data must be a hash, such as { name: \"Payments\" }."
+        end
+
+        seen << group_type.downcase
+
+        { "type" => group_type, "id" => group_id.to_s, "data" => data || {} }
+      end
+    end
+
+    # Reads a group's key whether the caller spelled it as a symbol or a string.
+    def group_value(group, key)
+      group.key?(key) ? group[key] : group[key.to_s]
+    end
+
     # Formats a timestamp the way the API's +Instant+ parser expects.
     #
     # A +Time+ is converted to UTC rather than sent with its offset, and a string is trusted as
@@ -254,6 +343,15 @@ module Dregs
       "#{base_url}/#{path.sub(%r{\A/+}, "")}"
     end
 
+    # Drops unset parameters and encodes the rest, or returns nil when nothing is left to send.
+    def query_string(params)
+      return nil if params.nil?
+
+      pairs = params.compact.map { |name, value| [name.to_s, value.to_s] }
+
+      pairs.empty? ? nil : URI.encode_www_form(pairs)
+    end
+
     def headers
       {
         "Authorization" => "Bearer #{@secret_key}",
@@ -285,6 +383,9 @@ module Dregs
       case method
       when :get then Net::HTTP::Get.new(uri)
       when :post then Net::HTTP::Post.new(uri)
+      when :put then Net::HTTP::Put.new(uri)
+      when :patch then Net::HTTP::Patch.new(uri)
+      when :delete then Net::HTTP::Delete.new(uri)
       else raise ArgumentError, "Unsupported HTTP method: #{method}."
       end
     end
@@ -339,8 +440,8 @@ module Dregs
     end
 
     def api_error(response, payload, status)
-      message = message_from(payload) || response.message.to_s
-      message = "Request failed" if message.empty?
+      message = message_from(payload) || response.message.to_s.strip
+      message = Errors.reason_phrase(status) if message.empty?
 
       return rate_limit_error(response, payload, message) if status == 429
 

data/lib/dregs/devices.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "models"
+require_relative "resource"
+
+module Dregs
+  # The +client.devices+ namespace: the browsers and devices Dregs has seen, identified by their
+  # fingerprints.
+  class Devices < Resource
+    # Returns one page of devices, most recently seen first. Use {#list_all} to walk every page.
+    #
+    # @param identity [String, nil] only devices this identity was seen on
+    # @param term [String, nil] free text matched against fingerprints, addresses, places, and user
+    #   agents
+    # @param page [Integer] the page to return, counting from 0
+    # @param page_size [Integer, nil] items per page, at most 100
+    # @param sort [String, nil] the field to sort on, such as +"lastSeenAt"+ or +"country"+
+    # @param order [Symbol, String, nil] +:asc+ or +:desc+
+    # @return [Page<Device>]
+    # @raise [ArgumentError] the page is negative or the order is not one of the two
+    def list(identity: nil, term: nil, page: 0, page_size: nil, sort: nil, order: nil)
+      filters = { "identity" => identity, "term" => term }
+
+      list_page("/devices", Device, filters, page: page, page_size: page_size, sort: sort, order: order)
+    end
+
+    # Walks every device that matches, fetching pages as it goes. Takes the filters {#list} does.
+    #
+    # @return [Enumerator<Device>] a lazy enumerator, which fetches a page only when the items
+    #   before it have been used up; nil when a block is given, which is called with each device
+    # @raise [ArgumentError] the order is not one of the two
+    def list_all(identity: nil, term: nil, page_size: nil, sort: nil, order: nil, &block)
+      filters = { "identity" => identity, "term" => term }
+
+      list_every("/devices", Device, filters, page_size: page_size, sort: sort, order: order, &block)
+    end
+
+    # Returns the device with this fingerprint.
+    #
+    # @param fingerprint [String] the device's fingerprint
+    # @return [Device]
+    # @raise [NotFoundError] no device has this fingerprint
+    def get(fingerprint)
+      Device.from_api(@client.request(:get, path_for(fingerprint)))
+    end
+
+    # Sets whether the device is disregarded, and returns it.
+    #
+    # A disregarded device, such as a shared office machine, no longer links the identities seen
+    # on it.
+    #
+    #   client.devices.update("a1b2c3d4e5", disregarded: true)
+    #
+    # @param fingerprint [String] the device's fingerprint
+    # @param disregarded [Boolean] whether to disregard it
+    # @return [Device]
+    # @raise [NotFoundError] no device has this fingerprint
+    def update(fingerprint, disregarded:)
+      body = { "disregarded" => disregarded ? true : false }
+
+      Device.from_api(@client.request(:patch, path_for(fingerprint), body: body))
+    end
+
+    private
+
+    def path_for(fingerprint)
+      "/devices/#{segment(fingerprint, "A device fingerprint")}"
+    end
+  end
+end

data/lib/dregs/errors.rb

@@ -115,7 +115,7 @@ module Dregs
   # 5xx. Something went wrong inside Dregs. These are retried automatically.
   class ServerError < APIError; end
 
-  # Maps HTTP statuses to the error class that represents them.
+  # Maps HTTP statuses to the error class that represents them, and to their reason phrases.
   module Errors
     STATUS_ERRORS = {
       400 => BadRequestError,
@@ -126,6 +126,48 @@ module Dregs
       429 => RateLimitError
     }.freeze
 
+    # The standard reason phrase for each status an error response is likely to carry.
+    #
+    # An error body without a message of its own still deserves one more useful than "Request
+    # failed", and a server or proxy speaking HTTP/2 sends no reason phrase on the status line to
+    # fall back to.
+    REASON_PHRASES = {
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      402 => "Payment Required",
+      403 => "Forbidden",
+      404 => "Not Found",
+      405 => "Method Not Allowed",
+      406 => "Not Acceptable",
+      408 => "Request Timeout",
+      409 => "Conflict",
+      410 => "Gone",
+      411 => "Length Required",
+      412 => "Precondition Failed",
+      413 => "Content Too Large",
+      414 => "URI Too Long",
+      415 => "Unsupported Media Type",
+      418 => "I'm a teapot",
+      422 => "Unprocessable Content",
+      425 => "Too Early",
+      428 => "Precondition Required",
+      429 => "Too Many Requests",
+      431 => "Request Header Fields Too Large",
+      500 => "Internal Server Error",
+      501 => "Not Implemented",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable",
+      504 => "Gateway Timeout"
+    }.freeze
+
+    # Returns the standard reason phrase for +status_code+, such as +"Not Found"+ for 404.
+    #
+    # @param status_code [Integer]
+    # @return [String] the phrase, or +"Request failed"+ for a status without a standard one
+    def self.reason_phrase(status_code)
+      REASON_PHRASES.fetch(status_code, "Request failed")
+    end
+
     # Returns the exception class that represents +status_code+.
     #
     # Anything at or above 500 is a {ServerError}; an unmapped 4xx falls back to the {APIError}

data/lib/dregs/escalations.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "models"
+require_relative "resource"
+
+module Dregs
+  # The +client.escalations+ namespace: the escalations your escalation rules open, and moving
+  # them along.
+  class Escalations < Resource
+    # The statuses an escalation moves through.
+    STATUSES = %w[OPEN ACKNOWLEDGED CLOSED].freeze
+
+    # Returns one page of escalations, newest first. Use {#list_all} to walk every page.
+    #
+    # @param status [Symbol, String, nil] only escalations in this status: +:open+,
+    #   +:acknowledged+, or +:closed+
+    # @param severity [Symbol, String, nil] only escalations of this severity: +:info+, +:warning+,
+    #   or +:critical+
+    # @param identity [String, nil] only escalations about this identity
+    # @param rule [Integer, String, nil] only escalations opened by the escalation rule with this id
+    # @param page [Integer] the page to return, counting from 0
+    # @param page_size [Integer, nil] items per page, at most 100
+    # @param sort [String, nil] the field to sort on, such as +"openedAt"+ or +"severity"+
+    # @param order [Symbol, String, nil] +:asc+ or +:desc+
+    # @return [Page<Escalation>]
+    # @raise [ArgumentError] the status is not one of the three, the page is negative, or the order
+    #   is not one of the two
+    def list(status: nil, severity: nil, identity: nil, rule: nil, page: 0, page_size: nil, sort: nil,
+             order: nil)
+      filters = list_filters(status: status, severity: severity, identity: identity, rule: rule)
+
+      list_page(
+        "/escalations", Escalation, filters, page: page, page_size: page_size, sort: sort, order: order
+      )
+    end
+
+    # Walks every escalation that matches, fetching pages as it goes. Takes the filters {#list}
+    # does.
+    #
+    #   client.escalations.list_all(status: :open, severity: :critical).each do |escalation|
+    #     notify_on_call(escalation.identity.id)
+    #     client.escalations.update(escalation.id, status: :acknowledged)
+    #   end
+    #
+    # @return [Enumerator<Escalation>] a lazy enumerator, which fetches a page only when the items
+    #   before it have been used up; nil when a block is given, which is called with each escalation
+    # @raise [ArgumentError] the status is not one of the three, or the order is not one of the two
+    def list_all(status: nil, severity: nil, identity: nil, rule: nil, page_size: nil, sort: nil, order: nil,
+                 &block)
+      filters = list_filters(status: status, severity: severity, identity: identity, rule: rule)
+
+      list_every("/escalations", Escalation, filters, page_size: page_size, sort: sort, order: order, &block)
+    end
+
+    # Returns the escalation with this id.
+    #
+    # @param escalation_id [Integer, String]
+    # @return [Escalation]
+    # @raise [NotFoundError] no escalation has this id
+    def get(escalation_id)
+      Escalation.from_api(@client.request(:get, path_for(escalation_id)))
+    end
+
+    # Moves the escalation to +status+ and returns it.
+    #
+    # @param escalation_id [Integer, String]
+    # @param status [Symbol, String] +:open+, +:acknowledged+, or +:closed+
+    # @return [Escalation]
+    # @raise [NotFoundError] no escalation has this id
+    # @raise [ArgumentError] the status is not one of the three
+    def update(escalation_id, status:)
+      body = { "status" => status_param(status) }
+
+      Escalation.from_api(@client.request(:patch, path_for(escalation_id), body: body))
+    end
+
+    # Returns how many escalations are open, acknowledged, and closed.
+    #
+    # @return [EscalationSummary]
+    def summary
+      EscalationSummary.from_api(@client.request(:get, "/escalations/summary"))
+    end
+
+    private
+
+    def path_for(escalation_id)
+      "/escalations/#{segment(escalation_id, "An escalation id")}"
+    end
+
+    def list_filters(status:, severity:, identity:, rule:)
+      {
+        "status" => status.nil? ? nil : status_param(status),
+        "severity" => severity.nil? || severity.to_s.empty? ? nil : severity.to_s.upcase,
+        "identity" => identity,
+        "rule" => rule
+      }
+    end
+
+    def status_param(status)
+      value = status.to_s.upcase if status.is_a?(String) || status.is_a?(Symbol)
+
+      raise ArgumentError, "status is :open, :acknowledged, or :closed." unless STATUSES.include?(value)
+
+      value
+    end
+  end
+end