camp3 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1494749b2bca6c9abf1b88fb92f095cb7b9a304a7109984dc625a1db82bd3983
-  data.tar.gz: 62cb4e89f50f16c162e8c74e06286fe8437980d5f542751a1b3cb49a3b38475e
+  metadata.gz: c51061a5954cc07915e99c8e709dde954de59d976664b0fafc0f4e8029d28505
+  data.tar.gz: 98cfe680d84287497ac4c0d8ab6bcdcde00fb9f41ab0b444e90a368cc2a472f4
 SHA512:
-  metadata.gz: 173586f31acad3b9d8219694c3268d5611d8c24eddf057f552c8fd3ab757745eb21a0ed4adb7d729da12e7e650c919602b5856bf595fad9ca6d8c94a90534b9c
-  data.tar.gz: 403f48695817d15d305ec6aca49c3bf91aecb76cce9292001dbbd8505fdff54284d2c585178c364a1c45e44d0a28a1bda5dd50f6477e4efde3e85b12a7168fe7
+  metadata.gz: 4697b931b0e50fdd54e7345de1ebf552f4a5daad1dfb1472773890c5ac107a2a9c512d2dfdf0a852c40650212ea3d3fcff508f23be27c73686fbe2b83539b55f
+  data.tar.gz: 736fe2af5f5eb1599920d9466f52ab60ab637e6356886115b1ff9b9b07822c6030359070e04f9bbc39f5a9eccae96c624be5e984f180f459883cd2178290dd43

data/.github/workflows/ci.yml

@@ -1,10 +1,3 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
-# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
-
 name: CI
 
 on:
@@ -34,3 +27,27 @@ jobs:
         gem install bundler --no-document
         bundle install --jobs 4 --retry 3
         bundle exec rake
+
+  changelog_prerelease:
+    name: Update Changelog For Prerelease
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+        with:
+          ref: master
+      - name: Update Changelog
+        uses: heinrichreimer/github-changelog-generator-action@v2.1.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issues: true
+          issuesWoLabels: true
+          pullRequests: true
+          prWoLabels: true
+          unreleased: true
+          addSections: '{"documentation":{"prefix":"**Documentation:**","labels":["documentation"]}}'
+      - uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: Update Changelog for PR
+          file_pattern: CHANGELOG.md

data/.github/workflows/release_metadata.yml

@@ -10,16 +10,29 @@ jobs:
     name: Update Changelog
     runs-on: ubuntu-latest
     steps:
+      - name: Get version from tag
+        env:
+          GITHUB_REF: ${{ github.ref }}
+        run: |
+          export CURRENT_VERSION=${GITHUB_TAG/refs\/tags\/v/}
+          echo "::set-env name=CURRENT_VERSION::$CURRENT_VERSION"
       - name: Checkout code
         uses: actions/checkout@v2
+        with:
+          ref: master
       - name: Update Changelog
         uses: heinrichreimer/github-changelog-generator-action@v2.1.1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
+          issues: true
+          issuesWoLabels: true
+          pullRequests: true
+          prWoLabels: true
+          addSections: '{"documentation":{"prefix":"**Documentation:**","labels":["documentation"]}}'
       - uses: stefanzweifel/git-auto-commit-action@v4
         with:
           # Required
-          commit_message: Update Changelog
+          commit_message: Update Changelog for tag ${{ env.CURRENT_VERSION }}
           file_pattern: CHANGELOG.md
 
   release_notes:

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## [Unreleased](https://github.com/renehernandez/camp3/tree/HEAD)
+
+**Implemented enhancements:**
+
+- Request a new access token once it expires [\#13](https://github.com/renehernandez/camp3/issues/13)
+- Retry for new access token [\#16](https://github.com/renehernandez/camp3/pull/16)
+
+**Fixed bugs:**
+
+- Remove unreleasedLabel field [\#15](https://github.com/renehernandez/camp3/pull/15)
+
+**Documentation:**
+
+- Initial documentation [\#5](https://github.com/renehernandez/camp3/issues/5)
+- Update docs for retry [\#17](https://github.com/renehernandez/camp3/pull/17)
+- Add section to categorize documentation changes [\#14](https://github.com/renehernandez/camp3/pull/14)
+- Docs [\#10](https://github.com/renehernandez/camp3/pull/10)
+
+## [v0.0.2](https://github.com/renehernandez/camp3/tree/v0.0.2) (2020-07-07)
+
+**Implemented enhancements:**
+
+- Manage release metadata [\#4](https://github.com/renehernandez/camp3/issues/4)
+- Implement release metadata management [\#9](https://github.com/renehernandez/camp3/pull/9)
+- Unify Resource and ObjectifiedHash classes [\#3](https://github.com/renehernandez/camp3/pull/3)
+- Added utility method to transform web URLs [\#2](https://github.com/renehernandez/camp3/pull/2)
+
+**Fixed bugs:**
+
+- Added missing import [\#1](https://github.com/renehernandez/camp3/pull/1)
+
+## [v0.0.1](https://github.com/renehernandez/camp3/tree/v0.0.1) (2020-06-29)
+
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/CONTRIBUTING.md

@@ -0,0 +1,183 @@
+# Contributing to Camp3
+
+Please take a moment to review this document in order to make the contribution
+process easy and effective for everyone involved!
+
+## Using the issue tracker
+
+You can use the issues tracker for:
+
+* [bug reports](#bug-reports)
+* [feature requests](#feature-requests)
+* [submitting pull requests](#pull-requests)
+
+Use [Stackoverflow](http://stackoverflow.com/) for questions and personal support requests.
+
+## Bug reports
+
+A bug is a _demonstrable problem_ that is caused by the code in the repository.
+Good bug reports are extremely helpful - thank you!
+
+Guidelines for bug reports:
+
+1. **Use the GitHub issue search** — check if the issue has already been
+   reported.
+
+2. **Check if the issue has been fixed** — try to reproduce it using the
+   `master` branch in the repository.
+
+3. **Isolate and report the problem** — ideally create a reduced test
+   case.
+
+Please try to be as detailed as possible in your report. Include information about
+your Ruby and Camp3 client. Please provide steps to
+reproduce the issue as well as the outcome you were expecting! All these details
+will help developers to fix any potential bugs.
+
+Example:
+
+> Short and descriptive example bug report title
+>
+> A summary of the issue and the environment in which it occurs. If suitable,
+> include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 2. This is the second step
+> 3. Further steps, etc.
+>
+> Any other information you want to share that is relevant to the issue being
+> reported. This might include the lines of code that you have identified as
+> causing the bug, and potential solutions (and your opinions on their
+> merits).
+
+## Feature requests
+
+Feature requests are welcome. But take a moment to find out whether your idea
+fits with the scope and aims of the project. It's up to *you* to make a strong
+case to convince the community of the merits of this feature.
+Please provide as much detail and context as possible.
+
+## Contributing Documentation
+
+Code documentation has a special convention: it uses [YARD](http://yardoc.org/)
+formatting and the first paragraph is considered to be a short summary.
+
+For methods say what it will do. For example write something like:
+
+```ruby
+# Reverses the contents of a String or IO object.
+#
+# @param [String, #read] contents the contents to reverse
+# @return [String] the contents reversed lexically
+def reverse(contents)
+  contents = contents.read if contents.respond_to? :read
+  contents.reverse
+end
+```
+
+For classes, modules say what it is. For example write something like:
+
+```ruby
+# Defines methods related to groups.
+module Groups
+```
+
+Keep in mind that the documentation notes might show up in a summary somewhere,
+long texts in the documentation notes create very ugly summaries. As a rule of thumb
+anything longer than 80 characters is too long.
+
+Try to keep unnecessary details out of the first paragraph, it's only there to
+give a user a quick idea of what the documented "thing" does/is. The rest of the
+documentation notes can contain the details, for example parameters and what
+is returned.
+
+If possible include examples
+
+This makes it easy to test the examples so that they don't go stale and examples
+are often a great help in explaining what a method does.
+
+## Pull requests
+
+Good pull requests - patches, improvements, new features - are a fantastic
+help. They should remain focused in scope and avoid containing unrelated
+commits.
+
+**IMPORTANT**: By submitting a patch, you agree that your work will be
+licensed under the license used by the project.
+
+If you have any large pull request in mind (e.g. implementing features,
+refactoring code, etc), **please ask first** otherwise you risk spending
+a lot of time working on something that the project's developers might
+not want to merge into the project.
+
+Please adhere to the coding conventions in the project (indentation,
+accurate comments, etc.) and don't forget to add your own tests and
+documentation. When working with git, we recommend the following process
+in order to craft an excellent pull request:
+
+1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork,
+   and configure the remotes:
+
+   ```sh
+   # Clone your fork of the repo into the current directory
+   git clone https://github.com/<your-username>/camp3
+   # Navigate to the newly cloned directory
+   cd camp3
+   # Assign the original repo to a remote called "upstream"
+   git remote add upstream https://github.com/renehernandez/camp3
+   ```
+
+2. If you cloned a while ago, get the latest changes from upstream:
+
+   ```bash
+   git checkout master
+   git pull upstream master
+   ```
+
+3. Create a new topic branch (off of `master`) to contain your feature, change,
+   or fix.
+
+   **IMPORTANT**: Making changes in `master` is discouraged. You should always
+   keep your local `master` in sync with upstream `master` and make your
+   changes in topic branches.
+
+   ```sh
+   git checkout -b <topic-branch-name>
+   ```
+
+4. Commit your changes in logical chunks. Keep your commit messages organized,
+   with a short description in the first line and more detailed information on
+   the following lines. Feel free to use Git's
+   [interactive rebase](https://help.github.com/articles/about-git-rebase/)
+   feature to tidy up your commits before making them public.
+
+5. Make sure all the tests are still passing.
+
+   ```sh
+   rake
+   ```
+
+6. Push your topic branch up to your fork:
+
+   ```sh
+   git push origin <topic-branch-name>
+   ```
+
+7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
+    with a clear title and description.
+
+8. If you haven't updated your pull request for a while, you should consider
+   rebasing on master and resolving any conflicts.
+
+   **IMPORTANT**: _Never ever_ merge upstream `master` into your branches. You
+   should always `git rebase` on `master` to bring your changes up to date when
+   necessary.
+
+   ```sh
+   git checkout master
+   git pull upstream master
+   git checkout <your-topic-branch>
+   git rebase master
+   ```
+
+Thank you for your contributions!

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    camp3 (0.0.1)
+    camp3 (0.0.2)
       httparty (~> 0.18)
       rack-oauth2 (~> 1.14)
 

data/README.md

@@ -1,8 +1,6 @@
 # camp3 ![CI](https://github.com/renehernandez/camp3/workflows/CI/badge.svg) [![Gem Version](https://badge.fury.io/rb/camp3.svg)](https://badge.fury.io/rb/camp3)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/camp3`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Camp3 is a Ruby wrapper for the [Basecamp 3 API](https://github.com/basecamp/bc3-api).
 
 ## Installation
 
@@ -14,22 +12,82 @@ gem 'camp3'
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install camp3
+```bash
+$ gem install camp3
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Configuration example:
+
+```ruby
+require 'camp3'
+
+Camp3.configure do |config|
+  config.client_id = ENV['BASECAMP3_CLIENT_ID']
+  config.client_secret = ENV['BASECAMP3_CLIENT_SECRET']
+  config.account_number = ENV['BASECAMP3_ACCOUNT_NUMBER']
+  config.refresh_token = ENV['BASECAMP3_REFRESH_TOKEN']
+  config.access_token = ENV['BASECAMP3_ACCESS_TOKEN']
+end
+```
+
+For more complex examples, we recommend using a client, instead of the top level `Camp3` wrapper. A `client` has a builtin mechanism to retry requests when the access token has expired and update its information (so it will use the new access token instead of the old one), as oppose to the top level `Camp3` which would request a new access token every time a request were to be made.
+
+Example getting list of TODOs:
+
+```ruby
+require 'camp3'
+
+Camp3.configure do |config|
+  config.client_id = ENV['BASECAMP3_CLIENT_ID']
+  config.client_secret = ENV['BASECAMP3_CLIENT_SECRET']
+  config.account_number = ENV['BASECAMP3_ACCOUNT_NUMBER']
+  config.refresh_token = ENV['BASECAMP3_REFRESH_TOKEN']
+  config.access_token = ENV['BASECAMP3_ACCESS_TOKEN']
+end
+
+client = Camp3.client
 
-## Development
+projects = client.projects
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+projects.each do |p|
+  puts "Project: #{p.inspect}"
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+  puts "Todo set: #{p.todoset.inspect}"
+
+  todoset = client.todoset(p)
+
+  client.todolists(todoset).each do |list|
+    puts "Todolist: #{list.title}"
+
+    client.todos(list).each do |todo|
+      puts todo.inspect
+    end
+  end
+end
+```
+
+For more examples, check the [examples](examples/) folder
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/camp3.
+Check out the [Contributing](CONTRIBUTING.md) page.
+
+## Changelog
+
+For inspecting the changes and tag releases, check the [Changelog](CHANGELOG.md) page
+
+## Appreciation
+
+The gem code structure and documentation is based on the awesome [NARKOZ/gitlab gem](https://github.com/narkoz/gitlab)
+
+## License
+
+Checkout the [LICENSE](LICENSE) for details

data/examples/messages.rb

@@ -8,15 +8,17 @@ Camp3.configure do |config|
   config.access_token = ENV['BASECAMP3_ACCESS_TOKEN']
 end
 
-projects = Camp3.projects
+client = Camp3.client
+
+projects = client.projects
 
 projects.each do |p|
   puts "Project: #{p.name}"
 
-  message_board = Camp3.message_board(p)
+  message_board = client.message_board(p)
   puts "Message Board: #{message_board.title}"
 
-  messages = Camp3.messages(message_board)
+  messages = client.messages(message_board)
 
   messages.each do |msg|
     puts msg.inspect

data/examples/oauth.rb

@@ -6,13 +6,15 @@ Camp3.configure do |config|
     config.redirect_uri = ENV['BASECAMP3_REDIRECT_URI']
 end
 
+client = Camp3.client
+
 # Get the authorization uri
-puts Camp3.authorization_uri
+puts client.authorization_uri
 
 # Once you have received the auth code from basecamp, you can proceed with the following step
 # This will update the configuration with the corresponding tokens
 # Store the tokens in a safe place
-token = Camp3.authorize! ENV['BASECAMP3_ACCESS_CODE']
+token = client.authorize! ENV['BASECAMP3_ACCESS_CODE']
 
 # Print refresh token
 puts token.refresh_token

data/examples/todos.rb

@@ -8,19 +8,21 @@ Camp3.configure do |config|
   config.access_token = ENV['BASECAMP3_ACCESS_TOKEN']
 end
 
-projects = Camp3.projects
+client = Camp3.client
+
+projects = client.projects
 
 projects.each do |p|
   puts "Project: #{p.inspect}"
 
   puts "Todo set: #{p.todoset.inspect}"
 
-  todoset = Camp3.todoset(p)
+  todoset = client.todoset(p)
 
-  Camp3.todolists(todoset).each do |list|
+  client.todolists(todoset).each do |list|
     puts "Todolist: #{list.title}"
 
-    Camp3.todos(list).each do |todo|
+    client.todos(list).each do |todo|
       puts todo.inspect
     end
   end

data/lib/camp3.rb

@@ -17,30 +17,6 @@ module Camp3
   extend Logging
   extend Configuration
 
-  # def self.authorize!(auth_code)
-  #   tokens = client.authorize!(auth_code)
-
-  #   Resource.configure(Camp3.access_token)
-
-  #   tokens
-  # end
-
-  # def self.update_access_token!(refresh_token = nil)
-  #   refresh_token = Camp3.refresh_token unless refresh_token
-    
-  #   tokens = client.update_access_token!(refresh_token)
-
-  #   Resource.configure(Camp3.access_token)
-
-  #   tokens
-  # end
-
-  # def self.configure
-  #   yield self
-
-  #   Resource.configure(Camp3.access_token) if Camp3.access_token
-  # end
-
   # Alias for Camp3::Client.new
   #
   # @return [Camp3::Client]

data/lib/camp3/authorization.rb

@@ -59,8 +59,8 @@ module Camp3
     private
 
     def store_tokens(token)
-      Camp3.access_token = token.access_token
-      Camp3.refresh_token = token.refresh_token
+      @access_token = token.access_token
+      @refresh_token = token.refresh_token
     end
   end
 end

data/lib/camp3/client.rb

@@ -2,7 +2,7 @@
 
 module Camp3
   # Wrapper for the Camp3 REST API.
-  class Client < Request
+  class Client
     Dir[File.expand_path('api/*.rb', __dir__)].each { |f| require f }
     
     # Keep in alphabetical order
@@ -23,8 +23,18 @@ module Camp3
       (Configuration::VALID_OPTIONS_KEYS).each do |key|
         send("#{key}=", options[key]) if options[key]
       end
+    end
+
+    %w[get post put delete].each do |method|
+      define_method method do |path, options = {}|
+        response, result = new_request.send(method, path, options)
+        return response unless result == Request::Result::AccessTokenExpired
+
+        update_access_token!
 
-      self.class.headers 'User-Agent' => user_agent
+        response, _ = new_request.send(method, path, options)
+        response
+      end
     end
 
     # Text representation of the client, masking private token.
@@ -46,6 +56,10 @@ module Camp3
 
     private
 
+    def new_request
+      Request.new(@access_token, @user_agent)
+    end
+
     def only_show_last_four_chars(token)
       "#{'*' * (token.size - 4)}#{token[-4..-1]}"
     end

data/lib/camp3/request.rb

@@ -6,10 +6,21 @@ module Camp3
   # @private
   class Request
     include HTTParty
-    format :plain
+    format :json
     headers 'Accept' => 'application/json'
+    parser(proc { |body, _| parse(body) })
 
-    attr_accessor :access_token
+    module Result
+      AccessTokenExpired = 'AccessTokenExpired'
+
+      Valid = 'Valid'
+    end
+
+    def initialize(access_token, user_agent)
+      @access_token = access_token
+
+      self.class.headers 'User-Agent' => user_agent
+    end
 
     # Converts the response body to a Resource.
     def self.parse(body)
@@ -32,44 +43,69 @@ module Camp3
 
     # Decodes a JSON response into Ruby object.
     def self.decode(response)
-      response ? JSON.parse(response) : {}
+      response ? JSON.load(response) : {}
     rescue JSON::ParserError
       raise Error::Parsing, 'The response is not a valid JSON'
     end
 
     %w[get post put delete].each do |method|
       define_method method do |path, options = {}|
-        override_path = options.delete(:override_path)
         params = options.dup
-
+        override_path = params.delete(:override_path)
+        
         params[:headers] ||= {}
-        params[:headers].merge!(authorization_header)
 
         full_endpoint = override_path ? path : Camp3.api_endpoint + path
 
-        validate self.class.send(method, full_endpoint, params)
+        execute_request(method, full_endpoint, params)
       end
     end
 
+    private
+
+    # Executes the request
+    def execute_request(method, endpoint, params)
+      params[:headers].merge!(authorization_header)
+      
+      Camp3.logger.debug("Method: #{method}; URL: #{endpoint}")
+      response, result = validate self.class.send(method, endpoint, params)
+
+      response = extract_parsed(response) if result == Result::Valid
+
+      return response, result
+    end
+
     # Checks the response code for common errors.
-    # Returns parsed response for successful requests.
+    # Informs that a retry needs to happen if request failed due to access token expiration
+    # @raise [Error::ResponseError] if response is an HTTP error
+    # @return [Response, Request::Result]
     def validate(response)
       error_klass = Error::STATUS_MAPPINGS[response.code]
+
+      if error_klass == Error::Unauthorized && response.parsed_response.error.include?("OAuth token expired (old age)")
+        Camp3.logger.debug("Access token expired. Please obtain a new access token")
+        return response, Result::AccessTokenExpired
+      end
+
       raise error_klass, response if error_klass
 
-      parsed = self.class.parse(response)
+      return response, Result::Valid
+    end
+
+    def extract_parsed(response)
+      parsed = response.parsed_response
+      
       parsed.client = self if parsed.respond_to?(:client=)
       parsed.parse_headers!(response.headers) if parsed.respond_to?(:parse_headers!)
+
       parsed
     end
 
-    private
-
     # Returns an Authorization header hash
     #
     # @raise [Error::MissingCredentials] if access_token and auth_token are not set.
     def authorization_header
-      raise Error::MissingCredentials, 'Please provide a access_token' unless @access_token
+      raise Error::MissingCredentials, 'Please provide a access_token' if @access_token.to_s.empty?
 
       { 'Authorization' => "Bearer #{@access_token}" }
     end

data/lib/camp3/resource.rb

@@ -62,9 +62,8 @@ module Camp3
     end
 
     def self.detect_type(url)
-      Camp3.logger.debug "Request URL: #{url}" 
       case url
-      when /#{Camp3.api_endpoint}\/projects\/\d+\.json/
+      when /#{Camp3.base_api_endpoint}\/\d+\/projects\/\d+\.json/
         return Project
       else
         return Resource

data/lib/camp3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Camp3
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: camp3
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - renehernandez
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-07 00:00:00.000000000 Z
+date: 2020-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -82,6 +82,8 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".ruby-version"
+- CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
 - LICENSE