overturo 0.7.2

data/lib/overturo/http_client.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module Overturo
+  class HttpClient
+    RETRY_SLEEP_BASE = 0.5
+
+    attr_reader :last_request_id
+
+    def initialize(config)
+      @config = config
+    end
+
+    def get(path, params: {}, headers: {})
+      request(:get, path, params: params, extra_request_headers: headers)
+    end
+
+    def post(path, body: {}, idempotency_key: nil)
+      request(:post, path, body: body, idempotency_key: idempotency_key)
+    end
+
+    def patch(path, body: {}, idempotency_key: nil)
+      request(:patch, path, body: body, idempotency_key: idempotency_key)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def request(method, path, params: {}, body: nil, idempotency_key: nil, extra_request_headers: {})
+      uri = build_uri(path, params)
+      request_id = generate_request_id
+      retries = 0
+
+      begin
+        response = execute_request(method, uri, body, request_id: request_id, idempotency_key: idempotency_key,
+                                                      extra_request_headers: extra_request_headers)
+        handle_response(response)
+      rescue RateLimitError, ApiError, ConnectionError, TimeoutError => e
+        if retries < @config.max_retries && retryable?(e)
+          retries += 1
+          sleep_time = RETRY_SLEEP_BASE * (2**(retries - 1))
+          log(:warn, "Retrying request #{request_id} (attempt #{retries}/#{@config.max_retries}) after #{sleep_time}s")
+          sleep(sleep_time)
+          retry
+        end
+        raise
+      end
+    end
+
+    def execute_request(method, uri, body, request_id: nil, idempotency_key: nil, extra_request_headers: {})
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.read_timeout
+      http.write_timeout = @config.write_timeout
+
+      req = build_request(method, uri, body, request_id: request_id, idempotency_key: idempotency_key,
+                                             extra_request_headers: extra_request_headers)
+      log(:debug, "[#{request_id}] #{method.upcase} #{uri.path}")
+      http.request(req)
+    rescue ::Timeout::Error, Errno::ETIMEDOUT => e
+      raise Overturo::TimeoutError, "Request timed out: #{e.message}"
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+           Errno::ENETUNREACH, SocketError, EOFError => e
+      raise Overturo::ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    def build_request(method, uri, body, request_id: nil, idempotency_key: nil, extra_request_headers: {})
+      klass = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      extra_headers = {}
+      extra_headers["X-Request-ID"] = request_id if request_id
+      extra_headers["Idempotency-Key"] = idempotency_key if idempotency_key
+      # 189 — caller-supplied per-request headers (e.g. the discovery resource's
+      # X-Publishable-Key). Merged last so an explicit header wins.
+      extra_headers.merge!(extra_request_headers) if extra_request_headers && !extra_request_headers.empty?
+
+      req = klass.new(uri.request_uri, headers.merge(extra_headers))
+      req.body = JSON.generate(body) if body && !body.empty?
+      req
+    end
+
+    def build_uri(path, params)
+      # chomp a trailing slash so a base_url like "https://x.com/" doesn't produce
+      # "https://x.com//api/..." (some gateways 404 the double slash).
+      url = "#{@config.base_url.to_s.chomp("/")}/api/#{@config.api_version}#{path}"
+      uri = URI.parse(url)
+      uri.query = URI.encode_www_form(params) if params && !params.empty?
+      uri
+    end
+
+    def headers
+      {
+        "Authorization" => "Bearer #{@config.api_key}",
+        "Content-Type" => "application/json",
+        "Accept" => "application/json",
+        "User-Agent" => "overturo-ruby/#{Overturo::VERSION}"
+      }
+    end
+
+    def handle_response(response)
+      @last_response_request_id = response["X-Request-ID"]
+      status = response.code.to_i
+      body = response.body
+      json = parse_json(body)
+
+      return json || {} if status >= 200 && status < 300
+
+      message = error_message(json, body)
+      error_class = ERROR_MAP[status] || (status >= 500 ? ApiError : Error)
+
+      raise error_class.new(
+        message.to_s,
+        http_status: status,
+        http_body: body,
+        json_body: json
+      )
+    end
+
+    # `{error: {code, message}}` reads as "code: message"; a string error or a
+    # non-JSON body is passed through.
+    def error_message(json, body)
+      return body unless json.is_a?(Hash)
+
+      error = json["error"]
+      return [error["code"], error["message"]].compact.join(": ") if error.is_a?(Hash)
+
+      error || body
+    end
+
+    def parse_json(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def retryable?(error)
+      error.is_a?(RateLimitError) || error.is_a?(ApiError) ||
+        error.is_a?(ConnectionError) || error.is_a?(TimeoutError)
+    end
+
+    def generate_request_id
+      @last_request_id = "req_#{SecureRandom.hex(12)}"
+    end
+
+    def log(level, message)
+      return unless @config.logger
+
+      @config.logger.send(level, "[Overturo] #{message}")
+    end
+  end
+end

data/lib/overturo/list_object.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Overturo
+  class ListObject
+    include Enumerable
+
+    attr_reader :data, :pagination
+
+    def initialize(data:, pagination:, http_client: nil, resource_path: nil, list_key: nil, params: {})
+      @data = data
+      @pagination = pagination
+      @http_client = http_client
+      @resource_path = resource_path
+      @list_key = list_key
+      @params = params
+    end
+
+    def each(&)
+      @data.each(&)
+    end
+
+    def more?
+      return false unless pagination
+
+      page_value(:page, 1) * page_value(:per_page, 25) < page_value(:total, 0)
+    end
+
+    alias has_more? more?
+
+    def auto_paging_each(&block)
+      return enum_for(:auto_paging_each) unless block_given?
+
+      @data.each(&block)
+      return unless @http_client && @resource_path && @list_key
+
+      current_params = @params.dup
+      current_page = page_value(:page, 1)
+
+      while pages_remaining?(current_page)
+        current_page += 1
+        current_params[:page] = current_page
+        response = @http_client.get(@resource_path, params: current_params)
+        items = response[@list_key] || []
+        items.each do |item|
+          block.call(item.is_a?(OverturoObject) ? item : OverturoObject.new(item))
+        end
+        @pagination = response["pagination"] || {}
+      end
+    end
+
+    def empty?
+      @data.empty?
+    end
+
+    def size
+      @data.size
+    end
+
+    alias length size
+
+    private
+
+    def page_value(key, default)
+      return default unless pagination
+
+      pagination[key.to_s] || pagination[key.to_sym] || default
+    end
+
+    def pages_remaining?(current_page)
+      current_page * page_value(:per_page, 25) < page_value(:total, 0)
+    end
+  end
+end

data/lib/overturo/overturo_object.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Overturo
+  class OverturoObject
+    def initialize(data = {})
+      @data = {}
+      data.each { |k, v| @data[k.to_s] = wrap_value(v) }
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    def []=(key, value)
+      @data[key.to_s] = wrap_value(value)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @data.key?(method_name.to_s) || super
+    end
+
+    def method_missing(method_name, *args)
+      key = method_name.to_s
+      if @data.key?(key)
+        @data[key]
+      else
+        super
+      end
+    end
+
+    def to_h
+      @data.transform_values { |v| unwrap_value(v) }
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def to_s
+      "#<#{self.class} #{@data.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}>"
+    end
+
+    def inspect
+      to_s
+    end
+
+    def key?(key)
+      @data.key?(key.to_s)
+    end
+
+    def keys
+      @data.keys
+    end
+
+    def values
+      @data.values
+    end
+
+    def each(&)
+      @data.each(&)
+    end
+
+    private
+
+    def wrap_value(value)
+      case value
+      when Hash
+        OverturoObject.new(value)
+      when Array
+        value.map { |v| wrap_value(v) }
+      else
+        value
+      end
+    end
+
+    def unwrap_value(value)
+      case value
+      when OverturoObject
+        value.to_h
+      when Array
+        value.map { |v| unwrap_value(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/overturo/resources/agree/agreements.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Agree
+      class Agreements < ApiResource
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/agreements"
+        OBJECT_KEY = "agreement"
+        LIST_KEY = "agreements"
+
+        collection_action :propose, method: :post
+        custom_action :counter, method: :post
+        custom_action :accept, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/agree/collaborations.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Agree
+      class Collaborations < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/collaborations"
+        OBJECT_KEY = "collaboration"
+        LIST_KEY = "collaborations"
+
+        custom_action :invite, method: :post, returns: :raw
+        custom_action :sign, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/agree/quorum_requests.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Agree
+      # M-of-N quorum authorization on Agreement actions ("collective
+      # guardianship" per the Agree surface). Lives at /api/v1/quorum_requests;
+      # /api/v1/decisions is the separate decisions API.
+      class QuorumRequests < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/quorum_requests"
+        OBJECT_KEY = "quorum_request"
+        LIST_KEY = "quorum_requests"
+
+        custom_action :vote, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/comply/anchors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Comply
+      class Anchors < ApiResource
+        include ApiOperations::Retrieve
+
+        RESOURCE_PATH = "/anchors"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :get, "<resource>/{id}/receipts"
+        OBJECT_KEY = "anchor"
+        LIST_KEY = "anchors"
+
+        custom_action :export, method: :get, returns: :raw
+
+        def receipts(id, params = {})
+          receipts_path = "#{resource_path}/#{id}/receipts"
+          response = http_client.get(receipts_path, params: params)
+          unwrap_list(response, path: receipts_path, key: "receipts", params: params)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/comply/clean_rooms.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Comply
+      class CleanRooms < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Delete
+
+        RESOURCE_PATH = "/clean_rooms"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :post, "<resource>/{id}/queries"
+        declare_endpoint :get, "<resource>/{id}/queries"
+        declare_endpoint :get, "<resource>/{id}/queries/{query_id}"
+        OBJECT_KEY = "clean_room"
+        LIST_KEY = "clean_rooms"
+
+        custom_action :approve, method: :post
+
+        # Compute-to-data. Run a query inside the
+        # clean room and read its result. The result carries its privacy
+        # parameters (`k_anonymity_met`, `noise_parameters`) and a first-class
+        # `suppressed` flag + `suppression_reason`: a full k-anonymity
+        # suppression is surfaced honestly, never returned as a silent empty.
+        def run_query(id, params = {})
+          path = "#{resource_path}/#{id}/queries"
+          OverturoObject.new(http_client.post(path, body: params))
+        end
+
+        # GET /clean_rooms/:id/queries — list prior compute-to-data queries.
+        def queries(id, params = {})
+          path = "#{resource_path}/#{id}/queries"
+          unwrap_list(http_client.get(path, params: params), path: path, key: "queries", params: params)
+        end
+
+        # GET /clean_rooms/:id/queries/:query_id — read a single query result.
+        def query(id, query_id, params = {})
+          path = "#{resource_path}/#{id}/queries/#{query_id}"
+          OverturoObject.new(http_client.get(path, params: params))
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/comply/evidence_packages.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Comply
+      class EvidencePackages < ApiResource
+        include ApiOperations::Retrieve
+
+        RESOURCE_PATH = "/evidence_packages"
+        OBJECT_KEY = "evidence_package"
+        LIST_KEY = "evidence_packages"
+      end
+    end
+  end
+end

data/lib/overturo/resources/comply/residency_posture.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Comply
+      # Read your residency posture: a per-country map of
+      # where your subjects' data is stored, the disclosure ledger, and an
+      # assurance status. Export a signed Proof of Residency. Singleton (no id).
+      class ResidencyPosture < ApiResource
+        RESOURCE_PATH = "/residency_posture"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :get, "<resource>"
+        declare_endpoint :post, "<resource>/evidence_package"
+        OBJECT_KEY = "residency_posture"
+
+        # GET /residency_posture — the per-country posture + assurance status.
+        def get(params = {})
+          response = http_client.get(resource_path, params: params)
+          OverturoObject.new(response)
+        end
+
+        # POST /residency_posture/evidence_package — the signed, anchored Proof
+        # of Residency, on the same verifiable path as the transfer register.
+        def evidence_package(params = {})
+          response = http_client.post("#{resource_path}/evidence_package", body: params)
+          OverturoObject.new(response)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/comply/transfer_register.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Comply
+      # Read the cross-border transfer register and export
+      # its signed, verifiable evidence package. Each entry carries the lawful
+      # basis it relied on, the adequacy verdict, and the country pair. Read and
+      # export only — the SDK never creates a transfer.
+      class TransferRegister < ApiResource
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/transfer_register"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :post, "<resource>/evidence_package"
+        OBJECT_KEY = "transfer"
+        LIST_KEY = "transfers"
+
+        # POST /transfer_register/evidence_package — the signed, anchored,
+        # independently-verifiable evidence package of the register.
+        def evidence_package(params = {})
+          response = http_client.post("#{resource_path}/evidence_package", body: params)
+          OverturoObject.new(response)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/connect/applications.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Connect
+      # Only the `publish` and `unpublish` member actions exist at the top
+      # level. Creating an application happens via the dashboard; per-application
+      # configuration uses the nested `applications/:id/...` resources — see
+      # Connect::Webhooks and Connect::Flows.
+      class Applications < ApiResource
+        RESOURCE_PATH = "/applications"
+        OBJECT_KEY = "application"
+        LIST_KEY = "applications"
+
+        custom_action :publish, method: :post
+        custom_action :unpublish, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/connect/connections.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Connect
+      class Connections < ApiResource
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Delete
+
+        RESOURCE_PATH = "/connections"
+        OBJECT_KEY = "connection"
+        LIST_KEY = "connections"
+
+        custom_action :suspend, method: :post
+        custom_action :unsuspend, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/connect/flows.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Connect
+      # Flows are nested under applications:
+      # /api/v1/applications/:application_id/flows[/:id][/<action>]
+      class Flows < ApiResource
+        include ApiOperations::NestedResource
+
+        RESOURCE_PATH = "/applications"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :post, "<resource>/{application_id}/flows/{id}/activate"
+        declare_endpoint :post, "<resource>/{application_id}/flows/{id}/deprecate"
+        declare_endpoint :post, "<resource>/{application_id}/flows/{id}/archive"
+        declare_endpoint :post, "<resource>/{application_id}/flows/{id}/resolve_preview"
+        OBJECT_KEY = "flow"
+        LIST_KEY = "flows"
+
+        nested_resource :flow,
+                        path: "flows",
+                        object_key: "flow",
+                        list_key: "flows",
+                        operations: %i[create retrieve list update delete]
+
+        # Public API aliases — take (application_id, ...) as first arg.
+        def create(application_id, params = {})
+          create_flow(application_id, params)
+        end
+
+        def retrieve(application_id, id)
+          retrieve_flow(application_id, id)
+        end
+
+        def list(application_id, params = {})
+          list_flows(application_id, params)
+        end
+
+        def update(application_id, id, params = {})
+          update_flow(application_id, id, params)
+        end
+
+        def delete(application_id, id)
+          delete_flow(application_id, id)
+        end
+
+        # Member actions on the nested resource. NestedResource doesn't have a
+        # `nested_custom_action` helper yet, so these are written explicitly.
+        def activate(application_id, id, params = {})
+          member_action(application_id, id, "activate", params)
+        end
+
+        def deprecate(application_id, id, params = {})
+          member_action(application_id, id, "deprecate", params)
+        end
+
+        def archive(application_id, id, params = {})
+          member_action(application_id, id, "archive", params)
+        end
+
+        def resolve_preview(application_id, id, params = {})
+          member_action(application_id, id, "resolve_preview", params)
+        end
+
+        private
+
+        def member_action(application_id, id, action, params)
+          response = http_client.post(
+            "#{RESOURCE_PATH}/#{application_id}/flows/#{id}/#{action}",
+            body: params
+          )
+          unwrap(response)
+        end
+      end
+    end
+  end
+end