module Bluekai
  class Category < Client
    ####
    #### Categories
    ####
    #### API definition can be found here
    #### https://kb.bluekai.com/display/PD/Self-Classification+Category+API
    ####

    # Public: Lists self classification categories in private taxonomy
    #
    # name:string - Returns all self-classification categories based on the specified
    #               name (whole or partial). The name is case-insensitive.
    #
    # offset:integer - Specify the starting index from which to return
    #                  the self-classification categories.
    #
    # size:integer - Specifies the maximum number of categories to be included in
    #                the response. This filter requires the offset filter to be specified.
    #
    # parent_id:integer - Returns all self-classification categories
    #                     based on the ID of the specified parent category.
    #
    # sort_by:string - Enter 'name' or 'id' to sort the returned self-classification categories in
    #                  alphabetical or numerical order (based on categoryId)
    #
    # sorting_order:string - Enter 'asc' or 'desc' to list the returned
    #                        self-classification categories in ascending
    #                        or descending order based on the category
    #                        name or categoryId.
    #
    # Returns array of category hashes
    def category_list(query = {})
      query = { sort_by: 'name',
                sorting_order: 'asc' }.merge(query)
      request('GET', '/Services/WS/classificationCategories', query)[:categories]
    end

    # Public: returns the self-classification category
    #         specified by the category_id
    #
    # category_id:integer - MANDATORY The unique ID assigned to the
    #                       self-classification category to be retrieved
    #
    # stats:string - {'True','False'} Returns the reach (estimated
    #                 number of unique users based on 30-day
    #                 inventory) for the self-classification category.
    #
    # device_type:string - reach for the self-classification category
    #                      based on the specified device, which may either
    #                      be 'all', 'desktop', or 'mobile'
    #
    # intl_code - returns the reach for the self-classification category
    #             based on the specified country. The default country
    #             is ALL. You may enter one of the following country
    #             codes: ALL, US, AU, CA, GB, GER, ESP, NL, MX, IT,
    #             FR, BR, AR, RU, NZ, JP, CL, CN.
    #
    # Returns: A hash of Bluekai private category data
    def category_read(query)
      fail 'no category_id found in hash' unless query.key?(:category_id)
      category_id = query.delete(:category_id)
      request('GET', "/Services/WS/classificationCategories/#{category_id}", query)
    end

    # Public: Creates a new self-classification category
    #
    # name:string - Name of the self-classification category
    #
    # parent_id:integer - Unique ID of the parent node for the
    #                     self-classification category.
    #
    # description:string - Description of uUser attribute
    #                      represented by this category.
    #
    # analytics_excluded:string - {'True','False'} Specify whether the
    #                   self-classification category is to be excluded
    #                   from Audience Analytics reports. This property
    #                   is false by default.
    #
    # navigation_only:string - {'True','False'} Specify whether the
    #                          self-classification category functions
    #                          exclusively as a parent node that cannot be
    #                          selected. This property is false by default.
    #
    # mutex_children:string - {'True','False'} Specify whether to limit
    #                         the number of the category's child nodes
    #                         that can be added to an audience segment to one.
    #                         This property is false by default.
    #
    # notes:string - (Optional) Enter any notes to be associated with
    #                this self-classification category.
    #
    # Example body hash = {name: 'a new category',
    #                parent_id: '2342', description: 'an example category',
    #                analytics_excluded: 'false', navigation_only: 'false',
    #                mutex_children: 'false', notes: 'Just an API test' }
    #
    # Returns: hash of created category parameters including its category_id
    def category_create(body)
      request('POST', '/Services/WS/classificationCategories', {}, body)
    end

    # Public: Updates a given self-classification category
    #
    # category_id:integer - The unique ID assigned to the self-classification
    #                       category to be updated
    #
    # name:string - Name of the self-classification category
    #
    # parent_id:integer - Unique ID of the parent node for the
    #                     self-classification category.
    #
    # description:string - Description of uUser attribute
    #                      represented by this category.
    #
    # analytics_excluded:string - {'True','False'} Specify whether the
    #                   self-classification category is to be excluded
    #                   from Audience Analytics reports. This property
    #                   is false by default.
    #
    # navigation_only:string - {'True','False'} Specify whether the
    #                          self-classification category functions
    #                          exclusively as a parent node that cannot be
    #                          selected. This property is false by default.
    #
    # mutex_children:string - {'True','False'} Specify whether to limit
    #                         the number of the category's child nodes
    #                         that can be added to an audience segment to one.
    #                         This property is false by default.
    #
    # notes:string - (Optional) Enter any notes to be associated with
    #                this self-classification category.
    #
    # Example body hash = {category_id: 1234, name: 'a chaged category',
    #                     parent_id: '2342', description: 'an example category',
    #                     analytics_exclued: 'false', navigation_only: 'false',
    #                     mutex_children: 'false', notes: 'Just an API test' }
    #
    # Returns: hash of updated category parameters
    def category_update(category_id, body)
      request('PUT', "/Services/WS/classificationCategories/#{category_id}", {}, body)
    end
  end
end