prelude-sdk 0.1.0 → 0.3.0

data/lib/prelude_sdk/resources/notify.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module PreludeSDK
+  module Resources
+    # Send transactional and marketing messages with compliance enforcement.
+    class Notify
+      # Retrieve a specific subscription management configuration by its ID.
+      #
+      # @overload get_subscription_config(config_id, request_options: {})
+      #
+      # @param config_id [String] The subscription configuration ID
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifyGetSubscriptionConfigResponse]
+      #
+      # @see PreludeSDK::Models::NotifyGetSubscriptionConfigParams
+      def get_subscription_config(config_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["v2/notify/management/subscriptions/%1$s", config_id],
+          model: PreludeSDK::Models::NotifyGetSubscriptionConfigResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Retrieve the current subscription status for a specific phone number within a
+      # subscription configuration.
+      #
+      # @overload get_subscription_phone_number(phone_number, config_id:, request_options: {})
+      #
+      # @param phone_number [String] The phone number in E.164 format (e.g., +33612345678)
+      #
+      # @param config_id [String] The subscription configuration ID
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifyGetSubscriptionPhoneNumberResponse]
+      #
+      # @see PreludeSDK::Models::NotifyGetSubscriptionPhoneNumberParams
+      def get_subscription_phone_number(phone_number, params)
+        parsed, options = PreludeSDK::NotifyGetSubscriptionPhoneNumberParams.dump_request(params)
+        config_id =
+          parsed.delete(:config_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: ["v2/notify/management/subscriptions/%1$s/phone_numbers/%2$s", config_id, phone_number],
+          model: PreludeSDK::Models::NotifyGetSubscriptionPhoneNumberResponse,
+          options: options
+        )
+      end
+
+      # Retrieve a paginated list of subscription management configurations for your
+      # account.
+      #
+      # Each configuration represents a subscription management setup with phone numbers
+      # for receiving opt-out/opt-in requests and a callback URL for webhook events.
+      #
+      # @overload list_subscription_configs(cursor: nil, limit: nil, request_options: {})
+      #
+      # @param cursor [String] Pagination cursor from the previous response
+      #
+      # @param limit [Integer] Maximum number of configurations to return per page
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifyListSubscriptionConfigsResponse]
+      #
+      # @see PreludeSDK::Models::NotifyListSubscriptionConfigsParams
+      def list_subscription_configs(params = {})
+        parsed, options = PreludeSDK::NotifyListSubscriptionConfigsParams.dump_request(params)
+        query = PreludeSDK::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "v2/notify/management/subscriptions",
+          query: query,
+          model: PreludeSDK::Models::NotifyListSubscriptionConfigsResponse,
+          options: options
+        )
+      end
+
+      # Retrieve a paginated list of subscription events (status changes) for a specific
+      # phone number within a subscription configuration.
+      #
+      # Events are ordered by timestamp in descending order (most recent first).
+      #
+      # @overload list_subscription_phone_number_events(phone_number, config_id:, cursor: nil, limit: nil, request_options: {})
+      #
+      # @param phone_number [String] Path param: The phone number in E.164 format (e.g., +33612345678)
+      #
+      # @param config_id [String] Path param: The subscription configuration ID
+      #
+      # @param cursor [String] Query param: Pagination cursor from the previous response
+      #
+      # @param limit [Integer] Query param: Maximum number of events to return per page
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifyListSubscriptionPhoneNumberEventsResponse]
+      #
+      # @see PreludeSDK::Models::NotifyListSubscriptionPhoneNumberEventsParams
+      def list_subscription_phone_number_events(phone_number, params)
+        parsed, options = PreludeSDK::NotifyListSubscriptionPhoneNumberEventsParams.dump_request(params)
+        query = PreludeSDK::Internal::Util.encode_query_params(parsed)
+        config_id =
+          parsed.delete(:config_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: [
+            "v2/notify/management/subscriptions/%1$s/phone_numbers/%2$s/events",
+            config_id,
+            phone_number
+          ],
+          query: query,
+          model: PreludeSDK::Models::NotifyListSubscriptionPhoneNumberEventsResponse,
+          options: options
+        )
+      end
+
+      # Retrieve a paginated list of phone numbers and their subscription statuses for a
+      # specific subscription configuration.
+      #
+      # You can optionally filter by subscription state (SUB or UNSUB).
+      #
+      # @overload list_subscription_phone_numbers(config_id, cursor: nil, limit: nil, state: nil, request_options: {})
+      #
+      # @param config_id [String] The subscription configuration ID
+      #
+      # @param cursor [String] Pagination cursor from the previous response
+      #
+      # @param limit [Integer] Maximum number of phone numbers to return per page
+      #
+      # @param state [Symbol, PreludeSDK::Models::NotifyListSubscriptionPhoneNumbersParams::State] Filter by subscription state
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifyListSubscriptionPhoneNumbersResponse]
+      #
+      # @see PreludeSDK::Models::NotifyListSubscriptionPhoneNumbersParams
+      def list_subscription_phone_numbers(config_id, params = {})
+        parsed, options = PreludeSDK::NotifyListSubscriptionPhoneNumbersParams.dump_request(params)
+        query = PreludeSDK::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["v2/notify/management/subscriptions/%1$s/phone_numbers", config_id],
+          query: query,
+          model: PreludeSDK::Models::NotifyListSubscriptionPhoneNumbersResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {PreludeSDK::Models::NotifySendParams} for more details.
+      #
+      # Send transactional and marketing messages to your users via SMS and WhatsApp
+      # with automatic compliance enforcement.
+      #
+      # @overload send_(template_id:, to:, callback_url: nil, correlation_id: nil, document: nil, expires_at: nil, from: nil, locale: nil, preferred_channel: nil, schedule_at: nil, variables: nil, request_options: {})
+      #
+      # @param template_id [String] The template identifier configured by your Customer Success team.
+      #
+      # @param to [String] The recipient's phone number in E.164 format.
+      #
+      # @param callback_url [String] The URL where webhooks will be sent for message delivery events.
+      #
+      # @param correlation_id [String] A user-defined identifier to correlate this message with your internal systems.
+      #
+      # @param document [PreludeSDK::Models::NotifySendParams::Document] A document to attach to the message. Only supported on WhatsApp templates that h
+      #
+      # @param expires_at [Time] The message expiration date in RFC3339 format. The message will not be sent if t
+      #
+      # @param from [String] The Sender ID. Must be approved for your account.
+      #
+      # @param locale [String] A BCP-47 formatted locale string with the language the text message will be sent
+      #
+      # @param preferred_channel [Symbol, PreludeSDK::Models::NotifySendParams::PreferredChannel] The preferred channel to be used in priority for message delivery. If the channe
+      #
+      # @param schedule_at [Time] Schedule the message for future delivery in RFC3339 format. Marketing messages c
+      #
+      # @param variables [Hash{Symbol=>String}] The variables to be replaced in the template.
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifySendResponse]
+      #
+      # @see PreludeSDK::Models::NotifySendParams
+      def send_(params)
+        parsed, options = PreludeSDK::NotifySendParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "v2/notify",
+          body: parsed,
+          model: PreludeSDK::Models::NotifySendResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {PreludeSDK::Models::NotifySendBatchParams} for more details.
+      #
+      # Send the same message to multiple recipients in a single request.
+      #
+      # @overload send_batch(template_id:, to:, callback_url: nil, correlation_id: nil, document: nil, expires_at: nil, from: nil, locale: nil, preferred_channel: nil, schedule_at: nil, variables: nil, request_options: {})
+      #
+      # @param template_id [String] The template identifier configured by your Customer Success team.
+      #
+      # @param to [Array<String>] The list of recipients' phone numbers in E.164 format.
+      #
+      # @param callback_url [String] The URL where webhooks will be sent for delivery events.
+      #
+      # @param correlation_id [String] A user-defined identifier to correlate this request with your internal systems.
+      #
+      # @param document [PreludeSDK::Models::NotifySendBatchParams::Document] A document to attach to the message. Only supported on WhatsApp templates that h
+      #
+      # @param expires_at [Time] The message expiration date in RFC3339 format. Messages will not be sent after t
+      #
+      # @param from [String] The Sender ID. Must be approved for your account.
+      #
+      # @param locale [String] A BCP-47 formatted locale string.
+      #
+      # @param preferred_channel [Symbol, PreludeSDK::Models::NotifySendBatchParams::PreferredChannel] Preferred channel for delivery. If unavailable, automatic fallback applies.
+      #
+      # @param schedule_at [Time] Schedule delivery in RFC3339 format. Marketing sends may be adjusted to comply w
+      #
+      # @param variables [Hash{Symbol=>String}] The variables to be replaced in the template.
+      #
+      # @param request_options [PreludeSDK::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [PreludeSDK::Models::NotifySendBatchResponse]
+      #
+      # @see PreludeSDK::Models::NotifySendBatchParams
+      def send_batch(params)
+        parsed, options = PreludeSDK::NotifySendBatchParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "v2/notify/batch",
+          body: parsed,
+          model: PreludeSDK::Models::NotifySendBatchResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [PreludeSDK::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/prelude_sdk/resources/transactional.rb

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Send transactional messages (deprecated - use Notify API instead).
     class Transactional
       # @deprecated
       #
@@ -11,7 +12,7 @@ module PreludeSDK
       # Legacy route maintained for backward compatibility. Migrate to `/v2/notify`
       # instead.
       #
-      # @overload send_(template_id:, to:, callback_url: nil, correlation_id: nil, expires_at: nil, from: nil, locale: nil, preferred_channel: nil, variables: nil, request_options: {})
+      # @overload send_(template_id:, to:, callback_url: nil, correlation_id: nil, document: nil, expires_at: nil, from: nil, locale: nil, preferred_channel: nil, variables: nil, request_options: {})
       #
       # @param template_id [String] The template identifier.
       #
@@ -21,6 +22,8 @@ module PreludeSDK
       #
       # @param correlation_id [String] A user-defined identifier to correlate this transactional message with. It is re
       #
+      # @param document [PreludeSDK::Models::TransactionalSendParams::Document] A document to attach to the message. Only supported on WhatsApp templates that h
+      #
       # @param expires_at [String] The message expiration date.
       #
       # @param from [String] The Sender ID.

data/lib/prelude_sdk/resources/verification.rb

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Verify phone numbers.
     class Verification
       # Some parameter documentations has been truncated, see
       # {PreludeSDK::Models::VerificationCreateParams} for more details.

data/lib/prelude_sdk/resources/verification_management.rb

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

data/lib/prelude_sdk/resources/watch.rb

@@ -2,6 +2,7 @@
 
 module PreludeSDK
   module Resources
+    # Evaluate email addresses and phone numbers for trustworthiness.
     class Watch
       # Some parameter documentations has been truncated, see
       # {PreludeSDK::Models::WatchPredictParams} for more details.

data/lib/prelude_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PreludeSDK
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/prelude_sdk.rb

@@ -3,6 +3,7 @@
 # Standard libraries.
 # rubocop:disable Lint/RedundantRequireStatement
 require "English"
+require "base64"
 require "cgi"
 require "date"
 require "erb"
@@ -53,6 +54,20 @@ require_relative "prelude_sdk/internal/transport/pooled_net_requester"
 require_relative "prelude_sdk/client"
 require_relative "prelude_sdk/models/lookup_lookup_params"
 require_relative "prelude_sdk/models/lookup_lookup_response"
+require_relative "prelude_sdk/models/notify_get_subscription_config_params"
+require_relative "prelude_sdk/models/notify_get_subscription_config_response"
+require_relative "prelude_sdk/models/notify_get_subscription_phone_number_params"
+require_relative "prelude_sdk/models/notify_get_subscription_phone_number_response"
+require_relative "prelude_sdk/models/notify_list_subscription_configs_params"
+require_relative "prelude_sdk/models/notify_list_subscription_configs_response"
+require_relative "prelude_sdk/models/notify_list_subscription_phone_number_events_params"
+require_relative "prelude_sdk/models/notify_list_subscription_phone_number_events_response"
+require_relative "prelude_sdk/models/notify_list_subscription_phone_numbers_params"
+require_relative "prelude_sdk/models/notify_list_subscription_phone_numbers_response"
+require_relative "prelude_sdk/models/notify_send_batch_params"
+require_relative "prelude_sdk/models/notify_send_batch_response"
+require_relative "prelude_sdk/models/notify_send_params"
+require_relative "prelude_sdk/models/notify_send_response"
 require_relative "prelude_sdk/models/transactional_send_params"
 require_relative "prelude_sdk/models/transactional_send_response"
 require_relative "prelude_sdk/models/verification_check_params"
@@ -77,6 +92,7 @@ require_relative "prelude_sdk/models/watch_send_feedbacks_params"
 require_relative "prelude_sdk/models/watch_send_feedbacks_response"
 require_relative "prelude_sdk/models"
 require_relative "prelude_sdk/resources/lookup"
+require_relative "prelude_sdk/resources/notify"
 require_relative "prelude_sdk/resources/transactional"
 require_relative "prelude_sdk/resources/verification"
 require_relative "prelude_sdk/resources/verification_management"

data/manifest.yaml

@@ -1,5 +1,6 @@
 dependencies:
   - English
+  - base64
   - cgi
   - date
   - erb

data/rbi/prelude_sdk/client.rbi

@@ -14,18 +14,28 @@ module PreludeSDK
     sig { returns(String) }
     attr_reader :api_token
 
+    # Retrieve detailed information about a phone number including carrier data, line
+    # type, and portability status.
     sig { returns(PreludeSDK::Resources::Lookup) }
     attr_reader :lookup
 
+    # Send transactional and marketing messages with compliance enforcement.
+    sig { returns(PreludeSDK::Resources::Notify) }
+    attr_reader :notify
+
+    # Send transactional messages (deprecated - use Notify API instead).
     sig { returns(PreludeSDK::Resources::Transactional) }
     attr_reader :transactional
 
+    # Verify phone numbers.
     sig { returns(PreludeSDK::Resources::Verification) }
     attr_reader :verification
 
+    # Verify phone numbers.
     sig { returns(PreludeSDK::Resources::VerificationManagement) }
     attr_reader :verification_management
 
+    # Evaluate email addresses and phone numbers for trustworthiness.
     sig { returns(PreludeSDK::Resources::Watch) }
     attr_reader :watch
 

data/rbi/prelude_sdk/internal/util.rbi

@@ -296,11 +296,31 @@ module PreludeSDK
       end
 
       JSON_CONTENT =
-        T.let(%r{^application/(?:vnd(?:\.[^.]+)*\+)?json(?!l)}, Regexp)
+        T.let(%r{^application/(?:[a-zA-Z0-9.-]+\+)?json(?!l)}, Regexp)
       JSONL_CONTENT =
         T.let(%r{^application/(:?x-(?:n|l)djson)|(:?(?:x-)?jsonl)}, Regexp)
 
       class << self
+        # @api private
+        sig do
+          params(query: PreludeSDK::Internal::AnyHash).returns(
+            PreludeSDK::Internal::AnyHash
+          )
+        end
+        def encode_query_params(query)
+        end
+
+        # @api private
+        sig do
+          params(
+            collection: PreludeSDK::Internal::AnyHash,
+            key: String,
+            element: T.anything
+          ).void
+        end
+        private def write_query_param_element!(collection, key, element)
+        end
+
         # @api private
         sig do
           params(

data/rbi/prelude_sdk/models/lookup_lookup_params.rbi

@@ -11,6 +11,10 @@ module PreludeSDK
           T.any(PreludeSDK::LookupLookupParams, PreludeSDK::Internal::AnyHash)
         end
 
+      # An E.164 formatted phone number to look up.
+      sig { returns(String) }
+      attr_accessor :phone_number
+
       # Optional features. Possible values are:
       #
       # - `cnam` - Retrieve CNAM (Caller ID Name) along with other information. Contact
@@ -31,11 +35,14 @@ module PreludeSDK
 
       sig do
         params(
+          phone_number: String,
           type: T::Array[PreludeSDK::LookupLookupParams::Type::OrSymbol],
           request_options: PreludeSDK::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        # An E.164 formatted phone number to look up.
+        phone_number:,
         # Optional features. Possible values are:
         #
         # - `cnam` - Retrieve CNAM (Caller ID Name) along with other information. Contact
@@ -48,6 +55,7 @@ module PreludeSDK
       sig do
         override.returns(
           {
+            phone_number: String,
             type: T::Array[PreludeSDK::LookupLookupParams::Type::OrSymbol],
             request_options: PreludeSDK::RequestOptions
           }

data/rbi/prelude_sdk/models/notify_get_subscription_config_params.rbi

@@ -0,0 +1,38 @@
+# typed: strong
+
+module PreludeSDK
+  module Models
+    class NotifyGetSubscriptionConfigParams < PreludeSDK::Internal::Type::BaseModel
+      extend PreludeSDK::Internal::Type::RequestParameters::Converter
+      include PreludeSDK::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            PreludeSDK::NotifyGetSubscriptionConfigParams,
+            PreludeSDK::Internal::AnyHash
+          )
+        end
+
+      sig { returns(String) }
+      attr_accessor :config_id
+
+      sig do
+        params(
+          config_id: String,
+          request_options: PreludeSDK::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(config_id:, request_options: {})
+      end
+
+      sig do
+        override.returns(
+          { config_id: String, request_options: PreludeSDK::RequestOptions }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end