clamp-analytics 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffb1d4e3b88c1a033a823f87ca944677956ba43bb9899f17904d4e9009e14998
-  data.tar.gz: '046796aafe3d755145de3304ee15d9ca4210a90d1aa3706b1578c07d94eb797e'
+  metadata.gz: 1c17e252fdceaf3760f959252b2ac2196a03c3980b7d95d017a3021f72620fa4
+  data.tar.gz: 7e351406203ac370254d7ca34e2fd2fe323fa44bd21d9608c8734b7dc32fddf2
 SHA512:
-  metadata.gz: 5deb502c2bfa8ec1007c11cfb93e736dfd933e216ea4d9bc3c6f580d0da7b5d9575f58ac54ea28ecec069f1adb61e9a59e258c4f7054dd239c230ebc823ad10b
-  data.tar.gz: 57be92f93a604ebea4f33c4ca526fd89bd57866fbee0ea9d705cf7bd6c3eafb613e5337b66f9de6651f5af29bd4330de37831f4703bc536f686b10a8b106c3fd
+  metadata.gz: 30a8aabb56447212110845cadc9e618b4787a4d41c879ae7e3807ece111f61fff5c73eed60e5d04d3cb515c936e8c556c3c210bdd0a186917fcc09497709daeb
+  data.tar.gz: c0a0debb406622311a582cd8cb17b94a8c9e2871d577ffcdf8492426a1f9880c11a034aca35159cafc56e6f7ac44c05ce8702cc63af2ff892701fe334603e581

data/README.md

@@ -73,6 +73,25 @@ Clamp::Analytics::Money.new(29.00, "USD")
 
 A typed monetary value. `amount` is in major units (29.00, not 2900). `currency` is an ISO 4217 code (uppercase, three letters).
 
+### `Clamp::Analytics.capture_error(exception, context: {}, anonymous_id: nil, timestamp: nil)`
+
+Sends an exception as a `$error` event. Convenience over `track` that extracts message, class name, and backtrace from the exception. The server adds a stable fingerprint at ingest so the same bug groups across occurrences.
+
+```ruby
+begin
+  process_webhook(payload)
+rescue => e
+  Clamp::Analytics.capture_error(e, context: { webhook: "stripe" })
+end
+```
+
+- **`exception`**: any `Exception` instance. Stack via `exception.backtrace`, type via `exception.class.name`.
+- **`context`**: optional flat hash of additional properties. Values must be primitives (`String`, `Integer`, `Float`, `true`/`false`); the reserved key `:handled` is ignored.
+- **`anonymous_id`**: optional. Links the error to a browser visitor.
+- **`timestamp`**: optional `Time` or ISO 8601 string.
+
+Same return value and exceptions as `track`. Lengths are capped (`error.message` 1KB, `error.type` 64 chars, `error.stack` 16KB) to match server-side limits.
+
 ## Framework integrations
 
 Per-framework integration patterns (Rails initializer + concern, Sinatra helper, Sidekiq middleware) are documented at <https://clamp.sh/docs/sdk/ruby>.

data/lib/clamp_analytics/version.rb

@@ -2,6 +2,6 @@
 
 module Clamp
   module Analytics
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/clamp_analytics.rb

@@ -73,6 +73,49 @@ module Clamp
         true
       end
 
+      # Capture an exception as a `$error` event. Convenience wrapper that
+      # extracts message/type/backtrace from the exception and forwards to
+      # {.track}. The server adds a stable fingerprint at ingest so the same
+      # bug groups across occurrences.
+      #
+      #   begin
+      #     process_webhook(payload)
+      #   rescue => e
+      #     Clamp::Analytics.capture_error(e, context: { webhook: "stripe" })
+      #   end
+      #
+      # @param exception [Exception] the exception to capture
+      # @param context [Hash] optional flat hash of additional properties.
+      #   Values must be primitives (String, Integer, Float, true/false).
+      #   The reserved key `:handled` is ignored if present.
+      # @param anonymous_id [String, nil] optional, links to a browser visitor
+      # @param timestamp [Time, String, nil] optional
+      # @raise [NotInitializedError] if init has not been called
+      # @raise [HTTPError] on non-2xx response
+      # @return [true]
+      def capture_error(exception, context: {}, anonymous_id: nil, timestamp: nil)
+        message = (exception.message || "Unknown error")[0, 1024]
+        error_type = exception.class.name[0, 64]
+        backtrace = (exception.backtrace || []).join("\n")
+        stack = backtrace.empty? ? "" : backtrace[0, 16384]
+
+        properties = {
+          "error.message" => message,
+          "error.type" => error_type,
+          "error.stack" => stack,
+          "error.handled" => true
+        }
+        context.each do |k, v|
+          key = k.to_s
+          next if key == "handled"
+          if v.is_a?(String) || v.is_a?(Integer) || v.is_a?(Float) || v == true || v == false
+            properties[key] = v
+          end
+        end
+
+        track("$error", properties: properties, anonymous_id: anonymous_id, timestamp: timestamp)
+      end
+
       # Override the transport. Used by tests; pass nil to restore the default.
       def transport=(transport)
         @mutex.synchronize { @transport = transport }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clamp-analytics
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Clamp Analytics
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-30 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec