ask-sentry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc6dc184f307c3a0661dbc52d48c8caee86d7a5309ca627993cd37312686509f
+  data.tar.gz: 5e7484e41f6915948497575f26a28d681da5665fee6f796189498458f4bb1d09
+SHA512:
+  metadata.gz: 4e2f9dce7c5a47978ecd41fe1696111472158c1e8e5c4f62db6b7d926483a91e8188267b8b27254e422d71d4e3a4831920020da7489a005cfdec816219c4a5d6
+  data.tar.gz: 3ef0390e2ffa88cc75fdb6b1df2260c1da15a1e5c05548e5f4547899fd05c761309db5b03408835b2c826d9de0c8db420ce54d4f19f53305ad246012e3b9e228

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-06-10)
+
+- Initial release
+- `Ask::Sentry.client` — authenticated Faraday client for the Sentry REST API
+- `Ask::Sentry.recent_errors` — convenience wrapper to fetch recent issues
+- `Ask::Sentry.issue_events` — convenience wrapper to fetch issue events
+- `Ask::Sentry::Errors` — structured error knowledge for common HTTP codes, rate limits, pagination
+- Auth token resolution via `Ask::Auth.resolve(:sentry_token)`
+- 401 response detection with `Ask::Auth::InvalidCredential` error
+- Faraday retry middleware (3 retries, exponential backoff)

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,26 @@
+# ask-sentry
+
+Sentry — error tracking via the Sentry API
+
+## Installation
+
+```ruby
+gem "ask-sentry"
+```
+
+## Usage
+
+```ruby
+client = Ask::Sentry.client
+# ... use the client according to its API
+```
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/sentry/client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "ask/auth"
+
+module Ask
+  module Sentry
+    # Returns an authenticated Faraday client configured for the Sentry REST API.
+    #
+    # Resolves the Sentry token via +Ask::Auth.resolve(:sentry_token)+ and
+    # configures the client with sensible defaults:
+    #
+    # - +base URL+: +https://sentry.io/api/0/+
+    # - +Authorization+: Bearer token
+    # - +middleware+: Faraday retry middleware (3 retries, exponential backoff)
+    #
+    # The client is wrapped in a +ClientProxy+ that converts
+    # HTTP 401 responses into +Ask::Auth::InvalidCredential+.
+    #
+    # @example
+    #   client = Ask::Sentry.client
+    #   issues = client.get("projects/myorg/myapp/issues/")
+    #
+    # @return [ClientProxy] an authenticated HTTP client
+    # @raise [Ask::Auth::MissingCredential] if no Sentry token is configured
+    # @raise [Ask::Auth::InvalidCredential] if the token is rejected (401)
+    def self.client
+      token = Ask::Auth.resolve(:sentry_token)
+
+      client = Faraday.new(url: "https://sentry.io/api/0/") do |f|
+        f.request :authorization, :Bearer, token
+        f.headers["Content-Type"] = "application/json"
+        f.request :retry, max: 3, interval: 1, backoff_factor: 2,
+                          retry_statuses: [429, 500, 502, 503]
+        f.adapter Faraday.default_adapter
+      end
+
+      ClientProxy.new(client)
+    end
+
+    # Convenience wrapper to fetch recent errors for a given organization and project.
+    #
+    # @param organization [String] Sentry organization slug
+    # @param project [String] Sentry project slug
+    # @param limit [Integer] Maximum number of issues to return (default: 10)
+    # @return [Faraday::Response] API response
+    def self.recent_errors(organization:, project:, limit: 10)
+      client.get("projects/#{organization}/#{project}/issues/") do |req|
+        req.params[:limit] = limit
+      end
+    end
+
+    # Convenience wrapper to fetch events for a specific issue.
+    #
+    # @param issue_id [Integer, String] Sentry issue ID
+    # @param limit [Integer] Maximum number of events to return (default: 10)
+    # @return [Faraday::Response] API response
+    def self.issue_events(issue_id, limit: 10)
+      client.get("issues/#{issue_id}/events/") do |req|
+        req.params[:limit] = limit
+      end
+    end
+
+    # Proxies method calls to a +Faraday::Connection+, converting 401 responses
+    # into +Ask::Auth::InvalidCredential+.
+    class ClientProxy < BasicObject
+      def initialize(client)
+        @client = client
+      end
+
+      def method_missing(name, ...)
+        response = @client.public_send(name, ...)
+
+        if response.is_a?(::Faraday::Response) && response.status == 401
+          ::Kernel.raise ::Ask::Auth::InvalidCredential, :sentry_token
+        end
+
+        response
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/ask/sentry/context.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ask
+  module Sentry
+    # Human-readable description of the Sentry service context.
+    DESCRIPTION = "Sentry — error tracking via the Sentry API"
+
+    # Base URL for Sentry REST API documentation.
+    DOCS_URL = "https://docs.sentry.io/api/"
+
+    # URL for the Sentry OpenAPI specification.
+    OPENAPI_URL = "https://sentry.io/api/0/"
+
+    # Credential name used with Ask::Auth.resolve.
+    AUTH_NAME = :sentry_token
+
+    # Instructions for obtaining a Sentry auth token.
+    AUTH_HOW = "https://sentry.io/settings/account/api/auth-tokens/"
+
+    # Gem name for the HTTP client.
+    GEM_NAME = "faraday"
+
+    # Required gem version constraint.
+    GEM_VERSION = "~> 2.0"
+
+    # URL for Faraday library documentation.
+    GEM_DOCS = "https://lostisland.github.io/faraday"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      client = Ask::Sentry.client
+      issues = client.get("/api/0/projects/ORG/PROJECT/issues/", limit: 10)
+
+      # Or use the helper:
+      Ask::Sentry.recent_errors(organization: "myorg", project: "myapp", limit: 10)
+    RUBY
+  end
+end

data/lib/ask/sentry/error_guide.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Ask
+  module Sentry
+    # Structured error knowledge for AI agents working with the Sentry API.
+    #
+    # Provides human-readable guidance for common HTTP status codes, rate
+    # limiting, pagination, and authentication errors encountered when
+    # using the Faraday-based Sentry client.
+    module Errors
+      # Rate limit information.
+      #
+      # - Sentry rate limits are based on the plan (see Sentry docs).
+      # - When rate-limited, the API returns 429 Too Many Requests.
+      # - The agent should wait for the Retry-After header and retry.
+      RATE_LIMIT = {
+        description: "Sentry rate limits vary by plan. See https://docs.sentry.io/api/rate-limiting/",
+        error_status: 429,
+        action: "Wait for the Retry-After header duration, then retry the request."
+      }.freeze
+
+      # Common HTTP status codes returned by the Sentry API and how to handle them.
+      STATUS_CODES = {
+        200 => "OK — Request succeeded.",
+        201 => "Created — Resource was created successfully.",
+        202 => "Accepted — Request accepted for processing.",
+        204 => "No Content — Request succeeded, no response body.",
+        400 => "Bad Request — Invalid request parameters. Check the request body.",
+        401 => "Unauthorized — Auth token is missing, invalid, or revoked. Re-authenticate.",
+        403 => "Forbidden — Token lacks the required scopes for this resource.",
+        404 => "Not Found — The requested resource does not exist.",
+        409 => "Conflict — Resource state conflict.",
+        413 => "Payload Too Large — Request body exceeds the maximum size limit.",
+        429 => "Too Many Requests — Rate limit exceeded. Wait before retrying.",
+        500 => "Internal Server Error — Sentry server issue. Retry with backoff.",
+        502 => "Bad Gateway — Sentry upstream issue. Retry with backoff.",
+        503 => "Service Unavailable — Sentry is temporarily unavailable. Retry later."
+      }.freeze
+
+      # Pagination guidance for large result sets.
+      PAGINATION = {
+        link_header: "Sentry uses Link headers for pagination. The Faraday client receives these in the response headers.",
+        cursor_based: "Sentry uses cursor-based pagination via the 'Link' header with 'rel=\"next\"' and 'rel=\"previous\"'.",
+        per_page: "Use the 'limit' query parameter to control page size.",
+        max_results: "For large queries, paginate using cursor values from the Link header."
+      }.freeze
+
+      # Map of error scenarios to human-readable guidance.
+      EXCEPTIONS = {
+        "Faraday::UnauthorizedError" => {
+          message: "Your Sentry auth token is invalid or has been revoked.",
+          action: "Generate a new token at https://sentry.io/settings/account/api/auth-tokens/ with the necessary scopes."
+        },
+        "Faraday::ForbiddenError" => {
+          message: "Your token lacks the required permissions for this operation.",
+          action: "Check your token scopes at https://sentry.io/settings/account/api/auth-tokens/."
+        },
+        "Faraday::ResourceNotFound" => {
+          message: "The requested project, issue, or resource does not exist.",
+          action: "Verify the organization slug, project slug, and resource identifiers."
+        },
+        "Faraday::TimeoutError" => {
+          message: "The request to Sentry timed out.",
+          action: "Check Sentry service status at https://status.sentry.io/ and retry the request."
+        },
+        "Faraday::TooManyRequestsError" => {
+          message: "Sentry API rate limit exceeded.",
+          action: "Check the Retry-After response header, wait the specified duration, then retry."
+        },
+        "Faraday::ClientError" => {
+          message: "Sentry API returned a client error (4xx).",
+          action: "Check the request parameters, auth token, and resource identifiers."
+        },
+        "Faraday::ServerError" => {
+          message: "Sentry API returned a server error (5xx).",
+          action: "Retry with exponential backoff. If the issue persists, check https://status.sentry.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/sentry/version.rb

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

data/lib/ask-sentry.rb

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

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification
+name: ask-sentry
+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.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !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 Sentry for the ask-rb ecosystem.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-sentry.rb
+- lib/ask/sentry/client.rb
+- lib/ask/sentry/context.rb
+- lib/ask/sentry/error_guide.rb
+- lib/ask/sentry/version.rb
+homepage: https://github.com/ask-rb/ask-sentry
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ask-rb/ask-sentry
+  changelog_uri: https://github.com/ask-rb/ask-sentry/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: Sentry — error tracking via the Sentry API
+test_files: []