ruby-jira 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a560af049fc2790fd46fcfa42a8913ff6a3e35fb6da619d0dbee7873a872fdec
+  data.tar.gz: d5e1af098eac6a126ca0643545effb8c9f420ef30349c716d127d7018ff3e8c5
+SHA512:
+  metadata.gz: c144da359a042b32d600661c40eb4d8588eac575ded10b1a00cec642958631fe50a878f240a97c2d8e6220824aa49973f49103fa1e4cac0f0774f6f39d754886
+  data.tar.gz: 15b14457c90a78271c0af4644276d945dd3cea0d980919967f24081d11a53b5b0b8a710204aeaa71757c68b89798a63d5f83ca3301543d79e3f2e9d02d8f92d5

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-09
+
+### Added
+
+- Add initial ruby-jira Jira API client gem ([09c7c53](https://github.com/macio/ruby-jira/commit/09c7c5302cec9ccd079d85f0c46466f53775e9da))
+
+

data/LICENSE.txt

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Maciej Kozak
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,273 @@
+# ruby-jira
+
+Ruby client for the [Jira Cloud REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/).
+
+> Inspired by and based on the architecture of [NARKOZ/gitlab](https://github.com/NARKOZ/gitlab) — a Ruby wrapper for the GitLab API. Many thanks for the solid foundation.
+
+## Requirements
+
+Ruby **3.2** or newer. Tested on 3.2, 3.3, and 3.4. Ruby 3.1 and older are not supported (EOL).
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ruby-jira"
+```
+
+## Authentication
+
+Two auth methods are supported: **Basic** (email + API token) and **OAuth 2.0**.
+
+### Basic auth
+
+```ruby
+Jira.configure do |config|
+  config.endpoint  = "https://your-domain.atlassian.net"
+  config.auth_type = :basic
+  config.email     = "you@example.com"
+  config.api_token = "your-api-token"
+end
+```
+
+Or via environment variables:
+
+```
+JIRA_ENDPOINT=https://your-domain.atlassian.net
+JIRA_EMAIL=you@example.com
+JIRA_API_TOKEN=your-api-token
+```
+
+### OAuth 2.0 — pre-fetched access token
+
+```ruby
+Jira.configure do |config|
+  config.endpoint           = "https://your-domain.atlassian.net"
+  config.auth_type          = :oauth2
+  config.cloud_id           = "your-cloud-id"
+  config.oauth_access_token = "your-access-token"
+end
+```
+
+### OAuth 2.0 — automatic token refresh (`refresh_token` grant)
+
+```ruby
+Jira.configure do |config|
+  config.endpoint              = "https://your-domain.atlassian.net"
+  config.auth_type             = :oauth2
+  config.cloud_id              = "your-cloud-id"
+  config.oauth_grant_type      = "refresh_token"
+  config.oauth_client_id       = "your-client-id"
+  config.oauth_client_secret   = "your-client-secret"
+  config.oauth_refresh_token   = "your-refresh-token"
+end
+```
+
+### OAuth 2.0 — service account (`client_credentials` grant)
+
+```ruby
+Jira.configure do |config|
+  config.endpoint            = "https://your-domain.atlassian.net"
+  config.auth_type           = :oauth2
+  config.cloud_id            = "your-cloud-id"
+  config.oauth_grant_type    = "client_credentials"
+  config.oauth_client_id     = "your-client-id"
+  config.oauth_client_secret = "your-client-secret"
+end
+```
+
+## Usage
+
+### Client
+
+Create a one-off client or use the global `Jira` facade:
+
+```ruby
+client = Jira.client   # uses global configuration
+# or
+client = Jira::Client.new(endpoint: "...", email: "...", api_token: "...")
+```
+
+All methods are also available directly on the `Jira` module:
+
+```ruby
+Jira.projects
+Jira.issue("TEST-1")
+```
+
+### Response objects
+
+All responses are returned as `Jira::ObjectifiedHash` instances, supporting both dot-notation and bracket access:
+
+```ruby
+issue = Jira.issue("TEST-1")
+issue.key           # => "TEST-1"
+issue[:key]         # => "TEST-1"
+issue.fields.summary
+issue.dig(:fields, :summary)
+issue.to_h          # => original Hash
+```
+
+### Projects
+
+```ruby
+# Search projects (offset-paginated)
+projects = Jira.projects(status: "live", maxResults: 50)
+projects.total        # => 42
+projects.next_page?   # => true
+projects.map(&:key)   # => ["TEST", "DEMO", ...]
+
+# Auto-paginate all projects
+all = projects.auto_paginate
+all = projects.paginate_with_limit(100)
+
+# Get a single project
+project = Jira.project("TEST")
+project.name
+project.lead.displayName
+
+# Archive a project
+Jira.archive_project("TEST")
+```
+
+### Issues
+
+```ruby
+# Get a single issue
+issue = Jira.issue("TEST-1")
+issue = Jira.issue("TEST-1", expand: "names,renderedFields")
+
+# Create an issue
+issue = Jira.create_issue({
+  fields: {
+    project:   { key: "TEST" },
+    summary:   "Something is broken",
+    issuetype: { id: "10001" }
+  }
+})
+
+# Update an issue
+Jira.edit_issue("TEST-1", { fields: { summary: "Updated summary" } })
+Jira.edit_issue("TEST-1", { fields: { summary: "Silent update" } }, notifyUsers: false)
+```
+
+### Permission schemes
+
+```ruby
+Jira.permission_scheme("TEST")
+Jira.issue_security_level_scheme("TEST")
+Jira.assign_permission_scheme("TEST", scheme_id: 101)
+```
+
+### Pagination
+
+Offset-paginated responses (`GET /project/search`, `GET /workflow/search`, etc.) return `Jira::PaginatedResponse`:
+
+```ruby
+page = Jira.projects
+page.total        # total count
+page.start_at     # current offset
+page.max_results  # page size
+page.last_page?   # isLast flag
+page.next_page?
+page.next_page    # fetches the next page
+page.auto_paginate                # fetches all pages, returns flat Array
+page.paginate_with_limit(200)
+page.each_page { |p| process(p) }
+```
+
+Cursor-paginated responses (`POST /search/jql`, etc.) return `Jira::CursorPaginatedResponse`:
+
+```ruby
+results = Jira.search_issues(jql: "project = TEST ORDER BY created DESC")
+results.next_page_token   # raw token
+results.next_page?
+results.next_page         # fetches next page automatically
+results.auto_paginate     # fetches all pages
+```
+
+### Rate limiting
+
+> Atlassian enforces a new points-based and tiered quota rate limiting policy for Jira Cloud apps since **March 2, 2026**.
+> This gem follows the current [official Jira Cloud Rate Limiting guide](https://developer.atlassian.com/cloud/jira/platform/rate-limiting/).
+
+The client automatically retries `429 Too Many Requests` and `503 Service Unavailable` (when rate-limit headers are present) on idempotent requests (`GET`, `PUT`, `DELETE`).
+
+**Supported response headers** (as enforced by Jira Cloud):
+
+| Header                  | Format             | Description                                                                    |
+| ----------------------- | ------------------ | ------------------------------------------------------------------------------ |
+| `Retry-After`           | integer seconds    | How long to wait before retrying (429 and some 503)                            |
+| `X-RateLimit-Reset`     | ISO 8601 timestamp | When the rate-limit window resets (429 only)                                   |
+| `X-RateLimit-Limit`     | integer            | Max request rate for the current scope                                         |
+| `X-RateLimit-Remaining` | integer            | Remaining capacity in the current window                                       |
+| `X-RateLimit-NearLimit` | `"true"`           | Signals < 20% capacity remains — consider throttling proactively               |
+| `RateLimit-Reason`      | string             | Which limit was exceeded (`jira-burst-based`, `jira-quota-tenant-based`, etc.) |
+
+**Retry strategy:** exponential backoff with proportional jitter (`delay × rand(0.7..1.3)`), respecting `Retry-After` and `X-RateLimit-Reset` headers. Falls back to backoff when no header is present.
+
+Default configuration (aligned with Atlassian recommendations):
+
+```ruby
+Jira.configure do |config|
+  config.ratelimit_retries    = 4     # max retry attempts
+  config.ratelimit_base_delay = 2.0   # seconds, base for exponential backoff
+  config.ratelimit_max_delay  = 30.0  # seconds, cap on backoff
+end
+```
+
+### Proxy
+
+```ruby
+Jira.http_proxy("proxy.example.com", 8080, "user", "pass")
+```
+
+## Configuration reference
+
+| Key                    | ENV variable                | Default                                  |
+| ---------------------- | --------------------------- | ---------------------------------------- |
+| `endpoint`             | `JIRA_ENDPOINT`             | —                                        |
+| `auth_type`            | `JIRA_AUTH_TYPE`            | `:basic`                                 |
+| `email`                | `JIRA_EMAIL`                | —                                        |
+| `api_token`            | `JIRA_API_TOKEN`            | —                                        |
+| `oauth_access_token`   | `JIRA_OAUTH_ACCESS_TOKEN`   | —                                        |
+| `oauth_client_id`      | `JIRA_OAUTH_CLIENT_ID`      | —                                        |
+| `oauth_client_secret`  | `JIRA_OAUTH_CLIENT_SECRET`  | —                                        |
+| `oauth_refresh_token`  | `JIRA_OAUTH_REFRESH_TOKEN`  | —                                        |
+| `oauth_grant_type`     | `JIRA_OAUTH_GRANT_TYPE`     | —                                        |
+| `oauth_token_endpoint` | `JIRA_OAUTH_TOKEN_ENDPOINT` | `https://auth.atlassian.com/oauth/token` |
+| `cloud_id`             | `JIRA_CLOUD_ID`             | —                                        |
+| `ratelimit_retries`    | `JIRA_RATELIMIT_RETRIES`    | `4`                                      |
+| `ratelimit_base_delay` | `JIRA_RATELIMIT_BASE_DELAY` | `2.0`                                    |
+| `ratelimit_max_delay`  | `JIRA_RATELIMIT_MAX_DELAY`  | `30.0`                                   |
+
+## Error handling
+
+```ruby
+rescue Jira::Error::Unauthorized   # 401
+rescue Jira::Error::Forbidden      # 403
+rescue Jira::Error::NotFound       # 404
+rescue Jira::Error::TooManyRequests # 429
+rescue Jira::Error::ResponseError  # any other 4xx/5xx
+rescue Jira::Error::Base           # all gem errors
+```
+
+`Jira::Error::ResponseError` exposes:
+
+```ruby
+e.response_status   # HTTP status code
+e.response_message  # parsed message from response body
+```
+
+## Running the example script
+
+```bash
+JIRA_ENDPOINT=https://your-domain.atlassian.net \
+JIRA_EMAIL=you@example.com \
+JIRA_API_TOKEN=your-api-token \
+JIRA_PROJECT_KEY=TEST \
+bundle exec ruby examples/basic_usage.rb
+```
+
+See [examples/basic_usage.rb](examples/basic_usage.rb) for all supported environment variables.

data/lib/jira/api.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jira
+  # @private
+  class API < Request
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+
+    # Creates a new API.
+    # @raise [Jira::Error::MissingCredentials]
+    # rubocop:disable Lint/MissingSuper
+    def initialize(options = {})
+      options = Jira.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key]) if options.key?(key)
+      end
+
+      request_defaults
+      self.class.headers "User-Agent" => user_agent
+    end
+    # rubocop:enable Lint/MissingSuper
+  end
+end

data/lib/jira/client/issues.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client
+    # Defines methods related to issues.
+    module Issues
+      # Creates a new issue
+      #
+      # @param payload [Hash] Issue payload
+      # @return [Hash]
+      def create_issue(payload = {})
+        post("/issue", body: payload)
+      end
+
+      # Gets a single issue
+      #
+      # @param issue_id_or_key [Integer, String] The ID or key of an issue
+      # @param options [Hash] Query parameters
+      # @return [Hash]
+      def issue(issue_id_or_key, options = {})
+        get("/issue/#{url_encode(issue_id_or_key)}", query: options)
+      end
+
+      # Updates an existing issue
+      #
+      # @param issue_id_or_key [Integer, String] The ID or key of an issue
+      # @param payload [Hash] Issue payload
+      # @param options [Hash] Query parameters
+      # @return [Hash]
+      def edit_issue(issue_id_or_key, payload = {}, options = {})
+        put("/issue/#{url_encode(issue_id_or_key)}", body: payload, query: options)
+      end
+    end
+  end
+end

data/lib/jira/client/project_permission_schemes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client
+    # Defines methods related to project permission schemes.
+    module ProjectPermissionSchemes
+      # Gets assigned issue security level scheme for a project
+      #
+      # @param project_key_or_id [Integer, String] Project ID or key
+      # @param options [Hash] Query parameters
+      # @return [Hash]
+      def issue_security_level_scheme(project_key_or_id, options = {})
+        get("/project/#{url_encode(project_key_or_id)}/issuesecuritylevelscheme", query: options)
+      end
+
+      # Gets assigned permission scheme for a project
+      #
+      # @param project_key_or_id [Integer, String] Project ID or key
+      # @param options [Hash] Query parameters
+      # @return [Hash]
+      def permission_scheme(project_key_or_id, options = {})
+        get("/project/#{url_encode(project_key_or_id)}/permissionscheme", query: options)
+      end
+
+      # Assigns permission scheme to a project
+      #
+      # @param project_key_or_id [Integer, String] Project ID or key
+      # @param scheme_id [Integer] Permission scheme ID
+      # @param options [Hash] Additional payload
+      # @return [Hash]
+      def assign_permission_scheme(project_key_or_id, scheme_id:, options: {})
+        body = { id: scheme_id }.merge(options)
+        put("/project/#{url_encode(project_key_or_id)}/permissionscheme", body: body)
+      end
+    end
+  end
+end

data/lib/jira/client/projects.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client
+    # Defines methods related to projects.
+    module Projects
+      # Search projects
+      #
+      # @param options [Hash] Query parameters
+      # @return [Jira::Request::PaginatedResponse]
+      def projects(options = {})
+        get("/project/search", query: options)
+      end
+
+      # Gets a single project
+      #
+      # @param project_id_or_key [Integer, String] Project ID or key
+      # @param options [Hash] Query parameters
+      # @return [Hash]
+      def project(project_id_or_key, options = {})
+        get("/project/#{url_encode(project_id_or_key)}", query: options)
+      end
+
+      # Archives a project
+      #
+      # @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
+    end
+  end
+end

data/lib/jira/client.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jira
+  class Client < API
+    Dir[File.expand_path("client/*.rb", __dir__)].each { |file| require file }
+
+    include Issues
+    include ProjectPermissionSchemes
+    include Projects
+
+    # Text representation of the client, masking auth secrets.
+    #
+    # @return [String]
+    def inspect
+      inspected = super
+      inspected = redact_secret(inspected, :api_token, @api_token) if @api_token
+      inspected = redact_secret(inspected, :oauth_access_token, @oauth_access_token) if @oauth_access_token
+      inspected = redact_secret(inspected, :oauth_client_secret, @oauth_client_secret) if @oauth_client_secret
+      inspected = redact_secret(inspected, :oauth_refresh_token, @oauth_refresh_token) if @oauth_refresh_token
+      inspected
+    end
+
+    # Utility method for URL encoding of a string.
+    #
+    # @return [String]
+    def url_encode(url)
+      url.to_s.b.gsub(/[^a-zA-Z0-9_\-.~]/n) { |match| format("%%%02X", match.unpack1("C")) }
+    end
+
+    private
+
+    def redact_secret(inspected, key, secret)
+      redacted = only_show_last_four_chars(secret)
+      inspected.sub %(@#{key}="#{secret}"), %(@#{key}="#{redacted}")
+    end
+
+    def only_show_last_four_chars(token)
+      return "****" if token.size <= 4
+
+      "#{"*" * (token.size - 4)}#{token[-4..]}"
+    end
+  end
+end

data/lib/jira/configuration.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Jira
+  module Configuration
+    VALID_OPTIONS_KEYS = %i[
+      endpoint
+      user_agent
+      httparty
+      auth_type
+      email
+      api_token
+      oauth_access_token
+      oauth_client_id
+      oauth_client_secret
+      oauth_refresh_token
+      oauth_grant_type
+      oauth_token_endpoint
+      cloud_id
+      ratelimit_retries
+      ratelimit_base_delay
+      ratelimit_max_delay
+    ].freeze
+
+    DEFAULT_USER_AGENT = "Ruby Jira Gem #{Jira::VERSION}".freeze
+    DEFAULT_AUTH_TYPE = :basic
+    DEFAULT_RATELIMIT_RETRIES = 4
+    DEFAULT_RATELIMIT_BASE_DELAY = 2.0
+    DEFAULT_RATELIMIT_MAX_DELAY = 30.0
+    DEFAULT_OAUTH_TOKEN_ENDPOINT = "https://auth.atlassian.com/oauth/token"
+
+    attr_accessor(*VALID_OPTIONS_KEYS)
+
+    def self.extended(base)
+      base.reset
+    end
+
+    def configure
+      yield self
+    end
+
+    def options
+      VALID_OPTIONS_KEYS.to_h do |key|
+        [key, send(key)]
+      end
+    end
+
+    def reset # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      self.endpoint = ENV.fetch("JIRA_ENDPOINT", nil)
+      self.auth_type = (ENV["JIRA_AUTH_TYPE"] || DEFAULT_AUTH_TYPE).to_sym
+      self.email = ENV.fetch("JIRA_EMAIL", nil)
+      self.api_token = ENV.fetch("JIRA_API_TOKEN", nil)
+      self.oauth_access_token = ENV.fetch("JIRA_OAUTH_ACCESS_TOKEN", nil)
+      self.oauth_client_id = ENV.fetch("JIRA_OAUTH_CLIENT_ID", nil)
+      self.oauth_client_secret = ENV.fetch("JIRA_OAUTH_CLIENT_SECRET", nil)
+      self.oauth_refresh_token = ENV.fetch("JIRA_OAUTH_REFRESH_TOKEN", nil)
+      self.oauth_grant_type = ENV.fetch("JIRA_OAUTH_GRANT_TYPE", nil)
+      self.oauth_token_endpoint = ENV.fetch("JIRA_OAUTH_TOKEN_ENDPOINT", DEFAULT_OAUTH_TOKEN_ENDPOINT)
+      self.cloud_id = ENV.fetch("JIRA_CLOUD_ID", nil)
+      self.ratelimit_retries = integer_env("JIRA_RATELIMIT_RETRIES", DEFAULT_RATELIMIT_RETRIES)
+      self.ratelimit_base_delay = float_env("JIRA_RATELIMIT_BASE_DELAY", DEFAULT_RATELIMIT_BASE_DELAY)
+      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
+    end
+
+    private
+
+    def get_httparty_config(options)
+      return nil if options.nil? || options.empty?
+
+      config = YAML.safe_load(options, permitted_classes: [Symbol], aliases: false)
+      raise ArgumentError, "HTTParty config should be a Hash." unless config.is_a?(Hash)
+
+      symbolize_keys(config)
+    end
+
+    def symbolize_keys(value)
+      return value unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, nested_value), output|
+        output[key.to_sym] = nested_value.is_a?(Hash) ? symbolize_keys(nested_value) : nested_value
+      end
+    end
+
+    def integer_env(key, default)
+      value = ENV.fetch(key, nil)
+      value ? Integer(value, 10) : default
+    rescue ArgumentError
+      default
+    end
+
+    def float_env(key, default)
+      value = ENV.fetch(key, nil)
+      value ? Float(value) : default
+    rescue ArgumentError
+      default
+    end
+  end
+end