issue-db 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f4349ba13a8c9f2971aae3c557c6bcd8d0b1b3fc51ecb4a901e3db2a30538db
-  data.tar.gz: a59e1724a2f9068bd4596a311b051224ad48a8df158e0607f5dc51374f096033
+  metadata.gz: 740a1a64de7f9ab45fd7932682999972139392b4c8d8f48105cde4f49e9474b1
+  data.tar.gz: 6219653cb7f2303482e039f906ae788e4d9f9a89131df12e750ef35cc0f8a976
 SHA512:
-  metadata.gz: e64935039edab751270a2fe8d924d32fff52035364baaa0a6455cf2fd0931fd4c51d39164b283435646c44cde628d3fb5cd98908673d8a1c0138a028855750d3
-  data.tar.gz: 28e242676837588f0dbadf5dc831569bc26e703d2533938daebe62e0eb45d59c3d243d8678d4f91dd03baeba371f40cc3272a4290d23af6b6bafd88aac8b2976
+  metadata.gz: 743c37f2ca18320e7ce68f4c5f88b2275a19c93f2239d10c7a1b5102ffb089444fb79ca947efef6dd47792bfeeafe82ead49812e92605f2ccafa0b351ce9ac43
+  data.tar.gz: cb0eb761ee2dfa89c3fc0f8d096957269905052778756a09fc755c3a5975264c690e725e38f707e4a10be618e8255f6b2cde26d1755d4ddac3d06c919e7499b7

data/README.md

@@ -65,9 +65,12 @@ gem install issue-db --version "X.X.X"
 
 ## Usage 💻
 
-The following CRUD operations are available for the `issue-db` gem:
+This section goes into details on the following CRUD operations are available for the `issue-db` gem.
 
-> Note: All methods return the `IssueDB::Record` of the object which was involved in the operation
+Note: All methods return the `IssueDB::Record` of the object which was involved in the operation
+
+> [!IMPORTANT]  
+> The key for the record is the title of the GitHub issue. This means that the key **must be unique** within the database. If you try to do any sort of duplicate operation on a key that already exists (like creating it again), the `issue-db` gem will return the existing record without modifying it. Here is an example log message where someone calls `db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] })` but the key already exists: `skipping issue creation and returning existing issue - an issue already exists with the key: order_number_123`. Additionally, if there are duplicates (same issue titles), then the latest issue will be returned (ex: issue 15 will be returned instead of issue 14). Basically, if you use fully unique keys, you won't ever run into this issue so please make sure to use unique keys for your records!
 
 ### `db.create(key, data, options = {})`
 
@@ -194,13 +197,14 @@ This section will go into detail around how you can configure the `issue-db` gem
 
 ## Authentication 🔒
 
-The `issue-db` gem uses the [`Octokit.rb`](https://github.com/octokit/octokit.rb) library under the hood for interactions with the GitHub API. You have three options for authentication when using the `issue-db` gem:
+The `issue-db` gem uses the [`Octokit.rb`](https://github.com/octokit/octokit.rb) library under the hood for interactions with the GitHub API. You have four options for authentication when using the `issue-db` gem:
 
 > Note: The order displayed below is also the order of priority that this Gem uses to authenticate.
 
 1. Pass in your own authenticated `Octokit.rb` instance to the `IssueDB.new` method
-2. Use a GitHub App by setting the `ISSUE_DB_GITHUB_APP_ID`, `ISSUE_DB_GITHUB_APP_INSTALLATION_ID`, and `ISSUE_DB_GITHUB_APP_KEY` environment variables
-3. Use a GitHub personal access token by setting the `ISSUE_DB_GITHUB_TOKEN` environment variable
+2. Pass GitHub App authentication parameters directly to the `IssueDB.new` method
+3. Use a GitHub App by setting the `ISSUE_DB_GITHUB_APP_ID`, `ISSUE_DB_GITHUB_APP_INSTALLATION_ID`, and `ISSUE_DB_GITHUB_APP_KEY` environment variables
+4. Use a GitHub personal access token by setting the `ISSUE_DB_GITHUB_TOKEN` environment variable
 
 > Using a GitHub App is the suggested method
 
@@ -215,7 +219,31 @@ require "issue_db"
 db = IssueDB.new("<org>/<repo>") # THAT'S IT! 🎉
 ```
 
-### Using a GitHub App
+### Using GitHub App Parameters Directly
+
+You can now pass GitHub App authentication parameters directly to the `IssueDB.new` method. This is especially useful when you want to manage authentication credentials in your application code or when you have multiple GitHub Apps for different purposes:
+
+```ruby
+require "issue_db"
+
+# Pass GitHub App credentials directly to IssueDB.new
+db = IssueDB.new(
+  "<org>/<repo>",
+  app_id: 12345,                    # Your GitHub App ID
+  installation_id: 56789,          # Your GitHub App Installation ID
+  app_key: "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",  # Your GitHub App private key
+  app_algo: "RS256"                 # Optional: defaults to RS256
+)
+```
+
+**Parameters:**
+
+- `app_id` (Integer) - Your GitHub App ID (found on the App's settings page)
+- `installation_id` (Integer) - Your GitHub App Installation ID (found in the installation URL: `https://github.com/organizations/<org>/settings/installations/<installation_id>`)
+- `app_key` (String) - Your GitHub App private key (can be the key content as a string or a file path ending in `.pem`)
+- `app_algo` (String, optional) - The algorithm to use for JWT signing (defaults to "RS256")
+
+### Using a GitHub App with Environment Variables
 
 This is the single best way to use the `issue-db` gem because GitHub Apps have increased rate limits, fine-grained permissions, and are more secure than using a personal access token. All you have to do is provide three environment variables and the `issue-db` gem will take care of the rest:
 

data/issue-db.gemspec

@@ -4,7 +4,7 @@ require_relative "lib/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "issue-db"
-  spec.version       = Version::VERSION
+  spec.version       = IssueDB::Version::VERSION
   spec.authors       = ["runwaylab", "GrantBirki"]
   spec.license       = "MIT"
 

data/lib/issue_db/authentication.rb

@@ -3,37 +3,45 @@
 require "octokit"
 require_relative "utils/github"
 
-class AuthenticationError < StandardError; end
+module IssueDB
+  class AuthenticationError < StandardError; end
 
-module Authentication
-  def self.login(client = nil, log = nil)
-    # if the client is not nil, use the pre-provided client
-    unless client.nil?
-      log.debug("using pre-provided client") if log
-      return client
-    end
+  module Authentication
+    def self.login(client = nil, log = nil, app_id: nil, installation_id: nil, app_key: nil, app_algo: nil)
+      # if the client is not nil, use the pre-provided client
+      unless client.nil?
+        log.debug("using pre-provided client") if log
+        return client
+      end
 
-    # if the client is nil, check for GitHub App env vars first
-    # first, check if all three of the following env vars are set and have values
-    # ISSUE_DB_GITHUB_APP_ID, ISSUE_DB_GITHUB_APP_INSTALLATION_ID, ISSUE_DB_GITHUB_APP_KEY
-    app_id = ENV.fetch("ISSUE_DB_GITHUB_APP_ID", nil)
-    installation_id = ENV.fetch("ISSUE_DB_GITHUB_APP_INSTALLATION_ID", nil)
-    app_key = ENV.fetch("ISSUE_DB_GITHUB_APP_KEY", nil)
-    if app_id && installation_id && app_key
-      log.debug("using github app authentication") if log
-      return GitHub.new(log:, app_id:, installation_id:, app_key:)
-    end
+      # if GitHub App parameters are provided, use them first
+      if app_id && installation_id && app_key
+        log.debug("using provided github app authentication parameters") if log
+        return IssueDB::Utils::GitHub.new(log:, app_id:, installation_id:, app_key:, app_algo:)
+      end
 
-    # if the client is nil and no GitHub App env vars were found, check for the ISSUE_DB_GITHUB_TOKEN
-    token = ENV.fetch("ISSUE_DB_GITHUB_TOKEN", nil)
-    if token
-      log.debug("using github token authentication") if log
-      octokit = Octokit::Client.new(access_token: token, page_size: 100)
-      octokit.auto_paginate = true
-      return octokit
-    end
+      # if the client is nil, check for GitHub App env vars
+      # first, check if all three of the following env vars are set and have values
+      # ISSUE_DB_GITHUB_APP_ID, ISSUE_DB_GITHUB_APP_INSTALLATION_ID, ISSUE_DB_GITHUB_APP_KEY
+      env_app_id = ENV.fetch("ISSUE_DB_GITHUB_APP_ID", nil)
+      env_installation_id = ENV.fetch("ISSUE_DB_GITHUB_APP_INSTALLATION_ID", nil)
+      env_app_key = ENV.fetch("ISSUE_DB_GITHUB_APP_KEY", nil)
+      if env_app_id && env_installation_id && env_app_key
+        log.debug("using github app authentication from environment variables") if log
+        return IssueDB::Utils::GitHub.new(log:, app_id: env_app_id, installation_id: env_installation_id, app_key: env_app_key)
+      end
 
-    # if we make it here, no valid auth method succeeded
-    raise AuthenticationError, "No valid GitHub authentication method was provided"
+      # if the client is nil and no GitHub App env vars were found, check for the ISSUE_DB_GITHUB_TOKEN
+      token = ENV.fetch("ISSUE_DB_GITHUB_TOKEN", nil)
+      if token
+        log.debug("using github token authentication") if log
+        octokit = Octokit::Client.new(access_token: token, page_size: 100)
+        octokit.auto_paginate = true
+        return octokit
+      end
+
+      # if we make it here, no valid auth method succeeded
+      raise AuthenticationError, "No valid GitHub authentication method was provided"
+    end
   end
 end

data/lib/issue_db/cache.rb

@@ -1,33 +1,35 @@
 # frozen_string_literal: true
 
-module Cache
-  # A helper method to update all issues in the cache
-  # :return: The updated issue cache as a list of issues
-  def update_issue_cache!
-    @log.debug("updating issue cache")
+module IssueDB
+  module Cache
+    # A helper method to update all issues in the cache
+    # :return: The updated issue cache as a list of issues
+    def update_issue_cache!
+      @log.debug("updating issue cache")
 
-    # find all issues in the repo that were created by this library
-    query = "repo:#{@repo.full_name} label:#{@label}"
+      # find all issues in the repo that were created by this library
+      query = "repo:#{@repo.full_name} label:#{@label}"
 
-    search_response = nil
-    begin
-      # issues structure: { "total_count": 0, "incomplete_results": false, "items": [<issues>] }
-      search_response = @client.search_issues(query)
-    rescue StandardError => e
-      retry_err_msg = "error search_issues() call: #{e.message}"
-      @log.error(retry_err_msg)
-      raise StandardError, retry_err_msg
-    end
+      search_response = nil
+      begin
+        # issues structure: { "total_count": 0, "incomplete_results": false, "items": [<issues>] }
+        search_response = @client.search_issues(query)
+      rescue StandardError => e
+        retry_err_msg = "error search_issues() call: #{e.message}"
+        @log.error(retry_err_msg)
+        raise StandardError, retry_err_msg
+      end
 
-    # Safety check to ensure search_response and items are not nil
-    if search_response.nil? || search_response.items.nil?
-      @log.error("search_issues returned nil response or nil items")
-      raise StandardError, "search_issues returned invalid response"
-    end
+      # Safety check to ensure search_response and items are not nil
+      if search_response.nil? || search_response.items.nil?
+        @log.error("search_issues returned nil response or nil items")
+        raise StandardError, "search_issues returned invalid response"
+      end
 
-    @log.debug("issue cache updated - cached #{search_response.total_count} issues")
-    @issues = search_response.items
-    @issues_last_updated = Time.now
-    return @issues
+      @log.debug("issue cache updated - cached #{search_response.total_count} issues")
+      @issues = search_response.items
+      @issues_last_updated = Time.now
+      return @issues
+    end
   end
 end