rujira 0.4.0 → 0.5.1

data/lib/rujira/api/field.rb

@@ -11,18 +11,27 @@ module Rujira
     class Field < Common
       # Retrieves all fields.
       #
-      # @yield [builder] Optional block to configure the request.
+      # Optional query parameters can be passed in a block, for example:
+      # - filtering by field type or custom criteria (if supported by Jira API)
+      #
+      # @yield [builder] Optional block to configure query parameters.
       # @return [Object] The API response containing all fields.
       #
       # @example List all fields
       #   client.Field.get
       #   client.Field.list
       #
-      def list
+      # @example List all fields with custom params (if supported)
+      #   client.Field.list do
+      #     params type: "custom"
+      #   end
+      #
+      def list(&block)
         builder do
           path 'field'
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
       alias get list
 
@@ -33,7 +42,8 @@ module Rujira
       #
       # @example Create a custom field
       #   client.Field.create do
-      #     payload name: "My Field", type: "com.atlassian.jira.plugin.system.customfieldtypes:textfield"
+      #     payload name: "My Field",
+      #             type: "com.atlassian.jira.plugin.system.customfieldtypes:textfield"
       #   end
       #
       def create(&block)
@@ -42,7 +52,7 @@ module Rujira
           path 'field'
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
     end
   end

data/lib/rujira/api/filter.rb

@@ -9,7 +9,7 @@ module Rujira
     # API reference:
     # https://docs.atlassian.com/software/jira/docs/api/REST/9.17.0/#api/2/filter
     #
-    class Filter < Common
+    class Filter < Common # rubocop:disable Metrics/ClassLength
       # Creates a new filter.
       #
       # @yield [builder] Block to configure the payload for the new filter.
@@ -26,7 +26,7 @@ module Rujira
           path 'filter'
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Updates an existing filter by ID.
@@ -46,44 +46,50 @@ module Rujira
           path "filter/#{id}"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Deletes a filter by ID.
       #
       # @param [String] id The filter ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response after deletion.
       #
-      def delete(id)
+      def delete(id, &block)
         builder do
           method :delete
           path "filter/#{id}"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Retrieves a filter by ID.
       #
       # @param [String] id The filter ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response containing filter details.
       #
-      def get(id)
+      def get(id, &block)
         builder do
           path "filter/#{id}"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Retrieves columns configuration of a filter.
       #
       # @param [String] id The filter ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response with columns configuration.
       #
-      def columns(id)
+      def columns(id, &block)
         builder do
           path "filter/#{id}/columns"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Updates columns configuration of a filter.
@@ -92,43 +98,42 @@ module Rujira
       # @yield [builder] Block to configure the payload for columns.
       # @return [Object] The API response after updating columns.
       #
-      # @example Set columns for a filter
-      #   client.Filter.set_columns("10001") do
-      #     payload ["summary", "assignee", "status"]
-      #   end
-      #
       def set_columns(id, &block)
         builder do
           method :put
           path "filter/#{id}/columns"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Resets columns of a filter to default.
       #
       # @param [String] id The filter ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response after resetting columns.
       #
-      def reset_columns(id)
+      def reset_columns(id, &block)
         builder do
           method :delete
           path "filter/#{id}/columns"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Lists permissions of a filter.
       #
       # @param [String] id The filter ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response containing permissions.
       #
-      def list_permission(id)
+      def list_permission(id, &block)
         builder do
           path "filter/#{id}/permission"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Adds a permission to a filter.
@@ -137,56 +142,57 @@ module Rujira
       # @yield [builder] Block to configure the permission payload.
       # @return [Object] The API response after adding permission.
       #
-      # @example Add permission to a filter
-      #   client.Filter.add_permission("10001") do
-      #     payload type: "group", groupname: "jira-users"
-      #   end
-      #
       def add_permission(id, &block)
         builder do
           method :post
           path "filter/#{id}/permission"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Retrieves a specific permission of a filter.
       #
       # @param [String] id The filter ID.
       # @param [String] permission_id The permission ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response containing the permission details.
       #
-      def permission(id, permission_id)
+      def permission(id, permission_id, &block)
         builder do
           path "filter/#{id}/permission/#{permission_id}"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Deletes a specific permission of a filter.
       #
       # @param [String] id The filter ID.
       # @param [String] permission_id The permission ID.
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response after deletion.
       #
-      def delete_permission(id, permission_id)
+      def delete_permission(id, permission_id, &block)
         builder do
           method :delete
           path "filter/#{id}/permission/#{permission_id}"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Retrieves the default share scope of filters.
       #
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response with default share scope.
       #
-      def default_share_scope
+      def default_share_scope(&block)
         builder do
           path 'filter/defaultShareScope'
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Updates the default share scope of filters.
@@ -194,29 +200,26 @@ module Rujira
       # @yield [builder] Block to configure the payload.
       # @return [Object] The API response after updating default share scope.
       #
-      # @example Set default share scope
-      #   client.Filter.set_default_share_scope do
-      #     payload type: "PROJECT", projectId: "10000"
-      #   end
-      #
       def set_default_share_scope(&block)
         builder do
           method :put
           path 'filter/defaultShareScope'
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Retrieves favorite filters.
       #
+      # @yield [builder] Optional block to add query parameters.
       # @return [Object] The API response containing favorite filters.
       #
-      def favourite
+      def favourite(&block)
         builder do
           path 'filter/favourite'
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
     end
   end

data/lib/rujira/api/issue/comments.rb

@@ -6,7 +6,8 @@ module Rujira
       # Module providing methods to manage comments on Jira issues.
       #
       # This module is included in the `Issue` class and allows you to:
-      # - Add a new comment to an issue
+      # - List comments
+      # - Add a new comment
       # - Retrieve a specific comment
       # - Update a comment
       # - Delete a comment
@@ -21,31 +22,15 @@ module Rujira
       #     payload({ body: "This is a comment" })
       #   end
       #
-      # @example Update a comment
-      #   client.Issue.update_comment("TEST-123", "10001") do
-      #     payload({ body: "Updated comment text" })
-      #   end
-      #
-      # @example Delete a comment
-      #   client.Issue.delete_comment("TEST-123", "10001")
-      #
-      # @example Get a pinned comment
-      #   client.Issue.get_pinned_comment("TEST-123")
-      #
-      # @example Pin a comment
-      #   client.Issue.pin_comment("TEST-123", "10001")
       module Comments
-        # Retrieves comments for a given issue.
+        # Retrieves all comments for a given issue.
         #
         # @param [String] id_or_key The issue ID or key.
-        # @yield [builder] Optional block to configure additional request parameters.
+        # @yield [builder] Optional block to configure the request (headers, query params).
         # @return [Object] The API response containing the issue's comments.
         #
         # @example Get comments for an issue
-        #   client.Issue.comment("TEST-123") do
-        #     # Optional: add query parameters or headers
-        #     params startAt: 0, maxResults: 50
-        #   end
+        #   client.Issue.list_comment("TEST-123")
         #
         def list_comment(id_or_key, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
@@ -54,19 +39,20 @@ module Rujira
             method :get
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Adds a comment to a given issue.
+        # Adds a new comment to an issue.
         #
         # @param [String] id_or_key The issue ID or key.
         # @yield [builder] Block to configure the payload for the new comment.
-        # @return [Object] The API response after adding the comment.
+        # @return [Object] The API response containing the created comment.
         #
-        # @example Add a comment to an issue
+        # @example Add a comment
         #   client.Issue.add_comment("TEST-123") do
-        #     payload body: "This is a new comment added via the API."
+        #     payload body: "New comment text"
         #   end
+        #
         def add_comment(id_or_key, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           builder do
@@ -74,20 +60,40 @@ module Rujira
             method :post
             instance_eval(&block) if block_given?
           end
-          run
+          call
+        end
+
+        # Retrieves a specific comment by its ID.
+        #
+        # @param [String] id_or_key The issue ID or key.
+        # @param [String] id The comment ID.
+        # @yield [builder] Optional block to configure the request.
+        # @return [Object] The API response containing the comment details.
+        #
+        # @example Get a comment
+        #   client.Issue.get_comment("TEST-123", "10001")
+        #
+        def get_comment(id_or_key, id, &block)
+          abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
+          builder do
+            path "issue/#{id_or_key}/comment/#{id}"
+            instance_eval(&block) if block_given?
+          end
+          call
         end
 
-        # Updates an existing comment on a given issue.
+        # Updates an existing comment.
         #
         # @param [String] id_or_key The issue ID or key.
         # @param [String] id The comment ID.
         # @yield [builder] Block to configure the payload for updating the comment.
         # @return [Object] The API response after updating the comment.
         #
-        # @example Update a comment on an issue
+        # @example Update a comment
         #   client.Issue.update_comment("TEST-123", "10001") do
-        #     payload body: "Updated comment content."
+        #     payload body: "Updated comment text"
         #   end
+        #
         def update_comment(id_or_key, id, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           builder do
@@ -95,20 +101,19 @@ module Rujira
             method :put
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Deletes a comment from a given issue.
+        # Deletes a comment from an issue.
         #
         # @param [String] id_or_key The issue ID or key.
         # @param [String] id The comment ID.
         # @yield [builder] Optional block to configure additional request parameters.
         # @return [Object] The API response after deleting the comment.
         #
-        # @example Delete a comment from an issue
-        #   client.Issue.delete_comment("TEST-123", "10001") do
-        #     # Optional: add headers or query parameters if needed
-        #   end
+        # @example Delete a comment
+        #   client.Issue.delete_comment("TEST-123", "10001")
+        #
         def delete_comment(id_or_key, id, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           builder do
@@ -116,50 +121,45 @@ module Rujira
             method :delete
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Retrieves a specific comment from a given issue.
+        # Pins a comment to the top of an issue's comment list.
         #
         # @param [String] id_or_key The issue ID or key.
         # @param [String] id The comment ID.
         # @yield [builder] Optional block to configure additional request parameters.
-        # @return [Object] The API response containing the comment details.
+        # @return [Object] The API response after pinning the comment.
         #
-        # @example Get a specific comment
-        #   client.Issue.get_comment("TEST-123", "10001") do
-        #     # Optional: add headers or query parameters if needed
-        #   end
+        # @example Pin a comment
+        #   client.Issue.pin_comment("TEST-123", "10001")
         #
-        def get_comment(id_or_key, id, &block)
+        def pin_comment(id_or_key, id, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           builder do
-            path "issue/#{id_or_key}/comment/#{id}"
+            method :put
+            path "issue/#{id_or_key}/comment/#{id}/pin"
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Pins a comment on a given issue.
+        # Retrieves all pinned comments for a given issue.
         #
         # @param [String] id_or_key The issue ID or key.
-        # @param [String] id The comment ID.
-        # @yield [builder] Optional block to configure additional request parameters.
-        # @return [Object] The API response after pinning the comment.
+        # @yield [builder] Optional block to configure the request.
+        # @return [Object] The API response containing pinned comments.
         #
-        # @example Pin a comment
-        #   client.Issue.pin_comment("TEST-123", "10001") do
-        #     # Optional: add headers or query parameters if needed
-        #   end
+        # @example Get pinned comments
+        #   client.Issue.get_pinned_comments("TEST-123")
         #
-        def pin_comment(id_or_key, id, &block)
+        def get_pinned_comments(id_or_key, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           builder do
-            method :put
-            path "issue/#{id_or_key}/comment/#{id}/pin"
+            path "issue/#{id_or_key}/pinned-comments"
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
         # Adds a comment to an issue.
@@ -177,26 +177,6 @@ module Rujira
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           @client.Comment.create id_or_key, &block
         end
-
-        # Retrieves the pinned comment(s) for a given issue.
-        #
-        # @param [String] id_or_key The issue ID or key.
-        # @yield [builder] Optional block to configure additional request parameters.
-        # @return [Object] The API response containing the pinned comment(s).
-        #
-        # @example Get pinned comments for an issue
-        #   client.Issue.get_pinned_comment("TEST-123") do
-        #     # Optional: add query parameters or headers
-        #     params expand: "renderedBody"
-        #   end
-        def get_pinned_comments(id_or_key, &block)
-          abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
-          builder do
-            path "issue/#{id_or_key}/pinned-comments"
-            instance_eval(&block) if block_given?
-          end
-          run
-        end
       end
     end
   end

data/lib/rujira/api/issue/watchers.rb

@@ -2,113 +2,108 @@
 
 module Rujira
   module Api
-    # Provides access to Jira issues via the REST API.
-    # API reference:
-    # https://docs.atlassian.com/software/jira/docs/api/REST/9.17.0/#api/2/issue
-    #
     class Issue < Common
       # Module providing methods to manage watchers on Jira issues.
       #
       # This module is included in the `Issue` class and allows you to:
       # - Retrieve the list of watchers for an issue
-      # - Add watchers to an issue
+      # - Add single or multiple watchers to an issue
       # - Remove watchers from an issue
       #
       # All methods support an optional block to customize the request using the
-      # builder DSL, e.g., adding headers, query parameters, or payloads.
+      # builder DSL (headers, query parameters, or payload).
       #
       # @example Get all watchers for an issue
       #   client.Issue.get_watchers("TEST-123")
       #
-      # @example Add watchers to an issue
+      # @example Add multiple watchers to an issue
       #   client.Issue.add_watchers("TEST-123") do
       #     payload ["john.doe", "jane.smith"]
       #   end
       #
+      # @example Add a single watcher to an issue
+      #   client.Issue.watcher("TEST-123", "john.doe")
+      #
       # @example Remove a watcher from an issue
       #   client.Issue.remove_watchers("TEST-123", "john.doe")
       module Watchers
-        # Removes a watcher from a given issue.
+        # Retrieves the list of watchers for a specific issue.
         #
         # @param [String] id_or_key The issue ID or key.
-        # @param [String] username The username of the watcher to remove.
-        # @yield [builder] Optional block to configure additional request parameters.
-        # @return [Object] The API response after removing the watcher.
+        # @yield [builder] Optional block to customize headers, query parameters, or other request options.
+        # @return [Object] The API response containing the watchers.
         #
-        # @example Remove a watcher from an issue
-        #   client.Issue.remove_watchers("TEST-123", "john.doe") do
-        #     # Optional: add headers or query parameters
-        #   end
-        def remove_watchers(id_or_key, username, &block)
+        # @example Retrieve watchers
+        #   client.Issue.get_watchers("TEST-123")
+        def get_watchers(id_or_key, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
-          abort 'USERNAME is required' if username.to_s.strip.empty?
           builder do
-            method :delete
             path "issue/#{id_or_key}/watchers"
-            params username: username
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Retrieves the list of watchers for a given issue.
+        # Adds multiple watchers to a specific issue.
         #
         # @param [String] id_or_key The issue ID or key.
-        # @yield [builder] Optional block to configure additional request parameters.
-        # @return [Object] The API response containing the list of watchers.
+        # @yield [builder] Block to configure the request payload (array of usernames).
+        # @return [Object] The API response after adding watchers.
         #
-        # @example Get watchers of an issue
-        #   client.Issue.get_watchers("TEST-123") do
-        #     # Optional: add query parameters or headers
+        # @example Add multiple watchers
+        #   client.Issue.add_watchers("TEST-123") do
+        #     payload ["john.doe", "jane.smith"]
         #   end
-        def get_watchers(id_or_key, &block)
+        def add_watchers(id_or_key, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
           builder do
+            method :post
             path "issue/#{id_or_key}/watchers"
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Adds watchers to a given issue.
+        # Adds a single watcher to a specific issue.
         #
         # @param [String] id_or_key The issue ID or key.
-        # @yield [builder] Block to configure the payload for adding watchers.
-        # @return [Object] The API response after adding watchers.
+        # @param [String] username The username of the watcher to add.
+        # @yield [builder] Optional block to customize the request.
+        # @return [Object] The API response after adding the watcher.
         #
-        # @example Add watchers to an issue
-        #   client.Issue.add_watchers("TEST-123") do
-        #     payload ["john.doe", "jane.smith"]
-        #   end
-        def add_watchers(id_or_key, &block)
+        # @example Add a single watcher
+        #   client.Issue.watcher("TEST-123", "john.doe")
+        def watcher(id_or_key, username, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
+          abort 'USERNAME is required' if username.to_s.strip.empty?
           builder do
-            method :post
             path "issue/#{id_or_key}/watchers"
+            method :post
+            payload username.to_json
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
 
-        # Adds a watcher to an issue.
+        # Removes a watcher from a specific issue.
         #
         # @param [String] id_or_key The issue ID or key.
-        # @param [String] name The username to add as a watcher.
-        # @yield [builder] Optional block to configure the request.
-        # @return [Object] The API response after adding the watcher.
-        #
-        # @example Add a watcher
-        #   client.Issue.watchers("TEST-123", "johndoe")
+        # @param [String] username The username of the watcher to remove.
+        # @yield [builder] Optional block to customize headers, query parameters, or other request options.
+        # @return [Object] The API response after removing the watcher.
         #
-        def watcher(id_or_key, name, &block)
+        # @example Remove a watcher
+        #   client.Issue.remove_watchers("TEST-123", "john.doe")
+        def remove_watchers(id_or_key, username, &block)
           abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
+          abort 'USERNAME is required' if username.to_s.strip.empty?
           builder do
+            method :delete
             path "issue/#{id_or_key}/watchers"
-            method :post
-            payload name.to_json
+            params username: username
             instance_eval(&block) if block_given?
           end
-          run
+          call
         end
       end
     end