ruby-jira 0.1.0 → 0.2.0

data/lib/jira/client/project_categories.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client
+    # Defines methods related to project categories.
+    #
+    # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-categories/
+    module ProjectCategories
+      # Returns all project categories
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-categories/#api-rest-api-3-projectcategory-get
+      #
+      # @return [Array<Hash>]
+      def project_categories
+        get("/projectCategory")
+      end
+
+      # Creates a project category
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-categories/#api-rest-api-3-projectcategory-post
+      #
+      # @param payload [Hash] Project category payload
+      # @return [Hash]
+      def create_project_category(payload = {})
+        post("/projectCategory", body: payload)
+      end
+
+      # Returns a project category by ID
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-categories/#api-rest-api-3-projectcategory-id-get
+      #
+      # @param id [Integer, String] The ID of the project category
+      # @return [Hash]
+      def project_category(id)
+        get("/projectCategory/#{url_encode(id)}")
+      end
+
+      # Updates a project category
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-categories/#api-rest-api-3-projectcategory-id-put
+      #
+      # @param id [Integer, String] The ID of the project category
+      # @param payload [Hash] Project category payload
+      # @return [Hash]
+      def update_project_category(id, payload = {})
+        put("/projectCategory/#{url_encode(id)}", body: payload)
+      end
+
+      # Deletes a project category
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-categories/#api-rest-api-3-projectcategory-id-delete
+      #
+      # @param id [Integer, String] The ID of the project category
+      # @return [nil]
+      def delete_project_category(id)
+        delete("/projectCategory/#{url_encode(id)}")
+      end
+    end
+  end
+end

data/lib/jira/client/project_permission_schemes.rb

@@ -3,9 +3,13 @@
 module Jira
   class Client
     # Defines methods related to project permission schemes.
+    #
+    # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-permission-schemes/
     module ProjectPermissionSchemes
       # Gets assigned issue security level scheme for a project
       #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-permission-schemes/#api-rest-api-3-project-projectkeyorid-issuesecuritylevelscheme-get
+      #
       # @param project_key_or_id [Integer, String] Project ID or key
       # @param options [Hash] Query parameters
       # @return [Hash]
@@ -15,6 +19,8 @@ module Jira
 
       # Gets assigned permission scheme for a project
       #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-permission-schemes/#api-rest-api-3-project-projectkeyorid-permissionscheme-get
+      #
       # @param project_key_or_id [Integer, String] Project ID or key
       # @param options [Hash] Query parameters
       # @return [Hash]
@@ -22,8 +28,20 @@ module Jira
         get("/project/#{url_encode(project_key_or_id)}/permissionscheme", query: options)
       end
 
+      # Returns security levels for a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-permission-schemes/#api-rest-api-3-project-projectkeyorid-securitylevel-get
+      #
+      # @param project_key_or_id [Integer, String] Project ID or key
+      # @return [Hash]
+      def project_security_levels(project_key_or_id)
+        get("/project/#{url_encode(project_key_or_id)}/securitylevel")
+      end
+
       # Assigns permission scheme to a project
       #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-permission-schemes/#api-rest-api-3-project-projectkeyorid-permissionscheme-put
+      #
       # @param project_key_or_id [Integer, String] Project ID or key
       # @param scheme_id [Integer] Permission scheme ID
       # @param options [Hash] Additional payload

data/lib/jira/client/project_properties.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client
+    # Defines methods related to project properties.
+    #
+    # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-properties/
+    module ProjectProperties
+      # Returns all property keys for a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-properties/#api-rest-api-3-project-projectidorkey-properties-get
+      #
+      # @param project_id_or_key [Integer, String] The ID or key of the project
+      # @return [Hash]
+      def project_property_keys(project_id_or_key)
+        get("/project/#{url_encode(project_id_or_key)}/properties")
+      end
+
+      # Returns the value of a project property
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-properties/#api-rest-api-3-project-projectidorkey-properties-propertykey-get
+      #
+      # @param project_id_or_key [Integer, String] The ID or key of the project
+      # @param property_key [String] The key of the property
+      # @return [Hash]
+      def project_property(project_id_or_key, property_key)
+        get("/project/#{url_encode(project_id_or_key)}/properties/#{url_encode(property_key)}")
+      end
+
+      # Sets the value of a project property
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-properties/#api-rest-api-3-project-projectidorkey-properties-propertykey-put
+      #
+      # @param project_id_or_key [Integer, String] The ID or key of the project
+      # @param property_key [String] The key of the property
+      # @param payload [Hash] The value to set
+      # @return [nil]
+      def set_project_property(project_id_or_key, property_key, payload = {})
+        put("/project/#{url_encode(project_id_or_key)}/properties/#{url_encode(property_key)}", body: payload)
+      end
+
+      # Deletes a project property
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-properties/#api-rest-api-3-project-projectidorkey-properties-propertykey-delete
+      #
+      # @param project_id_or_key [Integer, String] The ID or key of the project
+      # @param property_key [String] The key of the property
+      # @return [nil]
+      def delete_project_property(project_id_or_key, property_key)
+        delete("/project/#{url_encode(project_id_or_key)}/properties/#{url_encode(property_key)}")
+      end
+    end
+  end
+end

data/lib/jira/client/projects.rb

@@ -3,9 +3,13 @@
 module Jira
   class Client
     # Defines methods related to projects.
+    #
+    # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/
     module Projects
       # Search projects
       #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
+      #
       # @param options [Hash] Query parameters
       # @return [Jira::Request::PaginatedResponse]
       def projects(options = {})
@@ -14,6 +18,8 @@ module Jira
 
       # Gets a single project
       #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-get
+      #
       # @param project_id_or_key [Integer, String] Project ID or key
       # @param options [Hash] Query parameters
       # @return [Hash]
@@ -23,11 +29,65 @@ module Jira
 
       # Archives a project
       #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-archive-post
+      #
       # @param project_id_or_key [Integer, String] Project ID or key
       # @return [Hash]
       def archive_project(project_id_or_key)
         post("/project/#{url_encode(project_id_or_key)}/archive")
       end
+
+      # Updates a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-put
+      #
+      # @param project_id_or_key [Integer, String] Project ID or key
+      # @param payload [Hash] Fields to update
+      # @return [Hash]
+      def update_project(project_id_or_key, payload = {})
+        put("/project/#{url_encode(project_id_or_key)}", body: payload)
+      end
+
+      # Deletes a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-delete
+      #
+      # @param project_id_or_key [Integer, String] Project ID or key
+      # @return [Hash]
+      def delete_project(project_id_or_key)
+        delete("/project/#{url_encode(project_id_or_key)}")
+      end
+
+      # Gets all issue types with their statuses for a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-statuses-get
+      #
+      # @param project_id_or_key [Integer, String] Project ID or key
+      # @return [Array<Hash>]
+      def project_statuses(project_id_or_key)
+        get("/project/#{url_encode(project_id_or_key)}/statuses")
+      end
+
+      # Gets the issue type hierarchy for a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectid-hierarchy-get
+      #
+      # @param project_id [Integer, String] Project ID
+      # @return [Hash]
+      def project_issue_type_hierarchy(project_id)
+        get("/project/#{url_encode(project_id)}/hierarchy")
+      end
+
+      # Gets the notification scheme for a project
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectkeyorid-notificationscheme-get
+      #
+      # @param project_key_or_id [Integer, String] Project key or ID
+      # @param options [Hash] Query parameters (e.g. expand:)
+      # @return [Hash]
+      def project_notification_scheme(project_key_or_id, options = {})
+        get("/project/#{url_encode(project_key_or_id)}/notificationscheme", query: options)
+      end
     end
   end
 end

data/lib/jira/client/time_tracking.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client
+    # Defines methods related to time tracking.
+    #
+    # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-time-tracking/
+    module TimeTracking
+      # Returns the time tracking provider that is currently selected
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-time-tracking/#api-rest-api-3-configuration-timetracking-get
+      #
+      # @return [Hash]
+      def time_tracking_provider
+        get("/configuration/timetracking")
+      end
+
+      # Selects a time tracking provider
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-time-tracking/#api-rest-api-3-configuration-timetracking-put
+      #
+      # @param payload [Hash] Time tracking provider payload
+      # @return [nil]
+      def select_time_tracking_provider(payload = {})
+        put("/configuration/timetracking", body: payload)
+      end
+
+      # Returns all time tracking providers
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-time-tracking/#api-rest-api-3-configuration-timetracking-list-get
+      #
+      # @return [Array<Hash>]
+      def time_tracking_providers
+        get("/configuration/timetracking/list")
+      end
+
+      # Returns the time tracking settings
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-time-tracking/#api-rest-api-3-configuration-timetracking-options-get
+      #
+      # @return [Hash]
+      def time_tracking_settings
+        get("/configuration/timetracking/options")
+      end
+
+      # Sets the time tracking settings
+      #
+      # @url https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-time-tracking/#api-rest-api-3-configuration-timetracking-options-put
+      #
+      # @param payload [Hash] Time tracking settings payload
+      # @return [Hash]
+      def set_time_tracking_settings(payload = {})
+        put("/configuration/timetracking/options", body: payload)
+      end
+    end
+  end
+end

data/lib/jira/client.rb

@@ -4,9 +4,15 @@ module Jira
   class Client < API
     Dir[File.expand_path("client/*.rb", __dir__)].each { |file| require file }
 
+    include IssueComments
+    include IssueSearch
     include Issues
+    include IssueWorklogs
+    include ProjectCategories
     include ProjectPermissionSchemes
+    include ProjectProperties
     include Projects
+    include TimeTracking
 
     # Text representation of the client, masking auth secrets.
     #

data/lib/jira/configuration.rb

@@ -21,6 +21,7 @@ module Jira
       ratelimit_retries
       ratelimit_base_delay
       ratelimit_max_delay
+      logger
     ].freeze
 
     DEFAULT_USER_AGENT = "Ruby Jira Gem #{Jira::VERSION}".freeze
@@ -63,6 +64,7 @@ module Jira
       self.ratelimit_max_delay = float_env("JIRA_RATELIMIT_MAX_DELAY", DEFAULT_RATELIMIT_MAX_DELAY)
       self.httparty = get_httparty_config(ENV.fetch("JIRA_HTTPARTY_OPTIONS", nil))
       self.user_agent = DEFAULT_USER_AGENT
+      self.logger = nil
     end
 
     private

data/lib/jira/error.rb

@@ -11,6 +11,9 @@ module Jira
     # Raised when impossible to parse response body.
     class Parsing < Base; end
 
+    # Raised when pagination cannot continue safely.
+    class Pagination < Base; end
+
     # Custom error class for rescuing from HTTP response errors.
     class ResponseError < Base
       POSSIBLE_MESSAGE_KEYS = %i[message error_description error].freeze

data/lib/jira/logging.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jira
+  # Provides a #log helper that delegates to the configured logger.
+  # Mixed into Request and pagination classes to emit debug information.
+  #
+  # @example Enable logging
+  #   require "logger"
+  #   Jira.configure { |c| c.logger = Logger.new($stdout) }
+  module Logging
+    def log(message)
+      Jira.logger&.debug("[ruby-jira] #{message}")
+    end
+  end
+end

data/lib/jira/pagination/collection_behavior.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Jira
+  module Pagination
+    # Shared behavior for paginated collection wrappers.
+    module CollectionBehavior
+      def inspect
+        @array.inspect
+      end
+
+      def method_missing(name, *, &)
+        return @array.send(name, *, &) if @array.respond_to?(name)
+
+        super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        super || @array.respond_to?(method_name, include_private)
+      end
+
+      def each_page # rubocop:disable Metrics/MethodLength
+        return enum_for(:each_page) unless block_given?
+
+        current = self
+        seen_markers = {}
+        loop do
+          yield current
+          break unless current.has_next_page?
+
+          marker = current.pagination_progress_marker
+          check_repeated_marker!(seen_markers, marker)
+          seen_markers[marker] = true if marker
+          current = next_page_with_progress_check(current, marker)
+        end
+      end
+
+      def lazy_paginate
+        to_enum(:each_page).lazy.flat_map(&:to_ary)
+      end
+
+      def auto_paginate(&block)
+        return lazy_paginate.to_a unless block
+
+        lazy_paginate.each(&block)
+      end
+
+      def paginate_with_limit(limit, &block)
+        return lazy_paginate.take(limit).to_a unless block
+
+        lazy_paginate.take(limit).each(&block)
+      end
+
+      private
+
+      def check_repeated_marker!(seen_markers, marker)
+        return unless marker
+        return unless seen_markers.key?(marker)
+
+        raise Error::Pagination, "pagination cursor repeated: #{marker.inspect}"
+      end
+
+      def next_page_with_progress_check(current, marker)
+        next_page = current.next_page
+        raise Error::Pagination, "pagination returned nil page" unless next_page
+        return next_page unless marker
+        return next_page unless next_page.pagination_progress_marker == marker
+
+        raise Error::Pagination, "pagination did not advance from #{marker.inspect}"
+      end
+    end
+  end
+end

data/lib/jira/pagination/cursor_paginated_response.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module Jira
-  # Wrapper for Jira cursor-paginated responses (nextPageToken style).
+  # Wrapper for Jira cursor-paginated responses.
   #
   # Endpoints like POST /search/jql return a body of:
   #   { nextPageToken: "token", total: int, <items_key>: [...] }
+  # Some Jira APIs use alternative cursor fields:
+  #   { nextPageCursor: "cursor", ... } or { cursor: "...", nextPageCursor: "...", last: false, ... }
+  # Other APIs use URL-based cursor fields:
+  #   { nextPage: "https://...", lastPage: false, ... }
   #
   # The items array key varies by endpoint (e.g. "issues", "worklogs").
   # This class detects it automatically as the first non-metadata Array value.
@@ -12,77 +18,87 @@ module Jira
   # Pagination is driven by a +next_page_fetcher+ proc set by the Request layer,
   # which re-issues the original request with +nextPageToken+ injected.
   class CursorPaginatedResponse
-    METADATA_KEYS = %i[nextPageToken total self].freeze
+    include Logging
+    include Pagination::CollectionBehavior
+
+    METADATA_KEYS = %i[
+      nextPageToken nextPageCursor cursor nextPage total self isLast last lastPage expand warningMessages maxResults
+      startAt size
+    ].freeze
 
     attr_accessor :client, :next_page_fetcher
-    attr_reader :next_page_token, :total
+    attr_reader :next_page_token, :next_page_cursor, :next_page_url, :total
 
-    def initialize(body)
-      @body = body
+    def initialize(body) # rubocop:disable Metrics/AbcSize
       @next_page_token = body[:nextPageToken]
+      @next_page_cursor = body[:nextPageCursor] || body[:cursor]
+      @next_page_url = body[:nextPage]
+      @is_last = body[:isLast]
+      @last = body[:last]
+      @last_page = body[:lastPage]
       @total = body.fetch(:total, 0).to_i
-      @array = wrap_items(detect_items_array(body))
+      items_key, items = detect_items_array(body)
+      log "CursorPaginatedResponse: items_key=#{items_key.inspect} count=#{items.length}"
+      @array = wrap_items(items)
     end
 
-    def inspect
-      @array.inspect
+    def next_page?
+      return false if @is_last == true || @last == true || @last_page == true
+
+      !next_page_locator.to_s.empty?
     end
+    alias has_next_page? next_page?
 
-    def method_missing(name, *, &)
-      return @array.send(name, *, &) if @array.respond_to?(name)
+    def next_page
+      return nil unless has_next_page?
+      return next_page_by_link unless @next_page_url.to_s.empty?
+      raise Error::MissingCredentials, "next_page_fetcher not set on CursorPaginatedResponse" unless @next_page_fetcher
 
-      super
+      @next_page_fetcher.call(next_page_locator)
     end
 
-    def respond_to_missing?(method_name, include_private = false)
-      super || @array.respond_to?(method_name, include_private)
-    end
+    def cursor_parameter_key
+      return :nextPageToken unless @next_page_token.to_s.empty?
+      return :cursor unless @next_page_cursor.to_s.empty?
 
-    def each_page
-      current = self
-      yield current
-      while current.has_next_page?
-        current = current.next_page
-        yield current
-      end
+      nil
     end
 
-    def lazy_paginate
-      to_enum(:each_page).lazy.flat_map(&:to_ary)
+    def fetcher_based_pagination?
+      @next_page_url.to_s.empty?
     end
 
-    def auto_paginate(&block)
-      return lazy_paginate.to_a unless block
-
-      lazy_paginate.each(&block)
+    def pagination_progress_marker
+      next_page_locator
     end
 
-    def paginate_with_limit(limit, &block)
-      return lazy_paginate.take(limit).to_a unless block
+    private
 
-      lazy_paginate.take(limit).each(&block)
-    end
+    def next_page_locator
+      return @next_page_token unless @next_page_token.to_s.empty?
+      return @next_page_cursor unless @next_page_cursor.to_s.empty?
+      return @next_page_url unless @next_page_url.to_s.empty?
 
-    def next_page?
-      !@next_page_token.to_s.empty?
+      nil
     end
-    alias has_next_page? next_page?
 
-    def next_page
-      return nil unless has_next_page?
-      raise Error::MissingCredentials, "next_page_fetcher not set on CursorPaginatedResponse" unless @next_page_fetcher
+    def next_page_by_link
+      raise Error::MissingCredentials, "client not set on CursorPaginatedResponse" unless @client
 
-      @next_page_fetcher.call(@next_page_token)
+      @client.get(client_relative_path(@next_page_url))
     end
 
-    private
+    def client_relative_path(link)
+      client_endpoint_path = @client.api_request_path
+      URI.parse(link).request_uri.sub(client_endpoint_path, "")
+    end
 
     def detect_items_array(body)
       body.each do |key, value|
         next if METADATA_KEYS.include?(key)
-        return value if value.is_a?(Array)
+        return [key, value] if value.is_a?(Array)
       end
-      []
+      [nil, []]
     end
 
     def wrap_items(items)