mbuzz 0.6.2

data/lib/specs/v0.5.0_four_call_model.md

@@ -0,0 +1,505 @@
+# mbuzz Ruby Gem v0.5.0 - Four-Call Model
+
+**Status**: Complete
+**Last Updated**: 2025-11-29
+**Breaking Change**: Yes (from 0.4.0)
+
+---
+
+## Overview
+
+Simplify the SDK to a 4-method model:
+
+| Method | Purpose |
+|--------|---------|
+| `Mbuzz.init` | Configure SDK |
+| `Mbuzz.event` | Track journey steps |
+| `Mbuzz.conversion` | Track revenue outcomes |
+| `Mbuzz.identify` | Link visitor to user + store traits |
+
+---
+
+## Changes from v0.4.0
+
+| Change | Before (v0.4.0) | After (v0.5.0) |
+|--------|-----------------|----------------|
+| Configuration | `Mbuzz.configure { \|c\| ... }` | `Mbuzz.init(api_key: ...)` |
+| Track events | `Mbuzz.track(event_type:, ...)` | `Mbuzz.event("event_type", ...)` |
+| Link visitor | `Mbuzz.alias(user_id:, visitor_id:)` | Merged into `identify` |
+| Identify | `Mbuzz.identify(user_id:, traits:)` | `Mbuzz.identify(user_id, traits:, visitor_id:)` |
+
+---
+
+## New Public API
+
+### `Mbuzz.init`
+
+```ruby
+Mbuzz.init(
+  api_key: "sk_live_...",             # Required
+  api_url: "https://mbuzz.co/api/v1", # Optional - API endpoint
+  debug: false                        # Optional - enable debug logging
+)
+```
+
+**Note**: Session timeout is fixed at 30 minutes (cookie expiry). HTTP timeout defaults to 5 seconds.
+
+### `Mbuzz.event`
+
+```ruby
+Mbuzz.event("add_to_cart",
+  product_id: "SKU-123",
+  price: 49.99
+)
+# Returns: { success: true, event_id: "evt_abc123" } or false
+```
+
+### `Mbuzz.conversion`
+
+```ruby
+Mbuzz.conversion("purchase",
+  revenue: 99.99,
+  order_id: "ORD-123"
+)
+# Returns: { success: true, conversion_id: "conv_abc123" } or false
+```
+
+### `Mbuzz.identify`
+
+```ruby
+# Links visitor (from cookie) to user + stores traits
+Mbuzz.identify("user_123",
+  traits: { email: "jane@example.com", name: "Jane" }
+)
+
+# Or with explicit visitor_id
+Mbuzz.identify("user_123",
+  visitor_id: "abc123...",
+  traits: { email: "jane@example.com" }
+)
+# Returns: true on success, false on failure
+```
+
+**Backend Response**: The API returns `{ success: true, identity_id: "idt_...", visitor_linked: true/false }` but the SDK simplifies this to a boolean for ease of use.
+
+---
+
+## Removed
+
+- `Mbuzz.configure` → use `Mbuzz.init`
+- `Mbuzz.track` → use `Mbuzz.event`
+- `Mbuzz.alias` → use `Mbuzz.identify` with `visitor_id:`
+
+---
+
+## Files to Change
+
+| File | Action |
+|------|--------|
+| `lib/mbuzz/version.rb` | Bump to 0.5.0 |
+| `lib/mbuzz.rb` | New API methods |
+| `lib/mbuzz/client.rb` | Update signatures |
+| `lib/mbuzz/client/identify_request.rb` | Accept visitor_id |
+| `lib/mbuzz/client/alias_request.rb` | DELETE |
+| `README.md` | Complete rewrite |
+| `CHANGELOG.md` | Add 0.5.0 entry |
+
+---
+
+## README Content
+
+```markdown
+# 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)
+```
+
+### 3. Track Conversions
+
+Record revenue-generating outcomes:
+
+```ruby
+Mbuzz.conversion("purchase",
+  revenue: 99.99,
+  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
+  }
+)
+```
+
+## Rails Integration
+
+mbuzz provides:
+- Middleware for visitor and session cookie management
+- `mbuzz_visitor_id` helper in controllers
+
+## 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 2.7+
+- Rails 6.0+ (for automatic integration) or any Rack app
+
+## Links
+
+- [Documentation](https://mbuzz.co/docs)
+- [Dashboard](https://mbuzz.co/dashboard)
+
+## License
+
+MIT License
+```
+
+---
+
+## CHANGELOG Entry
+
+```markdown
+## [0.5.0] - 2025-XX-XX
+
+### 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
+
+### Removed
+
+- `Mbuzz.configure` block syntax
+- `Mbuzz.track` method
+- `Mbuzz.alias` method
+```
+
+---
+
+## Backend Requirements ✅ COMPLETE
+
+Backend `POST /api/v1/identify` must:
+1. ✅ Accept optional `visitor_id` in payload
+2. ✅ Link visitor to identity if visitor_id present
+3. ✅ Store/update traits
+4. ✅ Check for retroactive attribution (triggers `ReattributionJob`)
+5. ✅ Return `{ success: true, identity_id: "...", visitor_linked: true/false }`
+
+Backend `POST /api/v1/alias` ✅ REMOVED (commit 5c4b555)
+
+---
+
+## Session & Cookie Management
+
+### Cookie Specifications
+
+| Cookie | Name | Format | Max-Age | Purpose |
+|--------|------|--------|---------|---------|
+| Visitor | `_mbuzz_vid` | 64 hex chars | 2 years | Persistent visitor ID |
+| Session | `_mbuzz_sid` | 64 hex chars | 30 min | Session tracking |
+
+### Middleware Implementation
+
+```ruby
+# lib/mbuzz/middleware/tracking.rb
+module Mbuzz
+  module Middleware
+    class Tracking
+      SESSION_TIMEOUT = 1800 # 30 minutes
+      VISITOR_COOKIE = "_mbuzz_vid"
+      SESSION_COOKIE = "_mbuzz_sid"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @request = Rack::Request.new(env)
+
+        env[Mbuzz::ENV_VISITOR_ID_KEY] = visitor_id
+        env[Mbuzz::ENV_SESSION_ID_KEY] = session_id
+
+        Mbuzz::RequestContext.with_context(request: @request) do
+          status, headers, body = @app.call(env)
+          set_cookies(headers)
+          [status, headers, body]
+        end
+      end
+
+      private
+
+      def visitor_id
+        @visitor_id ||= @request.cookies[VISITOR_COOKIE] || SecureRandom.hex(32)
+      end
+
+      def session_id
+        @session_id ||= @request.cookies[SESSION_COOKIE] || SecureRandom.hex(32)
+      end
+
+      def set_cookies(headers)
+        Rack::Utils.set_cookie_header!(headers, VISITOR_COOKIE, visitor_cookie_options)
+        Rack::Utils.set_cookie_header!(headers, SESSION_COOKIE, session_cookie_options)
+      end
+
+      def visitor_cookie_options
+        { value: visitor_id, path: "/", max_age: 63072000, httponly: true, same_site: :lax, secure: @request.ssl? }
+      end
+
+      def session_cookie_options
+        { value: session_id, path: "/", max_age: SESSION_TIMEOUT, httponly: true, same_site: :lax, secure: @request.ssl? }
+      end
+    end
+  end
+end
+```
+
+### Request Context (URL/Referrer Enrichment)
+
+```ruby
+# lib/mbuzz/request_context.rb
+module Mbuzz
+  class RequestContext
+    def self.with_context(request:)
+      Thread.current[:mbuzz_context] = new(request)
+      yield
+    ensure
+      Thread.current[:mbuzz_context] = nil
+    end
+
+    def self.current
+      Thread.current[:mbuzz_context]
+    end
+
+    attr_reader :request
+
+    def initialize(request)
+      @request = request
+    end
+
+    def url
+      request.url
+    end
+
+    def referrer
+      request.referrer
+    end
+
+    def visitor_id
+      request.env[Mbuzz::ENV_VISITOR_ID_KEY]
+    end
+
+    def session_id
+      request.env[Mbuzz::ENV_SESSION_ID_KEY]
+    end
+
+    def enriched_properties(custom = {})
+      { url: url, referrer: referrer }.compact.merge(custom)
+    end
+  end
+end
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: API Rename
+- [x] Add `Mbuzz.init` (wrapper for configure)
+- [x] Add `Mbuzz.event` (wrapper for track)
+- [x] Deprecate `Mbuzz.configure` with warning
+- [x] Deprecate `Mbuzz.track` with warning
+- [x] Remove `Mbuzz.alias` method
+- [x] Update `Mbuzz.identify` to accept visitor_id
+
+### Phase 2: Internals
+- [x] Update `lib/mbuzz/client/identify_request.rb` for visitor_id
+- [x] Delete `lib/mbuzz/client/alias_request.rb`
+- [x] Update middleware for session cookies (if not already)
+- [x] Add RequestContext for URL/referrer enrichment
+
+### Phase 3: Documentation
+- [x] Rewrite README.md
+- [x] Update CHANGELOG.md
+- [x] Update gemspec description
+
+### Phase 4: Testing
+- [x] Unit tests for new API methods
+- [ ] Integration test with backend
+- [x] Verify cookies set correctly
+
+---
+
+## Migration Guide
+
+### Existing Integrations
+
+**No code changes required for basic usage!** The SDK auto-enriches events with URL and referrer.
+
+#### Configuration Change
+
+```ruby
+# Before (v0.4.0)
+Mbuzz.configure do |config|
+  config.api_key = ENV['MBUZZ_API_KEY']
+end
+
+# After (v0.5.0)
+Mbuzz.init(api_key: ENV['MBUZZ_API_KEY'])
+```
+
+#### Event Tracking Change
+
+```ruby
+# Before (v0.4.0)
+Mbuzz.track("add_to_cart", properties: { product_id: "123" })
+
+# After (v0.5.0)
+Mbuzz.event("add_to_cart", product_id: "123")
+```
+
+#### Alias → Identify
+
+```ruby
+# Before (v0.4.0)
+Mbuzz.alias(user_id: "user_123", visitor_id: visitor_id)
+
+# After (v0.5.0)
+Mbuzz.identify("user_123")  # visitor_id auto-captured from cookie
+```
+
+---
+
+## Testing Plan
+
+### Unit Tests
+
+```ruby
+# test/mbuzz_test.rb
+class MbuzzTest < Minitest::Test
+  def test_init_stores_api_key
+    Mbuzz.init(api_key: "sk_test_123")
+    assert_equal "sk_test_123", Mbuzz.config.api_key
+  end
+
+  def test_event_sends_to_api
+    stub_request(:post, "https://mbuzz.co/api/v1/events")
+      .to_return(status: 202, body: '{"accepted":1}')
+
+    result = Mbuzz.event("page_view", url: "https://example.com")
+    assert result
+  end
+
+  def test_identify_includes_visitor_id
+    stub_request(:post, "https://mbuzz.co/api/v1/identify")
+      .with(body: hash_including(visitor_id: "abc123"))
+      .to_return(status: 200, body: '{"success":true}')
+
+    with_visitor_id("abc123") do
+      Mbuzz.identify("user_123", traits: { email: "test@example.com" })
+    end
+  end
+end
+```
+
+### Integration Test
+
+```ruby
+# test/integration/tracking_test.rb
+class TrackingIntegrationTest < ActionDispatch::IntegrationTest
+  def test_full_journey
+    # 1. Visit with UTMs
+    get "/?utm_source=google&utm_campaign=q4"
+    assert cookies["_mbuzz_vid"].present?
+    assert cookies["_mbuzz_sid"].present?
+
+    # 2. Track event
+    Mbuzz.event("page_view")
+
+    # 3. Convert
+    Mbuzz.conversion("signup", revenue: 0)
+
+    # 4. Identify
+    result = Mbuzz.identify("user_123")
+    assert result[:visitor_linked]
+  end
+end
+```
+
+---
+
+## Success Metrics
+
+After deployment, verify:
+
+1. **Visitor creation**: `Visitor.where(created_at: 1.day.ago..).count` should match unique visitors
+2. **Session tracking**: Sessions with UTMs should have `initial_utm` populated
+3. **Event enrichment**: Events should have `url` in properties
+4. **Attribution accuracy**: Conversions attributed to original acquisition channel

data/sig/mbuzz.rbs

@@ -0,0 +1,4 @@
+module Mbuzz
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: mbuzz
+version: !ruby/object:Gem::Version
+  version: 0.6.2
+platform: ruby
+authors:
+- mbuzz team
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Track customer journeys, attribute conversions, know which channels
+  drive revenue. Simple 4-call API: init, event, conversion, identify. Works with
+  Rails, Sinatra, and any Rack application.'
+email:
+- support@mbuzz.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mbuzz.rb
+- lib/mbuzz/api.rb
+- lib/mbuzz/client.rb
+- lib/mbuzz/client/conversion_request.rb
+- lib/mbuzz/client/identify_request.rb
+- lib/mbuzz/client/session_request.rb
+- lib/mbuzz/client/track_request.rb
+- lib/mbuzz/configuration.rb
+- lib/mbuzz/controller_helpers.rb
+- lib/mbuzz/middleware/tracking.rb
+- lib/mbuzz/railtie.rb
+- lib/mbuzz/request_context.rb
+- lib/mbuzz/version.rb
+- lib/mbuzz/visitor/identifier.rb
+- lib/specs/old/SPECIFICATION.md
+- lib/specs/old/conversions.md
+- lib/specs/old/event_ids_response.md
+- lib/specs/old/v0.2.0_breaking_changes.md
+- lib/specs/old/v2.0.0_sessions_upgrade.md
+- lib/specs/v0.5.0_four_call_model.md
+- mbuzz-0.6.0.gem
+- sig/mbuzz.rbs
+homepage: https://mbuzz.co
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mbuzz.co
+  source_code_uri: https://github.com/mbuzz/mbuzz-ruby
+  changelog_uri: https://github.com/mbuzz/mbuzz-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://mbuzz.co/docs
+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.16
+signing_key:
+specification_version: 4
+summary: Server-side multi-touch attribution for Ruby
+test_files: []