calmlens 0.1.0

data/lib/calmlens/error_codes.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# Generated by packages/sdk-contract/generate.ts from packages/shared/src/PublicErrorCodes.ts.
+# Do not edit by hand: run `bun packages/sdk-contract/generate.ts`.
+module CalmLens
+  # Error codes the CalmLens API returns, for comparing with {Error#code}.
+  module ErrorCodes
+    INVALID_CURSOR = 'validation/invalid-cursor'
+    MISSING_TOKEN = 'auth/missing-token'
+    INVALID_API_KEY = 'auth/invalid-api-key'
+    API_KEY_PROJECT_MISMATCH = 'auth/project-mismatch'
+    API_KEY_NOT_ACCEPTED = 'auth/api-key-not-accepted'
+    FILE_TOO_LARGE = 'upload/file-too-large'
+    IMAGE_REQUIRES_MULTIPART_UPLOAD = 'upload/image-requires-multipart-upload'
+    MULTIPART_IMAGE_TOO_SMALL = 'upload/multipart-image-too-small'
+    MULTIPART_IMAGE_TOO_LARGE = 'upload/multipart-image-too-large'
+    IMAGE_EXCEEDED_MAX_DIMENSIONS = 'upload/image-exceeded-max-dimensions'
+    UPLOAD_LIMIT_EXCEEDED = 'upload/limit-exceeded'
+    SPEND_LIMIT_REACHED = 'upload/spend-limit-reached'
+    INVALID_UPLOAD_MIME_TYPE = 'upload/invalid-mime-type'
+    INVALID_EVENT_CURSOR = 'events/invalid-cursor'
+    INVALID_UPLOAD_PAYLOAD = 'upload/invalid-payload'
+    USE_UPLOAD_PART = 'upload/use-upload-part'
+    UPLOAD_NOT_OPEN = 'upload/not-open'
+    INVALID_UPLOAD_PART_NUMBER = 'upload/invalid-part-number'
+    UPLOAD_MISSING = 'upload/missing'
+    UPLOAD_SIZE_MISMATCH = 'upload/size-mismatch'
+    INVALID_IDEMPOTENCY_KEY = 'idempotency/invalid-key'
+    IDEMPOTENCY_KEY_REUSED = 'idempotency/key-reused'
+    IDEMPOTENT_REQUEST_IN_PROGRESS = 'idempotency/request-in-progress'
+    ASSET_NOT_FOUND = 'asset/not-found'
+    PROJECT_NOT_FOUND = 'project/not-found'
+    ASSET_UPDATE_FAILED = 'asset/update-failed'
+    ASSET_SAFETY_HELD = 'asset/safety-held'
+    ASSET_NOT_RETRYABLE = 'asset/not-retryable'
+    ASSET_CONTENT_UNAVAILABLE = 'asset/content-unavailable'
+    SUPPORT_TICKET_NOT_FOUND = 'support/ticket-not-found'
+    DUPLICATE_EXTERNAL_ID = 'asset/duplicate-external-id'
+    FOLDER_NOT_FOUND = 'folder/not-found'
+    DUPLICATE_FOLDER_NAME = 'folder/duplicate-name'
+    FOLDER_NOT_EMPTY = 'folder/not-empty'
+    FOLDER_PARENT_CYCLE = 'folder/parent-cycle'
+    LENS_VERSION_CONFLICT = 'lens/version-conflict'
+    UPLOAD_PRESET_NOT_FOUND = 'upload-preset/not-found'
+    UPLOAD_PRESET_DISABLED = 'upload-preset/disabled'
+    UPLOAD_PRESET_TOKEN_REQUIRED = 'upload-preset/token-required'
+    REMOTE_URL_NOT_ALLOWED = 'upload/remote-url-not-allowed'
+    WEBSITE_RATE_LIMIT_EXCEEDED = 'upload/website-rate-limit-exceeded'
+    UPLOAD_PRESET_CONTENT_TYPE_NOT_ALLOWED = 'upload-preset/content-type-not-allowed'
+    UPLOAD_PRESET_TOO_LARGE = 'upload-preset/too-large'
+    UPLOAD_PRESET_DAILY_LIMIT_REACHED = 'upload-preset/daily-limit-reached'
+    UPLOAD_PRESET_ORIGIN_NOT_ALLOWED = 'upload-preset/origin-not-allowed'
+    UPLOAD_PRESET_FIELD_NOT_ALLOWED = 'upload-preset/field-not-allowed'
+    UPLOAD_TOKEN_INVALID = 'upload-token/invalid'
+    UPLOAD_TOKEN_EXPIRED = 'upload-token/expired'
+    UPLOAD_TOKEN_USED = 'upload-token/used'
+    INVALID_REMOTE_URL = 'asset/invalid-remote-url'
+    REMOTE_URL_UNAVAILABLE = 'asset/remote-url-unavailable'
+    APPEAL_NOT_FOUND = 'appeal/not-found'
+    APPEAL_JUDGMENT_NOT_FOUND = 'appeal/judgment-not-found'
+    APPEAL_ASSET_NOT_FOUND = 'appeal/asset-not-found'
+    APPEAL_PERMISSION_DENIED = 'appeal/permission-denied'
+    APPEAL_ALREADY_REVIEWED = 'appeal/already-reviewed'
+    APPEAL_DECISION_CHANGED = 'appeal/decision-changed'
+    APPEAL_INVALID_ACTION = 'appeal/invalid-action'
+    APPEAL_SAFETY_HELD = 'appeal/safety-held'
+    APPEAL_CONTENT_UNAVAILABLE = 'appeal/content-unavailable'
+
+    # The HTTP status the API returns with each code.
+    STATUSES = {
+      'validation/invalid-cursor' => 400,
+      'auth/missing-token' => 401,
+      'auth/invalid-api-key' => 401,
+      'auth/project-mismatch' => 403,
+      'auth/api-key-not-accepted' => 403,
+      'upload/file-too-large' => 400,
+      'upload/image-requires-multipart-upload' => 400,
+      'upload/multipart-image-too-small' => 400,
+      'upload/multipart-image-too-large' => 400,
+      'upload/image-exceeded-max-dimensions' => 400,
+      'upload/limit-exceeded' => 403,
+      'upload/spend-limit-reached' => 402,
+      'upload/invalid-mime-type' => 400,
+      'events/invalid-cursor' => 400,
+      'upload/invalid-payload' => 400,
+      'upload/use-upload-part' => 409,
+      'upload/not-open' => 409,
+      'upload/invalid-part-number' => 409,
+      'upload/missing' => 409,
+      'upload/size-mismatch' => 400,
+      'idempotency/invalid-key' => 400,
+      'idempotency/key-reused' => 409,
+      'idempotency/request-in-progress' => 409,
+      'asset/not-found' => 404,
+      'project/not-found' => 404,
+      'asset/update-failed' => 500,
+      'asset/safety-held' => 423,
+      'asset/not-retryable' => 409,
+      'asset/content-unavailable' => 409,
+      'support/ticket-not-found' => 404,
+      'asset/duplicate-external-id' => 409,
+      'folder/not-found' => 404,
+      'folder/duplicate-name' => 409,
+      'folder/not-empty' => 409,
+      'folder/parent-cycle' => 409,
+      'lens/version-conflict' => 409,
+      'upload-preset/not-found' => 404,
+      'upload-preset/disabled' => 403,
+      'upload-preset/token-required' => 401,
+      'upload/remote-url-not-allowed' => 403,
+      'upload/website-rate-limit-exceeded' => 429,
+      'upload-preset/content-type-not-allowed' => 415,
+      'upload-preset/too-large' => 413,
+      'upload-preset/daily-limit-reached' => 429,
+      'upload-preset/origin-not-allowed' => 403,
+      'upload-preset/field-not-allowed' => 400,
+      'upload-token/invalid' => 401,
+      'upload-token/expired' => 401,
+      'upload-token/used' => 409,
+      'asset/invalid-remote-url' => 400,
+      'asset/remote-url-unavailable' => 422,
+      'appeal/not-found' => 404,
+      'appeal/judgment-not-found' => 404,
+      'appeal/asset-not-found' => 404,
+      'appeal/permission-denied' => 403,
+      'appeal/already-reviewed' => 409,
+      'appeal/decision-changed' => 409,
+      'appeal/invalid-action' => 400,
+      'appeal/safety-held' => 409,
+      'appeal/content-unavailable' => 409,
+    }.freeze
+  end
+end

data/lib/calmlens/errors.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module CalmLens
+  # Codes for errors the SDK raises itself, before or instead of an API response.
+  module SdkErrorCodes
+    # A method received a missing, malformed or conflicting argument.
+    INVALID_ARGUMENT = 'sdk/invalid-argument'
+    # The client was constructed with an invalid configuration.
+    INVALID_CONFIG = 'sdk/invalid-config'
+    # The connection failed or broke before a complete response arrived.
+    TRANSPORT_ERROR = 'sdk/transport-error'
+    # Connecting, sending or receiving took longer than the configured timeout.
+    TIMEOUT = 'sdk/timeout'
+    # A successful response could not be read (malformed JSON or too large).
+    INVALID_RESPONSE = 'sdk/invalid-response'
+    # A response body was larger than the SDK reads (32 MiB for API responses).
+    RESPONSE_TOO_LARGE = 'sdk/response-too-large'
+    # An error response did not carry a CalmLens error code.
+    HTTP_ERROR = 'sdk/http-error'
+    # A webhook signature or timestamp did not verify.
+    INVALID_WEBHOOK_SIGNATURE = 'sdk/invalid-webhook-signature'
+    # A verified webhook body was not a CalmLens event payload.
+    INVALID_WEBHOOK_PAYLOAD = 'sdk/invalid-webhook-payload'
+  end
+
+  # Base class of every error the SDK raises. Rescue it to handle any CalmLens failure.
+  #
+  # @!attribute [r] code
+  #   @return [String] a stable identifier such as `asset/not-found` or `sdk/timeout`.
+  #     Compare it with {ErrorCodes} or {SdkErrorCodes}, never with the message.
+  # @!attribute [r] details
+  #   @return [Hash{String => Object}] extra API details; API errors include `"network" => true`
+  #     and, when present, `"traceId"`.
+  # @!attribute [r] status
+  #   @return [Integer, nil] the HTTP status, or nil when no response was received.
+  # @!attribute [r] request_id
+  #   @return [String, nil] the `X-Request-Id` response header. Include it when contacting support.
+  # @!attribute [r] headers
+  #   @return [Hash{String => String}] response headers with lowercase names (empty without a response).
+  class Error < StandardError
+    attr_reader :code, :details, :status, :request_id, :headers
+
+    # @param code [String]
+    # @param message [String, nil] defaults to the code.
+    def initialize(code, message = nil, details: {}, status: nil, headers: {}, request_id: nil)
+      super("[calmlens] #{message || code}")
+      @code = code
+      @details = details
+      @status = status
+      @headers = headers.freeze
+      @request_id = request_id || headers['x-request-id']
+    end
+
+    # @return [Float, nil] seconds to wait before retrying, from the `Retry-After` header.
+    def retry_after
+      Error.parse_retry_after(headers['retry-after'])
+    end
+
+    # @return [Boolean] true when the resource does not exist.
+    def not_found?
+      status == 404 || code.end_with?('/not-found')
+    end
+
+    # @return [Boolean] true when repeating the same request may succeed: connection failures,
+    #   timeouts, throttling (429), 502/503/504 and `idempotency/request-in-progress`.
+    #   Repeat a write only with the same idempotency key.
+    def retryable?
+      [429, 502, 503, 504].include?(status) || code == ErrorCodes::IDEMPOTENT_REQUEST_IN_PROGRESS
+    end
+
+    # Builds the most specific error class for a code and HTTP status.
+    # @return [Error]
+    def self.build(code, message = nil, status: nil, **options)
+      klass = if status then APIError.class_for(status)
+              elsif code == SdkErrorCodes::TIMEOUT then TimeoutError
+              elsif code == SdkErrorCodes::TRANSPORT_ERROR then ConnectionError
+              elsif code == SdkErrorCodes::INVALID_RESPONSE then InvalidResponseError
+              elsif code == SdkErrorCodes::INVALID_CONFIG then ConfigurationError
+              else InvalidArgumentError
+              end
+      klass.new(code, message, status: status, **options)
+    end
+
+    # @api private
+    def self.parse_retry_after(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      text = value.to_s.strip
+      return [Float(text), 0.0].max if text.match?(/\A\d+(\.\d+)?\z/)
+
+      [Time.httpdate(text) - Time.now, 0.0].max
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # The API answered with an error status. {#status} is always set.
+  class APIError < Error
+    # @api private
+    def self.class_for(status)
+      case status
+      when 400 then BadRequestError
+      when 401 then AuthenticationError
+      when 403 then PermissionDeniedError
+      when 404 then NotFoundError
+      when 409 then ConflictError
+      when 429 then RateLimitError
+      when 500..599 then ServerError
+      else APIError
+      end
+    end
+  end
+
+  # HTTP 400: the request was rejected as invalid.
+  class BadRequestError < APIError; end
+  # HTTP 401: the API key is missing, invalid, revoked or expired.
+  class AuthenticationError < APIError; end
+  # HTTP 403: the API key may not perform this action.
+  class PermissionDeniedError < APIError; end
+  # HTTP 404: the resource does not exist in this project.
+  class NotFoundError < APIError; end
+  # HTTP 409: the request conflicts with the resource's current state.
+  class ConflictError < APIError; end
+  # HTTP 429: the request was throttled. See {Error#retry_after}.
+  class RateLimitError < APIError; end
+  # HTTP 5xx: CalmLens failed to handle the request.
+  class ServerError < APIError; end
+
+  # No complete response arrived (`sdk/transport-error`). The original exception is in `cause`.
+  class ConnectionError < Error
+    def retryable? = true
+  end
+
+  # Connecting, sending or receiving exceeded its timeout, or {Assets#wait_for_decision} had no
+  # decision in time (`sdk/timeout`).
+  class TimeoutError < ConnectionError; end
+
+  # A successful response could not be read (`sdk/invalid-response`) or was too large
+  # (`sdk/response-too-large`).
+  class InvalidResponseError < Error; end
+
+  # A method argument was rejected before any request was sent. The code is
+  # `sdk/invalid-argument` or, for upload payload checks shared with the API, an `upload/*` code.
+  class InvalidArgumentError < Error; end
+
+  # The client configuration is invalid (`sdk/invalid-config`).
+  class ConfigurationError < InvalidArgumentError; end
+
+  # A webhook delivery failed verification (`sdk/invalid-webhook-signature`) or was not an
+  # event payload (`sdk/invalid-webhook-payload`). Respond with 400 and do not process it.
+  class WebhookVerificationError < Error; end
+end

data/lib/calmlens/events.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # The project's events feed. Reach it through {ServerClient#events}.
+  class Events < Resource
+    # Lists events after a cursor, oldest first. Without `after`, returns no events and a cursor
+    # for the current time: save it, then pass each response's `cursor` as `after`.
+    # @option options [String] :after a cursor from a previous response
+    # @option options [Integer] :limit default 50
+    # @return [Hash] `{'events', 'cursor', 'hasMore'}`
+    def list(options = {})
+      call(options) { |api, request| request('GET', project('events'), query: api, request_options: request) }
+    end
+
+    # Iterates pages from `after` until `hasMore` is false. Persist each page's `cursor` once its
+    # events are handled, and resume from it later.
+    # @yieldparam page [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each_page(options = {})
+      return enum_for(:each_page, options) unless block_given?
+
+      api, request = call(options) { |*split| split }
+      loop do
+        page = list(api.merge('request_options' => request))
+        unless page.is_a?(Hash) && page['events'].is_a?(Array) && page['cursor'].is_a?(String)
+          raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Events page has no events or cursor')
+        end
+
+        yield page
+        break unless page['hasMore'] == true
+
+        api = api.merge('after' => page['cursor'])
+      end
+      nil
+    end
+
+    # Iterates the events after `after`, across pages. See {#each_page} to track the cursor.
+    # @yieldparam event [Hash]
+    # @return [Enumerator, nil] an Enumerator when no block is given.
+    def each(options = {}, &block)
+      return enum_for(:each, options) unless block
+
+      each_page(options) { |page| page['events'].each(&block) }
+    end
+  end
+end

data/lib/calmlens/folders.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # Folders organise a project's assets. Reach it through {ServerClient#folders}.
+  class Folders < Resource
+    # @return [Array<Hash>] every folder in the project.
+    def list(options = {})
+      call(options) do |_api, request|
+        response = request('GET', project('folders'), request_options: request)
+        folders = response.is_a?(Hash) ? response['folders'] : nil
+        raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Folder list has no folders') unless folders.is_a?(Array)
+
+        folders
+      end
+    end
+
+    # @option options [String] :name
+    # @option options [String, nil] :parent_id
+    # @return [Hash] the folder
+    def create(options)
+      call(options) { |api, request| request('POST', project('folders'), body: api, request_options: request) }
+    end
+
+    # @option options [String] :folder_id
+    # @return [Hash] the folder
+    def retrieve(options)
+      call(options) do |api, request|
+        request('GET', "/folders/#{Internal.segment(api['folderId'])}", request_options: request)
+      end
+    end
+
+    # @option options [String] :folder_id
+    # @option options [String] :name
+    # @return [Hash] the folder
+    def update(options)
+      call(options) do |api, request|
+        request('PATCH', "/folders/#{Internal.segment(api['folderId'])}", body: without(api, 'folderId'),
+                                                                          request_options: request)
+      end
+    end
+
+    # Moves a folder under another, or to the root with `parent_id: nil`.
+    # @option options [String] :folder_id
+    # @option options [String, nil] :parent_id
+    # @return [Hash] the folder
+    def move(options)
+      call(options) do |api, request|
+        request('POST', "/folders/#{Internal.segment(api['folderId'])}/move",
+                body: { 'parentId' => Internal.required(api, 'parentId') }, request_options: request)
+      end
+    end
+
+    # Deletes an empty folder.
+    # @option options [String] :folder_id
+    # @return [nil]
+    def delete(options)
+      call(options) do |api, request|
+        request('DELETE', "/folders/#{Internal.segment(api['folderId'])}", request_options: request)
+        nil
+      end
+    end
+  end
+end

data/lib/calmlens/internal.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module CalmLens
+  # Option conversion, identifier encoding and argument checks shared by the resources.
+  # @api private
+  module Internal
+    # Per-call settings accepted under the `request_options:` option of any method.
+    REQUEST_OPTIONS = %i[idempotency_key timeout open_timeout max_retries].freeze
+    IDEMPOTENCY_KEY = /\A[\x21-\x7e]{1,255}\z/
+    HEADER_VALUE = /\A[^\r\n\0]*\z/
+
+    module_function
+
+    # @return [InvalidArgumentError]
+    def invalid(message, code = SdkErrorCodes::INVALID_ARGUMENT)
+      InvalidArgumentError.new(code, message)
+    end
+
+    # Converts one snake_case option name to the API's camelCase. camelCase names are unchanged.
+    def camelize(key)
+      key.to_s.gsub(/_+([a-z0-9])/i) { Regexp.last_match(1).upcase }
+    end
+
+    # Converts every Hash key to camelCase strings, except inside `metadata`, whose keys are yours.
+    def normalize(value)
+      case value
+      when Hash
+        value.to_h do |key, item|
+          name = camelize(key)
+          [name, name == 'metadata' ? item : normalize(item)]
+        end
+      when Array then value.map { |item| normalize(item) }
+      else value
+      end
+    end
+
+    # Splits a method's options into API options (camelCase strings) and per-call request options.
+    # @return [Array(Hash, Hash)]
+    def options(value)
+      value = {} if value.nil?
+      raise invalid("Options must be a Hash, got #{value.class}") unless value.is_a?(Hash)
+
+      request = value.find { |key, _| %w[request_options requestOptions].include?(key.to_s) }&.last || {}
+      raise invalid('request_options must be a Hash') unless request.is_a?(Hash)
+
+      request = request.to_h { |key, item| [key.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym, item] }
+      unknown = request.keys - REQUEST_OPTIONS
+      raise invalid("Unknown request option: #{unknown.join(', ')}") unless unknown.empty?
+
+      check_request_options(request)
+      api = value.reject { |key, _| %w[request_options requestOptions].include?(key.to_s) }
+      [normalize(api), request]
+    end
+
+    def check_request_options(request)
+      key = request[:idempotency_key]
+      if !key.nil? && !(key.is_a?(String) && key.match?(IDEMPOTENCY_KEY))
+        raise invalid('idempotency_key must be 1 to 255 printable ASCII characters')
+      end
+
+      %i[timeout open_timeout].each do |name|
+        next if request[name].nil? || positive?(request[name])
+
+        raise invalid("#{name} must be a positive number of seconds")
+      end
+      retries = request[:max_retries]
+      raise invalid('max_retries must be a non-negative Integer') unless retries.nil? || (retries.is_a?(Integer) && retries >= 0)
+    end
+
+    def positive?(value)
+      value.is_a?(Numeric) && value.real? && value.to_f.finite? && value.positive?
+    end
+
+    # Fetches a required option.
+    def required(options, key, code = SdkErrorCodes::INVALID_ARGUMENT)
+      raise invalid("#{key} is required", code) unless options.key?(key)
+
+      options[key]
+    end
+
+    # Encodes an identifier as one path segment. "." and ".." are rejected because URL resolution
+    # treats them as relative segments, which would reach another route.
+    def segment(value)
+      text = value.to_s
+      raise invalid('Identifier is required') if text.empty?
+      raise invalid('Identifier cannot be "." or ".."') if %w[. ..].include?(text)
+
+      URI.encode_www_form_component(text).gsub('+', '%20')
+    end
+
+    # Splits an absolute URL into its parsed origin and its raw request target. URI rejects the
+    # literal brackets CDN transform selectors keep, so only the origin is parsed.
+    # @return [Array(URI::Generic, String)]
+    def split_url(url)
+      match = %r{\A([A-Za-z][A-Za-z0-9+.-]*://[^/?#]*)([^#]*)}.match(url.to_s)
+      raise URI::InvalidURIError, "Invalid URL: #{url}" unless match && match[2].match?(/\A[!-~]*\z/)
+
+      target = match[2]
+      target = "/#{target}" unless target.start_with?('/')
+      [URI(match[1]), target]
+    end
+
+    # Checks caller-supplied HTTP headers: names and values must be strings without line breaks.
+    def headers(value)
+      raise invalid('headers must be a Hash') unless value.is_a?(Hash)
+
+      value.to_h do |name, item|
+        name = name.to_s
+        unless name.match?(/\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/) && item.is_a?(String) && item.match?(HEADER_VALUE)
+          raise invalid("Invalid header #{name.inspect}: names are tokens and values are single-line strings")
+        end
+
+        [name, item]
+      end
+    end
+
+    # Encodes query values the way the API's parser expects: strings as-is, everything else as
+    # JSON, and ordering as `ordering[i][field]` pairs.
+    def query(params)
+      encoded = {}
+      params.each do |key, value|
+        next if value.nil?
+
+        if key == 'ordering' && value.is_a?(Array)
+          value.each_with_index do |order, index|
+            raise invalid('Each ordering entry must be a Hash') unless order.is_a?(Hash)
+
+            order.each { |name, item| encoded["ordering[#{index}][#{name}]"] = item.to_s }
+          end
+        else
+          encoded[key] = value.is_a?(String) ? value : JSON.generate(value)
+        end
+      end
+      encoded
+    end
+  end
+  private_constant :Internal
+end

data/lib/calmlens/lenses.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CalmLens
+  # Lens definitions, cached per client. Used through {ServerClient#ensure_lenses} and {ServerClient#ensure_lens}.
+  # @api private
+  class Lenses < Resource
+    def ensure_lenses(options)
+      call(options) { |api, request| @session.ensure_lenses(api['lenses'], request) }
+    end
+
+    def ensure_lens(options)
+      call(options) { |api, request| @session.ensure_lenses([api], request).first }
+    end
+  end
+  private_constant :Lenses
+end

data/lib/calmlens/resource.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module CalmLens
+  # Shared behaviour of the client's resource objects.
+  class Resource
+    # @api private
+    def initialize(session)
+      @session = session
+    end
+
+    def inspect = "#<#{self.class.name} project_id=#{@session.project_id.inspect}>"
+
+    private
+
+    # Runs a public method: splits options, and raises every argument problem as {InvalidArgumentError}.
+    def call(options)
+      api, request = Internal.options(options)
+      yield api, request
+    rescue Error
+      raise
+    rescue KeyError, TypeError, ArgumentError, JSON::GeneratorError, EncodingError, URI::Error, FloatDomainError => e
+      raise InvalidArgumentError.new(SdkErrorCodes::INVALID_ARGUMENT, e.message), cause: e
+    end
+
+    def request(...) = @session.request(...)
+    def project(path) = @session.project(path)
+
+    def without(options, *keys) = options.except(*keys)
+
+    # Fetches numbered pages lazily, from `start` until `hasMore` is false.
+    def pages(start, &fetch)
+      Enumerator.new do |out|
+        index = start
+        loop do
+          page = fetch.call(index)
+          items = page.is_a?(Hash) ? page['items'] : nil
+          raise InvalidResponseError.new(SdkErrorCodes::INVALID_RESPONSE, 'Page has no items') unless items.is_a?(Array)
+
+          out << page
+          break unless page['hasMore'] == true && !items.empty?
+
+          index = page['nextCursor']
+          break unless index
+        end
+      end
+    end
+  end
+end