tiktok_business_api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad55f88f2cd5e40133b2b5e9e50f531ab05d42c1481dbcb2bc10cce04e32b36c
-  data.tar.gz: 1d9c0d9cd1d66d5f9b18ed7cafb300554f838d60fa8b3f1e674e6add14b51d16
+  metadata.gz: b6df153f640ad431a27d8f06557b1424f2846d8adda17fa1189dfe6bded264e0
+  data.tar.gz: '01822882ce8e801f197433adb20e35c74eae2fa156f66521492e71d3f7dd75d9'
 SHA512:
-  metadata.gz: f62aad982847e47734da79d75d187819d67f518dbdc82232d2d85671bde0df713e022c930c544cb6a4976b21093f397d2aed810208deed395e1a16e846f70bac
-  data.tar.gz: 136d73e3995bd71017e27579a5923b93c5e92141ae5828ee479d97a4eeaed835742919251c41d5f512a14e3b0311142a34f184c103d84eee2bdf113d47783e2c
+  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 = 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,57 +6,57 @@ 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
       # @param params [Hash] Query parameters
       # @param headers [Hash] Custom headers
       # @return [Hash] Response data
-      def get(path, params = {}, headers = {})
+      def _http_get(path, params = {}, headers = {})
         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
       # @param params [Hash] Body parameters
       # @param headers [Hash] Custom headers
       # @return [Hash] Response data
-      def post(path, params = {}, headers = {})
+      def _http_post(path, params = {}, headers = {})
         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