rujira 0.4.0 → 0.5.1

data/lib/rujira/api/issue.rb

@@ -6,6 +6,9 @@ require_relative 'issue/comments'
 module Rujira
   module Api
     # Provides access to Jira issues via the REST API.
+    # Includes support for creating, updating, deleting, archiving issues,
+    # managing assignees, comments, remote links, transitions, watchers, and attachments.
+    #
     # API reference:
     # https://docs.atlassian.com/software/jira/docs/api/REST/9.17.0/#api/2/issue
     #
@@ -15,17 +18,11 @@ module Rujira
 
       # Creates a new issue.
       #
-      # @yield [builder] Optional block to configure the request payload.
+      # @yield [builder] Optional block to configure payload (fields, description, etc.).
       # @return [Object] The API response containing the created issue.
-      #
-      # @example Create an issue
+      # @example
       #   client.Issue.create do
-      #     payload fields: {
-      #       summary: "New bug report",
-      #       issuetype: { name: 'Task' },
-      #       project: { key: "TEST" },
-      #       description: 'This task was generated by the bot when creating changes in the repository.'
-      #     }
+      #     payload fields: { summary: "New bug", issuetype: { name: 'Task' }, project: { key: "TEST" } }
       #   end
       #
       def create(&block)
@@ -34,20 +31,16 @@ module Rujira
           method :post
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Creates multiple issues in bulk.
       #
-      # @yield [builder] Block to configure the payload for bulk creation.
-      # @return [Object] The API response after creating issues.
-      #
-      # @example Create issues in bulk
+      # @yield [builder] Block to configure bulk payload.
+      # @return [Object] API response after creating issues.
+      # @example
       #   client.Issue.create_bulk do
-      #     payload issues: [
-      #       { fields: { project: { key: "TEST" }, summary: "Issue 1", issuetype: { name: "Task" } } },
-      #       { fields: { project: { key: "TEST" }, summary: "Issue 2", issuetype: { name: "Bug" } } }
-      #     ]
+      #     payload issues: [{ fields: { summary: "Issue 1", project: { key: "TEST" }, issuetype: { name: "Task" } } }]
       #   end
       #
       def create_bulk(&block)
@@ -56,36 +49,30 @@ module Rujira
           method :post
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Retrieves an issue by its ID or key.
+      # Retrieves an issue by ID or key.
       #
       # @param [String] id_or_key The issue ID or key.
-      # @yield [builder] Optional block to configure the request.
-      # @return [Object] The API response containing the issue details.
-      #
-      # @example Get an issue
+      # @yield [builder] Optional block to configure additional request parameters or headers.
+      # @return [Object] The API response containing issue details.
+      # @example
       #   client.Issue.get("TEST-123")
-      #
       def get(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}"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Deletes an issue by its ID or key.
+      # Deletes an issue by ID or key.
       #
       # @param [String] id_or_key The issue ID or key.
-      # @yield [builder] Optional block to configure the request.
-      # @return [Object] The API response after deletion.
-      #
-      # @example Delete an issue
-      #   client.Issue.delete("TEST-123")
-      #
+      # @yield [builder] Optional block to configure additional request parameters.
+      # @return [Object] API response after deletion.
       def delete(id_or_key, &block)
         abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
         builder do
@@ -93,22 +80,15 @@ module Rujira
           method :delete
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
-
       alias del delete
 
       # Updates an existing issue.
       #
       # @param [String] id_or_key The issue ID or key.
       # @yield [builder] Optional block to configure the update payload.
-      # @return [Object] The API response after updating the issue.
-      #
-      # @example Edit an issue
-      #   client.Issue.edit("TEST-123") do
-      #     payload fields: { summary: "Updated summary" }
-      #   end
-      #
+      # @return [Object] API response after updating.
       def edit(id_or_key, &block)
         abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
         builder do
@@ -116,96 +96,72 @@ module Rujira
           method :put
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Archives an issue by its ID or key.
+      # Archives an issue.
       #
       # @param [String] id_or_key The issue ID or key.
-      # @return [Object] The API response after archiving the issue.
-      #
-      # @example Archive an issue
-      #   client.Issue.archive("TEST-123")
-      #
-      def archive(id_or_key)
+      # @yield [builder] Optional block for additional params.
+      # @return [Object] API response after archiving.
+      def archive(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}/archive"
           method :put
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Retrieves the archive information for a given issue.
+      # Lists archived information of an issue.
       #
       # @param [String] id_or_key The issue ID or key.
-      # @return [Object] The API response containing archive details for the issue.
-      #
-      # @example List archive information for an issue
-      #   client.Issue.list_archive("TEST-123")
-      def list_archive(id_or_key)
+      # @yield [builder] Optional block to add query parameters.
+      # @return [Object] API response with archive details.
+      def list_archive(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}/archive"
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Updates the assignee of an issue.
       #
-      # @param [String] id_or_key The issue ID or key.
-      # @yield [builder] Block to configure the payload for assignee update.
-      # @return [Object] The API response after updating the assignee.
-      #
-      # @example Assign an issue to a user
-      #   client.Issue.assignee("TEST-123") do
-      #     payload name: "john.doe"
-      #   end
-      #
-      def assignee(id_or_key)
+      # @param [String] id_or_key Issue ID or key.
+      # @yield [builder] Block to configure assignee payload.
+      # @return [Object] API response after assignment.
+      def assignee(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}/assignee"
           method :put
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Retrieves the edit metadata for a given issue.
-      # This provides information about which fields can be edited and their constraints.
-      #
-      # @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 edit metadata.
+      # Retrieves edit metadata for an issue.
       #
-      # @example Get edit metadata for an issue
-      #   client.Issue.editmeta("TEST-123") do
-      #     # Optional: add query parameters or headers
-      #     params expand: "projects,issuetypes.fields"
-      #   end
+      # @param [String] id_or_key Issue ID or key.
+      # @yield [builder] Optional block to configure query parameters.
+      # @return [Object] API response with editable fields and constraints.
       def editmeta(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}/editmeta"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Sends a notification about a specific issue.
-      #
-      # @param [String] id_or_key The issue ID or key.
-      # @yield [builder] Block to configure the payload for the notification.
-      # @return [Object] The API response after sending the notification.
+      # Sends a notification about an issue.
       #
-      # @example Notify users about an issue
-      #   client.Issue.notify("TEST-123") do
-      #     payload {
-      #       subject: "Issue Update",
-      #       textBody: "The issue has been updated.",
-      #       to: [{ type: "user", username: "john.doe" }]
-      #     }
-      #   end
+      # @param [String] id_or_key Issue ID or key.
+      # @yield [builder] Block to configure notification payload.
+      # @return [Object] API response after sending notification.
       def notify(id_or_key, &block)
         abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
         builder do
@@ -213,172 +169,34 @@ module Rujira
           path "issue/#{id_or_key}/notify"
           instance_eval(&block) if block_given?
         end
-        run
-      end
-
-      # Retrieves remote links 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 remote links.
-      #
-      # @example Get remote links for an issue
-      #   client.Issue.remotelink("TEST-123") do
-      #     # Optional: add query parameters or headers
-      #     params expand: "application"
-      #   end
-      def remotelink(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}/remotelink"
-          instance_eval(&block) if block_given?
-        end
-        run
+        call
       end
 
-      # Creates a remote link for a given issue.
+      # Uploads an attachment to an issue.
       #
-      # @param [String] id_or_key The issue ID or key.
-      # @yield [builder] Block to configure the payload for the remote link.
-      # @return [Object] The API response after creating the remote link.
-      #
-      # @example Create a remote link for an issue
-      #   client.Issue.create_remotelink("TEST-123") do
-      #     payload {
-      #       object: {
-      #         url: "https://example.com/task/123",
-      #         title: "External Task"
-      #       }
-      #     }
-      #   end
-      def create_remotelink(id_or_key, &block)
+      # @param [String] id_or_key Issue ID or key.
+      # @param [String] path Local path to file.
+      # @yield [builder] Optional block to configure request.
+      # @return [Object] API response after attachment.
+      def create_attachments(id_or_key, path, &block)
         abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
+        client = @client
         builder do
+          path "issue/#{id_or_key}/attachments"
           method :post
-          path "issue/#{id_or_key}/remotelink"
-          instance_eval(&block) if block_given?
-        end
-        run
-      end
-
-      # Deletes remote links 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 after deleting the remote link(s).
-      #
-      # @example Delete remote links for an issue
-      #   client.Issue.delete_remotelink("TEST-123") do
-      #     # Optional: add query parameters or headers if needed
-      #     params globalId: "com.example:task-123"
-      #   end
-      def delete_remotelink(id_or_key, &block)
-        abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
-        builder do
-          method :delete
-          path "issue/#{id_or_key}/remotelink"
-          instance_eval(&block) if block_given?
-        end
-        run
-      end
-
-      # Retrieves a specific remote link for a given issue.
-      #
-      # @param [String] id_or_key The issue ID or key.
-      # @param [String] link_id The remote link ID.
-      # @yield [builder] Optional block to configure additional request parameters.
-      # @return [Object] The API response containing the remote link details.
-      #
-      # @example Get a specific remote link
-      #   client.Issue.get_remotelink_by_id("TEST-123", "20001") do
-      #     # Optional: add headers or query parameters
-      #   end
-      def get_remotelink_by_id(id_or_key, link_id, &block)
-        abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
-        builder do
-          path "issue/#{id_or_key}/remotelink/#{link_id}"
-          instance_eval(&block) if block_given?
-        end
-        run
-      end
-
-      # Updates a specific remote link for a given issue.
-      #
-      # @param [String] id_or_key The issue ID or key.
-      # @param [String] link_id The remote link ID.
-      # @yield [builder] Block to configure the payload for updating the remote link.
-      # @return [Object] The API response after updating the remote link.
-      #
-      # @example Update a specific remote link
-      #   client.Issue.update_remotelink("TEST-123", "20001") do
-      #     payload {
-      #       object: {
-      #         url: "https://example.com/updated-task/123",
-      #         title: "Updated Task"
-      #       }
-      #     }
-      #   end
-      def update_remotelink(id_or_key, link_id, &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}/remotelink/#{link_id}"
-          instance_eval(&block) if block_given?
-        end
-        run
-      end
-
-      # Deletes a specific remote link by its ID for a given issue.
-      #
-      # @param [String] id_or_key The issue ID or key.
-      # @param [String] link_id The remote link ID.
-      # @yield [builder] Optional block to configure additional request parameters.
-      # @return [Object] The API response after deleting the remote link.
-      #
-      # @example Delete a specific remote link
-      #   client.Issue.delete_remotelink_by_id("TEST-123", "20001") do
-      #     # Optional: add headers or query parameters
-      #   end
-      def delete_remotelink_by_id(id_or_key, link_id, &block)
-        abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
-        builder do
-          method :delete
-          path "issue/#{id_or_key}/remotelink/#{link_id}"
-          instance_eval(&block) if block_given?
-        end
-        run
-      end
-
-      # Restores a previously archived 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 after restoring the issue.
-      #
-      # @example Restore an issue
-      #   client.Issue.restore("TEST-123") do
-      #     # Optional: add headers or payload if needed
-      #   end
-      def restore(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}/restore"
+          headers 'X-Atlassian-Token': 'no-check'
+          payload file: client.file(path)
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
+      alias attachments create_attachments
 
-      # Performs a transition on a given issue (e.g., change status).
-      #
-      # @param [String] id_or_key The issue ID or key.
-      # @yield [builder] Block to configure the payload for the transition.
-      # @return [Object] The API response after performing the transition.
+      # Performs a transition on an issue.
       #
-      # @example Transition an issue
-      #   client.Issue.transitions("TEST-123") do
-      #     payload transition: { id: "31" }
-      #   end
+      # @param [String] id_or_key Issue ID or key.
+      # @yield [builder] Block to configure transition payload.
+      # @return [Object] API response after transition.
       def transitions(id_or_key, &block)
         abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
         builder do
@@ -386,48 +204,24 @@ module Rujira
           path "issue/#{id_or_key}/transitions"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Retrieves available transitions 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 available transitions.
+      # Retrieves available transitions for an issue.
       #
-      # @example Get available transitions
-      #   client.Issue.get_transitions("TEST-123") do
-      #     # Optional: add query parameters or headers
-      #   end
+      # @param [String] id_or_key Issue ID or key.
+      # @yield [builder] Optional block to add query parameters.
+      # @return [Object] API response with available transitions.
       def get_transitions(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}/transitions"
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Uploads a file as an attachment to the specified Jira issue.
-      #
-      # @param [String] id_or_key The issue ID or key to which the file will be attached.
-      # @param [String] path The local file path of the attachment to upload.
-      # @yield [builder] Optional block to customize the request builder.
-      # @return [Object] The API response after executing the request.
-      #
-      def create_attachments(id_or_key, path, &block)
-        abort 'Issue ID or KEY is required' if id_or_key.to_s.strip.empty?
-        client = @client
-        builder do
-          path "issue/#{id_or_key}/attachments"
-          method :post
-          headers 'X-Atlassian-Token': 'no-check'
-          payload file: client.file(path)
-          instance_eval(&block) if block_given?
-        end
-        run
-      end
-      alias attachments create_attachments
+      # NOTE: Watchers and Comments modules are included separately.
     end
   end
 end

data/lib/rujira/api/myself.rb

@@ -3,7 +3,8 @@
 module Rujira
   module Api
     # Provides access to the Jira "Myself" resource via the REST API.
-    # Allows retrieving details about the currently authenticated user.
+    # Allows retrieving and updating details about the currently authenticated user,
+    # including password changes.
     #
     # API reference:
     # https://docs.atlassian.com/software/jira/docs/api/REST/9.17.0/#api/2/myself
@@ -11,23 +12,22 @@ module Rujira
     class Myself < Common
       # Retrieves details of the currently authenticated user.
       #
+      # @yield [builder] Optional block to configure additional request parameters.
       # @return [Object] The API response containing user details.
-      #
       # @example Get current user details
       #   client.Myself.get
-      #
-      def get
+      def get(&block)
         builder do
           path 'myself'
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Updates the current user's profile.
       #
       # @yield [builder] Block to configure the payload or additional request parameters.
       # @return [Object] The API response after updating the user profile.
-      #
       # @example Update user profile
       #   client.Myself.update do
       #     payload({ displayName: "New Name", emailAddress: "new@example.com" })
@@ -38,17 +38,16 @@ module Rujira
           path 'myself'
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
       # Changes the current user's password.
       #
-      # @yield [builder] Block to configure the payload for the password change.
+      # @yield [builder] Block to configure the payload for password change.
       # @return [Object] The API response after changing the password.
-      #
       # @example Change user password
       #   client.Myself.password do
-      #     payload({ password: "newpassword123" })
+      #     payload({ currentPassword: "oldpass", password: "newpass123" })
       #   end
       def password(&block)
         builder do
@@ -56,7 +55,7 @@ module Rujira
           path 'myself'
           instance_eval(&block) if block_given?
         end
-        run
+        call
       end
     end
   end

data/lib/rujira/api/permissions.rb

@@ -3,42 +3,40 @@
 module Rujira
   module Api
     # Provides access to Jira permissions via the REST API.
-    # Allows listing all permission schemes available in Jira.
+    # Allows listing all permission schemes and the current user's permissions.
     #
     # API reference:
     # https://docs.atlassian.com/software/jira/docs/api/REST/9.17.0/#api/2/permissions
     #
     class Permissions < Common
-      # Retrieves the list of all permissions in Jira.
+      # Retrieves the list of all permission schemes in Jira.
       #
-      # @yield [builder] Optional block to configure the request.
+      # @yield [builder] Optional block to configure additional request parameters.
       # @return [Object] The API response containing permissions details.
-      #
       # @example List all permissions
       #   client.Permissions.list
-      #
-      def list
+      def list(&block)
         builder do
           path 'permissions'
           method :get
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
 
-      # Retrieves the list of my permissions in Jira.
-      #
-      # @yield [builder] Optional block to configure the request.
-      # @return [Object] The API response containing permissions details.
+      # Retrieves the current user's permissions in Jira.
       #
-      # @example List all permissions
+      # @yield [builder] Optional block to configure additional request parameters.
+      # @return [Object] The API response containing the current user's permissions.
+      # @example List current user's permissions
       #   client.Permissions.my
-      #
-      def my
+      def my(&block)
         builder do
           path 'mypermissions'
           method :get
+          instance_eval(&block) if block_given?
         end
-        run
+        call
       end
     end
   end