conversant 1.0.16

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

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require_relative 'authorization'
+
+module Conversant
+  module V3
+    module Services
+      # Portal service for Conversant/SwiftFederation administration
+      #
+      # Provides access to portal functionality including appliance management
+      # and infrastructure monitoring.
+      #
+      # @example Basic usage
+      #   portal = Conversant::V3.portal(12345)
+      #
+      #   # Get appliances for current month
+      #   appliances = portal.appliances
+      #
+      #   # Get appliances for specific date range
+      #   appliances = portal.appliances('2025-01-01T00:00:00Z', '2025-01-31T23:59:59Z')
+      #
+      # @since 1.0.0
+      class Portal < ::Conversant::V3::Base
+        include Authorization
+
+        # Redis key prefix for caching appliance data
+        MASTER_APPLIANCE_REDIS_KEY = 'CONVERSANT.V3.PORTAL.APPLIANCE.ITEMS'
+
+        # Retrieves appliance data for a specified date range
+        #
+        # Returns information about appliances (CDN nodes) including their IP addresses,
+        # hostnames, locations (POP), traffic volume, and federation volume. Results are
+        # cached in Redis for 10 minutes to improve performance.
+        #
+        # @param gte [String, nil] Start date/time in ISO 8601 format (defaults to beginning of current month)
+        # @param lte [String, nil] End date/time in ISO 8601 format (defaults to end of current month)
+        #
+        # @return [Array<Hash>] Array of appliance hashes with keys:
+        #   - :ip [String] IP address of the appliance
+        #   - :hostname [String] Hostname of the appliance
+        #   - :deleted [Boolean] Whether the appliance has been deleted
+        #   - :pop [String] Point of Presence (datacenter location)
+        #   - :volume [Integer] Traffic volume in bytes
+        #   - :federation [Integer] Federation traffic volume in bytes
+        #
+        # @example Get appliances for current month
+        #   appliances = portal.appliances
+        #   appliances.each do |appliance|
+        #     puts "#{appliance[:hostname]} (#{appliance[:ip]}) - #{appliance[:pop]}"
+        #     puts "  Volume: #{appliance[:volume]} bytes"
+        #     puts "  Federation: #{appliance[:federation]} bytes"
+        #   end
+        #
+        # @example Get appliances for specific date range
+        #   start_date = '2025-01-01T00:00:00Z'
+        #   end_date = '2025-01-31T23:59:59Z'
+        #   appliances = portal.appliances(start_date, end_date)
+        #
+        # @since 1.0.0
+        def appliances(gte = nil, lte = nil)
+          today = Date.today.to_datetime
+
+          gte ||= today.beginning_of_month.strftime('%Y-%m-%dT00:00:00Z')
+          lte ||= today.end_of_month.strftime('%Y-%m-%dT23:59:59Z')
+
+          key = "#{MASTER_APPLIANCE_REDIS_KEY}.#{gte.to_datetime&.strftime('%Y%m')}"
+
+          items = redis.get(key)
+
+          if items.nil?
+            logger.debug "#{identifier}.METHOD:appliances.FETCHING_DATA"
+
+            payload = {
+              startTime: gte,
+              endTime: lte
+            }
+
+            response = JSON.parse(call('POST', '/load_appliance_data', payload))
+
+            items = response&.[]('applianceList')&.map do |item|
+              {
+                ip: item['ip'],
+                hostname: item['hostname'],
+                deleted: item['deleted'],
+                pop: item['pop'],
+                volume: item['volume'],
+                federation: item['federationVolume'],
+              }
+            end.to_json
+
+            redis.set(key, items, ex: 600)
+          end
+
+          JSON.parse(items)
+        rescue StandardError => e
+          logger.error "#{identifier}.METHOD:appliances.ERROR:#{e.message}"
+          []
+        end
+
+        # Get dashboard service instance
+        #
+        # @return [Dashboard] dashboard service for customer metadata and reporting
+        # @since 1.0.8
+        def dashboard
+          @dashboard ||= Dashboard.new(self)
+        end
+
+        protected
+
+        # Makes an authenticated API call to the Portal service
+        #
+        # Validates SESSION cookie presence before making the request and handles
+        # HTTP errors appropriately.
+        #
+        # @param method [String] HTTP method ('GET', 'POST', etc.)
+        # @param uri [String] API endpoint URI (relative to portal_endpoint)
+        # @param payload [Hash, nil] Request payload for POST/PUT requests
+        #
+        # @return [String] Response body
+        #
+        # @raise [AuthenticationError] if SESSION cookie is missing
+        # @raise [ApiError] if HTTP response code is 400 or higher
+        def call(method, uri, payload = nil)
+          url = "#{portal_endpoint}#{uri}"
+
+          headers = authorized_headers
+
+          # Check for SESSION in Cookie header
+          if headers['Cookie'].nil? || !headers['Cookie'].include?('SESSION=')
+            logger.error "#{identifier}.METHOD:call.NO_SESSION"
+            raise AuthenticationError, 'Missing SESSION for Portal'
+          end
+
+          code, response = request(method, url, payload, headers)
+
+          if code >= 400
+            logger.error "#{identifier}.METHOD:call.HTTP_ERROR:#{code}"
+            raise ApiError, "Portal API error: #{code}"
+          end
+
+          response.body
+        end
+
+        private
+
+        # Fetches a new SESSION cookie for Portal API access
+        #
+        # Authenticates with root portal sessions (SESSION + SSO_GW_SESSION2) and
+        # exchanges them for a customer-specific SESSION cookie. The new session
+        # is cached in Redis with the configured TTL.
+        #
+        # @return [String, nil] The SESSION cookie value, or nil if authentication fails
+        def fetch_new_session
+          sessions = authenticate
+          return nil unless sessions && sessions[:session] && sessions[:sso_gw_session2]
+
+          logger.debug "#{identifier}.METHOD:authorize.REQUESTING_SESSION"
+
+          response = RestClient.get(
+            "#{portal_endpoint}/?cId=#{customer_id}",
+            {
+              authority: URI.parse(portal_endpoint).hostname,
+              referer: portal_endpoint,
+              user_agent: configuration.default_ua,
+              cookies: {
+                'SESSION': sessions[:session],
+                'SSO_GW_SESSION2': sessions[:sso_gw_session2]
+              },
+              timeout: 30,
+              open_timeout: 30
+            }
+          )
+
+          if response.cookies['SESSION']
+            session_cookie = response.cookies['SESSION']
+            redis.set(session_cache_key, session_cookie, ex: configuration.cache_ttl)
+            logger.debug "#{identifier}.METHOD:authorize.SESSION_OBTAINED"
+            session_cookie
+          else
+            logger.error "#{identifier}.METHOD:authorize.NO_SESSION_IN_RESPONSE"
+            nil
+          end
+        rescue RestClient::Unauthorized, RestClient::Forbidden => e
+          logger.error "#{identifier}.METHOD:authorize.AUTH_ERROR:#{e.message}"
+          nil
+        rescue StandardError => e
+          logger.error "#{identifier}.METHOD:authorize.ERROR:#{e.message}"
+          nil
+        end
+
+        protected
+
+        # Returns the Portal service endpoint URL
+        #
+        # @return [String] The portal endpoint URL
+        def service_endpoint
+          portal_endpoint
+        end
+
+        # Returns the session cookie name used by Portal service
+        #
+        # @return [String] The cookie name ('SESSION')
+        def session_cookie_name
+          'SESSION'
+        end
+
+        # Indicates whether Portal service requires a session cookie
+        #
+        # @return [Boolean] true (Portal requires SESSION cookie)
+        def requires_session?
+          true
+        end
+      end
+    end
+  end
+end
+
+# Load nested service classes after Portal is defined
+require_relative 'portal/dashboard'

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Conversant
+  module V3
+    module Services
+      class VMS
+        # Analytics service for VMS metrics
+        #
+        # Provides analytics data for video transcoding operations
+        # including duration and volume metrics for reporting and
+        # capacity planning.
+        #
+        # @example Get transcoding analytics
+        #   vms = Conversant::V3.vms(12345)
+        #
+        #   # Get transcoding duration metrics
+        #   duration = vms.analytics.transcoding({
+        #     startTime: "2025-01-01",
+        #     endTime: "2025-01-31"
+        #   })
+        #
+        #   # Get volume metrics
+        #   volume = vms.analytics.volume({
+        #     startTime: "2025-01-01",
+        #     endTime: "2025-01-31"
+        #   })
+        #
+        # @since 1.0.0
+        class Analytics
+          # @return [VMS] the parent VMS service instance
+          attr_reader :parent
+
+          # Initialize analytics service
+          #
+          # @param parent [VMS] the parent VMS service instance
+          def initialize(parent)
+            @parent = parent
+          end
+
+          # Get transcoding duration analytics
+          #
+          # Retrieves duration metrics for video transcoding operations
+          # over a specified time range. Useful for capacity planning
+          # and billing calculations.
+          #
+          # @param payload [Hash] query parameters including time range
+          # @option payload [String] :startTime start date/time
+          # @option payload [String] :endTime end date/time
+          #
+          # @return [Array] transcoding duration metrics, or empty array on error
+          #
+          # @example Get monthly transcoding duration
+          #   duration = vms.analytics.transcoding({
+          #     startTime: "2025-01-01",
+          #     endTime: "2025-01-31"
+          #   })
+          #   puts "Total duration: #{duration.sum} minutes"
+          #
+          # @since 1.0.0
+          def transcoding(payload)
+            merged_payload = payload.merge(type: nil)
+            response = @parent.send(:call, 'GET', "/reporting/vms/transcoding/duration?#{merged_payload.to_query}")
+            return [] if response.nil?
+
+            JSON.parse(response)
+          rescue StandardError => e
+            logger.error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get volume analytics for transcoding
+          #
+          # Retrieves volume metrics (in bytes/GB) for transcoded video data
+          # over a specified time range. Useful for storage capacity planning
+          # and bandwidth analysis.
+          #
+          # @param payload [Hash] query parameters including time range
+          # @option payload [String] :startTime start date/time
+          # @option payload [String] :endTime end date/time
+          #
+          # @return [Array] volume metrics for transcoding operations, or empty array on error
+          #
+          # @example Get monthly transcoding volume
+          #   volume = vms.analytics.volume({
+          #     startTime: "2025-01-01",
+          #     endTime: "2025-01-31"
+          #   })
+          #   puts "Total volume: #{volume.sum} GB"
+          #
+          # @since 1.0.0
+          def volume(payload)
+            merged_payload = payload.merge(type: nil)
+            response = @parent.send(:call, 'GET', "/reporting/vms/transcoding/volume?#{merged_payload.to_query}")
+            return [] if response.nil?
+
+            JSON.parse(response)
+          rescue StandardError => e
+            logger.error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          private
+
+          # Get logger instance from parent
+          #
+          # @return [Logger] logger instance
+          def logger
+            @parent.send(:logger)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/conversant/v3/services/vms/business.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Conversant
+  module V3
+    module Services
+      class VMS
+        # Business metrics service for VMS
+        #
+        # Provides business-level metrics for billing and reporting
+        # including duration, volume, and transcoding statistics broken
+        # down by resolution (SD, HD, UHD) and operation type.
+        #
+        # @example Get business metrics
+        #   vms = Conversant::V3.vms(12345)
+        #
+        #   # Get duration metrics for billing
+        #   duration = vms.business.duration({
+        #     startTime: Time.now.beginning_of_month
+        #   })
+        #
+        #   # Get comprehensive transcoding breakdown
+        #   breakdown = vms.business.transcoding({
+        #     startTime: Time.now.beginning_of_month
+        #   })
+        #   puts "SD: #{breakdown[:vms_transcoding_sd]}"
+        #   puts "HD: #{breakdown[:vms_transcoding_hd]}"
+        #   puts "UHD: #{breakdown[:vms_transcoding_uhd]}"
+        #
+        # @since 1.0.0
+        class Business
+          # @return [VMS] the parent VMS service instance
+          attr_reader :parent
+
+          # Initialize business metrics service
+          #
+          # @param parent [VMS] the parent VMS service instance
+          def initialize(parent)
+            @parent = parent
+          end
+
+          # Get video duration metrics for billing
+          #
+          # Retrieves video transcoding duration metrics aggregated by month
+          # for billing and usage reporting purposes.
+          #
+          # @param payload [Hash] query parameters including month/year
+          # @option payload [Time, String] :startTime start time (used to extract month)
+          #
+          # @return [Array] duration metrics for billing purposes, or empty array on error
+          #
+          # @example Get current month duration
+          #   duration = vms.business.duration({
+          #     startTime: Time.now.beginning_of_month
+          #   })
+          #
+          # @since 1.0.0
+          def duration(payload)
+            month = extract_month(payload)
+            search_payload = {
+              month: month,
+              selectType: 'vtd',
+              customerType: @parent.type || 2,
+              _: (Time.now.to_f * 1000).to_i.to_s
+            }
+
+            response = @parent.send(:call, 'GET', "/v5/reporting/vms/business/usage/search?#{search_payload.to_query}")
+            return [] if response.nil?
+
+            JSON.parse(response)
+          rescue StandardError => e
+            logger.error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get video volume metrics for billing
+          #
+          # Retrieves video transcoding volume metrics aggregated by month
+          # for storage billing and capacity planning.
+          #
+          # @param payload [Hash] query parameters including month/year
+          # @option payload [Time, String] :startTime start time (used to extract month)
+          #
+          # @return [Array] volume metrics for billing purposes, or empty array on error
+          #
+          # @example Get current month volume
+          #   volume = vms.business.volume({
+          #     startTime: Time.now.beginning_of_month
+          #   })
+          #
+          # @since 1.0.0
+          def volume(payload)
+            month = extract_month(payload)
+            search_payload = {
+              month: month,
+              selectType: 'vtv',
+              customerType: @parent.type || 2,
+              _: (Time.now.to_f * 1000).to_i.to_s
+            }
+
+            response = @parent.send(:call, 'GET', "/v5/reporting/vms/business/usage/search?#{search_payload.to_query}")
+            return [] if response.nil?
+
+            JSON.parse(response)
+          rescue StandardError => e
+            logger.error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            []
+          end
+
+          # Get comprehensive transcoding metrics breakdown
+          #
+          # Retrieves detailed transcoding metrics broken down by resolution
+          # (SD, HD, UHD) and operation type (transcoding vs transmuxing).
+          # Useful for detailed billing and capacity analysis.
+          #
+          # @param payload [Hash] query parameters including month/year
+          # @option payload [Time, String] :startTime start time (used to extract month)
+          #
+          # @return [Hash] transcoding metrics breakdown with keys:
+          #   - :vms_transcoding [Float] total transcoding duration
+          #   - :vms_transmuxing [Float] transmuxing duration
+          #   - :vms_transcoding_sd [Float] SD transcoding duration
+          #   - :vms_transcoding_hd [Float] HD transcoding duration
+          #   - :vms_transcoding_uhd [Float] UHD transcoding duration
+          #
+          # @example Get transcoding breakdown
+          #   breakdown = vms.business.transcoding({
+          #     startTime: Time.now.beginning_of_month
+          #   })
+          #   puts "Total transcoding: #{breakdown[:vms_transcoding]} minutes"
+          #   puts "SD: #{breakdown[:vms_transcoding_sd]} minutes"
+          #   puts "HD: #{breakdown[:vms_transcoding_hd]} minutes"
+          #   puts "UHD: #{breakdown[:vms_transcoding_uhd]} minutes"
+          #   puts "Transmuxing: #{breakdown[:vms_transmuxing]} minutes"
+          #
+          # @since 1.0.0
+          def transcoding(payload)
+            report_vms = {
+              vms_transcoding: 0,
+              vms_transmuxing: 0,
+              vms_transcoding_sd: 0,
+              vms_transcoding_hd: 0,
+              vms_transcoding_uhd: 0
+            }
+
+            vms_trans = duration(payload)&.first
+            return report_vms unless vms_trans
+
+            name = vms_trans.keys&.first
+            if vms_trans[name].present? && !vms_trans[name].empty?
+              vms_trans[name]&.each do |item|
+                report_vms[:vms_transmuxing] += item['transmux']&.to_f || 0
+                report_vms[:vms_transcoding_sd] += (item['h264SdTranscoding']&.to_f || 0) + (item['h265SdTranscoding']&.to_f || 0)
+                report_vms[:vms_transcoding_hd] += (item['h264HdTranscoding']&.to_f || 0) + (item['h265HdTranscoding']&.to_f || 0)
+                report_vms[:vms_transcoding_uhd] += (item['h264UhdTranscoding']&.to_f || 0) + (item['h265UhdTranscoding']&.to_f || 0)
+              end
+            end
+
+            report_vms[:vms_transcoding] =
+              report_vms[:vms_transcoding_sd] +
+              report_vms[:vms_transcoding_hd] +
+              report_vms[:vms_transcoding_uhd]
+
+            report_vms
+          rescue StandardError => e
+            logger.error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+            report_vms
+          end
+
+          private
+
+          # Extract month in YYYYMM format from payload
+          #
+          # @param payload [Hash] payload containing startTime
+          # @return [String] month in YYYYMM format
+          def extract_month(payload)
+            start_time = payload[:startTime] || Time.now.beginning_of_month
+            start_time.to_datetime.strftime('%Y%m')
+          end
+
+          # Get logger instance from parent
+          #
+          # @return [Logger] logger instance
+          def logger
+            @parent.send(:logger)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/conversant/v3/services/vms/partner/analytics.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Conversant
+  module V3
+    module Services
+      class VMS
+        class Partner
+          # VMS analytics service for partner-level reporting
+          #
+          # Provides partner-level analytics and reporting for Video Management System services
+          # including VOD duration and transcoding metrics across multiple customer accounts.
+          #
+          # @since 1.0.12
+          class Analytics
+            # @return [Conversant::V3::Services::VMS] the parent VMS service instance
+            attr_reader :parent
+
+            # Initialize partner VMS analytics service
+            #
+            # @param parent [Conversant::V3::Services::VMS] the parent VMS service instance
+            def initialize(parent)
+              @parent = parent
+            end
+
+            # Get business service instance
+            #
+            # Provides access to business-focused analytics that aggregate transcoding
+            # data for VOD billing and capacity planning.
+            #
+            # @return [Business] business service for VMS aggregated analytics
+            # @since 1.0.16
+            #
+            # @example Access business methods
+            #   vms = Conversant::V3.vms(12345)
+            #   business = vms.partner.analytics.business
+            #   metrics = business.transcoding(startTime: Time.now.beginning_of_month)
+            def business
+              @business ||= Business.new(self)
+            end
+
+            # Get duration of VOD (Video on Demand) for business usage reporting
+            #
+            # Retrieves VOD transcoding duration metrics aggregated by month and customer type
+            # for partner-level business reporting and billing purposes.
+            #
+            # @param args [Hash] query parameters
+            # @option args [Time, String] :startTime start time for the report (defaults to beginning of current month)
+            # @option args [String, Integer] :type customer type filter (defaults to 2)
+            #
+            # @return [Array] VOD duration data, or empty array on error
+            #
+            # @example Get VOD duration for current month
+            #   duration = vms.partner.analytics.duration_of_vod
+            #   puts "Total VOD duration: #{duration.first['total_duration']} minutes"
+            #
+            # @since 1.0.8
+            def duration_of_vod(**args)
+              month, type, timestamp = queries(**args)
+
+              payload = {
+                month: month,
+                selectType: 'vtd',
+                customerType: type,
+                _: timestamp
+              }
+
+              response = @parent.send(:call, 'GET', "/v5/reporting/vms/business/usage/search?#{payload.to_query}")
+              return [] if response.nil?
+
+              JSON.parse(response)&.map(&:with_indifferent_access) || []
+            rescue StandardError => e
+              @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+              []
+            end
+
+            # Get VMS transcoding duration metrics
+            #
+            # Retrieves transcoding duration metrics for video processing operations,
+            # useful for capacity planning and billing calculations.
+            #
+            # @param params [Hash] query parameters
+            # @option params [String] :year year in YYYY format
+            #
+            # @return [Array] transcoding duration data, or empty array on error
+            #
+            # @example Get transcoding duration for a year
+            #   duration = vms.partner.analytics.duration(year: "2025")
+            #   puts "Total transcoding: #{duration['total']} hours"
+            #
+            # @since 1.0.8
+            def duration(params = {})
+              query_string = params.map { |k, v| "#{k}=#{v}" }.join('&')
+              uri = '/reporting/vms/transcoding/duration'
+              uri += "?#{query_string}" unless query_string.empty?
+              response = @parent.send(:call, 'GET', uri)
+              return [] if response.nil?
+
+              JSON.parse(response)&.map(&:with_indifferent_access) || []
+            rescue StandardError => e
+              @parent.send(:logger).error "#{@parent.send(:identifier)}.METHOD:#{__method__}.EXCEPTION:#{e.message}"
+              []
+            end
+
+            private
+
+            def logger
+              @parent.send(:logger)
+            end
+
+            # Helper method to build query parameters
+            #
+            # Generates month, customer type, and timestamp parameters for VMS business usage queries.
+            # Defaults to current month if startTime is not provided.
+            #
+            # @param args [Hash] Input parameters
+            # @option args [Time, String] :startTime Start time for the report (defaults to beginning of current month)
+            # @option args [String, Integer] :type Customer type filter (defaults to parent's type or 2)
+            #
+            # @return [Array<String, Integer, Integer>] Array containing [month (YYYYMM), customer_type, timestamp (ms)]
+            def queries(**args)
+              month = (args[:startTime] || Time.now&.beginning_of_month)&.to_datetime&.strftime('%Y%m')
+              customer_type = args[:type]
+              customer_type = @parent.type || 2 unless customer_type.present?
+              timestamp = Time.now.getutc.to_i * 1000
+
+              [month, customer_type, timestamp]
+            end
+          end
+        end
+      end
+    end
+  end
+end