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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## Unreleased
+
+- Accept zero departure and return stops in trip schemas so nonstop journeys can be tracked in Purchase Attempt and Payment Attempt.
+
+- 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.
+- 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
 
 - Delegate Bot Detection delivery to `js-api-client` 6.28.0's `fingerprint.sendObservation`: preserve SDK triggers and Mixpanel events, send `Fingerprint Requested` with configured Core API authentication, and use the client's bounded timeout instead of fetch keepalive.

package/README.md

@@ -44,23 +44,25 @@ window.addEventListener('Tracker Ready', () => {
 });
 ```
 
+Events called before Mixpanel is ready wait up to 5 seconds in the foreground. Valid unsent events can remain in memory for up to 60 seconds, bounded to 100 entries and 1 MiB of serialized snapshots. A later ready signal submits each retained event once. The oldest waiting entry is discarded when capacity is exhausted; individually oversized or unserializable pending payloads are discarded with a local diagnostic. Navigation or reload can lose retained work.
+
+Once this SDK invokes Mixpanel for an original event, it never retries that call, even if it throws: the provider might already have accepted the event. Separate consumer calls remain separate events, including calls with identical payloads. This limits SDK invocation to once per call; it does not guarantee remote delivery or end-to-end deduplication. Retained work is invalidated when the SDK switches user or starts a subsequent initialization; calls before the first init can join that initial anonymous session.
+
+`Tracker Ready` means Mixpanel and Core API configuration are ready. Fingerprint and geolocation initialize concurrently afterward and may still be unavailable. `await analytics.init(config)` waits up to 3 seconds for those optional stages after Mixpanel loads; browser permission prompts and late results can outlive that wait.
+
+Repeated SDK initialization with the same Mixpanel project and proxy reuses the initialized provider. Changing the project token or proxy after successful initialization is rejected before altering that active session; use a new page session for that change. Superseded initialization calls cannot replace newer Core API or Fingerprint configuration.
+
 `appName` is optional. When provided, it is sent as the `x-app-name` HTTP header on Datalake identify and anonymous-profile requests so the API can identify the originating client platform.
 
 ## Fingerprint Bot Detection relay
 
+For `Search`, `Payment Attempt`, and `Purchase Attempt`, the original Mixpanel event uses the cached visitor ID or an empty fingerprint. Fresh identification and relay run afterward in the background. A pending or failed identification does not delay that submission. Eligible observation work waits up to 10 seconds for the agent and is bounded to 100 intents and three actual identification requests in flight. Navigation may interrupt background work. View Results also submits cached or empty identity before refreshing Fingerprint in the background; its late result does not replay the event. Other events continue with an empty fingerprint if retrieval rejects.
+
 Fingerprint Bot Detection results are retrieved through Fingerprint Server API by Core API. This browser SDK does not call Server API or accept its Secret API Key. It can obtain the request-scoped `requestId` and relay the identification context to Core API.
 
 The SDK owns the eligible event list. Consumers do not configure a URL or choose events. Bot Detection currently runs on `Search`, `Payment Attempt`, and `Purchase Attempt`. The destination is built from the Core API `baseUrl`.
 
-For those events, the SDK requests a fresh Fingerprint identification, bypassing the Fingerprint SPA cache. This adds Fingerprint latency and an identification request before the original Mixpanel event is submitted. All other events keep the existing cache behavior.
-
-When identification succeeds, the original event contains:
-
-```json
-{
-  "User Fingerprint": "visitor-123"
-}
-```
+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:
 
@@ -75,7 +77,7 @@ After handing the original event to Mixpanel, the SDK sends this JSON payload to
 
 `distinctId` is omitted when Mixpanel cannot provide one. The Core API response is not used to modify the original event. The SDK sends the generated `requestId` only in the Core API relay payload. Core API owns the Fingerprint Server API lookup and any later enrichment.
 
-Relay failures are logged with `console.error` and do not turn an event already submitted to Mixpanel into a tracking failure. If the Fingerprint agent is unavailable, the SDK preserves its existing fingerprint fallback, sends the Mixpanel event, and skips the relay. A failure during an identification that already started follows the SDK's existing tracking error behavior.
+Relay failures are logged with `console.error` and do not turn an event already submitted to Mixpanel into a tracking failure. If the Fingerprint agent is still loading, the SDK sends the Mixpanel event immediately and defers only the observation within its ten-second budget. Expired observations, changed identity/configuration, and capacity overflow produce local diagnostics. Late identification results after expiry or identity/configuration changes do not update the cache or profile or start a relay. A provider request that remains pending still occupies one of the three concurrency slots until it settles; the SDK does not cancel the underlying request. Background identification failures are logged without changing or replacing the already-submitted event.
 
 ## Identifying Users
 
@@ -127,6 +129,10 @@ The authoritative local checks are:
 
 Run the full command before a push or pull request. See [the workflow](docs/agents/compound-engineering-workflow.md), [environment setup](docs/agents/setup-and-environments.md), and [review criteria](CODING_STANDARDS.md).
 
+### Releases
+
+Merging a PR into `main` with exactly one `patch`, `minor`, or `major` release label publishes a stable package automatically. Alphas remain manual: run **Publish to NPM** from `main`, selecting the channel, increment, and source branch. Stable releases require source `main`; alphas also support the temporary `alpha-sbx` integration branch. A lone `alpha` label does not publish on merge. See [the release process](docs/releases.md) for both paths, version allocation, commands, and recovery.
+
 ### OpenSpec prerequisites
 
 ### Prerequisites