linkedin-member-data 0.1.0

data/lib/linkedin/member_data/client.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module LinkedIn
+  module MemberData
+    # Entry point of the gem. Holds one `Connection`.
+    #
+    # @example Create a client and read a snapshot
+    #   client = LinkedIn::MemberData::Client.new(access_token: ENV["LINKEDIN_ACCESS_TOKEN"])
+    #   client.snapshot(:connections).each { |row| puts row["First Name"] }
+    class Client
+      # API path of the member authorizations resource.
+      # @return [String]
+      AUTHORIZATIONS_PATH = "/rest/memberAuthorizations"
+
+      # The HTTP connection used for every request.
+      # @api private
+      # @return [Connection]
+      attr_reader :connection
+
+      # Builds a client. No request is sent.
+      #
+      # @param access_token [String] OAuth token with scope `r_dma_portability_self_serve`.
+      #   Leading and trailing spaces are removed.
+      # @param retries [Integer] retries on 429, 5xx and network errors, with backoff. `0` turns retries off.
+      # @param timeout [Integer, Float] open, read and write timeout in seconds.
+      # @param logger [Logger, nil] gets one debug line per request: `GET url -> status`.
+      # @param connection [Connection, nil] ready-made connection. When given, `retries`, `timeout`
+      #   and `logger` are not used. Meant for tests.
+      # @raise [ConfigurationError] when `access_token` is nil or blank.
+      def initialize(access_token:, retries: 3, timeout: 30, logger: nil, connection: nil)
+        ensure_token(access_token)
+        @connection = connection_for(connection, access_token: access_token.to_s.strip, retries:, timeout:, logger:)
+      end
+
+      # Returns a lazy view over snapshot data. No request is sent until you iterate.
+      #
+      # @example One domain, symbol or string
+      #   client.snapshot(:profile).first     # symbol is upcased: "PROFILE"
+      #   client.snapshot("ALL_COMMENTS").to_a
+      # @example All domains
+      #   client.snapshot.each { |row| puts row.keys.inspect }
+      # @param domain [Symbol, String, nil] a name from `Domains::ALL`. A Symbol is upcased.
+      #   A String is sent as given, because the API is case sensitive. `nil` means all domains.
+      # @return [Snapshot]
+      # @raise [ArgumentError] when `domain` is not a Symbol, a String or nil.
+      def snapshot(domain = nil)
+        Snapshot.new(connection, Domains.normalize(domain))
+      end
+
+      # Returns a lazy view over the changelog of the last 28 days. No request is sent until you iterate.
+      #
+      # @example Events of the last 7 days
+      #   client.changelog(since: Time.now - 7 * 86_400).each do |event|
+      #     puts "#{event.method} #{event.resource_name} at #{event.processed_at}"
+      #   end
+      # @example Resume from the last event you saw
+      #   last_seen = client.changelog.to_a.last&.processed_at_ms
+      #   client.changelog(since: last_seen).each { |event| puts event.id }
+      # @param since [Time, Date, Integer, nil] first `processedAt` to fetch.
+      #   Integer is epoch milliseconds. A Date is midnight UTC. `nil` starts at the oldest event.
+      # @param count [Integer] events per request, from 1 to 50.
+      # @return [Changelog]
+      # @raise [ArgumentError] when `count` is outside 1..50 or `since` has an unsupported type.
+      #   Raised before any request.
+      def changelog(since: nil, count: Changelog::DEFAULT_COUNT)
+        Changelog.new(connection, since: since, count: count)
+      end
+
+      # Fetches the authorization record of the token. Sends one request.
+      #
+      # @example
+      #   authorization = client.authorization
+      #   puts authorization.regulated_at if authorization
+      # @return [Authorization, nil] `nil` when LinkedIn returns no authorization.
+      # @raise [ApiError] on a non-2xx response, for example `Unauthorized` for a bad token.
+      # @raise [ConnectionError] on a network failure after all retries.
+      def authorization
+        element = member_authorizations.first
+        Authorization.from_api(element) unless element.nil?
+      end
+
+      # Starts changelog archiving for the member. LinkedIn usually does this by itself.
+      #
+      # @example
+      #   client.enable_changelog!  # => true
+      # @return [true] always true. API failures raise.
+      # @raise [ApiError] on a non-2xx response.
+      # @raise [ConnectionError] on a network failure after all retries.
+      def enable_changelog!
+        connection.post(AUTHORIZATIONS_PATH, {})
+        true
+      end
+
+      private
+
+      def member_authorizations
+        connection.get(AUTHORIZATIONS_PATH, q: "memberAndApplication").fetch("elements", [])
+      end
+
+      def connection_for(connection, **) = connection.nil? ? Connection.new(**) : connection
+
+      def ensure_token(token)
+        raise ConfigurationError, "access_token is required" if token.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/linkedin/member_data/connection.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+module LinkedIn
+  module MemberData
+    # One HTTP door to api.linkedin.com. Adds headers, parses JSON,
+    # maps statuses to errors and retries 429/5xx/network failures.
+    # @api private
+    class Connection
+      # @return [String]
+      BASE_URL = "https://api.linkedin.com"
+      # Value of the `Linkedin-Version` header.
+      # @return [String]
+      API_VERSION = "202312"
+      # Network errors that become a `ConnectionError`.
+      # @return [Array<Class>]
+      RETRYABLE_EXCEPTIONS = [
+        Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED,
+        Errno::EPIPE, SocketError, EOFError, OpenSSL::SSL::SSLError
+      ].freeze
+      # Upper limit for a server-sent Retry-After, in seconds.
+      # @return [Integer]
+      MAX_RETRY_AFTER = 60
+      HEADERS = {
+        "Linkedin-Version" => API_VERSION,
+        "X-Restli-Protocol-Version" => "2.0.0",
+        "Content-Type" => "application/json",
+        "User-Agent" => "linkedin-member-data/#{VERSION}"
+      }.freeze
+
+      # Default transport: a real Net::HTTP call. Replaced in tests.
+      # @api private
+      class NetHttpTransport
+        # @param timeout [Integer, Float] open, read and write timeout in seconds.
+        def initialize(timeout:)
+          @timeout = timeout
+        end
+
+        # @param request [Net::HTTPRequest]
+        # @param uri [URI::HTTPS]
+        # @return [Net::HTTPResponse]
+        def call(request, uri)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: @timeout,
+                                              read_timeout: @timeout, write_timeout: @timeout) do |http|
+            http.request(request)
+          end
+        end
+      end
+
+      # Runs a block again on retryable errors. Waits for Retry-After, else backs off.
+      # @api private
+      class Retrier
+        def initialize(retries:, sleeper:)
+          @retries = retries
+          @sleeper = sleeper
+        end
+
+        # Yields, and runs again on a retryable error. Raises after the last try.
+        # @api private
+        def run
+          (0..@retries).each do |attempt|
+            return yield
+          rescue ApiError, ConnectionError => error
+            wait_or_raise(error, attempt)
+          end
+        end
+
+        private
+
+        def wait_or_raise(error, attempt)
+          raise error unless error.retryable? && attempt < @retries
+
+          backoff = (0.5 * (2**attempt)) + (rand * 0.1)
+          # compact.first picks Retry-After when present (a plain `||` is not provable by MC/DC).
+          @sleeper.call([[error.retry_after, backoff].compact.first, MAX_RETRY_AFTER].min)
+        end
+      end
+      private_constant :Retrier, :HEADERS
+
+      # @param access_token [String] OAuth token. Sent as a Bearer header.
+      # @param retries [Integer] retries on 429, 5xx and network errors. `0` turns retries off.
+      # @param timeout [Integer, Float] timeout in seconds for the default transport.
+      # @param logger [Logger, nil] gets one debug line per request.
+      # @param sleeper [#call] called with the seconds to wait between retries.
+      # @param transport [#call] takes `(request, uri)` and returns a response. Replaced in tests.
+      def initialize(access_token:, retries: 3, timeout: 30, logger: nil, sleeper: Kernel.method(:sleep),
+                     transport: NetHttpTransport.new(timeout: timeout))
+        @headers = HEADERS.merge("Authorization" => "Bearer #{access_token}")
+        @retrier = Retrier.new(retries: retries, sleeper: sleeper)
+        @logger = logger
+        @transport = transport
+      end
+
+      # Hides the token.
+      # @return [String]
+      def inspect = "#<#{self.class} base_url=#{BASE_URL}>"
+
+      # Sends a GET request.
+      #
+      # @param path [String] must start with a single `/`.
+      # @param params [Hash] query parameters. Nil values are dropped.
+      # @return [Hash] parsed JSON body. `{}` for an empty body.
+      # @raise [ArgumentError] when `path` does not start with a single `/`.
+      # @raise [ApiError] on a non-2xx response, or when a 2xx body is not JSON.
+      # @raise [ConnectionError] on a network failure after all retries.
+      def get(path, params = {})
+        perform(build_request(Net::HTTP::Get, path, params))
+      end
+
+      # Sends a POST request with a JSON body.
+      #
+      # @param path [String] must start with a single `/`.
+      # @param body [Hash] sent as JSON.
+      # @return [Hash] parsed JSON body. `{}` for an empty body.
+      # @raise [ArgumentError] when `path` does not start with a single `/`.
+      # @raise [ApiError] on a non-2xx response, or when a 2xx body is not JSON.
+      # @raise [ConnectionError] on a network failure after all retries.
+      def post(path, body = {})
+        request = build_request(Net::HTTP::Post, path)
+        request.body = JSON.generate(body)
+        perform(request)
+      end
+
+      private
+
+      def build_request(klass, path, params = {})
+        raise ArgumentError, "path must start with a single /: #{path.inspect}" unless path.match?(%r{\A/(?!/)})
+
+        uri = URI("#{BASE_URL}#{path}")
+        query = params.compact
+        uri.query = URI.encode_www_form(query) unless query.empty?
+        klass.new(uri, @headers)
+      end
+
+      def perform(request)
+        @retrier.run { attempt_request(request) }
+      end
+
+      def attempt_request(request)
+        response = transport_call(request)
+        code = response.code
+        @logger&.debug("#{request.method} #{request.uri} -> #{code}")
+        raise ApiError.from_response(response) unless code.start_with?("2")
+
+        parse_json(response.body.to_s, code.to_i)
+      end
+
+      def transport_call(request)
+        @transport.call(request, request.uri)
+      rescue *RETRYABLE_EXCEPTIONS => error
+        raise ConnectionError, "#{error.class}: #{error.message}"
+      end
+
+      def parse_json(text, status)
+        text.strip.empty? ? {} : JSON.parse(text)
+      rescue JSON::ParserError
+        raise ApiError.new("invalid JSON in response body", status: status)
+      end
+    end
+  end
+end

data/lib/linkedin/member_data/domains.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module LinkedIn
+  module MemberData
+    # Snapshot domains documented at
+    # https://learn.microsoft.com/en-us/linkedin/dma/member-data-portability/shared/snapshot-domain
+    # The API is case sensitive. Strings are sent as given; symbols are upcased.
+    module Domains
+      # Names of all snapshot domains. Pass one to `Client#snapshot`.
+      # @return [Array<String>]
+      ALL = %w[
+        ADS_CLICKED MEMBER_FOLLOWING LOGIN RICH_MEDIA SEARCHES INFERENCE_TAKEOUT
+        ALL_COMMENTS CONTACTS EVENTS RECEIPTS AD_TARGETING REGISTRATION REVIEWS
+        ARTICLES PATENTS GROUPS COMPANY_FOLLOWS INVITATIONS PHONE_NUMBERS
+        CONNECTIONS EMAIL_ADDRESSES JOB_POSTINGS JOB_APPLICATIONS
+        JOB_SEEKER_PREFERENCES LEARNING INBOX SAVED_JOBS SAVED_JOB_ALERTS PROFILE
+        SKILLS POSITIONS EDUCATION TEST_SCORES CAUSES_YOU_CARE_ABOUT PUBLICATIONS
+        PROJECTS ORGANIZATIONS LANGUAGES HONORS COURSES CERTIFICATIONS
+        RECOMMENDATIONS ENDORSEMENTS MEMBER_SHARE_INFO SECURITY_CHALLENGE_PIPE
+        TRUSTED_GRAPH MARKETPLACE_ENGAGEMENTS MARKETPLACE_PROVIDERS
+        MARKETPLACE_OPPORTUNITIES ACTOR_SAVE_ITEM JOB_APPLICANT_SAVED_ANSWERS
+        TALENT_QUESTION_SAVED_RESPONSE PROFILE_SUMMARY ALL_LIKES ALL_VOTES
+        RECEIPTS_LBP EASYAPPLY_BLOCKING LEARNING_COACH_AI_TAKEOUT
+        LEARNING_COACH_INBOX LEARNING_ROLEPLAY_INBOX VOLUNTEERING_EXPERIENCES
+        ACCOUNT_HISTORY INSTANT_REPOSTS IDENTITY_CREDENTIALS_AND_ASSETS ADS_LAN
+        PREMIUM_NOTES
+      ].freeze
+
+      # Turns a domain argument into the name sent to the API.
+      #
+      # @param domain [Symbol, String, nil] a Symbol is upcased. A String is returned as given. `nil` stays `nil`.
+      # @return [String, nil]
+      # @raise [ArgumentError] when `domain` is not a Symbol, a String or nil.
+      def self.normalize(domain)
+        case domain
+        when Symbol then domain.to_s.upcase
+        when nil, String then domain
+        else raise ArgumentError, "domain must be a Symbol or String, got #{domain.class}"
+        end
+      end
+    end
+  end
+end

data/lib/linkedin/member_data/errors.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LinkedIn
+  module MemberData
+    # Base class of every error this gem raises on purpose.
+    class Error < StandardError; end
+
+    # Missing or empty access token.
+    class ConfigurationError < Error; end
+
+    # Network failure after all retries (timeouts, reset connections).
+    class ConnectionError < Error
+      # @return [true] network errors are worth a retry.
+      def retryable? = true
+
+      # @return [nil] there is no Retry-After header, so the backoff decides.
+      def retry_after = nil
+    end
+
+    # Any non-2xx HTTP response, or a 2xx response with a body that is not JSON.
+    # The class depends on the status. See `Unauthorized`, `Forbidden`, `NotFound`,
+    # `VersionError`, `RateLimited` and `ServerError`. Other statuses raise ApiError itself.
+    class ApiError < Error
+      # Details of the failed response.
+      # `status` is the HTTP status code (Integer).
+      # `code` is `serviceErrorCode` or `code` from the body (Integer or String, nil when the body has neither).
+      # `body` is the parsed JSON body (nil when the body is empty, not JSON, or not an object).
+      # @return [Integer, String, Hash, nil] `status`, `code` or `body`.
+      attr_reader :status, :code, :body
+
+      # Builds the error class that fits the response status.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse] a non-2xx response.
+      # @return [ApiError] an instance of the subclass for the status.
+      def self.from_response(response)
+        status = response.code.to_i
+        body = parse_body(response.body)
+        klass = class_for(status)
+        klass.new(message_from(body, status), status: status, code: code_from(body), body: body,
+                                              **klass.extra_options(response))
+      end
+
+      def self.class_for(status)
+        STATUS_CLASSES.fetch(status) { status >= 500 ? ServerError : ApiError }
+      end
+
+      def self.parse_body(raw)
+        return nil if raw.to_s.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def self.message_from(body, status)
+        message = body.to_h["message"]
+        message.is_a?(String) && !message.empty? ? message : "HTTP #{status}"
+      end
+
+      def self.code_from(body) = body && (body["serviceErrorCode"] || body["code"])
+
+      # Internal hook: subclasses add constructor options read from the response.
+      # @api private
+      def self.extra_options(_response) = {}
+
+      private_class_method :class_for, :parse_body, :message_from, :code_from
+
+      # @param message [String] `message` from the body, or "HTTP <status>".
+      # @param status [Integer] HTTP status code.
+      # @param code [Integer, String, nil] error code from the body.
+      # @param body [Hash, nil] parsed response body.
+      def initialize(message, status:, code: nil, body: nil)
+        super(message)
+        @status = status
+        @code = code
+        @body = body
+      end
+
+      # Tells if a retry may help. False for most API errors.
+      # @return [Boolean]
+      def retryable? = false
+
+      # Only RateLimited knows a Retry-After. Others let the backoff decide.
+      # @return [nil]
+      def retry_after = nil
+    end
+
+    # HTTP 401. The token is invalid or expired.
+    class Unauthorized < ApiError; end
+
+    # HTTP 403. The token is not allowed to read this data.
+    class Forbidden < ApiError; end
+
+    # HTTP 404. For snapshots it can mean "No data found for this memberId".
+    class NotFound < ApiError; end
+
+    # HTTP 426. The API version sent by the gem is not supported.
+    class VersionError < ApiError; end
+
+    # HTTP 429. Retryable.
+    class RateLimited < ApiError
+      # Seconds to wait, from the `Retry-After` header.
+      # @return [Integer, nil] `nil` when the header is absent, is not a positive number, or is an HTTP date.
+      attr_reader :retry_after
+
+      # Adds the parsed `Retry-After` header to the constructor options.
+      # @api private
+      def self.extra_options(response) = { retry_after: retry_after_from(response["Retry-After"]) }
+
+      # Only a positive number of seconds counts. HTTP-dates and 0 mean "use backoff".
+      # @api private
+      def self.retry_after_from(value)
+        seconds = value.to_s.match?(/\A\d+\z/) ? value.to_i : 0
+        seconds.positive? ? seconds : nil
+      end
+
+      # @param message [String] error message.
+      # @param status [Integer] HTTP status code.
+      # @param code [Integer, String, nil] error code from the body.
+      # @param body [Hash, nil] parsed response body.
+      # @param retry_after [Integer, nil] seconds from the `Retry-After` header.
+      def initialize(message, status:, code: nil, body: nil, retry_after: nil)
+        super(message, status: status, code: code, body: body)
+        @retry_after = retry_after
+      end
+
+      # @return [true] a rate limit is worth a retry.
+      def retryable? = true
+    end
+
+    # HTTP 5xx. Retryable.
+    class ServerError < ApiError
+      # @return [true] server errors are worth a retry.
+      def retryable? = true
+    end
+
+    # Defined last because the classes must exist first.
+    class ApiError
+      # HTTP status => error class. Other statuses use `ServerError` (5xx) or `ApiError`.
+      # @api private
+      STATUS_CLASSES = {
+        401 => Unauthorized,
+        403 => Forbidden,
+        404 => NotFound,
+        426 => VersionError,
+        429 => RateLimited
+      }.freeze
+    end
+  end
+end

data/lib/linkedin/member_data/event.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module LinkedIn
+  module MemberData
+    # Data member name => JSON key. Time fields are handled separately.
+    # @api private
+    EVENT_KEYS = {
+      id: "id",
+      activity_id: "activityId",
+      activity_status: "activityStatus",
+      config_version: "configVersion",
+      owner: "owner",
+      actor: "actor",
+      resource_name: "resourceName",
+      resource_id: "resourceId",
+      resource_uri: "resourceUri",
+      # Shadows Object#method on purpose; it is the API field name.
+      method: "method",
+      method_name: "methodName",
+      activity: "activity",
+      processed_activity: "processedActivity",
+      sibling_activities: "siblingActivities",
+      parent_sibling_activities: "parentSiblingActivities"
+    }.freeze
+    private_constant :EVENT_KEYS
+
+    # One Member Changelog event. Immutable. Times are UTC. `activity` and friends stay raw.
+    # Fields missing in the API response are `nil`.
+    #
+    # `method` is the API field (`CREATE`, `UPDATE`, ...). It shadows Ruby's `Object#method` on purpose,
+    # so `event.method(:name)` does not work on an Event.
+    #
+    # @!attribute [r] id
+    #   @return [String, nil] event id. Used to skip events seen on the previous page.
+    # @!attribute [r] activity_id
+    #   @return [String, nil] value as sent by the API.
+    # @!attribute [r] activity_status
+    #   @return [String, nil] value as sent by the API.
+    # @!attribute [r] config_version
+    #   @return [Object, nil] value as sent by the API.
+    # @!attribute [r] owner
+    #   @return [String, nil] owner of the event, as sent by the API.
+    # @!attribute [r] actor
+    #   @return [String, nil] who did the action, as sent by the API.
+    # @!attribute [r] resource_name
+    #   @return [String, nil] kind of resource that changed.
+    # @!attribute [r] resource_id
+    #   @return [String, nil] value as sent by the API.
+    # @!attribute [r] resource_uri
+    #   @return [String, nil] value as sent by the API.
+    # @!attribute [r] method
+    #   @return [String, nil] API method, for example `CREATE` or `UPDATE`.
+    # @!attribute [r] method_name
+    #   @return [String, nil] value as sent by the API.
+    # @!attribute [r] captured_at
+    #   @return [Time, nil] when LinkedIn captured the event. UTC.
+    # @!attribute [r] processed_at
+    #   @return [Time, nil] when LinkedIn processed the event. UTC. Used as the cursor.
+    # @!attribute [r] activity
+    #   @return [Hash, nil] raw activity payload.
+    # @!attribute [r] processed_activity
+    #   @return [Hash, nil] raw processed activity payload.
+    # @!attribute [r] sibling_activities
+    #   @return [Array<Hash>, nil] raw sibling activities.
+    # @!attribute [r] parent_sibling_activities
+    #   @return [Array<Hash>, nil] raw parent sibling activities.
+    # @!attribute [r] raw
+    #   @return [Hash] the original event Hash from the API.
+    Event = Data.define(
+      *EVENT_KEYS.keys, :captured_at, :processed_at, :raw
+    ) do
+      # Builds an event from one element of the API response.
+      #
+      # @example
+      #   event = LinkedIn::MemberData::Event.from_api(
+      #     "id" => "1", "method" => "CREATE", "processedAt" => 1_788_000_000_000
+      #   )
+      #   event.method        # => "CREATE"
+      #   event.processed_at  # => 2026-08-29 10:40:00 UTC
+      #   event.processed_at_ms # => 1788000000000
+      # @param hash [Hash] one element of `elements` from the changelog response.
+      # @return [Event]
+      def self.from_api(hash)
+        attributes = EVENT_KEYS.transform_values { |key| hash[key] }
+        new(**attributes, **times_from(hash), raw: hash)
+      end
+
+      def self.times_from(hash)
+        { captured_at: Util.time_from_ms(hash["capturedAt"]),
+          processed_at: Util.time_from_ms(hash["processedAt"]) }
+      end
+      private_class_method :times_from
+
+      # Raw epoch milliseconds, used as the next `startTime` cursor.
+      # Pass it as `since:` to `Client#changelog` to resume.
+      #
+      # @return [Integer, nil] `nil` when the event has no `processedAt`.
+      def processed_at_ms = raw["processedAt"]
+    end
+  end
+end

data/lib/linkedin/member_data/snapshot/page.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module LinkedIn
+  module MemberData
+    class Snapshot
+      # One response page of snapshot data. Immutable.
+      #
+      # @!attribute [r] domain
+      #   @return [String, nil] `snapshotDomain` of the first element. An all-domains call may return several.
+      # @!attribute [r] rows
+      #   @return [Array<Hash{String => Object}>] rows of every element on this page. Keys differ per domain.
+      # @!attribute [r] start
+      #   @return [Integer, nil] page index from the `paging` object.
+      # @!attribute [r] count
+      #   @return [Integer, nil] page size from the `paging` object.
+      # @!attribute [r] total
+      #   @return [Integer, nil] total number of items from the `paging` object.
+      # @!attribute [r] has_next
+      #   @return [Boolean] true when `paging.links` has a link with rel `next`.
+      # @!attribute [r] raw
+      #   @return [Hash] the parsed response body.
+      Page = Data.define(:domain, :rows, :start, :count, :total, :has_next, :raw) do
+        # Builds a page from a parsed response body. Missing keys give empty or nil values.
+        #
+        # @param raw [Hash] parsed JSON body of the API response.
+        # @return [Snapshot::Page]
+        def self.from_api(raw)
+          elements = raw.fetch("elements", [])
+          # domain comes from the first element; an all-domains call may return several
+          new(domain: elements.dig(0, "snapshotDomain"), rows: rows_from(elements), raw: raw,
+              **paging_from(raw.fetch("paging", {})))
+        end
+
+        def self.rows_from(elements)
+          elements.flat_map { |element| element.fetch("snapshotData", []) }
+        end
+
+        def self.paging_from(paging)
+          { start: paging["start"], count: paging["count"], total: paging["total"],
+            has_next: paging.fetch("links", []).any? { |link| link["rel"] == "next" } }
+        end
+
+        private_class_method :rows_from, :paging_from
+
+        # Tells if another page may follow. Same value as `#has_next`.
+        # The last page can still carry a `next` link, so an empty next page is possible.
+        #
+        # @return [Boolean]
+        def next? = has_next
+      end
+    end
+  end
+end