ruby-jira 0.1.0

data/lib/jira/error.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Jira
+  module Error
+    # Base class for all Jira errors.
+    class Base < StandardError; end
+
+    # Raised when API endpoint credentials not configured.
+    class MissingCredentials < Base; end
+
+    # Raised when impossible to parse response body.
+    class Parsing < Base; end
+
+    # Custom error class for rescuing from HTTP response errors.
+    class ResponseError < Base
+      POSSIBLE_MESSAGE_KEYS = %i[message error_description error].freeze
+
+      def initialize(response)
+        @response = response
+        super(build_error_message)
+      end
+
+      # Status code returned in the HTTP response.
+      #
+      # @return [Integer]
+      def response_status
+        @response.code
+      end
+
+      # Body content returned in the HTTP response
+      #
+      # @return [String]
+      def response_message
+        parsed_response = @response.parsed_response
+        return parsed_response[:message] || parsed_response["message"] if parsed_response.is_a?(Hash)
+
+        parsed_response.respond_to?(:message) ? parsed_response.message : parsed_response
+      end
+
+      # Additional error context returned by some API endpoints
+      #
+      # @return [String]
+      def error_code
+        if @response.respond_to?(:error_code)
+          @response.error_code
+        else
+          ""
+        end
+      end
+
+      private
+
+      # Human friendly message.
+      #
+      # @return [String]
+      def build_error_message
+        parsed_response = classified_response
+        message = check_error_keys(parsed_response)
+        "Server responded with code #{@response.code}, message: " \
+          "#{handle_message(message)}. " \
+          "Request URI: #{@response.request.base_uri}#{@response.request.path}"
+      end
+
+      # Error keys vary across the API, find the first available key and return it.
+      def check_error_keys(response)
+        return hash_message(response) if response.is_a?(Hash)
+
+        object_message(response)
+      end
+
+      # Parse the body based on the classification of the body content type.
+      #
+      # @return [Object]
+      def classified_response
+        if @response.respond_to?(:headers)
+          @response.headers["content-type"] == "text/plain" ? { message: @response.to_s } : @response.parsed_response
+        else
+          @response.parsed_response
+        end
+      rescue Jira::Error::Parsing
+        @response.to_s
+      end
+
+      # Handle error response message in case of nested hashes.
+      def handle_message(message)
+        case message
+        when Hash
+          message.to_h.sort.map do |key, value|
+            "'#{key}' #{formatted_hash_value(value)}"
+          end.join(", ")
+        when Array
+          message.join(" ")
+        else
+          message
+        end
+      end
+
+      def formatted_hash_value(value)
+        if value.is_a?(Hash)
+          value.sort.map { |key, nested_value| "(#{key}: #{Array(nested_value).join(" ")})" }.join(" ")
+        else
+          Array(value).join(" ")
+        end
+      end
+
+      def present_value?(value)
+        return false if value.nil?
+        return !value.empty? if value.respond_to?(:empty?)
+
+        true
+      end
+
+      def hash_message(response)
+        POSSIBLE_MESSAGE_KEYS.each do |key|
+          symbol_value = response[key]
+          return symbol_value if present_value?(symbol_value)
+
+          string_value = response[key.to_s]
+          return string_value if present_value?(string_value)
+        end
+
+        response
+      end
+
+      def object_message(response)
+        POSSIBLE_MESSAGE_KEYS.each do |candidate|
+          next unless response.respond_to?(candidate)
+
+          value = response.send(candidate)
+          return value if present_value?(value)
+        end
+
+        compact_hash_response(response) || response
+      end
+
+      def compact_hash_response(response)
+        return nil if response.is_a?(Array) || !response.respond_to?(:to_h)
+
+        hash_response = response.to_h.compact
+        hash_response.empty? ? nil : hash_response
+      end
+    end
+
+    # Raised when API endpoint returns the HTTP status code 400.
+    class BadRequest < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 401.
+    class Unauthorized < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 403.
+    class Forbidden < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 404.
+    class NotFound < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 405.
+    class MethodNotAllowed < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 406.
+    class NotAcceptable < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 409.
+    class Conflict < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 422.
+    class Unprocessable < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 429.
+    class TooManyRequests < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 500.
+    class InternalServerError < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 502.
+    class BadGateway < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 503.
+    class ServiceUnavailable < ResponseError; end
+
+    # Raised when API endpoint returns the HTTP status code 522.
+    class ConnectionTimedOut < ResponseError; end
+
+    STATUS_MAPPINGS = {
+      400 => BadRequest,
+      401 => Unauthorized,
+      403 => Forbidden,
+      404 => NotFound,
+      405 => MethodNotAllowed,
+      406 => NotAcceptable,
+      409 => Conflict,
+      422 => Unprocessable,
+      429 => TooManyRequests,
+      500 => InternalServerError,
+      502 => BadGateway,
+      503 => ServiceUnavailable,
+      522 => ConnectionTimedOut
+    }.freeze
+
+    # Returns error class that should be raised for this response. Returns nil
+    # if the response status code is not 4xx or 5xx.
+    #
+    # @param response [HTTParty::Response] The response object.
+    # @return [Class<Jira::Error::ResponseError>, nil]
+    def self.klass(response)
+      error_klass = STATUS_MAPPINGS[response.code]
+      return error_klass if error_klass
+
+      ResponseError if response.server_error? || response.client_error?
+    end
+  end
+end

data/lib/jira/objectified_hash.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Jira
+  # Wraps a Hash to allow dot-notation access alongside bracket access.
+  #
+  # @example
+  #   issue = Jira::ObjectifiedHash.new({ key: "TEST-1", fields: { summary: "Bug" } })
+  #   issue.key          # => "TEST-1"
+  #   issue[:key]        # => "TEST-1"
+  #   issue.fields       # => <Jira::ObjectifiedHash ...>
+  #   issue.fields.summary  # => "Bug"
+  #   issue.to_h         # => { key: "TEST-1", ... }
+  class ObjectifiedHash
+    def initialize(hash)
+      @hash = hash
+      @data = hash.each_with_object({}) do |(key, value), data|
+        sym_key = key.to_sym
+        value = self.class.new(value) if value.is_a?(Hash)
+        value = value.map { |v| v.is_a?(Hash) ? self.class.new(v) : v } if value.is_a?(Array)
+        data[sym_key] = value
+      end
+    end
+
+    # @return [Hash] The original hash with original key types.
+    def to_hash
+      @hash
+    end
+    alias to_h to_hash
+
+    def inspect
+      "#<#{self.class}:#{object_id} {hash: #{@hash.inspect}}>"
+    end
+
+    # Supports both symbol and string key access.
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    # Supports nested key traversal, mirroring Hash#dig.
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty?
+      return nil unless value.respond_to?(:dig)
+
+      value.dig(*rest)
+    end
+
+    def ==(other)
+      return @hash == other.to_h if other.is_a?(self.class)
+
+      @hash == other
+    end
+
+    private
+
+    def method_missing(method_name, *, &)
+      return @data[method_name] if @data.key?(method_name)
+
+      super
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @data.key?(method_name) || super
+    end
+  end
+end

data/lib/jira/pagination/cursor_paginated_response.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Jira
+  # Wrapper for Jira cursor-paginated responses (nextPageToken style).
+  #
+  # Endpoints like POST /search/jql return a body of:
+  #   { nextPageToken: "token", total: int, <items_key>: [...] }
+  #
+  # The items array key varies by endpoint (e.g. "issues", "worklogs").
+  # This class detects it automatically as the first non-metadata Array value.
+  #
+  # 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
+
+    attr_accessor :client, :next_page_fetcher
+    attr_reader :next_page_token, :total
+
+    def initialize(body)
+      @body = body
+      @next_page_token = body[:nextPageToken]
+      @total = body.fetch(:total, 0).to_i
+      @array = wrap_items(detect_items_array(body))
+    end
+
+    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
+      current = self
+      yield current
+      while current.has_next_page?
+        current = current.next_page
+        yield current
+      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
+
+    def next_page?
+      !@next_page_token.to_s.empty?
+    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
+
+      @next_page_fetcher.call(@next_page_token)
+    end
+
+    private
+
+    def detect_items_array(body)
+      body.each do |key, value|
+        next if METADATA_KEYS.include?(key)
+        return value if value.is_a?(Array)
+      end
+      []
+    end
+
+    def wrap_items(items)
+      items.map { |item| item.is_a?(Hash) ? ObjectifiedHash.new(item) : item }
+    end
+  end
+end

data/lib/jira/pagination/paginated_response.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Jira
+  # Wrapper for Jira offset-paginated responses (values/isLast style).
+  #
+  # Endpoints like GET /project/search and GET /workflow/search return a body of:
+  #   { values: [...], isLast: bool, total: int, nextPage: url, startAt: int, maxResults: int }
+  class PaginatedResponse
+    attr_accessor :client
+    attr_reader :total, :max_results, :start_at, :self_url
+
+    def initialize(body)
+      @body = body
+      @array = wrap_items(body.fetch(:values, []))
+      @is_last = body.fetch(:isLast, false)
+      @max_results = body.fetch(:maxResults, 0).to_i
+      @next_page = body.fetch(:nextPage, "")
+      @self_url = body.fetch(:self, "")
+      @start_at = body.fetch(:startAt, 0).to_i
+      @total = body.fetch(:total, 0).to_i
+    end
+
+    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
+      current = self
+      yield current
+      while current.has_next_page?
+        current = current.next_page
+        yield current
+      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
+
+    def last_page?
+      @is_last == true
+    end
+    alias has_last_page? last_page?
+
+    def first_page?
+      @start_at.zero?
+    end
+    alias has_first_page? first_page?
+
+    def next_page?
+      @is_last == false && !@next_page.to_s.empty?
+    end
+    alias has_next_page? next_page?
+
+    def next_page
+      return nil unless has_next_page?
+
+      @client.get(client_relative_path(@next_page))
+    end
+
+    def client_relative_path(link)
+      client_endpoint_path = @client.api_request_path
+      URI.parse(link).request_uri.sub(client_endpoint_path, "")
+    end
+
+    private
+
+    def wrap_items(items)
+      items.map { |item| item.is_a?(Hash) ? ObjectifiedHash.new(item) : item }
+    end
+  end
+end

data/lib/jira/request/authentication.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Jira
+  class Request
+    class OAuthTokenClient
+      TOKEN_ENDPOINT_HEADERS = {
+        "Accept" => "application/json",
+        "Content-Type" => "application/json"
+      }.freeze
+
+      def initialize(request:)
+        @request = request
+      end
+
+      def fetch!(payload)
+        response = HTTParty.post(token_endpoint, **request_options(payload))
+        body = JSON.parse(response.body.to_s, symbolize_names: true)
+        return body if response.code.to_i.between?(200, 299)
+
+        message = body[:error_description] || body[:error] || response.body
+        raise Error::MissingCredentials, "OAuth token refresh failed: #{message}"
+      rescue JSON::ParserError
+        raise Error::MissingCredentials, "OAuth token refresh failed: invalid JSON response"
+      end
+
+      private
+
+      def token_endpoint
+        @request.oauth_token_endpoint || Configuration::DEFAULT_OAUTH_TOKEN_ENDPOINT
+      end
+
+      # Build HTTParty options, forwarding any proxy config set on Jira::Request.
+      def request_options(payload)
+        opts = { body: payload.to_json, headers: TOKEN_ENDPOINT_HEADERS }
+        proxy = proxy_options
+        opts.merge!(proxy) if proxy.any?
+        opts
+      end
+
+      def proxy_options
+        defaults = Jira::Request.default_options
+        {
+          http_proxyaddr: defaults[:http_proxyaddr],
+          http_proxyport: defaults[:http_proxyport],
+          http_proxyuser: defaults[:http_proxyuser],
+          http_proxypass: defaults[:http_proxypass]
+        }.compact
+      end
+    end
+
+    class Authenticator
+      OAUTH_TOKEN_EXPIRY_BUFFER = 30
+      SUPPORTED_OAUTH_GRANT_TYPES = %w[client_credentials refresh_token].freeze
+      OAUTH_MISSING_CREDENTIALS_MESSAGE = [
+        "Please provide oauth_access_token or",
+        "oauth_client_id/oauth_client_secret (and oauth_refresh_token for refresh_token grant) for :oauth2 auth"
+      ].join(" ").freeze
+
+      def initialize(request:, token_client: OAuthTokenClient.new(request: request))
+        @request = request
+        @token_client = token_client
+      end
+
+      def auth_type
+        type = (@request.auth_type || Configuration::DEFAULT_AUTH_TYPE).to_sym
+        return type if %i[basic oauth2].include?(type)
+
+        raise Error::MissingCredentials, "Unsupported auth_type '#{type}'. Use :basic or :oauth2"
+      end
+
+      def validate!
+        case auth_type
+        when :basic
+          validate_basic_auth!
+        when :oauth2
+          validate_oauth2_auth!
+        end
+      end
+
+      def authorization_header
+        case auth_type
+        when :basic
+          validate_basic_auth!
+          credentials = Base64.strict_encode64("#{@request.email}:#{@request.api_token}")
+          { "Authorization" => "Basic #{credentials}" }
+        when :oauth2
+          validate_oauth2_auth!
+          { "Authorization" => "Bearer #{oauth_access_token!}" }
+        end
+      end
+
+      private
+
+      def validate_basic_auth!
+        raise Error::MissingCredentials, "Please provide email for :basic auth" if @request.email.to_s.strip.empty?
+        return unless @request.api_token.to_s.strip.empty?
+
+        raise Error::MissingCredentials, "Please provide api_token for :basic auth"
+      end
+
+      def validate_oauth2_auth!
+        if !oauth_access_token_available? && !oauth_client_credentials_available?
+          raise Error::MissingCredentials, OAUTH_MISSING_CREDENTIALS_MESSAGE
+        end
+        return unless @request.cloud_id.to_s.strip.empty?
+
+        raise Error::MissingCredentials, "Please provide cloud_id for :oauth2 auth"
+      end
+
+      def oauth_access_token_available?
+        !@request.oauth_access_token.to_s.strip.empty?
+      end
+
+      def oauth_client_credentials_available?
+        return false if @request.oauth_client_id.to_s.strip.empty? || @request.oauth_client_secret.to_s.strip.empty?
+        return true if oauth_grant_type == "client_credentials"
+
+        !@request.oauth_refresh_token.to_s.strip.empty?
+      end
+
+      def oauth_access_token!
+        return @request.oauth_access_token if oauth_access_token_valid?
+        return refresh_oauth_access_token! if oauth_client_credentials_available?
+
+        raise Error::MissingCredentials, OAUTH_MISSING_CREDENTIALS_MESSAGE
+      end
+
+      def oauth_access_token_valid?
+        return false unless oauth_access_token_available?
+        return true if @request.oauth_access_token_expires_at.nil?
+
+        Time.now < @request.oauth_access_token_expires_at
+      end
+
+      def refresh_oauth_access_token!
+        body = @token_client.fetch!(refresh_token_payload)
+        apply_oauth_tokens!(body)
+        @request.oauth_access_token
+      end
+
+      def refresh_token_payload
+        payload = {
+          grant_type:    oauth_grant_type,
+          client_id:     @request.oauth_client_id,
+          client_secret: @request.oauth_client_secret
+        }
+        return payload if oauth_grant_type == "client_credentials"
+
+        payload.merge(refresh_token: @request.oauth_refresh_token)
+      end
+
+      def apply_oauth_tokens!(body)
+        token = body[:access_token]
+        raise Error::MissingCredentials, "OAuth token endpoint did not return access_token" if token.to_s.strip.empty?
+
+        @request.oauth_access_token = token
+        @request.oauth_refresh_token = body[:refresh_token] if body[:refresh_token]
+        update_oauth_expiry(body[:expires_in])
+      end
+
+      def update_oauth_expiry(expires_in)
+        return if expires_in.to_i <= 0
+
+        @request.oauth_access_token_expires_at = Time.now + [expires_in.to_i - OAUTH_TOKEN_EXPIRY_BUFFER, 0].max
+      end
+
+      def oauth_grant_type
+        type = @request.oauth_grant_type.to_s.strip
+        return "refresh_token" if type.empty? && !@request.oauth_refresh_token.to_s.strip.empty?
+        return "client_credentials" if type.empty?
+
+        unless SUPPORTED_OAUTH_GRANT_TYPES.include?(type)
+          raise Error::MissingCredentials, "Unsupported oauth_grant_type '#{type}'"
+        end
+
+        type
+      end
+    end
+  end
+end

data/lib/jira/request/paginated_response.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# This file is intentionally empty.
+# PaginatedResponse was moved to Jira::PaginatedResponse (lib/jira/paginated_response.rb).