overturo 0.7.2

data/lib/overturo/api_operations/nested_resource.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Overturo
+  module ApiOperations
+    module NestedResource
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # `list_key` names the JSON key the API wraps the collection in; the
+        # generated method is always `list_<plural name>` (`list_method` overrides).
+        def nested_resource(name, path:, object_key: nil, list_key: nil, list_method: nil, operations: [])
+          { create: [:post, "<resource>/{parent_id}/#{path}"], retrieve: [:get, "<resource>/{parent_id}/#{path}/{id}"],
+            list: [:get, "<resource>/{parent_id}/#{path}"], update: [:patch, "<resource>/{parent_id}/#{path}/{id}"],
+            delete: [:delete, "<resource>/{parent_id}/#{path}/{id}"] }.each { |op, (m, t)| declare_endpoint(m, t) if operations.include?(op) }
+          operations.each do |op|
+            case op
+            when :create
+              define_method(:"create_#{name}") do |parent_id, params = {}|
+                response = http_client.post("#{resource_path}/#{parent_id}/#{path}", body: params)
+                unwrap(response, object_key || name.to_s)
+              end
+            when :retrieve
+              define_method(:"retrieve_#{name}") do |parent_id, id|
+                response = http_client.get("#{resource_path}/#{parent_id}/#{path}/#{id}")
+                unwrap(response, object_key || name.to_s)
+              end
+            when :list
+              define_method(:"list_#{list_method || "#{name}s"}") do |parent_id, params = {}|
+                lk = list_key || "#{name}s"
+                nested_path = "#{resource_path}/#{parent_id}/#{path}"
+                response = http_client.get(nested_path, params: params)
+                unwrap_list(response, path: nested_path, key: lk, params: params)
+              end
+            when :update
+              define_method(:"update_#{name}") do |parent_id, id, params = {}|
+                response = http_client.patch("#{resource_path}/#{parent_id}/#{path}/#{id}", body: params)
+                unwrap(response, object_key || name.to_s)
+              end
+            when :delete
+              define_method(:"delete_#{name}") do |parent_id, id|
+                response = http_client.delete("#{resource_path}/#{parent_id}/#{path}/#{id}")
+                unwrap(response, object_key || name.to_s)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/overturo/api_operations/retrieve.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Overturo
+  module ApiOperations
+    module Retrieve
+      def self.included(base) = base.declare_endpoint(:get, "<resource>/{id}")
+
+      def retrieve(id)
+        response = http_client.get("#{resource_path}/#{id}")
+        unwrap(response)
+      end
+    end
+  end
+end

data/lib/overturo/api_operations/update.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Overturo
+  module ApiOperations
+    module Update
+      def self.included(base) = base.declare_endpoint(:patch, "<resource>/{id}")
+
+      def update(id, params = {})
+        response = http_client.patch("#{resource_path}/#{id}", body: params)
+        unwrap(response)
+      end
+    end
+  end
+end

data/lib/overturo/api_resource.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Overturo
+  class ApiResource
+    attr_reader :http_client
+
+    def initialize(http_client)
+      @http_client = http_client
+    end
+
+    def resource_path
+      self.class::RESOURCE_PATH
+    end
+
+    def object_key
+      self.class::OBJECT_KEY
+    end
+
+    def list_key
+      self.class::LIST_KEY
+    end
+
+    # Member-action transport: the verb the API declares for the action.
+    def member_request(method, path, params)
+      case method
+      when :post then http_client.post(path, body: params)
+      when :patch then http_client.patch(path, body: params)
+      else http_client.get(path, params: params)
+      end
+    end
+
+    def unwrap(response, key = object_key)
+      data = response.is_a?(Hash) && response.key?(key) ? response[key] : response
+      OverturoObject.new(data)
+    end
+
+    def unwrap_list(response, path: resource_path, key: list_key, params: {})
+      items = if response.is_a?(Array) then response # a bare collection (the accounts API renders one)
+              elsif response.is_a?(Hash) && response.key?(key) then response[key]
+              else
+                []
+              end
+      pagination = response.is_a?(Hash) ? (response["pagination"] || {}) : {}
+      wrapped = items.map { |item| OverturoObject.new(item) }
+
+      ListObject.new(
+        data: wrapped,
+        pagination: pagination,
+        http_client: http_client,
+        resource_path: path,
+        list_key: key,
+        params: params
+      )
+    end
+
+    class << self
+      # 193 D12 — every endpoint this class can construct, as [METHOD, template].
+      # Macros record templates with a <resource> token because `include
+      # ApiOperations::*` precedes RESOURCE_PATH in most classes; the token is
+      # expanded lazily here. Explicit http_client calls declare themselves.
+      def declare_endpoint(method, template)
+        (@declared_templates ||= []) << [method.to_s.upcase, template]
+      end
+
+      def declared_endpoints
+        (@declared_templates || []).map { |m, t| [m, t.sub("<resource>", self::RESOURCE_PATH)] }.uniq
+      end
+
+      def custom_action(name, method: :post, path: nil, returns: :object)
+        action_path = path || name.to_s
+        declare_endpoint(method, "<resource>/{id}/#{action_path}")
+
+        case returns
+        when :object
+          define_method(name) do |id, params = {}|
+            unwrap(member_request(method, "#{resource_path}/#{id}/#{action_path}", params))
+          end
+        when :raw
+          define_method(name) do |id, params = {}|
+            OverturoObject.new(member_request(method, "#{resource_path}/#{id}/#{action_path}", params))
+          end
+        when :list
+          raise ArgumentError, "custom_action #{name}: returns: :list is GET-only (declared #{method})" unless method == :get
+
+          define_method(name) do |id, params = {}|
+            lk = path || name.to_s
+            response = http_client.get("#{resource_path}/#{id}/#{lk}", params: params)
+            unwrap_list(response, path: "#{resource_path}/#{id}/#{lk}", key: lk, params: params)
+          end
+        end
+      end
+
+      def collection_action(name, method: :post, path: nil)
+        action_path = path || name.to_s
+        declare_endpoint(method, "<resource>/#{action_path}")
+        define_method(name) do |params = {}|
+          response = if method == :post
+                       http_client.post("#{resource_path}/#{action_path}", body: params)
+                     else
+                       http_client.get("#{resource_path}/#{action_path}", params: params)
+                     end
+          unwrap(response)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/client.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Overturo
+  class Client
+    attr_reader :config
+
+    def initialize(api_key: nil, base_url: nil, api_version: nil,
+                   open_timeout: nil, read_timeout: nil, write_timeout: nil,
+                   max_retries: nil, logger: nil)
+      @config = Configuration.new
+      @config.api_key = api_key if api_key
+      @config.base_url = base_url if base_url
+      @config.api_version = api_version if api_version
+      @config.open_timeout = open_timeout if open_timeout
+      @config.read_timeout = read_timeout if read_timeout
+      @config.write_timeout = write_timeout if write_timeout
+      @config.max_retries = max_retries if max_retries
+      @config.logger = logger if logger
+
+      @config.validate!
+      @http_client = HttpClient.new(@config)
+    end
+
+    def connect
+      @connect ||= ConnectSurface.new(@http_client)
+    end
+
+    def consent
+      @consent ||= ConsentSurface.new(@http_client)
+    end
+
+    def verify
+      @verify ||= VerifySurface.new(@http_client)
+    end
+
+    def protect
+      @protect ||= ProtectSurface.new(@http_client)
+    end
+
+    def agree
+      @agree ||= AgreeSurface.new(@http_client)
+    end
+
+    def delegate_ns
+      @delegate_ns ||= DelegateSurface.new(@http_client)
+    end
+
+    def comply
+      @comply ||= ComplySurface.new(@http_client)
+    end
+
+    def core
+      @core ||= CoreSurface.new(@http_client)
+    end
+  end
+
+  class SurfaceProxy
+    def initialize(http_client)
+      @http_client = http_client
+      @resources = {}
+    end
+
+    private
+
+    def resource(klass)
+      @resources[klass] ||= klass.new(@http_client)
+    end
+  end
+
+  class CoreSurface < SurfaceProxy
+    def me
+      resource(Resources::Core::Me)
+    end
+
+    def accounts
+      resource(Resources::Core::Accounts)
+    end
+  end
+
+  class ConnectSurface < SurfaceProxy
+    def applications
+      resource(Resources::Connect::Applications)
+    end
+
+    def webhooks
+      resource(Resources::Connect::Webhooks)
+    end
+
+    def connections
+      resource(Resources::Connect::Connections)
+    end
+
+    def flows
+      resource(Resources::Connect::Flows)
+    end
+
+    # Data portability (GDPR Art. 20).
+    def portability
+      resource(Resources::Connect::Portability)
+    end
+
+    # Meetings — the unit of record for meeting consent (window, platform,
+    # cancellation, participants with their decisions).
+    def meeting_consents
+      resource(Resources::Connect::MeetingConsents)
+    end
+  end
+
+  class ConsentSurface < SurfaceProxy
+    def consent_sessions
+      resource(Resources::Consent::ConsentSessions)
+    end
+
+    # 189 — pre-flight disclosure discovery (publishable-key-scoped).
+    def decisions
+      resource(Resources::Consent::Decisions)
+    end
+
+    # 201 — consent records captured outside Overturo's surfaces.
+    def consent_records
+      resource(Resources::Consent::ConsentRecords)
+    end
+
+    def entitlements
+      resource(Resources::Consent::Entitlements)
+    end
+
+    def trust_levels
+      resource(Resources::Consent::TrustLevels)
+    end
+  end
+
+  class VerifySurface < SurfaceProxy
+    def credentials
+      resource(Resources::Verify::Credentials)
+    end
+
+    def verification_sessions
+      resource(Resources::Verify::VerificationSessions)
+    end
+
+    def presentations
+      resource(Resources::Verify::Presentations)
+    end
+
+    def trust_scores
+      resource(Resources::Verify::TrustScores)
+    end
+
+    def vouches
+      resource(Resources::Verify::Vouches)
+    end
+  end
+
+  class ProtectSurface < SurfaceProxy
+    def policies
+      resource(Resources::Protect::Policies)
+    end
+
+    def data_requests
+      resource(Resources::Protect::DataRequests)
+    end
+
+    def transfers
+      resource(Resources::Protect::Transfers)
+    end
+
+    def data_licenses
+      resource(Resources::Protect::DataLicenses)
+    end
+  end
+
+  class AgreeSurface < SurfaceProxy
+    def agreements
+      resource(Resources::Agree::Agreements)
+    end
+
+    def quorum_requests
+      resource(Resources::Agree::QuorumRequests)
+    end
+
+    def collaborations
+      resource(Resources::Agree::Collaborations)
+    end
+  end
+
+  class DelegateSurface < SurfaceProxy
+    def delegations
+      resource(Resources::Delegate::Delegations)
+    end
+
+    def agent_identities
+      resource(Resources::Delegate::AgentIdentities)
+    end
+
+    def security_event_streams
+      resource(Resources::Delegate::SecurityEventStreams)
+    end
+
+    def authorization_receipts
+      resource(Resources::Delegate::AuthorizationReceipts)
+    end
+
+    def disclosure_receipts
+      resource(Resources::Delegate::DisclosureReceipts)
+    end
+  end
+
+  class ComplySurface < SurfaceProxy
+    def anchors
+      resource(Resources::Comply::Anchors)
+    end
+
+    def evidence_packages
+      resource(Resources::Comply::EvidencePackages)
+    end
+
+    def clean_rooms
+      resource(Resources::Comply::CleanRooms)
+    end
+
+    # Cross-border transfer register and residency posture.
+    def transfer_register
+      resource(Resources::Comply::TransferRegister)
+    end
+
+    def residency_posture
+      resource(Resources::Comply::ResidencyPosture)
+    end
+  end
+end

data/lib/overturo/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Overturo
+  class Configuration
+    attr_accessor :api_key, :base_url, :api_version,
+                  :open_timeout, :read_timeout, :write_timeout,
+                  :max_retries, :logger
+
+    def initialize
+      @api_key = nil
+      @base_url = "https://overturo.com"
+      @api_version = "v1"
+      @open_timeout = 30
+      @read_timeout = 80
+      @write_timeout = 30
+      @max_retries = 2
+      @logger = nil
+    end
+
+    def validate!
+      raise AuthenticationError, "No API key provided. Set your API key using Overturo::Client.new(api_key: \"sk_live_...\")" unless api_key && !api_key.empty?
+    end
+  end
+end

data/lib/overturo/endpoints.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Overturo
+  # The machine-readable manifest of every endpoint this gem can call, derived
+  # from the resource classes' declared endpoints. `endpoints.json` at the gem
+  # root is the committed copy (rake endpoints:write); spec/overturo/endpoints_spec.rb
+  # keeps the two equal.
+  module Endpoints
+    def self.resource_classes
+      Overturo::Resources.constants.sort.flat_map do |surface|
+        mod = Overturo::Resources.const_get(surface)
+        mod.constants.sort.map { |c| mod.const_get(c) }.select { |k| k.is_a?(Class) && k < Overturo::ApiResource }
+      end
+    end
+
+    def self.manifest
+      entries = resource_classes.flat_map do |klass|
+        klass.declared_endpoints.map { |m, t| { "method" => m, "path" => "/api/v1#{t}", "resource" => klass.name } }
+      end
+      entries.uniq.sort_by { |e| [e["path"], e["method"]] }
+    end
+
+    def self.document
+      { "sdk" => "overturo-ruby", "endpoints" => manifest }
+    end
+  end
+end

data/lib/overturo/errors.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Overturo
+  class Error < StandardError
+    attr_reader :http_status, :http_body, :json_body
+
+    def initialize(message = nil, http_status: nil, http_body: nil, json_body: nil)
+      @http_status = http_status
+      @http_body = http_body
+      @json_body = json_body
+      super(message)
+    end
+
+    # Machine code from a structured error body, across both authority
+    # 422 shapes: the receipts read uses {"error" => "<code>",
+    # "reason" => <message>}, the disclosure mint uses {"error" =>
+    # <message>, "code" => "<code>"}. `code` wins when present; the two
+    # shapes are the server's contract, surfaced as-is.
+    # The API's error envelope is `{error: {code, message}}`; some endpoints
+    # still answer `{error: "<code or message>", code?: "<code>"}`.
+    def error_code
+      return nil unless json_body.is_a?(Hash)
+
+      error = json_body["error"]
+      return error["code"] if error.is_a?(Hash)
+
+      json_body["code"] || error
+    end
+  end
+
+  # 401
+  class AuthenticationError < Error; end
+  # 403
+  class ForbiddenError < Error; end
+  # 404
+  class NotFoundError < Error; end
+  # 400, 422
+  class InvalidRequestError < Error; end
+  # 429
+  class RateLimitError < Error; end
+  # 500+
+  class ApiError < Error; end
+  # Network errors
+  class ConnectionError < Error; end
+  # Timeout
+  class TimeoutError < Error; end
+
+  # @api private
+  ERROR_MAP = {
+    400 => InvalidRequestError,
+    401 => AuthenticationError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    422 => InvalidRequestError,
+    429 => RateLimitError
+  }.freeze
+
+  # ── OAP denial classes ──────────────────────────────────────────────
+  # Raised by OAP-protocol failures (authorize, escalate, complete).
+  # Carry the structured envelope fields so callers can branch on
+  # `denial_category` or rescue the per-category subclass directly.
+  class OAPDenied < Error
+    attr_reader :reason_code, :failed_bound, :denial_category, :cascade_step, :detail
+
+    def initialize(message = nil, reason_code: nil, failed_bound: nil,
+                   denial_category: nil, cascade_step: nil, detail: nil,
+                   http_status: nil, http_body: nil, json_body: nil)
+      @reason_code = reason_code
+      @failed_bound = failed_bound
+      @denial_category = denial_category
+      @cascade_step = cascade_step
+      @detail = detail
+      super(message, http_status: http_status, http_body: http_body, json_body: json_body)
+    end
+
+    # Build the most-specific subclass for an OAP error envelope.
+    # Reason-code dispatch takes precedence over category dispatch so
+    # the most specific subclass wins (sequence denials are
+    # trajectory_denied but get their own subclass).
+    # @param envelope [Hash] the parsed JSON body (root, not the inner `error`)
+    # @param status   [Integer, nil] HTTP status for transport-level matching
+    def self.from_envelope(envelope, status: nil)
+      err = (envelope || {})["error"] || {}
+      target = REASON_CODE_TO_CLASS[err["reason_code"]] ||
+               CATEGORY_TO_CLASS.fetch(err["denial_category"], OAPDenied)
+      target.new(
+        err["message"],
+        reason_code: err["reason_code"],
+        failed_bound: err["failed_bound"],
+        denial_category: err["denial_category"],
+        cascade_step: err["cascade_step"],
+        detail: err["detail"],
+        http_status: status,
+        json_body: envelope
+      )
+    end
+  end
+
+  # denial_category == "authorization_denied" — OAuth/DPoP layer failed.
+  class OAPAuthorizationDenied < OAPDenied; end
+  # denial_category == "intent_denied" — request outside grant bounds.
+  class OAPIntentDenied < OAPDenied; end
+  # denial_category == "trajectory_denied" — execution history blocked the action.
+  class OAPTrajectoryDenied < OAPDenied; end
+  # sequence_bounds violation
+  # (sequence_prohibited / sequence_missing_predecessor). A trajectory
+  # denial with a structural-ordering flavour.
+  class OAPSequenceDenied < OAPTrajectoryDenied; end
+
+  OAPDenied::CATEGORY_TO_CLASS = {
+    "authorization_denied" => OAPAuthorizationDenied,
+    "intent_denied" => OAPIntentDenied,
+    "trajectory_denied" => OAPTrajectoryDenied
+  }.freeze
+
+  OAPDenied::REASON_CODE_TO_CLASS = {
+    "sequence_prohibited" => OAPSequenceDenied,
+    "sequence_missing_predecessor" => OAPSequenceDenied
+  }.freeze
+end