prelude-sdk 0.2.0 → 0.3.0

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_feedbacks_params.rbi

@@ -72,13 +72,6 @@ module PreludeSDK
         end
         attr_accessor :type
 
-        # The identifier of the dispatch that came from the front-end SDK.
-        sig { returns(T.nilable(String)) }
-        attr_reader :dispatch_id
-
-        sig { params(dispatch_id: String).void }
-        attr_writer :dispatch_id
-
         # The metadata for this feedback.
         sig do
           returns(
@@ -95,34 +88,14 @@ module PreludeSDK
         end
         attr_writer :metadata
 
-        # The signals used for anti-fraud. For more details, refer to
-        # [Signals](/verify/v2/documentation/prevent-fraud#signals).
-        sig do
-          returns(
-            T.nilable(PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals)
-          )
-        end
-        attr_reader :signals
-
-        sig do
-          params(
-            signals:
-              PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::OrHash
-          ).void
-        end
-        attr_writer :signals
-
         sig do
           params(
             target:
               PreludeSDK::WatchSendFeedbacksParams::Feedback::Target::OrHash,
             type:
               PreludeSDK::WatchSendFeedbacksParams::Feedback::Type::OrSymbol,
-            dispatch_id: String,
             metadata:
-              PreludeSDK::WatchSendFeedbacksParams::Feedback::Metadata::OrHash,
-            signals:
-              PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::OrHash
+              PreludeSDK::WatchSendFeedbacksParams::Feedback::Metadata::OrHash
           ).returns(T.attached_class)
         end
         def self.new(
@@ -130,13 +103,8 @@ module PreludeSDK
           target:,
           # The type of feedback.
           type:,
-          # The identifier of the dispatch that came from the front-end SDK.
-          dispatch_id: nil,
           # The metadata for this feedback.
-          metadata: nil,
-          # The signals used for anti-fraud. For more details, refer to
-          # [Signals](/verify/v2/documentation/prevent-fraud#signals).
-          signals: nil
+          metadata: nil
         )
         end
 
@@ -146,10 +114,7 @@ module PreludeSDK
               target: PreludeSDK::WatchSendFeedbacksParams::Feedback::Target,
               type:
                 PreludeSDK::WatchSendFeedbacksParams::Feedback::Type::OrSymbol,
-              dispatch_id: String,
-              metadata:
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Metadata,
-              signals: PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals
+              metadata: PreludeSDK::WatchSendFeedbacksParams::Feedback::Metadata
             }
           )
         end
@@ -306,211 +271,6 @@ module PreludeSDK
           def to_hash
           end
         end
-
-        class Signals < PreludeSDK::Internal::Type::BaseModel
-          OrHash =
-            T.type_alias do
-              T.any(
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals,
-                PreludeSDK::Internal::AnyHash
-              )
-            end
-
-          # The version of your application.
-          sig { returns(T.nilable(String)) }
-          attr_reader :app_version
-
-          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`.
-          sig { returns(T.nilable(String)) }
-          attr_reader :device_id
-
-          sig { params(device_id: String).void }
-          attr_writer :device_id
-
-          # The model of the user's device.
-          sig { returns(T.nilable(String)) }
-          attr_reader :device_model
-
-          sig { params(device_model: String).void }
-          attr_writer :device_model
-
-          # The type of the user's device.
-          sig do
-            returns(
-              T.nilable(
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::OrSymbol
-              )
-            )
-          end
-          attr_reader :device_platform
-
-          sig do
-            params(
-              device_platform:
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::OrSymbol
-            ).void
-          end
-          attr_writer :device_platform
-
-          # The IP address of the 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
-          # [Signals](/verify/v2/documentation/prevent-fraud#signals).
-          sig { returns(T.nilable(T::Boolean)) }
-          attr_reader :is_trusted_user
-
-          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.
-          sig { returns(T.nilable(String)) }
-          attr_reader :ja4_fingerprint
-
-          sig { params(ja4_fingerprint: String).void }
-          attr_writer :ja4_fingerprint
-
-          # The version of the user's device operating system.
-          sig { returns(T.nilable(String)) }
-          attr_reader :os_version
-
-          sig { params(os_version: String).void }
-          attr_writer :os_version
-
-          # The user agent of the user's device. If the individual fields (os_version,
-          # device_platform, device_model) are provided, we will prioritize those values
-          # instead of parsing them from the user agent string.
-          sig { returns(T.nilable(String)) }
-          attr_reader :user_agent
-
-          sig { params(user_agent: String).void }
-          attr_writer :user_agent
-
-          # The signals used for anti-fraud. For more details, refer to
-          # [Signals](/verify/v2/documentation/prevent-fraud#signals).
-          sig do
-            params(
-              app_version: String,
-              device_id: String,
-              device_model: String,
-              device_platform:
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::OrSymbol,
-              ip: String,
-              is_trusted_user: T::Boolean,
-              ja4_fingerprint: String,
-              os_version: String,
-              user_agent: String
-            ).returns(T.attached_class)
-          end
-          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`.
-            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.
-            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
-            # [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.
-            ja4_fingerprint: nil,
-            # The version of the user's device operating system.
-            os_version: nil,
-            # The user agent of the user's device. If the individual fields (os_version,
-            # device_platform, device_model) are provided, we will prioritize those values
-            # instead of parsing them from the user agent string.
-            user_agent: nil
-          )
-          end
-
-          sig do
-            override.returns(
-              {
-                app_version: String,
-                device_id: String,
-                device_model: String,
-                device_platform:
-                  PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::OrSymbol,
-                ip: String,
-                is_trusted_user: T::Boolean,
-                ja4_fingerprint: String,
-                os_version: String,
-                user_agent: String
-              }
-            )
-          end
-          def to_hash
-          end
-
-          # The type of the user's device.
-          module DevicePlatform
-            extend PreludeSDK::Internal::Type::Enum
-
-            TaggedSymbol =
-              T.type_alias do
-                T.all(
-                  Symbol,
-                  PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform
-                )
-              end
-            OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-            ANDROID =
-              T.let(
-                :android,
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::TaggedSymbol
-              )
-            IOS =
-              T.let(
-                :ios,
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::TaggedSymbol
-              )
-            IPADOS =
-              T.let(
-                :ipados,
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::TaggedSymbol
-              )
-            TVOS =
-              T.let(
-                :tvos,
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::TaggedSymbol
-              )
-            WEB =
-              T.let(
-                :web,
-                PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::TaggedSymbol
-              )
-
-            sig do
-              override.returns(
-                T::Array[
-                  PreludeSDK::WatchSendFeedbacksParams::Feedback::Signals::DevicePlatform::TaggedSymbol
-                ]
-              )
-            end
-            def self.values
-            end
-          end
-        end
       end
     end
   end

data/rbi/prelude_sdk/resources/lookup.rbi

@@ -2,6 +2,8 @@
 
 module PreludeSDK
   module Resources
+    # Retrieve detailed information about a phone number including carrier data, line
+    # type, and portability status.
     class Lookup
       # Retrieve detailed information about a phone number including carrier data, line
       # type, and portability status.

data/rbi/prelude_sdk/resources/notify.rbi

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Send transactional and marketing messages with compliance enforcement.
     class Notify
       # Retrieve a specific subscription management configuration by its ID.
       sig do
@@ -121,6 +122,7 @@ module PreludeSDK
           to: String,
           callback_url: String,
           correlation_id: String,
+          document: PreludeSDK::NotifySendParams::Document::OrHash,
           expires_at: Time,
           from: String,
           locale: String,
@@ -142,6 +144,9 @@ module PreludeSDK
         # It is returned in the response and any webhook events that refer to this
         # message.
         correlation_id: nil,
+        # A document to attach to the message. Only supported on WhatsApp templates that
+        # have a document header.
+        document: nil,
         # The message expiration date in RFC3339 format. The message will not be sent if
         # this time is reached.
         expires_at: nil,
@@ -172,6 +177,7 @@ module PreludeSDK
           to: T::Array[String],
           callback_url: String,
           correlation_id: String,
+          document: PreludeSDK::NotifySendBatchParams::Document::OrHash,
           expires_at: Time,
           from: String,
           locale: String,
@@ -191,6 +197,9 @@ module PreludeSDK
         callback_url: nil,
         # A user-defined identifier to correlate this request with your internal systems.
         correlation_id: nil,
+        # A document to attach to the message. Only supported on WhatsApp templates that
+        # have a document header.
+        document: nil,
         # The message expiration date in RFC3339 format. Messages will not be sent after
         # this time.
         expires_at: nil,

data/rbi/prelude_sdk/resources/transactional.rbi

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Send transactional messages (deprecated - use Notify API instead).
     class Transactional
       # Legacy route maintained for backward compatibility. Migrate to `/v2/notify`
       # instead.
@@ -11,6 +12,7 @@ module PreludeSDK
           to: String,
           callback_url: String,
           correlation_id: String,
+          document: PreludeSDK::TransactionalSendParams::Document::OrHash,
           expires_at: String,
           from: String,
           locale: String,
@@ -31,6 +33,9 @@ module PreludeSDK
         # returned in the response and any webhook events that refer to this
         # transactionalmessage.
         correlation_id: nil,
+        # A document to attach to the message. Only supported on WhatsApp templates that
+        # have a document header.
+        document: nil,
         # The message expiration date.
         expires_at: nil,
         # The Sender ID.

data/rbi/prelude_sdk/resources/verification.rbi

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Verify phone numbers.
     class Verification
       # Create a new verification for a specific phone number. If another non-expired
       # verification exists (the request is performed within the verification window),

data/rbi/prelude_sdk/resources/verification_management.rbi

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Verify phone numbers.
     class VerificationManagement
       # Remove a phone number from the allow or block list.
       #

data/rbi/prelude_sdk/resources/watch.rbi

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Evaluate email addresses and phone numbers for trustworthiness.
     class Watch
       # Predict the outcome of a verification based on Prelude’s anti-fraud system.
       sig do

data/sig/prelude_sdk/internal/util.rbs

@@ -106,6 +106,16 @@ module PreludeSDK
       JSON_CONTENT: Regexp
       JSONL_CONTENT: Regexp
 
+      def encode_query_params: (
+        ::Hash[Symbol, top] query
+      ) -> ::Hash[Symbol, top]
+
+      private def write_query_param_element!: (
+        ::Hash[Symbol, top] collection,
+        String key,
+        top element
+      ) -> nil
+
       def self?.write_multipart_content: (
         Enumerator::Yielder y,
         val: top,