mbuzz 0.6.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c9557bce57bad2c91864640fcfff650794bb4de6d56afd3497eaa693247cc10
+  data.tar.gz: fef9164f73131538bc7e6df11e2b5fc802a967580b65b26426aa671e5d68cc26
+SHA512:
+  metadata.gz: 2c0a78057cf989d08703c758f70b2c6711542c12994662ae47e5b9c67d1462aacd6e80d65b790bb287bb70e6ca03d61c60342eecb16f6c62059f4762359233ad
+  data.tar.gz: 8a6782fb3f84ce855438f64066becfb411f46f3db8ae68504dc5a96774b6a9ed4b0a04607da386888fca6683663c2ceddd1bd466b448df2fe82f4900fc03eee5

data/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2025-12-05
+
+### Added
+
+- **Path filtering in middleware** - Automatically skip tracking for:
+  - Health check endpoints (`/up`, `/health`, `/healthz`, `/ping`)
+  - Asset paths (`/assets`, `/packs`, `/rails/active_storage`)
+  - WebSocket paths (`/cable`)
+  - API paths (`/api`)
+  - Static assets by extension (`.js`, `.css`, `.png`, `.woff2`, etc.)
+- `skip_paths` configuration option - Add custom paths to skip
+- `skip_extensions` configuration option - Add custom extensions to skip
+
+### Fixed
+
+- Health check requests no longer create sessions or consume API quota
+- Static asset requests no longer pollute tracking data
+
+### Usage
+
+```ruby
+Mbuzz.init(
+  api_key: "sk_live_...",
+  skip_paths: ["/admin", "/internal"],      # Optional: additional paths to skip
+  skip_extensions: [".pdf", ".xml"]         # Optional: additional extensions to skip
+)
+```
+
+## [0.5.0] - 2025-11-29
+
+### Breaking Changes
+
+- `Mbuzz.configure` replaced with `Mbuzz.init`
+- `Mbuzz.track` renamed to `Mbuzz.event`
+- `Mbuzz.alias` removed - merged into `Mbuzz.identify`
+- `Mbuzz.identify` signature changed: positional user_id, keyword traits/visitor_id
+
+### Added
+
+- `Mbuzz.init(api_key:, ...)` - new configuration method
+- `Mbuzz.event(event_type, **properties)` - cleaner event tracking
+- Automatic visitor linking in `identify` when visitor_id available
+- `enriched_properties` in RequestContext for URL/referrer auto-enrichment
+
+### Removed
+
+- `Mbuzz.configure` block syntax
+- `Mbuzz.track` method
+- `Mbuzz.alias` method
+- `Mbuzz::Client::AliasRequest` class
+
+## [0.2.0] - 2025-11-25
+
+### BREAKING CHANGES
+
+This release fixes critical bugs that prevented events from being tracked. You MUST update your code to use this version.
+
+### Changed
+
+- **BREAKING**: Renamed `event:` parameter to `event_type:` to match backend API
+  - Before: `Mbuzz.track(event: 'Signup', user_id: 1)`
+  - After: `Mbuzz.track(event_type: 'Signup', user_id: 1)`
+  - Migration: Search/replace `event:` → `event_type:` in all `Mbuzz.track()` calls
+
+- **BREAKING**: Changed timestamp format from Unix epoch to ISO8601
+  - Before: Sent `1732550400` (integer)
+  - After: Sends `"2025-11-25T10:30:00Z"` (ISO8601 string)
+  - Migration: No action required - gem handles this automatically
+
+### Fixed
+
+- Events are now correctly formatted and accepted by backend
+- Timestamps are now in UTC with ISO8601 format
+
+## [0.1.0] - 2025-11-25
+
+### Added
+
+- Initial release
+- Event tracking with `Mbuzz::Client.track()`
+- User identification with `Mbuzz::Client.identify()`
+- Visitor aliasing with `Mbuzz::Client.alias()`
+- Automatic visitor and session management via middleware
+- Rails integration via Railtie
+- Controller helpers for convenient tracking

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+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,173 @@
+# mbuzz
+
+Server-side multi-touch attribution for Ruby. Track customer journeys, attribute conversions, know which channels drive revenue.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mbuzz'
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Initialize
+
+```ruby
+# config/initializers/mbuzz.rb
+Mbuzz.init(api_key: ENV['MBUZZ_API_KEY'])
+```
+
+### 2. Track Events
+
+Track steps in the customer journey:
+
+```ruby
+Mbuzz.event("page_view", url: request.url)
+Mbuzz.event("add_to_cart", product_id: "SKU-123", price: 49.99)
+Mbuzz.event("checkout_started", cart_total: 99.99)
+
+# Group events into funnels for focused analysis
+Mbuzz.event("signup_start", funnel: "signup", source: "homepage")
+Mbuzz.event("signup_complete", funnel: "signup")
+```
+
+### 3. Track Conversions
+
+Record revenue-generating outcomes:
+
+```ruby
+Mbuzz.conversion("purchase",
+  revenue: 99.99,
+  funnel: "purchase",  # Optional: group into funnel
+  order_id: order.id
+)
+```
+
+### 4. Identify Users
+
+Link visitors to known users (enables cross-device attribution):
+
+```ruby
+# On signup or login
+Mbuzz.identify(current_user.id,
+  traits: {
+    email: current_user.email,
+    name: current_user.name
+  }
+)
+```
+
+## Funnels
+
+Group related events into **funnels** for focused conversion analysis in your dashboard.
+
+```ruby
+# Signup funnel
+Mbuzz.event("pricing_view", funnel: "signup")
+Mbuzz.event("signup_start", funnel: "signup")
+Mbuzz.event("signup_complete", funnel: "signup")
+
+# Purchase funnel
+Mbuzz.event("add_to_cart", funnel: "purchase")
+Mbuzz.event("checkout_started", funnel: "purchase")
+Mbuzz.conversion("purchase", funnel: "purchase", revenue: 99.99)
+```
+
+**Why use funnels?**
+- Separate signup flow from purchase flow
+- Analyze each conversion path independently
+- Filter dashboard to specific customer journeys
+
+## Rails Integration
+
+mbuzz auto-integrates with Rails via Railtie:
+- Middleware for visitor and session cookie management
+- Controller helpers for convenient access
+
+### Controller Helpers
+
+```ruby
+class ApplicationController < ActionController::Base
+  # Access current IDs
+  mbuzz_visitor_id   # Returns the visitor ID from cookie
+  mbuzz_user_id      # Returns user_id from session["user_id"]
+  mbuzz_session_id   # Returns the session ID from cookie
+end
+```
+
+**Note:** For tracking and identification, prefer the main API which auto-enriches events with URL/referrer:
+
+```ruby
+# Recommended - use main API in controllers
+Mbuzz.event("page_view", page: request.path)
+Mbuzz.identify(current_user.id, traits: { email: current_user.email })
+```
+
+### Context Accessors
+
+Access IDs from anywhere in your request cycle:
+
+```ruby
+Mbuzz.visitor_id  # Current visitor ID (from cookie)
+Mbuzz.user_id     # Current user ID (from session["user_id"])
+Mbuzz.session_id  # Current session ID (from cookie)
+```
+
+## Rack / Sinatra Integration
+
+For non-Rails apps, add the middleware manually:
+
+```ruby
+# config.ru or app.rb
+require 'mbuzz'
+
+Mbuzz.init(api_key: ENV['MBUZZ_API_KEY'])
+
+use Mbuzz::Middleware::Tracking
+run MyApp
+```
+
+## Configuration Options
+
+```ruby
+Mbuzz.init(
+  api_key: "sk_live_...",             # Required - from mbuzz.co dashboard
+  api_url: "https://mbuzz.co/api/v1", # Optional - API endpoint
+  debug: false                        # Optional - enable debug logging
+)
+```
+
+## The 4-Call Model
+
+| Method | When to Use |
+|--------|-------------|
+| `init` | Once on app boot |
+| `event` | User interactions, funnel steps |
+| `conversion` | Purchases, signups, any revenue event |
+| `identify` | Login, signup, when you know the user |
+
+## Error Handling
+
+mbuzz never raises exceptions. All methods return `false` on failure and log errors in debug mode.
+
+## Requirements
+
+- Ruby 3.0+
+- Rails 6.0+ (for automatic integration) or any Rack app
+
+## Links
+
+- [Documentation](https://mbuzz.co/docs)
+- [Dashboard](https://mbuzz.co/dashboard)
+
+## License
+
+MIT License

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/mbuzz/api.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+module Mbuzz
+  class Api
+    def self.post(path, payload)
+      return false unless enabled_and_configured?
+
+      response = http_client(path).request(build_request(path, payload))
+      success?(response)
+    rescue ConfigurationError, Net::ReadTimeout, Net::OpenTimeout, Net::HTTPError => e
+      log_error("#{e.class}: #{e.message}")
+      false
+    end
+
+    def self.post_with_response(path, payload)
+      return nil unless enabled_and_configured?
+
+      response = http_client(path).request(build_request(path, payload))
+      return nil unless success?(response)
+
+      JSON.parse(response.body)
+    rescue ConfigurationError, Net::ReadTimeout, Net::OpenTimeout, Net::HTTPError, JSON::ParserError => e
+      log_error("#{e.class}: #{e.message}")
+      nil
+    end
+
+    def self.enabled_and_configured?
+      return false unless config.enabled
+      config.validate!
+      true
+    rescue ConfigurationError => e
+      log_error(e.message)
+      false
+    end
+    private_class_method :enabled_and_configured?
+
+    def self.uri(path)
+      @uri_cache ||= {}
+      @uri_cache[path] ||= begin
+        base = config.api_url.chomp("/")
+        endpoint = path.start_with?("/") ? path : "/#{path}"
+        URI.parse("#{base}#{endpoint}")
+      end
+    end
+    private_class_method :uri
+
+    def self.http_client(path)
+      Net::HTTP.new(uri(path).host, uri(path).port).tap do |http|
+        if uri(path).scheme == "https"
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.cert_store = ssl_cert_store
+        end
+        http.open_timeout = config.timeout
+        http.read_timeout = config.timeout
+      end
+    end
+    private_class_method :http_client
+
+    def self.ssl_cert_store
+      @ssl_cert_store ||= OpenSSL::X509::Store.new.tap do |store|
+        store.set_default_paths
+        # Don't set any CRL flags - Let's Encrypt uses OCSP, not CRL
+        store.flags = 0
+      end
+    end
+    private_class_method :ssl_cert_store
+
+    def self.build_request(path, payload)
+      Net::HTTP::Post.new(uri(path).path).tap do |request|
+        request["Authorization"] = "Bearer #{config.api_key}"
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "mbuzz-ruby/#{VERSION}"
+        request.body = JSON.generate(payload)
+      end
+    end
+    private_class_method :build_request
+
+    def self.success?(response)
+      return true if response.code.to_i.between?(200, 299)
+
+      log_error("API #{response.code}: #{response.body}")
+      false
+    end
+    private_class_method :success?
+
+    def self.log_error(message)
+      warn "[mbuzz] #{message}" if config.debug
+    end
+    private_class_method :log_error
+
+    def self.config
+      Mbuzz.config
+    end
+    private_class_method :config
+  end
+end

data/lib/mbuzz/client/conversion_request.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Client
+    class ConversionRequest
+      def initialize(event_id:, visitor_id:, user_id:, conversion_type:, revenue:, currency:, is_acquisition:, inherit_acquisition:, properties:)
+        @event_id = event_id
+        @visitor_id = visitor_id
+        @user_id = user_id
+        @conversion_type = conversion_type
+        @revenue = revenue
+        @currency = currency
+        @is_acquisition = is_acquisition
+        @inherit_acquisition = inherit_acquisition
+        @properties = properties
+      end
+
+      def call
+        return false unless valid?
+
+        { success: true, conversion_id: conversion_id, attribution: attribution }
+      end
+
+      private
+
+      def valid?
+        has_identifier? && present?(@conversion_type) && hash?(@properties) && conversion_id
+      end
+
+      def has_identifier?
+        present?(@event_id) || present?(@visitor_id) || present?(@user_id)
+      end
+
+      def conversion_id
+        @conversion_id ||= response&.dig("conversion", "id")
+      end
+
+      def attribution
+        response&.dig("attribution")
+      end
+
+      def response
+        @response ||= Api.post_with_response(CONVERSIONS_PATH, payload)
+      end
+
+      def payload
+        { conversion: conversion_payload }
+      end
+
+      def conversion_payload
+        base_payload
+          .merge(optional_identifiers)
+          .merge(optional_acquisition_fields)
+      end
+
+      def base_payload
+        {
+          conversion_type: @conversion_type,
+          currency: @currency,
+          properties: @properties,
+          timestamp: Time.now.utc.iso8601
+        }
+      end
+
+      def optional_identifiers
+        {}.tap do |h|
+          h[:event_id] = @event_id if @event_id
+          h[:visitor_id] = @visitor_id if @visitor_id
+          h[:user_id] = @user_id if @user_id
+          h[:revenue] = @revenue if @revenue
+        end
+      end
+
+      def optional_acquisition_fields
+        {}.tap do |h|
+          h[:is_acquisition] = @is_acquisition if @is_acquisition
+          h[:inherit_acquisition] = @inherit_acquisition if @inherit_acquisition
+        end
+      end
+
+      def present?(value) = value && !value.to_s.strip.empty?
+      def hash?(value) = value.is_a?(Hash)
+    end
+  end
+end

data/lib/mbuzz/client/identify_request.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Client
+    class IdentifyRequest
+      def initialize(user_id, visitor_id, traits)
+        @user_id = user_id
+        @visitor_id = visitor_id
+        @traits = traits
+      end
+
+      def call
+        return false unless valid?
+
+        Api.post(IDENTIFY_PATH, payload)
+      end
+
+      private
+
+      def valid?
+        id?(@user_id) && hash?(@traits)
+      end
+
+      def payload
+        {
+          user_id: @user_id,
+          visitor_id: @visitor_id,
+          traits: @traits,
+          timestamp: Time.now.utc.iso8601
+        }.compact
+      end
+
+      def id?(value) = value.is_a?(String) || value.is_a?(Numeric)
+      def hash?(value) = value.is_a?(Hash)
+    end
+  end
+end

data/lib/mbuzz/client/session_request.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Client
+    class SessionRequest
+      def initialize(visitor_id, session_id, url, referrer, started_at)
+        @visitor_id = visitor_id
+        @session_id = session_id
+        @url = url
+        @referrer = referrer
+        @started_at = started_at || Time.now.utc.iso8601
+      end
+
+      def call
+        return false unless valid?
+
+        Api.post(SESSIONS_PATH, payload)
+      end
+
+      private
+
+      attr_reader :visitor_id, :session_id, :url, :referrer, :started_at
+
+      def valid?
+        present?(visitor_id) && present?(session_id) && present?(url)
+      end
+
+      def payload
+        {
+          session: {
+            visitor_id: visitor_id,
+            session_id: session_id,
+            url: url,
+            referrer: referrer,
+            started_at: started_at
+          }.compact
+        }
+      end
+
+      def present?(value) = value && !value.to_s.strip.empty?
+    end
+  end
+end

data/lib/mbuzz/client/track_request.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Mbuzz
+  class Client
+    class TrackRequest
+      def initialize(user_id, visitor_id, session_id, event_type, properties)
+        @user_id = user_id
+        @visitor_id = visitor_id
+        @session_id = session_id
+        @event_type = event_type
+        @properties = properties
+      end
+
+      def call
+        return false unless valid?
+
+        { success: true, event_id: event["id"], event_type: event["event_type"],
+          visitor_id: event["visitor_id"], session_id: event["session_id"] }
+      end
+
+      private
+
+      def valid?
+        present?(@event_type) && hash?(@properties) && (@user_id || @visitor_id) && event
+      end
+
+      def event
+        @event ||= response&.dig("events", 0)
+      end
+
+      def response
+        @response ||= Api.post_with_response(EVENTS_PATH, { events: [payload] })
+      end
+
+      def payload
+        {
+          user_id: @user_id,
+          visitor_id: @visitor_id,
+          session_id: @session_id,
+          event_type: @event_type,
+          properties: @properties,
+          timestamp: Time.now.utc.iso8601
+        }.compact
+      end
+
+      def present?(value) = value && !value.to_s.strip.empty?
+      def hash?(value) = value.is_a?(Hash)
+    end
+  end
+end

data/lib/mbuzz/client.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "client/track_request"
+require_relative "client/identify_request"
+require_relative "client/conversion_request"
+require_relative "client/session_request"
+
+module Mbuzz
+  class Client
+    def self.track(user_id: nil, visitor_id: nil, session_id: nil, event_type:, properties: {})
+      TrackRequest.new(user_id, visitor_id, session_id, event_type, properties).call
+    end
+
+    def self.identify(user_id:, visitor_id: nil, traits: {})
+      IdentifyRequest.new(user_id, visitor_id, traits).call
+    end
+
+    def self.conversion(event_id: nil, visitor_id: nil, user_id: nil, conversion_type:, revenue: nil, currency: "USD", is_acquisition: false, inherit_acquisition: false, properties: {})
+      ConversionRequest.new(
+        event_id: event_id,
+        visitor_id: visitor_id,
+        user_id: user_id,
+        conversion_type: conversion_type,
+        revenue: revenue,
+        currency: currency,
+        is_acquisition: is_acquisition,
+        inherit_acquisition: inherit_acquisition,
+        properties: properties
+      ).call
+    end
+
+    def self.session(visitor_id:, session_id:, url:, referrer: nil, started_at: nil)
+      SessionRequest.new(visitor_id, session_id, url, referrer, started_at).call
+    end
+  end
+end