taboola_api 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c8017c93b8fcd0f4d2be7a9ac58c67b245c3d9f472253beaf67c12688ed57ff0
+  data.tar.gz: fbe4747b6344732927fe384d8df466d8bef193baa5440a03baf1f8c69748e2f4
+SHA512:
+  metadata.gz: 4ea087721692d0f309ea50c98a594038e2858abb07bbfbffec37253c54d0fc9d6438829cf15242df5929aff8c93e90b280541a6986d626a8d2168bc4da8fa7d0
+  data.tar.gz: ef14758c41af0b780413d5f1893022f123997c0297b61a56755c923fda90aeb73ad864567811192ec62fbeef31309e8306450a88780843b1308717a55bed198a

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.1](https://github.com/k0va1/taboola_api/compare/taboola_api-v0.1.0...taboola_api/v0.1.1) (2025-05-17)
+
+
+### Features
+
+* add realtime stats methods ([3cd5236](https://github.com/k0va1/taboola_api/commit/3cd5236dcb4f9e93f84d81380952db4dae65c25b))

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Alex Koval
+
+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,131 @@
+# Taboola API Client
+
+A comprehensive Ruby client for interacting with the Taboola API.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+$ bundle add taboola_api
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+$ gem install taboola_api
+```
+
+## Usage
+
+### Creating a Client
+
+```ruby
+require 'taboola_api'
+
+client = TaboolaApi::Client.new(
+  client_id: "your-client-id",
+  client_secret: "your-client-secret",
+  access_token: "your-access-token"
+)
+```
+
+### Accounts
+
+```ruby
+# List all allowed accounts
+accounts = client.accounts.list_all
+puts accounts
+```
+
+### Campaigns
+
+```ruby
+# List all campaigns
+campaigns = client.campaigns.list_all("account-id")
+puts campaigns
+
+# Get a specific campaign
+campaign = client.campaigns.get("account-id", "campaign-id")
+puts campaign
+```
+
+### Campaign Items
+
+```ruby
+# List all campaign items
+campaign_items = client.campaign_items.list_all("account-id", "campaign-id")
+puts campaign_items
+
+# Get a specific campaign item
+campaign_item = client.campaign_items.get("account-id", "campaign-id", "item-id")
+puts campaign_item
+
+# Create a new campaign item
+new_campaign_item = client.campaign_items.create("account-id", "campaign-id", {
+  name: "New Campaign Item",
+  url: "https://example.com"
+})
+puts new_campaign_item
+
+# Update an existing campaign item
+updated_campaign_item = client.campaign_items.update("account-id", "campaign-id", "item-id", {
+  name: "Updated Campaign Item"
+})
+puts updated_campaign_item
+```
+
+### Motion Ads
+
+```ruby
+# List all motion ads
+motion_ads = client.motion_ads.list_all("account-id", "campaign-id")
+puts motion_ads
+
+# Get a specific motion ad
+motion_ad = client.motion_ads.get("account-id", "campaign-id", "item-id")
+puts motion_ad
+
+# Create a new motion ad
+video_file = File.open("path/to/video.mp4")
+fallback_file = File.open("path/to/fallback.jpg")
+new_motion_ad = client.motion_ads.create("account-id", "campaign-id", video_file: video_file, fallback_file: fallback_file, {
+  name: "New Motion Ad"
+})
+puts new_motion_ad
+
+# Update an existing motion ad
+updated_motion_ad = client.motion_ads.update("account-id", "campaign-id", "item-id", {
+  name: "Updated Motion Ad"
+})
+puts updated_motion_ad
+```
+
+### Operations
+
+```ruby
+# Upload an image
+image_file = File.open("path/to/image.jpg")
+uploaded_image = client.operations.upload_image(image_file)
+puts uploaded_image
+```
+
+### Reportings
+
+```ruby
+# Get top campaign content report
+report = client.reportings.top_campaign_content_report(
+  account_id: "account-id",
+  start_date: "2023-01-01",
+  end_date: "2023-01-31"
+)
+puts report
+```
+
+## Development
+
+After checking out the repo, run `make install` to install dependencies. Then, run `make test` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+## 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,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "taboola_api"
+
+require "irb"
+IRB.start(__FILE__)

data/lib/taboola_api/client.rb

@@ -0,0 +1,123 @@
+require "faraday"
+require "faraday/multipart"
+require "faraday/follow_redirects"
+require "faraday/retry"
+require "taboola_api/error"
+
+module TaboolaApi
+  class Client
+    HOST = "https://backstage.taboola.com/backstage"
+    CURRENT_API_PATH = "api/1.0"
+    DEFAULT_URL = "#{HOST}/#{CURRENT_API_PATH}"
+
+    def initialize(client_id:, client_secret:, access_token:)
+      @client_id = client_id
+      @client_secret = client_secret
+      @access_token = access_token
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: DEFAULT_URL) do |conn|
+        conn.headers["Authorization"] = "Bearer #{@access_token}"
+        conn.headers["Content-Type"] = "application/json"
+
+        conn.options.timeout = 60
+        conn.options.open_timeout = 30
+
+        conn.request :multipart
+        conn.use Faraday::FollowRedirects::Middleware
+        conn.use Faraday::Retry::Middleware, max: 3
+
+        conn.response :json
+
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, path, params = {}, headers = {})
+      url = File.join(DEFAULT_URL, path)
+
+      response = connection.run_request(method, url, nil, headers) do |req|
+        case method
+        when :get, :delete
+          req.params = params
+        when :post, :put
+          if headers["Content-Type"] == "multipart/form-data"
+            req.options.timeout = 120
+            req.body = {}
+            params.each do |key, value|
+              req.body[key.to_sym] = value
+            end
+          else
+            req.body = JSON.generate(params) unless params.empty?
+          end
+        end
+      end
+
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      return response if response.success?
+
+      status = response.status
+      body = response.body
+      error_message = body.is_a?(Hash) ? body&.dig("message") : body
+
+      klass = case status
+      when 401
+        TaboolaApi::AuthenticationError
+      when 403
+        TaboolaApi::AuthorizationError
+      when 429
+        TaboolaApi::RateLimitError
+      when 400..499
+        TaboolaApi::InvalidRequestError
+      when 500..599
+        TaboolaApi::ApiError
+      else
+        TaboolaApi::Error
+      end
+
+      raise klass.new(error_message || "HTTP #{status}", status, body)
+    end
+
+    def update_access_token
+      response = Faraday.post("#{HOST}/oauth/token") do |req|
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(
+          client_id: @client_id,
+          client_secret: @client_secret,
+          grant_type: "client_credentials"
+        )
+      end
+      data = JSON.parse(response.body)
+
+      @access_token = data["access_token"]
+    end
+
+    def accounts
+      @accounts ||= TaboolaApi::Resources::Account.new(self)
+    end
+
+    def campaigns
+      @campaigns ||= TaboolaApi::Resources::Campaign.new(self)
+    end
+
+    def campaign_items
+      @campaign_items ||= TaboolaApi::Resources::CampaignItem.new(self)
+    end
+
+    def motion_ads
+      @motion_ads ||= TaboolaApi::Resources::MotionAds.new(self)
+    end
+
+    def operations
+      @operations ||= TaboolaApi::Resources::Operations.new(self)
+    end
+
+    def reportings
+      @reportings ||= TaboolaApi::Resources::Reportings.new(self)
+    end
+  end
+end

data/lib/taboola_api/error.rb

@@ -0,0 +1,22 @@
+module TaboolaApi
+  class Error < StandardError
+    attr_reader :status_code
+    attr_reader :body
+
+    def initialize(message = nil, status_code = nil, body = nil)
+      @status_code = status_code
+      @body = body
+      super(message)
+    end
+  end
+
+  class AuthenticationError < Error; end
+
+  class AuthorizationError < Error; end
+
+  class InvalidRequestError < Error; end
+
+  class ApiError < Error; end
+
+  class RateLimitError < Error; end
+end

data/lib/taboola_api/resources/account.rb

@@ -0,0 +1,10 @@
+module TaboolaApi
+  module Resources
+    class Account < Base
+      def list_all
+        response = client.request(:get, "users/current/allowed-accounts")
+        response.body
+      end
+    end
+  end
+end

data/lib/taboola_api/resources/base.rb

@@ -0,0 +1,11 @@
+module TaboolaApi
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+    end
+  end
+end

data/lib/taboola_api/resources/campaign.rb

@@ -0,0 +1,15 @@
+module TaboolaApi
+  module Resources
+    class Campaign < Base
+      def list_all(account_id, params: {})
+        response = client.request(:get, "#{account_id}/campaigns", params)
+        response.body
+      end
+
+      def get(account_id, campaign_id)
+        response = client.request(:get, "#{account_id}/campaigns/#{campaign_id}")
+        response.body
+      end
+    end
+  end
+end

data/lib/taboola_api/resources/campaign_item.rb

@@ -0,0 +1,25 @@
+module TaboolaApi
+  module Resources
+    class CampaignItem < Base
+      def get(account_id, campaign_id, item_id)
+        response = client.request(:get, "#{account_id}/campaigns/#{campaign_id}/items/#{item_id}")
+        response.body
+      end
+
+      def list_all(account_id, campaign_id, params: {})
+        response = client.request(:get, "#{account_id}/campaigns/#{campaign_id}/items", params)
+        response.body
+      end
+
+      def create(account_id, campaign_id, params: {})
+        response = client.request(:post, "#{account_id}/campaigns/#{campaign_id}/items", params)
+        response.body
+      end
+
+      def update(account_id, campaign_id, item_id, params: {})
+        response = client.request(:post, "#{account_id}/campaigns/#{campaign_id}/items/#{item_id}", params)
+        response.body
+      end
+    end
+  end
+end

data/lib/taboola_api/resources/motion_ads.rb

@@ -0,0 +1,48 @@
+require "mime/types"
+
+module TaboolaApi
+  module Resources
+    class MotionAds < Base
+      def get(account_id, campaign_id, item_id)
+        response = client.request(:get, "#{account_id}/campaigns/#{campaign_id}/performance-video/items/#{item_id}")
+        response.body
+      end
+
+      def list_all(account_id, campaign_id, params: {})
+        response = client.request(:get, "#{account_id}/campaigns/#{campaign_id}/performance-video/items", params)
+        response.body
+      end
+
+      def create(account_id, campaign_id, video_file:, fallback_file:, params: {})
+        raise ArgumentError, "Video file must be provided" unless video_file.is_a?(File) || video_file.is_a?(Tempfile)
+        raise ArgumentError, "Fallback image file must be provided" unless fallback_file.is_a?(File) || fallback_file.is_a?(Tempfile)
+
+        video_mime_type = MIME::Types.type_for(video_file.path).first.to_s
+        fallback_mime_type = MIME::Types.type_for(fallback_file.path).first.to_s
+
+        payload = {
+          new_item: Faraday::Multipart::ParamPart.new(
+            JSON.generate(params),
+            "application/json"
+          ),
+          video_file: Faraday::Multipart::FilePart.new(
+            video_file,
+            video_mime_type
+          ),
+          fallback_file: Faraday::Multipart::FilePart.new(
+            fallback_file,
+            fallback_mime_type
+          )
+        }
+        headers = {"Content-Type" => "multipart/form-data"}
+        response = client.request(:post, "#{account_id}/campaigns/#{campaign_id}/performance-video/items", payload, headers)
+        response.body
+      end
+
+      def update(account_id, campaign_id, item_id, params: {})
+        response = client.request(:put, "#{account_id}/campaigns/#{campaign_id}/performance-video/items/#{item_id}", params)
+        response.body
+      end
+    end
+  end
+end

data/lib/taboola_api/resources/operations.rb

@@ -0,0 +1,18 @@
+require "mime/types"
+
+module TaboolaApi
+  module Resources
+    class Operations < Base
+      def upload_image(file)
+        raise ArgumentError, "File must be provided" unless file.is_a?(File) || file.is_a?(Tempfile)
+
+        mime_type = MIME::Types.type_for(file.path).first.to_s
+        payload = {
+          file: Faraday::Multipart::FilePart.new(file, mime_type)
+        }
+        response = client.request(:post, "operations/upload-image", payload, "Content-Type" => "multipart/form-data")
+        response.body
+      end
+    end
+  end
+end

data/lib/taboola_api/resources/reportings.rb

@@ -0,0 +1,25 @@
+module TaboolaApi
+  module Resources
+    class Reportings < Base
+      def top_campaign_content_report(account_id:, start_date:, end_date:, campaign: nil)
+        params = {start_date: start_date, end_date: end_date, campaign: campaign}.compact
+        response = client.request(:get, "#{account_id}/reports/top-campaign-content/dimensions/item_breakdown", params)
+        response.body
+      end
+
+      def realtime_campaign_report(account_id:, dimension:, params: {})
+        raise ArgumentError, "start_date and end_date params are required" unless params[:start_date] && params[:end_date]
+
+        response = client.request(:get, "#{account_id}/reports/reports/realtime-campaign-summary/dimensions/#{dimension}", params)
+        response.body
+      end
+
+      def realtime_ads_report(account_id:, dimension:, params: {})
+        raise ArgumentError, "start_date and end_date params are required" unless params[:start_date] && params[:end_date]
+
+        response = client.request(:get, "#{account_id}/reports/reports/realtime-top-campaign-content/dimensions/#{dimension}", params)
+        response.body
+      end
+    end
+  end
+end

data/lib/taboola_api/version.rb

@@ -0,0 +1,3 @@
+module TaboolaApi
+  VERSION = "0.1.1"
+end

data/lib/taboola_api.rb

@@ -0,0 +1,7 @@
+require_relative "taboola_api/version"
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module TaboolaApi
+end

metadata

@@ -0,0 +1,212 @@
+--- !ruby/object:Gem::Specification
+name: taboola_api
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Alex Koval
+bindir: exe
+cert_chain: []
+date: 1980-01-02 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-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: 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: 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: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !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.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.49.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.49.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A comprehensive Ruby client for interacting with the Taboola API
+email:
+- al3xander.koval@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/console
+- lib/taboola_api.rb
+- lib/taboola_api/client.rb
+- lib/taboola_api/error.rb
+- lib/taboola_api/resources/account.rb
+- lib/taboola_api/resources/base.rb
+- lib/taboola_api/resources/campaign.rb
+- lib/taboola_api/resources/campaign_item.rb
+- lib/taboola_api/resources/motion_ads.rb
+- lib/taboola_api/resources/operations.rb
+- lib/taboola_api/resources/reportings.rb
+- lib/taboola_api/version.rb
+homepage: https://github.com/k0va1/taboola_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/k0va1/taboola_api
+  source_code_uri: https://github.com/k0va1/taboola_api
+  changelog_uri: https://github.com/k0va1/taboola_api/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A Ruby client for the Taboola API
+test_files: []