clamp-analytics 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ffb1d4e3b88c1a033a823f87ca944677956ba43bb9899f17904d4e9009e14998
+  data.tar.gz: '046796aafe3d755145de3304ee15d9ca4210a90d1aa3706b1578c07d94eb797e'
+SHA512:
+  metadata.gz: 5deb502c2bfa8ec1007c11cfb93e736dfd933e216ea4d9bc3c6f580d0da7b5d9575f58ac54ea28ecec069f1adb61e9a59e258c4f7054dd239c230ebc823ad10b
+  data.tar.gz: 57be92f93a604ebea4f33c4ca526fd89bd57866fbee0ea9d705cf7bd6c3eafb613e5337b66f9de6651f5af29bd4330de37831f4703bc536f686b10a8b106c3fd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Clamp
+
+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,99 @@
+# clamp-analytics (Ruby)
+
+Server-side analytics SDK for [Clamp Analytics](https://clamp.sh) in Ruby.
+
+Send tracked events from any Ruby app to Clamp. Works with Rails, Sinatra, Sidekiq workers, scheduled jobs, and anything else that runs Ruby 3.0+ and can make outbound HTTPS calls.
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem "clamp-analytics"
+```
+
+Or:
+
+```bash
+gem install clamp-analytics
+```
+
+Ruby 3.0+ supported. The gem uses only the standard library (`net/http`, `json`, `time`, `uri`).
+
+## Quick start
+
+```ruby
+require "clamp_analytics"
+
+Clamp::Analytics.init(
+  project_id: "proj_xxx",
+  api_key: ENV.fetch("CLAMP_API_KEY")
+)
+
+# Simple event
+Clamp::Analytics.track("signup", properties: { plan: "pro", method: "email" })
+
+# Link a server event to a browser visitor
+Clamp::Analytics.track(
+  "subscription_started",
+  properties: {
+    plan: "pro",
+    total: Clamp::Analytics::Money.new(29.00, "USD")
+  },
+  anonymous_id: "aid_xxx"
+)
+```
+
+Get a server API key at <https://clamp.sh/dashboard> (Settings → API Keys, format `sk_proj_...`). Read it from the environment; never commit it.
+
+## API
+
+### `Clamp::Analytics.init(project_id:, api_key:, endpoint: nil)`
+
+Initializes the SDK. Call once at app boot (Rails initializer, Sinatra setup, Sidekiq server middleware). State is held at the module level behind a Mutex, so it's safe across threads.
+
+`endpoint` is optional and overrides the default `https://api.clamp.sh`.
+
+### `Clamp::Analytics.track(name, properties: {}, anonymous_id: nil, timestamp: nil)`
+
+Sends a server event. Returns `true` on success.
+
+- **`name`**: event name string. Examples: `"signup"`, `"subscription_started"`.
+- **`properties`**: optional hash. Values may be `String`, `Integer`, `Float`, `true`/`false`, or `Money`. Other types raise `ArgumentError`.
+- **`anonymous_id`**: optional string. Links the server event to a browser visitor.
+- **`timestamp`**: optional `Time` (non-UTC times are normalized to UTC) or ISO 8601 string. If omitted, uses `Time.now.utc`.
+
+Raises `Clamp::Analytics::HTTPError` on a non-2xx response, `Clamp::Analytics::NotInitializedError` if `init` wasn't called.
+
+### `Clamp::Analytics::Money`
+
+```ruby
+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).
+
+## Framework integrations
+
+Per-framework integration patterns (Rails initializer + concern, Sinatra helper, Sidekiq middleware) are documented at <https://clamp.sh/docs/sdk/ruby>.
+
+## Errors
+
+The gem is synchronous and raises on failure. There are no automatic retries. If you want fire-and-forget behaviour, rescue around the call:
+
+```ruby
+begin
+  Clamp::Analytics.track("subscription_started", properties: ...)
+rescue Clamp::Analytics::Error => e
+  Rails.logger.error("clamp: #{e.message}")
+end
+```
+
+For high-throughput webhook handlers, defer the call to a Sidekiq job.
+
+## Links
+
+- RubyGems: <https://rubygems.org/gems/clamp-analytics>
+- Docs: <https://clamp.sh/docs/sdk/ruby>
+- Source: <https://github.com/clamp-sh/analytics-ruby>
+- Issues: <https://github.com/clamp-sh/analytics-ruby/issues>

data/lib/clamp_analytics/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Clamp
+  module Analytics
+    # Base class for all Clamp SDK errors.
+    class Error < StandardError; end
+
+    # Raised when track is called before init.
+    class NotInitializedError < Error; end
+
+    # Raised when the ingestion API returns a non-2xx response.
+    class HTTPError < Error
+      attr_reader :status_code, :body
+
+      def initialize(status_code, body)
+        @status_code = status_code
+        @body = body
+        super("clamp_analytics: #{status_code} #{body}")
+      end
+    end
+  end
+end

data/lib/clamp_analytics/money.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Clamp
+  module Analytics
+    # A typed monetary value attached to any event property.
+    #
+    #   Clamp::Analytics.track('purchase',
+    #     properties: {
+    #       plan: 'pro',
+    #       total: Clamp::Analytics::Money.new(29.00, 'USD'),
+    #       tax: Clamp::Analytics::Money.new(4.35, 'USD')
+    #     }
+    #   )
+    Money = Struct.new(:amount, :currency) do
+      def to_wire
+        { amount: amount, currency: currency }
+      end
+    end
+  end
+end

data/lib/clamp_analytics/version.rb

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

data/lib/clamp_analytics.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "time"
+require "uri"
+
+require_relative "clamp_analytics/version"
+require_relative "clamp_analytics/money"
+require_relative "clamp_analytics/errors"
+
+# Server-side analytics SDK for Clamp.
+#
+#   require "clamp_analytics"
+#
+#   Clamp::Analytics.init(
+#     project_id: "proj_xxx",
+#     api_key: ENV.fetch("CLAMP_API_KEY")
+#   )
+#
+#   Clamp::Analytics.track("signup", properties: { plan: "pro", method: "email" })
+module Clamp
+  module Analytics
+    DEFAULT_ENDPOINT = "https://api.clamp.sh"
+
+    @config = nil
+    @transport = nil
+    @mutex = Mutex.new
+
+    class << self
+      # Initialize the SDK. Call once at application boot (Rails initializer,
+      # Sinatra setup block, etc.).
+      def init(project_id:, api_key:, endpoint: nil)
+        @mutex.synchronize do
+          @config = {
+            project_id: project_id,
+            api_key: api_key,
+            endpoint: endpoint || DEFAULT_ENDPOINT
+          }
+        end
+      end
+
+      # Track a server-side event.
+      #
+      # @param name [String] event name
+      # @param properties [Hash] optional, values may be String, Integer,
+      #   Float, true/false, or Money
+      # @param anonymous_id [String, nil] optional, links to a browser visitor
+      # @param timestamp [Time, String, nil] optional; if omitted, uses Time.now.utc
+      # @raise [NotInitializedError] if init has not been called
+      # @raise [HTTPError] on non-2xx response
+      # @return [true]
+      def track(name, properties: {}, anonymous_id: nil, timestamp: nil)
+        cfg = @mutex.synchronize { @config }
+        raise NotInitializedError, "clamp_analytics: call Clamp::Analytics.init before track" if cfg.nil?
+
+        payload = { p: cfg[:project_id], name: name }
+        payload[:anonymousId] = anonymous_id unless anonymous_id.nil?
+        payload[:properties] = serialize_properties(properties) unless properties.empty?
+        payload[:timestamp] = serialize_timestamp(timestamp)
+
+        response = transport.call(
+          "#{cfg[:endpoint]}/e/s",
+          { "content-type" => "application/json", "x-clamp-key" => cfg[:api_key] },
+          JSON.generate(payload)
+        )
+
+        status = response[:status]
+        if status < 200 || status >= 300
+          raise HTTPError.new(status, response[:body].to_s)
+        end
+
+        true
+      end
+
+      # Override the transport. Used by tests; pass nil to restore the default.
+      def transport=(transport)
+        @mutex.synchronize { @transport = transport }
+      end
+
+      # Reset all SDK state. Intended for tests.
+      def reset!
+        @mutex.synchronize do
+          @config = nil
+          @transport = nil
+        end
+      end
+
+      private
+
+      def transport
+        @transport || method(:default_transport)
+      end
+
+      def default_transport(url, headers, body)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 5
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = body
+
+        response = http.request(request)
+        { status: response.code.to_i, body: response.body || "" }
+      end
+
+      def serialize_properties(properties)
+        properties.each_with_object({}) do |(key, value), out|
+          out[key] = case value
+                    when Money
+                      value.to_wire
+                    when String, Integer, Float, TrueClass, FalseClass
+                      value
+                    else
+                      raise ArgumentError,
+                            "clamp_analytics: property '#{key}' has unsupported type #{value.class}. " \
+                            "Allowed: String, Integer, Float, true/false, Money."
+                    end
+        end
+      end
+
+      def serialize_timestamp(timestamp)
+        case timestamp
+        when nil
+          Time.now.utc.iso8601
+        when Time
+          timestamp.utc.iso8601
+        when String
+          timestamp
+        else
+          raise ArgumentError, "clamp_analytics: timestamp must be Time or String, got #{timestamp.class}"
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: clamp-analytics
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Clamp Analytics
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.20'
+description: Send tracked events from Ruby apps (Rails, Sinatra, Sidekiq, etc.) to
+  Clamp Analytics.
+email:
+- sidney@mail.clamp.sh
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/clamp_analytics.rb
+- lib/clamp_analytics/errors.rb
+- lib/clamp_analytics/money.rb
+- lib/clamp_analytics/version.rb
+homepage: https://clamp.sh
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://clamp.sh
+  source_code_uri: https://github.com/clamp-sh/analytics-ruby
+  documentation_uri: https://clamp.sh/docs/sdk/ruby
+  bug_tracker_uri: https://github.com/clamp-sh/analytics-ruby/issues
+  changelog_uri: https://github.com/clamp-sh/analytics-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Server-side analytics SDK for Clamp.
+test_files: []