didit-sdk 1.0.0

data/lib/didit/resources/networks.rb

@@ -0,0 +1,427 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +networks+ resource.
+    class Networks < Didit::Resource
+      # @return [Didit::Resources::Networks::Notes]
+      def notes
+        @notes ||= Notes.new(@client)
+      end
+
+      # Add a tag to a network
+      #
+      # Put one of your application's tags on the network. Returns the network detail, whose `tags` lists your
+      # application's tags on the network, with `201` when the tag was added and `200` when it was already on the
+      # network. A tag that belongs to another application, or does not exist, returns 404 `Tag not found.`. Requires
+      # a full-access API key, or `write:networks` for a console member.
+      #
+      # +POST /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/add/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param tag_uuid [String] UUID of one of your application's tags.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworkDetailResponse]
+      def add_tag(network_uuid, tag_uuid:, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/add/",
+          path_params: { "network_uuid" => network_uuid },
+          body: {
+            "tag_uuid" => tag_uuid
+          },
+          scope: :application,
+          response: Types::NetworkDetailResponse,
+          request_options: request_options
+        )
+      end
+
+      # Download a network evidence report
+      #
+      # Download a PDF of the current organization network, its observed account connections, signal references and
+      # review status. Requires read:networks. Global intelligence and private analyst notes are not included. Each
+      # account and signal list is capped at 500 entries and the report states when it is incomplete. The request does
+      # not change network status. Errors are returned as JSON.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/report/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @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 download_report(network_uuid, request_options: nil, &block)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/report/",
+          path_params: { "network_uuid" => network_uuid },
+          scope: :application,
+          response: :binary,
+          accept: "application/pdf, application/json",
+          request_options: request_options, &block
+        )
+      end
+
+      # List networks
+      #
+      # List fraud networks detected within this application's organization, highest risk first by default. By default
+      # dismissed networks are excluded; pass status to include them. Sandbox applications never have networks:
+      # clustering excludes sandbox data entirely. Every response carries the organization's `sharing_mode` and
+      # whether cross-organization signals apply to it (`cross_org_available`, `cross_org_unavailable_reason`). `kpis`
+      # aggregate the networks that match your filters and `counts` aggregate every network the application can see;
+      # pass `summary=false` to skip both when you only need the page. Requires a full-access API key, or
+      # `list:networks` for a console member.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/+
+      #
+      # @param status [String] Comma-separated statuses to include: active,in_review,resolved,dismissed. Omit to
+      #   exclude dismissed.
+      # @param scope [String] `transactions` keeps networks whose members are all transaction parties; `identity`
+      #   keeps every other network. Omit for both. It also narrows `counts.views` and `counts.facets`. Any other value
+      #   returns 400.
+      # @param signal_type [String] Comma-separated signal types:
+      #   ip_address,device,face,document_number,phone,email,address.
+      # @param pattern_type [String] Comma-separated pattern types, e.g. exact_same_device,same_email.
+      # @param risk_band [String] Comma-separated bands: low,medium,high.
+      # @param min_size [Integer] Minimum member count.
+      # @param max_size [Integer] Maximum member count.
+      # @param assignee [String] Comma-separated assignees: `unassigned`, member emails (matched case-insensitively),
+      #   or `me` for the calling console member. A network matches any value. `me` needs a console member token: an API
+      #   key gets 400 `{"assignee": ["\"me\" needs a user token; an API key has no assignee identity."]}`.
+      # @param priority [String] Comma-separated priorities: `low`, `medium`, `high`, or `none` for networks without a
+      #   priority. Any other value returns 400 `{"priority": "Unknown priority: <values>."}`.
+      # @param risk_min [Integer] Minimum risk score, a whole number from 0 to 100. A value that is not a whole number
+      #   returns 400 `{"risk_min": "Use a whole number from 0 to 100."}`.
+      # @param has_case [Boolean] `true` keeps the networks your application opened a case for, `false` the others.
+      #   Any other value is ignored.
+      # @param date_from [Date, String] Lower bound on last_activity_at (ISO 8601 date or datetime).
+      # @param date_to [Date, String] Upper bound on first_activity_at (ISO 8601 date or datetime).
+      # @param q [String] Free-text search across network name, member names, the network_id (N-0001), and exact
+      #   pattern_type tokens.
+      # @param ordering [String] One of risk_score, -risk_score, last_activity_at, -last_activity_at,
+      #   first_activity_at, -first_activity_at, network_number, -network_number. Defaults to
+      #   -risk_score,-last_activity_at.
+      # @param limit [Integer] Page size, 1-500. Defaults to 100.
+      # @param offset [Integer] Zero-based offset of the first record.
+      # @param summary [Boolean] `false` returns the page and its `count` only, without `kpis` and `counts`. Defaults
+      #   to `true`. Any value other than `true` or `false` returns 400.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::NetworkListItem>]
+      def list(
+        status: OMIT,
+        scope: OMIT,
+        signal_type: OMIT,
+        pattern_type: OMIT,
+        risk_band: OMIT,
+        min_size: OMIT,
+        max_size: OMIT,
+        assignee: OMIT,
+        priority: OMIT,
+        risk_min: OMIT,
+        has_case: OMIT,
+        date_from: OMIT,
+        date_to: OMIT,
+        q: OMIT,
+        ordering: OMIT,
+        limit: OMIT,
+        offset: OMIT,
+        summary: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/",
+          query: {
+            "status" => status,
+            "scope" => scope,
+            "signal_type" => signal_type,
+            "pattern_type" => pattern_type,
+            "risk_band" => risk_band,
+            "min_size" => min_size,
+            "max_size" => max_size,
+            "assignee" => assignee,
+            "priority" => priority,
+            "risk_min" => risk_min,
+            "has_case" => has_case,
+            "date_from" => date_from,
+            "date_to" => date_to,
+            "q" => q,
+            "ordering" => ordering,
+            "limit" => limit,
+            "offset" => offset,
+            "summary" => summary
+          },
+          scope: :application,
+          page: Types::NetworkListItem,
+          request_options: request_options
+        )
+      end
+
+      # List network members
+      #
+      # List the subjects (vendor users, vendor businesses, or transaction parties) that belong to this network.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/members/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworksListMembersResponse]
+      def list_members(network_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/members/",
+          path_params: { "network_uuid" => network_uuid },
+          scope: :application,
+          response: Types::NetworksListMembersResponse,
+          request_options: request_options
+        )
+      end
+
+      # List network signals
+      #
+      # List the signals (shared device, IP, face, document number, phone, email, or address values) that link this
+      # network's members.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/signals/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworksListSignalsResponse]
+      def list_signals(network_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/signals/",
+          path_params: { "network_uuid" => network_uuid },
+          scope: :application,
+          response: Types::NetworksListSignalsResponse,
+          request_options: request_options
+        )
+      end
+
+      # Remove a tag from a network
+      #
+      # Remove one of your application's tags from the network. Returns the network detail. 404 when the tag is not on
+      # the network, or does not belong to your application. Requires a full-access API key, or `write:networks` for a
+      # console member.
+      #
+      # +POST /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/remove/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param tag_uuid [String] UUID of one of your application's tags.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworkDetailResponse]
+      def remove_tag(network_uuid, tag_uuid:, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/remove/",
+          path_params: { "network_uuid" => network_uuid },
+          body: {
+            "tag_uuid" => tag_uuid
+          },
+          scope: :application,
+          response: Types::NetworkDetailResponse,
+          request_options: request_options
+        )
+      end
+
+      # Get network
+      #
+      # Retrieve a single network's full detail: stats, fraud tags and risk signals, plus the organization's
+      # `sharing_mode` and cross-organization availability, your application's `tags` on the network, member
+      # `outcomes` and pattern scores (`patterns`). Requires a full-access API key, or `read:networks` for a console
+      # member.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworkDetailResponse]
+      def retrieve(network_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/",
+          path_params: { "network_uuid" => network_uuid },
+          scope: :application,
+          response: Types::NetworkDetailResponse,
+          request_options: request_options
+        )
+      end
+
+      # Get network graph
+      #
+      # Retrieve the network as a graph of subject nodes (vendor users, vendor businesses, transaction parties) and
+      # signal nodes (the shared device/IP/face/document/phone/email/address values linking them), with edges
+      # representing memberships.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/graph/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param depth [String] Hops from the focus subject to include. Defaults to all (unbounded).
+      # @param focus_kind [String] Subject type to center the graph on. Must be supplied together with focus_id;
+      #   defaults to an arbitrary member when depth is bounded and neither is supplied.
+      # @param focus_id [String] Subject UUID to center the graph on.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworkGraph]
+      def retrieve_graph(network_uuid, depth: OMIT, focus_kind: OMIT, focus_id: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/graph/",
+          path_params: { "network_uuid" => network_uuid },
+          query: {
+            "depth" => depth,
+            "focus_kind" => focus_kind,
+            "focus_id" => focus_id
+          },
+          scope: :application,
+          response: Types::NetworkGraph,
+          request_options: request_options
+        )
+      end
+
+      # Get network map
+      #
+      # Geographic points where this network's members' addresses/locations converge, sourced from the sessions,
+      # business sessions, and transactions backing its memberships.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/map/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworkMap]
+      def retrieve_map(network_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/map/",
+          path_params: { "network_uuid" => network_uuid },
+          scope: :application,
+          response: Types::NetworkMap,
+          request_options: request_options
+        )
+      end
+
+      # Get network timeline
+      #
+      # Without `contract`: the network's own events (detection, each signal's latest observation and its review),
+      # oldest first and not paginated. `limit`, `cursor` and `event_type` are ignored. With `contract=2`: the typed
+      # timeline, newest first and paginated by cursor. It adds what the member accounts did (verification attempts,
+      # transactions, sign-ins you post through the events API and the live rules they hit) and the cases opened for
+      # the network. `note_added` events are returned to console members only, never to an API key. Requires a
+      # full-access API key, or `read:networks` for a console member.
+      #
+      # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/timeline/+
+      #
+      # @param network_uuid [String] Network UUID.
+      # @param contract [String] `2` returns the typed timeline. Omit it for the default timeline. Any other value
+      #   returns 400.
+      # @param limit [Integer] Typed timeline only. Events per page, 1 to 500. Defaults to 100.
+      # @param cursor [String] Typed timeline only. The previous page's `next_cursor`. An invalid or empty cursor
+      #   returns 400.
+      # @param event_type [Array<String>] Typed timeline only. Event types to keep, repeated or comma-separated, at
+      #   most 20 values. Defaults to every type.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::NetworksRetrieveTimelineResponse]
+      def retrieve_timeline(
+        network_uuid,
+        contract: OMIT,
+        limit: OMIT,
+        cursor: OMIT,
+        event_type: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :get,
+          "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/timeline/",
+          path_params: { "network_uuid" => network_uuid },
+          query: {
+            "contract" => contract,
+            "limit" => limit,
+            "cursor" => cursor,
+            "event_type" => event_type
+          },
+          scope: :application,
+          response: Types::NetworksRetrieveTimelineResponse,
+          request_options: request_options
+        )
+      end
+
+      # The +networks.notes+ resource.
+      class Notes < Didit::Resource
+        # Add a private network note
+        #
+        # Requires a console user with write:networks. The author is assigned from the authenticated user. Supply a
+        # new random UUID client_reference for each note; retry the same body and reference after an uncertain
+        # response to avoid duplicates. Reusing a reference for another body, author or network returns 409. Notes
+        # follow the surviving investigation when networks merge.
+        #
+        # +POST /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/+
+        #
+        # @param network_uuid [String] Network UUID.
+        # @param comment [String]
+        # @param client_reference [String]
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [Didit::Types::NetworkNote]
+        def create(network_uuid, comment:, client_reference:, request_options: nil)
+          @client.request(
+            :post,
+            "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/",
+            path_params: { "network_uuid" => network_uuid },
+            body: {
+              "comment" => comment,
+              "client_reference" => client_reference
+            },
+            scope: :application,
+            response: Types::NetworkNote,
+            request_options: request_options
+          )
+        end
+
+        # Delete your network note
+        #
+        # Requires write:networks and the authenticated author of the note. Deletion is irreversible. Connected
+        # account and verification data are unaffected.
+        #
+        # +DELETE /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/{note_uuid}/+
+        #
+        # @param network_uuid [String] Network UUID.
+        # @param note_uuid [String]
+        # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+        # @return [nil]
+        def delete(network_uuid, note_uuid, request_options: nil)
+          @client.request(
+            :delete,
+            "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/{note_uuid}/",
+            path_params: { "network_uuid" => network_uuid, "note_uuid" => note_uuid },
+            scope: :application,
+            request_options: request_options
+          )
+        end
+
+        # List private network notes
+        #
+        # Console users with read:networks can read notes on a network visible to the application. Notes stay within
+        # the organization and are not contributed to shared intelligence. Newest notes appear first.
+        #
+        # +GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/+
+        #
+        # @param network_uuid [String] Network UUID.
+        # @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::NetworkNote>]
+        def list(network_uuid, limit: OMIT, offset: OMIT, request_options: nil)
+          @client.request(
+            :get,
+            "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/",
+            path_params: { "network_uuid" => network_uuid },
+            query: {
+              "limit" => limit,
+              "offset" => offset
+            },
+            scope: :application,
+            page: Types::NetworkNote,
+            request_options: request_options
+          )
+        end
+      end
+    end
+  end
+end

data/lib/didit/resources/passive_liveness.rb

@@ -0,0 +1,103 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +passive_liveness+ resource.
+    class PassiveLiveness < Didit::Resource
+      # Passive Liveness
+      #
+      # Detect presentation attacks - printed photos, screen replays, masks, deepfakes - from a single face image. No
+      # video, motion, or user interaction required.
+      #
+      # **How it works.** The image is analyzed by a biometric model; the largest detected face is evaluated and a
+      # liveness `score` (0-100) is computed. `status` is `Declined` when any `error`-severity warning fires:
+      # - `NO_FACE_DETECTED` - the liveness model found no face,
+      # - `LOW_LIVENESS_SCORE` - score at or below `face_liveness_score_decline_threshold` (default `30`),
+      # - `LIVENESS_FACE_ATTACK` - the model detected a presentation attack,
+      # - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` - the face matches an entry on your face blocklist.
+      #
+      # `MULTIPLE_FACES_DETECTED` is a `warning`-severity signal (does not decline), and `DUPLICATED_FACE` /
+      # `POSSIBLE_DUPLICATED_FACE` are `information`-severity signals that the same face already appeared in another
+      # approved session (they never decline). `face_quality` and `face_luminance` (0-100, nullable) describe capture
+      # quality.
+      #
+      # **Blocklist and duplicate screening.** Runs on **every** call - with or without `save_api_request` - by
+      # matching the detected face against your application's face search index. Prior faces with the same
+      # `vendor_data` are excluded from the entire index search - so re-running liveness for the same user does not
+      # trigger `DUPLICATED_FACE`, and a blocklisted face originating from a session with the caller's own
+      # `vendor_data` is also NOT flagged (`FACE_IN_BLOCKLIST` screening is bypassed for same-`vendor_data` faces).
+      #
+      # **Billing.** Each `200` response consumes one Passive Liveness API credit (paid from your plan credit or
+      # top-up balance). Insufficient balance returns `403` before any image processing.
+      #
+      # **Session persistence and face enrollment (`save_api_request`, default `true`).** When `true`, the call is
+      # persisted as an API-type session (Business Console, `GET /v3/session/{sessionId}/decision/` via the returned
+      # `request_id`, `status.updated` webhook), the reference image and face crop are stored, and the detected face
+      # is **enrolled into your face search index** so later Face Search calls and duplicate checks can match it. When
+      # `false`, the call is one-shot: nothing is stored and the face is not enrolled (blocklist/duplicate screening
+      # still runs).
+      #
+      # **Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still
+      # returns `400`), the endpoint returns a static `Approved` mock payload, no session is persisted, and no credits
+      # are consumed.
+      #
+      # **Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials
+      # return `403` (`{"detail": "You do not have permission to perform this action."}`) - this API never returns
+      # `401`.
+      #
+      # **Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints;
+      # exceeding it returns `429`.
+      #
+      # +POST /v3/passive-liveness/+
+      #
+      # @param user_image [Pathname, IO, String, Didit::FilePart] Front-facing face image (e.g. a selfie). Allowed
+      #   extensions: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Maximum upload size: **5 MB** (larger files are rejected
+      #   with `400`). Images are automatically compressed to ~0.5 MB before processing, so very high resolutions do not
+      #   improve accuracy. The image should contain a single subject - when several faces are present, the largest one
+      #   is evaluated and a `MU...
+      # @param face_liveness_score_decline_threshold [Numeric] Liveness score threshold (0-100). A computed score **at
+      #   or below** this value emits a `LOW_LIVENESS_SCORE` warning and sets `status` to `Declined`. Default `30`;
+      #   raise it for a stricter anti-spoofing posture. Values outside 0-100 return `400`.
+      # @param rotate_image [Boolean] When `true`, the service tries 90-degree rotations of the input and uses the
+      #   orientation that yields the best face detection. Useful when EXIF orientation is missing. Adds latency.
+      # @param save_api_request [Boolean] When `true` (default), persists the call as an API-type session, stores the
+      #   face images, emits a `status.updated` webhook, and enrolls the detected face into your face search index. When
+      #   `false`, the call is one-shot - nothing is stored and the face is not enrolled. Blocklist and duplicate
+      #   screening run either way.
+      # @param vendor_data [String] Optional opaque identifier (your user id, email, UUID…) stored on the persisted
+      #   session and echoed back. Also used to exclude prior sessions with the same `vendor_data` from the
+      #   duplicate-face check, so re-verifying the same user does not raise `DUPLICATED_FACE`.
+      # @param metadata [Hash] Optional JSON object stored with the session (when `save_api_request=true`) and echoed
+      #   back. In multipart requests, send it as a JSON-encoded string field - it is parsed into an object.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::PassiveLivenessCheckResponse]
+      def check(
+        user_image:,
+        face_liveness_score_decline_threshold: OMIT,
+        rotate_image: OMIT,
+        save_api_request: OMIT,
+        vendor_data: OMIT,
+        metadata: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/passive-liveness/",
+          body: {
+            "user_image" => user_image,
+            "face_liveness_score_decline_threshold" => face_liveness_score_decline_threshold,
+            "rotate_image" => rotate_image,
+            "save_api_request" => save_api_request,
+            "vendor_data" => vendor_data,
+            "metadata" => metadata
+          },
+          encoding: :multipart,
+          file_fields: %w[user_image],
+          response: Types::PassiveLivenessCheckResponse,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end