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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## Unreleased
+
+- 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.
+- Events called before Mixpanel is ready now wait up to 5 seconds instead of rejecting an unobserved promise. Expired attempts log a controlled diagnostic, release their resources, and do not replay after late readiness.
+- 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,21 @@ window.addEventListener('Tracker Ready', () => {
 });
 ```
 
+Events called before Mixpanel is ready wait up to 5 seconds. If readiness never arrives, the SDK logs a controlled timeout and discards that attempt; later readiness does not replay it. Submission to Mixpanel does not guarantee remote delivery.
+
+`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.
+
 `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. One fresh identification per eligible event remains; navigation may interrupt background work. 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. 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 +73,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 unavailable, the SDK preserves its existing fingerprint fallback, sends the Mixpanel event, and skips the relay. Background identification failures are logged without changing or replacing the already-submitted event.
 
 ## Identifying Users
 
@@ -127,6 +125,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