twurl 0.9.1 → 0.9.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e12cf717906fbf24bcd34598212105569647dbed1f6b5ee37a195ec0db8ca15
+  data.tar.gz: c5d7a22975a06fccc328a99323ead35584104e77fcf3827611d9cf279ccb22bf
+SHA512:
+  metadata.gz: daf4dae500fb05b24eaed8413538420bf66d5f113982663e7e3bd416df6d4a98eef31b982eac9174eaa251421aef512db60bd3675c4ae55529ef009603a070de
+  data.tar.gz: 7ef9671671c1d946f0671147b49c8485b21da16837a1c890b2e67b28f5b3f4ed2065e9b896ae9a3533d92bb384908c79f0fd72543adb5a06626aec0390d98f2c

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,48 @@
+# Code of Conduct v2.0
+
+This code of conduct outlines our expectations for participants within the [@TwitterOSS](https://twitter.com/twitteross) community, as well as steps to reporting unacceptable behavior. We are committed to providing a welcoming and inspiring community for all and expect our code of conduct to be honored. Anyone who violates this code of conduct may be banned from the community.
+
+Our open source community strives to:
+
+* **Be friendly and patient.**
+* **Be welcoming**: We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
+* **Be considerate**: Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
+* **Be respectful**:  Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one.
+* **Be careful in the words that you choose**: we are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
+  * Violent threats or language directed against another person.
+  * Discriminatory jokes and language.
+  * Posting sexually explicit or violent material.
+  * Posting (or threatening to post) other people's personally identifying information ("doxing").
+  * Personal insults, especially those using racist or sexist terms.
+  * Unwelcome sexual attention.
+  * Advocating for, or encouraging, any of the above behavior.
+  * Repeated harassment of others. In general, if someone asks you to stop, then stop.
+* **When we disagree, try to understand why**: Disagreements, both social and technical, happen all the time. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of our community comes from its diversity, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
+
+This code is not exhaustive or complete. It serves to distill our common understanding of a collaborative, shared environment, and goals. We expect it to be followed in spirit as much as in the letter.
+
+### Diversity Statement
+
+We encourage everyone to participate and are committed to building a community for all. Although we may not be able to satisfy everyone, we all agree that everyone is equal. Whenever a participant has made a mistake, we expect them to take responsibility for it. If someone has been harmed or offended, it is our responsibility to listen carefully and respectfully, and do our best to right the wrong.
+
+Although this list cannot be exhaustive, we explicitly honor diversity in age, gender, gender identity or expression, culture, ethnicity, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, and technical ability. We will not tolerate discrimination based on any of the protected
+characteristics above, including participants with disabilities.
+
+### Reporting Issues
+
+If you experience or witness unacceptable behavior—or have any other concerns—please report it by contacting us via [opensource+codeofconduct@twitter.com](mailto:opensource+codeofconduct@twitter.com). All reports will be handled with discretion. In your report please include:
+
+- Your contact information.
+- Names (real, nicknames, or pseudonyms) of any individuals involved. If there are additional witnesses, please
+include them as well. Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly available record (e.g. a mailing list archive or a public IRC logger), please include a link.
+- Any additional information that may be helpful.
+
+After filing a report, a representative will contact you personally. If the person who is harassing you is part of the response team, they will recuse themselves from handling your incident. A representative will then review the incident, follow up with any additional questions, and make a decision as to how to respond. We will respect confidentiality requests for the purpose of protecting victims of abuse.
+
+Anyone asked to stop unacceptable behavior is expected to comply immediately. If an individual engages in unacceptable behavior, the representative may take any action they deem appropriate, up to and including a permanent ban from our community without warning.
+
+## Thanks
+
+This code of conduct is based on the [Open Code of Conduct](https://github.com/todogroup/opencodeofconduct) from the [TODOGroup](http://todogroup.org). 
+
+We are thankful for their work and all the communities who have paved the way with code of conducts.

data/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# How to Contribute
+
+We'd love to get patches from you!
+
+## Getting Started
+
+We follow the [GitHub Flow Workflow](https://guides.github.com/introduction/flow/)
+
+1. Fork the project
+2. Check out the `master` branch
+3. Create a feature branch
+4. Write code and tests for your change  
+
+```sh
+$ cd ./twurl
+
+# install twurl from source
+$ bundle install
+
+# run twurl from source
+$ bundle exec twurl -v
+
+# run tests
+$ bundle exec rake
+```
+
+5. From your branch, make a pull request against `twitter/twurl/master`
+6. Work with repo maintainers to get your change reviewed
+7. Wait for your change to be pulled into `twitter/twurl/master`
+8. Delete your feature branch
+
+## License
+
+By contributing your code, you agree to license your contribution under the
+terms of the MIT License: https://github.com/twitter/twurl/blob/master/LICENSE
+
+## Code of Conduct
+
+Read our [Code of Conduct](CODE_OF_CONDUCT.md) for the project.

data/INSTALL.md

@@ -0,0 +1,36 @@
+# Install
+
+## Install with RubyGems (recommended)
+
+```sh
+# installing the latest release
+$ gem install twurl
+```
+
+```sh
+# verify installation
+$ twurl -v
+0.9.6
+```
+
+## Install from source
+
+In case if you haven't installed `bundler` you need to install it first:
+
+```sh
+$ gem install bundler
+```
+
+```sh
+$ git clone https://github.com/twitter/twurl
+$ cd twurl
+$ bundle install
+```
+
+If you don't want to install Twurl globally on your system, use `--path` [option](https://bundler.io/v2.0/bundle_install.html):
+
+```
+$ bundle install --path path/to/directory
+$ bundle exec twurl -v
+0.9.6
+```

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2009 Marcel Molina <marcel@twitter.com>, 2019 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,176 @@
+# Twurl
+
+[![MIT License](https://img.shields.io/apm/l/atomic-design-ui.svg?)](https://github.com/twitter/twurl/blob/master/LICENSE)
+ [![Gem Version](https://badge.fury.io/rb/twurl.svg)](https://badge.fury.io/rb/twurl)
+  [![Build Status](https://travis-ci.com/twitter/twurl.svg?branch=master)](https://travis-ci.com/twitter/twurl)
+
+Twurl is like curl, but tailored specifically for the Twitter API.
+It knows how to grant an access token to a client application for
+a specified user and then sign all requests with that access token.
+
+It also provides other development and debugging conveniences such
+as defining aliases for common requests, as well as support for
+multiple access tokens to easily switch between different client
+applications and Twitter accounts.
+
+## Installing Twurl
+
+Twurl can be installed using RubyGems:
+
+```sh
+gem install twurl
+```
+
+## Getting Started
+
+If you haven't already, the first thing to do is apply for a developer account to access Twitter APIs:
+
+```text
+https://developer.twitter.com/en/apply-for-access
+```
+
+After you have that access you can create a Twitter app and generate a consumer key and secret.
+
+When you have your consumer key and its secret you authorize
+your Twitter account to make API requests with that consumer key
+and secret.
+
+```sh
+twurl authorize --consumer-key key       \
+                --consumer-secret secret
+```
+
+This will return an URL that you should open up in your browser.
+Authenticate to Twitter, and then enter the returned PIN back into
+the terminal.  Assuming all that works well, you will be authorized
+to make requests with the API. Twurl will tell you as much.
+
+## Making Requests
+
+The simplest request just requires that you specify the path you
+want to request.
+
+```sh
+twurl /1.1/statuses/home_timeline.json
+```
+
+Similar to curl, a GET request is performed by default.
+
+You can implicitly perform a POST request by passing the -d option,
+which specifies POST parameters.
+
+```sh
+twurl -d 'status=Testing twurl' /1.1/statuses/update.json
+```
+
+You can explicitly specify what request method to perform with
+the -X (or --request-method) option.
+
+```sh
+twurl -X POST /1.1/statuses/destroy/1234567890.json
+```
+
+## Using Bearer Tokens (Application-only authentication)
+
+You can generate a bearer token using `--bearer` option in combination with the `authorize` subcommand.
+
+```sh
+twurl authorize --bearer --consumer-key key       \
+                         --consumer-secret secret
+```
+
+And then, you can make a request using a generated bearer token using `--bearer` request option.
+
+```sh
+twurl --bearer '/1.1/search/tweets.json?q=hello'
+```
+
+To list your generated bearer tokens, you can use the `bearer_tokens` subcommand.
+
+```sh
+twurl bearer_tokens
+```
+
+This will print a pair of consumer_key and its associated bearer token. Note, tokens are omitted from this output.
+
+## Accessing Different Hosts
+
+You can access different hosts for other Twitter APIs using the -H flag.
+
+```sh
+twurl -H "ads-api.twitter.com" "/7/accounts"
+```
+
+## Uploading Media
+
+To upload binary files, you can format the call as a form post. Below, the binary is "/path/to/media.jpg" and the form field is "media":
+
+```sh
+twurl -H "upload.twitter.com" -X POST "/1.1/media/upload.json" --file "/path/to/media.jpg" --file-field "media"
+```
+
+## Creating aliases
+
+```sh
+twurl alias h /1.1/statuses/home_timeline.json
+```
+
+You can then use "h" in place of the full path.
+
+```sh
+twurl h
+```
+
+Paths that require additional options (such as request parameters, for example) can be used with aliases the same as with full explicit paths, just as you might expect.
+
+```sh
+twurl alias tweet /1.1/statuses/update.json
+twurl tweet -d "status=Aliases in twurl are convenient"
+```
+
+## Changing your default profile
+
+The first time you authorize a client application to make requests on behalf of your account, twurl stores your access token information in its `~/.twurlrc` file. Subsequent requests will use this profile as the default profile. You can use the `accounts` subcommand to see what client applications have been authorized for what user names:
+
+```sh
+twurl accounts
+  noradio
+    HQsAGcBm5MQT4n6j7qVJw
+    hhC7Koy2zRsTZvQh1hVlSA (default)
+  testiverse
+    guT9RsJbNQgVe6AwoY9BA
+```
+
+Notice that one of those consumer keys is marked as the default. To change the default use the `set` subcommand, passing then either just the username, if it's unambiguous, or the username and consumer key pair if it isn't unambiguous:
+
+```sh
+twurl set default testiverse
+twurl accounts
+  noradio
+    HQsAGcBm5MQT4n6j7qVJw
+    hhC7Koy2zRsTZvQh1hVlSA
+  testiverse
+    guT9RsJbNQgVe6AwoY9BA (default)
+```
+
+```sh
+twurl set default noradio HQsAGcBm5MQT4n6j7qVJw
+twurl accounts
+  noradio
+    HQsAGcBm5MQT4n6j7qVJw (default)
+    hhC7Koy2zRsTZvQh1hVlSA
+  testiverse
+    guT9RsJbNQgVe6AwoY9BA
+```
+
+### Profiles and Bearer Tokens
+
+While changing the default profile allows you to select which access token (OAuth1.0a) to use, bearer tokens don't link to any user profiles as the Application-only authentication doesn't require user context. That is, you can make an application-only request regardless of your default profile if you specify the `-c` (`--consumer-key`) option once you generate a bearer token with this consumer key. By default, twurl reads the current profile's consumer key and its associated bearer token from `~/.twurlrc` file.
+
+## Contributors
+
+Marcel Molina / @noradio
+
+Erik Michaels-Ober / @sferik
+
+and there are many [more](https://github.com/twitter/twurl/graphs/contributors)!

data/lib/twurl.rb

@@ -4,6 +4,7 @@ require 'optparse'
 require 'ostruct'
 require 'stringio'
 require 'yaml'
+require 'json'
 
 library_files = Dir[File.join(File.dirname(__FILE__), "/twurl/**/*.rb")].sort
 library_files.each do |file|

data/lib/twurl/app_only_oauth_client.rb

@@ -0,0 +1,78 @@
+require 'base64'
+require_relative 'oauth_client'
+
+module Twurl
+  class AppOnlyOAuthClient < Twurl::OAuthClient
+
+    AUTHORIZATION_FAILED_MESSAGE = "Authorization failed. Check that your consumer key and secret are correct."
+
+    attr_reader :consumer_key, :consumer_secret, :bearer_token
+
+    def initialize(options = {})
+      @consumer_key    = options['consumer_key']
+      @consumer_secret = options['consumer_secret']
+      @bearer_token    = options['bearer_token']
+    end
+
+    def save
+      self.class.rcfile.bearer_token(consumer_key, bearer_token)
+    end
+
+    def exchange_credentials_for_access_token
+      response = fetch_oauth2_token
+      if response.nil? || response[:access_token].nil?
+        raise Exception, AUTHORIZATION_FAILED_MESSAGE
+      end
+      @bearer_token = response[:access_token]
+    end
+
+    def perform_request_from_options(options, &block)
+      request = build_request_from_options(options)
+      request['user-agent'] = user_agent
+      request['authorization'] = "Bearer #{bearer_token}"
+
+      http_client.request(request, &block)
+    end
+
+    def needs_to_authorize?
+      bearer_token.nil?
+    end
+
+    def request_data
+      {'grant_type' => 'client_credentials'}
+    end
+
+    def http_client
+      uri = URI.parse(Twurl.options.base_url)
+      http = if Twurl.options.proxy
+        proxy_uri = URI.parse(Twurl.options.proxy)
+        Net::HTTP.new(uri.host, uri.port, proxy_uri.host, proxy_uri.port)
+      else
+        Net::HTTP.new(uri.host, uri.port)
+      end
+      set_http_client_options(http)
+    end
+
+    def set_http_client_options(http)
+      http.set_debug_output(Twurl.options.debug_output_io) if Twurl.options.trace
+      http.read_timeout = http.open_timeout = Twurl.options.timeout || 60
+      http.open_timeout = Twurl.options.connection_timeout if Twurl.options.connection_timeout
+      # Only override if Net::HTTP support max_retries (since Ruby >= 2.5)
+      http.max_retries = 0 if http.respond_to?(:max_retries=)
+      if Twurl.options.ssl?
+        http.use_ssl     = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      http
+    end
+
+    def fetch_oauth2_token
+      request = Net::HTTP::Post.new('/oauth2/token')
+      request.body = URI.encode_www_form(request_data)
+      request['user-agent'] = user_agent
+      request['authorization'] = "Basic #{Base64.strict_encode64("#{consumer_key}:#{consumer_secret}")}"
+      response = http_client.request(request).body
+      JSON.parse(response,:symbolize_names => true)
+    end
+  end
+end

data/lib/twurl/app_only_token_information_controller.rb

@@ -0,0 +1,18 @@
+module Twurl
+  class AppOnlyTokenInformationController < AbstractCommandController
+    NO_ISSUED_TOKENS_MESSAGE = "No issued application-only (Bearer) tokens"
+
+    def dispatch
+      rcfile = OAuthClient.rcfile
+      if rcfile.empty? || rcfile.bearer_tokens.nil?
+        CLI.puts NO_ISSUED_TOKENS_MESSAGE
+      else
+        tokens = rcfile.bearer_tokens
+        CLI.puts "[consumer_key: bearer_token]"
+        tokens.each_key do |consumer_key|
+          CLI.puts "#{consumer_key}: (omitted)"
+        end
+      end
+    end
+  end
+end

data/lib/twurl/cli.rb

@@ -1,10 +1,10 @@
 module Twurl
   class CLI
-    SUPPORTED_COMMANDS     = %w(authorize accounts alias set)
+    SUPPORTED_COMMANDS     = %w(authorize accounts bearer_tokens alias set)
     DEFAULT_COMMAND        = 'request'
     PATH_PATTERN           = /^\/\w+/
     PROTOCOL_PATTERN       = /^\w+:\/\//
-    README                 = File.dirname(__FILE__) + '/../../README'
+    README                 = File.dirname(__FILE__) + '/../../README.md'
     @output              ||= STDOUT
     class NoPathFound < Exception
     end
@@ -28,6 +28,8 @@ module Twurl
                        AuthorizationController
                      when 'accounts'
                        AccountInformationController
+                     when 'bearer_tokens'
+                       AppOnlyTokenInformationController
                      when 'alias'
                        AliasesController
                      when 'set'
@@ -41,9 +43,8 @@ module Twurl
       end
 
       def parse_options(args)
-        arguments = args.dup
-
         Twurl.options         = Options.new
+        Twurl.options.args    = args.dup
         Twurl.options.trace   = false
         Twurl.options.data    = {}
         Twurl.options.headers = {}
@@ -66,7 +67,6 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
 
           o.section "Authorization options:" do
             username
-            password
             consumer_key
             consumer_secret
             access_token
@@ -76,6 +76,7 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
           o.section "Common options:" do
             trace
             data
+            raw_data
             headers
             host
             quiet
@@ -87,19 +88,31 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
             file
             filefield
             base64
+            json_format
+            timeout
+            connection_timeout
+            app_only
           end
         end
 
-        arguments                 = option_parser.parse!(args)
+        begin
+          arguments               = option_parser.parse!(args)
+        rescue OptionParser::InvalidOption
+          CLI.puts "ERROR: undefined option"
+          exit
+        rescue
+          CLI.puts "ERROR: invalid argument"
+          exit
+        end
         Twurl.options.command     = extract_command!(arguments)
         Twurl.options.path        = extract_path!(arguments)
-
-        if Twurl.options.command == DEFAULT_COMMAND and Twurl.options.path.nil?
+        Twurl.options.subcommands = arguments
+        
+        if Twurl.options.command == DEFAULT_COMMAND and Twurl.options.path.nil? and Twurl.options.args.empty?
           CLI.puts option_parser
           raise NoPathFound, "No path found"
         end
 
-        Twurl.options.subcommands = arguments
         Twurl.options
       end
 
@@ -158,11 +171,9 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
         end
 
         def escape_params(params)
-          split_params = params.split("&").map do |param|
-            key, value = param.split('=', 2)
-            CGI::escape(key) + '=' + CGI::escape(value)
-          end
-          split_params.join("&")
+          CGI::parse(params).map do |key, value|
+            "#{CGI.escape key}=#{CGI.escape value.first}"
+          end.join("&")
         end
     end
 
@@ -204,7 +215,7 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
       end
 
       def token_secret
-        on('-S', '--token-secret', "Your token secret") do |secret|
+        on('-S', '--token-secret [secret]', "Your token secret") do |secret|
           options.token_secret = secret
         end
       end
@@ -215,12 +226,6 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
         end
       end
 
-      def password
-        on('-p', '--password [password]', 'Password of account to authorize (required)') do |password|
-          options.password = password ? password : CLI.prompt_for('Password')
-        end
-      end
-
       def trace
         on('-t', '--[no-]trace', 'Trace request/response traffic (default: --no-trace)') do |trace|
           options.trace = trace
@@ -229,9 +234,21 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
 
       def data
         on('-d', '--data [data]', 'Sends the specified data in a POST request to the HTTP server.') do |data|
-          data.split('&').each do |pair|
-            key, value = pair.split('=', 2)
-            options.data[key] = value
+          if options.args.count { |item| /content-type: (.*)/i.match(item) } > 0
+            options.data[data] = nil
+          else
+            data.split('&').each do |pair|
+              key, value = pair.split('=', 2)
+              options.data[key] = value
+            end
+          end
+        end
+      end
+
+      def raw_data
+        on('-r', '--raw-data [data]', 'Sends the specified data as it is in a POST request to the HTTP server.') do |data|
+          CGI::parse(data).each_pair do |key, value|
+            options.data[key] = value.first
           end
         end
       end
@@ -296,29 +313,51 @@ Supported Commands: #{SUPPORTED_COMMANDS.sort.join(', ')}
         on('-f', '--file [path_to_file]', 'Specify the path to the file to upload') do |file|
           if File.file?(file)
             options.upload['file'] << file
-          else 
+          else
             CLI.puts "ERROR: File not found"
             exit
           end
         end
       end
-      
-      def filefield 
-        on('-F', '--file-field [field_name]', 'Specify the file field for the upload to be included within (default: media)') do |filefield|
+
+      def filefield
+        on('-F', '--file-field [field_name]', 'Specify the POST parameter name for the file upload data (default: media)') do |filefield|
           options.upload['filefield'] = filefield
-          options.upload['filefield'] = 'media[]' if options.upload['filefield'].empty? 
         end
       end
-      
-      def base64 
+
+      def base64
         on('-b', '--base64', 'Encode the uploaded file as base64 (default: false)') do |base64|
           options.upload['base64'] = base64
         end
       end
+
+      def json_format
+        on('-j', '--json-pretty', 'Format response body to JSON pretty style') do |json_format|
+          options.json_format = true
+        end
+      end
+
+      def timeout
+        on('--timeout [sec]', Integer, 'Number of seconds to wait for the request to be read (default: 60)') do |timeout|
+          options.timeout = timeout
+        end
+      end
+
+      def connection_timeout
+        on('--connection-timeout [sec]', Integer, 'Number of seconds to wait for the connection to open (default: 60)') do |connection_timeout|
+          options.connection_timeout = connection_timeout
+        end
+      end
+
+      def app_only
+        on('--bearer', "Use application-only authentication (Bearer Token)") do |app_only|
+          options.app_only = true
+        end
+      end
     end
   end
 
-    
   class Options < OpenStruct
     DEFAULT_REQUEST_METHOD = 'get'
     DEFAULT_HOST           = 'api.twitter.com'