@reservamos/browser-analytics 1.1.8-alpha.1 → 1.1.8-alpha.2

package/CHANGELOG.md

@@ -2,15 +2,28 @@
 
 ## Unreleased
 
+- Pin js-api-client 6.28.1 to keep an initiated Fingerprint observation relay alive across navigation within browser limits; retain its five-second timeout and add a local redirect fixture.
+
+- Apply Identify identity and initial people properties before optional profile/fingerprint enrichment; resolve locally before enrichment and suppress stale results without mutating caller properties.
+- Add `analytics.identifiers.waitForFingerprintId(timeoutMs = 2000)` to await cached or in-flight identity within a caller budget without forcing fresh identification; preserve late successful cache updates when the caller times out and the identity lifecycle remains current.
+- Accept optional validated `product` on Purchase Confirmation Viewed. These additive public changes require minor release impact.
+- Accept an optional `Coupon` on `Passengers Created`, validated like `Payment Attempt`, so checkout events that carry a coupon are no longer rejected.
+
 - Accept zero departure and return stops in trip schemas so nonstop journeys can be tracked in Purchase Attempt and Payment Attempt.
 
+- Submit View Results with cached or empty identity before refreshing Fingerprint, so pending identification cannot block the event.
+
 - Retain valid events that have not reached Mixpanel for up to 60 seconds with bounded memory and a five-second foreground wait. Claim each event once and never retry a submission that throws, preventing SDK recovery from replaying uncertain sends.
 - Defer Bot Detection observations for up to ten seconds while Fingerprint loads, cap actual identification concurrency at three, and suppress expired or stale identity/configuration effects without replaying original Mixpanel events.
 - Invalidate stale readiness during reinitialization, preserve original pending payload snapshots, and reuse matching Mixpanel singleton initialization without awaiting an unavailable callback. Reject unsupported in-place project/proxy changes before disturbing the active session.
 
-- Add manual alpha and stable publication alongside automatic patch/minor/major releases for PRs merged into main. Alphas also support the temporary alpha-sbx branch; both paths allocate versions from npm, validate fully, and tag the exact source commit without version commits on main.
-- A pending location permission or Fingerprint load no longer holds Tracker Ready. Core API is configured before listeners run; optional initialization waits are bounded to 3 seconds and pre-initialization fingerprint cache reads remain safe.
 - Search, Payment Attempt, and Purchase Attempt are submitted before fresh Fingerprint identification and Bot Detection relay. View Results and other non-bot events continue with an empty fingerprint when retrieval fails.
+
+- A pending location permission or Fingerprint load no longer holds Tracker Ready. Core API is configured before listeners run; optional initialization waits are bounded to 3 seconds and pre-initialization fingerprint cache reads remain safe.
+- Document that Search, Payment Attempt and Purchase Attempt fired before Fingerprint readiness can omit Bot Detection observations when Fingerprint remains unavailable throughout the ten-second deferral window; regression coverage verifies original event submission and no replay after optional initialization.
+
+- Events called before Mixpanel is ready now wait up to 5 seconds instead of rejecting an unobserved promise, and resume directly when Mixpanel loads without waiting for optional initialization or `Tracker Ready`. Expired attempts log a controlled diagnostic, release their resources, and do not replay after late readiness.
+- Add manual alpha and stable publication alongside automatic patch/minor/major releases for PRs merged into main. Alphas also support the temporary alpha-sbx branch; both paths allocate versions from npm, validate fully, and tag the exact source commit without version commits on main.
 - Blocked SDK localStorage no longer discards events or live Mixpanel identity. Cache fallback safely returns null when unavailable, and identify retains its controlled cache diagnostic and people updates.
 
 ## 1.1.7

package/README.md

@@ -64,14 +64,14 @@ The SDK owns the eligible event list. Consumers do not configure a URL or choose
 
 For those events, fresh identification bypasses the Fingerprint SPA cache and runs in the background after the original event has been submitted. Its returned visitor ID and request ID are used for the relay; they do not replace the cached or empty fingerprint already submitted with the original event. View Results submits cached or empty identity before refreshing Fingerprint without a Bot Detection relay. Other events retain their existing cache selection and continue with an empty fingerprint if retrieval rejects.
 
-After handing the original event to Mixpanel, the SDK sends this JSON payload to `${coreApiBaseUrl}/v1/fingerprint/bot-detection` with `POST`, `Content-Type: application/json`, optional `x-app-name`, and `keepalive: true`. The browser supplies the actual `Origin` header:
+After handing the original event to Mixpanel, the SDK sends this JSON payload to `${coreApiBaseUrl}/v1/fingerprint/bot-detection` with `POST`, `Content-Type: application/json`, optional `x-app-name`, through `js-api-client`. The pinned 6.28.1 client uses fetch `keepalive` with a five-second abort, allowing an already-started relay to continue after navigation within browser transport limits. The browser supplies the actual `Origin` header:
 
 ```json
 {
   "requestId": "request-123",
   "visitorId": "visitor-123",
   "distinctId": "mixpanel-distinct-123",
-  "eventName": "Payment Attempt"
+  "eventName": "Fingerprint Requested"
 }
 ```
 
@@ -81,7 +81,7 @@ Relay failures are logged with `console.error` and do not turn an event already
 
 ## Identifying Users
 
-`await analytics.identify(...)` waits for the local identification attempt, not confirmed remote delivery. The SDK limits readiness to 5 seconds, anonymous-profile enrichment to 3 seconds, and fingerprint enrichment to 2 seconds. Optional enrichment or SDK cache failures do not block the Mixpanel attempt. Once readiness expires, a later `Tracker Ready` does not reactivate that call.
+`await analytics.identify(...)` resolves after Mixpanel identity and initial people properties are submitted locally, without waiting for optional enrichment or confirming remote delivery. Readiness is limited to 5 seconds before that submission; anonymous-profile enrichment and fingerprint enrichment run afterward with limits of 3 and 2 seconds. Once readiness expires, a later `Tracker Ready` does not reactivate that call.
 
 Mixpanel profile callbacks and the existing geolocation request are observed separately for up to 5 seconds. The SDK does not retry requests; a missing callback means its outcome was not observed. Diagnostics use controlled stage/reason values without user identifiers or personal properties. `Visitor Found` is optional metadata: available booleans are preserved, and absent values are not replaced with `false` or inferred from cache state.
 
@@ -165,3 +165,25 @@ Use these slash commands in Cursor or Claude Code:
 5. `/opsx-archive` — move the change to `openspec/changes/archive/`
 
 When OpenSpec is used, `tasks.md` is the canonical implementation plan. Do not also run `ce-plan` for the same change.
+
+## Comporte redirect and identity readiness
+
+`await analytics.identify(userId, properties)` resolves after Mixpanel identity and the initial people properties are submitted locally. Anonymous profile and fingerprint enrichment run afterward, with their existing time limits. A later profile ID updates `reservamos_one_id` without identifying again. New identify attempts or initialization invalidate stale enrichment; caller properties are not mutated. Redirects can interrupt background work, and local completion does not guarantee remote delivery.
+
+`analytics.identifiers.getFingerprintId()` remains a synchronous cache lookup. To wait for agent loading or an identification already in flight, use:
+
+```typescript
+const fingerprintId = await analytics.identifiers.waitForFingerprintId(2000);
+// fingerprintId is string | null. Waiting does not force a fresh FPJS request.
+analytics.track.search(searchProperties);
+```
+
+The wait defaults to 2000 ms and resolves `null` on timeout, failure or replaced session/initialization. Concurrent waits share identification; the timeout does not cancel an underlying provider request, and a late successful result still fills the cache while its initialization and identity lifecycle remain current. When neither cache nor in-flight work exists, waiting can start one cache-eligible FPJS identification. Eligible Bot Detection events still request their own fresh identification as before. Events keep their nonblocking cached-or-empty fingerprint behavior. If the cache cannot be written, the returned ID is still available, but later events may carry an empty fingerprint.
+
+Send `analytics.track.purchaseConfirmation` when the confirmation page is viewed, with `Operation Id` and `Payment Status` (`confirmed` or `pending_pix`). Optional `product` accepts the same values as other SDK events (`web`, `web-mobile`, `ios`, `android`, `app`). This browser event is separate from datalake's Purchase Completed.
+
+## Local relay navigation check
+
+Run `node scripts/serve-relay-redirect.mjs` and open the printed URL in a browser. The fixture invokes the real SDK relay with dummy IDs and credentials against a second local origin, then navigates without awaiting it. The local backend delays its response by 1.5 seconds. Read its `/observations` endpoint afterward to check CORS preflight, one POST, headers, normal completion or early disconnection. The pending-IDs button navigates before its simulated IDs exist and should produce no POST.
+
+This check uses the published 6.28.1 client pinned by the SDK; it can also be repeated with a locally built candidate. Candidate verification is recorded in `openspec/changes/sdk-relay-keepalive/verification.md`; Comporte staging is still needed for their real origin, FPJS acquisition and backend. The fixture contacts only its localhost backend and does not initialize real Mixpanel or Fingerprint services.