end_point_blank 0.6.1 → 0.13.0

data/lib/end_point_blank/management/client.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "configuration"
+require_relative "error"
+require_relative "transport"
+require_relative "resources/base"
+require_relative "resources/api_packages"
+require_relative "resources/clients"
+require_relative "resources/applications"
+
+module EndPointBlank
+  module Management
+    # A client for the EndPointBlank organization management API (app_portal's
+    # +/api/v1+): your organization's API packages, clients, package
+    # assignments, grants, applications, environments and runtime credentials,
+    # and the managed clients you run for your customers.
+    #
+    # Plain Ruby: usable from a script, a job or a console as well as a Rails
+    # app. It authenticates only with a management API key
+    # (<tt>Authorization: Bearer epb_mk_...</tt>, created in the portal under
+    # Settings > API Keys) and shares nothing with the runtime configuration:
+    # it never sends a runtime client_id/client_secret and never calls intake.
+    #
+    #   mgmt = EndPointBlank::Management::Client.new(api_key: ENV.fetch("EPB_MGMT_KEY"))
+    #   mgmt.organization                  # => {"id" => ..., "name" => ..., ...}
+    #   mgmt.api_packages.each { |package| puts package["name"] }
+    #
+    # Arguments left nil fall back to {Management.configure} (and its
+    # ENDPOINTBLANK_MANAGEMENT_* environment variables), then the defaults.
+    #
+    # Thread-safe: each request opens its own connection.
+    class Client
+      KEY_PREFIX = "epb_mk_"
+      # The prefix and the rest of the key in the alphabet app_portal mints it
+      # in (URL-safe base64): nothing else can be a valid key, so nothing else
+      # is ever put in a header.
+      KEY_FORMAT = /\Aepb_mk_[A-Za-z0-9_-]+\z/.freeze
+
+      # The options {#initialize} takes besides api_key and base_url.
+      OPTIONS = %i[max_retries max_retry_wait connect_timeout read_timeout sleeper excon_options].freeze
+
+      DEFAULT_SLEEPER = ->(seconds) { Kernel.sleep(seconds) }
+
+      # @return [Resources::ApiPackages]
+      attr_reader :api_packages
+      # @return [Resources::Endpoints]
+      attr_reader :endpoints
+      # @return [Resources::Clients]
+      attr_reader :clients
+      # @return [Resources::PackageAssignments]
+      attr_reader :package_assignments
+      # @return [Resources::Grants]
+      attr_reader :grants
+      # @return [Resources::Applications]
+      attr_reader :applications
+      # @return [Resources::Environments]
+      attr_reader :environments
+      # @return [Resources::Credentials]
+      attr_reader :credentials
+
+      # @param api_key [String] a management API key, epb_mk_...
+      # @param base_url [String] app_portal's URL (default https://app.endpointblank.com)
+      # @param max_retries [Integer] retries after the first attempt; 0 turns them off
+      # @param max_retry_wait [Numeric] the longest single wait, in seconds
+      # @param connect_timeout [Numeric] seconds
+      # @param read_timeout [Numeric] seconds
+      # @param sleeper [#call] called with the seconds to wait before a retry
+      #   (default Kernel#sleep); replace it in tests
+      # @param excon_options [Hash] extra options for Excon.new (e.g. a proxy,
+      #   or <tt>mock: true</tt> with Excon.stub in tests)
+      # @raise [EndPointBlank::ConfigurationError] for a missing or malformed key or base URL
+      def initialize(api_key: nil, base_url: nil, **options)
+        unknown = options.keys - OPTIONS
+        raise ArgumentError, "unknown option(s): #{unknown.join(", ")}" unless unknown.empty?
+
+        config = Management.configuration
+        @transport = Transport.new(
+          api_key: self.class.validate_key(api_key || config.api_key),
+          base_url: self.class.validate_base_url(base_url || config.base_url),
+          **transport_options(config, options)
+        )
+        build_resources
+      end
+
+      # app_portal's URL this client calls.
+      def base_url
+        @transport.base_url
+      end
+
+      # GET /organization: the organization the key belongs to, and the key's
+      # name and scope.
+      # @return [Hash] <tt>{"id", "name", "domain", "slug", "key" => {"name", "scope"}}</tt>
+      def organization
+        body = @transport.request("GET", "/organization")
+        body.is_a?(Hash) ? body["data"] : body
+      end
+
+      # A view of the API as your managed client +client_id+ (a client
+      # created with <tt>clients.create_managed</tt>): its applications,
+      # environments and credentials, under /clients/:client_id/. Works only
+      # while the client is unclaimed; afterwards every call answers 404.
+      #
+      # @return [ManagedClient]
+      def for_managed_client(client_id)
+        ManagedClient.new(@transport, client_id, @clients)
+      end
+
+      # Never shows the key.
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} api_key=[REDACTED]>"
+      end
+      alias to_s inspect
+
+      # The key, if it is a management API key. The error never repeats it.
+      # @api private
+      def self.validate_key(api_key)
+        key = normalized_key(api_key)
+        return key if key&.match?(KEY_FORMAT)
+
+        given = key.nil? || key.empty? ? "No key was given" : "The key given does not have that form"
+        raise EndPointBlank::ConfigurationError,
+              "EndPointBlank::Management::Client needs a management API key: #{KEY_PREFIX} followed by " \
+              "the rest of the key, as the portal shows it under Settings > API Keys. #{given}. " \
+              "Runtime client credentials are not accepted by the management API."
+      end
+
+      # +api_key+ without surrounding whitespace (a key read from a file or an
+      # env var often ends in a newline), or nil when it is not a readable
+      # String at all.
+      def self.normalized_key(api_key)
+        return nil unless api_key.is_a?(String) && api_key.valid_encoding? && api_key.encoding.ascii_compatible?
+
+        api_key.strip
+      end
+      private_class_method :normalized_key
+
+      # +base_url+ without a trailing slash, if it is an http(s) URL with a
+      # host and no userinfo, query or fragment. The error never repeats it,
+      # since a URL can carry credentials.
+      # @api private
+      def self.validate_base_url(base_url)
+        return UrlPath.strip_trailing_slashes(base_url.to_s) if plain_http_url?(base_url)
+
+        raise EndPointBlank::ConfigurationError,
+              "The management API base_url must be an http(s) URL with a host and no userinfo, " \
+              "query or fragment, such as #{Configuration::DEFAULT_BASE_URL}."
+      end
+
+      def self.plain_http_url?(base_url)
+        uri = URI.parse(base_url.to_s)
+        %w[http https].include?(uri.scheme) && !uri.host.to_s.empty? &&
+          [uri.userinfo, uri.query, uri.fragment].all?(&:nil?)
+      rescue URI::InvalidURIError
+        false
+      end
+      private_class_method :plain_http_url?
+
+      private
+
+      def transport_options(config, options)
+        {
+          max_retries: non_negative(:max_retries, options.fetch(:max_retries, config.max_retries)),
+          max_retry_wait: non_negative(:max_retry_wait, options.fetch(:max_retry_wait, config.max_retry_wait)),
+          connect_timeout: options.fetch(:connect_timeout, config.connect_timeout),
+          read_timeout: options.fetch(:read_timeout, config.read_timeout),
+          sleeper: options.fetch(:sleeper, DEFAULT_SLEEPER),
+          excon_options: options.fetch(:excon_options, {})
+        }
+      end
+
+      def non_negative(name, value)
+        return value if value.is_a?(Numeric) && !value.negative?
+
+        raise ArgumentError, "#{name} must be a non-negative number, got #{value.inspect}"
+      end
+
+      def build_resources
+        @api_packages = Resources::ApiPackages.new(@transport)
+        @endpoints = Resources::Endpoints.new(@transport)
+        @clients = Resources::Clients.new(@transport)
+        @package_assignments = Resources::PackageAssignments.new(@transport)
+        @grants = Resources::Grants.new(@transport)
+        @applications = Resources::Applications.new(@transport)
+        @environments = Resources::Environments.new(@transport)
+        @credentials = Resources::Credentials.new(@transport)
+      end
+    end
+
+    # Your managed client's applications, environments and credentials, from
+    # {Client#for_managed_client}. The same calls as the {Client}'s own,
+    # sent under /api/v1/clients/:client_id/.
+    class ManagedClient
+      # @return [String] the client's id (as in /clients/:client_id)
+      attr_reader :client_id
+      # @return [Resources::Applications]
+      attr_reader :applications
+      # @return [Resources::Environments]
+      attr_reader :environments
+      # @return [Resources::Credentials]
+      attr_reader :credentials
+
+      def initialize(transport, client_id, clients)
+        prefix = "/clients/#{Resources::Base.escape(client_id)}"
+        @client_id = client_id
+        @clients = clients
+        @applications = Resources::Applications.new(transport, prefix)
+        @environments = Resources::Environments.new(transport, prefix)
+        @credentials = Resources::Credentials.new(transport, prefix)
+      end
+
+      # The client itself (GET /clients/:client_id). @return [Hash]
+      def get
+        @clients.get(client_id)
+      end
+
+      # POST /clients/:client_id/claim_invites: emails your customer an
+      # invite to claim the client. @return [Hash]
+      def claim_invite(email:, idempotency_key: nil)
+        @clients.claim_invite(client_id, email: email, idempotency_key: idempotency_key)
+      end
+
+      def inspect
+        "#<#{self.class.name} client_id=#{client_id.inspect}>"
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/configuration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # Defaults for {Client.new}, set with {Management.configure}, e.g. in a
+    # Rails initializer.
+    #
+    # Separate from {EndPointBlank::Configuration} on purpose: the runtime
+    # client_id/client_secret are never sent to the management API, and the
+    # management key is never sent to intake. Nothing here reads the runtime
+    # configuration, and nothing in the runtime configuration reads this.
+    class Configuration
+      DEFAULT_BASE_URL = "https://app.endpointblank.com"
+      DEFAULT_MAX_RETRIES = 2
+      DEFAULT_MAX_RETRY_WAIT = 60
+      DEFAULT_CONNECT_TIMEOUT = 5
+      DEFAULT_READ_TIMEOUT = 30
+
+      attr_writer :api_key, :base_url
+
+      # Retries after the first attempt (see {Transport}). 0 turns them off.
+      attr_accessor :max_retries
+      # The longest wait, in seconds, a retry will sleep (a longer
+      # Retry-After raises the error instead).
+      attr_accessor :max_retry_wait
+      attr_accessor :connect_timeout, :read_timeout
+
+      def initialize
+        @max_retries = DEFAULT_MAX_RETRIES
+        @max_retry_wait = DEFAULT_MAX_RETRY_WAIT
+        @connect_timeout = DEFAULT_CONNECT_TIMEOUT
+        @read_timeout = DEFAULT_READ_TIMEOUT
+      end
+
+      # The management API key (epb_mk_...), falling back to the
+      # ENDPOINTBLANK_MANAGEMENT_KEY environment variable.
+      def api_key
+        @api_key || ENV.fetch("ENDPOINTBLANK_MANAGEMENT_KEY", nil)
+      end
+
+      # app_portal's URL, falling back to the
+      # ENDPOINTBLANK_MANAGEMENT_BASE_URL environment variable, then
+      # {DEFAULT_BASE_URL}. Not the runtime's intake base_url.
+      def base_url
+        @base_url || ENV.fetch("ENDPOINTBLANK_MANAGEMENT_BASE_URL", nil) || DEFAULT_BASE_URL
+      end
+
+      # Never shows the key.
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} api_key=#{api_key ? "[REDACTED]" : "nil"} " \
+          "max_retries=#{max_retries.inspect}>"
+      end
+      alias to_s inspect
+    end
+  end
+end

data/lib/end_point_blank/management/error.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "error_codes"
+
+module EndPointBlank
+  # Reopened with the same superclass in end_point_blank.rb; declared here too
+  # so this file can be required on its own.
+  class Error < StandardError; end
+
+  module Management
+    # Raised by {Client} for every refused or failed management API call.
+    #
+    # The API answers errors as
+    # <tt>{"error": {"code", "message", "details"}}</tt>. +code+ is stable and
+    # meant for programs; match on it (see {ErrorCodes}). +message+ is for
+    # people. +details+ is present only when there is something field-level to
+    # say, e.g. a +validation_failed+ error's fields.
+    #
+    # A code this SDK does not know still raises, carrying that code. An answer
+    # that is not the API's error shape (an HTML page from a proxy) raises with
+    # code +http_error+; a request that never got an answer raises with code
+    # +connection_error+ and no status.
+    class Error < EndPointBlank::Error
+      # @return [String] the API's error code, or one of {ErrorCodes::SDK}
+      attr_reader :code
+      # @return [Object, nil] field-level details, as the API sent them
+      attr_reader :details
+      # @return [Integer, nil] the HTTP status; nil for +connection_error+
+      attr_reader :status
+      # @return [Numeric, nil] the Retry-After header's seconds, when present
+      attr_reader :retry_after
+      # @return [String, nil] the Location header, e.g. on +idempotency_replay_unavailable+
+      attr_reader :location
+      # @return [String, nil] the X-Request-Id header, for support requests
+      attr_reader :request_id
+      # @return [String, nil] the HTTP method of the failed request
+      attr_reader :http_method
+      # @return [String, nil] the path of the failed request (no query, no host)
+      attr_reader :path
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(message, code:, status: nil, details: nil, retry_after: nil, location: nil,
+                     request_id: nil, http_method: nil, path: nil)
+        @code = code
+        @status = status
+        @details = details
+        @retry_after = retry_after
+        @location = location
+        @request_id = request_id
+        @http_method = http_method
+        @path = path
+        super(message)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Builds the error for an answer outside 2xx. +headers+ is any Hash-like
+      # whose keys are header names in any case.
+      def self.from_response(status:, headers:, body:, http_method: nil, path: nil)
+        code, message, details = parse_body(status, body)
+        if code == ErrorCodes::IDEMPOTENCY_REPLAY_UNAVAILABLE
+          message = replay_unavailable_message(header(headers, "location"))
+        end
+
+        new(message,
+            code: code, status: status, details: details,
+            retry_after: parse_retry_after(header(headers, "retry-after")),
+            location: header(headers, "location"), request_id: header(headers, "x-request-id"),
+            http_method: http_method, path: path)
+      end
+
+      # Whether this error is +code+ (a String or Symbol).
+      def code?(code)
+        self.code == code.to_s
+      end
+
+      def inspect
+        "#<#{self.class.name} code=#{code.inspect} status=#{status.inspect} message=#{message.inspect}>"
+      end
+
+      class << self
+        # The case-insensitive value of header +name+, or nil.
+        def header(headers, name)
+          return nil if headers.nil?
+
+          headers.each { |key, value| return value.to_s if key.to_s.casecmp?(name) }
+          nil
+        end
+
+        # Seconds to wait from a Retry-After header: delta-seconds, or an
+        # HTTP-date. nil when absent or unreadable; never negative.
+        def parse_retry_after(value)
+          return nil if value.nil? || value.strip.empty?
+          return Integer(value.strip, 10) if value.strip.match?(/\A\d+\z/)
+
+          require "time"
+          [Time.httpdate(value.strip) - Time.now, 0].max
+        rescue ArgumentError
+          nil
+        end
+
+        private
+
+        def parse_body(status, body)
+          error = JSON.parse(body.to_s)["error"]
+          if error.is_a?(Hash) && error["code"].is_a?(String)
+            message = error["message"].is_a?(String) ? error["message"] : "The request failed (#{error["code"]})."
+            return [error["code"], message, error["details"]]
+          end
+
+          unexpected(status, body)
+        rescue JSON::ParserError, TypeError, NoMethodError
+          unexpected(status, body)
+        end
+
+        def unexpected(status, body)
+          snippet = body.to_s.strip.gsub(/\s+/, " ")[0, 200]
+          message = "The management API answered HTTP #{status} without its JSON error shape"
+          message += snippet.empty? ? "." : ": #{snippet}"
+          [ErrorCodes::HTTP_ERROR, message, nil]
+        end
+
+        def replay_unavailable_message(location)
+          message = +"A request with this Idempotency-Key already succeeded, and its answer held a secret " \
+                     "that is shown only once, so it can't be replayed and was not retried. Read or list " \
+                     "the resource to see its current state"
+          message << " (#{location})" if location
+          message << ". If you need a secret you never received, rotate the credential."
+          message
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/error_codes.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # Every +error.code+ the management API can answer, with its HTTP status, as
+    # app_portal's docs list them, plus the few codes this SDK raises itself
+    # when there is no API answer to read one from.
+    #
+    # Match on these rather than on messages, which are for people and may
+    # change. The list is not closed: an {Error} carrying a code missing here
+    # still raises with that code, so a newer API never breaks an older SDK.
+    module ErrorCodes
+      # Authentication and limits
+      MISSING_KEY = "missing_key"
+      INVALID_KEY = "invalid_key"
+      RUNTIME_CREDENTIAL_REFUSED = "runtime_credential_refused"
+      INSUFFICIENT_SCOPE = "insufficient_scope"
+      AUDIT_UNAVAILABLE = "audit_unavailable"
+      RATE_LIMITED = "rate_limited"
+      PLAN_LIMIT = "plan_limit"
+
+      # Requests
+      VALIDATION_FAILED = "validation_failed"
+      # No such resource in your organization (another organization's id
+      # answers this too), or no such /api/v1 path.
+      NOT_FOUND = "not_found"
+      INVALID_PAGINATION = "invalid_pagination"
+      INVALID_FILTER = "invalid_filter"
+      INVALID_IDEMPOTENCY_KEY = "invalid_idempotency_key"
+      IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused"
+      IDEMPOTENCY_REQUEST_IN_PROGRESS = "idempotency_request_in_progress"
+      IDEMPOTENCY_REPLAY_UNAVAILABLE = "idempotency_replay_unavailable"
+      # Any request the API cannot read (e.g. a body that is not JSON).
+      BAD_REQUEST = "bad_request"
+      INTERNAL_SERVER_ERROR = "internal_server_error"
+
+      # Applications, environments and API packages
+      HAS_DEPENDENTS = "has_dependents"
+      PROTECTED = "protected"
+      INVALID_ENVIRONMENT_BASE_URLS = "invalid_environment_base_urls"
+      API_PACKAGE_ASSIGNED = "api_package_assigned"
+      INTAKE_SYNC_FAILED = "intake_sync_failed"
+
+      # Credentials
+      DELETE_REFUSED = "delete_refused"
+      INTAKE_CREDENTIAL = "intake_credential"
+      INTAKE_REJECTED = "intake_rejected"
+      INTAKE_UNAVAILABLE = "intake_unavailable"
+
+      # Clients, packages and grants
+      INVALID_CONTACTS = "invalid_contacts"
+      INVALID_PACKAGES = "invalid_packages"
+      INVALID_GRANTS = "invalid_grants"
+      INVALID_MANAGED = "invalid_managed"
+      CLIENT_NOT_ACCEPTED = "client_not_accepted"
+      CLIENT_ACCEPTED = "client_accepted"
+      CLIENT_NOT_MANAGED = "client_not_managed"
+      ALREADY_A_MEMBER = "already_a_member"
+      MANAGED_CLIENT_HAS_CREDENTIALS = "managed_client_has_credentials"
+      API_PACKAGE_NOT_FOUND = "api_package_not_found"
+      ENVIRONMENT_NOT_FOUND = "environment_not_found"
+      ALREADY_ASSIGNED = "already_assigned"
+      NOTHING_PUBLISHED_IN_ENVIRONMENT = "nothing_published_in_environment"
+      APPLICATION_NOT_FOUND = "application_not_found"
+      ENDPOINT_NOT_FOUND = "endpoint_not_found"
+      ENVIRONMENT_NOT_IN_APPLICATION = "environment_not_in_application"
+      ALREADY_GRANTED = "already_granted"
+      GRANT_REVOKED_CONCURRENTLY = "grant_revoked_concurrently"
+
+      # The warning code API package endpoint writes answer in +warnings+ (not
+      # an error): a client assignment of the package now derives no grant.
+      ASSIGNMENT_DERIVES_NOTHING = "assignment_derives_nothing"
+
+      # Raised by this SDK, never sent by the API: the request never got an
+      # answer (DNS, TLS, refused connection, timeout).
+      CONNECTION_ERROR = "connection_error"
+      # Raised by this SDK: an error answer whose body is not the API's JSON
+      # error shape, such as an HTML page from a proxy. +status+ still says
+      # what happened.
+      HTTP_ERROR = "http_error"
+      # Raised by this SDK: a success answer whose body is not JSON.
+      INVALID_RESPONSE = "invalid_response"
+
+      # The HTTP status the API answers each of its codes with.
+      STATUSES = {
+        MISSING_KEY => 401, INVALID_KEY => 401, RUNTIME_CREDENTIAL_REFUSED => 401,
+        INSUFFICIENT_SCOPE => 403, AUDIT_UNAVAILABLE => 503, RATE_LIMITED => 429, PLAN_LIMIT => 402,
+        VALIDATION_FAILED => 422, NOT_FOUND => 404, INVALID_PAGINATION => 400, INVALID_FILTER => 422,
+        INVALID_IDEMPOTENCY_KEY => 400, IDEMPOTENCY_KEY_REUSED => 422,
+        IDEMPOTENCY_REQUEST_IN_PROGRESS => 409, IDEMPOTENCY_REPLAY_UNAVAILABLE => 409,
+        BAD_REQUEST => 400, INTERNAL_SERVER_ERROR => 500,
+        HAS_DEPENDENTS => 422, PROTECTED => 422, INVALID_ENVIRONMENT_BASE_URLS => 422,
+        API_PACKAGE_ASSIGNED => 422, INTAKE_SYNC_FAILED => 422,
+        DELETE_REFUSED => 422, INTAKE_CREDENTIAL => 409, INTAKE_REJECTED => 422, INTAKE_UNAVAILABLE => 503,
+        INVALID_CONTACTS => 422, INVALID_PACKAGES => 422, INVALID_GRANTS => 422, INVALID_MANAGED => 422,
+        CLIENT_NOT_ACCEPTED => 422, CLIENT_ACCEPTED => 422, CLIENT_NOT_MANAGED => 422,
+        ALREADY_A_MEMBER => 422, MANAGED_CLIENT_HAS_CREDENTIALS => 422, API_PACKAGE_NOT_FOUND => 422,
+        ENVIRONMENT_NOT_FOUND => 422, ALREADY_ASSIGNED => 422, NOTHING_PUBLISHED_IN_ENVIRONMENT => 422,
+        APPLICATION_NOT_FOUND => 422, ENDPOINT_NOT_FOUND => 422, ENVIRONMENT_NOT_IN_APPLICATION => 422,
+        ALREADY_GRANTED => 422, GRANT_REVOKED_CONCURRENTLY => 409
+      }.freeze
+
+      # Every code the API can send, as strings.
+      ALL = STATUSES.keys.freeze
+
+      # Codes this SDK raises itself.
+      SDK = [CONNECTION_ERROR, HTTP_ERROR, INVALID_RESPONSE].freeze
+
+      # Whether +code+ is one this version of the SDK knows about.
+      def self.known?(code)
+        STATUSES.key?(code) || SDK.include?(code)
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/idempotency_key.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module EndPointBlank
+  module Management
+    # The Idempotency-Key a management API request carries: every POST has
+    # one, so a retry of it is replayed by the API rather than run twice.
+    module IdempotencyKey
+      MAX_LENGTH = 255
+
+      # The key to send for +method+: the caller's (stripped, as the API reads
+      # it), or a new random UUID v4 for a POST without one; nil for any other
+      # method, which must not be given one.
+      #
+      # @raise [ArgumentError] for a key on a non-POST, or an empty or
+      #   too-long key
+      def self.resolve(method, key)
+        unless method == "POST"
+          raise ArgumentError, "idempotency_key applies to POST requests only" unless key.nil?
+
+          return nil
+        end
+        return SecureRandom.uuid if key.nil?
+
+        key = key.to_s.strip
+        return key if key.length.between?(1, MAX_LENGTH)
+
+        raise ArgumentError, "idempotency_key must be 1 to #{MAX_LENGTH} characters"
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/page.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # One page of a management API list: the items (+data+, Hashes with String
+    # keys, as the API sent them) and the cursor for the next page, nil on the
+    # last one. Enumerable over its items.
+    #
+    # Pass +next_cursor+ as +after:+ to the same list call for the next page,
+    # or use the resource's +each+ to walk every page.
+    class Page
+      include Enumerable
+
+      # @return [Array<Hash>]
+      attr_reader :data
+      # @return [String, nil]
+      attr_reader :next_cursor
+
+      def initialize(data:, next_cursor:)
+        @data = data
+        @next_cursor = next_cursor
+      end
+
+      # Builds a page from a list answer, <tt>{"data" => [...], "next_cursor" => ...}</tt>.
+      def self.from_body(body)
+        body = {} unless body.is_a?(Hash)
+        new(data: Array(body["data"]), next_cursor: body["next_cursor"])
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        data.each(&block)
+        self
+      end
+
+      # Whether there is a page after this one.
+      def next_page?
+        !next_cursor.nil? && !next_cursor.empty?
+      end
+
+      def size
+        data.size
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} size=#{size} next_cursor=#{next_cursor.inspect}>"
+      end
+    end
+  end
+end