module GettyConnect
  class Client
    module Image 
      
      # Search for images by keyword.
      #
      # @param phrase [String] The search phrase. 
      # param options [Hash] A customisable set of options
      # @option options [Array] :filetypes String array of filetypes. Possible
      #   values are `eps` and `jpg`.
      # @option options [Integer] :item_count Number of items to return
      # @option options [Integer] :item_start_number Returns the index of 
      #   the first image. Use with `:item_count` to support pagination.
      # @option options [String] :language String. Specify an IETF RFC 5646 
      #   compliant language tag to determine the language used for localizable
      #   strings returned in the response. Defaults to `en-US`.
      # @option options [Array] :licenses Array of strings specifying a type 
      #   of license by which to filter results. 
      #   Possible values are: `royaltyfree`, `rightsmanaged`.
      # @option options [String] :orientations Possible values are: `horizontal`,
      #   `vertical`, `panoramichorizontal`, `panoramicvertical`, `square`
      # @option options [Array] :specific_persons Specify the personalities 
      #   to query the images that match all of the specified personalities.
      # @example Search for images of bears, returning a max. of 5 results
      #   client.search("bears", {:item_count => 5})
      def search(phrase, options={})
        
        request = {
          :RequestHeader => { :Token => self.token},
          :SearchForImages2RequestBody => {
            :Query => { 
              :SearchPhrase => phrase,
              :SpecificPersons => options[:specific_persons],
            },
            :Language => options[:language] || "en-us",
            :ResultOptions => {
              :ItemCount => options[:item_count] || 15,
              :ItemStartNumber => options[:item_start_number] || 1
            },
            :Filter => {
                :LicensingModels => options[:licenses] || ["royaltyfree"],
                :Orientations => options[:orientations],
                :FileTypes => options[:filetypes] || ["jpg"],
                :ProductOfferings => options[:product_offerings] || ["EasyAccess"]
            },
          }
        }
        post(@search_endpoint, request)
      end

      # Returns list of authorized downloads 
      def get_largest_download_auth(asset_ids, options={})
        asset_id_list = Array.new()
        asset_ids.each do |aid|
          asset_id_list << {:ImageId=>aid}
        end

        request = {
          :RequestHeader => {
            :Token => self.token,
            :CoordinationId => options[:coordination_id] || ""
          },
          :GetLargestImageDownloadAuthorizationsRequestBody => {
            :Images => asset_id_list
          },
        }
        post(@download_largest_endpoint, request)
      end

      # Returns detailed image metadata for all specified images.
      #
      # @param assetIds [Array] An array of AssetIds
      # @param options [Hash] A customisable set of options
      # @option options [String] :coordination_id Indicates the CoordinationId 
      #   value provided in the triggering request.
      # @option options [String] :country_code Enables hide/block rules based on
      #   locale-based limitations on content; filters out any image whose use is
      #   prohibited in the specific country. Accepts three-letter country codes
      #   as defined in ISO 3166-1 
      #   http://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Current_codes. 
      #   Defaults to USA.
      # @option options [String] :language String. Specify an IETF RFC 5646 
      #   compliant language tag to determine the language used for localizable
      #   strings returned in the response. Defaults to `en-US`.
      def get_details(assetIds, options={})
        request = {
          :RequestHeader => {
            :Token => self.token,
            :CoordinationId => options[:coordination_id] || ""
          },
          :GetImageDetailsRequestBody => {
            :CountryCode => options[:country_code] || "USA",
            :ImageIds => assetIds,
            :Language => options[:language] || "en-us"
          }
        }
        post(@image_details_endpoint, request)
      end

      # Convenience method. Returns a collection of urls and imageids 
      #
      # @param assetIds [Array] Array of assetIds 
      # @param preview_format [String] Format of preview image. Options in order 
      #   of size are: `thumb`, `preview`, `comp`, `watermark_preview`, 
      #   `watermark_comp`
      def get_preview(assetIds, preview_format)
        response = get_details(assetIds)
        preview = []
        response.GetImageDetailsResult.Images.each do |image, index|
          url = ""
          case preview_format
          when "comp"
            url = image.UrlComp
          when "preview"
            url = image.UrlPreview
          when "thumb"
            url = image.UrlThumb
          when "watermark_comp"
            url = image.UrlWatermarkComp
          when "watermark_preview"
            url = image.UrlWatermarkPreview
          end
          preview << { "imageId" => image.ImageId,
                       "url" => url }
        end
        preview 
      end

      # Requests download authorisation for image
      #
      # @param image_id [Integer] Id of image
      # @param size_key [String] Identifies size of the image being authorized
      #   for download. Returned from `get_details()`.
      def get_download_token(image_id, size_key)
        request = {
          :RequestHeader => {
            :Token => self.token
          },
          :GetImageDownloadAuthorizationsRequestBody => {
            :ImageSizes => [{
              :ImageId => image_id,
              :SizeKey => size_key
            }]
          }
        }
        response = post(@download_auth_endpoint, request)
        response.GetImageDownloadAuthorizationsResult.Images.first.Authorizations.first.DownloadToken
      end

      # Returns download urls and related data for images 
      #
      # @param download_token [String]  Specify the token authorizing the image
      #   download. Use the DownloadToken value provided by 
      #   `get_download_authorisation()` or `get_largest_download_authorisation()`
      # @option options [String] :coordination_id Value will be echoed in the
      #   response. Can be used to track requests.
      def download(download_token, options={})
        request = {
          :RequestHeader => {
            :Token => self.secure_token,
            :CoordinationId => options[:coordination_id] || ""
          },
          :CreateDownloadRequestBody => {
            :DownloadItems => [{
              :DownloadToken => download_token
            }]
          }
        }
        post(@download_request_endpoint, request, use_ssl=true)
      end

    end
  end
end