overturo 0.7.2

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Connect
+      # Meetings are nested under applications:
+      # /api/v1/applications/:application_id/meeting_consents[/:id][/participants]
+      #
+      # A meeting is the unit of record: it has a window (scheduled_at / ends_at),
+      # a platform identity, a cancellation, and participant rows that carry
+      # each person's decision per purpose.
+      class MeetingConsents < ApiResource
+        include ApiOperations::NestedResource
+
+        RESOURCE_PATH = "/applications"
+        declare_endpoint :get, "<resource>/{application_id}/meeting_consents/{id}/participants"
+        OBJECT_KEY = "meeting_consent"
+        LIST_KEY = "meeting_consents"
+
+        nested_resource :meeting_consent,
+                        path: "meeting_consents",
+                        object_key: "meeting_consent",
+                        list_key: "meeting_consents",
+                        operations: %i[create retrieve list update delete]
+
+        # Public API aliases — take (application_id, ...) as first arg.
+        def create(application_id, params = {})
+          create_meeting_consent(application_id, params)
+        end
+
+        def retrieve(application_id, id)
+          retrieve_meeting_consent(application_id, id)
+        end
+
+        def list(application_id, params = {})
+          list_meeting_consents(application_id, params)
+        end
+
+        # Rename or reschedule (title, scheduled_at, duration_minutes, platform,
+        # external_meeting_id).
+        def update(application_id, id, params = {})
+          update_meeting_consent(application_id, id, params)
+        end
+
+        # Cancels the meeting (participants are told; the record stays).
+        def cancel(application_id, id)
+          delete_meeting_consent(application_id, id)
+        end
+        alias delete cancel
+
+        # The meeting's participants with their decisions per purpose.
+        def participants(application_id, id, params = {})
+          path = "#{RESOURCE_PATH}/#{application_id}/meeting_consents/#{id}/participants"
+          response = http_client.get(path, params: params)
+          unwrap_list(response, path: path, key: "participants", params: params)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Connect
+      # Data portability (GDPR Art. 20). List the supported
+      # export formats and confirm a cross-border export/import. The self-service
+      # *access* DSAR is a web-only export and is not part of the API surface.
+      #
+      # Application-scoped: every call takes the application_id as its first
+      # argument and resolves under /applications/:application_id/portability.
+      class Portability < ApiResource
+        RESOURCE_PATH = "/applications"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :get, "<resource>/{application_id}/portability/formats"
+        declare_endpoint :post, "<resource>/{application_id}/portability/confirm_export"
+        declare_endpoint :post, "<resource>/{application_id}/portability/confirm_import"
+
+        # GET /applications/:application_id/portability/formats — the supported
+        # portability formats.
+        def formats(application_id, params = {})
+          OverturoObject.new(http_client.get(portability_path(application_id, "formats"), params: params))
+        end
+
+        # POST /applications/:application_id/portability/confirm_export —
+        # confirm and forward the export.
+        def confirm_export(application_id, params = {})
+          OverturoObject.new(http_client.post(portability_path(application_id, "confirm_export"), body: params))
+        end
+
+        # POST /applications/:application_id/portability/confirm_import —
+        # confirm an import.
+        def confirm_import(application_id, params = {})
+          OverturoObject.new(http_client.post(portability_path(application_id, "confirm_import"), body: params))
+        end
+
+        private
+
+        def portability_path(application_id, action)
+          "#{resource_path}/#{application_id}/portability/#{action}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Connect
+      class Webhooks < ApiResource
+        include ApiOperations::NestedResource
+
+        RESOURCE_PATH = "/applications"
+        OBJECT_KEY = "webhook_subscription"
+        LIST_KEY = "webhook_subscriptions"
+
+        nested_resource :webhook,
+                        path: "webhooks",
+                        object_key: "webhook_subscription",
+                        list_key: "webhook_subscriptions",
+                        operations: %i[create retrieve list update delete]
+
+        # Public API aliases: take (application_id, ...) as first arg
+        def create(application_id, params = {})
+          create_webhook(application_id, params)
+        end
+
+        def retrieve(application_id, id)
+          retrieve_webhook(application_id, id)
+        end
+
+        def list(application_id, params = {})
+          list_webhooks(application_id, params)
+        end
+
+        def update(application_id, id, params = {})
+          update_webhook(application_id, id, params)
+        end
+
+        def delete(application_id, id)
+          delete_webhook(application_id, id)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/consent/consent_records.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Overturo
+  module Resources
+    module Consent
+      # 201 — consent records captured outside Overturo's surfaces: the Record
+      # API (create = capture + commit in one call, idempotent on your key),
+      # the read, the batch import with its dry run, and the status read by
+      # the subject reference you supplied (email or your own identifier).
+      class ConsentRecords < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+
+        RESOURCE_PATH = "/consent_records"
+        OBJECT_KEY = "consent_record"
+        LIST_KEY = "consent_records"
+
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :post, "<resource>/imports"
+        declare_endpoint :get, "<resource>/imports/{import_id}"
+        declare_endpoint :get, "/applications/{application_id}/consent_status"
+
+        # Import consents you already hold (at most 5000 rows per batch).
+        # Returns the import (status pending); read it with #import_status.
+        def import(flow_id:, records:, dry_run: false, send_receipts: false)
+          raise ArgumentError, "flow_id is required" if flow_id.nil? || flow_id.to_s.empty?
+          raise ArgumentError, "records must be a non-empty array" unless records.is_a?(Array) && records.any?
+
+          response = http_client.post("#{resource_path}/imports",
+                                      body: { flow_id: flow_id, records: records, dry_run: dry_run, send_receipts: send_receipts })
+          unwrap(response, "import")
+        end
+
+        def import_status(import_id)
+          raise ArgumentError, "import_id is required" if import_id.nil? || import_id.to_s.empty?
+
+          unwrap(http_client.get("#{resource_path}/imports/#{CGI.escape(import_id.to_s)}"), "import")
+        end
+
+        # The per-purpose consent status for a subject reference.
+        def status(application_id:, email: nil, external_id: nil)
+          raise ArgumentError, "application_id is required" if application_id.nil? || application_id.to_s.empty?
+          raise ArgumentError, "email or external_id is required" if email.to_s.empty? && external_id.to_s.empty?
+
+          # Flat bracket keys: the query is `subject[email]=…`, the shape the server reads.
+          params = {}
+          params["subject[email]"] = email unless email.to_s.empty?
+          params["subject[external_id]"] = external_id unless external_id.to_s.empty?
+          response = http_client.get("/applications/#{CGI.escape(application_id.to_s)}/consent_status", params: params)
+          OverturoObject.new(response)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/consent/consent_sessions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Consent
+      class ConsentSessions < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+
+        RESOURCE_PATH = "/consent_sessions"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :post, "<resource>/{id}/exchange"
+        OBJECT_KEY = "consent_session"
+        LIST_KEY = "consent_sessions"
+
+        custom_action :authorize, method: :post
+        custom_action :verify, method: :get
+
+        # Exchange a consent token for claims, attestations, credentials, and tokens.
+        # Handles HTTP 202 (fulfillment pending) transparently by retrying with
+        # the Retry-After interval until the server returns the full result.
+        def exchange(id, params = {})
+          max_retries = 5
+          path = "#{resource_path}/#{id}/exchange"
+
+          (max_retries + 1).times do |attempt|
+            response = http_client.post(path, body: params)
+
+            # HttpClient returns parsed JSON for all 2xx responses.
+            # A 202 returns {status: "pending", ...} — detect and retry.
+            if response.is_a?(Hash) && response["status"] == "pending"
+              if attempt == max_retries
+                raise Overturo::ApiError.new(
+                  "Exchange timeout: fulfillment still pending",
+                  http_status: 202
+                )
+              end
+
+              sleep(1)
+              next
+            end
+
+            return OverturoObject.new(response)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/consent/decisions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Overturo
+  module Resources
+    module Consent
+      # 189 — pre-flight disclosure discovery. Returns what the decision screen
+      # would present for a consent flow (purposes, fields, steps, the action
+      # label, expiry, application branding) BEFORE any session exists, in public
+      # vocabulary and the requested locale.
+      #
+      # Publishable-key authenticated: the publishable key (pk_live_… / pk_test_…)
+      # is an embed-safe, per-application credential passed EXPLICITLY per call
+      # rather than via client config — this endpoint ignores the client's bearer
+      # token, so the publishable key is the only credential that matters. An
+      # unknown / foreign / non-consent flow answers a uniform 404
+      # (Overturo::NotFoundError).
+      class Decisions < ApiResource
+        RESOURCE_PATH = "/decisions"
+        OBJECT_KEY = "decision"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :get, "<resource>/flows/{flow_id}/disclosures"
+
+        # 201 — commit a capture: your server received the capture token with the
+        # form submission and commits it with the application credential
+        # (`authorize(token, subject: {email:, external_id:}, suppress_receipt: false)`).
+        # The result carries `status`, `record_id` and the receipt `channel`. A
+        # publishable key cannot commit (403 publishable_key_cannot_commit).
+        custom_action :authorize, method: :post
+
+        def discover(flow_id, publishable_key:, locale: nil)
+          raise ArgumentError, "flow_id is required" if flow_id.nil? || flow_id.to_s.empty?
+          raise ArgumentError, "publishable_key is required" if publishable_key.nil? || publishable_key.to_s.empty?
+
+          path = "#{resource_path}/flows/#{CGI.escape(flow_id.to_s)}/disclosures"
+          # Only send ?locale= for a non-blank locale (in Ruby "" is truthy, so a
+          # bare truthiness check would emit ?locale= — the JS/py clients omit it).
+          params = locale.to_s.empty? ? {} : { locale: locale }
+          response = http_client.get(path, params: params, headers: { "X-Publishable-Key" => publishable_key })
+
+          # The server wraps the inventory as {"flow" => {...}}; return the
+          # inventory itself, matching the JS/py/node
+          # clients' `envelope.flow`. An envelope-less 200 (a proxy/gateway
+          # misconfig — the server is fail-closed) is a typed error, never a
+          # silent pass-through of the whole body dressed up as the inventory.
+          raise Overturo::ApiError, "Malformed discovery response: missing 'flow' in body" unless response.is_a?(Hash) && response.key?("flow")
+
+          OverturoObject.new(response.fetch("flow"))
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/consent/entitlements.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Consent
+      class Entitlements < ApiResource
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/entitlements"
+        OBJECT_KEY = "entitlement"
+        LIST_KEY = "entitlements"
+
+        custom_action :verify, method: :get, returns: :raw
+      end
+    end
+  end
+end

data/lib/overturo/resources/consent/trust_levels.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Consent
+      class TrustLevels < ApiResource
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/trust_levels"
+        OBJECT_KEY = "trust_level"
+        LIST_KEY = "trust_levels"
+
+        custom_action :trigger, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/core/accounts.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Core
+      # The accounts API is list-only. Account creation happens through the
+      # dashboard signup flow, not the API, and per-account configuration is
+      # managed server-side.
+      class Accounts < ApiResource
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/accounts"
+        OBJECT_KEY = "account"
+        LIST_KEY = "accounts"
+      end
+    end
+  end
+end

data/lib/overturo/resources/core/me.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Core
+      class Me < ApiResource
+        RESOURCE_PATH = "/me"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :get, "<resource>"
+        OBJECT_KEY = "user"
+        LIST_KEY = nil
+
+        def retrieve
+          response = http_client.get(resource_path)
+          unwrap(response)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/delegate/agent_identities.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Delegate
+      class AgentIdentities < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Update
+        include ApiOperations::Delete
+
+        RESOURCE_PATH = "/agent_identities"
+        OBJECT_KEY = "agent_identity"
+        LIST_KEY = "agent_identities"
+
+        custom_action :delegate, method: :post
+        custom_action :suspend, method: :post
+        custom_action :reactivate, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/delegate/authorization_receipts.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Delegate
+      # Durable authorization records — `GET /api/v1/authorization_receipts/:id`.
+      # Requires the
+      # `audit:verify` token scope. The 404 contract is parity-preserving by
+      # design: unknown, foreign-account, and non-authority ids are
+      # indistinguishable — don't try to disambiguate client-side.
+      class AuthorizationReceipts < ApiResource
+        RESOURCE_PATH = "/authorization_receipts"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :get, "<resource>/{id}"
+        OBJECT_KEY = "authorization_receipt"
+
+        # flavor:
+        #   nil / "canonical" — the wrapped document (unwrapped to an
+        #     OverturoObject here, like every other resource read)
+        #   "signed" — the bare signed envelope, returned as a plain Hash:
+        #     it is a portable artifact you hand to a record verifier or
+        #     write to disk, not an API object
+        #   "dpv" — the JSON-LD document, also a plain Hash (the server
+        #     responds with application/ld+json; the body is JSON)
+        #
+        # Typed refusals (422) surface as Overturo::InvalidRequestError with
+        # `error_code` — "unknown_flavor", "not_signable", "dpv_unavailable".
+        def retrieve(id, flavor: nil)
+          params = flavor ? { flavor: flavor } : {}
+          response = http_client.get("#{RESOURCE_PATH}/#{id}", params: params)
+          return unwrap(response) if flavor.nil? || flavor.to_s == "canonical"
+
+          response
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/delegate/delegations.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Delegate
+      # `/api/v1/delegations` supports index/create/show/update. There is **no**
+      # bare DELETE endpoint — delegations are torn down via the `/revoke`
+      # member action, which is mounted as `DELETE /delegations/:id/revoke`
+      # (the verb encodes destruction; the path encodes that revocation is a
+      # specific lifecycle event distinct from a hard delete).
+      class Delegations < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Update
+
+        RESOURCE_PATH = "/delegations"
+        # 193 D12 — endpoints built by explicit http_client calls below.
+        declare_endpoint :delete, "<resource>/{id}/revoke"
+        OBJECT_KEY = "delegation_grant"
+        LIST_KEY = "delegation_grants"
+
+        # Revoke uses DELETE on a member sub-path. `custom_action` only knows
+        # :get and :post, so this is written explicitly. `http_client.delete`
+        # doesn't accept a body or params — the action takes the id and that's
+        # the entire contract.
+        def revoke(id)
+          response = http_client.delete("#{RESOURCE_PATH}/#{id}/revoke")
+          unwrap(response)
+        end
+      end
+    end
+  end
+end

data/lib/overturo/resources/delegate/disclosure_receipts.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Delegate
+      # Operator-declared disclosure receipts — `POST /api/v1/disclosure_receipts`.
+      # Requires the `disclosures:write`
+      # token scope. Mint-only by design: the operator disclosure log page is the
+      # read side (programmatic reads are a registered deferred capability).
+      #
+      # Payload: flow_id, agent_id, disclosed_at (ISO 8601), optional locale.
+      # The 201 unwraps to {record_id:, record:}. Typed refusals (422) surface
+      # as Overturo::InvalidRequestError with `error_code` — this endpoint's
+      # shape is {"error" => <human message>, "code" => <machine code>}
+      # ("agent_not_disclosed", "invalid_disclosed_at", "purposes_missing").
+      class DisclosureReceipts < ApiResource
+        include ApiOperations::Create
+
+        RESOURCE_PATH = "/disclosure_receipts"
+        OBJECT_KEY = "disclosure_receipt"
+      end
+    end
+  end
+end

data/lib/overturo/resources/delegate/security_event_streams.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Delegate
+      class SecurityEventStreams < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Update
+        include ApiOperations::Delete
+
+        RESOURCE_PATH = "/security_event_streams"
+        OBJECT_KEY = "security_event_stream"
+        LIST_KEY = "security_event_streams"
+
+        custom_action :verify, method: :post, returns: :raw
+        custom_action :poll, method: :get, returns: :raw
+      end
+    end
+  end
+end

data/lib/overturo/resources/protect/data_licenses.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Protect
+      class DataLicenses < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/data_licenses"
+        OBJECT_KEY = "data_license"
+        LIST_KEY = "data_licenses"
+
+        custom_action :terminate, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/protect/data_requests.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Protect
+      class DataRequests < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/data_requests"
+        OBJECT_KEY = "data_request"
+        LIST_KEY = "data_requests"
+      end
+    end
+  end
+end

data/lib/overturo/resources/protect/policies.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Protect
+      class Policies < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Update
+        include ApiOperations::Delete
+
+        RESOURCE_PATH = "/policies"
+        OBJECT_KEY = "policy"
+        LIST_KEY = "policies"
+
+        custom_action :activate, method: :post
+        custom_action :revoke, method: :post
+        custom_action :share, method: :post, returns: :raw
+      end
+    end
+  end
+end

data/lib/overturo/resources/protect/transfers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Protect
+      class Transfers < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+
+        RESOURCE_PATH = "/transfers"
+        OBJECT_KEY = "transfer"
+        LIST_KEY = "transfers"
+
+        custom_action :cancel, method: :post
+      end
+    end
+  end
+end

data/lib/overturo/resources/verify/credentials.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Verify
+      # `/api/v1/credentials` supports index/create/show/destroy plus the
+      # `/wallet_pass` member action. There is **no** PATCH endpoint —
+      # credentials are immutable once issued.
+      class Credentials < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+        include ApiOperations::List
+        include ApiOperations::Delete
+
+        RESOURCE_PATH = "/credentials"
+        OBJECT_KEY = "credential"
+        LIST_KEY = "credentials"
+
+        custom_action :wallet_pass, method: :get, returns: :raw
+      end
+    end
+  end
+end

data/lib/overturo/resources/verify/presentations.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Overturo
+  module Resources
+    module Verify
+      class Presentations < ApiResource
+        include ApiOperations::Create
+        include ApiOperations::Retrieve
+
+        RESOURCE_PATH = "/presentations"
+        OBJECT_KEY = "presentation"
+        LIST_KEY = "presentations"
+
+        custom_action :present, method: :patch, returns: :raw
+      end
+    end
+  end
+end