didit-sdk 1.0.0

data/lib/didit/resources/monitoring_events.rb

@@ -0,0 +1,466 @@
+# Code generated by codegen from openapi/*.json. DO NOT EDIT.
+# frozen_string_literal: true
+
+module Didit
+  module Resources
+    # The +monitoring_events+ resource.
+    class MonitoringEvents < Didit::Resource
+      # Create monitoring event
+      #
+      # Send one non-monetary event (login, session, gameplay, bonus, affiliate, payment, dispute, security,
+      # responsible gambling or custom) from your backend. The event is validated against its category contract,
+      # stored, IP-enriched once per unique public address, and evaluated by your real-time event rules before the
+      # response returns; cross-subject and long-window rules run asynchronously (`correlation_pending: true`), and in
+      # a sandbox application no rules run. `event_id` is the idempotency key: the same `event_id` with the same
+      # `event_category`, `action_type`, `occurred_at`, `subject.vendor_data` and `payload` returns `200` with
+      # `idempotent_replay: true` and the stored outcome (other envelope fields are not compared), while different
+      # values return `409`. Event ingestion is opt-in per application: until it is switched on this endpoint returns
+      # `403` with `code: event_monitoring_disabled` and stores nothing. A scoped API key needs `transactions: write`.
+      # See [Event ingestion](https://docs.didit.me/transaction-monitoring/events) and [Rules on
+      # events](https://docs.didit.me/transaction-monitoring/event-rules); to send events from a browser or app, use
+      # [SDK event submission](https://docs.didit.me/transaction-monitoring/sdk-event-submission).
+      #
+      # +POST /v3/events/+
+      #
+      # @param event_id [String] Your identifier for the event, unique per application. It is the idempotency key:
+      #   resending the same `event_category`, `action_type`, `occurred_at`, `subject.vendor_data` and `payload` under
+      #   it is a replay, anything different is a conflict.
+      # @param event_category [String] Event category.
+      # @param action_type [String] What happened within the category. Open vocabulary; the managed actions listed in
+      #   [Event ingestion](https://docs.didit.me/transaction-monitoring/events) (for example `login`,
+      #   `deposit_completed`, `chargeback_opened`) unlock typed validation and managed rule fields. Leading and
+      #   trailing whitespace is trimmed.
+      # @param occurred_at [Time, String] When the event happened on your side, ISO 8601 (a value without an offset is
+      #   read as UTC). Must be no more than 7 days in the past and no more than 5 minutes in the future.
+      # @param subject [Hash] The user or company the event belongs to. It resolves to the user (or company) with this
+      #   `vendor_data` in your application; one is created when none exists.
+      # @param time_zone [String, nil] Time zone of the occurrence on your side, for example `Europe/Madrid`. Stored
+      #   with the event; not returned by the read endpoints.
+      # @param business [Hash] The business the event belongs to, when it differs from the subject. Only `vendor_data`
+      #   is read.
+      # @param session [Hash] Your session context for the event.
+      # @param device_context [Hash] Device and network context, stored as sent and returned by `GET
+      #   /v3/events/{event_uuid}/`. On this server lane Didit does not see the end user's connection, so the IP
+      #   enriched and used by rules is `network_context.ip_address` as you send it.
+      # @param transaction_context [Hash] Money context. Non-empty values here also satisfy the required payload keys
+      #   of the action.
+      # @param payload [Hash] The category's domain fields, at most 16384 bytes once JSON-encoded. Some actions
+      #   require keys (in `payload` or `transaction_context`): `gameplay.p2p_settlement` needs `game_id`,
+      #   `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role` and one of `hand_id`, `round_id`,
+      #   `match_id`; `gameplay.bet_placed` and `gameplay.bet_settled` need `game_id`; `payment.deposit_initiated`,
+      #   `payment...
+      # @param custom_values [Hash{String => String, Numeric, Boolean, nil}] Up to 100 keys of your own, addressable
+      #   from rules as `custom_values.<key>`. Values must be scalars (string, number, boolean or null); nested objects
+      #   and arrays are rejected.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::MonitoringEventIngestResult]
+      def create(
+        event_id:,
+        event_category:,
+        action_type:,
+        occurred_at:,
+        subject:,
+        time_zone: OMIT,
+        business: OMIT,
+        session: OMIT,
+        device_context: OMIT,
+        transaction_context: OMIT,
+        payload: OMIT,
+        custom_values: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/events/",
+          body: {
+            "event_id" => event_id,
+            "event_category" => event_category,
+            "action_type" => action_type,
+            "occurred_at" => occurred_at,
+            "subject" => subject,
+            "time_zone" => time_zone,
+            "business" => business,
+            "session" => session,
+            "device_context" => device_context,
+            "transaction_context" => transaction_context,
+            "payload" => payload,
+            "custom_values" => custom_values
+          },
+          response: Types::MonitoringEventIngestResult,
+          request_options: request_options
+        )
+      end
+
+      # Create monitoring events in batch
+      #
+      # Submit 1 to 500 events in one request, each in the same envelope as `POST /v3/events/`. Every item is
+      # validated, stored and evaluated on its own and gets its own outcome (`accepted`, `replayed` or `rejected`), so
+      # one malformed event never rolls back the others: the response is `201` when no item was rejected and `207`
+      # when at least one was, and both mean the request was processed. Send `{"events": [...]}`; a bare JSON array of
+      # events is also accepted. Event ingestion must be switched on for the application, otherwise the whole request
+      # returns `403` with `code: event_monitoring_disabled` and nothing is stored. A scoped API key needs
+      # `transactions: write`. See [Batches](https://docs.didit.me/transaction-monitoring/events#batches).
+      #
+      # +POST /v3/events/batch/+
+      #
+      # @param events [Array<Hash>] 1 to 500 events. Each item follows `MonitoringEventCreateRequest`, including the
+      #   7-day past and 5-minute future window on `occurred_at`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::MonitoringEventsCreateBatchResponse]
+      def create_batch(events:, request_options: nil)
+        @client.request(
+          :post,
+          "/v3/events/batch/",
+          body: {
+            "events" => events
+          },
+          response: Types::MonitoringEventsCreateBatchResponse,
+          request_options: request_options
+        )
+      end
+
+      # Mint monitoring SDK token
+      #
+      # Mint a short-lived device credential bound to one subject, so your web or mobile app can send that user's
+      # events straight to Didit without an API key. The app sends the returned `monitoring_token` in the
+      # `X-Monitoring-Token` header to the device lane (`POST /v1/events/` and `POST /v1/events/batch/`), where the
+      # subject is always overwritten with this `vendor_data`, events outside `allowed_event_categories` are rejected,
+      # each submitted event spends one use, and a request whose `Origin` does not equal `bind_to_origin` is refused.
+      # Call it from your backend only; minting creates the credential and nothing else (no user is created). Event
+      # ingestion must be switched on for the application, otherwise this endpoint returns `403` with `code:
+      # event_monitoring_disabled` instead of minting a credential that could never write. A scoped API key needs
+      # `transactions: write`. See [SDK event
+      # submission](https://docs.didit.me/transaction-monitoring/sdk-event-submission).
+      #
+      # +POST /v3/events/sdk-token/+
+      #
+      # @param vendor_data [String] Your id for the subject every event submitted with this credential belongs to.
+      # @param entity_type [String] `company` binds a company subject; any other value (default `individual`) binds an
+      #   individual.
+      # @param allowed_event_categories [Array<String>] Categories the credential may submit. Omit it or send `[]` to
+      #   allow every category.
+      # @param ttl_seconds [Integer] Lifetime of the credential in seconds.
+      # @param max_uses [Integer, nil] Number of events the credential may submit (a batch spends one use per event).
+      #   Send `null` for no cap within the lifetime.
+      # @param bind_to_origin [String, nil] When set, the browser `Origin` header of every device request must equal
+      #   this value exactly; a request without `Origin` is refused.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::MonitoringEventsCreateSdkTokenResponse]
+      def create_sdk_token(
+        vendor_data:,
+        entity_type: OMIT,
+        allowed_event_categories: OMIT,
+        ttl_seconds: OMIT,
+        max_uses: OMIT,
+        bind_to_origin: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :post,
+          "/v3/events/sdk-token/",
+          body: {
+            "vendor_data" => vendor_data,
+            "entity_type" => entity_type,
+            "allowed_event_categories" => allowed_event_categories,
+            "ttl_seconds" => ttl_seconds,
+            "max_uses" => max_uses,
+            "bind_to_origin" => bind_to_origin
+          },
+          response: Types::MonitoringEventsCreateSdkTokenResponse,
+          request_options: request_options
+        )
+      end
+
+      # Delete monitoring event
+      #
+      # Permanently delete one monitoring event together with its rule runs, notes and tag links, for example an event
+      # sent by mistake. After the `204` the event is gone from every read (retrieve returns `404`, and it no longer
+      # appears in the list or the subject timeline), the deletion is irreversible, and its `event_id` is free to be
+      # used for a new event. Not affected: the user or company the event resolved to, cases a rule opened, list
+      # entries a rule added, and the scores and statuses already applied to other events. To erase everything about a
+      # person or a company, delete the user or the company instead, which also deletes their events. A scoped API key
+      # needs `transactions: write`.
+      #
+      # +DELETE /v3/events/{event_uuid}/delete/+
+      #
+      # @param event_uuid [String] Didit identifier of the event (`event_uuid` from the create, batch, list or
+      #   timeline response), not your own `event_id`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [nil]
+      def delete(event_uuid, request_options: nil)
+        @client.request(
+          :delete,
+          "/v3/events/{event_uuid}/delete/",
+          path_params: { "event_uuid" => event_uuid },
+          request_options: request_options
+        )
+      end
+
+      # List monitoring events
+      #
+      # List the monitoring events stored for your application, newest `occurred_at` first, with optional filters that
+      # combine with AND. Multi-value filters (`event_category`, `action_type`, `status`, `retention_class`) repeat
+      # the parameter and match any of the values; the other filters are exact matches, and unknown values simply
+      # return no events. Each result is a summary: call `GET /v3/events/{event_uuid}/` for the payload, device
+      # context, IP enrichment and rule evidence, and prefer `GET /v3/events/subjects/{vendor_data}/` for one
+      # subject's history. Reads work whether or not event ingestion is switched on. A scoped API key needs
+      # `transactions: read`. See [Event ingestion](https://docs.didit.me/transaction-monitoring/events).
+      #
+      # +GET /v3/events/+
+      #
+      # @param limit [Integer] Maximum number of events per page. Defaults to 50. Values above 1000000 return `400`; a
+      #   non-numeric, zero or negative value falls back to 50.
+      # @param offset [Integer] Number of events to skip. Defaults to 0. Prefer following the `next` URL from the
+      #   response.
+      # @param event_category [Array<String>] Only events in these categories. Repeat the parameter for several values
+      #   (`?event_category=payment&event_category=dispute`); an event matching any of them is returned.
+      # @param action_type [Array<String>] Only events with these action types (exact, case-sensitive). Repeat for
+      #   several values.
+      # @param status [Array<String>] Only events with these statuses. Repeat for several values.
+      # @param retention_class [Array<String>] Only events in these retention classes. Repeat for several values.
+      # @param subject_vendor_data [String] Exact match on the subject's `vendor_data`. The same id can name an
+      #   individual and a company; add `subject_entity_type` to pick one, or use `GET
+      #   /v3/events/subjects/{vendor_data}/`.
+      # @param subject_entity_type [String] `company` returns only events of company subjects; any other non-empty
+      #   value (for example `individual`) returns only events of individuals. Omit it to return both.
+      # @param business_vendor_data [String] Exact match on the `business.vendor_data` sent with the event.
+      # @param session_id [String] Exact match on `session.session_id`.
+      # @param device_fingerprint [String] Exact match on `device_context.fingerprint`.
+      # @param ip_address [String] Exact match on the event's IP address.
+      # @param game_id [String] Exact match on the promoted `game_id`.
+      # @param round_id [String] Exact match on the promoted `round_id`.
+      # @param affiliate_code [String] Exact match on the promoted `affiliate_code`.
+      # @param payment_reference_id [String] Exact match on the payment reference (from
+      #   `transaction_context.payment_reference_id` or `payload.payment_reference_id`).
+      # @param counterparty_vendor_data [String] Exact match on the promoted `counterparty_vendor_data`.
+      # @param matched_only [Boolean] `true` (also `1` or `yes`, case-insensitive) returns only events at least one
+      #   rule matched (`rules_matched_count` above 0). Any other value is ignored.
+      # @param occurred_from [Time, String] Only events with `occurred_at` at or after this instant (inclusive). Send
+      #   an ISO 8601 value: `2026-10-01T00:00:00Z`, an explicit offset with the `+` percent-encoded
+      #   (`2026-10-01T02:00:00%2B02:00`; an unencoded `+` is decoded as a space and the value no longer parses), or a
+      #   date alone (`2026-10-01`), which means 00:00:00 UTC of that day. A value without an offset is read as UTC.
+      #   Values in any othe...
+      # @param occurred_to [Time, String] Only events with `occurred_at` at or before this instant (inclusive). A date
+      #   alone means the start of that day, so `occurred_to=2026-10-15` excludes the rest of 15 October; send
+      #   `2026-10-15T23:59:59Z` to include it. Send an ISO 8601 value: `2026-10-01T00:00:00Z`, an explicit offset with
+      #   the `+` percent-encoded (`2026-10-01T02:00:00%2B02:00`; an unencoded `+` is decoded as a space and the value
+      #   no...
+      # @param search [String] Case-insensitive substring match on `event_id`, `action_type`, `subject_vendor_data` or
+      #   `counterparty_vendor_data`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::MonitoringEvent>]
+      def list(
+        limit: OMIT,
+        offset: OMIT,
+        event_category: OMIT,
+        action_type: OMIT,
+        status: OMIT,
+        retention_class: OMIT,
+        subject_vendor_data: OMIT,
+        subject_entity_type: OMIT,
+        business_vendor_data: OMIT,
+        session_id: OMIT,
+        device_fingerprint: OMIT,
+        ip_address: OMIT,
+        game_id: OMIT,
+        round_id: OMIT,
+        affiliate_code: OMIT,
+        payment_reference_id: OMIT,
+        counterparty_vendor_data: OMIT,
+        matched_only: OMIT,
+        occurred_from: OMIT,
+        occurred_to: OMIT,
+        search: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :get,
+          "/v3/events/",
+          query: {
+            "limit" => limit,
+            "offset" => offset,
+            "event_category" => event_category,
+            "action_type" => action_type,
+            "status" => status,
+            "retention_class" => retention_class,
+            "subject_vendor_data" => subject_vendor_data,
+            "subject_entity_type" => subject_entity_type,
+            "business_vendor_data" => business_vendor_data,
+            "session_id" => session_id,
+            "device_fingerprint" => device_fingerprint,
+            "ip_address" => ip_address,
+            "game_id" => game_id,
+            "round_id" => round_id,
+            "affiliate_code" => affiliate_code,
+            "payment_reference_id" => payment_reference_id,
+            "counterparty_vendor_data" => counterparty_vendor_data,
+            "matched_only" => matched_only,
+            "occurred_from" => occurred_from,
+            "occurred_to" => occurred_to,
+            "search" => search
+          },
+          page: Types::MonitoringEvent,
+          request_options: request_options
+        )
+      end
+
+      # Get monitoring event
+      #
+      # Retrieve one monitoring event with everything the list returns plus the payload, custom values, device
+      # context, field provenance (`field_sources`), the promoted domain fields, `expires_at`, every matching rule run
+      # with its evidence, the IP enrichment and the tags rules attached. While `correlation_pending` is `true` an
+      # asynchronous rule still has to run; read the event again a few minutes later for the final `status`, `score`
+      # and `rule_runs`. Reads work whether or not event ingestion is switched on. A scoped API key needs
+      # `transactions: read`. See [Evidence](https://docs.didit.me/transaction-monitoring/event-rules#evidence) and
+      # [IP enrichment](https://docs.didit.me/transaction-monitoring/ip-enrichment).
+      #
+      # +GET /v3/events/{event_uuid}/+
+      #
+      # @param event_uuid [String] Didit identifier of the event (`event_uuid` from the create, batch, list or
+      #   timeline response), not your own `event_id`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::MonitoringEventDetail]
+      def retrieve(event_uuid, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/events/{event_uuid}/",
+          path_params: { "event_uuid" => event_uuid },
+          response: Types::MonitoringEventDetail,
+          request_options: request_options
+        )
+      end
+
+      # Get event enrichment metrics
+      #
+      # Return the event ingestion and IP-enrichment counters of your application for a period, summed over every lane
+      # (server, batch and device), so you can watch event volume and confirm that enrichment is resolved once per
+      # unique address rather than once per event. The period covers today plus the previous `days` days, counted by
+      # UTC calendar date. The three ratios are null when their denominator is zero. A scoped API key needs
+      # `transactions: read`. See [IP enrichment](https://docs.didit.me/transaction-monitoring/events#ip-enrichment).
+      #
+      # +GET /v3/events/enrichment-metrics/+
+      #
+      # @param days [Integer] Length of the period in days. Defaults to 30; values are clamped to 1 to 365, and a
+      #   non-integer value falls back to 30. The value applied is returned as `period_days`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Types::MonitoringEventsRetrieveEnrichmentMetricsResponse]
+      def retrieve_enrichment_metrics(days: OMIT, request_options: nil)
+        @client.request(
+          :get,
+          "/v3/events/enrichment-metrics/",
+          query: {
+            "days" => days
+          },
+          response: Types::MonitoringEventsRetrieveEnrichmentMetricsResponse,
+          request_options: request_options
+        )
+      end
+
+      # Get subject event timeline
+      #
+      # List every monitoring event of one subject, newest `occurred_at` first. A `vendor_data` is unique only within
+      # an entity type, so the same id can name an individual and a company: `entity_type` picks which timeline you
+      # get, and it defaults to `individual`, so a company's events need `entity_type=company`. The filters of `GET
+      # /v3/events/` apply on top, and a `vendor_data` with no events returns an empty page rather than `404`. A
+      # scoped API key needs `transactions: read`. See [Reading events
+      # back](https://docs.didit.me/transaction-monitoring/events#reading-events-back).
+      #
+      # +GET /v3/events/subjects/{vendor_data}/+
+      #
+      # @param vendor_data [String] Your id for the subject (`subject.vendor_data` of its events). URL-encode it; a
+      #   value containing `/` cannot be addressed by this endpoint.
+      # @param entity_type [String] `company` returns the company with this `vendor_data`; any other value, or none,
+      #   returns the individual. `subject_entity_type` is accepted as an alias when `entity_type` is absent.
+      # @param limit [Integer] Maximum number of events per page. Defaults to 50. Values above 1000000 return `400`; a
+      #   non-numeric, zero or negative value falls back to 50.
+      # @param offset [Integer] Number of events to skip. Defaults to 0. Prefer following the `next` URL from the
+      #   response.
+      # @param event_category [Array<String>] Only events in these categories. Repeat the parameter for several values
+      #   (`?event_category=payment&event_category=dispute`); an event matching any of them is returned.
+      # @param action_type [Array<String>] Only events with these action types (exact, case-sensitive). Repeat for
+      #   several values.
+      # @param status [Array<String>] Only events with these statuses. Repeat for several values.
+      # @param retention_class [Array<String>] Only events in these retention classes. Repeat for several values.
+      # @param business_vendor_data [String] Exact match on the `business.vendor_data` sent with the event.
+      # @param session_id [String] Exact match on `session.session_id`.
+      # @param device_fingerprint [String] Exact match on `device_context.fingerprint`.
+      # @param ip_address [String] Exact match on the event's IP address.
+      # @param game_id [String] Exact match on the promoted `game_id`.
+      # @param round_id [String] Exact match on the promoted `round_id`.
+      # @param affiliate_code [String] Exact match on the promoted `affiliate_code`.
+      # @param payment_reference_id [String] Exact match on the payment reference (from
+      #   `transaction_context.payment_reference_id` or `payload.payment_reference_id`).
+      # @param counterparty_vendor_data [String] Exact match on the promoted `counterparty_vendor_data`.
+      # @param matched_only [Boolean] `true` (also `1` or `yes`, case-insensitive) returns only events at least one
+      #   rule matched (`rules_matched_count` above 0). Any other value is ignored.
+      # @param occurred_from [Time, String] Only events with `occurred_at` at or after this instant (inclusive). Send
+      #   an ISO 8601 value: `2026-10-01T00:00:00Z`, an explicit offset with the `+` percent-encoded
+      #   (`2026-10-01T02:00:00%2B02:00`; an unencoded `+` is decoded as a space and the value no longer parses), or a
+      #   date alone (`2026-10-01`), which means 00:00:00 UTC of that day. A value without an offset is read as UTC.
+      #   Values in any othe...
+      # @param occurred_to [Time, String] Only events with `occurred_at` at or before this instant (inclusive). A date
+      #   alone means the start of that day, so `occurred_to=2026-10-15` excludes the rest of 15 October; send
+      #   `2026-10-15T23:59:59Z` to include it. Send an ISO 8601 value: `2026-10-01T00:00:00Z`, an explicit offset with
+      #   the `+` percent-encoded (`2026-10-01T02:00:00%2B02:00`; an unencoded `+` is decoded as a space and the value
+      #   no...
+      # @param search [String] Case-insensitive substring match on `event_id`, `action_type`, `subject_vendor_data` or
+      #   `counterparty_vendor_data`.
+      # @param request_options [Hash, nil] :timeout, :max_retries, :extra_headers, :extra_query, :extra_body
+      # @return [Didit::Page<Didit::Types::MonitoringEvent>]
+      def retrieve_subject_timeline(
+        vendor_data,
+        entity_type: OMIT,
+        limit: OMIT,
+        offset: OMIT,
+        event_category: OMIT,
+        action_type: OMIT,
+        status: OMIT,
+        retention_class: OMIT,
+        business_vendor_data: OMIT,
+        session_id: OMIT,
+        device_fingerprint: OMIT,
+        ip_address: OMIT,
+        game_id: OMIT,
+        round_id: OMIT,
+        affiliate_code: OMIT,
+        payment_reference_id: OMIT,
+        counterparty_vendor_data: OMIT,
+        matched_only: OMIT,
+        occurred_from: OMIT,
+        occurred_to: OMIT,
+        search: OMIT,
+        request_options: nil
+      )
+        @client.request(
+          :get,
+          "/v3/events/subjects/{vendor_data}/",
+          path_params: { "vendor_data" => vendor_data },
+          query: {
+            "entity_type" => entity_type,
+            "limit" => limit,
+            "offset" => offset,
+            "event_category" => event_category,
+            "action_type" => action_type,
+            "status" => status,
+            "retention_class" => retention_class,
+            "business_vendor_data" => business_vendor_data,
+            "session_id" => session_id,
+            "device_fingerprint" => device_fingerprint,
+            "ip_address" => ip_address,
+            "game_id" => game_id,
+            "round_id" => round_id,
+            "affiliate_code" => affiliate_code,
+            "payment_reference_id" => payment_reference_id,
+            "counterparty_vendor_data" => counterparty_vendor_data,
+            "matched_only" => matched_only,
+            "occurred_from" => occurred_from,
+            "occurred_to" => occurred_to,
+            "search" => search
+          },
+          page: Types::MonitoringEvent,
+          request_options: request_options
+        )
+      end
+    end
+  end
+end