twitter-ads 0.3.4

data/lib/twitter-ads/resources/dsl.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  # A light-wight DSL for building out Twitter Ads API resources.
+  module DSL
+
+    def self.included(klass)
+      klass.send :include, InstanceMethods
+      klass.extend ClassMethods
+    end
+
+    module InstanceMethods
+
+      # Populates a given objects attributes from a parsed JSON API response. This helper
+      # handles all necessary type coercions as it assigns attribute values.
+      #
+      # @param object [Hash] The parsed JSON response object.
+      #
+      # @return [self] A fully hydrated instance of the current class.
+      #
+      # @since 0.1.0
+      def from_response(object)
+        self.class.properties.each do |name, type|
+          value = nil
+          if type == :time && object[name] && !object[name].empty?
+            value = Time.parse(object[name])
+          elsif type == :bool && object[name]
+            value = TwitterAds::Utils.to_bool(object[name])
+          end
+          instance_variable_set("@#{name}", value || object[name])
+        end
+        self
+      end
+
+      # Generates a Hash of property values for the current object. This helper
+      # handles all necessary type coercions as it generates its output.
+      #
+      # @return [Hash] A Hash of the object's properties and cooresponding values.
+      #
+      # @since 0.1.0
+      def to_params
+        params = {}
+        self.class.properties.each do |name, type|
+          value = instance_variable_get("@#{name}") || send(name)
+          next if value.nil?
+
+          # handles unset with empty string
+          if value.respond_to?(:strip) && value.strip == ''
+            params[name] = value.strip
+            next
+          end
+
+          if type == :time
+            params[name] = value.iso8601
+          elsif type == :bool
+            params[name] = TwitterAds::Utils.to_bool(value)
+          elsif value.is_a?(Array)
+            next if value.size < 1
+            params[name] = value.join(',')
+          else
+            params[name] = value
+          end
+        end
+        params
+      end
+
+    end
+
+    module ClassMethods
+
+      # Resource property declaration helper.
+      #
+      # @example
+      #   class Foo
+      #     include TwitterAds::DSL
+      #
+      #     property :foo
+      #     property :bar, type: :bool
+      #     property :created_at, type: time, read_only: true
+      #   end
+      #
+      # @param name [Symbol] The name of the property.
+      # @param opts [Hash] A Hash of extended options to be applied to the property (Optional).
+      #
+      # @return [Symbol] The property name.
+      #
+      # @since 0.1.0
+      def property(name, opts = {})
+        properties[name] = opts.fetch(:type, nil)
+        opts[:read_only] ? attr_reader(name) : attr_accessor(name)
+        name
+      end
+
+      # Helper for managing properties for the current class.
+      #
+      # @return [Hash] A Hash of properties declared in the current class.
+      #
+      # @api private
+      # @since 0.1.0
+      def properties
+        @properties ||= {}
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/resources/persistence.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Persistence
+
+    # Saves or updates the current object instance depending on the presence of `object.id`.
+    #
+    # @example
+    #   object.save
+    #
+    # @return [self] Returns the instance refreshed from the API.
+    #
+    # @since 0.1.0
+    def save
+      if @id
+        resource = self.class::RESOURCE % { account_id: account.id, id: id }
+        response = Request.new(account.client, :put, resource, params: to_params).perform
+      else
+        resource = self.class::RESOURCE_COLLECTION % { account_id: account.id }
+        response = Request.new(account.client, :post, resource, params: to_params).perform
+      end
+      from_response(response.body[:data])
+    end
+
+    # Deletes the current object instance depending on the presence of `object.id`.
+    #
+    # @example
+    #   object.delete!
+    #
+    # Note: calls to this method are destructive and irreverisble for most API objects.
+    #
+    # @return [self] Returns the instance refreshed from the API.
+    #
+    # @since 0.1.0
+    def delete!
+      resource = self.class::RESOURCE % { account_id: account.id, id: id }
+      response = Request.new(account.client, :delete, resource).perform
+      from_response(response.body[:data])
+    end
+
+  end
+end

data/lib/twitter-ads/resources/resource.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Resource
+
+    def self.included(klass)
+      klass.send :include, InstanceMethods
+      klass.extend ClassMethods
+    end
+
+    module InstanceMethods
+
+      # Reloads all attributes for the current object instance from the API.
+      #
+      # @example
+      #   object.reload!
+      #
+      # Note: calls to this method dispose of any unsaved data on the object instance.
+      #
+      # @param opts [Hash] An optional Hash of extended request options.
+      #
+      # @return [self] The reloaded instance of the current object.
+      #
+      # @since 0.1.0
+      def reload!(opts = {})
+        return self unless id
+        params   = { with_deleted: true }.merge!(opts)
+        resource = self.class::RESOURCE % { account_id: account.id, id: id }
+        response = Request.new(account.client, :get, resource, params: params).perform
+        from_response(response.body[:data])
+      end
+
+      # Returns an inspection string for the current object instance.
+      #
+      # @example
+      #   object.inspect
+      #
+      # @return [String] The object instance details.
+      #
+      # @since 0.1.0
+      def inspect
+        str = String.new("#<#{self.class.name}:0x#{object_id}")
+        str << " id=\"#{@id}\"" if @id
+        str << ' deleted="true"' if @deleted
+        str << '>'
+      end
+
+    end
+
+    module ClassMethods
+
+      # Returns a Cursor instance for a given resource.
+      #
+      # @param account [Account] The Account object instance.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+      # @option opts [String] :sort_by The object param to sort the API response by.
+      #
+      # @return [Cursor] A Cusor object ready to iterate through the API response.
+      #
+      # @since 0.1.0
+      # @see Cursor
+      # @see https://dev.twitter.com/ads/basics/sorting Sorting
+      def all(account, opts = {})
+        resource = self::RESOURCE_COLLECTION % { account_id: account.id }
+        request = Request.new(account.client, :get, resource, params: opts)
+        Cursor.new(self, request, init_with: [account])
+      end
+
+      # Returns an object instance for a given resource.
+      #
+      # @param account [Account] The Account object instance.
+      # @param id [String] The ID of the specific object to be loaded.
+      # @param opts [Hash] An optional Hash of extended options.
+      # @option opts [Boolean] :with_deleted Indicates if deleted items should be included.
+      # @option opts [String] :sort_by The object param to sort the API response by.
+      #
+      # @return [self] The object instance for the specified resource.
+      #
+      # @since 0.1.0
+      def load(account, id, opts = {})
+        params   = { with_deleted: true }.merge!(opts)
+        resource = self::RESOURCE % { account_id: account.id, id: id }
+        response = Request.new(account.client, :get, resource, params: params).perform
+        new(account).from_response(response.body[:data])
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/targeting/reach_estimate.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module ReachEstimate
+
+    class << self
+
+      # Get a reach estimate for the specified line item details.
+      #
+      # @example
+      #   TwitterAds::ReachEstimate.fetch(
+      #     account,
+      #     'PROMOTED_TWEETS',
+      #     'WEBSITE_CLICKS',
+      #     2153688540,
+      #     similar_to_followers_of_user: 2153688540,
+      #     gender: 2
+      #   )
+      #
+      # @param client [Client] The Client object instance.
+      # @param account [Account] The Ads Account instance for this request.
+      # @param product_type [String] The product type being targeted.
+      # @param objective [String] The objective being targeted.
+      # @param user_id [Long] The ID of the user whose content will be promoted.
+      # @param opts [Hash] A Hash of extended options.
+      #
+      # @option opts [String] :bid_type The bidding mechanism.
+      # @option opts [Long] :bid_amount_local_micro Bid amount in local currency micros.
+      # @option opts [String] :currency ISO-4217 Currency code for bid amount.
+      # @option opts [String] :followers_of_users Comma-separated user IDs.
+      # @option opts [String] :similar_to_followers_of_users Comma-separated user IDs.
+      # @option opts [String] :locations Comma-separated location IDs.
+      # @option opts [String] :interests Comma-seaprated interest IDs.
+      # @option opts [String] :gender Gender identifier.
+      # @option opts [String] :platforms Comma-separated platform IDs.
+      # @option opts [String] :tailored_audiences Comma-separated tailored audience IDs.
+      # @option opts [String] :tailored_audiences_expanded Comma-separated tailoerd audience IDs.
+      # @option opts [String] :languages Comma-separated language IDs.
+      # @option opts [String] :platform_versions Comma-separated platform version IDs.
+      # @option opts [String] :devices Comma-separated device IDs.
+      # @option opts [String] :behaviors Comma-separated behavior IDs.
+      # @option opts [String] :behaviors_expanded Comma-separated behaviors IDs.
+      # @option opts [String] :campaign engagement Campaign ID for Tweet Engager Retargeting.
+      # @option opts [String] :user_engagement Promoted User ID for Tweet Engager Retargeting.
+      # @option opts [String] :engagement_type engagement type for Tweet Engager Retargeting.
+      #
+      # @return [Hash] A hash containing count and infinite_bid_count.
+      #
+      # @since 0.2.0
+      # @see https://dev.twitter.com/ads/reference/get/accounts/%3Aaccount_id/reach_estimate
+      def fetch(account, product_type, objective, user_id, opts = {})
+        resource = "/0/accounts/#{account.id}/reach_estimate"
+        params = { product_type: product_type, objective: objective, user_id: user_id }.merge!(opts)
+
+        # The response value count is "bid sensitive", we default to bid_type=AUTO here to preserve
+        # expected behavior despite an API change that occurred in December 2015.
+        unless params.keys.include?(:bid_type) || params.keys.include?(:bid_amount_local_micro)
+          params = { bid_type: 'AUTO' }.merge!(params)
+        end
+
+        response = TwitterAds::Request.new(account.client, :get, resource, params: params).perform
+        response.body[:data]
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/utils.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  module Utils
+
+    class << self
+
+      # Helper to convert objects into boolean values.
+      #
+      # @param object [Object] The object to be converted.
+      #
+      # @return [Boolean] The boolean result.
+      #
+      # @api private
+      # @since 0.1.0
+      def to_bool(object)
+        (object.to_s.downcase == 'false') ? false : !!object
+      end
+
+      # Helper to convert a time object according to a given granularity level.
+      #
+      # @param time [Time] A valid Time instance.
+      # @param granularity [Symbol] A symbol representing the desired granuarlity (eg. :hour).
+      #
+      # @return [Time] The formatted Time instance.
+      #
+      # @api private
+      # @since 0.1.0
+      def to_time(time, granularity = nil)
+        return time.iso8601 unless granularity
+        if granularity == :hour
+          Time.new(time.year, time.month, time.day, time.hour).iso8601
+        elsif granularity == :day
+          Time.new(time.year, time.month, time.day).iso8601
+        else
+          time.iso8601
+        end
+      end
+
+      # Converts key names to symbols on a given object.
+      #
+      # @param object [Object] The object to be converted.
+      #
+      # @return [Object] The symbolized, converted object.
+      #
+      # @api private
+      # @since 0.1.0
+      def symbolize!(object)
+        if object.is_a?(Array)
+          object.each_with_index { |value, index| object[index] = symbolize!(value) }
+        elsif object.is_a?(Hash)
+          object.keys.each { |key| object[key.to_sym] = symbolize!(object.delete(key)) }
+        end
+        object
+      end
+
+      # Creates a deprecation message.
+      #
+      # @param name [String] The name of the object or method being deprecated.
+      # @param replacement [String] The name of the new object or method (optional).
+      # @param refer [String] HTTP address with supporting information (optional).
+      #
+      # @api private
+      # @since 0.3.2
+      def deprecated(name, opts = {})
+        message = String.new("[DEPRECATED] #{name} has been deprecated")
+        message += opts[:replacement] ? " (please use #{opts[:replacement]})." : '.'
+        message += " Please see #{opts[:refer]} for more info." if opts[:refer]
+        warn message
+      end
+
+    end
+
+  end
+end

data/lib/twitter-ads/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  VERSION = '0.3.4'.freeze
+end

data/spec/fixtures/accounts_all.json

@@ -0,0 +1,65 @@
+{
+  "request": {
+    "params": {}
+  },
+  "data": [
+    {
+      "name": "Schuppe-Casper",
+      "timezone": "America/Los_Angeles",
+      "timezone_switch_at": "2014-11-17T08:00:00Z",
+      "id": "2iqph",
+      "created_at": "2015-03-04T10:50:42Z",
+      "salt": "5ab2pizq7qxjjqrx3z67f4wbko61o7xs",
+      "updated_at": "2015-04-11T05:20:08Z",
+      "approval_status": "ACCEPTED",
+      "deleted": false
+    },
+    {
+      "name": "Schuppe-Casper",
+      "timezone": "America/Los_Angeles",
+      "timezone_switch_at": "2014-11-17T08:00:00Z",
+      "id": "pz6ec",
+      "created_at": "2015-05-29T00:52:16Z",
+      "salt": "39ku32xvhdt0jax8thps2c70e2fv3yok",
+      "updated_at": "2015-05-29T00:52:16Z",
+      "approval_status": "ACCEPTED",
+      "deleted": false
+    },
+    {
+      "name": "Kozey-Farrell",
+      "timezone": "America/Los_Angeles",
+      "timezone_switch_at": "2014-11-17T08:00:00Z",
+      "id": "j9ozo",
+      "created_at": "2015-05-01T12:08:10Z",
+      "salt": "winwfne3y6oyikl4tm84bj9r50waxj37",
+      "updated_at": "2015-05-01T12:08:10Z",
+      "approval_status": "ACCEPTED",
+      "deleted": false
+    },
+    {
+      "name": "Osinski, Quitzon and Hilll",
+      "timezone": "America/Los_Angeles",
+      "timezone_switch_at": "2014-11-17T08:00:00Z",
+      "id": "9ttgd",
+      "created_at": "2015-06-24T18:51:20Z",
+      "salt": "tj9hmt5xylm5zztrq05w7hwh4mkpkg5r",
+      "updated_at": "2015-06-26T06:13:24Z",
+      "approval_status": "ACCEPTED",
+      "deleted": false
+    },
+    {
+      "name": "Jakubowski-Aufderhar",
+      "timezone": "America/Los_Angeles",
+      "timezone_switch_at": "2013-05-22T07:00:00Z",
+      "id": "47d0v",
+      "created_at": "2015-05-28T05:42:03Z",
+      "salt": "1ms1mq1nww7zl7169865gwqt89s9127m",
+      "updated_at": "2015-05-28T05:42:03Z",
+      "approval_status": "ACCEPTED",
+      "deleted": false
+    }
+  ],
+  "data_type": "account",
+  "total_count": 5,
+  "next_cursor": null
+}