feat: add session tracking

[gunoooo]

Summary

• Add session tracking to the React Native SDK
• SessionService tracks SESSION_START events using React Native's AppState API for lifecycle detection (background → active)
• Timeout-based session management with configurable sessionTimeoutMs (default 30s, minimum 5s enforced)
• Push notification tap attributes session via pendingMessageId through NotificationService
• Add sessionTimeoutMs to ClixConfig

Changes

• New: src/services/SessionService.ts — SessionService with AppState listener, SessionEvent enum
• Modified: src/core/Clix.ts — Initialize and start SessionService
• Modified: src/core/ClixConfig.ts — Add sessionTimeoutMs field (default 30000)
• Modified: src/services/NotificationService.ts — Set pendingMessageId on push tap for session attribution

Spec

• https://www.notion.so/greyboxhq/Tech-Clix-Session-3031f02665f180dfa04bc91a836f0889

Summary by CodeRabbit

• New Features
  • Added session management with automatic activity tracking and app-state monitoring.
  • Sessions automatically resume if activity falls within a configurable timeout, otherwise start a new session.
  • Push notification taps now record a pending message ID so notification interactions are tracked within the active session.

[coderabbitai]

Walkthrough

Introduces a new SessionService that manages session lifecycle (AppState tracking, last-activity persistence, pending message handling) and integrates it into Clix core and NotificationService, with an optional sessionTimeoutMs configuration entry.

Changes

Cohort / File(s)	Summary
Session Service Implementation src/services/SessionService.ts	Adds SessionService class: persists last activity, listens to AppState changes, resumes or starts sessions based on timeout, supports setPendingMessageId, exposes start() and cleanup(), and tracks SESSION_START events via EventService.
Configuration & Core Integration src/core/ClixConfig.ts, src/core/Clix.ts	Adds optional sessionTimeoutMs?: number to ClixConfig. Clix now declares sessionService?: SessionService, instantiates it with StorageService, EventService, and configured timeout, passes it into NotificationService, and starts the session service after notifications initialize.
Notification Service Integration src/services/NotificationService.ts	NotificationService constructor accepts optional SessionService. trackPushTappedEvent now calls sessionService?.setPendingMessageId(payload.messageId) before tracking the push-tap event.

Possibly related PRs

• feat: extend StorageService to support MMKV v2–v4 #3 — Modifies Clix initialization and NotificationService constructor wiring; overlaps with this PR's changes to Clix and service dependencies.
• fix: reorder event logging and push display #18 — Changes NotificationService push event handling; related to the addition of pending message ID handling and event ordering in this PR.

Suggested reviewers

• pitzcarraldo

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add session tracking' clearly and concisely summarizes the main change—introducing session tracking functionality to the SDK.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-session

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

src/services/SessionService.ts (3)

27-46: Make start() idempotent to avoid duplicate listeners.
If start() is called more than once, multiple AppState subscriptions will accumulate.

♻️ Proposed fix

 async start(): Promise<void> {
+  if (this.appStateSubscription) {
+    return;
+  }
   this.appStateSubscription = AppState.addEventListener(
     'change',
     this.handleAppStateChange.bind(this)
   );

---

48-73: Re-check AppState after the 100ms delay.
A rapid active→background transition during the delay can still run the active-path logic and start/resume a session while backgrounded.

🛡️ Proposed guard

     if (previousAppState === 'background' && nextAppState === 'active') {
       // Small delay to allow notification tap handlers to set pendingMessageId
       await new Promise((resolve) => setTimeout(resolve, 100));
+      if (this.lastAppState !== 'active') {
+        return;
+      }

---

100-102: Clear the subscription reference after cleanup.
This enables safe re-starts if start() is called again later.

♻️ Proposed fix

 cleanup(): void {
   this.appStateSubscription?.remove();
+  this.appStateSubscription = undefined;
 }

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8f2b38f21

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/services/SessionService.ts`:
- Around line 47-70: handleAppStateChange can run concurrently because of the
async delay, causing duplicate SESSION_START events; update this.lastAppState
eagerly at the start of handleAppStateChange (before the await) or add a simple
boolean guard (e.g., isHandlingStateChange) to short-circuit re-entrant calls;
specifically modify the handleAppStateChange method to set this.lastAppState =
nextAppState immediately (or acquire/set isHandlingStateChange true at entry and
clear it on exit) so the subsequent logic (timeout check, updateLastActivity,
startNewSession) cannot run concurrently for the same transition.
- Around line 97-99: The SessionService.cleanup() subscriber removal is never
invoked because Clix lacks a teardown path; add a public deinitialize() (or
similar) method on the Clix class that calls sessionService.cleanup() (and any
other services' cleanup/shutdown methods), expose it on the SDK API so consumers
can call it, and ensure any internal code paths that recreate Clix instances
call deinitialize() before reinitializing to prevent AppState listener
accumulation.

🧹 Nitpick comments (1)

src/services/SessionService.ts (1)

27-45: Duplicate session-continuation logic in start() and handleAppStateChange().

Lines 33–43 and 54–64 share identical read-lastActivity / check-elapsed / continue-or-start logic. Extracting this into a private helper (e.g., resumeOrStartSession()) would reduce duplication and make future changes less error-prone.

Also applies to: 54-64