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

package/CHANGELOG.md

@@ -2,15 +2,32 @@
 
 ## 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.
+
+- Recover pending `reservamos_one_id` profile enrichment after same-tab, same-origin navigation without another application identify call. Scope the original normalized Core request in sessionStorage to the current user and configuration, expire it after ten minutes, and limit profile requests to three attempts. Keep foreground identity nonblocking and fall back to ordinary in-memory enrichment when storage is unavailable.
+
+- Reduce the Mixpanel batch flush interval to one second for events and people updates, including native identity events, while retaining batching and local identify completion semantics. Smaller batches can increase HTTP requests; the interval does not guarantee delivery before redirects.
+
+- 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,9 +81,9 @@ 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.
+Mixpanel profile callbacks and the existing geolocation request are observed separately for up to 5 seconds. Profile recovery after navigation is bounded as described below; other optional requests are not retried. 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.
 
 The `identify` method accepts a main identifier and an object containing user information. The object has four predefined fields: `email`, `firstName`, `lastName`, and `phone`. In addition to these, you can include any custom fields to store additional user-specific information as needed.
 
@@ -165,3 +165,31 @@ 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.
+
+The SDK keeps Mixpanel batching enabled and configures a 1000 ms batch flush interval for events and people updates, including the native `$identify` event. This reduces queueing time before short redirects, but can produce smaller batches and more HTTP requests. Network delays and retries can extend delivery beyond that interval; it does not guarantee receipt before navigation.
+
+Pending `reservamos_one_id` enrichment can resume after a full-page redirect when the destination initializes the SDK in the same tab and origin, with the same Mixpanel project/proxy, Core API base URL/application, and current user. No additional application `identify()` call is needed. Recovery restores native people readiness for that unchanged user without emitting a new `$identify` event; it does not replay business events or location identification.
+
+The SDK stores at most one 4 KiB recovery entry in `sessionStorage`, containing the current user ID, configuration scope, attempt metadata, and the normalized original Core profile request: its email/phone, additional identifiers (including captured fingerprint and distinct ID), and name fields when supplied. Arbitrary custom properties and credentials are excluded. Replaying the same request preserves profile matching and details; it does not rebuild identifiers in the destination. The SDK replaces that request with the profile ID once resolved, then removes the entry after Mixpanel accepts the property update into its queue or confirms an unbatched request. Queue acceptance does not confirm remote delivery. Unresolved profiles allow at most three HTTP attempts, including the original, with no retry loop within one initialization. Entries expire after ten minutes and are checked and cleaned on SDK reads; tab closure ends their storage lifetime. Invalid entries and user/configuration mismatches are discarded. Blocked storage preserves ordinary in-memory enrichment but prevents recovery across navigation. A recovery HTTP request starts only after its attempt count is saved.
+
+`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.