mbuzz 0.6.2

data/lib/specs/old/v2.0.0_sessions_upgrade.md

@@ -0,0 +1,265 @@
+# mbuzz-ruby v2.0.0 Upgrade: Sessions Endpoint
+
+**Created**: 2025-11-28
+**Status**: Required for full SDK compliance
+
+---
+
+## Summary
+
+The Multibuzz backend now has a dedicated `POST /api/v1/sessions` endpoint for creating sessions with full acquisition context (UTM parameters, referrer, channel). The SDK must be updated to call this endpoint on new session creation.
+
+---
+
+## Current State
+
+The current SDK (v0.x/v1.x):
+- Generates visitor_id and session_id cookies
+- Does NOT explicitly create sessions on the backend
+- Sessions are created implicitly when events are tracked
+
+## Required Changes
+
+### 1. Add Session Creation on New Session
+
+When the middleware detects a new session (no session cookie or expired), it must:
+
+1. Generate new session_id
+2. POST to `/api/v1/sessions` with full context
+3. Store session_id in cookie
+
+**New Endpoint:**
+
+```
+POST /api/v1/sessions
+
+{
+  "session": {
+    "visitor_id": "64-char-hex-string",
+    "session_id": "64-char-hex-string",
+    "url": "https://example.com/landing?utm_source=google&utm_medium=cpc",
+    "referrer": "https://www.google.com/search",
+    "started_at": "2025-11-28T10:30:00Z"
+  }
+}
+```
+
+**Response (202 Accepted):**
+
+```json
+{
+  "status": "accepted",
+  "visitor_id": "abc123...",
+  "session_id": "xyz789...",
+  "channel": "paid_search"
+}
+```
+
+### 2. New Files Required
+
+```
+lib/mbuzz/client/session_request.rb    # New request class
+```
+
+### 3. Update Middleware
+
+Update `lib/mbuzz/middleware/tracking.rb`:
+
+```ruby
+# Add session constant
+SESSION_COOKIE_NAME = "_mbuzz_sid"
+SESSION_COOKIE_MAX_AGE = 30 * 60  # 30 minutes
+
+def call(env)
+  @request = Rack::Request.new(env)
+
+  env[ENV_VISITOR_ID_KEY] = visitor_id
+  env[ENV_SESSION_ID_KEY] = session_id  # NEW
+
+  RequestContext.with_context(request: request) do
+    create_session_if_new  # NEW - fire and forget
+
+    status, headers, body = app.call(env)
+    set_visitor_cookie(headers)
+    set_session_cookie(headers)  # NEW
+    [status, headers, body]
+  end
+end
+
+private
+
+def session_id
+  @session_id ||= session_id_from_cookie || generate_session_id
+end
+
+def session_id_from_cookie
+  request.cookies[SESSION_COOKIE_NAME]
+end
+
+def generate_session_id
+  SecureRandom.hex(32)
+end
+
+def new_session?
+  session_id_from_cookie.nil?
+end
+
+def create_session_if_new
+  return unless new_session?
+
+  # Fire and forget - don't block the request
+  Thread.new do
+    Client.session(
+      visitor_id: visitor_id,
+      session_id: session_id,
+      url: request.url,
+      referrer: request.referer
+    )
+  rescue => e
+    # Log but don't raise - session creation is non-critical
+    Mbuzz.config.logger&.error("Session creation failed: #{e.message}")
+  end
+end
+
+def set_session_cookie(headers)
+  cookie_options = {
+    value: session_id,
+    path: VISITOR_COOKIE_PATH,
+    max_age: SESSION_COOKIE_MAX_AGE,
+    httponly: true,
+    same_site: VISITOR_COOKIE_SAME_SITE
+  }
+  cookie_options[:secure] = true if request.ssl?
+
+  Rack::Utils.set_cookie_header!(headers, SESSION_COOKIE_NAME, cookie_options)
+end
+```
+
+### 4. Add Client Method
+
+Update `lib/mbuzz/client.rb`:
+
+```ruby
+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
+```
+
+### 5. Create SessionRequest Class
+
+Create `lib/mbuzz/client/session_request.rb`:
+
+```ruby
+# 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?
+        visitor_id.present? && session_id.present? && url.present?
+      end
+
+      def payload
+        {
+          session: {
+            visitor_id: visitor_id,
+            session_id: session_id,
+            url: url,
+            referrer: referrer,
+            started_at: started_at
+          }.compact
+        }
+      end
+    end
+  end
+end
+```
+
+### 6. Add Constant
+
+Update `lib/mbuzz.rb`:
+
+```ruby
+SESSIONS_PATH = "/sessions"
+SESSION_COOKIE_NAME = "_mbuzz_sid"
+SESSION_COOKIE_MAX_AGE = 30 * 60  # 30 minutes
+
+ENV_SESSION_ID_KEY = "mbuzz.session_id"
+```
+
+### 7. Add Helper Method
+
+Update `lib/mbuzz/controller_helpers.rb`:
+
+```ruby
+def mbuzz_session_id
+  request.env[Mbuzz::ENV_SESSION_ID_KEY]
+end
+```
+
+---
+
+## Benefits
+
+1. **Accurate Attribution**: Sessions are created with full acquisition context (UTMs, referrer, channel) at session start, not when first event is tracked
+2. **Channel Attribution**: Backend determines channel immediately from URL/referrer
+3. **Consistent Data**: Session data matches the landing page, not a later page view
+4. **Decoupled from Events**: Sessions exist even if no events are tracked
+
+---
+
+## Migration Path
+
+### Breaking Changes
+
+None - this is additive. Existing events endpoint still creates sessions implicitly.
+
+### Recommended Upgrade
+
+1. Add session creation to middleware
+2. Add session cookie management
+3. Add `mbuzz_session_id` helper
+4. Bump version to 2.0.0
+
+---
+
+## Testing
+
+Add tests for:
+
+1. Session cookie is created on new visit
+2. Session cookie is reused within 30 minutes
+3. New session is created after 30 minute gap
+4. `POST /api/v1/sessions` is called on new session
+5. Session creation failures don't break the request
+6. `mbuzz_session_id` helper returns correct value
+
+---
+
+## API Contract
+
+See: `multibuzz/lib/docs/sdk/api_contract.md` for full endpoint documentation.
+
+Key points:
+- Sessions endpoint requires: `visitor_id`, `session_id`, `url`
+- Optional: `referrer`, `started_at`
+- Returns: `status`, `visitor_id`, `session_id`, `channel`
+- Backend extracts UTMs from URL, determines channel from UTM/referrer