drone-ci 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32b1b7687a34f96c1f5fb7d9874e812d863a6908d4a71c0fe8ba9f7caf43be87
-  data.tar.gz: 968b4778d5e9bbf0313c9d4cffe0065ef6bff6df0e6fd5f868424942e2002429
+  metadata.gz: 9f484658c0d071dcfba3fda2385534c52034879bb62619eb1261a6356963d451
+  data.tar.gz: 65471e81f6ccc0fdc7baa34bb5c50fd953a2c60c72c0775e9878ac6bd2a49992
 SHA512:
-  metadata.gz: e2724927033b7b82438f18dcdf80577a07be0aad50f72ba6f0ff0b1c1d62f91e3b215e8337a119b88d284442c614d5ae10fa3b8e266d149c4c667ba259d13718
-  data.tar.gz: 2323cdc13b445b43b510dd3538bced63c77487606b6057b77ec3bb400860f213d77b9d6ad6dfa70f7540c62ceb4dbca19a06478798b643464eb41814047cf857
+  metadata.gz: b75bb62ad76c510c73282e4721bc145676fe3d9c4e8fda654c6f15b4c081ff88952d961a285c588b6a87c188f0edb54395eee268eed9858abdb48d64229302c4
+  data.tar.gz: a28baf3eaff5723e9ae2c5c516c26b2424774059ac187a4bd90f887ae1e78c132c5ac9a19f987654bd06073b752e6357fd7f621793e7d9776353ab5c4866547e

data/.github/workflows/gem-push.yml

@@ -38,6 +38,7 @@ jobs:
         files: |
           *.gem
           LICENSE.txt
+          CHANGELOG.md
 #     - name: Publish to RubyGems
 #       run: |
 #         mkdir -p $HOME/.gem

data/.gitignore

@@ -1,2 +1,3 @@
 .bundle
 Gemfile.lock
+*.gem

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+0.2.0
+
+- (feature) add undocumented params to BuildsAPI#build_list: `page`, `per_page`
+- (feature) add undocumented param to ReposAPI#repo_delete: `remove`
+- (feature) add undocumented params to ReposAPI#repo_list: `page`, `per_page`
+- (feature) add undocumented endpoint to UserAPI: `user_token`
+- (dependency) update octokit from `~> 5.5` to `~> 5.6`
+
+  0.1.1
+
+- (feature) Added documentation to API methods.
+- (fix) removed required but unused argument from ReposAPI#repo_list
+- (fix) ReposAPI#repo_create now actually uses the arguments given... :sweat_smile:
+
+  0.1.0
+
+- Initial Release

data/drone-ci.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |gem|
   # gem.signing_key   = File.expand_path ENV.fetch 'GEM_SIGNING_KEY'
 
   if ENV['HACKING']
-    gem.version     = '0.0.0-pre'
+    gem.version     = '0.0.0'
     gem.files       = Dir.glob('**')
     gem.executables = Dir.glob('bin/*')
   else
@@ -28,12 +28,12 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency 'faraday',        '~> 2.5', '>= 2.5.2'
   gem.add_runtime_dependency 'faraday-retry',  '~> 2.0'
   gem.add_runtime_dependency 'httpx',          '~> 0.21.0'
-  gem.add_runtime_dependency 'octokit',        '~> 5.4'
+  gem.add_runtime_dependency 'octokit',        '~> 5.6'
 
   gem.add_development_dependency 'pry',        '~> 0.14.1'
   gem.add_development_dependency 'pry-doc',    '~> 1.3'
   gem.add_development_dependency 'rubocop',    '~> 1.35'
-  gem.add_development_dependency 'solargraph', '~> 0.45.0'
+  gem.add_development_dependency 'solargraph', '~> 0.46.0'
   gem.add_development_dependency 'yard',       '~> 0.9.28'
   gem.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/drone-ci/api/builds.rb

@@ -2,12 +2,20 @@
 
 module DroneCI
   module BuildsAPI
-    # https://docs.drone.io/api/builds/build_approve/
+    # Approves a blocked build.
+    #
+    # Please note this api requires write access to the repository, and the request parameter {build} is not the build id but the build number.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_approve/
     def build_approve(owner, repo, build)
       api.post("repos/#{owner}/#{repo}/builds/#{build}/approve")
     end
 
-    # https://docs.drone.io/api/builds/build_create/
+    # Create a build using the latest commit for the specified branch.
+    #
+    # Please note the resulting build is created with event type `custom`.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_create/
     def build_create(namespace, name, branch: nil, commit: nil, **params)
       api.post("repos/#{namespace}/#{name}/builds") do |request|
         { branch: branch, commit: commit }.merge(params).compact.transform_keys(&:to_s).each do |key, value|
@@ -16,43 +24,80 @@ module DroneCI
       end
     end
 
-    # https://docs.drone.io/api/builds/build_decline/
+    # Declines a blocked build.
+    #
+    # Please note this api requires write access to the repository, and the request parameter {build} is not the build id but the build number.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_decline/
     def build_decline(owner, repo, build)
       api.post("repos/#{owner}/#{repo}/builds/#{build}/decline")
     end
 
-    # https://docs.drone.io/api/builds/build_info/
+    # Returns the specified repository build.
+    #
+    # Please note this api requires read access to the repository and the request parameter {build} is not the build id but the build number.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_info/
     def build_info(owner, repo, build)
       api.get("repos/#{owner}/#{repo}/builds/#{build}")
     end
 
-    # https://docs.drone.io/api/builds/build_list/
-    def build_list(owner, repo)
-      api.get("repos/#{owner}/#{repo}/builds")
+    # Returns recent builds for the repository based on name.
+    #
+    # Please note this api requires read access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_list/
+    def build_list(owner, repo, branch: nil, tag: nil, page: 1, per_page: 25)
+      api.get("repos/#{owner}/#{repo}/builds") do |request|
+        {
+          branch: branch,
+          commit: commit,
+          page: page,
+          per_page: [[per_page, 1].max, 100].min, # https://github.com/harness/drone/blob/cbfd342333ffa4b2fe76b7e8948235efd3535fac/handler/api/repos/builds/list.go#L45-L47
+        }.compact.transform_keys(&:to_s).each do |key, value|
+          request.params[key] = value
+        end
+      end
     end
 
-    # https://docs.drone.io/api/builds/build_logs/
+    # Please note this api requires read access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_logs/
     def build_logs(owner, repo, build, stage, step)
       api.get("repos/#{owner}/#{repo}/builds/#{build}/logs/#{stage}/#{step}")
     end
 
-    # https://docs.drone.io/api/builds/build_promote/
-    def build_promote(owner, repo, build, target:, **params)
+    # Promote the specified build number to the target environment.
+    #
+    # If given, additional (custom) parameters will be available to your pipeline steps as environment variables.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_promote/
+    def build_promote(owner, repo, build, target:)
       api.post("repos/#{owner}/#{repo}/builds/#{build}") do |request|
-        { target: target }.merge(params).compact.transform_keys(&:to_s).each do |key, value|
+        { target: target }.compact.transform_keys(&:to_s).each do |key, value|
           request.params[key] = value
         end
       end
     end
 
-    # https://docs.drone.io/api/builds/build_start/
+    # Restart the specified build.
+    #
+    # Please note this api requires read and write access to the repository and the request parameter {build} is not the build id but the build number.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_start/
     def build_start(owner, repo, build)
       api.post("repos/#{owner}/#{repo}/builds/#{build}")
     end
 
     alias build_restart build_start
 
-    # https://docs.drone.io/api/builds/build_stop/
+    # Stop the specified build.
+    #
+    # Please note this api requires administrative privileges and the request parameter {build} is not the build id but the build number.
+    #
+    # Reference: https://docs.drone.io/api/builds/build_stop/
     def build_stop(owner, repo, build)
       api.delete("repos/#{owner}/#{repo}/builds/#{build}")
     end

data/lib/drone-ci/api/cron.rb

@@ -2,32 +2,56 @@
 
 module DroneCI
   module CronAPI
-    # https://docs.drone.io/api/cron/cron_create/
+    # Create a new cron job.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/cron/cron_create/
     def cron_create(owner, repo, **body)
       api.post("repos/#{owner}/#{repo}/cron", body)
     end
 
-    # https://docs.drone.io/api/cron/cron_delete/
+    # Deletes a cron job.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/cron/cron_delete/
     def cron_delete(owner, repo, name)
       api.delete("repos/#{owner}/#{repo}/cron/#{name}")
     end
 
-    # https://docs.drone.io/api/cron/cron_info/
+    # Returns the named cron job.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/cron/cron_info/
     def cron_info(owner, repo, name)
       api.get("repos/#{owner}/#{repo}/cron/#{name}")
     end
 
-    # https://docs.drone.io/api/cron/cron_list/
+    # Returns the cron job list.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/cron/cron_list/
     def cron_list(owner, repo)
       api.get("repos/#{owner}/#{repo}/cron")
     end
 
-    # https://docs.drone.io/api/cron/cron_trigger/
+    # Trigger an existing cron task.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/cron/cron_trigger/
     def cron_trigger(owner, repo, name)
       api.post("repos/#{owner}/#{repo}/cron/#{name}")
     end
 
-    # https://docs.drone.io/api/cron/cron_update/
+    # Updates the named cron job.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/cron/cron_update/
     def cron_update(owner, repo, name, **body)
       api.patch("repos/#{owner}/#{repo}/cron/#{name}", body)
     end

data/lib/drone-ci/api/repos.rb

@@ -2,43 +2,77 @@
 
 module DroneCI
   module ReposAPI
-    # https://docs.drone.io/api/repos/repo_chown/
+    # Lets a user assume ownership of a named repository.
+    #
+    # Please note this api requires administrative access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_chown/
     def repo_chown(owner, repo)
       api.post("repos/#{owner}/#{repo}/chown")
     end
 
-    # https://docs.drone.io/api/repos/repo_delete/
-    def repo_delete(owner, repo)
-      api.delete("repos/#{owner}/#{repo}")
+    # Permanently deletes a repository. It cannot be undone.
+    #
+    # Please note this api requires administrative access to the repository, and repository’s secrets and builds aren’t deleted.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_delete/
+    def repo_delete(owner, repo, remove: nil)
+      api.delete("repos/#{owner}/#{repo}") do |request|
+        { remove: remove }.compact.transform_keys(&:to_s).each do |key, value|
+          request[key] = value
+        end
+      end
     end
 
     alias repo_disable repo_delete
 
-    # https://docs.drone.io/api/repos/repo_create/
-    def repo_create(owner, _name)
-      api.post("repos/#{owner}/#{repo}")
+    # Registers a named repository with Drone.
+    #
+    # Please note this api requires administrative access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_create/
+    def repo_create(owner, name)
+      api.post("repos/#{owner}/#{name}")
     end
 
     alias repo_enable repo_create
 
-    # https://docs.drone.io/api/repos/repo_info/
+    # Retrieves the details of a repository.
+    #
+    # Please note this api requires read access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_info/
     def repo_info(owner, repo)
       api.get("repos/#{owner}/#{repo}")
     end
 
-    # https://docs.drone.io/api/repos/repo_list/
+    # Returns repositories which are registered to Drone.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_list/
     # the docs are wrong, they say this is at api/user/repos, but the source code says...
     # https://github.com/harness/drone/blob/2d45d90cdd5cf2ec0e8dbcce2ea6bc340ce1e67e/handler/api/api.go#L173-L182
-    def repo_list(_owner)
-      api.get('repos')
+    def repo_list(page: 1, per_page: 25)
+      api.get('repos') do |request|
+        { page: page, per_page: per_page }.compact.transform_keys(&:to_s).each do |key, value|
+          request[key] = value
+        end
+      end
     end
 
-    # https://docs.drone.io/api/repos/repo_repair/
+    # Recreates webhooks for your repository in your version control system (e.g GitHub). This can be used if you accidentally delete your webhooks.
+    #
+    # Please note this api requires administrative access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_repair/
     def repo_repair(owner, repo)
       api.post("repos/#{owner}/#{repo}/repair")
     end
 
-    # https://docs.drone.io/api/repos/repo_update/
+    # Updates a named repository.
+    #
+    # Please note this api requires administrative access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/repos/repo_update/
     def repo_update(owner, repo, **body)
       api.patch("repos/#{owner}/#{repo}", body)
     end

data/lib/drone-ci/api/secrets.rb

@@ -2,27 +2,47 @@
 
 module DroneCI
   module SecretsAPI
-    # https://docs.drone.io/api/secrets/secret_create/
+    # Create a new repository secret.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/secrets/secret_create/
     def secret_create(owner, repo, **body)
       api.post("repos/#{owner}/#{repo}/secrets", body)
     end
 
-    # https://docs.drone.io/api/secrets/secret_delete/
+    # Deletes a repository secret.
+    #
+    # Please note this api requires write access to the repository, and the request parameter {secret} is not the secret’s id but secret name.
+    #
+    # Reference: https://docs.drone.io/api/secrets/secret_delete/
     def secret_delete(owner, repo, secret)
       api.post("repos/#{owner}/#{repo}/secrets/#{secret}")
     end
 
-    # https://docs.drone.io/api/secrets/secret_info/
+    # Returns the repository secret.
+    #
+    # Please note this api requires write access to the repository, and the request parameter {secret} is not the secret’s id but secret name.
+    #
+    # Reference: https://docs.drone.io/api/secrets/secret_info/
     def secret_info(owner, repo, secret)
       api.get("repos/#{owner}/#{repo}/secrets/#{secret}")
     end
 
-    # https://docs.drone.io/api/secrets/secret_list/
+    # Returns the repository secret list.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/secrets/secret_list/
     def secret_list(owner, repo)
       api.get("repos/#{owner}/#{repo}/secrets")
     end
 
-    # https://docs.drone.io/api/secrets/secret_update/
+    # Updates the specified repository secret.
+    #
+    # Please note this api requires write access to the repository, and the request parameter {secret} is not the secret’s id but secret name.
+    #
+    # Reference: https://docs.drone.io/api/secrets/secret_update/
     def secret_update(owner, repo, secret, **body)
       api.patch("repos/#{owner}/#{repo}/secrets/#{secret}", body)
     end

data/lib/drone-ci/api/templates.rb

@@ -2,27 +2,47 @@
 
 module DroneCI
   module TemplatesAPI
-    # https://docs.drone.io/api/templates/template_create/
+    # Create a new template.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/templates/template_create/
     def template_create(namespace, **body)
       api.post("templates/#{namespace}", body)
     end
 
-    # https://docs.drone.io/api/templates/template_delete/
+    # Deletes a template.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/templates/template_delete/
     def template_delete(namespace, name)
       api.delete("templates/#{namespace}/#{name}")
     end
 
-    # https://docs.drone.io/api/templates/template_info/
+    # Returns the template.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/templates/template_info/
     def template_info(namespace, name)
       api.get("templates/#{namespace}/#{name}")
     end
 
-    # https://docs.drone.io/api/templates/template_list/
+    # Returns the organization template list.
+    #
+    # Please note this api requires write access to the repository.
+    #
+    # Reference: https://docs.drone.io/api/templates/template_list/
     def template_list(namespace)
       api.get("templates/#{namespace}")
     end
 
-    # https://docs.drone.io/api/templates/template_update/
+    # Updates the specified repository secret.
+    #
+    # Please note this api requires write access to the repository, and the request parameter {secret} is not the secret’s id but secret name.
+    #
+    # Reference: https://docs.drone.io/api/templates/template_update/
     def template_update(namespace, name, **body)
       api.patch("templates/#{namespace}/#{name}", body)
     end

data/lib/drone-ci/api/user.rb

@@ -2,17 +2,25 @@
 
 module DroneCI
   module UserAPI
-    # https://docs.drone.io/api/user/user_builds/
+    # Returns the currently authenticated user’s build feed.
+    #
+    # Reference: https://docs.drone.io/api/user/user_builds/
     def user_builds
       api.get('user/builds')
     end
 
-    # https://docs.drone.io/api/user/user_info/
+    # Returns the currently authenticated user.
+    #
+    # Reference: https://docs.drone.io/api/user/user_info/
     def user_info
       api.get('user')
     end
 
-    # https://docs.drone.io/api/user/user_repos/
+    # Returns the currently authenticated user’s repository list.
+    #
+    # Optionally, include the latest build for each active repository.
+    #
+    # Reference: https://docs.drone.io/api/user/user_repos/
     def user_repos(latest: nil)
       api.get('user/repos') do |request|
         { latest: latest }.compact.each do |key, value|
@@ -21,9 +29,27 @@ module DroneCI
       end
     end
 
-    # https://docs.drone.io/api/user/user_sync/
-    def user_sync
-      api.post('user/repos')
+    # Synchronize the currently authenticated user’s repository list.
+    #
+    # Reference: https://docs.drone.io/api/user/user_sync/
+    def user_sync(async: nil)
+      api.post('user/repos') do |request|
+        { async: async }.compact.each do |key, value|
+          request.params[key] = value
+        end
+      end
+    end
+
+    # Undocumented endpoint.
+    #
+    # Route Reference: https://github.com/harness/drone/blob/master/handler/api/api.go#L324
+    # Code Reference: https://github.com/harness/drone/blob/master/handler/api/user/token.go
+    def user_token(rotate: nil)
+      api.post('user/token') do |request|
+        { rotate: rotate }.compact.each do |key, value|
+          request.params[key] = value
+        end
+      end
     end
   end
 end

data/lib/drone-ci/api/users.rb

@@ -2,27 +2,47 @@
 
 module DroneCI
   module UsersAPI
-    # https://docs.drone.io/api/users/users_create/
+    # Creates a user.
+    #
+    # Please note this api requires administrative privileges.
+    #
+    # Reference: https://docs.drone.io/api/users/users_create/
     def users_create(**body)
       api.post('users', body)
     end
 
-    # https://docs.drone.io/api/users/users_delete/
+    # Deletes a user.
+    #
+    # Please note this api requires administrative privileges.
+    #
+    # Reference: https://docs.drone.io/api/users/users_delete/
     def users_delete(login)
       api.delete("users/#{login}")
     end
 
-    # https://docs.drone.io/api/users/users_info/
+    # Returns information about the named registered user.
+    #
+    # Please note this api requires administrative privileges.
+    #
+    # Reference: https://docs.drone.io/api/users/users_info/
     def users_info(login)
       api.get("users/#{login}")
     end
 
-    # https://docs.drone.io/api/users/users_list/
+    # Returns a list of all registered users.
+    #
+    # Please note this api requires administrative privileges.
+    #
+    # Reference: https://docs.drone.io/api/users/users_list/
     def users_list
       api.get('users')
     end
 
-    # https://docs.drone.io/api/users/users_update/
+    # Updates the specified user.
+    #
+    # Please note this api requires administrative privileges.
+    #
+    # Reference: https://docs.drone.io/api/users/users_update/
     def users_update(login, **body)
       api.patch("users/#{login}", body)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: drone-ci
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chris Olstrom
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-10 00:00:00.000000000 Z
+date: 2022-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -64,14 +64,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.4'
+        version: '5.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.4'
+        version: '5.6'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -120,14 +120,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.45.0
+        version: 0.46.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.45.0
+        version: 0.46.0
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -154,6 +154,7 @@ files:
 - ".github/workflows/gem-push.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md