didit-sdk 1.0.0

data/lib/didit/resources/investigator.rb

@@ -0,0 +1,419 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +investigator+ resource.
+    class Investigator < Didit::Resource
+      # Accept a recommendation
+      #
+      # Applies the recommended action through the item's normal path, so your usual webhooks fire. A `narrative`
+      # makes it edited and accepted. Restricted keys need the `decisions` scope (write); transaction alerts also need
+      # `transactions` (write). Escalating a verification or transaction opens a case.
+      #
+      # +POST /v3/investigator/runs/{run_id}/accept/+
+      #
+      # @param run_id [String]
+      # @param narrative [String] A rewritten narrative. Sending one records the decision as edited and accepted.
+      # @param send_email [Boolean] Email the person about the decision.
+      # @param email_address [String] Required when `send_email` is true.
+      # @param email_language [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorDecision]
+      def accept_run(
+        run_id,
+        narrative: OMIT,
+        send_email: OMIT,
+        email_address: OMIT,
+        email_language: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/investigator/runs/{run_id}/accept/",
+          path_params: { "run_id" => run_id },
+          body: {
+            "narrative" => narrative,
+            "send_email" => send_email,
+            "email_address" => email_address,
+            "email_language" => email_language
+          },
+          response: Types::InvestigatorDecision,
+          request_options: request_options
+        )
+      end
+
+      # Batch accept recommendations
+      #
+      # Accepts up to 50 reports marked Ready to accept. Each is its own decision: one that cannot be accepted is
+      # skipped with its reason. Restricted keys need the `decisions` scope (write); transaction alerts also need
+      # `transactions` (write). Escalating a verification or transaction opens a case.
+      #
+      # +POST /v3/investigator/runs/batch-accept/+
+      #
+      # @param run_ids [Array<String>]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorBatchAcceptResponse]
+      def batch_accept_runs(run_ids:, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/investigator/runs/batch-accept/",
+          body: {
+            "run_ids" => run_ids
+          },
+          response: Types::InvestigatorBatchAcceptResponse,
+          request_options: request_options
+        )
+      end
+
+      # Export Investigator activity
+      #
+      # The same entries as CSV, one row per decision, newest first, up to 10,000 entries. Restricted keys need the
+      # `decisions` scope (read); transaction alerts also need `transactions`.
+      #
+      # +GET /v3/investigator/activity/export/+
+      #
+      # @param scope [String] `identity` (sessions, and cases not opened by a transaction rule) or `transactions`
+      #   (transaction alerts, and cases a transaction rule opened).
+      # @param group [String]
+      # @param actor [String] `agent` for the Investigator, or a person's email.
+      # @param since [Time, String]
+      # @param until [Time, String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [String, nil] the body bytes, or nil when a block receives the chunks
+      def export_activity(scope: OMIT, group: OMIT, actor: OMIT, since: OMIT, until: OMIT, request_options: nil, &block)
+        @client.request(
+          :get,
+          "/v3/investigator/activity/export/",
+          query: {
+            "scope" => scope,
+            "group" => group,
+            "actor" => actor,
+            "since" => since,
+            "until" => binding.local_variable_get(:until)
+          },
+          response: :binary,
+          accept: "text/csv, application/json",
+          request_options: request_options, &block
+        )
+      end
+
+      # List Investigator activity
+      #
+      # The append-only audit trail, newest first. A batch accept is one entry. Adds `counts` per group and `actors`.
+      # Restricted keys need the `decisions` scope (read); transaction alerts also need `transactions`.
+      #
+      # +GET /v3/investigator/activity/+
+      #
+      # @param scope [String] `identity` (sessions, and cases not opened by a transaction rule) or `transactions`
+      #   (transaction alerts, and cases a transaction rule opened).
+      # @param group [String]
+      # @param actor [String] `agent` for the Investigator, or a person's email.
+      # @param since [Time, String]
+      # @param until [Time, String]
+      # @param limit [Integer]
+      # @param offset [Integer]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Hash>]
+      def list_activity(
+        scope: OMIT,
+        group: OMIT,
+        actor: OMIT,
+        since: OMIT,
+        until: OMIT,
+        limit: OMIT,
+        offset: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :get,
+          "/v3/investigator/activity/",
+          query: {
+            "scope" => scope,
+            "group" => group,
+            "actor" => actor,
+            "since" => since,
+            "until" => binding.local_variable_get(:until),
+            "limit" => limit,
+            "offset" => offset
+          },
+          page: :any,
+          request_options: request_options
+        )
+      end
+
+      # List the locked guardrails
+      #
+      # The five guardrails that apply to every queue. They cannot be switched off. Restricted keys need the
+      # `decisions` scope (read); transaction alerts also need `transactions`.
+      #
+      # +GET /v3/investigator/guardrails/+
+      #
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorListGuardrailsResponse]
+      def list_guardrails(request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/guardrails/",
+          response: Types::InvestigatorListGuardrailsResponse,
+          request_options: request_options
+        )
+      end
+
+      # List the Investigator queue
+      #
+      # Open reports, **Ready to accept** first, then by deadline, risk and wait. `counts` covers every kind in scope.
+      # `count` is capped at 100. Restricted keys need the `decisions` scope (read); transaction alerts also need
+      # `transactions`.
+      #
+      # +GET /v3/investigator/queue/+
+      #
+      # @param scope [String] `identity` (sessions, and cases not opened by a transaction rule) or `transactions`
+      #   (transaction alerts, and cases a transaction rule opened).
+      # @param kind [String] `session`, `business_session`, `transaction` or `case`, or several separated by commas.
+      # @param queue [String]
+      # @param recommendation [String]
+      # @param confidence [String]
+      # @param ready [Boolean]
+      # @param search [String] Name, company, case title, number, transaction ID or item ID.
+      # @param limit [Integer]
+      # @param offset [Integer]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::InvestigatorQueueRow>]
+      def list_queue(
+        scope: OMIT,
+        kind: OMIT,
+        queue: OMIT,
+        recommendation: OMIT,
+        confidence: OMIT,
+        ready: OMIT,
+        search: OMIT,
+        limit: OMIT,
+        offset: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :get,
+          "/v3/investigator/queue/",
+          query: {
+            "scope" => scope,
+            "kind" => kind,
+            "queue" => queue,
+            "recommendation" => recommendation,
+            "confidence" => confidence,
+            "ready" => ready,
+            "search" => search,
+            "limit" => limit,
+            "offset" => offset
+          },
+          page: Types::InvestigatorQueueRow,
+          request_options: request_options
+        )
+      end
+
+      # Override a recommendation
+      #
+      # Takes another action with a category and a reason. Also overrides a decision the Investigator took on its own
+      # while it still stands. Restricted keys need the `decisions` scope (write); transaction alerts also need
+      # `transactions` (write). Escalating a verification or transaction opens a case.
+      #
+      # +POST /v3/investigator/runs/{run_id}/override/+
+      #
+      # @param run_id [String]
+      # @param action [String]
+      # @param category [String]
+      # @param reason [String]
+      # @param send_email [Boolean] Email the person about the decision.
+      # @param email_address [String] Required when `send_email` is true.
+      # @param email_language [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorDecision]
+      def override_run(
+        run_id,
+        action:,
+        category:,
+        reason:,
+        send_email: OMIT,
+        email_address: OMIT,
+        email_language: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/investigator/runs/{run_id}/override/",
+          path_params: { "run_id" => run_id },
+          body: {
+            "action" => action,
+            "category" => category,
+            "reason" => reason,
+            "send_email" => send_email,
+            "email_address" => email_address,
+            "email_language" => email_language
+          },
+          response: Types::InvestigatorDecision,
+          request_options: request_options
+        )
+      end
+
+      # Investigator dashboard
+      #
+      # The last 30 days: reviews, decisions, automation rate, hours saved, spend, overrides, quality samples since
+      # go-live, per-queue and weekly figures. Restricted keys need the `decisions` scope (read); transaction alerts
+      # also need `transactions`.
+      #
+      # +GET /v3/investigator/dashboard/+
+      #
+      # @param scope [String] `identity` (sessions, and cases not opened by a transaction rule) or `transactions`
+      #   (transaction alerts, and cases a transaction rule opened).
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorRetrieveDashboardResponse]
+      def retrieve_dashboard(scope: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/dashboard/",
+          query: {
+            "scope" => scope
+          },
+          response: Types::InvestigatorRetrieveDashboardResponse,
+          request_options: request_options
+        )
+      end
+
+      # Investigator performance
+      #
+      # Agreement with your team, volume, time saved, confidence calibration, per-queue results, override reasons and
+      # disagreements for a period. Restricted keys need the `decisions` scope (read); transaction alerts also need
+      # `transactions`.
+      #
+      # +GET /v3/investigator/performance/+
+      #
+      # @param scope [String] `identity` (sessions, and cases not opened by a transaction rule) or `transactions`
+      #   (transaction alerts, and cases a transaction rule opened).
+      # @param period [String] Days, ending today.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorRetrievePerformanceResponse]
+      def retrieve_performance(scope: OMIT, period: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/performance/",
+          query: {
+            "scope" => scope,
+            "period" => period
+          },
+          response: Types::InvestigatorRetrievePerformanceResponse,
+          request_options: request_options
+        )
+      end
+
+      # Get an Investigator report
+      #
+      # The full report of one run. 404 when the run has no completed report, or its item was deleted. Restricted keys
+      # need the `decisions` scope (read); transaction alerts also need `transactions`.
+      #
+      # +GET /v3/investigator/runs/{run_id}/+
+      #
+      # @param run_id [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorRunDetail]
+      def retrieve_run(run_id, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/runs/{run_id}/",
+          path_params: { "run_id" => run_id },
+          response: Types::InvestigatorRunDetail,
+          request_options: request_options
+        )
+      end
+
+      # Get Investigator settings
+      #
+      # The stage (`none`, `shadow` or `live`) and the monthly spend limit with this month's spend. Restricted keys
+      # need the `applications` scope (read).
+      #
+      # +GET /v3/investigator/settings/+
+      #
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorSettings]
+      def retrieve_settings(request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/settings/",
+          response: Types::InvestigatorSettings,
+          request_options: request_options
+        )
+      end
+
+      # Investigator summary
+      #
+      # Stage, queue counts, reports prepared and decided today, 30-day agreement, prices and the autonomy level of
+      # each queue. Restricted keys need the `decisions` scope (read); transaction alerts also need `transactions`.
+      #
+      # +GET /v3/investigator/summary/+
+      #
+      # @param scope [String] `identity` (sessions, and cases not opened by a transaction rule) or `transactions`
+      #   (transaction alerts, and cases a transaction rule opened).
+      # @param timezone [String] IANA time zone (for example `Europe/Madrid`) that "today" counts from. UTC by
+      #   default.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorRetrieveSummaryResponse]
+      def retrieve_summary(scope: OMIT, timezone: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/summary/",
+          query: {
+            "scope" => scope,
+            "timezone" => timezone
+          },
+          response: Types::InvestigatorRetrieveSummaryResponse,
+          request_options: request_options
+        )
+      end
+
+      # Get a transaction's Investigator review
+      #
+      # The transaction's latest review, or `investigator: null` when it never had one. Restricted keys need the
+      # `decisions` and `transactions` scopes (read).
+      #
+      # +GET /v3/investigator/transactions/{transaction_id}/+
+      #
+      # @param transaction_id [String]
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorRetrieveTransactionResponse]
+      def retrieve_transaction(transaction_id, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/investigator/transactions/{transaction_id}/",
+          path_params: { "transaction_id" => transaction_id },
+          response: Types::InvestigatorRetrieveTransactionResponse,
+          request_options: request_options
+        )
+      end
+
+      # Update Investigator settings
+      #
+      # Change the stage, the monthly spend limit, or both. Moving past `none` needs a plan that includes the
+      # Investigator (Growth or higher); `live` also needs a contract that prices it, if you have one. Restricted keys
+      # need the `applications` scope (write).
+      #
+      # +PATCH /v3/investigator/settings/+
+      #
+      # @param stage [String]
+      # @param monthly_spend_limit [String, nil] Monthly limit in your billing currency, 0.01 to 1,000,000. Null turns
+      #   it off.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::InvestigatorSettings]
+      def update_settings(stage: OMIT, monthly_spend_limit: OMIT, request_options: nil)
+        @client.request(
+          :patch,
+          "/v3/investigator/settings/",
+          body: {
+            "stage" => stage,
+            "monthly_spend_limit" => monthly_spend_limit
+          },
+          response: Types::InvestigatorSettings,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end

data/lib/didit/resources/ip.rb

@@ -0,0 +1,68 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +ip+ resource.
+    class Ip < Didit::Resource
+      # Risk-score an IP address
+      #
+      # Return geolocation, network ownership, VPN/Tor and data-center flags, threat data, and `country_mismatch` for
+      # a supplied IP address. The endpoint creates an API session and returns its id as `request_id`.
+      #
+      # **Decision.** `status` is `In Review` when the resolved country conflicts with `claimed_country`, or when the
+      # address is associated with VPN, Tor, or data-center infrastructure. Otherwise it is `Approved`.
+      #
+      # **Best effort.** IP enrichment is best effort. If no enrichment source returns usable data, the endpoint
+      # returns an approved response with `ip.ip_address: null`, `ip.country_mismatch: null`, and an empty `ip.threat`
+      # object.
+      #
+      # **Billing.** Live calls use IP Risk API pricing. The request is billable once the lookup starts.
+      #
+      # **Sandbox.** Sandbox keys validate the request and return deterministic approved data without consuming
+      # credits, creating a session, or contributing to Networks.
+      #
+      # **Authentication.** Send your application's API key in `x-api-key`. Missing or invalid credentials return
+      # `403` - this API never returns `401`.
+      #
+      # **Rate limit.** Shared write budget of 300 requests per minute per API key across all POST/PATCH/DELETE
+      # endpoints.
+      #
+      # +POST /v3/ip/risk/+
+      #
+      # @param ip_address [String] IPv4 or IPv6 address to score.
+      # @param claimed_country [String] Optional ISO 3166-1 alpha-2 or alpha-3 country claimed by the user or session.
+      #   Used to calculate `country_mismatch`.
+      # @param user_agent [String] User agent observed by your backend. Stored as request context; it does not provide
+      #   device fingerprinting.
+      # @param vendor_data [String] Your stable reference for this request. Stored on the API session and echoed in
+      #   the response.
+      # @param metadata [Hash, nil] Your non-sensitive JSON metadata. Stored on the API session and echoed in the
+      #   response.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::IPRiskResponse]
+      def assess_risk(
+        ip_address:,
+        claimed_country: OMIT,
+        user_agent: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/ip/risk/",
+          body: {
+            "ip_address" => ip_address,
+            "claimed_country" => claimed_country,
+            "user_agent" => user_agent,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata
+          },
+          response: Types::IPRiskResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end