twitter-ads 0.3.4

data/lib/twitter-ads/creative/video.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class Video
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :tweeted, type: :bool, read_only: true
+      property :ready_to_tweet, type: :bool, read_only: true
+      property :duration, read_only: true
+      property :reasons_not_servable, read_only: true
+      property :preview_url, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :updated_at, type: :time, read_only: true
+      property :deleted, type: :bool, read_only: true
+
+      property :title
+      property :description
+      property :video_media_id
+
+      RESOURCE_COLLECTION = '/0/accounts/%{account_id}/videos'.freeze # @api private
+      RESOURCE            = '/0/accounts/%{account_id}/videos/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end
+
+# TODO: legacy namespace support, to be removed in v1.0.0 (next major)
+TwitterAds::Video = TwitterAds::Creative::Video

data/lib/twitter-ads/creative/video_app_download_card.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class VideoAppDownloadCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, read_only: true
+      property :video_url, read_only: true
+      property :video_poster_url, read_only: true
+      property :deleted, type: :bool, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :updated_at, type: :time, read_only: true
+
+      property :name
+      property :app_country_code
+      property :iphone_app_id
+      property :iphone_deep_link
+      property :ipad_app_id
+      property :ipad_deep_link
+      property :googleplay_app_id
+      property :googleplay_deep_link
+      property :app_cta
+      property :image_media_id
+      property :video_id
+
+      RESOURCE_COLLECTION =
+        '/0/accounts/%{account_id}/cards/video_app_download'.freeze # @api private
+      RESOURCE = '/0/accounts/%{account_id}/cards/video_app_download/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/creative/video_conversation_card.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class VideoConversationCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, read_only: true
+      property :video_url, read_only: true
+      property :video_poster_url, read_only: true
+      property :deleted, type: :bool, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :updated_at, type: :time, read_only: true
+
+      property :name
+      property :title
+      property :first_cta
+      property :first_cta_tweet
+      property :second_cta
+      property :second_cta_tweet
+      property :thank_you_text
+      property :thank_you_url
+      property :image_media_id
+      property :video_id
+
+      RESOURCE_COLLECTION =
+        '/0/accounts/%{account_id}/cards/video_conversation'.freeze # @api private
+      RESOURCE = '/0/accounts/%{account_id}/cards/video_conversation/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/creative/website_card.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Creative
+
+    class WebsiteCard
+
+      include TwitterAds::DSL
+      include TwitterAds::Resource
+      include TwitterAds::Persistence
+
+      attr_reader :account
+
+      property :id, read_only: true
+      property :preview_url, read_only: true
+      property :deleted, type: :bool, read_only: true
+      property :created_at, type: :time, read_only: true
+      property :updated_at, type: :time, read_only: true
+
+      property :name
+      property :website_title
+      property :website_url
+      # @return [String] An enum value for the call-to-action prompt.
+      # @deprecated Please see https://t.co/deprecated-website-card-cta for more info.
+      property :website_cta
+      property :image_media_id
+
+      RESOURCE_COLLECTION = '/0/accounts/%{account_id}/cards/website'.freeze # @api private
+      RESOURCE            = '/0/accounts/%{account_id}/cards/website/%{id}'.freeze # @api private
+
+      def initialize(account)
+        @account = account
+        self
+      end
+
+      # Overload for CTA deprecation warning.
+      # @private
+      def website_cta=(value)
+        TwitterAds::Utils.deprecated(
+          "#{self.class}#website_cta", refer: 'https://t.co/deprecated-website-card-cta')
+        @website_cta = value
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/cursor.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Cursor
+
+    include ::Enumerable
+    extend ::Forwardable
+
+    def_delegators :@collection, :first, :[]
+
+    # Creates a new Cursor instance.
+    #
+    # @param klass [String] The object class the contained by the Cursor instance.
+    # @param request [Request] The Request object instance.
+    # @param opts [Hash] A Hash of extended options.
+    #
+    # @return [Cursor] The new Cursor instance.
+    #
+    # @since 0.1.0
+    def initialize(klass, request, opts = {})
+      @klass      = klass
+      @client     = request.client
+      @method     = request.method
+      @resource   = request.resource
+      @options    = opts.merge!(request.options)
+      @collection = []
+      from_response(request.perform)
+      self
+    end
+
+    # Exhausts the Cursor then returns the last object in the collection.
+    #
+    # @return [Object] The last object in the collection.
+    #
+    # @since 0.2.0
+    def last
+      each {}
+      @collection.last
+    end
+
+    # Method to fetch the next page only.
+    #
+    # @return [Array] A collection containing the next page of objects.
+    #
+    # @since 0.1.0
+    def next
+      return @collection unless @next_cursor
+      current_size = @collection.size - 1
+      fetch_next
+      @collection[current_size..-1]
+    end
+
+    # Method to iterate through all items until the Cursor is exhausted.
+    #
+    # @return [Cursor] The current Cursor instance.
+    #
+    # @since 0.1.0
+    def each(offset = 0)
+      return to_enum(:each, offset) unless block_given?
+      @collection[offset..-1].each { |element| yield(element) }
+      unless exhausted?
+        offset = [@collection.size, offset].max
+        fetch_next
+        each(offset, &Proc.new)
+      end
+      self
+    end
+
+    # Determines whether or not the current Cusor instance has been exhausted.
+    #
+    # @return [Boolean] A boolean value indicating Cursor status.
+    #
+    # @since 0.1.0
+    def exhausted?
+      !@next_cursor
+    end
+
+    # Returns the full size of the cursor (even if not exhausted).
+    #
+    # @return [Integer] The Cursor count / size.
+    #
+    # @since 0.1.0
+    def count
+      @total_count || @collection.size
+    end
+    alias size count
+
+    # Returns an inspection string for the current Cursor instance.
+    #
+    # @example
+    #   cursor.inspect
+    #
+    # @since 0.1.0
+    #
+    # @return [String] The inspection string.
+    def inspect
+      "#<#{self.class.name}:0x#{object_id} " \
+      "count=#{size} fetched=#{@collection.size} " \
+      "exhausted=#{exhausted?}>"
+    end
+
+    private
+
+    def fetch_next
+      return unless @next_cursor
+      opts = @options.dup
+      opts[:params] = opts.fetch(:params, {}).merge!(cursor: @next_cursor)
+      from_response(Request.new(@client, @method, @resource, opts).perform)
+    end
+
+    def from_response(response)
+      @next_cursor = response.body[:next_cursor]
+      @total_count = response.body[:total_count].to_i if response.body.key?(:total_count)
+      response.body.fetch(:data, []).each do |object|
+        @collection << if @klass && @klass.method_defined?(:from_response)
+                         @klass.new(
+                           *@options[:init_with]).from_response(object)
+                       else
+                         object
+                       end
+      end
+    end
+
+  end
+
+end

data/lib/twitter-ads/enum.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+# Copyright (Cend 2015 Twitter, Inc.
+
+module TwitterAds
+  module Enum
+
+    module Objective
+      APP_ENGAGEMENTS   = 'APP_ENGAGEMENTS'.freeze
+      APP_INSTALLS      = 'APP_INSTALLS'.freeze
+      FOLLOWERS         = 'FOLLOWERS'.freeze
+      LEAD_GENERATION   = 'LEAD_GENERATION'.freeze
+      TWEET_ENGAGEMENTS = 'TWEET_ENGAGEMENTS'.freeze
+      VIDEO_VIEWS       = 'VIDEO_VIEWS'.freeze
+      WEBSITE_CLICKS    = 'WEBSITE_CLICKS'.freeze
+
+      # @deprecated
+      CUSTOM = 'CUSTOM'.freeze
+    end
+
+    module Product
+      PROMOTED_ACCOUNT = 'PROMOTED_ACCOUNT'.freeze
+      PROMOTED_TWEETS  = 'PROMOTED_TWEETS'.freeze
+    end
+
+    module Placement
+      ALL_ON_TWITTER    = 'ALL_ON_TWITTER'.freeze
+      TWITTER_SEARCH    = 'TWITTER_SEARCH'.freeze
+      TWITTER_TIMELINE  = 'TWITTER_TIMELINE'.freeze
+      PUBLISHER_NETWORK = 'PUBLISHER_NETWORK'.freeze
+    end
+
+    module Placement
+      class << self
+
+        # Helper method to return a list a valid placement combinations by Product.
+        #
+        # @example
+        #   Placement.valid_combinations(Product::PROMOTED_TWEETS)
+        #
+        # @param product_type [Product] The enum value for the Product type being targeted.
+        #
+        # @return [Array] An array of valid placement combinations.
+        #
+        # @deprecated use LineItems#placements(). Will be deprecated in v1.0.0.
+        #
+        # @since 0.1.0
+        # @see https://dev.twitter.com/ads/reference/get/line_items/placements
+        def valid_combinations(client, product_type)
+          TwitterAds::Utils.deprecated(
+            'Placement#valid_combinations', replacement: 'LineItem#placements')
+          TwitterAds::LineItem.placements(client, product_type)
+        end
+
+      end
+    end
+
+    module BidUnit
+      APP_CLICK   = 'APP_CLICK'.freeze
+      APP_INSTALL = 'APP_INSTALL'.freeze
+      ENGAGEMENT  = 'ENGAGEMENT'.freeze
+      FOLLOW      = 'FOLLOW'.freeze
+      LEAD        = 'LEAD'.freeze
+      LINK_CLICK  = 'LINK_CLICK'.freeze
+      VIEW        = 'VIEW'.freeze
+    end
+
+    module ChargeBy
+      APP_CLICK   = 'APP_CLICK'.freeze
+      APP_INSTALL = 'APP_INSTALL'.freeze
+      ENGAGEMENT  = 'ENGAGEMENT'.freeze
+      FOLLOW      = 'FOLLOW'.freeze
+      LEAD        = 'LEAD'.freeze
+      LINK_CLICK  = 'LINK_CLICK'.freeze
+      VIEW        = 'VIEW'.freeze
+    end
+
+    module Optimizations
+      DEFAULT             = 'DEFAULT'.freeze
+      WEBSITE_CONVERSIONS = 'WEBSITE_CONVERSIONS'.freeze
+    end
+
+    module Granularity
+      HOUR  = 'HOUR'.freeze
+      DAY   = 'DAY'.freeze
+      TOTAL = 'TOTAL'.freeze
+    end
+
+    module AgeBucket
+      AGE_13_TO_17 = 'AGE_13_TO_17'.freeze
+      AGE_18_TO_24 = 'AGE_18_TO_24'.freeze
+      AGE_25_TO_34 = 'AGE_25_TO_34'.freeze
+      AGE_35_TO_44 = 'AGE_35_TO_44'.freeze
+      AGE_45_TO_54 = 'AGE_45_TO_54'.freeze
+      AGE_55_TO_64 = 'AGE_55_TO_64'.freeze
+      AGE_OVER_65  = 'AGE_OVER_65'.freeze
+    end
+
+    module AgeBucketCoarse
+      AGE_18_TO_34 = 'AGE_18_TO_34'.freeze
+      AGE_18_TO_49 = 'AGE_18_TO_49'.freeze
+      AGE_25_TO_54 = 'AGE_25_TO_54'.freeze
+      AGE_OVER_21  = 'AGE_OVER_21'.freeze
+    end
+
+    module Events
+      MUSIC_AND_ENTERTAINMENT = 'MUSIC_AND_ENTERTAINMENT'.freeze
+      SPORTS                  = 'SPORTS'.freeze
+      HOLIDAY                 = 'HOLIDAY'.freeze
+      CONFERENCE              = 'CONFERENCE'.freeze
+      OTHER                   = 'OTHER'.freeze
+    end
+
+    module Sentiment
+      ALL = 'ALL'.freeze
+      POSITIVE_ONLY = 'POSITIVE_ONLY'.freeze
+    end
+
+    module TAListTypes
+      EMAIL        = 'EMAIL'.freeze
+      DEVICE_ID    = 'DEVICE_ID'.freeze
+      TWITTER_ID   = 'TWITTER_ID'.freeze
+      HANDLE       = 'HANDLE'.freeze
+      PHONE_NUMBER = 'PHONE_NUMBER'.freeze
+    end
+
+    module TAOperations
+      ADD = 'ADD'.freeze
+      REMOVE  = 'REMOVE'.freeze
+      REPLACE = 'REPLACE'.freeze
+    end
+
+  end
+end