tiktok_business_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad55f88f2cd5e40133b2b5e9e50f531ab05d42c1481dbcb2bc10cce04e32b36c
+  data.tar.gz: 1d9c0d9cd1d66d5f9b18ed7cafb300554f838d60fa8b3f1e674e6add14b51d16
+SHA512:
+  metadata.gz: f62aad982847e47734da79d75d187819d67f518dbdc82232d2d85671bde0df713e022c930c544cb6a4976b21093f397d2aed810208deed395e1a16e846f70bac
+  data.tar.gz: 136d73e3995bd71017e27579a5923b93c5e92141ae5828ee479d97a4eeaed835742919251c41d5f512a14e3b0311142a34f184c103d84eee2bdf113d47783e2c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+# TikTok Business API Ruby Gem
+
+A Ruby interface to the TikTok Business API with support for campaigns, ad groups, ads, and more.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tiktok_business_api'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install tiktok_business_api
+```
+
+## Getting Started
+
+### Configuration
+
+You need to configure the client with your TikTok app credentials:
+
+```ruby
+TiktokBusinessApi.configure do |config|
+  config.app_id = 'your_app_id'
+  config.secret = 'your_app_secret'
+  config.debug = true # Enable request/response logging
+end
+```
+
+If you want to use a custom logger:
+
+```ruby
+require 'logger'
+logger = Logger.new(STDOUT)
+logger.level = Logger::DEBUG
+
+TiktokBusinessApi.configure do |config|
+  config.logger = logger
+end
+```
+
+### Authentication
+
+#### Generate an authorization URL
+
+```ruby
+client = TiktokBusinessApi.client
+auth_url = client.auth.authorization_url('https://your-redirect-url.com/callback')
+```
+
+After the user authorizes your app, TikTok will redirect to your callback URL with an authorization code.
+
+#### Generate an access token
+
+```ruby
+auth_code = 'auth_code_from_callback'
+redirect_uri = 'https://your-redirect-url.com/callback'
+
+response = client.auth.generate_access_token(auth_code, redirect_uri)
+access_token = response['data']['access_token']
+```
+
+The access token will automatically be stored in your client configuration for future requests.
+
+### Working with Campaigns
+
+```ruby
+# Create a new client instance
+client = TiktokBusinessApi.client(access_token: 'your_access_token')
+
+# Create a campaign
+advertiser_id = '6000000000000'
+campaign_params = {
+  campaign_name: 'My First Campaign',
+  objective_type: 'TRAFFIC',
+  budget_mode: 'BUDGET_MODE_TOTAL',
+  budget: 1000
+}
+
+campaign = client.campaigns.create(advertiser_id, campaign_params)
+campaign_id = campaign['campaign_id']
+
+# Get a list of campaigns
+campaigns = client.campaigns.list(advertiser_id)
+
+# Get a specific campaign
+campaign = client.campaigns.get(advertiser_id, campaign_id)
+
+# Update a campaign
+update_params = {
+  campaign_name: 'Updated Campaign Name'
+}
+client.campaigns.update(advertiser_id, campaign_id, update_params)
+
+# Enable/disable a campaign
+client.campaigns.update_status(advertiser_id, campaign_id, 'DISABLE')
+
+# Delete a campaign
+client.campaigns.delete(advertiser_id, campaign_id)
+
+# List all campaigns with pagination (yields each campaign to a block)
+client.campaigns.list_all(advertiser_id) do |campaign|
+  puts "Campaign: #{campaign['campaign_name']}"
+end
+```
+
+## Logging Requests and Responses
+
+You can enable debug logging to see all API requests and responses:
+
+```ruby
+TiktokBusinessApi.configure do |config|
+  config.debug = true
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+## Error Handling
+
+The gem raises specific exceptions for different error types:
+
+```ruby
+begin
+  client.campaigns.create(advertiser_id, campaign_params)
+rescue TiktokBusinessApi::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue TiktokBusinessApi::RateLimitError => e
+  puts "Rate limit exceeded: #{e.message}"
+rescue TiktokBusinessApi::ApiError => e
+  puts "API error: #{e.message}, Status code: #{e.status_code}, Body: #{e.body}"
+rescue TiktokBusinessApi::Error => e
+  puts "General error: #{e.message}"
+end
+```
+
+## Development
+
+### With Docker (recommended)
+
+This gem includes a Docker-based development environment to ensure consistent development and testing.
+
+#### Prerequisites
+
+- Docker and Docker Compose
+- Make (optional, but recommended)
+
+#### Setup using Make
+
+```bash
+# Set up the development environment
+make setup
+
+# Run tests
+make test
+
+# Open a shell in the Docker container
+make shell
+
+# Start a console with the gem loaded
+make console
+
+# Run RuboCop linting
+make lint
+
+# Generate documentation
+make docs
+
+# Build the gem
+make build
+
+# Prepare a new release
+make release
+
+# Publish to RubyGems
+make publish
+
+# View all available commands
+make help
+```
+
+#### Without Make
+
+If you prefer to use Docker Compose directly:
+
+```bash
+# Set up the development environment
+docker-compose build
+
+# Run tests
+docker-compose run --rm test
+
+# Start a console with the gem loaded
+docker-compose run --rm console
+
+# Open a shell in the Docker container
+docker-compose run --rm gem bash
+```
+
+### Without Docker
+
+If you prefer to develop without Docker:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake spec
+
+# Run linting
+bundle exec rubocop
+
+# Generate documentation
+bundle exec yard
+
+# Build the gem
+bundle exec rake build
+
+# Start a console with the gem loaded
+bin/console
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "tiktok_business_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/publish_gem

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -e
+
+# This script publishes the gem to RubyGems without requiring Git operations
+
+# Build the gem if needed
+if [ ! -f "pkg/tiktok_business_api-$(ruby -r ./lib/tiktok_business_api/version -e 'print TiktokBusinessApi::VERSION').gem" ]; then
+  echo "Building gem..."
+  bundle exec rake build
+fi
+
+# Get the current version
+CURRENT_VERSION=$(ruby -r ./lib/tiktok_business_api/version -e 'print TiktokBusinessApi::VERSION')
+echo "Publishing tiktok_business_api version $CURRENT_VERSION to RubyGems..."
+
+# Prompt for RubyGems credentials if needed
+if [ -z "$RUBYGEMS_API_KEY" ]; then
+  if [ ! -f ~/.gem/credentials ]; then
+    echo "RubyGems credentials not found. You need to log in to RubyGems."
+    gem push --help
+    read -p "Press Enter after you've set up your credentials..." _
+  fi
+fi
+
+# Push to RubyGems
+echo "Pushing gem to RubyGems..."
+gem push "pkg/tiktok_business_api-$CURRENT_VERSION.gem"
+
+echo "Gem successfully published!"

data/lib/tiktok_ads_api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'faraday/follow_redirects'
+require 'json'
+
+require_relative 'tiktok_ads_api/version'
+require_relative 'tiktok_ads_api/config'
+require_relative 'tiktok_ads_api/errors'
+require_relative 'tiktok_ads_api/client'
+require_relative 'tiktok_ads_api/auth'
+
+# Resources
+require_relative 'tiktok_ads_api/resources/base_resource'
+require_relative 'tiktok_ads_api/resources/campaign'
+
+module TiktokAdsApi
+  class << self
+    attr_accessor :config
+
+    # Configure the TikTok Ads API client
+    #
+    # @yield [config] Configuration object that can be modified
+    # @return [TiktokAdsApi::Config] The configuration object
+    def configure
+      self.config ||= Config.new
+      yield(config) if block_given?
+      config
+    end
+
+    # Create a new client instance
+    #
+    # @param options [Hash] Optional configuration overrides
+    # @return [TiktokAdsApi::Client] A new client instance
+    def client(options = {})
+      TiktokAdsApi::Client.new(options)
+    end
+  end
+end

data/lib/tiktok_business_api/auth.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  # Handles authentication with the TikTok Business API
+  class Auth
+    # @return [TiktokBusinessApi::Client] Client instance
+    attr_reader :client
+    
+    # Initialize the Auth handler
+    #
+    # @param client [TiktokBusinessApi::Client] Client instance
+    def initialize(client)
+      @client = client
+    end
+    
+    # Generate an access token using an authorization code
+    #
+    # @param auth_code [String] Authorization code from TikTok
+    # @param redirect_uri [String] Redirect URI used in the authorization request
+    # @return [Hash] Access token response
+    def generate_access_token(auth_code, redirect_uri)
+      params = {
+        app_id: client.config.app_id,
+        secret: client.config.secret,
+        auth_code: auth_code,
+        grant_type: 'auth_code'
+      }
+      
+      # Add redirect_uri if provided
+      params[:redirect_uri] = redirect_uri if redirect_uri
+      
+      response = client.request(:post, 'v1.3/oauth2/access_token/', params)
+      
+      # Store the access token in the client config
+      client.config.access_token = response['data']['access_token'] if response['data'] && response['data']['access_token']
+      
+      response
+    end
+    
+    # Refresh an access token (for TikTok account access tokens)
+    #
+    # @param refresh_token [String] Refresh token
+    # @return [Hash] New access token response
+    def refresh_access_token(refresh_token)
+      params = {
+        app_id: client.config.app_id,
+        secret: client.config.secret,
+        refresh_token: refresh_token,
+        grant_type: 'refresh_token'
+      }
+      
+      response = client.request(:post, 'v1.3/tt_user/oauth2/refresh_token/', params)
+      
+      # Update the access token in the client config
+      client.config.access_token = response['data']['access_token'] if response['data'] && response['data']['access_token']
+      
+      response
+    end
+    
+    # Revoke an access token
+    #
+    # @param token [String] Access token to revoke (defaults to the current access token)
+    # @return [Hash] Response
+    def revoke_access_token(token = nil)
+      token ||= client.config.access_token
+      
+      params = {
+        app_id: client.config.app_id,
+        secret: client.config.secret,
+        access_token: token
+      }
+      
+      response = client.request(:post, 'v1.3/oauth2/revoke_token/', params)
+      
+      # Clear the access token if it was revoked
+      client.config.access_token = nil if response['code'] == 0
+      
+      response
+    end
+    
+    # Get a list of authorized advertiser accounts
+    #
+    # @param app_id [String] App ID (defaults to the configured app_id)
+    # @param secret [String] App secret (defaults to the configured secret)
+    # @param access_token [String] Access token (defaults to the configured access_token)
+    # @return [Hash] List of authorized advertisers
+    def get_authorized_advertisers(app_id = nil, secret = nil, access_token = nil)
+      params = {}
+      
+      # Use provided values or fallback to client config
+      headers = {}
+      headers['Access-Token'] = access_token || client.config.access_token if access_token || client.config.access_token
+      
+      client.request(:get, 'v1.3/oauth2/advertiser/get/', params, headers)
+    end
+    
+    # Generate authorization URL for TikTok Business API
+    #
+    # @param redirect_uri [String] Redirect URI where the authorization code will be sent
+    # @param state [String] Optional state parameter for security
+    # @param scope [Array<String>] Optional array of permission scopes
+    # @return [String] Authorization URL
+    def authorization_url(redirect_uri, state = nil, scope = nil)
+      params = {
+        app_id: client.config.app_id,
+        redirect_uri: redirect_uri
+      }
+      
+      params[:state] = state if state
+      params[:scope] = scope.join(',') if scope && !scope.empty?
+      
+      query = params.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
+      "https://ads.tiktok.com/marketing_api/auth?#{query}"
+    end
+  end
+end

data/lib/tiktok_business_api/client.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  # Main client for interacting with the TikTok Business API
+  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
+      
+      # 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
+    end
+    
+    # Make an HTTP request to the TikTok Business API
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param path [String] API endpoint path
+    # @param params [Hash] URL parameters for GET, or body parameters for POST/PUT
+    # @param headers [Hash] Additional HTTP headers
+    # @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?
+        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
+    
+    private
+    
+    # Set up Faraday connection
+    #
+    # @return [Faraday::Connection] Faraday connection
+    def connection
+      @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
+        
+        conn.adapter Faraday.default_adapter
+      end
+    end
+    
+    # Parse and handle the API response
+    #
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Parsed response body
+    # @raise [TiktokBusinessApi::Error] If the response indicates an error
+    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
+      
+      # 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
+    # @param url [String] Request URL
+    # @param params [Hash] Request parameters
+    # @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
+  end
+end

data/lib/tiktok_business_api/config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  # Configuration class for TikTok Business API
+  class Config
+    # @return [String] TikTok API app ID
+    attr_accessor :app_id
+    
+    # @return [String] TikTok API app secret
+    attr_accessor :secret
+    
+    # @return [String] TikTok API access token
+    attr_accessor :access_token
+    
+    # @return [String] Base URL for the TikTok API
+    attr_accessor :api_base_url
+    
+    # @return [Boolean] Whether to enable debug logging
+    attr_accessor :debug
+    
+    # @return [Object] Custom logger instance
+    attr_accessor :logger
+    
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+    
+    # @return [Integer] Open timeout in seconds
+    attr_accessor :open_timeout
+    
+    # Initialize configuration with default values
+    def initialize
+      @api_base_url = 'https://business-api.tiktok.com/open_api/'
+      @debug = false
+      @timeout = 60
+      @open_timeout = 30
+    end
+  end
+end

data/lib/tiktok_business_api/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  # Base error class for the TikTok Business API
+  class Error < StandardError
+    # @return [Integer] HTTP status code
+    attr_reader :status_code
+    
+    # @return [Hash] Full response body
+    attr_reader :body
+    
+    # @return [Hash] Request that caused the error
+    attr_reader :request
+    
+    # Initialize a new error
+    #
+    # @param message [String] Error message
+    # @param status_code [Integer] HTTP status code
+    # @param body [Hash] Response body
+    # @param request [Hash] Request that caused the error
+    def initialize(message = nil, status_code = nil, body = nil, request = nil)
+      @status_code = status_code
+      @body = body
+      @request = request
+      super(message)
+    end
+  end
+  
+  # Error raised when authentication fails
+  class AuthenticationError < Error; end
+  
+  # Error raised when authorization fails
+  class AuthorizationError < Error; end
+  
+  # Error raised for invalid requests
+  class InvalidRequestError < Error; end
+  
+  # Error raised for API errors
+  class ApiError < Error; end
+  
+  # Error raised for rate limit errors
+  class RateLimitError < Error; end
+
+  # Factory for creating the appropriate error object
+  class ErrorFactory
+    # Create an error object based on the response
+    #
+    # @param response [Faraday::Response] The HTTP response
+    # @param request [Hash] The request that caused the error
+    # @return [TiktokBusinessApi::Error] The appropriate error object
+    def self.from_response(response, request = nil)
+      status = response.status
+      body = response.body
+      
+      # 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
+        AuthenticationError
+      when 403
+        AuthorizationError
+      when 429
+        RateLimitError
+      when 400..499
+        InvalidRequestError
+      when 500..599
+        ApiError
+      else
+        Error
+      end
+      
+      # Create and return the error
+      klass.new(
+        error_message || "HTTP #{status}",
+        status,
+        body,
+        request
+      )
+    end
+  end
+end

data/lib/tiktok_business_api/resources/base_resource.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module TiktokBusinessApi
+  module Resources
+    # Base class for all API resources
+    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 = {})
+        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 = {})
+        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
+      # @param params [Hash] Query parameters
+      # @param headers [Hash] Custom headers
+      # @param data_key [String] Key in the response that contains the data array
+      # @yield [item] Block to process each item
+      # @yieldparam item [Hash] Item from the response
+      # @return [Array] All items if no block is given
+      def paginate(path, params = {}, headers = {}, data_key = 'data')
+        items = []
+        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
+  end
+end

data/lib/tiktok_business_api/resources/campaign.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+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']
+      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']
+      end
+    end
+  end
+end

data/lib/tiktok_business_api/version.rb

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

data/lib/tiktok_business_api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'faraday/follow_redirects'
+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/client'
+require_relative 'tiktok_business_api/auth'
+
+# Resources
+require_relative 'tiktok_business_api/resources/base_resource'
+require_relative 'tiktok_business_api/resources/campaign'
+
+module TiktokBusinessApi
+  class << self
+    attr_accessor :config
+
+    # Configure the TikTok Business API client
+    #
+    # @yield [config] Configuration object that can be modified
+    # @return [TiktokBusinessApi::Config] The configuration object
+    def configure
+      self.config ||= Config.new
+      yield(config) if block_given?
+      config
+    end
+
+    # Create a new client instance
+    #
+    # @param options [Hash] Optional configuration overrides
+    # @return [TiktokBusinessApi::Client] A new client instance
+    def client(options = {})
+      TiktokBusinessApi::Client.new(options)
+    end
+  end
+end

metadata

@@ -0,0 +1,183 @@
+--- !ruby/object:Gem::Specification
+name: tiktok_business_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Your Name
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.14'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby interface to the TikTok Business API with support for campaigns,
+  ad groups, ads, and more
+email:
+- your.email@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/console
+- bin/publish_gem
+- lib/tiktok_ads_api.rb
+- lib/tiktok_business_api.rb
+- lib/tiktok_business_api/auth.rb
+- lib/tiktok_business_api/client.rb
+- lib/tiktok_business_api/config.rb
+- lib/tiktok_business_api/errors.rb
+- lib/tiktok_business_api/resources/base_resource.rb
+- lib/tiktok_business_api/resources/campaign.rb
+- lib/tiktok_business_api/version.rb
+homepage: https://github.com/yourusername/tiktok_business_api
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby client for the TikTok Business API
+test_files: []