Merge pull request #33 from blendto/user-traits

User traits

Author: deepakg202

docs/README.md

@@ -28,7 +28,7 @@ verified in their own repositories.
 
 ## Current compatibility
 
-- package version: `0.5.0`;
+- package version: `0.5.3`;
 - session JSON schema: `9`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;

docs/integration/collector.md

@@ -159,7 +159,7 @@ The SDK calls:
 
 | Request | Purpose |
 | --- | --- |
-| `POST /v1/sessions` | `session_start` and `session_end` lifecycle payloads |
+| `POST /v1/sessions` | Session lifecycle and identity: `session_start`, `session_identify`, `session_end`, `traits_updated`, `user_changed` |
 | `POST /v1/events/batch` | JSON event batches |
 | `POST /v1/frames` | multipart PNG frame upload |
 
@@ -173,10 +173,30 @@ an accepted start response and reads its `sessionId`; events, frames, and the
 end lifecycle request then use that collector-issued ID. Events and frames are
 not uploaded before this handshake completes.
 
+Session payloads may include:
+
+- `traits` — full traits snapshot when the host has set a bag (`session_start`,
+  `session_identify`, `traits_updated`, `user_changed`); the collector stores
+  the bag as-is (no server-side partial merge);
+- `traitsId` — pass-through of a prior collector-issued id when no new bag is
+  sent (for example `session_end`, or `session_start` after only an id is
+  cached). Ignored by the collector when `traits` is present.
+
+Accepted session responses (`202`) may return `traitsId`. The SDK caches that
+value in process memory and stamps it onto subsequent event batches. Host apps
+register traits with `TugboatReplay.setTraits` and change the runtime user with
+`TugboatReplay.setUserId`. While `session_start` is still pending, both APIs
+update in-memory identity only (folded into start at send time). After start,
+changes within 3s coalesce into one lifecycle POST: `session_identify` when
+both user and traits change, otherwise `user_changed` or `traits_updated`.
+Debounced updates are flushed before `session_end`. The SDK does **not** call
+`/v1/identify` or `/v1/events/identify`.
+
 Event payloads contain:
 
 - event ID, type, `atMs`, and absolute UTC `triggeredAt`;
 - optional user/session/run/action IDs;
+- optional `traitsId` (pass-through only; does not upsert the traits dictionary);
 - optional before/after frame references, related-event ID, and result;
 - serialized state and target anchors;
 - event-specific data under `payload`;

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,46 @@
+## 0.5.3
+
+### Added
+
+- **Debounced identity coalesce** — after `session_start`, `setUserId` and
+  `setTraits` within 3s consolidate into one `session_identify` POST when
+  both change; otherwise `user_changed` or `traits_updated`. Pending updates are
+  flushed before `session_end`.
+
+### Changed
+
+- Pre-start identity still folds into a single `session_start` when values are
+  staged before or while start is pending.
+
+## 0.5.2
+
+### Changed
+
+- **`setUserId` folds into pending `session_start`** — when a `session_start`
+  is still pending, `CollectorHttpSink.setUserId` updates the runtime id only
+  and skips `user_changed` (same coalesce already used by `setTraits`). Boot
+  identity can land on a single `session_start` POST.
+
+## 0.5.1
+
+### Added
+
+- **User traits via collector sessions** — `TugboatReplay.setTraits` posts
+  `eventType: traits_updated` on `POST /v1/sessions` with a full traits bag,
+  caches the response `traitsId`, and stamps it on event batches.
+  `TugboatReplay.setUserId` posts `user_changed` and updates the runtime user
+  id. Pre-set traits are included on the next `session_start`. No
+  `/v1/identify` route.
+
+### Changed
+
+- **`setUserId` skips unchanged ids** — calling `TugboatReplay.setUserId` /
+  `CollectorHttpSink.setUserId` with the same value as the current runtime
+  user id does not post `user_changed`.
+- **Pre-initialize identify** — `setTraits` / `setUserId` called after the
+  controller mounts but before the HTTP sink is created retain identity for
+  the next `session_start` instead of dropping it.
+
 ## 0.5.0
 
 ### Breaking changes

packages/tugboat/README.md

@@ -5,7 +5,7 @@ checkpoints around meaningful interactions, compact structural anchors, route
 transitions, scrolling evidence, and optional viewport semantic maps. Capture
 can be sent to the local exploration WebSocket, the HTTP collector, or both.
 
-The current package version is `0.5.0`. Session JSON writers emit schema
+The current package version is `0.5.3`. Session JSON writers emit schema
 version `9`; compatibility readers should accept versions `6` through
 `9`. Structural fingerprints use fingerprint schema version `6`.
 
@@ -153,11 +153,37 @@ Identity contract:
 - `captureSessionId` (`session.id`) — SDK-generated emitted evidence session
 - `collectorSessionId` — stamped after HTTP `session_start` acceptance
 - `explorationRunId` — exploration control-plane ID from config
+- `traitsId` — collector-issued traits dictionary id after `setTraits` / session responses
 
 `TugboatReplay.activeSessionId` remains as a deprecated alias for
 `activationRequestId`. Inspect `TugboatReplay.health` for sink/outbox/screenshot
 budget pressure without reading protected content.
 
+### User traits and user id
+
+When an HTTP collector is configured, register a full traits snapshot (not a
+partial merge) via `POST /v1/sessions`:
+
+```dart
+await TugboatReplay.setTraits({
+  'plan': 'pro',
+  'seatCount': 3,
+});
+
+await TugboatReplay.setUserId(currentUserId);
+```
+
+- `setTraits` debounces `traits_updated` (3s) after start acceptance, or
+  `session_identify` when combined with a pending user change. Caches
+  `traitsId` and stamps it on event batches. While `session_start` is pending,
+  updates memory only (folded into start at send time).
+- `setUserId` debounces `user_changed` (3s) after start acceptance, or
+  `session_identify` when combined with a pending traits change. Unchanged ids
+  are ignored. While `session_start` is pending, updates memory only.
+- Pre-activate calls are retained in memory and included on the next
+  `session_start` when present. Pending debounced updates flush on `session_end`.
+  There is no `/v1/identify` route.
+
 Optional durable HTTP delivery (Collector only, default off):
 
 ```dart
@@ -263,7 +289,7 @@ Emitted event types currently include:
   immutable `origin`, `result`, `attribution`, and `evidenceEventIds`;
 - legacy gesture peers (`stream: legacy_projection` when canonical is on):
   `tap`, `tap_settled`, `swipe`, `tap_outside_tree`, `tap_gesture_resolved`;
-- lifecycle: `session_start`, `session_end`;
+- lifecycle: `session_start`, `session_identify`, `session_end`;
 - input: `pointer_cancel` (`stream: evidence`);
 - state/navigation evidence (`stream: evidence`): `state_change`, `route_change`
   (claimed routes also carry `causedByInteractionId`);
@@ -380,11 +406,12 @@ so it is suitable for health polling and cannot grow with session duration.
 
 ## Public surface
 
-The supported import exports `TugboatReplay`, `TugboatNavigatorObserver`,
-`TugboatReplayConfig`, capture/semantic/masking enums and policies, collector
-configuration and host helpers, markers (`TugboatSensitive`, `TugboatTag`,
-`TugboatSubView`, `TugboatInternal`), anchor and session models, the controller,
-and `TugboatExplorationTransport`.
+The supported import exports `TugboatReplay` (including `setTraits` /
+`setUserId`), `TugboatNavigatorObserver`, `TugboatReplayConfig`,
+capture/semantic/masking enums and policies, collector configuration and host
+helpers, markers (`TugboatSensitive`, `TugboatTag`, `TugboatSubView`,
+`TugboatInternal`), anchor and session models, the controller, and
+`TugboatExplorationTransport`.
 
 `TugboatCaptureSink` and the built-in sink implementations are internal today;
 config supports only the WebSocket and HTTP destinations above. A stable custom

packages/tugboat/example/pubspec.yaml

@@ -32,7 +32,7 @@ resolution: workspace
 dependencies:
   flutter:
     sdk: flutter
-  tugboat: ^0.5.0
+  tugboat: ^0.5.3
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.