prelude-sdk 0.2.0 → 0.4.0

data/rbi/prelude_sdk/models/verification_create_response.rbi

@@ -24,6 +24,13 @@ module PreludeSDK
       attr_accessor :verification_method
 
       # The status of the verification.
+      #
+      # - `success` - A new verification window was created.
+      # - `retry` - A new attempt was created for an existing verification window.
+      # - `challenged` - The verification is suspicious and is restricted to non-SMS and
+      #   non-voice channels only. This mode must be enabled for your customer account
+      #   by Prelude support.
+      # - `blocked` - The verification was blocked.
       sig do
         returns(
           PreludeSDK::Models::VerificationCreateResponse::Status::TaggedSymbol
@@ -107,6 +114,51 @@ module PreludeSDK
       sig { params(request_id: String).void }
       attr_writer :request_id
 
+      # The risk factors that contributed to the verification being blocked. Only
+      # present when status is "blocked" and the anti-fraud system detected specific
+      # risk signals.
+      #
+      # - `behavioral_pattern` - The phone number past behavior during verification
+      #   flows exhibits suspicious patterns.
+      # - `device_attribute` - The device exhibits characteristics associated with
+      #   suspicious activity patterns.
+      # - `fraud_database` - The phone number has been flagged as suspicious in one or
+      #   more of our fraud databases.
+      # - `location_discrepancy` - The phone number prefix and IP address discrepancy
+      #   indicates potential fraud.
+      # - `network_fingerprint` - The network connection exhibits characteristics
+      #   associated with suspicious activity patterns.
+      # - `poor_conversion_history` - The phone number has a history of poorly
+      #   converting to a verified phone number.
+      # - `prefix_concentration` - The phone number is part of a range known to be
+      #   associated with suspicious activity patterns.
+      # - `suspected_request_tampering` - The SDK signature is invalid and the request
+      #   is considered to be tampered with.
+      # - `suspicious_ip_address` - The IP address is deemed to be associated with
+      #   suspicious activity patterns.
+      # - `temporary_phone_number` - The phone number is known to be a temporary or
+      #   disposable number.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[
+              PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+            ]
+          )
+        )
+      end
+      attr_reader :risk_factors
+
+      sig do
+        params(
+          risk_factors:
+            T::Array[
+              PreludeSDK::Models::VerificationCreateResponse::RiskFactor::OrSymbol
+            ]
+        ).void
+      end
+      attr_writer :risk_factors
+
       # The silent verification specific properties.
       sig do
         returns(
@@ -138,6 +190,10 @@ module PreludeSDK
           reason:
             PreludeSDK::Models::VerificationCreateResponse::Reason::OrSymbol,
           request_id: String,
+          risk_factors:
+            T::Array[
+              PreludeSDK::Models::VerificationCreateResponse::RiskFactor::OrSymbol
+            ],
           silent: PreludeSDK::Models::VerificationCreateResponse::Silent::OrHash
         ).returns(T.attached_class)
       end
@@ -147,6 +203,13 @@ module PreludeSDK
         # The method used for verifying this phone number.
         verification_method:,
         # The status of the verification.
+        #
+        # - `success` - A new verification window was created.
+        # - `retry` - A new attempt was created for an existing verification window.
+        # - `challenged` - The verification is suspicious and is restricted to non-SMS and
+        #   non-voice channels only. This mode must be enabled for your customer account
+        #   by Prelude support.
+        # - `blocked` - The verification was blocked.
         status:,
         # The ordered sequence of channels to be used for verification
         channels: nil,
@@ -169,6 +232,31 @@ module PreludeSDK
         #   anti-fraud system.
         reason: nil,
         request_id: nil,
+        # The risk factors that contributed to the verification being blocked. Only
+        # present when status is "blocked" and the anti-fraud system detected specific
+        # risk signals.
+        #
+        # - `behavioral_pattern` - The phone number past behavior during verification
+        #   flows exhibits suspicious patterns.
+        # - `device_attribute` - The device exhibits characteristics associated with
+        #   suspicious activity patterns.
+        # - `fraud_database` - The phone number has been flagged as suspicious in one or
+        #   more of our fraud databases.
+        # - `location_discrepancy` - The phone number prefix and IP address discrepancy
+        #   indicates potential fraud.
+        # - `network_fingerprint` - The network connection exhibits characteristics
+        #   associated with suspicious activity patterns.
+        # - `poor_conversion_history` - The phone number has a history of poorly
+        #   converting to a verified phone number.
+        # - `prefix_concentration` - The phone number is part of a range known to be
+        #   associated with suspicious activity patterns.
+        # - `suspected_request_tampering` - The SDK signature is invalid and the request
+        #   is considered to be tampered with.
+        # - `suspicious_ip_address` - The IP address is deemed to be associated with
+        #   suspicious activity patterns.
+        # - `temporary_phone_number` - The phone number is known to be a temporary or
+        #   disposable number.
+        risk_factors: nil,
         # The silent verification specific properties.
         silent: nil
       )
@@ -190,6 +278,10 @@ module PreludeSDK
             reason:
               PreludeSDK::Models::VerificationCreateResponse::Reason::TaggedSymbol,
             request_id: String,
+            risk_factors:
+              T::Array[
+                PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+              ],
             silent: PreludeSDK::Models::VerificationCreateResponse::Silent
           }
         )
@@ -243,6 +335,13 @@ module PreludeSDK
       end
 
       # The status of the verification.
+      #
+      # - `success` - A new verification window was created.
+      # - `retry` - A new attempt was created for an existing verification window.
+      # - `challenged` - The verification is suspicious and is restricted to non-SMS and
+      #   non-voice channels only. This mode must be enabled for your customer account
+      #   by Prelude support.
+      # - `blocked` - The verification was blocked.
       module Status
         extend PreludeSDK::Internal::Type::Enum
 
@@ -265,6 +364,11 @@ module PreludeSDK
             :retry,
             PreludeSDK::Models::VerificationCreateResponse::Status::TaggedSymbol
           )
+        CHALLENGED =
+          T.let(
+            :challenged,
+            PreludeSDK::Models::VerificationCreateResponse::Status::TaggedSymbol
+          )
         BLOCKED =
           T.let(
             :blocked,
@@ -451,6 +555,80 @@ module PreludeSDK
         end
       end
 
+      module RiskFactor
+        extend PreludeSDK::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              PreludeSDK::Models::VerificationCreateResponse::RiskFactor
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        BEHAVIORAL_PATTERN =
+          T.let(
+            :behavioral_pattern,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        DEVICE_ATTRIBUTE =
+          T.let(
+            :device_attribute,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        FRAUD_DATABASE =
+          T.let(
+            :fraud_database,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        LOCATION_DISCREPANCY =
+          T.let(
+            :location_discrepancy,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        NETWORK_FINGERPRINT =
+          T.let(
+            :network_fingerprint,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        POOR_CONVERSION_HISTORY =
+          T.let(
+            :poor_conversion_history,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        PREFIX_CONCENTRATION =
+          T.let(
+            :prefix_concentration,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        SUSPECTED_REQUEST_TAMPERING =
+          T.let(
+            :suspected_request_tampering,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        SUSPICIOUS_IP_ADDRESS =
+          T.let(
+            :suspicious_ip_address,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+        TEMPORARY_PHONE_NUMBER =
+          T.let(
+            :temporary_phone_number,
+            PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              PreludeSDK::Models::VerificationCreateResponse::RiskFactor::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+
       class Silent < PreludeSDK::Internal::Type::BaseModel
         OrHash =
           T.type_alias do

data/rbi/prelude_sdk/models/verification_management_delete_phone_number_params.rbi

@@ -14,17 +14,27 @@ module PreludeSDK
           )
         end
 
+      sig do
+        returns(
+          PreludeSDK::VerificationManagementDeletePhoneNumberParams::Action::OrSymbol
+        )
+      end
+      attr_accessor :action
+
       # An E.164 formatted phone number to remove from the list.
       sig { returns(String) }
       attr_accessor :phone_number
 
       sig do
         params(
+          action:
+            PreludeSDK::VerificationManagementDeletePhoneNumberParams::Action::OrSymbol,
           phone_number: String,
           request_options: PreludeSDK::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        action:,
         # An E.164 formatted phone number to remove from the list.
         phone_number:,
         request_options: {}
@@ -33,7 +43,12 @@ module PreludeSDK
 
       sig do
         override.returns(
-          { phone_number: String, request_options: PreludeSDK::RequestOptions }
+          {
+            action:
+              PreludeSDK::VerificationManagementDeletePhoneNumberParams::Action::OrSymbol,
+            phone_number: String,
+            request_options: PreludeSDK::RequestOptions
+          }
         )
       end
       def to_hash

data/rbi/prelude_sdk/models/verification_management_list_phone_numbers_params.rbi

@@ -15,14 +15,31 @@ module PreludeSDK
         end
 
       sig do
-        params(request_options: PreludeSDK::RequestOptions::OrHash).returns(
-          T.attached_class
+        returns(
+          PreludeSDK::VerificationManagementListPhoneNumbersParams::Action::OrSymbol
         )
       end
-      def self.new(request_options: {})
+      attr_accessor :action
+
+      sig do
+        params(
+          action:
+            PreludeSDK::VerificationManagementListPhoneNumbersParams::Action::OrSymbol,
+          request_options: PreludeSDK::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(action:, request_options: {})
       end
 
-      sig { override.returns({ request_options: PreludeSDK::RequestOptions }) }
+      sig do
+        override.returns(
+          {
+            action:
+              PreludeSDK::VerificationManagementListPhoneNumbersParams::Action::OrSymbol,
+            request_options: PreludeSDK::RequestOptions
+          }
+        )
+      end
       def to_hash
       end
 

data/rbi/prelude_sdk/models/verification_management_set_phone_number_params.rbi

@@ -14,17 +14,27 @@ module PreludeSDK
           )
         end
 
+      sig do
+        returns(
+          PreludeSDK::VerificationManagementSetPhoneNumberParams::Action::OrSymbol
+        )
+      end
+      attr_accessor :action
+
       # An E.164 formatted phone number to add to the list.
       sig { returns(String) }
       attr_accessor :phone_number
 
       sig do
         params(
+          action:
+            PreludeSDK::VerificationManagementSetPhoneNumberParams::Action::OrSymbol,
           phone_number: String,
           request_options: PreludeSDK::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        action:,
         # An E.164 formatted phone number to add to the list.
         phone_number:,
         request_options: {}
@@ -33,7 +43,12 @@ module PreludeSDK
 
       sig do
         override.returns(
-          { phone_number: String, request_options: PreludeSDK::RequestOptions }
+          {
+            action:
+              PreludeSDK::VerificationManagementSetPhoneNumberParams::Action::OrSymbol,
+            phone_number: String,
+            request_options: PreludeSDK::RequestOptions
+          }
         )
       end
       def to_hash

data/rbi/prelude_sdk/models/watch_predict_params.rbi

@@ -206,8 +206,9 @@ module PreludeSDK
         sig { params(app_version: String).void }
         attr_writer :app_version
 
-        # The unique identifier for the user's device. For Android, this corresponds to
-        # the `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`.
+        # A unique ID for the user's device. You should ensure that each user device has a
+        # unique `device_id` value. Ideally, for Android, this corresponds to the
+        # `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`.
         sig { returns(T.nilable(String)) }
         attr_reader :device_id
 
@@ -239,15 +240,18 @@ module PreludeSDK
         end
         attr_writer :device_platform
 
-        # The IP address of the user's device.
+        # The public IP v4 or v6 address of the end-user's device. You should collect this
+        # from your backend. If your backend is behind a proxy, use the `X-Forwarded-For`,
+        # `Forwarded`, `True-Client-IP`, `CF-Connecting-IP` or an equivalent header to get
+        # the actual public IP of the end-user's device.
         sig { returns(T.nilable(String)) }
         attr_reader :ip
 
         sig { params(ip: String).void }
         attr_writer :ip
 
-        # This signal should provide a higher level of trust, indicating that the user is
-        # genuine. Contact us to discuss your use case. For more details, refer to
+        # This signal should indicate a higher level of trust, explicitly stating that the
+        # user is genuine. Contact us to discuss your use case. For more details, refer to
         # [Signals](/verify/v2/documentation/prevent-fraud#signals).
         sig { returns(T.nilable(T::Boolean)) }
         attr_reader :is_trusted_user
@@ -255,9 +259,9 @@ module PreludeSDK
         sig { params(is_trusted_user: T::Boolean).void }
         attr_writer :is_trusted_user
 
-        # The JA4 fingerprint observed for the connection. Prelude will infer it
-        # automatically when requests go through our client SDK (which uses Prelude's
-        # edge), but you can also provide it explicitly if you terminate TLS yourself.
+        # The JA4 fingerprint observed for the end-user's connection. Prelude will infer
+        # it automatically when you use our Frontend SDKs (which use Prelude's edge
+        # network), but you can also forward the value if you terminate TLS yourself.
         sig { returns(T.nilable(String)) }
         attr_reader :ja4_fingerprint
 
@@ -299,22 +303,26 @@ module PreludeSDK
         def self.new(
           # The version of your application.
           app_version: nil,
-          # The unique identifier for the user's device. For Android, this corresponds to
-          # the `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`.
+          # A unique ID for the user's device. You should ensure that each user device has a
+          # unique `device_id` value. Ideally, for Android, this corresponds to the
+          # `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`.
           device_id: nil,
           # The model of the user's device.
           device_model: nil,
           # The type of the user's device.
           device_platform: nil,
-          # The IP address of the user's device.
+          # The public IP v4 or v6 address of the end-user's device. You should collect this
+          # from your backend. If your backend is behind a proxy, use the `X-Forwarded-For`,
+          # `Forwarded`, `True-Client-IP`, `CF-Connecting-IP` or an equivalent header to get
+          # the actual public IP of the end-user's device.
           ip: nil,
-          # This signal should provide a higher level of trust, indicating that the user is
-          # genuine. Contact us to discuss your use case. For more details, refer to
+          # This signal should indicate a higher level of trust, explicitly stating that the
+          # user is genuine. Contact us to discuss your use case. For more details, refer to
           # [Signals](/verify/v2/documentation/prevent-fraud#signals).
           is_trusted_user: nil,
-          # The JA4 fingerprint observed for the connection. Prelude will infer it
-          # automatically when requests go through our client SDK (which uses Prelude's
-          # edge), but you can also provide it explicitly if you terminate TLS yourself.
+          # The JA4 fingerprint observed for the end-user's connection. Prelude will infer
+          # it automatically when you use our Frontend SDKs (which use Prelude's edge
+          # network), but you can also forward the value if you terminate TLS yourself.
           ja4_fingerprint: nil,
           # The version of the user's device operating system.
           os_version: nil,

data/rbi/prelude_sdk/models/watch_predict_response.rbi

@@ -28,12 +28,61 @@ module PreludeSDK
       sig { returns(String) }
       attr_accessor :request_id
 
+      # The risk factors that contributed to the suspicious prediction. Only present
+      # when prediction is "suspicious" and the anti-fraud system detected specific risk
+      # signals.
+      #
+      # - `behavioral_pattern` - The phone number past behavior during verification
+      #   flows exhibits suspicious patterns.
+      # - `device_attribute` - The device exhibits characteristics associated with
+      #   suspicious activity patterns.
+      # - `fraud_database` - The phone number has been flagged as suspicious in one or
+      #   more of our fraud databases.
+      # - `location_discrepancy` - The phone number prefix and IP address discrepancy
+      #   indicates potential fraud.
+      # - `network_fingerprint` - The network connection exhibits characteristics
+      #   associated with suspicious activity patterns.
+      # - `poor_conversion_history` - The phone number has a history of poorly
+      #   converting to a verified phone number.
+      # - `prefix_concentration` - The phone number is part of a range known to be
+      #   associated with suspicious activity patterns.
+      # - `suspected_request_tampering` - The SDK signature is invalid and the request
+      #   is considered to be tampered with.
+      # - `suspicious_ip_address` - The IP address is deemed to be associated with
+      #   suspicious activity patterns.
+      # - `temporary_phone_number` - The phone number is known to be a temporary or
+      #   disposable number.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[
+              PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+            ]
+          )
+        )
+      end
+      attr_reader :risk_factors
+
+      sig do
+        params(
+          risk_factors:
+            T::Array[
+              PreludeSDK::Models::WatchPredictResponse::RiskFactor::OrSymbol
+            ]
+        ).void
+      end
+      attr_writer :risk_factors
+
       sig do
         params(
           id: String,
           prediction:
             PreludeSDK::Models::WatchPredictResponse::Prediction::OrSymbol,
-          request_id: String
+          request_id: String,
+          risk_factors:
+            T::Array[
+              PreludeSDK::Models::WatchPredictResponse::RiskFactor::OrSymbol
+            ]
         ).returns(T.attached_class)
       end
       def self.new(
@@ -43,7 +92,32 @@ module PreludeSDK
         prediction:,
         # A string that identifies this specific request. Report it back to us to help us
         # diagnose your issues.
-        request_id:
+        request_id:,
+        # The risk factors that contributed to the suspicious prediction. Only present
+        # when prediction is "suspicious" and the anti-fraud system detected specific risk
+        # signals.
+        #
+        # - `behavioral_pattern` - The phone number past behavior during verification
+        #   flows exhibits suspicious patterns.
+        # - `device_attribute` - The device exhibits characteristics associated with
+        #   suspicious activity patterns.
+        # - `fraud_database` - The phone number has been flagged as suspicious in one or
+        #   more of our fraud databases.
+        # - `location_discrepancy` - The phone number prefix and IP address discrepancy
+        #   indicates potential fraud.
+        # - `network_fingerprint` - The network connection exhibits characteristics
+        #   associated with suspicious activity patterns.
+        # - `poor_conversion_history` - The phone number has a history of poorly
+        #   converting to a verified phone number.
+        # - `prefix_concentration` - The phone number is part of a range known to be
+        #   associated with suspicious activity patterns.
+        # - `suspected_request_tampering` - The SDK signature is invalid and the request
+        #   is considered to be tampered with.
+        # - `suspicious_ip_address` - The IP address is deemed to be associated with
+        #   suspicious activity patterns.
+        # - `temporary_phone_number` - The phone number is known to be a temporary or
+        #   disposable number.
+        risk_factors: nil
       )
       end
 
@@ -53,7 +127,11 @@ module PreludeSDK
             id: String,
             prediction:
               PreludeSDK::Models::WatchPredictResponse::Prediction::TaggedSymbol,
-            request_id: String
+            request_id: String,
+            risk_factors:
+              T::Array[
+                PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+              ]
           }
         )
       end
@@ -91,6 +169,77 @@ module PreludeSDK
         def self.values
         end
       end
+
+      module RiskFactor
+        extend PreludeSDK::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, PreludeSDK::Models::WatchPredictResponse::RiskFactor)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        BEHAVIORAL_PATTERN =
+          T.let(
+            :behavioral_pattern,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        DEVICE_ATTRIBUTE =
+          T.let(
+            :device_attribute,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        FRAUD_DATABASE =
+          T.let(
+            :fraud_database,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        LOCATION_DISCREPANCY =
+          T.let(
+            :location_discrepancy,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        NETWORK_FINGERPRINT =
+          T.let(
+            :network_fingerprint,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        POOR_CONVERSION_HISTORY =
+          T.let(
+            :poor_conversion_history,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        PREFIX_CONCENTRATION =
+          T.let(
+            :prefix_concentration,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        SUSPECTED_REQUEST_TAMPERING =
+          T.let(
+            :suspected_request_tampering,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        SUSPICIOUS_IP_ADDRESS =
+          T.let(
+            :suspicious_ip_address,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+        TEMPORARY_PHONE_NUMBER =
+          T.let(
+            :temporary_phone_number,
+            PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              PreludeSDK::Models::WatchPredictResponse::RiskFactor::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
     end
   end
 end

data/rbi/prelude_sdk/models/watch_send_events_params.rbi

@@ -14,7 +14,8 @@ module PreludeSDK
           )
         end
 
-      # A list of events to dispatch.
+      # A list of events to dispatch. A maximum of 100 events can be sent in a single
+      # request.
       sig { returns(T::Array[PreludeSDK::WatchSendEventsParams::Event]) }
       attr_accessor :events
 
@@ -25,7 +26,8 @@ module PreludeSDK
         ).returns(T.attached_class)
       end
       def self.new(
-        # A list of events to dispatch.
+        # A list of events to dispatch. A maximum of 100 events can be sent in a single
+        # request.
         events:,
         request_options: {}
       )