labclient 0.1.0

data/lib/labclient/notes/snippets/update.rb

@@ -0,0 +1,32 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class SnippetNotes < Common
+    doc 'Snippets' do
+      title 'Update'
+      desc 'Get a single project snippet. [Project ID, Snippet ID, Note ID]'
+      example 'client.notes.snippets.update(16, 1, 43, "Updaaate")'
+      result <<~DOC
+        => #<Note id: 43, type: Snippet>
+      DOC
+    end
+
+    doc 'Snippets' do
+      markdown <<~DOC
+        | Attribute  | Type   | Required | Description |
+        | ---------  | ----   | -------- | ----------- |
+        | body       | string | yes | Name for Badge |
+      DOC
+    end
+
+    # Show
+    def update(project_id, snippet_id, note_id, body)
+      project_id = format_id(project_id)
+      snippet_id = format_id(snippet_id)
+      note_id = format_id(note_id)
+      query = { body: body }
+
+      client.request(:put, "projects/#{project_id}/snippets/#{snippet_id}/notes/#{note_id}", Note, query)
+    end
+  end
+end

data/lib/labclient/notifications/list.rb

@@ -0,0 +1,54 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class Notifications < Common
+    doc '' do
+      subtitle 'Levels & Custom'
+
+      markdown <<~DOC
+        For each global/group/project a specific level, or custom settings can be specified.
+
+        See [docs](https://docs.gitlab.com/ee/api/notification_settings.html#valid-notification-levels) on valid levels and custom settings.
+      DOC
+    end
+
+    doc 'List' do
+      desc 'Get current notification settings and email address.'
+      example 'client.notifications.list_global'
+      result <<~DOC
+        => {:level=>"watch", :notification_email=>"admin@labclient.com"}
+      DOC
+    end
+
+    doc 'List' do
+      desc 'List Alias'
+      example 'client.notifications.list'
+    end
+
+    def list_global
+      client.request(:get, 'notification_settings')
+    end
+
+    alias list list_global
+
+    doc 'List' do
+      desc 'Get group notification settings. [Group ID]'
+      example 'client.notifications.list_group(5)'
+    end
+
+    def list_group(group_id)
+      group_id = format_id(group_id)
+      client.request(:get, "groups/#{group_id}/notification_settings")
+    end
+
+    doc 'List' do
+      desc 'Get project notification settings. [Project ID]'
+      example 'client.notifications.list_project(16)'
+    end
+
+    def list_project(project_id)
+      project_id = format_id(project_id)
+      client.request(:get, "projects/#{project_id}/notification_settings")
+    end
+  end
+end

data/lib/labclient/notifications/update.rb

@@ -0,0 +1,64 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class Notifications < Common
+    doc 'Update' do
+      desc 'Get a namespace by ID. [Hash]'
+      example 'client.notifications.update_global(level: :watch)'
+      result <<~DOC
+        => {:level=>"watch", :notification_email=>"admin@labclient.com"}
+      DOC
+    end
+
+    def update_global(query)
+      client.request(:put, 'notification_settings', nil, query)
+    end
+
+    alias update update_global
+
+    doc 'Update' do
+      desc 'Update Group [Group ID, Hash]'
+      example 'client.notifications.update_group(5, level: :mention)'
+    end
+
+    def update_group(group_id, query)
+      group_id = format_id(group_id)
+      client.request(:put, "groups/#{group_id}/notification_settings", nil, query)
+    end
+
+    doc 'Update' do
+      desc 'Update Project [Project ID, Hash'
+      example 'client.notifications.update_project(16, level: :custom)'
+
+      result <<~DOC
+           OpenStruct {
+             :level => "custom",
+            :events => OpenStruct {
+                           :new_release => nil,
+                              :new_note => nil,
+                             :new_issue => nil,
+                          :reopen_issue => nil,
+                           :close_issue => nil,
+                        :reassign_issue => nil,
+                             :issue_due => nil,
+                     :new_merge_request => nil,
+                 :push_to_merge_request => nil,
+                  :reopen_merge_request => nil,
+                   :close_merge_request => nil,
+                :reassign_merge_request => nil,
+                   :merge_merge_request => nil,
+                       :failed_pipeline => true,
+                        :fixed_pipeline => true,
+                      :success_pipeline => nil,
+                              :new_epic => nil
+            }
+        }
+      DOC
+    end
+
+    def update_project(project_id, query)
+      project_id = format_id(project_id)
+      client.request(:put, "projects/#{project_id}/notification_settings", nil, query)
+    end
+  end
+end

data/lib/labclient/open_struct.rb

@@ -0,0 +1,14 @@
+# Extend OpenStruct
+class OpenStruct
+  def keys
+    to_h.keys.sort
+  end
+
+  def inspect
+    to_h.inspect
+  end
+
+  def as_json(*args)
+    super.as_json['table']
+  end
+end

data/lib/labclient/overview.rb

@@ -0,0 +1,243 @@
+# The glorious gitlab labclient of labs
+# rubocop:disable Metrics/ClassLength
+module LabClient
+  # Helper for Docs
+  class Overview
+    extend Docs
+
+    doc 'Overview' do
+      title 'About'
+      desc <<~DOC
+        Labclient is another Gitlab API Gem. A focus on ease of use and helpers and snippets.
+
+        <a href="https://github.com/NARKOZ/gitlab">Gitlab</a> is an excellent gem, and is nearly complete in its implementation. While this is still a work in progress and you are looking for general use you should use it.
+      DOC
+    end
+
+    doc 'Overview' do
+      title 'Setup'
+      desc 'Install from RubyGems'
+      example 'gem install labclient'
+    end
+
+    doc 'Overview' do
+      title 'Initialize Client'
+      example <<~DOC
+        client = LabClient::Client.new(
+          url: 'https://gitlab.labclient',
+          token: 'gitlab api token',
+          ssl_verify: false
+        )
+      DOC
+    end
+
+    doc 'Authentication' do
+      title 'Credentials File'
+      desc 'The client will use ~/.gitlab-labclient for credentials. Configuring this will automatically setup client'
+      example <<~DOC
+        {
+          "url": "https://labclient",
+          "token": "super_secure",
+          "ssl_verify": false,
+          "paginate": false
+        }
+      DOC
+    end
+
+    doc 'Authentication' do
+      title 'Environment Variables'
+      desc 'If not provided, and credentials file does not exist will attempt to use ENV variables'
+      example <<~DOC
+        LABCLIENT_URL='http://gitlab.com'
+        LABCLIENT_TOKEN='superAwesomeToken'
+        client = LabClient::Client.new
+      DOC
+    end
+
+    doc 'Pagination' do
+      desc 'Pagination is enabled by default if not specified. Can be explicitly enabled or disabled'
+      example <<~DOC
+        client = LabClient::Client.new(
+          url: 'https://gitlab.labclient',
+          token: 'gitlab api token',
+          paginate: false
+        )
+      DOC
+    end
+
+    doc 'Pagination' do
+      title 'auto_paginate'
+      desc 'Automatically collect and return all results for a query. Accepts block'
+      example 'client.users.list.auto_paginate'
+      result <<~DOC
+        [
+          #<User id: 56, username: leonardmccoy>,
+          #<User id: 55, username: harrykim>,
+          #<User id: 54, username: princehumperdinck>,
+          #<User id: 53, username: yorick>,
+          #<User id: 52, username: anivia>,
+          ...
+        ]
+      DOC
+    end
+
+    doc 'Pagination' do
+      markdown '`auto_paginate` with a block'
+      example <<~DOC
+        client.users.list.auto_paginate do |page|
+          puts page.length
+        end
+      DOC
+
+      result <<~DOC
+        20
+        20
+        16
+      DOC
+    end
+
+    doc 'Pagination' do
+      title 'each_page'
+      markdown 'Similar with `auto_paginate`, you can call `each_page` directly'
+      example <<~DOC
+        client.users.list.each_page do |page|
+          puts page.length
+        end
+      DOC
+
+      result <<~DOC
+        20
+        20
+        16
+      DOC
+    end
+
+    doc 'Pagination' do
+      title 'paginate_with_limit'
+      desc 'Iterate through pages, but end when a certain limit is reached'
+      example <<~DOC
+        client.users.list.paginate_with_limit(25)
+      DOC
+
+      result <<~DOC
+        # 5 API Calls, 5 Results per page
+        users = client.users.list(per_page: 5).paginate_with_limit(25)
+        users.length
+        => 25
+      DOC
+    end
+
+    doc 'Pagination' do
+      desc 'Iterate through pages with a block'
+      example <<~DOC
+        client.users.list.paginate_with_limit(25) do |page|
+          puts page.length
+        end
+      DOC
+
+      result <<~DOC
+        # 5 API Calls, 5 Results per page
+        users = client.users.list(per_page: 5).paginate_with_limit(25)
+        users.length
+        => 25
+      DOC
+    end
+
+    doc 'Other' do
+      title 'Common Helpers'
+      markdown <<~DOC
+        The main api namespaces have a `help` and an `api_methods` methods. These will print out available methods and examples
+      DOC
+
+      result <<~DOC
+        client.help
+        client.api_methods
+
+        client.projects.api_methods
+        # => [:show, :list, :create]
+
+        client.users.help
+        Users
+          Available Methods
+            - list show
+
+        List
+          - client.users.list
+          - client.users.list(username: "rakan")
+          - client.users.list(search: "Sid")
+          - client.users.list(active: true)
+
+        User
+          - client.users.show(5)
+          - client.users.show(5)
+      DOC
+    end
+
+    doc 'Other' do
+      title 'Object IDs'
+
+      markdown <<~DOC
+        LabClient will automatically escape Project ID parameters that are namespaces. [More info](https://docs.gitlab.com/ee/api/README.html#namespaced-path-encoding)
+
+        This lets you pass Project ID parameters in several ways.
+      DOC
+
+      example <<~DOC
+        client.projects.show(16)
+        client.projects.show('16')
+        client.projects.show('group/project')
+      DOC
+    end
+
+    doc 'Other' do
+      desc 'Or pass LabClient Objects into API Calls'
+
+      example <<~DOC
+        project = client.projects.show(16)
+        client.commits.list project
+        # => Project Commits
+      DOC
+    end
+
+    doc 'Other' do
+      title 'Docker'
+      desc 'A docker image is created from master and can be used to execute snippets or load a quick pry session'
+
+      example 'docker run -it registry.gitlab.com/labclient/labclient'
+
+      result <<~DOC
+        # Run Container
+        docker run -it -e LABCLIENT_URL="https://labclient" -e LABCLIENT_TOKEN="token" registry.gitlab.com/labclient/labclient
+
+        client = LabClient::Client.new
+        client.users.list
+      DOC
+    end
+
+    doc 'Other' do
+      title 'Curl'
+      desc 'Sometimes you just wana have a curl example to test or send someone'
+      markdown <<~DOC
+        This will attempt to make a curl request from a generated request/response. **Note** this will include the private token!
+      DOC
+
+      example <<~DOC
+        list = client.users.list # Get output
+        list.curl # Show Curl
+      DOC
+
+      result <<~DOC
+        curl -k -H "Private-Token: super_secret_token" -H "Accept: application/json" "https://labclient/api/v4/users?"
+      DOC
+    end
+
+    doc 'Other' do
+      title 'Useful Links'
+      markdown <<~DOC
+        - [Gitlab API Docs](https://docs.gitlab.com/ee/api/)
+        - [API Authentication](https://docs.gitlab.com/ee/api/README.html#authentication)
+      DOC
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/labclient/paginated_response.rb

@@ -0,0 +1,115 @@
+module LabClient
+  # Additional Pagination Support
+  # First page is always request prior to this class being instantiated
+  class PaginatedResponse
+    include CurlHelper
+
+    attr_accessor :client, :response, :array
+
+    def initialize(klass, response, client)
+      @klass = klass
+      @response = response
+      @client = client
+
+      @array = response.data.map { |entry| process_entry(entry, response) }
+
+      auto_paginate if client.settings[:paginate]
+    end
+
+    def inspect
+      @array
+    end
+
+    def method_missing(name, *args, &block)
+      if @array.respond_to?(name)
+        @array.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def help
+      puts <<~DOC
+        Pagination Helper Methods
+          auto_paginate
+            Automatically collect and return all results for a query. Accepts block
+          paginate_with_limit
+            Iterate through pages, but end when a certain limit is reached
+          each_page
+            Similar with auto_paginate, you can call each_page directly
+      DOC
+    end
+
+    def respond_to_missing?(method_name, include_private = false); end
+
+    def each_page(&block)
+      yield @array # This will eventually be the whole list
+      auto_paginate(&block)
+    end
+
+    def auto_paginate(&block)
+      yield @array if block_given?
+
+      loop do
+        break unless next_page?
+
+        next_page(&block)
+      end
+
+      @array
+    end
+
+    # Paginate to a limit
+    def paginate_with_limit(limit, &block)
+      yield @array if block_given?
+
+      loop do
+        break unless next_page?
+        break if @array.length >= limit
+
+        next_page(&block)
+      end
+
+      @array
+    end
+
+    # Check for and store next page
+    def next_page?
+      text = @response.headers['link']&.split(',')&.find { |x| x.include? 'next' }
+      return nil if text.nil?
+
+      @link = link_regex.match(text.strip)[1]
+
+      return false if @link.nil?
+
+      true
+    end
+
+    def link_regex
+      /<([^>]+)>; rel=\"([^\"]+)\"/
+    end
+
+    def next_page
+      return false unless next_page?
+
+      @response = client.http.request(:get, @link)
+
+      raise LabClient::Error.new(@response), @response.friendly_error unless @response.success?
+
+      results = process
+      @array.concat results
+      yield results if block_given?
+    end
+
+    # Create Class Objects
+    def process_entry(entry, entry_response)
+      @klass ? @klass.new(entry, entry_response, client) : entry
+    end
+
+    def process
+      @response.data.map do |entry|
+        process_entry(entry, @response)
+      end
+    end
+  end
+end

data/lib/labclient/pipelines/cancel.rb

@@ -0,0 +1,34 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class Pipelines < Common
+    doc 'Cancel' do
+      desc 'Cancel jobs in a pipeline. [Project ID, Pipeline ID]'
+      example 'client.pipelines.cancel(264, 7)'
+      result '#<Pipeline id: 10, ref: master, status: canceled>'
+    end
+
+    doc 'Cancel' do
+      desc 'Via Project'
+      example <<~DOC
+        project = client.projects.show(5)
+        project.pipeline_cancel(7)
+      DOC
+    end
+
+    doc 'Cancel' do
+      desc 'Via Pipeline'
+      example <<~DOC
+        pipeline = client.pipelines.show(264,7)
+        pipeline.cancel
+      DOC
+    end
+
+    def cancel(project_id, pipeline_id)
+      project_id = format_id(project_id)
+      pipeline_id = format_id(pipeline_id)
+
+      client.request(:post, "projects/#{project_id}/pipelines/#{pipeline_id}/cancel", Pipeline)
+    end
+  end
+end

data/lib/labclient/pipelines/create.rb

@@ -0,0 +1,29 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class Pipelines < Common
+    doc 'Create' do
+      desc 'Create a new pipeline. [Project ID]'
+      example 'client.pipelines.create(264, ref: :master)'
+      result '#<Pipeline id: 7, ref: master, status: success>'
+
+      markdown <<~DOC
+        | Attribute   | Type    | Required | Description         |
+        | ref       | string  | yes      | Reference to commit |
+        | variables | array   | no       | An array containing the variables available in the pipeline, matching the structure [{ 'key' => 'UPLOAD_TO_S3', 'variable_type' => 'file', 'value' => 'true' }] |
+      DOC
+    end
+
+    doc 'Create' do
+      desc 'Via Project'
+      example <<~DOC
+        project = client.projects.show(5)
+        project.pipeline_create(ref: :master)
+      DOC
+    end
+
+    def create(project_id, query)
+      client.request(:post, "projects/#{project_id}/pipeline", Pipeline, query)
+    end
+  end
+end

data/lib/labclient/pipelines/delete.rb

@@ -0,0 +1,33 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class Pipelines < Common
+    doc 'Delete' do
+      desc 'Delete a pipeline. [Project ID, Pipeline ID]'
+      example 'client.pipelines.delete(264, 7)'
+    end
+
+    doc 'Delete' do
+      desc 'Via Project'
+      example <<~DOC
+        project = client.projects.show(5)
+        project.pipeline_delete(7)
+      DOC
+    end
+
+    doc 'Delete' do
+      desc 'Via Pipeline'
+      example <<~DOC
+        pipeline = client.pipelines.show(264,7)
+        pipeline.delete
+      DOC
+    end
+
+    def delete(project_id, pipeline_id)
+      project_id = format_id(project_id)
+      pipeline_id = format_id(pipeline_id)
+
+      client.request(:delete, "projects/#{project_id}/pipelines/#{pipeline_id}")
+    end
+  end
+end

data/lib/labclient/pipelines/list.rb

@@ -0,0 +1,50 @@
+# Top namespace
+module LabClient
+  # Specifics
+  class Pipelines < Common
+    doc 'List' do
+      desc 'List project pipelines. [Project ID, Hash]'
+      example 'client.pipelines.list(5)'
+      result '[#<Pipeline id: 6, ref: master, status: success>, ... ]'
+
+      markdown <<~DOC
+        | Attribute | Type    | Required | Description         |
+        |-----------|---------|----------|---------------------|
+        | scope   | string  | no       | The scope of pipelines, one of: running, pending, finished, branches, tags |
+        | status  | string  | no       | The status of pipelines, one of: running, pending, success, failed, canceled, skipped, created |
+        | ref     | string  | no       | The ref of pipelines |
+        | sha     | string  | no       | The SHA of pipelines |
+        | yaml_errors| boolean  | no       | Returns pipelines with invalid configurations |
+        | name| string  | no       | The name of the user who triggered pipelines |
+        | username| string  | no       | The username of the user who triggered pipelines |
+        | updated_after | datetime | no | Return pipelines updated after the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
+        | updated_before | datetime | no | Return pipelines updated before the specified date. Format: ISO 8601 YYYY-MM-DDTHH:MM:SSZ |
+        | order_by| string  | no       | Order pipelines by id, status, ref, updated_at or user_id (default: id) |
+        | sort    | string  | no       | Sort pipelines in asc or desc order (default: desc) |
+      DOC
+    end
+
+    doc 'List' do
+      desc 'Via Project'
+      example <<~DOC
+        project = client.projects.show(5)
+        project.pipelines
+      DOC
+    end
+
+    doc 'List' do
+      desc 'Filter by date'
+      example 'client.pipelines.list(264, updated_before: 10.day.ago)'
+    end
+
+    def list(project_id, query = {})
+      project_id = format_id(project_id)
+
+      %i[updated_after updated_before].each do |field|
+        query[field] = query[field].to_time.iso8601 if format_time?(query[field])
+      end
+
+      client.request(:get, "projects/#{project_id}/pipelines", Pipeline, query)
+    end
+  end
+end