tiktok_business_api 0.1.0 → 0.2.0

data/lib/tiktok_business_api/resources/campaign.rb

@@ -3,111 +3,17 @@
 module TiktokBusinessApi
   module Resources
     # Campaign resource for the TikTok Business API
-    class Campaign < BaseResource
-      # Create a new campaign
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param params [Hash] Campaign parameters
-      # @return [Hash] New campaign data
-      def create(advertiser_id, params = {})
-        # Ensure advertiser_id is included in the params
-        params = params.merge(advertiser_id: advertiser_id)
-        
-        response = post('create/', params)
-        response['data']
-      end
-      
-      # Get a list of campaigns
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param params [Hash] Filter parameters
-      # @return [Hash] Campaign list response
-      def list(advertiser_id, params = {})
-        # Ensure advertiser_id is included in the params
-        params = params.merge(advertiser_id: advertiser_id)
-        
-        response = get('get/', params)
-        response['data']
-      end
-      
-      # Get a list of campaigns with pagination support
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param params [Hash] Filter parameters
-      # @yield [campaign] Block to process each campaign
-      # @yieldparam campaign [Hash] Campaign from the response
-      # @return [Array] All campaigns if no block is given
-      def list_all(advertiser_id, params = {}, &block)
-        # Ensure advertiser_id is included in the params
-        params = params.merge(advertiser_id: advertiser_id)
-        
-        paginate('get/', params, {}, 'list')
-      end
-      
-      # Get a campaign by ID
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param campaign_id [String] Campaign ID
-      # @return [Hash] Campaign data
-      def get(advertiser_id, campaign_id)
-        params = {
-          advertiser_id: advertiser_id,
-          campaign_ids: [campaign_id]
-        }
-        
-        response = get('get/', params)
-        campaigns = response.dig('data', 'list') || []
-        campaigns.first
-      end
-      
-      # Update a campaign
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param campaign_id [String] Campaign ID
-      # @param params [Hash] Campaign parameters to update
-      # @return [Hash] Updated campaign data
-      def update(advertiser_id, campaign_id, params = {})
-        # Ensure required parameters are included
-        params = params.merge(
-          advertiser_id: advertiser_id,
-          campaign_id: campaign_id
-        )
-        
-        response = post('update/', params)
-        response['data']
-      end
-      
-      # Update campaign status (enable/disable)
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param campaign_id [String] Campaign ID
-      # @param status [String] New status ('ENABLE' or 'DISABLE')
-      # @return [Hash] Result
-      def update_status(advertiser_id, campaign_id, status)
-        params = {
-          advertiser_id: advertiser_id,
-          campaign_ids: [campaign_id],
-          operation_status: status
-        }
-        
-        response = post('status/update/', params)
-        response['data']
+    class Campaign < CrudResource
+      RESOURCE_NAME = 'campaign'
+
+      def get(advertiser_id:, campaign_id:)
+        list(advertiser_id: advertiser_id, filtering: {campaign_ids: [campaign_id]}).first
       end
-      
-      # Delete a campaign
-      #
-      # @param advertiser_id [String] Advertiser ID
-      # @param campaign_id [String] Campaign ID
-      # @return [Hash] Result
-      def delete(advertiser_id, campaign_id)
-        params = {
-          advertiser_id: advertiser_id,
-          campaign_ids: [campaign_id]
-        }
-        
-        response = post('delete/', params)
-        response['data']
+
+      def list(advertiser_id:, filtering: {}, page_size: nil, page: nil, **other_params, &block)
+        super(filtering: filtering, page_size: page_size, page: page, **other_params.merge(advertiser_id: advertiser_id), &block)
       end
+
     end
   end
 end

data/lib/tiktok_business_api/resources/crud_resource.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  module Resources
+    # Base CRUD class for all API resources
+    class CrudResource < BaseResource
+      # Default path for create operations
+      def create_path
+        'create/'
+      end
+
+      # Default path for read/list operations
+      def list_path
+        'get/'
+      end
+
+      # Default path for update operations
+      def update_path
+        'update/'
+      end
+
+      # Default path for delete operations
+      def delete_path
+        'delete/'
+      end
+
+      # Default path for status updates
+      def status_update_path
+        'status/update/'
+      end
+
+      def resource_name
+        self::class::RESOURCE_NAME
+      end
+
+      # Default ID parameter name
+      def id_param_name
+        "#{resource_name}_id"
+      end
+
+      # Default IDs parameter name for bulk operations
+      def ids_param_name
+        "#{resource_name}_ids"
+      end
+
+      # Create a new resource
+      #
+      # @param owner_id [String] ID of the resource owner (e.g., advertiser_id)
+      # @param params [Hash] Resource parameters
+      # @param owner_param_name [String] Parameter name for the owner ID
+      # @return [Hash] New resource data
+      def create(owner_id, params = {}, owner_param_name = 'advertiser_id')
+        params = params.merge(owner_param_name => owner_id)
+        response = _http_post(create_path, params)
+        response['data']
+      end
+
+      def list(filtering: {}, page_size: nil, page: nil, **other_params)
+        # Build request paramss
+        request_params = other_params.merge(filtering: filtering.to_json)
+
+        page_size ||= 100
+        page ||= 1
+        request_params[:page_size] = [page_size, 100].min # Most APIs limit page size
+        request_params[:page] = page
+
+        # Make the request
+        response = _http_get(list_path, request_params)
+
+        # If a block is given, yield each item
+        if block_given?
+          items = response.dig('data', 'list') || []
+          items.each { |item| yield(item) }
+
+          # Return the response for method chaining
+          response
+        else
+          # Just return the data otherwise
+          response['data']['list']
+        end
+      end
+
+      # List all resources with automatic pagination
+      #
+      # @param owner_id [String] ID of the resource owner (e.g., advertiser_id)
+      # @param params [Hash] Filter parameters
+      # @param owner_param_name [String] Parameter name for the owner ID
+      # @param list_key [String] Key in the response that contains the data array
+      # @yield [resource] Block to process each resource
+      # @yieldparam resource [Hash] Resource from the response
+      # @return [Array] All resources if no block is given
+      def list_all(owner_id, params = {}, owner_param_name = 'advertiser_id', list_key = 'list')
+        items = []
+        page = 1
+        page_size = params[:page_size] || 10
+        has_more = true
+
+        # Ensure owner_id is included in the params
+        request_params = params.merge(owner_param_name => owner_id)
+
+        while has_more
+          request_params[:page] = page
+          request_params[:page_size] = page_size
+
+          response = _http_get(list_path, request_params)
+
+          # Extract data from the response
+          current_items = response.dig('data', list_key) || []
+
+          if block_given?
+            current_items.each { |item| yield(item) }
+          else
+            items.concat(current_items)
+          end
+
+          # Check if there are more pages
+          page_info = response.dig('data', 'page_info') || {}
+          total_number = page_info['total_number'] || 0
+          total_fetched = page * page_size
+
+          has_more = page_info['has_more'] == true ||
+            (total_number > 0 && total_fetched < total_number)
+          page += 1
+
+          # Break if we've reached the end or there's an empty result
+          break if current_items.empty?
+        end
+
+        block_given? ? nil : items
+      end
+
+      # Get a resource by ID
+      #
+      # @param owner_id [String] ID of the resource owner (e.g., advertiser_id)
+      # @param resource_id [String] Resource ID
+      # @param owner_param_name [String] Parameter name for the owner ID
+      # @return [Hash] Resource data
+      def get(owner_id, resource_id, owner_param_name = 'advertiser_id')
+        params = {
+          owner_param_name => owner_id,
+          ids_param_name => [resource_id]
+        }
+
+        response = _http_get(list_path, params)
+        items = response.dig('data', 'list') || []
+        items.first
+      end
+
+      # Update a resource
+      #
+      # @param owner_id [String] ID of the resource owner (e.g., advertiser_id)
+      # @param resource_id [String] Resource ID
+      # @param params [Hash] Resource parameters to update
+      # @param owner_param_name [String] Parameter name for the owner ID
+      # @return [Hash] Updated resource data
+      def update(owner_id, resource_id, params = {}, owner_param_name = 'advertiser_id')
+        # Ensure required parameters are included
+        params = params.merge(
+          owner_param_name => owner_id,
+          id_param_name => resource_id
+        )
+
+        response = _http_post(update_path, params)
+        response['data']
+      end
+
+      # Update resource status
+      #
+      # @param owner_id [String] ID of the resource owner (e.g., advertiser_id)
+      # @param resource_id [String] Resource ID
+      # @param status [String] New status
+      # @param owner_param_name [String] Parameter name for the owner ID
+      # @return [Hash] Result
+      def update_status(owner_id, resource_id, status, owner_param_name = 'advertiser_id')
+        params = {
+          owner_param_name => owner_id,
+          ids_param_name => [resource_id],
+          'operation_status' => status
+        }
+
+        response = _http_post(status_update_path, params)
+        response['data']
+      end
+
+      # Delete a resource
+      #
+      # @param owner_id [String] ID of the resource owner (e.g., advertiser_id)
+      # @param resource_id [String] Resource ID
+      # @param owner_param_name [String] Parameter name for the owner ID
+      # @return [Hash] Result
+      def delete(owner_id, resource_id, owner_param_name = 'advertiser_id')
+        params = {
+          owner_param_name => owner_id,
+          ids_param_name => [resource_id]
+        }
+
+        response = _http_post(delete_path, params)
+        response['data']
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/resources/identity.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  module Resources
+    # Identity resource for the TikTok Business API
+    class Identity < BaseResource
+      RESOURCE_NAME = 'identity'
+
+      # Get a list of identities
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param options [Hash] Additional options for the request
+      # @option options [String] :identity_type Identity type. Enum values: CUSTOMIZED_USER, AUTH_CODE, TT_USER, BC_AUTH_TT
+      # @option options [String] :identity_authorized_bc_id ID of the Business Center (required when identity_type is BC_AUTH_TT)
+      # @option options [Hash] :filtering Filtering conditions (valid only for CUSTOMIZED_USER or when identity_type not specified)
+      # @option options [Integer] :page Page number
+      # @option options [Integer] :page_size Number of results per page
+      # @return [Hash] Response with list of identities and pagination info
+      def list(advertiser_id:, **options)
+        params = {
+          advertiser_id: advertiser_id
+        }
+
+        # Add optional parameters if provided
+        params[:identity_type] = options[:identity_type] if options[:identity_type]
+        params[:identity_authorized_bc_id] = options[:identity_authorized_bc_id] if options[:identity_authorized_bc_id]
+        params[:filtering] = options[:filtering].to_json if options[:filtering]
+        params[:page] = options[:page] if options[:page]
+        params[:page_size] = options[:page_size] if options[:page_size]
+
+        response = client.request(:get, "#{base_path}get/", params)
+
+        if block_given? && response['data']['identity_list']
+          response['data']['identity_list'].each { |identity| yield(identity) }
+          response['data']
+        else
+          response['data']
+        end
+      end
+
+      # Get information about a specific identity
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param identity_id [String] Identity ID
+      # @param identity_type [String] Identity type. Enum values: CUSTOMIZED_USER, AUTH_CODE, TT_USER, BC_AUTH_TT
+      # @param identity_authorized_bc_id [String] ID of the Business Center (required when identity_type is BC_AUTH_TT)
+      # @return [Hash] Identity information
+      def get_info(advertiser_id:, identity_id:, identity_type:, identity_authorized_bc_id: nil)
+        params = {
+          advertiser_id: advertiser_id,
+          identity_id: identity_id,
+          identity_type: identity_type
+        }
+
+        # Add Business Center ID if provided (required for BC_AUTH_TT)
+        params[:identity_authorized_bc_id] = identity_authorized_bc_id if identity_authorized_bc_id
+
+        response = client.request(:get, "#{base_path}info/", params)
+        response['data']['identity_info']
+      end
+
+      # Create a new Custom User identity
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param display_name [String] Display name (max 100 characters)
+      # @param image_uri [String] The ID of the avatar image (optional)
+      # @return [Hash] Response containing the new identity ID
+      def create(advertiser_id:, display_name:, image_uri: nil)
+        params = {
+          advertiser_id: advertiser_id,
+          display_name: display_name
+        }
+
+        # Add image URI if provided
+        params[:image_uri] = image_uri if image_uri
+
+        response = client.request(:post, "#{base_path}create/", params)
+        response['data']
+      end
+
+      # List all identities with automatic pagination
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param options [Hash] Additional options for the request
+      # @yield [identity] Block to process each identity
+      # @yieldparam identity [Hash] Identity from the response
+      # @return [Array, nil] All identities if no block is given, nil otherwise
+      def list_all(advertiser_id:, **options, &block)
+        page = options[:page] || 1
+        page_size = options[:page_size] || 100
+        all_identities = []
+        has_more = true
+
+        while has_more
+          current_options = options.merge(page: page, page_size: page_size)
+          response = list(advertiser_id: advertiser_id, **current_options)
+
+          identities = response['identity_list'] || []
+
+          if block_given?
+            identities.each { |identity| yield(identity) }
+          else
+            all_identities.concat(identities)
+          end
+
+          # Check pagination info
+          page_info = response['page_info'] || {}
+          current_page = page_info['page'].to_i
+          total_pages = page_info['total_page'].to_i
+
+          has_more = current_page < total_pages
+          page += 1
+
+          # Break if empty result or no more pages
+          break if identities.empty? || !has_more
+        end
+
+        block_given? ? nil : all_identities
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/resources/image.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  module Resources
+    # Image resource for the TikTok Business API
+    class Image < BaseResource
+      # Get the resource name (used for endpoint paths)
+      #
+      # @return [String] Resource name
+      def resource_name
+        'file/image/ad'
+      end
+
+      # Upload an image
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param options [Hash] Upload options
+      # @option options [String] :upload_type Upload type ('UPLOAD_BY_FILE', 'UPLOAD_BY_URL', 'UPLOAD_BY_FILE_ID')
+      # @option options [String] :file_name Image file name
+      # @option options [File] :image_file Image file (required when upload_type is 'UPLOAD_BY_FILE')
+      # @option options [String] :image_signature MD5 of image file (optional when upload_type is 'UPLOAD_BY_FILE', will be calculated if not provided)
+      # @option options [String] :image_url Image URL (required when upload_type is 'UPLOAD_BY_URL')
+      # @option options [String] :file_id File ID (required when upload_type is 'UPLOAD_BY_FILE_ID')
+      # @return [Hash] Upload result with image ID
+      def upload(advertiser_id:, **options)
+        upload_type = options[:upload_type] || 'UPLOAD_BY_FILE'
+
+        params = {
+          advertiser_id: advertiser_id,
+          upload_type: upload_type
+        }
+
+        # Add file_name if provided
+        params[:file_name] = options[:file_name] if options[:file_name]
+
+        case upload_type
+        when 'UPLOAD_BY_FILE'
+          raise ArgumentError, 'image_file is required for UPLOAD_BY_FILE' unless options[:image_file]
+
+          # Auto-calculate image signature if not provided
+          if !options[:image_signature]
+            options[:image_signature] = TiktokBusinessApi::Utils.calculate_md5(options[:image_file])
+          end
+
+          # Create a FilePart for multipart file upload
+          params[:image_file] = Faraday::Multipart::FilePart.new(
+            options[:image_file],
+            TiktokBusinessApi::Utils.detect_content_type(options[:image_file])
+          )
+          params[:image_signature] = options[:image_signature]
+
+          # For file uploads, we need to use multipart/form-data
+          headers = { 'Content-Type' => 'multipart/form-data' }
+          response = client.request(:post, "#{base_path}/upload/", params, headers)
+        when 'UPLOAD_BY_URL'
+          raise ArgumentError, 'image_url is required for UPLOAD_BY_URL' unless options[:image_url]
+
+          params[:image_url] = options[:image_url]
+          response = client.request(:post, "#{base_path}/upload/", params)
+        when 'UPLOAD_BY_FILE_ID'
+          raise ArgumentError, 'file_id is required for UPLOAD_BY_FILE_ID' unless options[:file_id]
+
+          params[:file_id] = options[:file_id]
+          response = client.request(:post, "#{base_path}/upload/", params)
+        else
+          raise ArgumentError, "Invalid upload_type: #{upload_type}"
+        end
+
+        response['data']
+      end
+
+      # Get image info by image ID
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param image_id [String] Image ID
+      # @return [Hash] Image info
+      def get_info(advertiser_id, image_id)
+        params = {
+          advertiser_id: advertiser_id,
+          image_ids: [image_id]
+        }
+
+        response = client.request(:get, "#{base_path}/info/", params)
+        images = response.dig('data', 'list') || []
+        images.first
+      end
+
+      # Search for images
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param options [Hash] Search options
+      # @option options [Integer] :page Current page number (default: 1)
+      # @option options [Integer] :page_size Page size (default: 20)
+      # @option options [String] :image_ids Image IDs, comma-separated
+      # @option options [String] :material_ids Material IDs, comma-separated
+      # @option options [Integer] :width Image width
+      # @option options [Integer] :height Image height
+      # @option options [String] :signature Image MD5 hash
+      # @option options [Integer] :start_time Start time, in seconds
+      # @option options [Integer] :end_time End time, in seconds
+      # @option options [Boolean] :displayable Whether image can be displayed
+      # @yield [image] Block to process each image
+      # @yieldparam image [Hash] Image data from the response
+      # @return [Hash, Array] Image list response or processed images
+      def search(advertiser_id:, **options)
+        # Set up default values
+        page = options[:page] || 1
+        page_size = options[:page_size] || 20
+
+        params = {
+          advertiser_id: advertiser_id,
+          page: page,
+          page_size: page_size
+        }
+
+        # Add optional parameters if provided
+        search_fields = [:image_ids, :material_ids, :width, :height, :signature,
+                         :start_time, :end_time, :displayable]
+
+        search_fields.each do |field|
+          params[field] = options[field] if options.key?(field)
+        end
+
+        response = client.request(:get, "#{base_path}/search/", params)
+        image_list = response.dig('data', 'list') || []
+
+        if block_given?
+          image_list.each { |image| yield(image) }
+          response['data']
+        else
+          image_list
+        end
+      end
+
+      # Check if an image file name is already in use
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param file_names [Array<String>] List of file names to check
+      # @return [Hash] Result with available and unavailable file names
+      def check_name(advertiser_id, file_names)
+        params = {
+          advertiser_id: advertiser_id,
+          file_names: file_names
+        }
+
+        response = client.request(:post, 'file/name/check/', params)
+        response['data']
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/utils.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+require 'digest/md5'
+
+module TiktokBusinessApi
+  # Utility methods for TikTok Business API
+  module Utils
+    # Calculate MD5 hash of the file
+    #
+    # @param file [File, String] File object or file path
+    # @return [String] MD5 hash
+    def self.calculate_md5(file)
+      if file.is_a?(String) && File.exist?(file)
+        # File path was provided
+        Digest::MD5.file(file).hexdigest
+      elsif file.respond_to?(:path) && File.exist?(file.path)
+        # File object with path
+        Digest::MD5.file(file.path).hexdigest
+      elsif file.respond_to?(:read)
+        # IO-like object
+        content = file.read
+        file.rewind if file.respond_to?(:rewind) # Reset the file pointer
+        Digest::MD5.hexdigest(content)
+      else
+        raise ArgumentError, "Unable to calculate MD5: invalid file object"
+      end
+    end
+
+    # Detect content type based on file extension
+    #
+    # @param file [File, String] File object or file path
+    # @return [String] MIME type
+    def self.detect_content_type(file)
+      file_path = if file.is_a?(String)
+                    file
+                  elsif file.respond_to?(:path)
+                    file.path
+                  else
+                    return "application/octet-stream" # Default if we can't determine
+                  end
+
+      # Simple extension to MIME type mapping for common image formats
+      case File.extname(file_path).downcase
+      when '.jpg', '.jpeg'
+        'image/jpeg'
+      when '.png'
+        'image/png'
+      when '.gif'
+        'image/gif'
+      when '.bmp'
+        'image/bmp'
+      when '.webp'
+        'image/webp'
+      else
+        'application/octet-stream'
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TiktokBusinessApi
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/tiktok_business_api.rb

@@ -3,17 +3,24 @@
 require 'faraday'
 require 'faraday/retry'
 require 'faraday/follow_redirects'
+require 'faraday/multipart'
 require 'json'
 
 require_relative 'tiktok_business_api/version'
 require_relative 'tiktok_business_api/config'
 require_relative 'tiktok_business_api/errors'
+require_relative 'tiktok_business_api/utils'
 require_relative 'tiktok_business_api/client'
 require_relative 'tiktok_business_api/auth'
 
 # Resources
 require_relative 'tiktok_business_api/resources/base_resource'
+require_relative 'tiktok_business_api/resources/crud_resource'
 require_relative 'tiktok_business_api/resources/campaign'
+require_relative 'tiktok_business_api/resources/adgroup'
+require_relative 'tiktok_business_api/resources/ad'
+require_relative 'tiktok_business_api/resources/image'
+require_relative 'tiktok_business_api/resources/identity'
 
 module TiktokBusinessApi
   class << self