sessionvision 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f94cb9100274b790c0eeff2de556da99bd0a0f45980e2ddf7f350c7ab119026f
+  data.tar.gz: ea6cce1a64cf136ef40cf37d397a908295ee91fc6c63368e47d211f280c5a813
+SHA512:
+  metadata.gz: 0bbaa3ccd591fcccf34e737a6b1469090d44742d813a8261e3b002e31396dfa289f1552683bfbce69ab25e052db749a13c451bed788f7a60206293fab8b54eff
+  data.tar.gz: 1ff05e7cd2de691da8fb71b471a595c4f592be2b9bb1e556913691320cec6a4bccc7c2dbd45c42dccf50241e06f921bf44a1dd37da0adf8e1ab08ab1d86efc5d

data/lib/sessionvision/client.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "logger"
+
+module SessionVision
+  class Client
+    def initialize(config)
+      @config = config
+      @lock = Mutex.new
+      @registered = {}
+      @shutdown_called = false
+
+      @logger = config.debug ? Logger.new($stdout, progname: "sessionvision") : nil
+
+      @transport = Transport.new(
+        ingest_host: config.ingest_host,
+        max_retries: config.max_retries,
+        retry_delays: config.retry_delays,
+        gzip_threshold: config.gzip_threshold,
+        on_error: config.on_error,
+        logger: @logger
+      )
+
+      @buffer = EventBuffer.new(
+        flush_size: config.flush_size,
+        flush_interval: config.flush_interval,
+        send_fn: method(:send_batch),
+        logger: @logger
+      )
+      @buffer.start
+
+      at_exit { shutdown }
+
+      @logger&.debug("Client initialized (host=#{config.ingest_host})")
+    end
+
+    def capture(event_name, user_id: nil, anonymous_id: nil, session_id: nil, properties: {})
+      raise ArgumentError, "event_name must be a non-empty string" unless event_name.is_a?(String) && !event_name.empty?
+      raise ArgumentError, "Either user_id or anonymous_id is required" if user_id.nil? && anonymous_id.nil?
+
+      merged_props = @lock.synchronize { @registered.merge(properties || {}) }
+
+      event = {
+        "event" => event_name,
+        "timestamp" => (Time.now.to_f * 1000).to_i,
+        "properties" => merged_props,
+        "sessionId" => session_id || SecureRandom.uuid
+      }
+      event["userId"] = user_id if user_id
+      event["anonymousId"] = anonymous_id if anonymous_id
+
+      @logger&.debug("Event captured: #{event_name}")
+      @buffer.push(event)
+    end
+
+    def identify(user_id, **traits)
+      raise ArgumentError, "user_id must be a non-empty string" unless user_id.is_a?(String) && !user_id.empty?
+
+      capture("$identify", user_id: user_id, properties: traits.transform_keys(&:to_s))
+    end
+
+    def register(**properties)
+      @lock.synchronize do
+        properties.each { |k, v| @registered[k.to_s] = v }
+      end
+    end
+
+    def register_once(**properties)
+      @lock.synchronize do
+        properties.each do |k, v|
+          key = k.to_s
+          @registered[key] = v unless @registered.key?(key)
+        end
+      end
+    end
+
+    def flush
+      @buffer.flush
+    end
+
+    def shutdown
+      @lock.synchronize do
+        return if @shutdown_called
+
+        @shutdown_called = true
+      end
+
+      @logger&.debug("Shutting down")
+      @buffer.shutdown
+    end
+
+    def reset
+      @lock.synchronize { @registered.clear }
+    end
+
+    private
+
+    def send_batch(events)
+      @transport.send_batch(@config.project_token, events)
+    end
+  end
+end

data/lib/sessionvision/config.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SessionVision
+  class Config
+    attr_reader :project_token, :ingest_host, :flush_size, :flush_interval,
+                :max_retries, :retry_delays, :gzip_threshold, :debug, :on_error
+
+    def initialize(
+      project_token:,
+      ingest_host: "https://app.sessionvision.com",
+      flush_size: 10,
+      flush_interval: 5,
+      max_retries: 3,
+      retry_delays: [1, 2, 4],
+      gzip_threshold: 1024,
+      debug: false,
+      on_error: nil
+    )
+      raise ArgumentError, "project_token is required" if project_token.nil? || project_token.empty?
+
+      @project_token = project_token
+      @ingest_host = ingest_host.chomp("/")
+      @flush_size = flush_size
+      @flush_interval = flush_interval
+      @max_retries = max_retries
+      @retry_delays = retry_delays
+      @gzip_threshold = gzip_threshold
+      @debug = debug
+      @on_error = on_error
+    end
+  end
+end

data/lib/sessionvision/event_buffer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SessionVision
+  class EventBuffer
+    def initialize(flush_size:, flush_interval:, send_fn:, logger: nil)
+      @flush_size = flush_size
+      @flush_interval = flush_interval
+      @send_fn = send_fn
+      @logger = logger
+
+      @buffer = []
+      @lock = Mutex.new
+      @stop = false
+      @timer_thread = nil
+    end
+
+    def start
+      return if @timer_thread
+
+      @lock.synchronize { @stop = false }
+      @timer_thread = Thread.new { run_timer }
+      @timer_thread.abort_on_exception = false
+    end
+
+    def push(event)
+      should_flush = false
+
+      @lock.synchronize do
+        @buffer << event
+        should_flush = @buffer.length >= @flush_size
+      end
+
+      flush if should_flush
+    end
+
+    def flush
+      events = nil
+
+      @lock.synchronize do
+        return if @buffer.empty?
+
+        events = @buffer.dup
+        @buffer.clear
+      end
+
+      @logger&.debug("Flushing #{events.length} events")
+      @send_fn.call(events)
+    end
+
+    def shutdown
+      @lock.synchronize { @stop = true }
+
+      if @timer_thread
+        @timer_thread.join(10)
+        @timer_thread = nil
+      end
+
+      flush
+    end
+
+    private
+
+    def run_timer
+      loop do
+        sleep(@flush_interval)
+
+        should_stop = @lock.synchronize { @stop }
+        break if should_stop
+
+        flush
+      end
+    rescue StandardError => e
+      @logger&.error("Flush timer error: #{e.message}")
+    end
+  end
+end

data/lib/sessionvision/transport.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "zlib"
+require "stringio"
+require "logger"
+
+module SessionVision
+  class Transport
+    TIMEOUT_OPEN = 10
+    TIMEOUT_READ = 15
+
+    def initialize(ingest_host:, max_retries: 3, retry_delays: [1, 2, 4],
+                   gzip_threshold: 1024, on_error: nil, logger: nil)
+      @url = URI("#{ingest_host}/api/v1/ingest/events")
+      @max_retries = max_retries
+      @retry_delays = retry_delays
+      @gzip_threshold = gzip_threshold
+      @on_error = on_error
+      @logger = logger
+    end
+
+    def send_batch(project_token, events)
+      payload = JSON.generate({ "projectToken" => project_token, "events" => events })
+      body = payload.encode("utf-8")
+      headers = { "Content-Type" => "application/json" }
+
+      if body.bytesize > @gzip_threshold
+        body = gzip_compress(body)
+        headers["Content-Encoding"] = "gzip"
+      end
+
+      last_error = nil
+
+      (1 + @max_retries).times do |attempt|
+        begin
+          response = post(body, headers)
+          status = response.code.to_i
+
+          if status >= 200 && status < 300
+            @logger&.debug("Batch sent successfully (#{events.length} events)")
+            return true
+          elsif status >= 400 && status < 500
+            @logger&.warn("Client error #{status}, not retrying")
+            call_on_error(RuntimeError.new("HTTP #{status}"), project_token, events)
+            return false
+          else
+            last_error = RuntimeError.new("HTTP #{status}")
+            @logger&.debug("Server error #{status} on attempt #{attempt + 1}/#{1 + @max_retries}")
+          end
+        rescue StandardError => e
+          last_error = e
+          @logger&.debug("Network error on attempt #{attempt + 1}/#{1 + @max_retries}: #{e.message}")
+        end
+
+        if attempt < @max_retries
+          delay = attempt < @retry_delays.length ? @retry_delays[attempt] : @retry_delays.last
+          sleep(delay)
+        end
+      end
+
+      @logger&.warn("Failed to send batch after #{@max_retries} retries")
+      call_on_error(last_error, project_token, events) if last_error
+      false
+    end
+
+    private
+
+    def post(body, headers)
+      http = Net::HTTP.new(@url.host, @url.port)
+      http.use_ssl = @url.scheme == "https"
+      http.open_timeout = TIMEOUT_OPEN
+      http.read_timeout = TIMEOUT_READ
+
+      request = Net::HTTP::Post.new(@url.request_uri, headers)
+      request.body = body
+      http.request(request)
+    end
+
+    def gzip_compress(data)
+      io = StringIO.new
+      io.set_encoding("BINARY")
+      gz = Zlib::GzipWriter.new(io)
+      gz.write(data)
+      gz.close
+      io.string
+    end
+
+    def call_on_error(error, project_token, events)
+      return unless @on_error
+
+      @on_error.call(error, { project_token: project_token, events: events })
+    rescue StandardError => e
+      @logger&.error("on_error callback raised: #{e.message}")
+    end
+  end
+end

data/lib/sessionvision/version.rb

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

data/lib/sessionvision.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "sessionvision/version"
+require_relative "sessionvision/config"
+require_relative "sessionvision/transport"
+require_relative "sessionvision/event_buffer"
+require_relative "sessionvision/client"
+
+# Session Vision server-side Ruby SDK.
+#
+# Usage:
+#
+#   SessionVision.init("proj_xxx", ingest_host: "https://app.sessionvision.com")
+#   SessionVision.capture("purchase", user_id: "user_123", properties: { amount: 99.99 })
+#   SessionVision.shutdown
+#
+module SessionVision
+  class Error < StandardError; end
+
+  @client = nil
+  @mutex = Mutex.new
+
+  class << self
+    def init(project_token, **options)
+      @mutex.synchronize do
+        @client&.shutdown
+        config = Config.new(project_token: project_token, **options)
+        @client = Client.new(config)
+      end
+    end
+
+    def capture(event_name, user_id: nil, anonymous_id: nil, session_id: nil, properties: {})
+      client.capture(event_name, user_id: user_id, anonymous_id: anonymous_id,
+                                 session_id: session_id, properties: properties)
+    end
+
+    def identify(user_id, **traits)
+      client.identify(user_id, **traits)
+    end
+
+    def register(**properties)
+      client.register(**properties)
+    end
+
+    def register_once(**properties)
+      client.register_once(**properties)
+    end
+
+    def flush
+      client.flush
+    end
+
+    def shutdown
+      @mutex.synchronize do
+        return unless @client
+
+        @client.shutdown
+        @client = nil
+      end
+    end
+
+    def reset
+      client.reset
+    end
+
+    private
+
+    def client
+      raise Error, "SessionVision.init must be called before using the SDK" unless @client
+
+      @client
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: sessionvision
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- sessionvision
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Server-side Ruby SDK for sessionvision product analytics. Track events,
+  identify users, and send data to your sessionvision instance.
+email:
+- support@sessionvision.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/sessionvision.rb
+- lib/sessionvision/client.rb
+- lib/sessionvision/config.rb
+- lib/sessionvision/event_buffer.rb
+- lib/sessionvision/transport.rb
+- lib/sessionvision/version.rb
+homepage: https://github.com/jjdinho/session_vision
+licenses:
+- MIT
+metadata: {}
+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.5.11
+signing_key:
+specification_version: 4
+summary: sessionvision analytics SDK for Ruby
+test_files: []