conversant 1.0.16

data/lib/conversant/v3/services/authorization.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Conversant
+  module V3
+    module Services
+      # Shared authorization methods for service classes
+      #
+      # This module provides common authentication and authorization functionality
+      # for Conversant V3 service classes. It handles session management, cookie
+      # generation, and HTTP header construction with automatic caching via Redis.
+      #
+      # @example Including in a service class
+      #   class MyService < Conversant::V3::BaseService
+      #     include Conversant::V3::Services::Authorization
+      #
+      #     def fetch_new_session
+      #       # Custom session fetching logic
+      #     end
+      #
+      #     def service_endpoint
+      #       'https://api.example.com'
+      #     end
+      #   end
+      module Authorization
+        protected
+
+        # Builds authorized HTTP headers with session cookies
+        #
+        # Retrieves session cookies from cache or authenticates if needed,
+        # then constructs headers with appropriate cookie values.
+        #
+        # @return [Hash] HTTP headers including Cookie header if sessions exist
+        def authorized_headers
+          session_cookie = fetch_session_cookie
+          sso_gw_session2 = fetch_sso_session
+
+          log_missing_session if session_cookie.nil? && respond_to?(:requires_session?) && requires_session?
+
+          build_headers_with_cookies(session_cookie, sso_gw_session2)
+        end
+
+        # Authorizes and retrieves a session cookie
+        #
+        # Checks Redis cache first, then fetches a new session if not cached.
+        #
+        # @return [String, nil] The session cookie value, or nil if authorization fails
+        def authorize
+          cached = cached_session
+          return cached if cached
+
+          fetch_new_session
+        rescue StandardError => e
+          logger.debug "#{identifier}.METHOD:authorize.EXCEPTION:#{e.message}"
+          nil
+        end
+
+        private
+
+        # Fetches session cookie from cache or authorizes to get a new one
+        #
+        # @return [String, nil] The session cookie value
+        def fetch_session_cookie
+          cached = cached_session
+          cached || authorize
+        end
+
+        # Fetches SSO session from authentication or cache
+        #
+        # @return [String, nil] The SSO_GW_SESSION2 cookie value
+        def fetch_sso_session
+          sessions = authenticate
+          sessions&.[](:sso_gw_session2)
+        end
+
+        # Retrieves cached session from Redis
+        #
+        # @return [String, nil] The cached session value
+        def cached_session
+          redis.get(session_cache_key)
+        end
+
+        # Generates Redis cache key for session storage
+        #
+        # @return [String] Redis key in format "CONVERSANT.V3.SERVICE.SESSION_TYPE.CUSTOMER_ID"
+        def session_cache_key
+          service_name = self.class.name.split('::').last.upcase
+          session_type = respond_to?(:session_cookie_name, true) ? session_cookie_name : 'SESSION'
+          "CONVERSANT.V3.#{service_name}.#{session_type}.#{customer_id}"
+        end
+
+        # Generates Redis cache key for SSO session storage
+        #
+        # @return [String] Redis key in format "CONVERSANT.V3.PORTAL.SSO_GW_SESSION2.CUSTOMER_ID"
+        def sso_cache_key
+          "CONVERSANT.V3.PORTAL.SSO_GW_SESSION2.#{customer_id}"
+        end
+
+        # Builds HTTP headers hash with cookie values
+        #
+        # @param session_cookie [String, nil] The session cookie value
+        # @param sso_gw_session2 [String, nil] The SSO session cookie value
+        # @return [Hash] Complete HTTP headers including Cookie header if applicable
+        def build_headers_with_cookies(session_cookie, sso_gw_session2)
+          headers = base_headers
+          cookie_header = format_cookies(session_cookie, sso_gw_session2)
+          headers['Cookie'] = cookie_header if cookie_header
+          headers
+        end
+
+        # Builds base HTTP headers for API requests
+        #
+        # @return [Hash] Base headers with Authority, Content-Type, Referer, and User-Agent
+        def base_headers
+          {
+            'Authority' => URI.parse(service_endpoint).hostname,
+            'Content-Type' => configuration.default_content_type,
+            'Referer' => portal_endpoint,
+            'User-Agent' => configuration.default_ua
+          }
+        end
+
+        # Formats cookie hash into HTTP Cookie header string
+        #
+        # @param session_cookie [String, nil] The session cookie value
+        # @param sso_gw_session2 [String, nil] The SSO session cookie value
+        # @return [String, nil] Formatted cookie string "key1=value1; key2=value2" or nil if no cookies
+        def format_cookies(session_cookie, sso_gw_session2)
+          cookies = build_cookie_hash(session_cookie, sso_gw_session2)
+          return nil if cookies.empty?
+
+          cookies.map { |k, v| "#{k}=#{v}" }.join('; ')
+        end
+
+        # Builds hash of cookie key-value pairs
+        #
+        # @param session_cookie [String, nil] The session cookie value
+        # @param sso_gw_session2 [String, nil] The SSO session cookie value
+        # @return [Hash] Cookie hash with appropriate keys based on service configuration
+        def build_cookie_hash(session_cookie, sso_gw_session2)
+          cookies = {}
+
+          if respond_to?(:session_cookie_name, true)
+            cookies[session_cookie_name] = session_cookie if session_cookie
+          elsif session_cookie
+            cookies['SESSION'] = session_cookie
+          end
+
+          cookies['SSO_GW_SESSION2'] = sso_gw_session2 if sso_gw_session2
+          cookies
+        end
+
+        # Logs warning when required session is missing
+        #
+        # @return [void]
+        def log_missing_session
+          session_type = respond_to?(:session_cookie_name, true) ? session_cookie_name : 'SESSION'
+          logger.warn "#{identifier}.METHOD:authorized_headers.NO_#{session_type}"
+        end
+
+        # Returns the service-specific API endpoint
+        #
+        # @abstract Subclasses must implement this method
+        # @return [String] The service endpoint URL
+        # @raise [NotImplementedError] if not implemented by subclass
+        def service_endpoint
+          raise NotImplementedError, "#{self.class} must implement #service_endpoint"
+        end
+
+        # Fetches a new session from the service
+        #
+        # @abstract Subclasses must implement this method with service-specific logic
+        # @return [String] The new session cookie value
+        # @raise [NotImplementedError] if not implemented by subclass
+        def fetch_new_session
+          raise NotImplementedError, "#{self.class} must implement #fetch_new_session"
+        end
+
+        # Returns the session cookie name for this service
+        #
+        # @return [String] The cookie name (defaults to 'SESSION')
+        def session_cookie_name
+          'SESSION'
+        end
+
+        # Indicates whether this service requires a session cookie
+        #
+        # @return [Boolean] true if session is required, false otherwise
+        def requires_session?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/conversant/v3/services/cdn/analytics.rb

@@ -0,0 +1,483 @@
+# frozen_string_literal: true
+
+module Conversant
+  module V3
+    module Services
+      class CDN
+        # Analytics service for CDN metrics and reporting
+        #
+        # Provides comprehensive analytics data for CDN performance including:
+        # - Bandwidth and volume metrics
+        # - Viewer statistics
+        # - Request rates and hit rates
+        # - HTTP status code distribution
+        # - Referrer and popular content analytics
+        # - Origin request metrics
+        # - ISP and user agent analytics
+        #
+        # @example Basic usage
+        #   cdn = Conversant::V3.cdn(12345)
+        #
+        #   # Get bandwidth data
+        #   bandwidth = cdn.analytics.bandwidths({
+        #     domain: "All",
+        #     startTime: "2025-01-01T00:00:00Z",
+        #     endTime: "2025-01-01T23:59:59Z",
+        #     interval: "hour"
+        #   })
+        #
+        #   # Get viewer statistics
+        #   viewers = cdn.analytics.viewers({
+        #     domain: "streaming.example.com",
+        #     startTime: "2025-01-01T00:00:00Z",
+        #     endTime: "2025-01-01T23:59:59Z",
+        #     interval: "minute"
+        #   })
+        #
+        # @since 1.0.0
+        class Analytics
+          # @return [CDN] the parent CDN service instance
+          attr_reader :parent
+
+          # Initialize analytics service
+          #
+          # @param parent [CDN] the parent CDN service instance
+          def initialize(parent)
+            @parent = parent
+          end
+
+          # Get bandwidth analytics data
+          #
+          # @param payload [Hash] analytics parameters
+          # @option payload [String] :domain domain name or "All" for all domains
+          # @option payload [String] :startTime start time in ISO 8601 format ("2025-01-01T00:00:00Z")
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [String] :interval time interval ("minute", "hour", "day")
+          # @option payload [Boolean] :fillFixedTime whether to fill missing time slots
+          # @option payload [String] :daHostName specific hostname filter
+          #
+          # @return [Hash, nil] bandwidth data with averageThroughput and data array, or nil on error
+          #
+          # @example Get hourly bandwidth for all domains
+          #   bandwidth = cdn.analytics.bandwidths({
+          #     domain: "All",
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-01T23:59:59Z",
+          #     interval: "hour",
+          #     fillFixedTime: true
+          #   })
+          #   puts bandwidth[:averageThroughput]
+          #   bandwidth[:data].each { |point| puts "#{point['time']}: #{point['value']}" }
+          #
+          # @since 1.0.0
+          def bandwidths(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/bandwidth', payload))
+            if response&.[]('bandwidth')
+              {
+                averageThroughput: response&.[]('averageThroughput'),
+                data: response&.[]('bandwidth'),
+              }
+            end
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get volume analytics data
+          #
+          # @param payload [Hash] analytics parameters
+          # @option payload [String] :domain domain name or "All" for all domains
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [String] :interval time interval ("minute", "hour", "day")
+          # @option payload [Boolean] :fillFixedTime whether to fill missing time slots
+          #
+          # @return [Hash, nil] volume data with domain and volumes array, or nil on error
+          #
+          # @example Get daily volume data
+          #   volume = cdn.analytics.volumes({
+          #     domain: "example.com",
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-31T00:00:00Z",
+          #     interval: "day"
+          #   })
+          #   puts "Domain: #{volume[:domain]}"
+          #   volume[:data].each { |point| puts "#{point['time']}: #{point['bytes']} bytes" }
+          #
+          # @since 1.0.0
+          def volumes(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/volume', payload))
+            { data: response&.[]('volumes') } if response&.[]('volumes')
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get viewer analytics data
+          #
+          # @param payload [Hash] analytics parameters
+          # @option payload [String] :domain domain name or "All" for all domains
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [String] :interval time interval ("minute", "hour", "day")
+          #
+          # @return [Array, nil] array of viewer data points, or nil on error
+          #
+          # @example Get viewer statistics
+          #   viewers = cdn.analytics.viewers({
+          #     domain: "streaming.example.com",
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-01T23:59:59Z",
+          #     interval: "minute"
+          #   })
+          #   viewers.each { |point| puts "#{point['time']}: #{point['viewers']} viewers" }
+          #
+          # @since 1.0.0
+          def viewers(payload)
+            JSON.parse(@parent.send(:call, 'POST', '/api/report/viewers', payload))
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get requests per second (RPS) analytics
+          #
+          # @param payload [Hash] analytics parameters (passed as query string)
+          # @option payload [String] :domain domain name or "All" for all domains
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [String] :interval time interval
+          #
+          # @return [Hash, nil] RPS data with statistics and time series, or nil on error
+          #
+          # @example Get RPS data
+          #   rps = cdn.analytics.request_per_second({
+          #     domain: "api.example.com",
+          #     startTime: "2025-01-01T12:00:00Z",
+          #     endTime: "2025-01-01T13:00:00Z"
+          #   })
+          #   puts "Max RPS: #{rps[:maxQuantity]}"
+          #   puts "Avg RPS: #{rps[:avgQuantity]}"
+          #   puts "HTTP Total: #{rps[:httpTotalQuantity]}"
+          #   puts "HTTPS Total: #{rps[:httpsTotalQuantity]}"
+          #
+          # @since 1.0.0
+          def request_per_second(payload)
+            response = JSON.parse(@parent.send(:call, 'GET', "/api/rps_chart_data?#{payload.to_query}"))
+            if response&.[]('datas')
+              {
+                maxQuantity: response['maxQuantity'],
+                avgQuantity: response['avgQuantity'],
+                httpTotalQuantity: response['httpTotalQuantity'],
+                httpsTotalQuantity: response['httpsTotalQuantity'],
+                data: response['datas'],
+              }
+            end
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get HTTP status code analytics
+          #
+          # @param payload [Hash] analytics parameters
+          # @option payload [Array<String>] :domains array of domain names
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [String] :interval time interval
+          #
+          # @return [Hash, nil] HTTP status code distribution data, or nil on error
+          #
+          # @example Get HTTP status codes
+          #   codes = cdn.analytics.http_codes({
+          #     domains: ["example.com"],
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-01T23:59:59Z",
+          #     interval: "hour"
+          #   })
+          #   puts "2xx responses: #{codes['2xx']}"
+          #   puts "4xx responses: #{codes['4xx']}"
+          #
+          # @since 1.0.1
+          def http_codes(payload)
+            JSON.parse(@parent.send(:call, 'POST', "/api/report/customers/#{@parent.customer_id}/http_codes", payload))
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get referrer analytics by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @option payload [String] :customerId customer ID
+          # @option payload [String] :serviceName domain/service name
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [Integer] :pageNumber page number (0-based)
+          # @option payload [Integer] :pageSize number of results per page
+          #
+          # @return [Array] array of referrer data, or empty array on error
+          #
+          # @example Get top referrers
+          #   referrers = cdn.analytics.referrer_by_domain({
+          #     customerId: "12345",
+          #     serviceName: "example.com",
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-07T00:00:00Z",
+          #     pageNumber: 0,
+          #     pageSize: 20
+          #   })
+          #   referrers.each { |ref| puts "#{ref['referrer']}: #{ref['requests']} requests" }
+          #
+          # @since 1.0.1
+          def referrer_by_domain(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/getReferrerByDomain', payload))
+            response&.[]('list') || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get popular content URLs by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @option payload [String] :customerId customer ID
+          # @option payload [String] :serviceName domain/service name
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [Integer] :pageNumber page number (0-based)
+          # @option payload [Integer] :pageSize number of results per page
+          #
+          # @return [Array] array of popular URL data, or empty array on error
+          #
+          # @example Get most requested URLs
+          #   urls = cdn.analytics.popular_content_url_by_domain({
+          #     customerId: "12345",
+          #     serviceName: "cdn.example.com",
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-07T00:00:00Z",
+          #     pageNumber: 0,
+          #     pageSize: 50
+          #   })
+          #   urls.each { |url| puts "#{url['url']}: #{url['requests']} requests" }
+          #
+          # @since 1.0.1
+          def popular_content_url_by_domain(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/getUrlByDomain', payload))
+            response&.[]('list') || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get origin request analytics
+          #
+          # @param payload [Hash] analytics parameters (passed as query string)
+          # @option payload [String] :domain domain name
+          # @option payload [String] :startTime start time in ISO 8601 format
+          # @option payload [String] :endTime end time in ISO 8601 format
+          # @option payload [String] :interval time interval
+          #
+          # @return [Hash, nil] origin request data with time series, or nil on error
+          #
+          # @example Get origin request data
+          #   origin = cdn.analytics.origin_request({
+          #     domain: "example.com",
+          #     startTime: "2025-01-01T00:00:00Z",
+          #     endTime: "2025-01-01T23:59:59Z",
+          #     interval: "hour"
+          #   })
+          #   origin[:data].each { |point| puts "#{point['time']}: #{point['requests']} origin requests" }
+          #
+          # @since 1.0.0
+          def origin_request(payload)
+            response = JSON.parse(@parent.send(:call, 'GET', "/api/origin_request_chart_data?#{payload.to_query}"))
+            { data: response['requestSpots'] } if response&.[]('requestSpots')
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get request hit rate analytics
+          #
+          # @param params [Hash] analytics parameters (passed as query string)
+          # @option params [String] :domain domain name or "All"
+          # @option params [String] :startTime start time in ISO 8601 format
+          # @option params [String] :endTime end time in ISO 8601 format
+          # @option params [String] :interval time interval
+          # @option params [Boolean] :fillFixedTime fill missing time slots
+          #
+          # @return [Hash, nil] hit rate data, or nil on error
+          #
+          # @since 1.0.8
+          def request_hit_rate(params)
+            query_string = URI.encode_www_form(params)
+            response = JSON.parse(@parent.send(:call, 'GET', "/api/hit_rate_chart_data?#{query_string}", nil))
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get byte hit rate analytics
+          #
+          # @param params [Hash] analytics parameters (passed as query string)
+          # @return [Hash, nil] byte hit rate data, or nil on error
+          # @since 1.0.8
+          def byte_hit_rate(params)
+            query_string = URI.encode_www_form(params)
+            response = JSON.parse(@parent.send(:call, 'GET', "/api/byte_rate_chart_data?#{query_string}", nil))
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get origin bandwidth analytics
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Array] origin bandwidth data, or empty array on error
+          # @since 1.0.8
+          def origin_bandwidth(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/origin_bandwidth', payload))
+            response || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get number of concurrent viewers by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Array] concurrent viewer data, or empty array on error
+          # @since 1.0.8
+          def number_of_concurrent_viewers(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/domain/viewers', payload))
+            response || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get origin HTTP status codes
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Array] origin HTTP code data, or empty array on error
+          # @since 1.0.8
+          def origin_http_codes(payload)
+            customer_id = @parent.send(:customer_id)
+            response = JSON.parse(@parent.send(:call, 'POST', "/api/report/customers/#{customer_id}/origin_http_codes", payload))
+            response || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get total referrer count by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Hash, nil] total referrer data, or nil on error
+          # @since 1.0.8
+          def referrer_total_by_domain(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/getReferrerTotalByDomain', payload))
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get referrer CSV export by domain
+          #
+          # @param payload [Hash] analytics parameters with csvRequest: 1
+          # @return [String, nil] CSV data, or nil on error
+          # @since 1.0.8
+          def referrer_csv_by_domain(payload)
+            response = @parent.send(:call, 'POST', '/api/report/getReferrerCsvByDomain', payload)
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get total popular content URL count by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Hash, nil] total URL data, or nil on error
+          # @since 1.0.8
+          def popular_content_url_total_by_domain(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/getUrlTotalByDomain', payload))
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get popular content URL CSV export by domain
+          #
+          # @param payload [Hash] analytics parameters with csvRequest: 1
+          # @return [String, nil] CSV data, or nil on error
+          # @since 1.0.8
+          def popular_content_url_csv_by_domain(payload)
+            response = @parent.send(:call, 'POST', '/api/report/getUrlCsvByDomain', payload)
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get request and visit number statistics
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Hash, nil] request/visit statistics, or nil on error
+          # @since 1.0.8
+          def request_visit_number(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/request_visit_number', payload))
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+
+          # Get ISP analytics
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Array] ISP data, or empty array on error
+          # @since 1.0.8
+          def isp(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/isp', payload))
+            response || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get user agent analytics by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [Array] user agent data, or empty array on error
+          # @since 1.0.8
+          def user_agent(payload)
+            response = JSON.parse(@parent.send(:call, 'POST', '/api/report/domain/userAgent', payload))
+            response&.[]('list') || []
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get user agent CSV export by domain
+          #
+          # @param payload [Hash] analytics parameters
+          # @return [String, nil] CSV data, or nil on error
+          # @since 1.0.8
+          def user_agent_csv(payload)
+            response = @parent.send(:call, 'POST', '/api/report/domain/userAgentCsv', payload)
+            response
+          rescue StandardError => e
+            @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            nil
+          end
+        end
+      end
+    end
+  end
+end