rcs 2.0.5 → 2.0.7

data/lib/pinnacle/conversations/client.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    class Client
+      # @param client [Pinnacle::Internal::Http::RawClient]
+      #
+      # @return [void]
+      def initialize(client:)
+        @client = client
+      end
+
+      # Fetch a specific conversation using either its unique identifier or by matching sender and recipient details.
+      #
+      # @param request_options [Hash]
+      # @param params [Pinnacle::Types::GetConversationParams]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Pinnacle::Types::Conversation, nil]
+      def get(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "conversations/get",
+          body: Pinnacle::Types::GetConversationParams.new(params).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        return if code.between?(200, 299)
+
+        error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+        raise error_class.new(response.body, code: code)
+      end
+
+      # Retrieves conversations by page with optional filtering based off provided parameters.
+      #
+      # @param request_options [Hash]
+      # @param params [Pinnacle::Conversations::Types::ListConversationsParams]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Pinnacle::Types::ConversationList]
+      def list(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        body_prop_names = %i[brand_id campaign_id campaign_type page_index page_size receiver sender]
+        body_bag = params.slice(*body_prop_names)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "conversations/list",
+          body: Pinnacle::Conversations::Types::ListConversationsParams.new(body_bag).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::ConversationList.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Update the notes associated with a specific conversation.
+      #
+      # @param request_options [Hash]
+      # @param params [Pinnacle::Conversations::Types::UpdateConversationParams]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      #
+      # @return [Pinnacle::Types::SuccessfulConversationUpdate]
+      def update(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        body_prop_names = %i[id notes]
+        body_bag = params.slice(*body_prop_names)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "conversations/update",
+          body: Pinnacle::Conversations::Types::UpdateConversationParams.new(body_bag).to_h,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::SuccessfulConversationUpdate.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+
+      # Retrieve a paginated and filtered list of messages for a specific conversation.
+      #
+      # @param request_options [Hash]
+      # @param params [Hash]
+      # @option request_options [String] :base_url
+      # @option request_options [Hash{String => Object}] :additional_headers
+      # @option request_options [Hash{String => Object}] :additional_query_parameters
+      # @option request_options [Hash{String => Object}] :additional_body_parameters
+      # @option request_options [Integer] :timeout_in_seconds
+      # @option params [String] :id
+      # @option params [Integer, nil] :page_index
+      # @option params [Integer, nil] :page_size
+      # @option params [Pinnacle::Conversations::Types::ConversationsListMessagesRequestSortOrder, nil] :sort_order
+      # @option params [Pinnacle::Conversations::Types::ConversationsListMessagesRequestDirection, nil] :direction
+      # @option params [Pinnacle::Conversations::Types::ConversationsListMessagesRequestStatus, nil] :status
+      # @option params [Pinnacle::Conversations::Types::ConversationsListMessagesRequestType, nil] :type
+      # @option params [String, nil] :date_from
+      # @option params [String, nil] :date_to
+      #
+      # @return [Pinnacle::Types::MessageList]
+      def list_messages(request_options: {}, **params)
+        params = Pinnacle::Internal::Types::Utils.normalize_keys(params)
+        query_param_names = %i[page_index page_size sort_order direction status type date_from date_to]
+        query_params = {}
+        query_params["pageIndex"] = params[:page_index] if params.key?(:page_index)
+        query_params["pageSize"] = params[:page_size] if params.key?(:page_size)
+        query_params["sortOrder"] = params[:sort_order] if params.key?(:sort_order)
+        query_params["direction"] = params[:direction] if params.key?(:direction)
+        query_params["status"] = params[:status] if params.key?(:status)
+        query_params["type"] = params[:type] if params.key?(:type)
+        query_params["dateFrom"] = params[:date_from] if params.key?(:date_from)
+        query_params["dateTo"] = params[:date_to] if params.key?(:date_to)
+        params = params.except(*query_param_names)
+
+        request = Pinnacle::Internal::JSON::Request.new(
+          base_url: request_options[:base_url],
+          method: "POST",
+          path: "conversations/#{params[:id]}/messages",
+          query: query_params,
+          request_options: request_options
+        )
+        begin
+          response = @client.send(request)
+        rescue Net::HTTPRequestTimeout
+          raise Pinnacle::Errors::TimeoutError
+        end
+        code = response.code.to_i
+        if code.between?(200, 299)
+          Pinnacle::Types::MessageList.load(response.body)
+        else
+          error_class = Pinnacle::Errors::ResponseError.subclass_for_code(code)
+          raise error_class.new(response.body, code: code)
+        end
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/conversations_list_messages_request.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      class ConversationsListMessagesRequest < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+        field :page_index, -> { Integer }, optional: true, nullable: false, api_name: "pageIndex"
+        field :page_size, -> { Integer }, optional: true, nullable: false, api_name: "pageSize"
+        field :sort_order, -> { Pinnacle::Conversations::Types::ConversationsListMessagesRequestSortOrder }, optional: true, nullable: false, api_name: "sortOrder"
+        field :direction, -> { Pinnacle::Conversations::Types::ConversationsListMessagesRequestDirection }, optional: true, nullable: false
+        field :status, -> { Pinnacle::Conversations::Types::ConversationsListMessagesRequestStatus }, optional: true, nullable: false
+        field :type, -> { Pinnacle::Conversations::Types::ConversationsListMessagesRequestType }, optional: true, nullable: false
+        field :date_from, -> { String }, optional: true, nullable: false, api_name: "dateFrom"
+        field :date_to, -> { String }, optional: true, nullable: false, api_name: "dateTo"
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/conversations_list_messages_request_direction.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      module ConversationsListMessagesRequestDirection
+        extend Pinnacle::Internal::Types::Enum
+
+        INBOUND = "INBOUND"
+        OUTBOUND = "OUTBOUND"
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/conversations_list_messages_request_sort_order.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      module ConversationsListMessagesRequestSortOrder
+        extend Pinnacle::Internal::Types::Enum
+
+        ASC = "asc"
+        DESC = "desc"
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/conversations_list_messages_request_status.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      module ConversationsListMessagesRequestStatus
+        extend Pinnacle::Internal::Types::Enum
+
+        PENDING = "PENDING"
+        SENT = "SENT"
+        SEND_FAILED = "SEND_FAILED"
+        DELIVERED = "DELIVERED"
+        DELIVERY_FAILED = "DELIVERY_FAILED"
+        RECEIVED = "RECEIVED"
+        READ = "READ"
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/conversations_list_messages_request_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      module ConversationsListMessagesRequestType
+        extend Pinnacle::Internal::Types::Enum
+
+        SMS = "SMS"
+        MMS = "MMS"
+        RCS = "RCS"
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/list_conversations_params.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      class ListConversationsParams < Internal::Types::Model
+        field :brand_id, -> { String }, optional: true, nullable: false, api_name: "brandId"
+        field :campaign_id, -> { String }, optional: true, nullable: false, api_name: "campaignId"
+        field :campaign_type, -> { Pinnacle::Types::CampaignEnum }, optional: true, nullable: false, api_name: "campaignType"
+        field :page_index, -> { Integer }, optional: false, nullable: false, api_name: "pageIndex"
+        field :page_size, -> { Integer }, optional: true, nullable: false, api_name: "pageSize"
+        field :receiver, -> { String }, optional: true, nullable: false
+        field :sender, -> { String }, optional: true, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/conversations/types/update_conversation_params.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Conversations
+    module Types
+      class UpdateConversationParams < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+        field :notes, -> { String }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/pinnacle/errors/api_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Errors
+    class ApiError < StandardError
+    end
+  end
+end

data/lib/pinnacle/errors/client_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Errors
+    class ClientError < ResponseError
+    end
+
+    class UnauthorizedError < ClientError
+    end
+
+    class ForbiddenError < ClientError
+    end
+
+    class NotFoundError < ClientError
+    end
+  end
+end

data/lib/pinnacle/errors/redirect_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Errors
+    class RedirectError < ResponseError
+    end
+  end
+end

data/lib/pinnacle/errors/response_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Errors
+    class ResponseError < ApiError
+      attr_reader :code
+
+      def initialize(msg, code:)
+        @code = code
+        super(msg)
+      end
+
+      def inspect
+        "#<#{self.class.name} @code=#{code} @body=#{message}>"
+      end
+
+      # Returns the most appropriate error class for the given code.
+      #
+      # @return [Class]
+      def self.subclass_for_code(code)
+        case code
+        when 300..399
+          RedirectError
+        when 401
+          UnauthorizedError
+        when 403
+          ForbiddenError
+        when 404
+          NotFoundError
+        when 400..499
+          ClientError
+        when 503
+          ServiceUnavailableError
+        when 500..599
+          ServerError
+        else
+          ResponseError
+        end
+      end
+    end
+  end
+end

data/lib/pinnacle/errors/server_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Errors
+    class ServerError < ResponseError
+    end
+
+    class ServiceUnavailableError < ApiError
+    end
+  end
+end

data/lib/pinnacle/errors/timeout_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Errors
+    class TimeoutError < ApiError
+    end
+  end
+end

data/lib/pinnacle/internal/errors/constraint_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Internal
+    module Errors
+      class ConstraintError < StandardError
+      end
+    end
+  end
+end

data/lib/pinnacle/internal/errors/type_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Internal
+    module Errors
+      class TypeError < StandardError
+      end
+    end
+  end
+end

data/lib/pinnacle/internal/http/base_request.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Internal
+    module Http
+      # @api private
+      class BaseRequest
+        attr_reader :base_url, :path, :method, :headers, :query, :request_options
+
+        # @param base_url [String] The base URL for the request
+        # @param path [String] The path for the request
+        # @param method [String] The HTTP method for the request (:get, :post, etc.)
+        # @param headers [Hash] Additional headers for the request (optional)
+        # @param query [Hash] Query parameters for the request (optional)
+        # @param request_options [Pinnacle::RequestOptions, Hash{Symbol=>Object}, nil]
+        def initialize(base_url:, path:, method:, headers: {}, query: {}, request_options: {})
+          @base_url = base_url
+          @path = path
+          @method = method
+          @headers = headers
+          @query = query
+          @request_options = request_options
+        end
+
+        # Child classes should implement:
+        # - encode_headers: Returns the encoded HTTP request headers.
+        # - encode_body: Returns the encoded HTTP request body.
+      end
+    end
+  end
+end

data/lib/pinnacle/internal/http/raw_client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Internal
+    module Http
+      # @api private
+      class RawClient
+        # @return [String] The base URL for requests
+        attr_reader :base_url
+
+        # @param base_url [String] The base url for the request.
+        # @param max_retries [Integer] The number of times to retry a failed request, defaults to 2.
+        # @param timeout [Float] The timeout for the request, defaults to 60.0 seconds.
+        # @param headers [Hash] The headers for the request.
+        def initialize(base_url:, max_retries: 2, timeout: 60.0, headers: {})
+          @base_url = base_url
+          @max_retries = max_retries
+          @timeout = timeout
+          @default_headers = {
+            "X-Fern-Language": "Ruby",
+            "X-Fern-SDK-Name": "rcs",
+            "X-Fern-SDK-Version": "0.0.1"
+          }.merge(headers)
+        end
+
+        # @param request [Pinnacle::Internal::Http::BaseRequest] The HTTP request.
+        # @return [HTTP::Response] The HTTP response.
+        def send(request)
+          url = build_url(request)
+
+          http_request = build_http_request(
+            url:,
+            method: request.method,
+            headers: request.encode_headers,
+            body: request.encode_body
+          )
+
+          conn = connect(url)
+          conn.open_timeout = @timeout
+          conn.read_timeout = @timeout
+          conn.write_timeout = @timeout
+          conn.continue_timeout = @timeout
+
+          conn.request(http_request)
+        end
+
+        # @param request [Pinnacle::Internal::Http::BaseRequest] The HTTP request.
+        # @return [URI::Generic] The URL.
+        def build_url(request)
+          # If the path is already an absolute URL, use it directly
+          if request.path.start_with?("http://", "https://")
+            url = request.path
+            url = "#{url}?#{encode_query(request.query)}" if request.query&.any?
+            return URI.parse(url)
+          end
+
+          path = request.path.start_with?("/") ? request.path[1..] : request.path
+          base = request.base_url || @base_url
+          url = "#{base.chomp("/")}/#{path}"
+          url = "#{url}?#{encode_query(request.query)}" if request.query&.any?
+          URI.parse(url)
+        end
+
+        # @param url [URI::Generic] The url to the resource.
+        # @param method [String] The HTTP method to use.
+        # @param headers [Hash] The headers for the request.
+        # @param body [String, nil] The body for the request.
+        # @return [HTTP::Request] The HTTP request.
+        def build_http_request(url:, method:, headers: {}, body: nil)
+          request = Net::HTTPGenericRequest.new(
+            method,
+            !body.nil?,
+            method != "HEAD",
+            url
+          )
+
+          request_headers = @default_headers.merge(headers)
+          request_headers.each { |name, value| request[name] = value }
+          request.body = body if body
+
+          request
+        end
+
+        # @param query [Hash] The query for the request.
+        # @return [String, nil] The encoded query.
+        def encode_query(query)
+          query.to_h.empty? ? nil : URI.encode_www_form(query)
+        end
+
+        # @param url [URI::Generic] The url to connect to.
+        # @return [Net::HTTP] The HTTP connection.
+        def connect(url)
+          is_https = (url.scheme == "https")
+
+          port = if url.port
+                   url.port
+                 elsif is_https
+                   Net::HTTP.https_default_port
+                 else
+                   Net::HTTP.http_default_port
+                 end
+
+          http = Net::HTTP.new(url.host, port)
+          http.use_ssl = is_https
+          http.max_retries = @max_retries
+          http
+        end
+
+        # @return [String]
+        def inspect
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} @base_url=#{@base_url.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/pinnacle/internal/iterators/cursor_item_iterator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Internal
+    class CursorItemIterator < ItemIterator
+      # Instantiates a CursorItemIterator, an Enumerable class which wraps calls to a cursor-based paginated API and yields individual items from it.
+      #
+      # @param initial_cursor [String] The initial cursor to use when iterating, if any.
+      # @param cursor_field [Symbol] The field in API responses to extract the next cursor from.
+      # @param item_field [Symbol] The field in API responses to extract the items to iterate over.
+      # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
+      # @return [Pinnacle::Internal::CursorItemIterator]
+      def initialize(initial_cursor:, cursor_field:, item_field:, &)
+        super()
+        @item_field = item_field
+        @page_iterator = CursorPageIterator.new(initial_cursor:, cursor_field:, &)
+        @page = nil
+      end
+
+      # Returns the CursorPageIterator mediating access to the underlying API.
+      #
+      # @return [Pinnacle::Internal::CursorPageIterator]
+      def pages
+        @page_iterator
+      end
+    end
+  end
+end

data/lib/pinnacle/internal/iterators/cursor_page_iterator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Pinnacle
+  module Internal
+    class CursorPageIterator
+      include Enumerable
+
+      # Instantiates a CursorPageIterator, an Enumerable class which wraps calls to a cursor-based paginated API and yields pages of items.
+      #
+      # @param initial_cursor [String] The initial cursor to use when iterating, if any.
+      # @param cursor_field [Symbol] The name of the field in API responses to extract the next cursor from.
+      # @param block [Proc] A block which is responsible for receiving a cursor to use and returning the given page from the API.
+      # @return [Pinnacle::Internal::CursorPageIterator]
+      def initialize(initial_cursor:, cursor_field:, &block)
+        @need_initial_load = initial_cursor.nil?
+        @cursor = initial_cursor
+        @cursor_field = cursor_field
+        @get_next_page = block
+      end
+
+      # Iterates over each page returned by the API.
+      #
+      # @param block [Proc] The block which each retrieved page is yielded to.
+      # @return [NilClass]
+      def each(&block)
+        while (page = next_page)
+          block.call(page)
+        end
+      end
+
+      # Whether another page will be available from the API.
+      #
+      # @return [Boolean]
+      def next?
+        @need_initial_load || !@cursor.nil?
+      end
+
+      # Retrieves the next page from the API.
+      #
+      # @return [Boolean]
+      def next_page
+        return if !@need_initial_load && @cursor.nil?
+
+        @need_initial_load = false
+        fetched_page = @get_next_page.call(@cursor)
+        @cursor = fetched_page.send(@cursor_field)
+        fetched_page
+      end
+    end
+  end
+end