issue-db 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f4349ba13a8c9f2971aae3c557c6bcd8d0b1b3fc51ecb4a901e3db2a30538db
-  data.tar.gz: a59e1724a2f9068bd4596a311b051224ad48a8df158e0607f5dc51374f096033
+  metadata.gz: 8c165f569fbb2648a4c73a0bf4007f67e6da2ff2dae28132af424d9eb9844575
+  data.tar.gz: 224bc98fcc029e417e620e4d8efaa79030fdf1a767558d126ab22145fec66ac7
 SHA512:
-  metadata.gz: e64935039edab751270a2fe8d924d32fff52035364baaa0a6455cf2fd0931fd4c51d39164b283435646c44cde628d3fb5cd98908673d8a1c0138a028855750d3
-  data.tar.gz: 28e242676837588f0dbadf5dc831569bc26e703d2533938daebe62e0eb45d59c3d243d8678d4f91dd03baeba371f40cc3272a4290d23af6b6bafd88aac8b2976
+  metadata.gz: e870e848ab6765beb5470008c38c03c9d0133fa22c9bd74a93888bbef7e59fb001dc18f9311106bdc8e43c4ef442eeb8f9f18fd8e18df37fcc7f9e9e5e4a1ad2
+  data.tar.gz: 5932e25bbc9bd9f1bf68638d38b61675ac5a497c4cc2fc2e59e121bdc838a3c2759d45a32c3e47014c8e88f6000116d33227379336fc3fbe1370107a4613402f

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 = {})`
 
@@ -85,6 +88,23 @@ record = db.create("order_number_123", { location: "London", items: [ "cookies",
 # more on this in another section of the README below
 options = { body_before: "some markdown text before the data", body_after: "some markdown text after the data" }
 record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
+
+# with the `labels` option to add additional GitHub labels to the issue (in addition to the library-managed label)
+options = { labels: ["priority:high", "customer:premium"] }
+record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
+
+# with the `assignees` option to assign GitHub users to the issue
+options = { assignees: ["alice", "bob"] }
+record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
+
+# with multiple options combined
+options = { 
+  labels: ["priority:high", "customer:premium"],
+  assignees: ["alice", "bob"],
+  body_before: "some markdown text before the data", 
+  body_after: "some markdown text after the data" 
+}
+record = db.create("order_number_123", { location: "London", items: [ "cookies", "espresso" ] }, options)
 ```
 
 Notes:
@@ -122,6 +142,23 @@ record = db.update("order_number_123", { location: "London", items: [ "cookies",
 # more on this in another section of the README below
 options = { body_before: "# Order 123\n\nData:", body_after: "Please do not edit the body of this issue" }
 record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
+
+# with the `labels` option to add additional GitHub labels to the issue (in addition to the library-managed label)
+options = { labels: ["status:processed", "priority:low"] }
+record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
+
+# with the `assignees` option to assign GitHub users to the issue
+options = { assignees: ["charlie", "diana"] }
+record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
+
+# with multiple options combined
+options = { 
+  labels: ["status:processed", "priority:low"],
+  assignees: ["charlie", "diana"],
+  body_before: "# Order 123\n\nData:", 
+  body_after: "Please do not edit the body of this issue" 
+}
+record = db.update("order_number_123", { location: "London", items: [ "cookies", "espresso", "chips" ] }, options)
 ```
 
 ### `db.delete(key, options = {})`
@@ -133,6 +170,21 @@ Example:
 
 ```ruby
 record = db.delete("order_number_123")
+
+# with the `labels` option to add additional GitHub labels to the issue before closing it
+options = { labels: ["archived", "completed"] }
+record = db.delete("order_number_123", options)
+
+# with the `assignees` option to assign GitHub users to the issue before closing it
+options = { assignees: ["alice"] }
+record = db.delete("order_number_123", options)
+
+# with multiple options combined
+options = { 
+  labels: ["archived", "completed"],
+  assignees: ["alice"]
+}
+record = db.delete("order_number_123", options)
 ```
 
 ### `db.list_keys(options = {})`
@@ -192,15 +244,163 @@ This section will go into detail around how you can configure the `issue-db` gem
 | `GH_APP_ALGO` | The algo to use for your GitHub App if providing a private key | `RS256` |
 | `ISSUE_DB_GITHUB_TOKEN` | The GitHub personal access token to use for authenticating with the GitHub API. You can also use a GitHub app or pass in your own authenticated Octokit.rb instance | `nil` |
 
+## Labels 🏷️
+
+The `issue-db` gem uses GitHub issue labels for organization and management. Here's how labels work:
+
+### Library-Managed Label
+
+The gem automatically applies a library-managed label (default: `issue-db`) to all issues it creates. This label:
+
+- **Cannot be modified or removed** by users (the gem will always ensure it's present)
+- Is used to identify which issues in the repository are managed by the `issue-db` gem
+- Can be customized by setting the `ISSUE_DB_LABEL` environment variable or passing the `label` parameter to `IssueDB.new()`
+
+### Additional Custom Labels
+
+You can add your own custom labels to issues when creating, updating, or deleting records by using the `labels` option:
+
+```ruby
+# Add custom labels when creating a record
+options = { labels: ["priority:high", "customer:premium", "region:europe"] }
+record = db.create("order_123", { product: "laptop" }, options)
+
+# Add custom labels when updating a record
+options = { labels: ["status:processed", "priority:low"] }
+record = db.update("order_123", { product: "laptop", status: "shipped" }, options)
+
+# Add custom labels before deleting (closing) a record
+options = { labels: ["archived", "completed", "Q4-2024"] }
+record = db.delete("order_123", options)
+```
+
+**Important Notes:**
+
+- Custom labels are **added in addition** to the library-managed label, not instead of it
+- If you accidentally include the library-managed label in your custom labels array, it will be automatically filtered out to prevent duplicates
+- Custom labels follow GitHub's label naming conventions and restrictions
+- Labels help with organization, filtering, and automation workflows in GitHub
+
+### Label Preservation
+
+When performing update or delete operations, the gem preserves existing labels by default:
+
+```ruby
+# Create a record with custom labels
+options = { labels: ["priority:high", "customer:premium"] }
+record = db.create("order_123", { product: "laptop" }, options)
+# Result: Issue has labels ["issue-db", "priority:high", "customer:premium"]
+
+# Update the record WITHOUT specifying labels - existing labels are preserved
+record = db.update("order_123", { product: "laptop", status: "shipped" })
+# Result: Issue STILL has labels ["issue-db", "priority:high", "customer:premium"]
+
+# Update the record WITH new labels - replaces all labels (except library-managed)
+options = { labels: ["status:processed", "priority:low"] }
+record = db.update("order_123", { product: "laptop", status: "delivered" }, options)
+# Result: Issue now has labels ["issue-db", "status:processed", "priority:low"]
+```
+
+**Key Behavior:**
+
+- **Labels specified** = Replace all labels with library-managed label + specified labels
+- **No labels specified** = Preserve existing labels exactly as they are
+
+### Example with Multiple Options
+
+You can combine labels with other options:
+
+```ruby
+options = {
+  labels: ["priority:high", "customer:vip"],
+  body_before: "## Order Details\n\nCustomer: VIP\n\n",
+  body_after: "\n\n---\n*This order requires special handling*"
+}
+record = db.create("vip_order_456", { items: ["premium_service"] }, options)
+```
+
+## Assignees 👥
+
+The `issue-db` gem supports GitHub issue assignees for task ownership and responsibility tracking. Here's how assignees work:
+
+### Basic Assignee Usage
+
+You can assign GitHub users to issues when creating, updating, or deleting records by using the `assignees` option:
+
+```ruby
+# Assign users when creating a record
+options = { assignees: ["alice", "bob"] }
+record = db.create("task_123", { type: "code_review" }, options)
+
+# Assign users when updating a record
+options = { assignees: ["charlie", "diana"] }
+record = db.update("task_123", { type: "code_review", status: "in_progress" }, options)
+
+# Assign users before deleting (closing) a record
+options = { assignees: ["alice"] }
+record = db.delete("task_123", options)
+```
+
+### Assignee Preservation
+
+Just like labels, the gem preserves existing assignees by default when no assignees are specified:
+
+```ruby
+# Create a record with assignees
+options = { assignees: ["alice", "bob"] }
+record = db.create("task_123", { type: "code_review" }, options)
+# Result: Issue is assigned to alice and bob
+
+# Update the record WITHOUT specifying assignees - existing assignees are preserved
+record = db.update("task_123", { type: "code_review", status: "in_progress" })
+# Result: Issue is STILL assigned to alice and bob
+
+# Update the record WITH new assignees - replaces all assignees
+options = { assignees: ["charlie"] }
+record = db.update("task_123", { type: "code_review", status: "completed" }, options)
+# Result: Issue is now only assigned to charlie
+```
+
+**Key Behavior:**
+
+- **Assignees specified** = Replace all assignees with the specified assignees
+- **No assignees specified** = Preserve existing assignees exactly as they are
+- **Empty array specified** = Remove all assignees from the issue
+
+### Combining Labels and Assignees
+
+You can use both labels and assignees together for comprehensive issue management:
+
+```ruby
+options = {
+  labels: ["priority:high", "type:bug", "team:backend"],
+  assignees: ["alice", "bob"],
+  body_before: "## Bug Report\n\nPriority: High\nTeam: Backend\n\n",
+  body_after: "\n\n---\n*Assigned to backend team leads*"
+}
+record = db.create("bug_456", { 
+  error: "Database timeout", 
+  severity: "critical" 
+}, options)
+```
+
+**Important Notes:**
+
+- Assignees must be valid GitHub usernames with access to the repository
+- You can assign up to 10 users to a single issue (GitHub's limit)
+- Invalid or inaccessible usernames will cause the API call to fail
+- Assignees help with responsibility tracking, notifications, and project management workflows
+
 ## 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 +415,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