tgvizor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31681be1460576d09d0dea7a7315b6d7ff812a9ac425e6ae62c8c5bd4d5cb717
+  data.tar.gz: a934ae3c134704255c2a8ea2fb71db2f26b0493a3a89bb03f0b5ba62bdd77b30
+SHA512:
+  metadata.gz: 254f3e78dcc28a652740274cca131deb4e07615c88c8168bff72446dbbdfc74b9eb0722a965234705df5835eb04dc703bea11c41ab3d65283bd6187af650d74f
+  data.tar.gz: 89bc809693738c7987af924f36e48672dc0eeae65c9aa4526a39d8bd2cbe33d1427d11daea6f8630a3fcb7dd1f7f8483fbb60b84761687f8623f57b12b7bedb7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TGVizor
+
+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,115 @@
+# tgvizor
+
+**Analytics SDK for Telegram bots.** Track events, errors, performance, user journeys, and blocked users with one line of middleware. Zero runtime dependencies.
+
+```bash
+gem install tgvizor
+```
+
+Ruby >= 3.1.
+
+## telegram-bot-ruby
+
+```ruby
+require 'telegram/bot'
+require 'tgvizor'
+require 'tgvizor/middleware/telegram_bot_ruby'
+
+vizor   = TgVizor::Client.new(api_key: ENV['TGVIZOR_API_KEY'])
+tracker = TgVizor::Middleware::TelegramBotRuby.new(vizor)
+
+Telegram::Bot::Client.run(ENV['BOT_TOKEN']) do |bot|
+  bot.listen do |update|
+    tracker.track(update) do
+      # your existing handler — unchanged
+    end
+  end
+end
+```
+
+## What gets tracked automatically
+
+- **Commands** (`/start`, `/help`, etc., with `@BotName` stripped). The full argument string is stored in `properties[:args]`.
+- **Messages** by type (text, photo, voice, sticker, video, document, audio, animation, video_note, location, contact, poll, dice). The **plain text content** of text messages is NOT captured by default — see "Capturing message text" below.
+- **Callback queries** (button presses) — `data` is stored verbatim.
+- **Inline queries** — `query` is stored verbatim.
+- **Response time** — attached to every action event as `_response_time_ms` + `_response_time_handler`
+- **First-seen users** — `$identify` with username, first_name, language_code, is_premium (bounded 50k LRU)
+- **Errors** — any raised `StandardError` becomes a `$error` event with fingerprint
+- **Blocked users** — 403 from Telegram becomes a `user_blocked` event with `last_action`
+
+The middleware re-raises every exception so your existing error handling stays intact.
+
+## Capturing message text
+
+By default, the middleware stores only the **type** of plain (non-command) messages, not the content. This is the privacy-safe default — plain messages can contain anything (emails, card numbers, personal info), and storing user-generated content has GDPR implications you'll want to opt into explicitly.
+
+For bots where the message content IS the signal — AI chatbots, translators, URL extractors, search bots — enable it explicitly:
+
+```ruby
+tracker = TgVizor::Middleware::TelegramBotRuby.new(
+  vizor,
+  capture_message_text:    true,   # default false
+  max_message_text_length: 500,    # default 500; longer is truncated with "…"
+)
+```
+
+Captured text lands in `properties[:text]` on the `message` event and is visible in the Event Explorer + User Journey pages. Commands always capture `args` regardless of this setting — those are structured arguments you designed.
+
+## Custom events
+
+```ruby
+vizor.track('purchase', user_id: update.from.id, properties: { amount: 9.99 })
+
+vizor.identify(update.from.id, username: update.from.username, language_code: update.from.language_code)
+
+begin
+  handle_checkout
+rescue => e
+  vizor.capture_error(e, user_id: update.from.id, command: '/checkout', extra: { cart: 3 })
+  raise
+end
+```
+
+## Graceful shutdown
+
+```ruby
+at_exit do
+  vizor.shutdown!
+end
+```
+
+(The SDK registers this automatically; listed here for reference.)
+
+## Disk fallback
+
+If the ingestion API is unreachable after `max_retries` attempts, events persist to `.tgvizor/events.jsonl` (capped at 10 MB) and drain automatically when connectivity returns. Disable with `persist_queue: false`.
+
+## Configuration
+
+```ruby
+TgVizor::Client.new(
+  api_key: 'pk_live_xxx',               # required
+
+  endpoint: 'https://ingest.tgvizor.com',
+  flush_interval: 5,                     # seconds
+  max_queue_size: 10_000,
+  max_retries: 5,
+  persist_queue: true,
+  batch_size: 500,
+)
+```
+
+## HTTP fallback
+
+No Ruby? Any language can POST to `https://ingest.tgvizor.com/v1/events` directly. See [api-reference.md](https://github.com/LinGG/tgvizor/blob/main/docs/api-reference.md).
+
+## Links
+
+- 📖 [Full documentation](https://github.com/LinGG/tgvizor/tree/main/docs)
+- 🏠 [tgvizor.com](https://tgvizor.com)
+- 🐛 [Issues](https://github.com/LinGG/tgvizor/issues)
+
+## License
+
+MIT.

data/lib/tgvizor/client.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "digest"
+require "thread"
+require "time"
+
+module TgVizor
+  # TgVizor analytics client.
+  #
+  # Buffers events in memory, flushes them in the background to the ingestion API,
+  # and falls back to a JSONL disk queue if the API is unreachable.
+  #
+  # @example
+  #   vizor = TgVizor::Client.new(api_key: ENV["TGVIZOR_API_KEY"])
+  #   vizor.track("purchase", user_id: 123, properties: { amount: 9.99 })
+  #   vizor.identify(123, username: "john")
+  #
+  #   begin
+  #     do_work
+  #   rescue => e
+  #     vizor.capture_error(e, user_id: 123, command: "/buy")
+  #     raise
+  #   end
+  #
+  #   vizor.shutdown! # also auto-called via at_exit
+  class Client
+    DEFAULT_ENDPOINT       = "https://ingest.tgvizor.com"
+    DEFAULT_FLUSH_INTERVAL = 5     # seconds
+    DEFAULT_MAX_QUEUE_SIZE = 10_000
+    DEFAULT_BATCH_SIZE     = 500
+    DEFAULT_MAX_RETRIES    = 5
+
+    def initialize(
+      api_key:,
+      endpoint:       DEFAULT_ENDPOINT,
+      flush_interval: DEFAULT_FLUSH_INTERVAL,
+      max_queue_size: DEFAULT_MAX_QUEUE_SIZE,
+      batch_size:     DEFAULT_BATCH_SIZE,
+      max_retries:    DEFAULT_MAX_RETRIES,
+      persist_queue:  true,
+      auto_shutdown:  true,
+      debug:          false,
+      logger:         nil
+    )
+      raise ArgumentError, "TgVizor: api_key is required" if api_key.nil? || api_key.to_s.empty?
+
+      @api_key        = api_key
+      @endpoint       = endpoint
+      @flush_interval = flush_interval
+      @batch_size     = batch_size
+      @debug          = debug
+      @logger         = logger
+
+      @queue      = EventQueue.new(max_queue_size)
+      @transport  = Transport.new(
+        endpoint:    endpoint,
+        api_key:     api_key,
+        max_retries: max_retries,
+        debug:       debug,
+        logger:      logger,
+      )
+      @disk_queue = persist_queue ? DiskQueue.new : nil
+
+      @shutdown    = false
+      @state_mutex = Mutex.new
+      @flush_mutex = Mutex.new
+      @flush_thread = nil
+
+      start_flush_loop
+      install_at_exit_hook if auto_shutdown
+    end
+
+    # Track a custom event.
+    def track(event_name, user_id: nil, properties: nil, timestamp: nil)
+      enqueue(
+        event:      event_name,
+        userId:     user_id,
+        properties: properties,
+        timestamp:  timestamp,
+      )
+    end
+
+    # Identify a user with optional traits (profile enrichment).
+    def identify(user_id, traits = {})
+      enqueue(
+        event:      "$identify",
+        userId:     user_id,
+        properties: traits,
+      )
+    end
+
+    # Capture an exception. Includes class name, message, fingerprint and
+    # the first stack frame so the dashboard can group it.
+    def capture_error(error, user_id: nil, command: nil, extra: nil)
+      stack         = error.backtrace || []
+      first_frame   = stack.first.to_s
+      fingerprint   = build_fingerprint(error.class.name.to_s, error.message.to_s, first_frame)
+
+      properties = {
+        type:        error.class.name,
+        message:     error.message,
+        stack:       stack.first(50).join("\n"),
+        fingerprint: fingerprint,
+      }
+      properties[:context] = { user_id: user_id, command: command, extra: extra }.compact unless user_id.nil? && command.nil? && extra.nil?
+
+      enqueue(event: "$error", userId: user_id, properties: properties)
+    end
+
+    # Drain the in-memory + disk queues to the ingestion API. Safe to call
+    # at any time. Skips silently if there's nothing to send.
+    def flush!
+      @flush_mutex.synchronize do
+        # Pull anything previously persisted to disk back into memory first.
+        # `any?` is an O(1) stat — `size` would re-read the whole JSONL file.
+        if @disk_queue && @disk_queue.any?
+          @disk_queue.drain_all.each { |e| @queue.push(e) }
+        end
+
+        while @queue.any?
+          batch = @queue.drain(@batch_size)
+          break if batch.empty?
+
+          result = @transport.send_batch(batch)
+
+          unless result.ok?
+            if result.retryable && @disk_queue
+              batch.each { |e| @disk_queue.append(e) }
+            end
+            debug_log("flush failed: #{result.message}")
+            break
+          end
+        end
+      end
+    end
+
+    # Stop the background flush thread and drain remaining events. Idempotent.
+    def shutdown!
+      @state_mutex.synchronize do
+        return if @shutdown
+
+        @shutdown = true
+      end
+
+      stop_flush_loop
+      flush!
+    end
+
+    def shutdown?
+      @state_mutex.synchronize { @shutdown }
+    end
+
+    # @return [Integer] events currently buffered in memory
+    def queue_size
+      @queue.size
+    end
+
+    private
+
+    def enqueue(event)
+      if shutdown?
+        debug_log("dropping event, SDK is shut down")
+        return
+      end
+
+      queued = event.compact.merge(
+        timestamp:    event[:timestamp] || (Time.now.utc.to_f * 1000).to_i,
+        _sdk_version: VERSION,
+        _sdk_lang:    "ruby",
+      )
+
+      overflowed = @queue.push(queued)
+      debug_log("queue overflow, oldest event dropped") if overflowed
+    end
+
+    def start_flush_loop
+      @flush_thread = Thread.new do
+        loop do
+          sleep @flush_interval
+          break if shutdown?
+          next unless @queue.any?
+
+          begin
+            flush!
+          rescue StandardError => e
+            debug_log("flush loop error: #{e.class} #{e.message}")
+          end
+        end
+      end
+      @flush_thread.name = "tgvizor-flush"
+      @flush_thread.report_on_exception = false
+    end
+
+    def stop_flush_loop
+      thread = @flush_thread
+      return unless thread
+
+      # Wake the thread out of its sleep so it notices @state and exits cleanly.
+      thread.wakeup if thread.alive?
+      thread.join(2) # cap at 2s — we'll force-kill if it doesn't cooperate
+      thread.kill if thread.alive?
+      @flush_thread = nil
+    end
+
+    def install_at_exit_hook
+      # Use a weak reference via a closure that re-checks state, so multiple
+      # Client instances each register their own hook.
+      client_ref = self
+      at_exit { client_ref.shutdown! }
+    end
+
+    # Same shape as the TS SDK fingerprint: "fp_" + base36 of a hash.
+    # We use SHA256 truncated rather than the TS hash function — same column,
+    # different language, that's fine since the dashboard groups by exact match.
+    def build_fingerprint(type, message, first_frame)
+      digest = Digest::SHA256.hexdigest("#{type}:#{message}:#{first_frame}")
+      "fp_#{digest[0, 16]}"
+    end
+
+    def debug_log(msg)
+      return unless @debug
+
+      if @logger
+        @logger.debug("[tgvizor] #{msg}")
+      else
+        warn("[tgvizor] #{msg}")
+      end
+    end
+  end
+end

data/lib/tgvizor/disk_queue.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module TgVizor
+  # JSONL-based disk queue for persisting events when the ingestion API is unreachable.
+  #
+  # Append-only writes during normal operation. On drain, reads the whole file
+  # and truncates. Corrupt lines (e.g. from a crash mid-write) are silently
+  # skipped — the SDK must never crash the host bot.
+  #
+  # Capped at 10 MB to bound disk usage during prolonged outages; further events
+  # are silently dropped once the cap is reached.
+  class DiskQueue
+    DEFAULT_PATH    = File.join(".tgvizor", "events.jsonl")
+    MAX_FILE_BYTES  = 10 * 1024 * 1024 # 10 MB
+
+    def initialize(path: nil)
+      @path  = path || File.join(Dir.pwd, DEFAULT_PATH)
+      @mutex = Mutex.new
+    end
+
+    # Append a single event. Silently no-ops if the cap is reached or the
+    # write fails — observability code must not crash the host bot.
+    def append(event)
+      @mutex.synchronize do
+        return if file_size >= MAX_FILE_BYTES
+
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, "a") do |f|
+          f.write(JSON.generate(event))
+          f.write("\n")
+        end
+      end
+    rescue StandardError
+      # disk write failed — drop the event rather than raise
+    end
+
+    # Read every event off disk, truncate the file, and return them.
+    # Corrupt lines are skipped.
+    def drain_all
+      @mutex.synchronize do
+        return [] unless File.exist?(@path)
+
+        content = File.read(@path)
+        File.write(@path, "") # truncate immediately so concurrent drains don't double-read
+
+        content.each_line.filter_map do |line|
+          stripped = line.strip
+          next if stripped.empty?
+
+          begin
+            JSON.parse(stripped, symbolize_names: true)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+      end
+    rescue StandardError
+      []
+    end
+
+    def file_size
+      File.exist?(@path) ? File.size(@path) : 0
+    rescue StandardError
+      0
+    end
+
+    # O(1) check — used by the flush loop to skip empty disk queues without
+    # paying the file-scan cost of `size`.
+    def any?
+      file_size.positive?
+    end
+
+    # Approximate number of events currently on disk. Walks the file — only
+    # call this when you actually need the count, never as a hot-path guard.
+    def size
+      return 0 unless File.exist?(@path)
+
+      File.foreach(@path).count { |l| !l.strip.empty? }
+    rescue StandardError
+      0
+    end
+
+    attr_reader :path
+  end
+end

data/lib/tgvizor/event_queue.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module TgVizor
+  # Thread-safe in-memory event queue with batch draining.
+  #
+  # Events are pushed one at a time from any thread (handler thread, error
+  # callbacks) and drained in batches by the background flush thread. When
+  # the queue exceeds +max_size+, the oldest events are dropped to bound
+  # memory usage in incident scenarios where ingestion is unreachable.
+  class EventQueue
+    def initialize(max_size)
+      @items    = []
+      @max_size = max_size
+      @mutex    = Mutex.new
+    end
+
+    # Push an event to the queue.
+    # @return [Boolean] true if the queue overflowed (oldest event dropped).
+    def push(event)
+      @mutex.synchronize do
+        @items << event
+        if @items.size > @max_size
+          @items.shift
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Remove and return up to +batch_size+ events from the front.
+    # Caller takes ownership of the returned array.
+    def drain(batch_size)
+      @mutex.synchronize do
+        @items.shift(batch_size)
+      end
+    end
+
+    def size
+      @mutex.synchronize { @items.size }
+    end
+
+    def empty?
+      size.zero?
+    end
+
+    def any?
+      !empty?
+    end
+
+    def clear
+      @mutex.synchronize { @items.clear }
+    end
+  end
+end

data/lib/tgvizor/middleware/telegram_bot_ruby.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "set"
+
+module TgVizor
+  module Middleware
+    # Middleware for the telegram-bot-ruby gem (https://github.com/atipugin/telegram-bot-ruby).
+    #
+    # Wraps your update-handling block with auto-tracking of:
+    #   - the update type (command / message / callback_query / inline_query)
+    #   - response time (handler duration in ms)
+    #   - $identify on first-seen-per-process for each user
+    #   - $error on any StandardError raised by the handler
+    #   - user_blocked when the handler triggers a 403 from Telegram
+    #
+    # Re-raises every exception so the host bot's existing error handling stays
+    # intact. TgVizor is an observer, not a control-flow modifier.
+    #
+    # @example
+    #   require "telegram/bot"
+    #   require "tgvizor"
+    #   require "tgvizor/middleware/telegram_bot_ruby"
+    #
+    #   vizor   = TgVizor::Client.new(api_key: ENV["TGVIZOR_API_KEY"])
+    #   tracker = TgVizor::Middleware::TelegramBotRuby.new(vizor)
+    #
+    #   Telegram::Bot::Client.run(TOKEN) do |bot|
+    #     bot.listen do |update|
+    #       tracker.track(update) do
+    #         # your existing handler, unchanged
+    #       end
+    #     end
+    #   end
+    class TelegramBotRuby
+      MESSAGE_TYPES = %i[
+        text photo voice sticker video document audio animation
+        video_note location contact poll dice
+      ].freeze
+
+      # Bound on the in-process "have we identified this user yet?" set.
+      # Uncapped, a long-running bot serving millions of users would grow this
+      # forever (~80 MB at 1M ids). When the cap is hit we drop a random half —
+      # those users will simply re-fire identify on their next interaction,
+      # which is harmless.
+      SEEN_USERS_CAP = 50_000
+
+      # Short enough that a spammer can't inflate the events table with a
+      # 10k-char wall of text; long enough for most natural-language prompts.
+      DEFAULT_MAX_MESSAGE_TEXT_LENGTH = 500
+
+      # `capture_message_text` is opt-in because plain messages can contain PII
+      # (emails, card numbers, personal info). Storing user-generated content
+      # carries GDPR obligations most bot owners will want to opt into
+      # explicitly. Safe to enable for bots whose plain-text traffic is the
+      # signal itself: AI chatbots, translators, URL extractors, search bots.
+      # Commands always capture `args` regardless of this setting.
+      def initialize(
+        client,
+        capture_message_text: false,
+        max_message_text_length: DEFAULT_MAX_MESSAGE_TEXT_LENGTH
+      )
+        @client                  = client
+        @seen_users              = Set.new
+        @seen_mutex              = Mutex.new
+        @capture_message_text    = capture_message_text
+        @max_message_text_length = max_message_text_length
+      end
+
+      # Wrap a single update through the analytics layer.
+      #
+      # @param update [Telegram::Bot::Types::Base] message, callback query, inline query, ...
+      # @yield runs your handler with the update
+      # @return [Object] whatever the block returns
+      def track(update, &block)
+        classification = classify(update)
+        user_id        = extract_user_id(update)
+        started_at     = monotonic_now
+
+        identify_once(update, user_id)
+
+        block.call
+      rescue Telegram::Bot::Exceptions::ResponseError => e
+        if e.error_code.to_i == 403
+          # Prefer the specific command text (e.g. "/promo_weekly") over the generic
+          # event class — bot owners want to know which action drove the block.
+          last_action = classification[:command] || classification[:event] || "unknown"
+          @client.track(
+            "user_blocked",
+            user_id:    user_id,
+            properties: { last_action: last_action },
+          )
+        else
+          @client.capture_error(e, user_id: user_id, command: classification[:command])
+        end
+        raise
+      rescue StandardError => e
+        @client.capture_error(e, user_id: user_id, command: classification[:command])
+        raise
+      ensure
+        if classification && classification[:event]
+          elapsed_ms = started_at ? ((monotonic_now - started_at) * 1000).round : nil
+          emit_classified_event(classification, user_id, elapsed_ms)
+        end
+      end
+
+      private
+
+      # Classify the update into an event-name + properties payload.
+      # Returns nil for update kinds we don't track.
+      def classify(update)
+        return classify_message(update)        if message?(update)
+        return classify_callback_query(update) if callback_query?(update)
+        return classify_inline_query(update)   if inline_query?(update)
+
+        { event: nil }
+      end
+
+      def classify_message(message)
+        text = message.respond_to?(:text) ? message.text : nil
+
+        if text && text.start_with?("/")
+          command, args = text.split(" ", 2)
+          # Strip @BotName suffix from /start@MyBot
+          command = command.split("@", 2).first
+          return {
+            event:      "command",
+            command:    command,
+            properties: { command: command, args: args },
+          }
+        end
+
+        type = MESSAGE_TYPES.find { |t| message.respond_to?(t) && !message.public_send(t).nil? }
+        properties = { type: (type || :text).to_s }
+
+        if @capture_message_text && text && !text.empty?
+          properties[:text] = truncate_text(text)
+        end
+
+        {
+          event:      "message",
+          properties: properties,
+        }
+      end
+
+      def truncate_text(text)
+        return text if text.length <= @max_message_text_length
+
+        text[0, @max_message_text_length] + "…"
+      end
+
+      def classify_callback_query(query)
+        data = query.respond_to?(:data) ? query.data : nil
+        {
+          event:      "callback_query",
+          properties: { data: data },
+        }
+      end
+
+      def classify_inline_query(query)
+        text = query.respond_to?(:query) ? query.query : nil
+        {
+          event:      "inline_query",
+          properties: { query: text },
+        }
+      end
+
+      def message?(update)
+        defined?(Telegram::Bot::Types::Message) && update.is_a?(Telegram::Bot::Types::Message)
+      end
+
+      def callback_query?(update)
+        defined?(Telegram::Bot::Types::CallbackQuery) && update.is_a?(Telegram::Bot::Types::CallbackQuery)
+      end
+
+      def inline_query?(update)
+        defined?(Telegram::Bot::Types::InlineQuery) && update.is_a?(Telegram::Bot::Types::InlineQuery)
+      end
+
+      def extract_user_id(update)
+        return nil unless update.respond_to?(:from) && update.from
+
+        update.from.respond_to?(:id) ? update.from.id : nil
+      end
+
+      def identify_once(update, user_id)
+        return unless user_id
+
+        already_seen = @seen_mutex.synchronize do
+          if @seen_users.size >= SEEN_USERS_CAP
+            # Drop the oldest half by walking the underlying hash. Set is
+            # insertion-ordered in Ruby 3+, so this evicts the longest-standing
+            # entries — a poor-man's LRU without an extra dependency.
+            half = SEEN_USERS_CAP / 2
+            @seen_users = Set.new(@seen_users.to_a.last(half))
+          end
+          !@seen_users.add?(user_id)
+        end
+        return if already_seen
+        return unless update.respond_to?(:from) && update.from
+
+        from = update.from
+        traits = {}
+        traits[:username]      = from.username      if from.respond_to?(:username)      && from.username
+        traits[:first_name]    = from.first_name    if from.respond_to?(:first_name)    && from.first_name
+        traits[:last_name]     = from.last_name     if from.respond_to?(:last_name)     && from.last_name
+        traits[:language_code] = from.language_code if from.respond_to?(:language_code) && from.language_code
+        traits[:is_premium]    = from.is_premium    if from.respond_to?(:is_premium)    && !from.is_premium.nil?
+
+        @client.identify(user_id, traits)
+      end
+
+      # Emit a single event row with the perf data attached. The Performance
+      # dashboard reads `properties->>'_response_time_ms'` so this row both
+      # records the action AND fuels the performance page — half the events
+      # of the original "two-event-per-handler" approach.
+      def emit_classified_event(classification, user_id, elapsed_ms)
+        properties = (classification[:properties] || {}).dup
+        if elapsed_ms
+          properties[:_response_time_ms]      = elapsed_ms
+          properties[:_response_time_handler] = classification[:command] || classification[:event]
+        end
+
+        @client.track(
+          classification[:event],
+          user_id:    user_id,
+          properties: properties,
+        )
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/tgvizor/transport.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module TgVizor
+  # HTTP transport for sending event batches to the ingestion API.
+  #
+  # Uses Net::HTTP from stdlib (zero runtime deps). Retries with exponential
+  # backoff + jitter on 5xx, 429, and network failures. Treats 4xx other than
+  # 429 as non-retryable (bad request, unauthorized — caller's fault).
+  class Transport
+    # Outcome of a single send attempt.
+    #
+    # @!attribute ok
+    #   @return [Boolean] true on 202 Accepted
+    # @!attribute retryable
+    #   @return [Boolean] true if the caller should persist and retry later
+    # @!attribute status
+    #   @return [Integer, nil] HTTP status code, if any
+    # @!attribute message
+    #   @return [String, nil] human-readable error message
+    Result = Struct.new(:ok, :retryable, :status, :message, keyword_init: true) do
+      def ok? = ok
+    end
+
+    OPEN_TIMEOUT = 5    # seconds
+    READ_TIMEOUT = 10   # seconds
+
+    def initialize(endpoint:, api_key:, max_retries: 5, debug: false, logger: nil)
+      @uri         = URI.join(endpoint.chomp("/") + "/", "v1/events")
+      @api_key     = api_key
+      @max_retries = max_retries
+      @debug       = debug
+      @logger      = logger
+    end
+
+    # Send a batch of events.
+    # @param events [Array<Hash>] queued events
+    # @return [Result]
+    def send_batch(events)
+      body = JSON.generate(events: events)
+
+      # One HTTP connection across all retries — saves a TCP+TLS handshake
+      # (~150-300ms) on every retry attempt and lets keep-alive coalesce
+      # follow-up batches in the same flush.
+      http = build_http
+      http.start
+
+      begin
+        (0..@max_retries).each do |attempt|
+          sleep(backoff_seconds(attempt)) if attempt.positive?
+
+          result = attempt_send(http, body, attempt)
+          return result if result
+
+          # nil result means retryable — loop continues
+        end
+
+        Result.new(ok: false, retryable: true, message: "max retries exceeded")
+      ensure
+        http.finish if http.started?
+      end
+    end
+
+    private
+
+    def build_http
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl      = (@uri.scheme == "https")
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      http.keep_alive_timeout = 30
+      http
+    end
+
+    # Returns a Result on terminal outcome (success or non-retryable failure),
+    # or nil to signal "retry the loop".
+    def attempt_send(http, body, attempt)
+      request = Net::HTTP::Post.new(@uri.request_uri)
+      request["Content-Type"] = "application/json"
+      request["X-API-Key"]    = @api_key
+      request.body = body
+
+      response = http.request(request)
+      handle_response(response, attempt)
+    rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET,
+           Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError, EOFError, IOError => e
+      debug_log("network error on attempt #{attempt + 1}: #{e.class} #{e.message}")
+      return Result.new(ok: false, retryable: true, message: e.message) if attempt == @max_retries
+
+      nil # retry
+    end
+
+    def handle_response(response, attempt)
+      code = response.code.to_i
+
+      return Result.new(ok: true, retryable: false, status: 202) if code == 202
+
+      if code == 401
+        return Result.new(ok: false, retryable: false, status: 401, message: "unauthorized")
+      end
+
+      if code == 429
+        debug_log("rate limited (429) on attempt #{attempt + 1}")
+        return nil # retry
+      end
+
+      if code >= 500
+        debug_log("server error #{code} on attempt #{attempt + 1}")
+        return nil # retry
+      end
+
+      # Other 4xx — caller's fault, don't retry.
+      message = parse_message(response.body) || "unexpected status #{code}"
+      Result.new(ok: false, retryable: false, status: code, message: message)
+    end
+
+    def parse_message(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)["message"]
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Exponential backoff with full jitter: ~1s, ~2s, ~4s, ~8s, ~16s, capped at 30s.
+    def backoff_seconds(attempt)
+      base = [1.0 * (2**(attempt - 1)), 30.0].min
+      base + (rand * base * 0.5)
+    end
+
+    def debug_log(msg)
+      return unless @debug
+
+      if @logger
+        @logger.debug("[tgvizor] #{msg}")
+      else
+        warn("[tgvizor] #{msg}")
+      end
+    end
+  end
+end

data/lib/tgvizor/version.rb

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

data/lib/tgvizor.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "tgvizor/version"
+require_relative "tgvizor/event_queue"
+require_relative "tgvizor/transport"
+require_relative "tgvizor/disk_queue"
+require_relative "tgvizor/client"
+
+# TgVizor — analytics SDK for Telegram bots.
+#
+# @example
+#   vizor = TgVizor::Client.new(api_key: ENV["TGVIZOR_API_KEY"])
+#   vizor.track("purchase", user_id: 123, properties: { amount: 9.99 })
+#   vizor.identify(123, username: "john", first_name: "John")
+#   vizor.shutdown!
+module TgVizor
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: tgvizor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TGVizor
+bindir: bin
+cert_chain: []
+date: 2026-04-25 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: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !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'
+description: Track events, errors, performance, and user behavior in your Telegram
+  bot with one line of code. Pairs with telegram-bot-ruby.
+email:
+- hello@tgvizor.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/tgvizor.rb
+- lib/tgvizor/client.rb
+- lib/tgvizor/disk_queue.rb
+- lib/tgvizor/event_queue.rb
+- lib/tgvizor/middleware/telegram_bot_ruby.rb
+- lib/tgvizor/transport.rb
+- lib/tgvizor/version.rb
+homepage: https://tgvizor.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://tgvizor.com
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Analytics SDK for Telegram bots
+test_files: []