tiktok_business_api 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b75b59a548d691df5ead2efd45a9f7ea8bf1bd046f14cfd0286b3f564279041
-  data.tar.gz: 51cf8b92af0775d12cbc0f94aee289437b7ae3723b889933efe4b36a23dc9f00
+  metadata.gz: b6df153f640ad431a27d8f06557b1424f2846d8adda17fa1189dfe6bded264e0
+  data.tar.gz: '01822882ce8e801f197433adb20e35c74eae2fa156f66521492e71d3f7dd75d9'
 SHA512:
-  metadata.gz: 5a956599241be58b694721840c447856d6ba58f0e16352309bd402eeafac0d6c5e70ffefc1c642122b3e6b0a716bc8a25ad2d3b92d952b72115c49868b90088c
-  data.tar.gz: 2efcfa2e2caf123b88a5c3d863812443a09ec59cb51da37618b4fe08f804b25d3448bf51bf41f4c53c7682f7b3c4fef6234a40a45a5b4ce66ff921dd5edcdfcc
+  metadata.gz: 2b1a377795b3a0cf988b83f1e0f2325166cad9ffbb19ee9d01b3e047e4afab9d9ef0a1824f4ba0faf0b971b5e58fb10b40e2c7a40c02633c383d2e1687f97a8a
+  data.tar.gz: 64840256b05f91aad973ad96b5a6ad980bd01d82e9086e0784df96abd9f5a08a59dc7cf3615a821ad8f2a63d0e29b555d45fcab7c71d42e81e9dacfdcaeff256

data/README.md

@@ -113,6 +113,56 @@ client.campaigns.list_all(advertiser_id) do |campaign|
 end
 ```
 
+### Working with Identities
+
+The Identity feature allows you to create Spark Ads by working with authorized TikTok accounts.
+
+```ruby
+# List available identities
+identities = client.identities.list(advertiser_id: 'your_advertiser_id')
+
+# Get information about a specific identity
+identity_info = client.identities.get_info(
+  advertiser_id: 'your_advertiser_id',
+  identity_id: 'identity_id',
+  identity_type: 'TT_USER'
+)
+
+# Create a custom user identity
+new_identity = client.identities.create(
+  advertiser_id: 'your_advertiser_id',
+  display_name: 'My Custom Identity',
+  image_uri: 'image_id_from_uploaded_image' # Optional
+)
+
+# List all identities with pagination
+client.identities.list_all(advertiser_id: 'your_advertiser_id') do |identity|
+  puts "Identity: #{identity['display_name']} (#{identity['identity_type']})"
+end
+```
+
+### Working with Images
+
+Upload and manage images for your ads:
+
+```ruby
+# Upload an image file
+uploaded_image = client.images.upload(
+  advertiser_id: 'your_advertiser_id',
+  image_file: File.open('/path/to/image.jpg')
+)
+
+# Get image info
+image_info = client.images.get_info('your_advertiser_id', uploaded_image['image_id'])
+
+# Search for images
+images = client.images.search(
+  advertiser_id: 'your_advertiser_id',
+  page: 1,
+  page_size: 20
+)
+```
+
 ## Logging Requests and Responses
 
 You can enable debug logging to see all API requests and responses:

data/lib/tiktok_business_api/client.rb

@@ -5,42 +5,42 @@ module TiktokBusinessApi
   class Client
     # @return [TiktokBusinessApi::Config] Client configuration
     attr_reader :config
-    
+
     # @return [TiktokBusinessApi::Auth] Authentication handler
     attr_reader :auth
-    
+
     # Initialize a new client
     #
     # @param options [Hash] Override configuration options
     def initialize(options = {})
       @config = TiktokBusinessApi.config.dup || Config.new
-      
+
       # Override config with options
       options.each do |key, value|
         @config.send("#{key}=", value) if @config.respond_to?("#{key}=")
       end
-      
+
       @auth = Auth.new(self)
       @resources = {}
     end
-    
+
     # Get or create a resource instance
     #
     # @param resource_name [Symbol] Name of the resource
     # @return [BaseResource] Resource instance
     def resource(resource_name)
       @resources[resource_name] ||= begin
-        # Convert resource_name to class name (e.g., :campaign => Campaign)
-        class_name = resource_name.to_s.split('_').map(&:capitalize).join
-        
-        # Get the resource class
-        resource_class = TiktokBusinessApi::Resources.const_get(class_name)
-        
-        # Create an instance
-        resource_class.new(self)
-      end
+                                      # Convert resource_name to class name (e.g., :campaign => Campaign)
+                                      class_name = resource_name.to_s.split('_').map(&:capitalize).join
+
+                                      # Get the resource class
+                                      resource_class = TiktokBusinessApi::Resources.const_get(class_name)
+
+                                      # Create an instance
+                                      resource_class.new(self)
+                                    end
     end
-    
+
     # Make an HTTP request to the TikTok Business API
     #
     # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
@@ -50,46 +50,83 @@ module TiktokBusinessApi
     # @return [Hash] Parsed API response
     def request(method, path, params = {}, headers = {})
       url = File.join(@config.api_base_url, path)
-      
+
       # Set up default headers
       default_headers = {
         'Content-Type' => 'application/json'
       }
-      
+
       # Add access token if available
       if @config.access_token
         default_headers['Access-Token'] = @config.access_token
       end
-      
+
       # Merge with custom headers
       headers = default_headers.merge(headers)
-      
+
       # Log the request
       log_request(method, url, params, headers)
-      
+
       # Build the request
       response = connection.run_request(method, url, nil, headers) do |req|
         case method
         when :get, :delete
           req.params = params
         when :post, :put
-          req.body = JSON.generate(params) unless params.empty?
+          if headers['Content-Type'] == 'multipart/form-data'
+            # For multipart form data, let Faraday handle it
+            req.options.timeout = 120 # Extend timeout for file uploads
+            req.body = {}  # Initialize the body as an empty hash
+            params.each do |key, value|
+              req.body[key.to_sym] = value
+            end
+          else
+            req.body = JSON.generate(params) unless params.empty?
+          end
         end
       end
-      
+
       # Parse and handle the response
       handle_response(response)
     end
-    
+
     # Access to campaign resource
     #
     # @return [TiktokBusinessApi::Resources::Campaign] Campaign resource
     def campaigns
       resource(:campaign)
     end
-    
+
+    # Access to ad group resource
+    #
+    # @return [TiktokBusinessApi::Resources::Adgroup] Ad group resource
+    def adgroups
+      resource(:adgroup)
+    end
+
+    # Access to ad resource
+    #
+    # @return [TiktokBusinessApi::Resources::Ad] Ad resource
+    def ads
+      resource(:ad)
+    end
+
+    # Access to image resource
+    #
+    # @return [TiktokBusinessApi::Resources::Image] Image resource
+    def images
+      resource(:image)
+    end
+
+    # Access to identity resource
+    #
+    # @return [TiktokBusinessApi::Resources::Identity] Identity resource
+    def identities
+      resource(:identity)
+    end
+
     private
-    
+
     # Set up Faraday connection
     #
     # @return [Faraday::Connection] Faraday connection
@@ -97,16 +134,19 @@ module TiktokBusinessApi
       @connection ||= Faraday.new do |conn|
         conn.options.timeout = @config.timeout
         conn.options.open_timeout = @config.open_timeout
-        
+
         # Set up middleware
         conn.use Faraday::Response::Logger, @config.logger if @config.logger
         conn.use Faraday::FollowRedirects::Middleware
         conn.use Faraday::Retry::Middleware, max: 3
-        
+
+        # Use multipart middleware for file uploads
+        conn.request :multipart
+
         conn.adapter Faraday.default_adapter
       end
     end
-    
+
     # Parse and handle the API response
     #
     # @param response [Faraday::Response] HTTP response
@@ -115,26 +155,26 @@ module TiktokBusinessApi
     def handle_response(response)
       # Log the response
       log_response(response)
-      
+
       # Parse the response body
       body = if response.body && !response.body.empty?
-        begin
-          JSON.parse(response.body)
-        rescue JSON::ParserError
-          { error: "Invalid JSON response: #{response.body}" }
-        end
-      else
-        {}
-      end
-      
+               begin
+                 JSON.parse(response.body)
+               rescue JSON::ParserError
+                 { error: "Invalid JSON response: #{response.body}" }
+               end
+             else
+               {}
+             end
+
       # Check for API errors
       if !response.success? || (body.is_a?(Hash) && body['code'] != 0)
         raise ErrorFactory.from_response(response)
       end
-      
+
       body
     end
-    
+
     # Log the request details
     #
     # @param method [Symbol] HTTP method
@@ -143,18 +183,18 @@ module TiktokBusinessApi
     # @param headers [Hash] Request headers
     def log_request(method, url, params, headers)
       return unless @config.debug && @config.logger
-      
+
       @config.logger.debug "[TiktokBusinessApi] Request: #{method.upcase} #{url}"
       @config.logger.debug "[TiktokBusinessApi] Parameters: #{params.inspect}"
       @config.logger.debug "[TiktokBusinessApi] Headers: #{headers.inspect}"
     end
-    
+
     # Log the response details
     #
     # @param response [Faraday::Response] HTTP response
     def log_response(response)
       return unless @config.debug && @config.logger
-      
+
       @config.logger.debug "[TiktokBusinessApi] Response Status: #{response.status}"
       @config.logger.debug "[TiktokBusinessApi] Response Body: #{response.body}"
     end

data/lib/tiktok_business_api/errors.rb

@@ -50,12 +50,20 @@ module TiktokBusinessApi
     # @return [TiktokBusinessApi::Error] The appropriate error object
     def self.from_response(response, request = nil)
       status = response.status
-      body = response.body
+      body = if response.body && !response.body.empty?
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          { error: "Invalid JSON response: #{response.body}" }
+        end
+      else
+        {}
+      end
       
       # Parse TikTok API response which has its own error structure
       error_code = body.is_a?(Hash) ? body['code'] : nil
       error_message = body.is_a?(Hash) ? body['message'] : nil
-      
+
       # Determine the error class based on status and error code
       klass = case status
       when 401

data/lib/tiktok_business_api/resources/ad.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  module Resources
+    # Ad resource for the TikTok Business API
+    class Ad < CrudResource
+      RESOURCE_NAME = 'ad'
+
+      def get(advertiser_id:, ad_id:)
+        list(advertiser_id: advertiser_id, filtering: {ad_ids: [ad_id]}).first
+      end
+
+      # Create a new ad
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param adgroup_id [String] Ad group ID
+      # @param creatives [Array<Hash>] Array of creative objects
+      # @return [Hash] New ad data with created ad IDs
+      def create(advertiser_id:, adgroup_id:, creatives:)
+        params = {
+          advertiser_id: advertiser_id,
+          adgroup_id: adgroup_id,
+          creatives: creatives
+        }
+
+        response = _http_post(create_path, params)
+        response['data']
+      end
+
+      def list(advertiser_id:, campaign_id: nil, adgroup_id: nil, filtering: {}, page_size: nil, page: nil, **other_params, &block)
+        filtering[:campaign_ids] = [campaign_id] if campaign_id
+        filtering[:adgroup_ids] = [adgroup_id] if adgroup_id
+        super(filtering: filtering, page_size: page_size, page: page, **other_params.merge(advertiser_id: advertiser_id), &block)
+      end
+
+      # Update an ad
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param ad_id [String] Ad ID
+      # @param params [Hash] Ad parameters to update
+      # @return [Hash] Updated ad data
+      def update(advertiser_id:, ad_id:, **params)
+        params = params.merge(
+          advertiser_id: advertiser_id,
+          ad_id: ad_id
+        )
+
+        response = _http_post(update_path, params)
+        response['data']
+      end
+
+      # Update ad status (enable/disable)
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param ad_id [String] Ad ID
+      # @param status [String] New status ('ENABLE' or 'DISABLE')
+      # @return [Hash] Result
+      def update_status(advertiser_id:, ad_id:, status:)
+        params = {
+          advertiser_id: advertiser_id,
+          ad_ids: [ad_id],
+          operation_status: status
+        }
+
+        response = _http_post('status/update/', params)
+        response['data']
+      end
+
+      # Delete an ad
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param ad_id [String] Ad ID
+      # @return [Hash] Result
+      def delete(advertiser_id:, ad_id:)
+        params = {
+          advertiser_id: advertiser_id,
+          ad_ids: [ad_id]
+        }
+
+        response = _http_post(delete_path, params)
+        response['data']
+      end
+
+      # Create Smart Creative ads
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param adgroup_id [String] Ad group ID
+      # @param creatives [Array<Hash>] Array of creative objects
+      # @return [Hash] New Smart Creative ad data
+      def create_aco(advertiser_id:, adgroup_id:, creatives:)
+        params = {
+          advertiser_id: advertiser_id,
+          adgroup_id: adgroup_id,
+          creatives: creatives
+        }
+
+        response = _http_post('aco/create/', params)
+        response['data']
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/resources/adgroup.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  module Resources
+    # AdGroup resource for the TikTok Business API
+    class Adgroup < CrudResource
+      RESOURCE_NAME = 'adgroup'
+
+      def get(advertiser_id:, adgroup_id:)
+        list(advertiser_id: advertiser_id, filtering: {adgroup_ids: [adgroup_id]}).first
+      end
+
+      # Create a new ad group
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param params [Hash] Ad group parameters
+      # @return [Hash] New ad group data
+      def create(advertiser_id, params = {})
+        # Ensure advertiser_id is included in the params
+        params = params.merge(advertiser_id: advertiser_id)
+
+        response = _http_post(create_path, params)
+        response['data']
+      end
+
+      def list(advertiser_id:, campaign_id: nil, filtering: {}, page_size: nil, page: nil, **other_params, &block)
+        filtering[:campaign_ids] = [campaign_id] if campaign_id
+        super(filtering: filtering, page_size: page_size, page: page, **other_params.merge(advertiser_id: advertiser_id), &block)
+      end
+
+      # Update an ad group
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param adgroup_id [String] Ad group ID
+      # @param params [Hash] Ad group parameters to update
+      # @return [Hash] Updated ad group data
+      def update(advertiser_id, adgroup_id, params = {})
+        params = params.merge(
+          advertiser_id: advertiser_id,
+          adgroup_id: adgroup_id
+        )
+
+        response = _http_post(update_path, params)
+        response['data']
+      end
+
+      # Update ad group status (enable/disable)
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param adgroup_id [String] Ad group ID
+      # @param status [String] New status ('ENABLE' or 'DISABLE')
+      # @return [Hash] Result
+      def update_status(advertiser_id, adgroup_id, status)
+        params = {
+          advertiser_id: advertiser_id,
+          adgroup_ids: [adgroup_id],
+          operation_status: status
+        }
+
+        response = _http_post('status/update/', params)
+        response['data']
+      end
+
+      # Delete an ad group
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param adgroup_id [String] Ad group ID
+      # @return [Hash] Result
+      def delete(advertiser_id, adgroup_id)
+        params = {
+          advertiser_id: advertiser_id,
+          adgroup_ids: [adgroup_id]
+        }
+
+        response = _http_post(delete_path, params)
+        response['data']
+      end
+
+      # Estimate audience size for an ad group
+      #
+      # @param advertiser_id [String] Advertiser ID
+      # @param params [Hash] Targeting parameters for estimation
+      # @return [Hash] Audience size estimation
+      def estimate_audience_size(advertiser_id, params = {})
+        params = params.merge(advertiser_id: advertiser_id)
+
+        response = _http_post('audience_size/estimate/', params)
+        response['data']
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/resources/base_resource.rb

@@ -6,35 +6,35 @@ module TiktokBusinessApi
     class BaseResource
       # @return [TiktokBusinessApi::Client] Client instance
       attr_reader :client
-      
+
       # Initialize a new resource
       #
       # @param client [TiktokBusinessApi::Client] Client instance
       def initialize(client)
         @client = client
       end
-      
+
       # Get the resource name (used for endpoint paths)
       #
       # @return [String] Resource name
       def resource_name
         self.class.name.split('::').last.downcase
       end
-      
+
       # Get the API version
       #
       # @return [String] API version
       def api_version
         'v1.3'
       end
-      
+
       # Get the base path for this resource
       #
       # @return [String] Base path
       def base_path
         "#{api_version}/#{resource_name}/"
       end
-      
+
       # Make a GET request to the resource
       #
       # @param path [String] Path relative to the resource base path
@@ -45,7 +45,7 @@ module TiktokBusinessApi
         full_path = File.join(base_path, path)
         client.request(:get, full_path, params, headers)
       end
-      
+
       # Make a POST request to the resource
       #
       # @param path [String] Path relative to the resource base path
@@ -56,7 +56,7 @@ module TiktokBusinessApi
         full_path = File.join(base_path, path)
         client.request(:post, full_path, params, headers)
       end
-      
+
       # Handle pagination for list endpoints
       #
       # @param path [String] Path relative to the resource base path
@@ -71,28 +71,28 @@ module TiktokBusinessApi
         page = 1
         page_size = params[:page_size] || 10
         has_more = true
-        
+
         while has_more
           params[:page] = page
           params[:page_size] = page_size
-          
+
           response = get(path, params, headers)
-          
+
           # Extract data from the response
           current_items = response.dig('data', data_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') || {}
           has_more = page_info['has_more'] == true
           page += 1
         end
-        
+
         block_given? ? nil : items
       end
     end

data/lib/tiktok_business_api/resources/campaign.rb

@@ -3,97 +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)
+    class Campaign < CrudResource
+      RESOURCE_NAME = 'campaign'
 
-        response = post('create/', params)
-        response['data']
+      def get(advertiser_id:, campaign_id:)
+        list(advertiser_id: advertiser_id, filtering: {campaign_ids: [campaign_id]}).first
       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 = _http_get('get/', params)
-        response['data']
-      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 = _http_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 = _http_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']
+      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
 
-      # 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 = _http_post('delete/', params)
-        response['data']
-      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.1"
+  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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tiktok_business_api
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Vlad Zloteanu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-15 00:00:00.000000000 Z
+date: 2025-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +150,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
 description: A Ruby interface to the TikTok Business API (Tiktok Ads API) with support
   for campaigns, ad groups, ads, and more
 email:
@@ -151,8 +179,14 @@ files:
 - lib/tiktok_business_api/client.rb
 - lib/tiktok_business_api/config.rb
 - lib/tiktok_business_api/errors.rb
+- lib/tiktok_business_api/resources/ad.rb
+- lib/tiktok_business_api/resources/adgroup.rb
 - lib/tiktok_business_api/resources/base_resource.rb
 - lib/tiktok_business_api/resources/campaign.rb
+- lib/tiktok_business_api/resources/crud_resource.rb
+- lib/tiktok_business_api/resources/identity.rb
+- lib/tiktok_business_api/resources/image.rb
+- lib/tiktok_business_api/utils.rb
 - lib/tiktok_business_api/version.rb
 homepage: https://github.com/vladzloteanu/tiktok_business_api
 licenses: