ask-honeybadger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30842eefeba7cdd4bc71ad4958755872c84f36f935259717824d235f51ccac99
+  data.tar.gz: c177120c6ee8d243ad0559a935ffb66797aaa896f9cbd096725c3f5acd6e6a6a
+SHA512:
+  metadata.gz: be92b43b9113fa04f1b378b53dcb6c39dd4ce4f6a4dd75dfee2567cd39ae79a57558c5b393fe6c2ec6f7913ae47c1ac7831f3680fc6cdb7d1596abc7db5fbadf
+  data.tar.gz: 6625078687f978f71a36bc32788200f4383f815d83d6ae42d0a7dc6586484c07e30585a8529442aa06ca0b4a47c0b375af86f264c13f094b86cda07cc27ed516

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v0.1.0 (2026-06-10)
+
+- Initial release
+- context.rb: DESCRIPTION, QUICK_START, AUTH_NAME, and auth instructions
+- client.rb: Faraday-based HTTP client with Basic Auth and retry middleware
+- error_guide.rb: Structured error knowledge for common API errors
+- Convenience methods: recent_faults, fault_summary, fault, projects

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+# ask-honeybadger
+
+Honeybadger — error tracking via the Honeybadger API
+
+Part of the [ask-rb](https://github.com/ask-rb) ecosystem.
+
+## Installation
+
+```ruby
+gem "ask-honeybadger"
+```
+
+## Usage
+
+```ruby
+require "ask-honeybadger"
+
+# Get an authenticated client:
+client = Ask::Honeybadger.client
+
+# List faults for a project:
+faults = client.get("/v2/projects/PROJECT_ID/faults")
+
+# Or use the convenience helpers:
+Ask::Honeybadger.recent_faults(project_id: "PROJECT_ID", limit: 10)
+Ask::Honeybadger.fault_summary(project_id: "PROJECT_ID")
+Ask::Honeybadger.fault(project_id: "PROJECT_ID", fault_id: 42)
+Ask::Honeybadger.projects
+```
+
+## Authentication
+
+Set your Honeybadger API token in the environment:
+
+```bash
+export HONEYBADGER_TOKEN=your_token_here
+```
+
+Or add it to `~/.ask/credentials.yml`:
+
+```yaml
+honeybadger_token: your_token_here
+```
+
+Get your token at https://app.honeybadger.io/users/edit
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/honeybadger/client.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "ask/auth"
+
+module Ask
+  module Honeybadger
+    # Base URL for the Honeybadger Data API.
+    BASE_URL = "https://app.honeybadger.io/v2"
+
+    # Returns an authenticated Faraday client for the Honeybadger Data API.
+    #
+    # Resolves the Honeybadger API token via +Ask::Auth.resolve(:honeybadger_token)+
+    # and configures the client with sensible defaults:
+    #
+    # - +request+: JSON encoding
+    # - +response+: JSON decoding
+    # - +retry+: Faraday retry middleware (3 retries, exponential backoff)
+    # - +auth+: HTTP Basic Auth with token as username and blank password
+    #
+    # The client is wrapped in a +ClientProxy+ that converts
+    # +Faraday::UnauthorizedError+ into +Ask::Auth::InvalidCredential+.
+    #
+    # @example
+    #   client = Ask::Honeybadger.client
+    #   client.get("/v2/projects/ID/faults")
+    #
+    # @return [Faraday::Connection] an authenticated HTTP client
+    # @raise [Ask::Auth::MissingCredential] if no Honeybadger token is configured
+    # @raise [Ask::Auth::InvalidCredential] if the token is rejected (401)
+    def self.client
+      token = Ask::Auth.resolve(:honeybadger_token)
+
+      conn = Faraday.new(url: BASE_URL) do |f|
+        # HTTP Basic Auth: token is the username, password is blank
+        f.request :authorization, :basic, token, ""
+
+        # JSON request/response handling
+        f.request :json
+        f.response :json
+
+        # Retry middleware for transient failures
+        f.request :retry, max: 3, interval: 1, backoff_factor: 2,
+                          retry_statuses: [429, 500, 502, 503]
+
+        f.adapter Faraday.default_adapter
+      end
+
+      ClientProxy.new(conn)
+    end
+
+    # Convenience: fetch recent faults for a project.
+    #
+    # @param project_id [String, Integer] The Honeybadger project ID
+    # @param limit [Integer] Number of faults to return (max 25)
+    # @param params [Hash] Additional query parameters (q, order, environment, etc.)
+    # @return [Hash] Response with +results+ array and +links+
+    def self.recent_faults(project_id:, limit: 25, **params)
+      params[:limit] = limit
+      client.get("/v2/projects/#{project_id}/faults", params).body
+    end
+
+    # Convenience: get a fault summary (counts grouped by environment, status, etc.).
+    #
+    # @param project_id [String, Integer] The Honeybadger project ID
+    # @param params [Hash] Additional query parameters
+    # @return [Hash] Fault summary with counts
+    def self.fault_summary(project_id:, **params)
+      client.get("/v2/projects/#{project_id}/faults/summary", params).body
+    end
+
+    # Convenience: fetch a single fault by ID.
+    #
+    # @param project_id [String, Integer] The Honeybadger project ID
+    # @param fault_id [String, Integer] The fault ID
+    # @return [Hash] Fault details
+    def self.fault(project_id:, fault_id:)
+      client.get("/v2/projects/#{project_id}/faults/#{fault_id}").body
+    end
+
+    # Convenience: list all projects accessible with this token.
+    #
+    # @return [Hash] Response with +results+ array and +links+
+    def self.projects
+      client.get("/v2/projects").body
+    end
+
+    # Proxies method calls to a +Faraday::Connection+, converting
+    # authentication errors into +Ask::Auth::InvalidCredential+.
+    class ClientProxy < BasicObject
+      def initialize(client)
+        @client = client
+      end
+
+      def method_missing(name, ...)
+        @client.public_send(name, ...)
+      rescue ::Faraday::UnauthorizedError
+        ::Kernel.raise ::Ask::Auth::InvalidCredential, :honeybadger_token
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/ask/honeybadger/context.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ask
+  module Honeybadger
+    # Human-readable description of the Honeybadger service context.
+    DESCRIPTION = "Honeybadger — error tracking via the Honeybadger API"
+
+    # Base URL for Honeybadger API documentation.
+    DOCS_URL = "https://docs.honeybadger.io/api/"
+
+    # Credential name used with Ask::Auth.resolve.
+    AUTH_NAME = :honeybadger_token
+
+    # Instructions for obtaining a Honeybadger API token.
+    AUTH_HOW = "https://app.honeybadger.io/users/edit"
+
+    # Gem name for the Honeybadger Ruby integration.
+    GEM_NAME = "honeybadger-ruby"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      client = Ask::Honeybadger.client
+
+      # List faults for a project:
+      faults = client.get("/v2/projects/PROJECT_ID/faults")
+
+      # Get fault details:
+      fault = client.get("/v2/projects/PROJECT_ID/faults/FAULT_ID")
+
+      # List projects:
+      projects = client.get("/v2/projects")
+
+      # Convenience helpers:
+      Ask::Honeybadger.recent_faults(project_id: "PROJECT_ID", limit: 10)
+      Ask::Honeybadger.fault_summary(project_id: "PROJECT_ID")
+    RUBY
+  end
+end

data/lib/ask/honeybadger/error_guide.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Ask
+  module Honeybadger
+    # Structured error knowledge for AI agents working with the Honeybadger API.
+    #
+    # Provides human-readable guidance for common HTTP status codes, rate
+    # limiting, pagination, and authentication errors encountered when
+    # using the Honeybadger Data API.
+    module Errors
+      # Rate limit information.
+      #
+      # - Authenticated requests: 360 requests per hour
+      #
+      # When rate-limited, the API returns HTTP 403 (Forbidden). The agent
+      # should check the +X-RateLimit-Reset+ header and wait until that
+      # timestamp before retrying.
+      RATE_LIMIT = {
+        authenticated: "360 requests per hour (using API token)",
+        error_class: "Faraday::ForbiddenError",
+        action: "Check the X-RateLimit-Reset header, wait until that Unix timestamp, then retry the request.",
+        headers: {
+          limit: "X-RateLimit-Limit — number of requests you can make per hour",
+          remaining: "X-RateLimit-Remaining — number of requests remaining in the current window",
+          reset: "X-RateLimit-Reset — Unix timestamp when the rate limit resets"
+        }
+      }.freeze
+
+      # Common HTTP status codes returned by the Honeybadger API and how to handle them.
+      STATUS_CODES = {
+        200 => "OK — Request succeeded.",
+        201 => "Created — Resource was created successfully.",
+        204 => "No Content — Request succeeded, no response body.",
+        301 => "Moved Permanently — The resource URL has changed; update your reference.",
+        400 => "Bad Request — The request was malformed. Check parameters.",
+        401 => "Unauthorized — Token is missing, invalid, or revoked. Re-authenticate.",
+        403 => "Forbidden — Token lacks permissions or rate limit exceeded. Check token or retry later.",
+        404 => "Not Found — Resource does not exist or is private.",
+        409 => "Conflict — Resource state conflict.",
+        422 => "Unprocessable Entity — Validation failed. Check request parameters.",
+        429 => "Too Many Requests — Rate limit exceeded. Wait before retrying.",
+        500 => "Internal Server Error — Honeybadger server issue. Retry with backoff.",
+        502 => "Bad Gateway — Honeybadger upstream issue. Retry with backoff.",
+        503 => "Service Unavailable — Honeybadger is down for maintenance. Retry later."
+      }.freeze
+
+      # Pagination guidance for the Honeybadger API.
+      PAGINATION = {
+        links: "List responses include a links hash with 'self', 'next', and 'prev' URLs.",
+        next_page: "Load the next page by following the URL in the 'next' link.",
+        prev_page: "Load the previous page by following the URL in the 'prev' link.",
+        results_key: "Results are in the 'results' array within the response body.",
+        missing_links: "If next or prev links are missing, there is no further page in that direction."
+      }.freeze
+
+      # Map of exception classes to human-readable guidance.
+      EXCEPTIONS = {
+        "Faraday::UnauthorizedError" => {
+          message: "Your Honeybadger API token is invalid or has been revoked.",
+          action: "Generate a new token at https://app.honeybadger.io/users/edit"
+        },
+        "Faraday::ForbiddenError" => {
+          message: "Your token lacks the required permissions, or the rate limit has been exceeded.",
+          action: "Check your token permissions. If rate-limited, wait until the X-RateLimit-Reset timestamp."
+        },
+        "Faraday::ResourceNotFound" => {
+          message: "The requested project or fault does not exist or is not accessible.",
+          action: "Verify the project ID or fault ID. Ensure the token has access to this resource."
+        },
+        "Faraday::ParsingError" => {
+          message: "Failed to parse the API response.",
+          action: "The API may have returned an unexpected format. Check the raw response body."
+        },
+        "Faraday::TimeoutError" => {
+          message: "The request timed out.",
+          action: "Retry with exponential backoff. If the issue persists, check https://status.honeybadger.io."
+        },
+        "Faraday::ConnectionFailed" => {
+          message: "Failed to connect to the Honeybadger API.",
+          action: "Check your network connection and verify that https://app.honeybadger.io is reachable."
+        },
+        "Faraday::ServerError" => {
+          message: "Honeybadger encountered a server error (5xx).",
+          action: "Retry with exponential backoff. If the issue persists, check https://status.honeybadger.io."
+        }
+      }.freeze
+
+      # Look up guidance for an exception class name.
+      #
+      # @param exception_class [String] The exception class name (e.g., "Faraday::ResourceNotFound")
+      # @return [Hash, nil] A hash with +:message+ and +:action+ keys, or nil if unknown
+      def self.for(exception_class)
+        EXCEPTIONS[exception_class]
+      end
+
+      # Describe an HTTP status code.
+      #
+      # @param code [Integer] HTTP status code
+      # @return [String, nil] Description of the status code
+      def self.status_code_description(code)
+        STATUS_CODES[code]
+      end
+    end
+  end
+end

data/lib/ask/honeybadger/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Honeybadger
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask-honeybadger.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ask/honeybadger/version"
+require_relative "ask/honeybadger/context"
+require_relative "ask/honeybadger/client"
+require_relative "ask/honeybadger/error_guide"

metadata

@@ -0,0 +1,177 @@
+--- !ruby/object:Gem::Specification
+name: ask-honeybadger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: ask-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Error context for agents via Honeybadger for the ask-rb ecosystem.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-honeybadger.rb
+- lib/ask/honeybadger/client.rb
+- lib/ask/honeybadger/context.rb
+- lib/ask/honeybadger/error_guide.rb
+- lib/ask/honeybadger/version.rb
+homepage: https://github.com/ask-rb/ask-honeybadger
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-honeybadger
+  source_code_uri: https://github.com/ask-rb/ask-honeybadger
+  changelog_uri: https://github.com/ask-rb/ask-honeybadger/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Honeybadger — error tracking via the Honeybadger API
+test_files: []