twitter-ads 0.3.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c2a9baebef194bb1afe3d158260acac82197b4a9
+  data.tar.gz: 683bc57423beae4e79a1f41ecd58b0063b98a66b
+SHA512:
+  metadata.gz: 642dc745353d0f378aefa9a3dadde2820ddb6cec1d79c72f54e26d0958607fa6f4acf2235328d8e3e20b6a4af11a73288e4e0202f03887599c457e600986bfac
+  data.tar.gz: 51ccabfa2fdd681462f649ea6bd478e472760efa0290658b3e48b1f0851a240b2b035dc5763fa34e4949741c8a8dea125f78c9c48a5eca702333d254dd054f7c

data.tar.gz.sig

@@ -0,0 +1,2 @@
+=��z�y��a:~���h���J���I��ש�'��ы��O�
+�慊�!����8U𣦙I#+�+k�〠���z�����N�����~Vkl}��8�(�+�i8�

data/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing Guidelines
+
+We love pull requests from everyone!
+
+We encourage community contributions for all kinds of changes
+both big and small, but we ask that you adhere to the following guidelines for contributing code.
+
+##### Proposing Changes
+
+As a starting point for all changes, we recommend [reporting an issue][report-issue]
+before you begin making any changes. Make sure to search the issues on this repository
+first to check and see the issue has already been previously discussed and whether or
+not it's already being worked on.
+
+- For small changes, improvements and bug fixes please feel free to send us a pull
+request with proposed changes along-side the issue you report.
+
+- For larger more involved or design related changes, please open an issue and discuss
+the changes with the other contributors before submitting any pull requests.
+
+[report-issue]: https://github.com/twitterdev/twitter-ruby-ads-sdk/issues?q=is%3Aopen+is%3Aissue
+
+##### Submitting A Pull Request
+
+1) Fork us and clone the repository locally.
+
+```bash
+git clone git@github.com:twitterdev/twitter-ruby-ads-sdk.git
+```
+
+2) Install development dependencies:
+
+```bash
+# install bundler (if you don't have it already)
+gem install bundler
+
+# install all development dependencies
+bundle install
+```
+
+3) Make sure all tests pass before you start:
+
+```bash
+rake
+```
+
+4) Make your changes! (Don't forget tests and documentation)
+
+5) Test your changes again and make sure everything passes:
+
+```bash
+rake
+```
+
+The test suite will automatically enforce test coverage and code style.
+For the most part, we follow [this][style] community style guide with a
+[few exceptions](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/master/.rubocop.yml).
+
+[style]: https://github.com/bbatsov/ruby-style-guide
+
+6) Submit your changes!
+
+- [Squash](http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit) your development commits. Put features in a single clean commit whenever possible or logically split it into a few commits (no development commits). Test coverage can be included in a separate commit if preferred. 
+- Write a [good commit message][commit] for your change.
+- Push to your fork.
+- Submit a [pull request][pr].
+
+[commit]: http://chris.beams.io/posts/git-commit/
+[pr]: https://github.com/thoughtbot/suspenders/compare/
+
+We try to at least comment on pull requests within one business day and may suggest changes.
+
+##### Release Schedule and Versioning
+
+We have a regular release cadence and adhere to [semantic versioning](http://semver.org/). When
+exactly your change ships will depend on the scope of your changes and what type of upcoming release
+its best suited for.

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (C) 2015 Twitter, Inc.
+
+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,111 @@
+Getting Started [![Build Status](https://travis-ci.org/twitterdev/twitter-ruby-ads-sdk.svg?branch=master)](https://travis-ci.org/twitterdev/twitter-ruby-ads-sdk) [![Code Climate](https://codeclimate.com/github/twitterdev/twitter-ruby-ads-sdk/badges/gpa.svg)](https://codeclimate.com/github/twitterdev/twitter-ruby-ads-sdk) [![Test Coverage](https://codeclimate.com/github/twitterdev/twitter-ruby-ads-sdk/badges/coverage.svg)](https://codeclimate.com/github/twitterdev/twitter-ruby-ads-sdk/coverage) [![Gem Version](https://badge.fury.io/rb/twitter-ads.svg)](http://badge.fury.io/rb/twitter-ads)
+------
+
+##### Installation
+```bash
+# installing the latest signed release
+gem install twitter-ads
+```
+
+##### Quick Start
+```ruby
+require 'twitter-ads'
+
+# initialize the client
+client = TwitterAds::Client.new(
+  CONSUMER_KEY,
+  CONSUMER_SECRET,
+  ACCESS_TOKEN,
+  ACCESS_TOKEN_SECRET
+)
+
+# load the advertiser account instance
+account = client.accounts('c3won9gy')
+
+# load and update a specific campaign
+campaign = account.campaigns('4m0gjms')
+campaign.paused = true
+campaign.save
+
+# iterate through campaigns
+account.campaigns.each do |camp|
+  # do stuff
+end
+```
+
+##### Command Line Helper
+```bash
+# The twitter-ads command launches an interactive session for testing purposes
+# with a client instance automatically loaded from your .twurlrc file.
+
+~ ❯ twitter-ads
+twitter-ads vX.X.X >> CLIENT
+=> #<TwitterAds::Client:0x70101526238580 consumer_key="Fy90KQy57152sn5Mv7axji9409">
+twitter-ads vX.X.X >> CLIENT.accounts.first
+=> #<TwitterAds::Account:0x70101527905720 id="4lvtcum">
+```
+For more help please see our [Examples and Guides](https://github.com/twitterdev/twitter-ruby-ads-sdk/tree/master/examples) or check the online [Reference Documentation](http://twitterdev.github.io/twitter-ruby-ads-sdk/reference/index.html).
+
+## Compatibility & Versioning
+
+This project is designed to work with Ruby 2.0.0 or greater. While it may work on other version of Ruby, below are the platform and runtime versions we officially support and regularly test against.
+
+Platform | Versions
+-------- | --------
+MRI | 2.0.0, 2.1.x, 2.2.x, 2.3.x
+JRuby | 1.7.x, 9.0.0.0 (JDK7, JDK8, OpenJDK)
+Rubinius | 2.4.x, 2.5.x
+
+All releases adhere to strict [semantic versioning](http://semver.org). For Example, major.minor.patch-pre (aka. stick.carrot.oops-peek).
+
+## Development
+If you'd like to contribute to the project or try an unreleased development version of this project locally, you can do so quite easily by following the examples below.
+```bash
+# clone the repository
+git clone git@github.com:twitterdev/twitter-ruby-ads-sdk.git
+cd twitter-ruby-ads-sdk
+
+# install dependencies
+bundle install
+
+rake docs # building documentation
+rake spec # run all tests
+
+# installing a local unsigned release
+gem build twitter-ads.gemspec & gem install twitter-ads-X.X.X.gem
+```
+We love community contributions! If you're planning to send us a pull request, please make sure read our [Contributing Guidelines](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/master/CONTRIBUTING.md) first.
+
+## Feedback and Bug Reports
+Found an issue? Please open up a [GitHub issue](https://github.com/twitterdev/twitter-ruby-ads-sdk/issues) or even better yet [send us](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/master/CONTRIBUTING.md) a pull request.<br/>
+Have a question? Want to discuss a new feature? Come chat with us in the [Twitter Community Forums](https://twittercommunity.com/c/advertiser-api).
+
+## Error Handling
+
+Like the [Response](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/master/lib/twitter-ads/http/response.rb) and [Request](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/master/lib/twitter-ads/http/request.rb) classes, the Ads API SDK fully models all [error objects](https://github.com/twitterdev/twitter-ruby-ads-sdk/blob/master/lib/twitter-ads/error.rb) for easy error handling.
+
+<img src="http://i.imgur.com/opbv7Nh.png"/ alt="Error Hierarchy">
+
+## License
+
+The MIT License (MIT)
+
+Copyright (C) 2015 Twitter, Inc.
+
+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/Rakefile

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright (C) 2015 Twitter, Inc.
+
+require 'rubygems'
+
+begin
+  require 'bundler'
+  require 'bundler/gem_tasks'
+rescue LoadError
+  raise '[FAIL] Bundler not found! Install it with ' \
+        '`gem install bundler; bundle install`.'
+end
+
+# Helper for making a bit of log noise.
+def announce(type, message, &block)
+  print "[#{type.to_s.upcase}] #{message}... "
+  begin
+    yield block
+    print "[DONE]\n".colorize(color: :green).bold
+  rescue StandardError
+    print "[FAILED]\n".colorize(color: :red).bold
+    abort
+  end
+end
+
+# Default Rake Task
+if ENV['CI']
+  task default: ['spec'] # 'features'
+  Bundler.require(:default, :test)
+else
+  task default: ['spec'] # 'features'
+  Bundler.require(:default, :test, :development, :release)
+end
+
+# Cucumber Setup
+require 'cucumber'
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = 'features --format progress --strict'
+end
+
+# RSpec Setup
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+unless ENV['CI']
+
+  # Release and Deployment
+  desc 'Builds the latest SDK docs locally'
+  task :docs do
+    FileUtils.rm_rf('doc')
+    YARD::CLI::CommandParser.run('--quiet')
+  end
+
+  namespace :docs do
+    git = Git.open(File.expand_path('../', __FILE__))
+
+    desc 'Builds and deploys the latest SDK docs'
+    task :deploy do
+      unless git.status.changed.empty?
+        puts 'Error! Cannot proceeed, you have pending changes.'.colorize(color: :red).bold
+        abort
+      end
+      FileUtils.rm_rf('doc')
+      YARD::CLI::CommandParser.run
+
+      current_branch = git.branch.name
+      announce(:build, "updating v#{TwitterAds::VERSION} documentation") do
+        git.branch('gh-pages').checkout
+        FileUtils.rm_rf('reference')
+        FileUtils.mv('doc', 'reference')
+        git.add('reference')
+        git.commit("[docs] updating v#{TwitterAds::VERSION} documentation")
+      end
+
+      announce(:push, "publishing v#{TwitterAds::VERSION} documentation") do
+        git.push('origin', 'gh-pages')
+      end
+
+      git.branch(current_branch).checkout
+    end
+  end
+
+end

data/bin/twitter-ads

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'twitter'
+rescue LoadError
+end
+
+$LOAD_PATH.push File.join(File.dirname(__FILE__), '..', 'lib')
+require 'twitter-ads'
+
+include TwitterAds
+include TwitterAds::Enum
+
+# load up a ready-to-go client instance if .twurlrc is setup
+if File.exists?(File.expand_path('~/.twurlrc'))
+  require 'yaml'
+  twurl_config    = YAML.load(File.read(File.expand_path('~/.twurlrc')))
+  profile_name    = twurl_config['configuration']['default_profile'][0]
+  profile_key     = twurl_config['configuration']['default_profile'][1]
+  default_profile = twurl_config['profiles'][profile_name][profile_key]
+  CLIENT = TwitterAds::Client.new(
+    default_profile['consumer_key'],
+    default_profile['consumer_secret'],
+    default_profile['token'],
+    default_profile['secret'],
+  )
+end
+
+begin
+  require 'pry'
+  KLASS = Pry
+  version_info = "twitter-ads v#{TwitterAds::VERSION}"
+  KLASS.config.prompt = [
+    proc { "#{version_info} >> " },
+    proc { "#{version_info} ... " }
+  ]
+rescue LoadError
+  require 'irb'
+  KLASS = IRB
+end
+
+KLASS.start(__FILE__)

data/lib/twitter-ads.rb

@@ -0,0 +1,54 @@
+# rubocop:disable Style/FileName
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+# rubocop:enable Style/FileName
+
+require 'time'
+require 'oauth'
+require 'multi_json'
+require 'forwardable'
+require 'logger'
+
+require 'twitter-ads/version'
+require 'twitter-ads/utils'
+require 'twitter-ads/error'
+
+require 'twitter-ads/resources/dsl'
+require 'twitter-ads/resources/resource'
+require 'twitter-ads/resources/persistence'
+require 'twitter-ads/resources/analytics'
+
+require 'twitter-ads/client'
+require 'twitter-ads/cursor'
+require 'twitter-ads/account'
+
+require 'twitter-ads/http/request'
+require 'twitter-ads/http/response'
+require 'twitter-ads/http/ton_upload'
+
+require 'twitter-ads/audiences/tailored_audience'
+
+require 'twitter-ads/campaign/app_list'
+require 'twitter-ads/campaign/campaign'
+require 'twitter-ads/campaign/funding_instrument'
+require 'twitter-ads/campaign/line_item'
+require 'twitter-ads/campaign/promotable_user'
+require 'twitter-ads/campaign/targeting_criteria'
+require 'twitter-ads/campaign/tweet'
+
+require 'twitter-ads/enum'
+
+require 'twitter-ads/creative/app_download_card'
+require 'twitter-ads/creative/image_app_download_card'
+require 'twitter-ads/creative/image_conversation_card'
+require 'twitter-ads/creative/lead_gen_card'
+require 'twitter-ads/creative/promoted_account'
+require 'twitter-ads/creative/promoted_tweet'
+require 'twitter-ads/creative/video_app_download_card'
+require 'twitter-ads/creative/video_conversation_card'
+require 'twitter-ads/creative/website_card'
+require 'twitter-ads/creative/video'
+
+require 'twitter-ads/targeting/reach_estimate'
+
+require 'twitter-ads/legacy.rb'

data/lib/twitter-ads/account.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+# Copyright (C) 2015 Twitter, Inc.
+
+module TwitterAds
+  class Account
+
+    include TwitterAds::DSL
+
+    attr_reader :client
+
+    property :id, read_only: true
+    property :name, read_only: true
+    property :salt, read_only: true
+    property :timezone, read_only: true
+    property :timezone_switch_at, type: :time, 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
+
+    RESOURCE_COLLECTION = '/0/accounts'.freeze # @api private
+    RESOURCE            = '/0/accounts/%{id}'.freeze # @api private
+    FEATURES            = '/0/accounts/%{id}/features'.freeze # @api private
+    SCOPED_TIMELINE     = '/0/accounts/%{id}/scoped_timeline'.freeze # @api private
+    AUTHENTICATED_USER_ACCESS = '/0/accounts/%{id}/authenticated_user_access'.freeze # @api private
+
+    def initialize(client)
+      @client = client
+      self
+    end
+
+    class << self
+
+      # Load a specific Account object by ID.
+      #
+      # @example
+      #   account = Account.load(client, '7o4em', with_deleted: true)
+      #
+      # @param client [Client] The Client object instance.
+      # @param id [String] The Account ID value.
+      #
+      # @return [Account] The Account object instance.
+      #
+      # @since 0.1.0
+      def load(client, id)
+        resource = RESOURCE % { id: id }
+        response = Request.new(client, :get, resource).perform
+        new(client).from_response(response.body[:data])
+      end
+
+      # Fetches all available Accounts.
+      #
+      # @example
+      #   account = Account.all(client, with_deleted: true, sort_by: 'updated_at-desc')
+      #
+      # @param client [Client] The Client object instance.
+      # @param opts [Hash] A 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 Cursor for the API results.
+      #
+      # @since 0.1.0
+      # @see https://dev.twitter.com/ads/basics/sorting Sorting
+      def all(client, opts = {})
+        request = Request.new(client, :get, RESOURCE_COLLECTION, params: opts)
+        Cursor.new(self, request, init_with: [client])
+      end
+
+    end
+
+    # Returns an inspection string for the current object instance.
+    #
+    # @return [String] The object instance detail.
+    def inspect
+      str = String.new("#<#{self.class.name}:0x#{object_id}")
+      str << " id=\"#{@id}\"" if @id
+      str << '>'
+    end
+
+    # Returns a collection of features available to the current account.
+    #
+    # @return [Array] The list of features enabled for the account.
+    #
+    # @since 0.1.0
+    def features
+      validate_loaded
+      resource = FEATURES % { id: @id }
+      response = Request.new(client, :get, resource).perform
+      response.body[:data]
+    end
+
+    # Returns a collection of promotable users available to the current account.
+    #
+    # @param id [String] The PromotableUser ID value.
+    # @param opts [Hash] A 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 A Cursor or object instance.
+    #
+    # @since 0.1.0
+    def promotable_users(id = nil, opts = {})
+      load_resource(PromotableUser, id, opts)
+    end
+
+    # Returns a collection of funding instruments available to the current account.
+    #
+    # @param id [String] The FundingInstrument ID value.
+    # @param opts [Hash] A 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 A Cursor or object instance.
+    #
+    # @since 0.1.0
+    def funding_instruments(id = nil, opts = {})
+      load_resource(FundingInstrument, id, opts)
+    end
+
+    # Returns a collection of campaigns available to the current account.
+    #
+    # @param id [String] The Campaign ID value.
+    # @param opts [Hash] A 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 A Cursor or object instance.
+    #
+    # @since 0.1.0
+    def campaigns(id = nil, opts = {})
+      load_resource(Campaign, id, opts)
+    end
+
+    # Returns a collection of line items available to the current account.
+    #
+    # @param id [String] The LineItem ID value.
+    # @param opts [Hash] A 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 A Cursor or object instance.
+    #
+    # @since 0.1.0
+    def line_items(id = nil, opts = {})
+      load_resource(LineItem, id, opts)
+    end
+
+    # Returns a collection of app lists available to the current account.
+    #
+    # @param id [String] The AppList ID value.
+    # @param opts [Hash] A 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.
+    #
+    # @since 0.2.0
+    #
+    # @return A list or object instance.
+    def app_lists(id = nil, opts = {})
+      load_resource(AppList, id, opts)
+    end
+
+    # Returns a collection of tailored audiences available to the current account.
+    #
+    # @param id [String] The TailoredAudience ID value.
+    # @param opts [Hash] A 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.
+    #
+    # @since 0.3.0
+    #
+    # @return A Cursor or object instance.
+    def tailored_audiences(id = nil, opts = {})
+      load_resource(TailoredAudience, id, opts)
+    end
+
+    # Returns a collection of videos available to the current account.
+    #
+    # @param id [String] The Video ID value.
+    # @param opts [Hash] A 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.
+    #
+    # @since 0.3.0
+    #
+    # @return A Cursor or object instance.
+    def videos(id = nil, opts = {})
+      load_resource(Video, id, opts)
+    end
+
+    # Returns the most recent promotable Tweets created by one or more specified Twitter users.
+    #
+    # @param ids [Array] An Array of Twitter user IDs.
+    # @param opts [Hash] A Hash of extended options.
+    #
+    # @return [Array] An Array of Tweet objects.
+    #
+    # @since 0.2.3
+    def scoped_timeline(ids, opts = {})
+      ids      = ids.join(',') if ids.is_a?(Array)
+      params   = { user_ids: ids }.merge!(opts)
+      resource = SCOPED_TIMELINE % { id: @id }
+      request  = Request.new(client, :get, resource, params: params)
+      response = request.perform
+      response.body[:data]
+    end
+
+    def authenticated_user_access
+      params = {}
+      resource = AUTHENTICATED_USER_ACCESS % { id: @id }
+      request  = Request.new(client, :get, resource, params: params)
+      response = request.perform
+      response.body[:data]
+    end
+
+    private
+
+    def load_resource(klass, id = nil, opts = {})
+      validate_loaded
+      id ? klass.load(self, id, opts) : klass.all(self, opts)
+    end
+
+    def validate_loaded
+      raise ArgumentError.new(
+        "Error! #{self.class} object not yet initialized, " \
+        "call #{self.class}.load first") unless @id
+    end
+
+  end
+end