bugstack 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da0101ebd6b1cd809d68d700373e930e115813f35cc42f737e5963b18b9881fe
+  data.tar.gz: bef41397dd9156644ef76784feb204c0df41f491f469aafe9beb2f86692e18ea
+SHA512:
+  metadata.gz: 3f1dad3f2f483114a07cfb8e3170455d8b82d678782653c4a2273ba2c3c19de46eb1be92782399184ebda9d3fe3bc051c1c8a0ca15bfe88962ef359c395c22a9
+  data.tar.gz: e52217eddf681a0c79e89ec20e449337915730eb3055a206a99bda2e101470aae0acaef4150342b6621e22294d382ae410f19e97c2719772ff25c6633f337c79

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-02-13
+
+### Added
+
+- Core SDK with `Bugstack.init` and `Bugstack.capture_exception`
+- Background thread transport with retry and exponential backoff
+- SHA-256 error fingerprinting and client-side deduplication
+- `before_send` hook for event inspection/modification/filtering
+- `ignored_errors` for skipping specific error types or messages
+- `dry_run` mode for transparent debugging
+- `enabled` kill switch
+- Block-style configuration
+- Rails integration via Railtie and Rack middleware
+- Sinatra integration via `register`
+- Generic integration via `at_exit` hook
+- Zero runtime gem dependencies

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BugStack
+
+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,174 @@
+# bugstack-ruby
+
+Official Ruby SDK for [BugStack](https://bugstack.dev) — capture, report, and auto-fix production errors.
+
+[![Gem Version](https://badge.fury.io/rb/bugstack.svg)](https://rubygems.org/gems/bugstack)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Installation
+
+```ruby
+gem "bugstack"
+```
+
+Or install directly:
+
+```bash
+gem install bugstack
+```
+
+## Quick Start
+
+```ruby
+require "bugstack"
+
+Bugstack.init(api_key: "bs_live_...")
+
+begin
+  risky_operation
+rescue => e
+  Bugstack.capture_exception(e)
+end
+```
+
+## Block Configuration
+
+```ruby
+Bugstack.init do |config|
+  config.api_key = "bs_live_..."
+  config.environment = "production"
+  config.auto_fix = true
+  config.debug = true
+end
+```
+
+## Framework Integrations
+
+### Rails
+
+Add to your Gemfile:
+
+```ruby
+gem "bugstack"
+```
+
+Create an initializer:
+
+```ruby
+# config/initializers/bugstack.rb
+Bugstack.init do |config|
+  config.api_key = Rails.application.credentials.bugstack_api_key
+  config.environment = Rails.env
+  config.auto_fix = true
+end
+```
+
+The Railtie automatically inserts Rack middleware for exception capture.
+
+### Sinatra
+
+```ruby
+require "sinatra"
+require "bugstack"
+require "bugstack/integrations/sinatra"
+
+Bugstack.init(api_key: "bs_live_...")
+
+class MyApp < Sinatra::Base
+  register Bugstack::Integrations::Sinatra
+
+  get "/" do
+    "Hello!"
+  end
+end
+```
+
+### Generic (at_exit hook)
+
+```ruby
+require "bugstack"
+require "bugstack/integrations/generic"
+
+Bugstack.init(api_key: "bs_live_...")
+Bugstack::Integrations::Generic.install!
+```
+
+## Configuration
+
+```ruby
+Bugstack.init do |config|
+  config.api_key = "bs_live_..."        # Required
+  config.environment = "production"     # Default: "production"
+  config.auto_fix = true                # Enable AI-powered auto-fix
+  config.debug = false                  # Log SDK activity
+  config.dry_run = false                # Log without sending
+  config.enabled = true                 # Kill switch
+  config.deduplication_window = 300     # Seconds (default: 5 min)
+  config.timeout = 5.0                  # HTTP timeout in seconds
+  config.max_retries = 3                # Retry attempts
+  config.ignored_errors = [             # Errors to skip
+    SystemExit,
+    SignalException,
+    "expected error message",
+  ]
+  config.before_send = ->(event) {      # Inspect/modify/drop events
+    event  # return nil to drop
+  }
+end
+```
+
+## Data Transparency
+
+### `before_send` Hook
+
+```ruby
+Bugstack.init do |config|
+  config.api_key = "bs_live_..."
+  config.before_send = ->(event) {
+    # Drop health check errors
+    return nil if event.request&.dig(:route)&.include?("/health")
+
+    # Redact sensitive data
+    event.metadata.delete("secret")
+
+    event
+  }
+end
+```
+
+### `dry_run` Mode
+
+```ruby
+Bugstack.init(api_key: "bs_live_...", dry_run: true)
+# Prints: [BugStack DryRun] Would send: { ... }
+```
+
+## What Gets Sent
+
+```json
+{
+  "apiKey": "bs_live_...",
+  "error": {
+    "message": "undefined method 'foo' for nil",
+    "stackTrace": "NoMethodError: undefined method...",
+    "file": "app/controllers/users_controller.rb",
+    "function": "show",
+    "fingerprint": "a1b2c3d4e5f6g7h8"
+  },
+  "environment": {
+    "language": "ruby",
+    "languageVersion": "3.2.0",
+    "framework": "rails",
+    "frameworkVersion": "7.1.0",
+    "os": "x86_64-linux",
+    "sdkVersion": "1.0.0"
+  },
+  "timestamp": "2026-01-15T08:30:00Z"
+}
+```
+
+Zero runtime gem dependencies. No cookies, IP addresses, or user data.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/bugstack/client.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Bugstack
+  # Core client for capturing and reporting errors to BugStack.
+  # Thread-safe. Handles deduplication, filtering, and transport.
+  class Client
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+      @deduplicator = Deduplicator.new(window: config.deduplication_window)
+      @transport = nil
+
+      if config.enabled && !config.dry_run
+        @transport = Transport.new(
+          endpoint: config.endpoint,
+          api_key: config.api_key,
+          timeout: config.timeout,
+          max_retries: config.max_retries,
+          debug: config.debug
+        )
+      end
+
+      log_debug("Client initialized (endpoint=#{config.endpoint}, dry_run=#{config.dry_run})")
+    end
+
+    # Capture an exception and send it to BugStack.
+    #
+    # @param exception [Exception]
+    # @param request [Hash, nil] { route:, method: }
+    # @param metadata [Hash, nil]
+    # @return [Boolean]
+    def capture_exception(exception, request: nil, metadata: nil)
+      do_capture(exception, request: request, metadata: metadata)
+    rescue => e
+      log_debug("Error during capture: #{e.message}")
+      false
+    end
+
+    # Shut down the client and flush pending events.
+    def shutdown
+      @transport&.shutdown
+      @transport = nil
+    end
+
+    private
+
+    def do_capture(exception, request: nil, metadata: nil)
+      return false unless @config.enabled
+
+      # Check ignored errors
+      if ignored?(exception)
+        log_debug("Error ignored: #{exception.class.name}")
+        return false
+      end
+
+      # Extract location info
+      exc_type, file, function, line = Fingerprint.extract_location(exception)
+      stack_trace = Fingerprint.format_backtrace(exception)
+
+      # Build event
+      event = Event.new(
+        message: exception.message,
+        stack_trace: stack_trace,
+        file: file,
+        function: function,
+        exception_type: exc_type,
+        fingerprint: Fingerprint.generate(exc_type, file, function, line),
+        request: request,
+        timestamp: Time.now.utc.iso8601,
+        metadata: metadata || {}
+      )
+
+      # before_send hook
+      if @config.before_send
+        event = @config.before_send.call(event)
+        if event.nil?
+          log_debug("Event dropped by before_send")
+          return false
+        end
+      end
+
+      # Deduplication
+      unless @deduplicator.should_send?(event.fingerprint)
+        log_debug("Event deduplicated: #{event.fingerprint}")
+        return false
+      end
+
+      # Build payload
+      payload = event.to_payload(@config)
+
+      # Dry run
+      if @config.dry_run
+        $stdout.puts "[BugStack DryRun] Would send: #{JSON.pretty_generate(payload)}"
+        return true
+      end
+
+      # Enqueue for sending
+      @transport&.enqueue(payload)
+      log_debug("Event queued: #{event.fingerprint}")
+      true
+    end
+
+    def ignored?(exception)
+      @config.ignored_errors.any? do |pattern|
+        case pattern
+        when Class
+          exception.is_a?(pattern)
+        when String
+          exception.message == pattern
+        else
+          false
+        end
+      end
+    end
+
+    def log_debug(msg)
+      return unless @config.debug
+
+      warn "[BugStack] #{msg}"
+    end
+  end
+end

data/lib/bugstack/configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Bugstack
+  # Configuration for the BugStack SDK.
+  #
+  # @example
+  #   Bugstack.init do |config|
+  #     config.api_key = "bs_live_..."
+  #     config.environment = "production"
+  #     config.auto_fix = true
+  #   end
+  class Configuration
+    # @return [String] BugStack API key (required)
+    attr_accessor :api_key
+
+    # @return [String] BugStack API endpoint
+    attr_accessor :endpoint
+
+    # @return [String] Project identifier
+    attr_accessor :project_id
+
+    # @return [String] Environment name
+    attr_accessor :environment
+
+    # @return [Boolean] Enable autonomous error fixing
+    attr_accessor :auto_fix
+
+    # @return [Boolean] Kill switch — set to false to disable everything
+    attr_accessor :enabled
+
+    # @return [Boolean] Log SDK activity to console
+    attr_accessor :debug
+
+    # @return [Boolean] Log errors but don't send them
+    attr_accessor :dry_run
+
+    # @return [Float] Deduplication window in seconds
+    attr_accessor :deduplication_window
+
+    # @return [Float] HTTP timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Max retry attempts
+    attr_accessor :max_retries
+
+    # @return [Array<Class, String>] Error types or messages to ignore
+    attr_accessor :ignored_errors
+
+    # @return [Proc, nil] Hook to inspect/modify/drop events before sending
+    attr_accessor :before_send
+
+    def initialize
+      @api_key = ""
+      @endpoint = "https://api.bugstack.dev/api/capture"
+      @project_id = ""
+      @environment = "production"
+      @auto_fix = false
+      @enabled = true
+      @debug = false
+      @dry_run = false
+      @deduplication_window = 300.0
+      @timeout = 5.0
+      @max_retries = 3
+      @ignored_errors = []
+      @before_send = nil
+    end
+  end
+end

data/lib/bugstack/event.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Bugstack
+  # Represents an error event to be sent to BugStack.
+  class Event
+    attr_accessor :message, :stack_trace, :file, :function, :fingerprint,
+                  :exception_type, :request, :environment, :timestamp, :metadata
+
+    def initialize(
+      message:,
+      stack_trace: "",
+      file: "",
+      function: "",
+      fingerprint: "",
+      exception_type: "",
+      request: nil,
+      environment: nil,
+      timestamp: nil,
+      metadata: {}
+    )
+      @message = message
+      @stack_trace = stack_trace
+      @file = file
+      @function = function
+      @fingerprint = fingerprint
+      @exception_type = exception_type
+      @request = request
+      @environment = environment || default_environment
+      @timestamp = timestamp || Time.now.utc.iso8601
+      @metadata = metadata || {}
+    end
+
+    # Serialize to the standard BugStack API payload.
+    #
+    # @param config [Bugstack::Configuration]
+    # @return [Hash]
+    def to_payload(config)
+      payload = {
+        "apiKey" => config.api_key,
+        "error" => {
+          "message" => @message,
+          "stackTrace" => @stack_trace,
+          "file" => @file,
+          "function" => @function,
+          "fingerprint" => @fingerprint
+        },
+        "environment" => {
+          "language" => @environment[:language],
+          "languageVersion" => @environment[:language_version],
+          "framework" => @environment[:framework].to_s,
+          "frameworkVersion" => @environment[:framework_version].to_s,
+          "os" => @environment[:os],
+          "sdkVersion" => @environment[:sdk_version]
+        },
+        "timestamp" => @timestamp
+      }
+
+      if @request
+        payload["request"] = {
+          "route" => @request[:route].to_s,
+          "method" => @request[:method].to_s
+        }
+      end
+
+      payload["projectId"] = config.project_id unless config.project_id.empty?
+
+      meta = @metadata.dup
+      meta["autoFix"] = true if config.auto_fix
+      payload["metadata"] = meta unless meta.empty?
+
+      payload
+    end
+
+    private
+
+    def default_environment
+      {
+        language: "ruby",
+        language_version: RUBY_VERSION,
+        framework: "",
+        framework_version: "",
+        os: RUBY_PLATFORM,
+        sdk_version: Bugstack::VERSION
+      }
+    end
+  end
+end

data/lib/bugstack/fingerprint.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Bugstack
+  module Fingerprint
+    # Generate a stable SHA-256 fingerprint for an error.
+    #
+    # @param exception_type [String]
+    # @param file [String]
+    # @param function [String]
+    # @param line [Integer, nil]
+    # @return [String] 16-char hex fingerprint
+    def self.generate(exception_type, file, function, line = nil)
+      parts = [exception_type, file, function]
+      parts << line.to_s if line
+      key = parts.join(":")
+      Digest::SHA256.hexdigest(key)[0, 16]
+    end
+
+    # Extract file, function, and line from an exception's backtrace.
+    #
+    # @param exception [Exception]
+    # @return [Array<(String, String, String, Integer)>]
+    #   [exception_type, file, function, line]
+    def self.extract_location(exception)
+      exception_type = exception.class.name
+
+      bt = exception.backtrace
+      return [exception_type, "", "", nil] if bt.nil? || bt.empty?
+
+      # Parse the first backtrace line: "file:line:in `method'"
+      first_line = bt.first
+      if first_line =~ /\A(.+):(\d+):in [`'](.+)'\z/
+        file = Regexp.last_match(1)
+        line = Regexp.last_match(2).to_i
+        function = Regexp.last_match(3)
+        [exception_type, file, function, line]
+      else
+        [exception_type, first_line, "", nil]
+      end
+    end
+
+    # Format an exception's backtrace as a string.
+    #
+    # @param exception [Exception]
+    # @return [String]
+    def self.format_backtrace(exception)
+      bt = exception.backtrace
+      return "#{exception.class}: #{exception.message}" if bt.nil? || bt.empty?
+
+      lines = ["#{exception.class}: #{exception.message}"]
+      bt.each { |frame| lines << "  from #{frame}" }
+      lines.join("\n")
+    end
+  end
+
+  # Client-side error deduplicator.
+  # Prevents the same error (by fingerprint) from being reported
+  # more than once within a configurable time window.
+  class Deduplicator
+    def initialize(window: 300.0)
+      @cache = {}
+      @window = window
+      @mutex = Mutex.new
+    end
+
+    # Check if an error should be sent. Thread-safe.
+    #
+    # @param fingerprint [String]
+    # @return [Boolean]
+    def should_send?(fingerprint)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      @mutex.synchronize do
+        last_sent = @cache[fingerprint]
+        if last_sent && (now - last_sent) < @window
+          return false
+        end
+
+        @cache[fingerprint] = now
+        cleanup(now)
+        true
+      end
+    end
+
+    def clear
+      @mutex.synchronize { @cache.clear }
+    end
+
+    private
+
+    def cleanup(now)
+      @cache.delete_if { |_, ts| (now - ts) >= @window }
+    end
+  end
+end

data/lib/bugstack/integrations/generic.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Bugstack
+  module Integrations
+    # Generic Ruby integration that hooks into at_exit
+    # to capture unhandled exceptions.
+    #
+    # Usage:
+    #   require "bugstack"
+    #   require "bugstack/integrations/generic"
+    #
+    #   Bugstack.init(api_key: "bs_live_...")
+    #   Bugstack::Integrations::Generic.install!
+    module Generic
+      @installed = false
+
+      # Install global exception hooks.
+      def self.install!
+        return if @installed
+
+        @installed = true
+
+        at_exit do
+          if $! && !$!.is_a?(SystemExit)
+            Bugstack.capture_exception($!)
+          end
+        end
+      end
+
+      # Check if hooks are installed.
+      def self.installed?
+        @installed
+      end
+
+      # Reset for testing.
+      def self.reset!
+        @installed = false
+      end
+    end
+  end
+end

data/lib/bugstack/integrations/rails.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Bugstack
+  module Integrations
+    # Rails integration via Railtie for automatic setup
+    # and Rack middleware for exception capture.
+    #
+    # Add to your Gemfile:
+    #   gem "bugstack"
+    #
+    # Configure in an initializer:
+    #   # config/initializers/bugstack.rb
+    #   Bugstack.init do |config|
+    #     config.api_key = Rails.application.credentials.bugstack_api_key
+    #     config.environment = Rails.env
+    #     config.auto_fix = true
+    #   end
+    class Railtie < ::Rails::Railtie
+      initializer "bugstack.middleware" do |app|
+        app.middleware.insert(0, Bugstack::Integrations::RackMiddleware)
+      end
+    end if defined?(::Rails::Railtie)
+
+    # Rack middleware that captures unhandled exceptions.
+    class RackMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        capture_from_rack(e, env)
+        raise
+      end
+
+      private
+
+      def capture_from_rack(exception, env)
+        client = Bugstack.client
+        return unless client
+
+        request = build_request_context(env)
+        client.capture_exception(
+          exception,
+          request: request,
+          metadata: { "framework" => "rails" }
+        )
+      rescue => inner
+        warn "[BugStack] Error capturing exception: #{inner.message}" if client&.config&.debug
+      end
+
+      def build_request_context(env)
+        {
+          route: env["PATH_INFO"].to_s,
+          method: env["REQUEST_METHOD"].to_s
+        }
+      end
+    end
+  end
+end

data/lib/bugstack/integrations/sinatra.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Bugstack
+  module Integrations
+    # Sinatra integration for capturing unhandled exceptions.
+    #
+    # Usage:
+    #   require "sinatra"
+    #   require "bugstack"
+    #   require "bugstack/integrations/sinatra"
+    #
+    #   Bugstack.init(api_key: "bs_live_...")
+    #
+    #   class MyApp < Sinatra::Base
+    #     register Bugstack::Integrations::Sinatra
+    #
+    #     get "/" do
+    #       "Hello!"
+    #     end
+    #   end
+    module Sinatra
+      def self.registered(app)
+        app.error do |exception|
+          client = Bugstack.client
+          if client
+            client.capture_exception(
+              exception,
+              request: {
+                route: request.path_info,
+                method: request.request_method
+              },
+              metadata: { "framework" => "sinatra" }
+            )
+          end
+
+          raise exception
+        end
+      end
+    end
+  end
+end

data/lib/bugstack/transport.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Bugstack
+  # HTTP transport with background thread and retry logic.
+  # Uses stdlib net/http — zero gem dependencies.
+  class Transport
+    def initialize(endpoint:, api_key:, timeout: 5.0, max_retries: 3, debug: false)
+      @endpoint = URI.parse(endpoint)
+      @api_key = api_key
+      @timeout = timeout
+      @max_retries = max_retries
+      @debug = debug
+      @queue = Queue.new
+      @shutdown = false
+      @worker = start_worker
+    end
+
+    # Add a payload to the send queue (non-blocking).
+    #
+    # @param payload [Hash]
+    def enqueue(payload)
+      return if @shutdown
+
+      @queue << payload
+    rescue => e
+      log_debug("Enqueue failed: #{e.message}")
+    end
+
+    # Stop the worker thread and wait for it to finish.
+    def shutdown
+      @shutdown = true
+      @queue << :stop
+      @worker&.join(2)
+    end
+
+    private
+
+    def start_worker
+      Thread.new do
+        loop do
+          payload = @queue.pop
+          break if payload == :stop
+
+          send_with_retry(payload)
+        end
+      end.tap { |t| t.name = "bugstack-transport" if t.respond_to?(:name=) }
+    end
+
+    def send_with_retry(payload)
+      body = JSON.generate(payload)
+
+      @max_retries.times do |attempt|
+        begin
+          http = Net::HTTP.new(@endpoint.host, @endpoint.port)
+          http.use_ssl = @endpoint.scheme == "https"
+          http.open_timeout = @timeout
+          http.read_timeout = @timeout
+
+          request = Net::HTTP::Post.new(@endpoint.request_uri)
+          request["Content-Type"] = "application/json"
+          request["X-BugStack-API-Key"] = @api_key
+          request["X-BugStack-SDK-Version"] = Bugstack::VERSION
+          request.body = body
+
+          response = http.request(request)
+
+          if response.code.to_i < 400
+            log_debug("Event sent successfully")
+            return true
+          end
+
+          log_debug("HTTP #{response.code} (attempt #{attempt + 1})")
+        rescue => e
+          log_debug("Send failed (attempt #{attempt + 1}): #{e.message}")
+        end
+
+        # Exponential backoff: 1s, 2s, 4s
+        sleep(2**attempt) if attempt < @max_retries - 1
+      end
+
+      log_debug("Max retries exceeded, dropping event")
+      false
+    end
+
+    def log_debug(msg)
+      return unless @debug
+
+      warn "[BugStack] #{msg}"
+    end
+  end
+end

data/lib/bugstack/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Bugstack
+  VERSION = "1.0.0"
+end

data/lib/bugstack.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "bugstack/version"
+require_relative "bugstack/configuration"
+require_relative "bugstack/event"
+require_relative "bugstack/fingerprint"
+require_relative "bugstack/transport"
+require_relative "bugstack/client"
+
+# BugStack SDK for Ruby — capture, report, and auto-fix production errors.
+#
+# Usage:
+#   Bugstack.init(api_key: "bs_live_...")
+#
+#   begin
+#     risky_operation
+#   rescue => e
+#     Bugstack.capture_exception(e)
+#   end
+module Bugstack
+  class Error < StandardError; end
+
+  class << self
+    # @return [Bugstack::Client, nil]
+    attr_reader :client
+
+    # Initialize the BugStack SDK.
+    #
+    # @param api_key [String] Your BugStack API key (required)
+    # @yield [config] Optional block for configuration
+    # @return [Bugstack::Client]
+    def init(api_key: nil, **options, &block)
+      config = Configuration.new
+      config.api_key = api_key if api_key
+      options.each { |k, v| config.public_send(:"#{k}=", v) }
+      yield config if block_given?
+
+      @client&.shutdown
+      @client = Client.new(config)
+    end
+
+    # Capture an exception and send it to BugStack.
+    #
+    # @param exception [Exception]
+    # @param request [Hash, nil] Request context
+    # @param metadata [Hash, nil] Additional metadata
+    # @return [Boolean]
+    def capture_exception(exception, request: nil, metadata: nil)
+      unless @client
+        warn "[BugStack] Not initialized. Call Bugstack.init first."
+        return false
+      end
+
+      @client.capture_exception(exception, request: request, metadata: metadata)
+    end
+
+    # Flush pending events and shut down.
+    def shutdown
+      @client&.shutdown
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: bugstack
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- BugStack
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: Capture, report, and auto-fix production errors with BugStack. Zero runtime
+  dependencies. Framework integrations for Rails, Sinatra, and more.
+email:
+- team@bugstack.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/bugstack.rb
+- lib/bugstack/client.rb
+- lib/bugstack/configuration.rb
+- lib/bugstack/event.rb
+- lib/bugstack/fingerprint.rb
+- lib/bugstack/integrations/generic.rb
+- lib/bugstack/integrations/rails.rb
+- lib/bugstack/integrations/sinatra.rb
+- lib/bugstack/transport.rb
+- lib/bugstack/version.rb
+homepage: https://bugstack.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://bugstack.dev
+  source_code_uri: https://github.com/MasonBachmann7/bugstack-ruby
+  changelog_uri: https://github.com/MasonBachmann7/bugstack-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/MasonBachmann7/bugstack-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official BugStack SDK for Ruby
+test_files: []