Add support for custom notifications without exceptions

Allow notify() and notify_sync() to accept String messages or Hash
payloads in addition to Exception objects. This enables sending custom
alerts, warnings, or informational notices without needing to raise
an exception.

Usage:
  Checkend.notify("Rate limit exceeded", error_class: "RateLimitError")
  Checkend.notify({ error_class: "Alert", message: "Something happened" })

Author: geetfun

lib/checkend.rb

@@ -77,45 +77,64 @@ def flush(timeout: nil)
 
     # ========== Primary API ==========
 
-    # Report an exception to Checkend
+    # Report an error or custom notification to Checkend
     #
-    # @param exception [Exception] the exception to report
+    # Accepts an Exception, String message, or Hash with error details.
+    #
+    # @param exception_or_message [Exception, String, Hash] the error to report
+    #   - Exception: reports the exception with its class, message, and backtrace
+    #   - String: reports a custom notification with the string as the message
+    #   - Hash: reports a custom notification with :error_class, :message, :backtrace
+    # @param error_class [String] custom error class (only used with String messages)
     # @param context [Hash] additional context data
     # @param request [Hash] request information
     # @param user [Hash] user information
     # @param fingerprint [String] custom fingerprint for grouping
     # @param tags [Array<String>] tags for filtering
     # @return [Hash, nil] the API response or nil if not sent
-    def notify(exception, context: {}, request: nil, user: nil, fingerprint: nil, tags: [])
+    #
+    # @example Report an exception
+    #   Checkend.notify(exception)
+    #
+    # @example Report a custom message
+    #   Checkend.notify("User exceeded rate limit", error_class: "RateLimitExceeded")
+    #
+    # @example Report with a hash
+    #   Checkend.notify(error_class: "CustomAlert", message: "Something happened")
+    #
+    def notify(exception_or_message, error_class: nil, context: {}, request: nil, user: nil, fingerprint: nil, tags: [])
       return nil unless should_notify?
-      return nil if configuration.ignore_exception?(exception)
 
-      notice = NoticeBuilder.build(
-        exception: exception,
+      notice = build_notice(
+        exception_or_message,
+        error_class: error_class,
         context: context,
         request: request,
         user: user,
         fingerprint: fingerprint,
         tags: tags
       )
+      return nil unless notice
 
       # Run before_notify callbacks
       return nil unless before_notify_callbacks_allow?(notice)
 
       send_notice(notice)
     end
 
-    # Report an exception synchronously (blocking)
+    # Report an error or custom notification synchronously (blocking)
     #
     # Useful for CLI tools, tests, or when you need confirmation of delivery.
     #
-    # @param exception [Exception] the exception to report
+    # @param exception_or_message [Exception, String, Hash] the error to report
     # @param options [Hash] same options as notify
     # @return [Hash, nil] the API response or nil if not sent
-    def notify_sync(exception, **options)
+    def notify_sync(exception_or_message, **options)
       return nil unless should_notify?
 
-      notice = NoticeBuilder.build(exception: exception, **options)
+      notice = build_notice(exception_or_message, **options)
+      return nil unless notice
+
       client.send_notice(notice)
     end
 
@@ -188,6 +207,24 @@ def should_notify?
       true
     end
 
+    def build_notice(exception_or_message, error_class: nil, context: {}, request: nil, user: nil, fingerprint: nil, tags: [])
+      options = { context: context, request: request, user: user, fingerprint: fingerprint, tags: tags }
+
+      case exception_or_message
+      when Exception
+        return nil if configuration.ignore_exception?(exception_or_message)
+
+        NoticeBuilder.build(exception: exception_or_message, **options)
+      when String
+        NoticeBuilder.build_from_message(exception_or_message, error_class: error_class, **options)
+      when Hash
+        NoticeBuilder.build_from_hash(exception_or_message, **options)
+      else
+        log_debug("notify called with unsupported type: #{exception_or_message.class}")
+        nil
+      end
+    end
+
     def before_notify_callbacks_allow?(notice)
       configuration.before_notify.each do |callback|
         result = callback.call(notice)

lib/checkend/notice_builder.rb

@@ -9,6 +9,9 @@ class NoticeBuilder
     MAX_BACKTRACE_LINES = 100
     MAX_MESSAGE_LENGTH = 10_000
 
+    # Default error class for custom notifications without an exception
+    DEFAULT_ERROR_CLASS = 'Checkend::Notice'
+
     class << self
       # Build a Notice from an exception
       #
@@ -40,6 +43,70 @@ def build(exception:, context: {}, request: nil, user: nil, fingerprint: nil, ta
         notice
       end
 
+      # Build a Notice from a message string (custom notification without exception)
+      #
+      # @param message [String] the notification message
+      # @param error_class [String] custom error class name (defaults to 'Checkend::Notice')
+      # @param context [Hash] additional context data
+      # @param request [Hash] request information
+      # @param user [Hash] user information
+      # @param fingerprint [String] custom fingerprint for grouping
+      # @param tags [Array<String>] tags for filtering
+      # @return [Notice] the constructed notice
+      def build_from_message(message, error_class: nil, context: {}, request: nil, user: nil, fingerprint: nil, tags: [])
+        notice = Notice.new
+
+        # Error info - no backtrace for custom notifications
+        notice.error_class = error_class || DEFAULT_ERROR_CLASS
+        notice.message = truncate_message(message)
+        notice.backtrace = []
+        notice.fingerprint = fingerprint
+        notice.tags = Array(tags)
+
+        # Merge thread-local context with provided context
+        notice.context = merge_context(context)
+        notice.user = user || thread_local_user
+        notice.request = request || {}
+
+        # Environment
+        notice.environment = Checkend.configuration.environment
+
+        notice
+      end
+
+      # Build a Notice from a hash (custom notification with full control)
+      #
+      # @param hash [Hash] the notification data
+      # @option hash [String] :error_class custom error class name
+      # @option hash [String] :message the notification message
+      # @option hash [Array<String>] :backtrace optional backtrace
+      # @param context [Hash] additional context data
+      # @param request [Hash] request information
+      # @param user [Hash] user information
+      # @param fingerprint [String] custom fingerprint for grouping
+      # @param tags [Array<String>] tags for filtering
+      # @return [Notice] the constructed notice
+      def build_from_hash(hash, context: {}, request: nil, user: nil, fingerprint: nil, tags: [])
+        notice = Notice.new
+
+        # Error info from hash
+        notice.error_class = hash[:error_class] || hash['error_class'] || DEFAULT_ERROR_CLASS
+        notice.message = truncate_message(hash[:message] || hash['message'])
+        notice.backtrace = clean_backtrace(hash[:backtrace] || hash['backtrace'] || [])
+        notice.fingerprint = fingerprint || hash[:fingerprint] || hash['fingerprint']
+        notice.tags = Array(tags.empty? ? (hash[:tags] || hash['tags'] || []) : tags)
+
+        # Merge thread-local context with provided context
+        notice.context = merge_context(context)
+        notice.user = user || thread_local_user
+        notice.request = request || {}
+
+        # Environment
+        notice.environment = Checkend.configuration.environment
+
+        notice
+      end
+
       private
 
       def clean_backtrace(backtrace)

test/checkend/notice_builder_test.rb

@@ -162,4 +162,174 @@ def test_handles_nil_backtrace
 
     assert_empty notice.backtrace
   end
+
+  # ========== build_from_message tests ==========
+
+  def test_build_from_message_creates_notice
+    notice = Checkend::NoticeBuilder.build_from_message('Something went wrong')
+
+    assert_equal 'Checkend::Notice', notice.error_class
+    assert_equal 'Something went wrong', notice.message
+    assert_empty notice.backtrace
+  end
+
+  def test_build_from_message_with_custom_error_class
+    notice = Checkend::NoticeBuilder.build_from_message(
+      'Rate limit exceeded',
+      error_class: 'RateLimitError'
+    )
+
+    assert_equal 'RateLimitError', notice.error_class
+    assert_equal 'Rate limit exceeded', notice.message
+  end
+
+  def test_build_from_message_with_context
+    notice = Checkend::NoticeBuilder.build_from_message(
+      'Alert message',
+      context: { severity: 'high', source: 'api' }
+    )
+
+    assert_equal 'high', notice.context[:severity]
+    assert_equal 'api', notice.context[:source]
+  end
+
+  def test_build_from_message_with_user
+    notice = Checkend::NoticeBuilder.build_from_message(
+      'User alert',
+      user: { id: 123, email: 'test@example.com' }
+    )
+
+    assert_equal 123, notice.user[:id]
+    assert_equal 'test@example.com', notice.user[:email]
+  end
+
+  def test_build_from_message_with_tags
+    notice = Checkend::NoticeBuilder.build_from_message(
+      'Tagged alert',
+      tags: %w[urgent security]
+    )
+
+    assert_equal %w[urgent security], notice.tags
+  end
+
+  def test_build_from_message_with_fingerprint
+    notice = Checkend::NoticeBuilder.build_from_message(
+      'Custom fingerprint',
+      fingerprint: 'my-custom-fp'
+    )
+
+    assert_equal 'my-custom-fp', notice.fingerprint
+  end
+
+  def test_build_from_message_includes_environment
+    notice = Checkend::NoticeBuilder.build_from_message('Test')
+
+    assert_equal 'test', notice.environment
+  end
+
+  def test_build_from_message_truncates_long_messages
+    long_message = 'a' * 15_000
+
+    notice = Checkend::NoticeBuilder.build_from_message(long_message)
+
+    assert_equal 10_000, notice.message.length
+    assert notice.message.end_with?('...')
+  end
+
+  def test_build_from_message_merges_thread_local_context
+    Thread.current[:checkend_context] = { existing: 'value' }
+
+    notice = Checkend::NoticeBuilder.build_from_message('Test', context: { new_key: 'new' })
+
+    assert_equal 'value', notice.context[:existing]
+    assert_equal 'new', notice.context[:new_key]
+  ensure
+    Thread.current[:checkend_context] = nil
+  end
+
+  # ========== build_from_hash tests ==========
+
+  def test_build_from_hash_creates_notice
+    notice = Checkend::NoticeBuilder.build_from_hash({
+      error_class: 'CustomError',
+      message: 'Something happened'
+    })
+
+    assert_equal 'CustomError', notice.error_class
+    assert_equal 'Something happened', notice.message
+  end
+
+  def test_build_from_hash_with_string_keys
+    notice = Checkend::NoticeBuilder.build_from_hash({
+      'error_class' => 'StringKeyError',
+      'message' => 'Using string keys'
+    })
+
+    assert_equal 'StringKeyError', notice.error_class
+    assert_equal 'Using string keys', notice.message
+  end
+
+  def test_build_from_hash_defaults_error_class
+    notice = Checkend::NoticeBuilder.build_from_hash({ message: 'Just a message' })
+
+    assert_equal 'Checkend::Notice', notice.error_class
+  end
+
+  def test_build_from_hash_with_backtrace
+    notice = Checkend::NoticeBuilder.build_from_hash({
+      error_class: 'CustomError',
+      message: 'With backtrace',
+      backtrace: ['file.rb:10:in `method`', 'file.rb:20:in `caller`']
+    })
+
+    assert_equal 2, notice.backtrace.length
+    assert_includes notice.backtrace.first, 'file.rb:10'
+  end
+
+  def test_build_from_hash_with_fingerprint_in_hash
+    notice = Checkend::NoticeBuilder.build_from_hash({
+      error_class: 'CustomError',
+      message: 'Test',
+      fingerprint: 'hash-fingerprint'
+    })
+
+    assert_equal 'hash-fingerprint', notice.fingerprint
+  end
+
+  def test_build_from_hash_option_fingerprint_overrides_hash
+    notice = Checkend::NoticeBuilder.build_from_hash(
+      { error_class: 'CustomError', fingerprint: 'hash-fp' },
+      fingerprint: 'option-fp'
+    )
+
+    assert_equal 'option-fp', notice.fingerprint
+  end
+
+  def test_build_from_hash_with_tags_in_hash
+    notice = Checkend::NoticeBuilder.build_from_hash({
+      error_class: 'CustomError',
+      message: 'Test',
+      tags: %w[from hash]
+    })
+
+    assert_equal %w[from hash], notice.tags
+  end
+
+  def test_build_from_hash_option_tags_overrides_hash
+    notice = Checkend::NoticeBuilder.build_from_hash(
+      { error_class: 'CustomError', tags: %w[from hash] },
+      tags: %w[from options]
+    )
+
+    assert_equal %w[from options], notice.tags
+  end
+
+  def test_build_from_hash_with_context
+    notice = Checkend::NoticeBuilder.build_from_hash(
+      { error_class: 'CustomError' },
+      context: { key: 'value' }
+    )
+
+    assert_equal 'value', notice.context[:key]
+  end
 end