unshared-frontend-sdk 3.0.0-rc.14 → 3.0.0

package/README.md

@@ -80,6 +80,8 @@ new UnsharedBrowser({
 });
 ```
 
+### BrowserConfig
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `baseUrl` | `string` | `undefined` | Proxy mode: base URL of your backend. Use `""` when your frontend and backend share the same domain. Omitting both `baseUrl` and `publishableKey` defaults to same-origin proxy mode (unless a key was baked into a client-specific build — see below). |
@@ -87,6 +89,10 @@ new UnsharedBrowser({
 | `apiUrl` | `string` | `https://api.unshared.ai` | Direct mode: Unshared Labs platform origin. |
 | `maxRetries` | `number` | `3` | Retry budget for eligible operations |
 | `timeout` | `number` | `30000` | Per-attempt timeout in milliseconds |
+| `includePathPrefix` | `string[]` | Unset (all paths) | Literal `location.pathname` prefixes for lifecycle event submission; `[]` submits on none. This is browser-side filtering, not server enforcement. |
+| `skipPaths` | `string[]` | Unset | Literal pathname prefixes excluded from lifecycle submission; wins over includes. Does not prevent explicit `init()` from establishing identity/collecting, or disable low-level collection methods. |
+| `sessionId` | `() => string \| undefined` | Cookie, then UUID | Resolver runs at construction; a defined value wins over `__unshared_sid`/generated UUID and is persisted to the correlation cookie. Not an auth-session TTL setting. |
+| `deviceId` | `() => string \| undefined` | Legacy stored device, then collected stable hash | Resolver runs at construction and init; a nonempty value overrides the device identifier, not the canonical collected hashes or separate permanent ID. |
 | `enableInterstitial` | `boolean` | `false` | Auto-render the interstitial modal when the user is flagged (via the `unshared:flagged` event); works in direct or proxy mode. See [Interstitial modal](#interstitial-modal). |
 | `interstitialFlowType` | `string` | `email_verification` | Flow type requested for the auto-shown interstitial. |
 
@@ -104,7 +110,14 @@ Build a client-specific distribution with:
 UNSHARED_PUBLISHABLE_API_KEY=upk_test_or_client_key npm --prefix sdks/javascript/browser run build
 ```
 
-Passing `baseUrl`, including `baseUrl: ""`, keeps proxy mode and suppresses the packaged-key fallback.
+Passing `baseUrl`, including `baseUrl: ""`, suppresses the packaged-key fallback
+and keeps proxy mode unless an explicit nonempty `publishableKey` is supplied.
+
+An explicit nonempty `publishableKey` takes precedence even when `baseUrl` is also
+passed; `baseUrl` suppresses only the packaged-key fallback. Use HTTPS origins
+(HTTP is accepted only for loopback development), and never put a secret `usk_` key
+in browser config. `maxRetries` applies only to eligible reads, not ingestion,
+Trigger or Verify.
 
 The build applies targeted obfuscation before minification to the packaged publishable key and the default API URL so they are not present as obvious raw string literals in `dist/index.umd.js`. This is only a friction layer against casual source inspection; the browser still reconstructs those values at runtime, and server-side origin allowlists/rate limits remain the real security controls.
 
@@ -123,6 +136,44 @@ Use the confidential-docs override only for local investigation; do not commit m
 
 ## Methods
 
+### Identity and Lifecycle
+
+Call `init({ userId, emailAddress, isPaidSubscriber })` after authenticated identity
+is available, `onRouteChange()` on SPA navigation, and `client.destroy()` on logout
+or teardown. `isPaidSubscriber: false` suppresses collection/submission for that
+user. `destroy()` clears cached collection/login state and detaches listeners; it
+does not erase permanent device/hash cookies or change your application's auth TTL.
+
+Init and MPA collection reuse a paired raw/wire fingerprint cache: the complete raw
+JSON is in per-tab sessionStorage `__unshared_fp_raw`, and the normalized wire view
+is in `__unshared_fp`. SPA events reuse this pair rather than recollecting; overlapping
+init/MPA collection shares one pending collection per SDK instance. Old wire-only
+caches are recollected. In-memory fallback keeps the current instance usable when
+storage is blocked, but cannot persist across reloads.
+
+Eligible init/route submission activity refreshes readable correlation cookies to
+rolling **400 days (`Max-Age=34560000`) before deduplication**, even if no new event
+is sent: `__unshared_stable_hash`, `__unshared_full_hash`, `__unshared_device_id`,
+legacy stable alias `__unshared_fp_id`, and `__unshared_sid`. The permanent
+`__unshared_device_id=upid_<uuid-v4>` is independent of mutable hashes, backed by
+localStorage; an existing valid localStorage ID takes precedence over a cookie when
+restoring it. Cookies use `Path=/`, `SameSite=Lax` and `Secure` on HTTPS. Browser
+privacy controls, storage blocking and user deletion can shorten retention.
+
+With the protection proxy, the server also writes the legacy HttpOnly
+`__unshared_fingerprint_id`: it preserves the first full hash, while canonical
+`__unshared_full_hash` tracks the current collection. Only a server response can
+renew that HttpOnly alias. These correlation lifetimes do not extend authentication:
+the SDK UID/email server cookies retain their existing 365-day TTL and the
+verification challenge remains ten minutes. The per-tab collection cache is not a
+400-day fingerprint snapshot.
+
+Lifecycle submissions share `window.__unshared.lastKey` with the inline middleware
+script and mirror the last `(user, pathname + query)` in sessionStorage. Consecutive
+duplicates are suppressed, including reloads in the tab; A-to-B-to-A can submit
+again. This is not guaranteed delivery: no persistent replay queue is maintained,
+old queue entries are discarded, and failed ingestion is not retried.
+
 ### `collect()`
 
 Collect a browser fingerprint. Returns a `FingerprintWireFormat` object ready to pass to `submitFingerprintEvent`.
@@ -222,9 +273,15 @@ flow is authored in the Unshared dashboard and stored per company; the SDK fetch
 published definition from `GET /v2/browser/interstitial-flow`, renders it in a
 Shadow-DOM-isolated modal, and routes the flow's actions back through
 `triggerEmailVerification()` / `verify()` above — so all verification logic stays
-server-side. Direct mode only (requires `publishableKey`).
+server-side. Direct mode uses `publishableKey`; proxy mode is described below.
 
-**Proxy mode is supported too.** When the SDK is constructed with `baseUrl` (no `publishableKey`) and your backend runs the Node middleware, `showInterstitial()` fetches the flow through `GET {baseUrl}/__unshared/interstitial-flow` and runs the modal's actions through the middleware's `/__unshared/verify-trigger` and `/__unshared/verify` routes. The secret key never leaves your server, and the user's identity is resolved server-side — the browser sends only the OTP. This requires your middleware to resolve the email server-side (a `resolveEmailAddress` resolver or the `__unshared_email` cookie), the same requirement as the verify routes.
+**Proxy mode is supported too.** When the SDK is constructed with `baseUrl` (no `publishableKey`) and your backend runs the Node middleware, `showInterstitial()` fetches the flow through `GET {baseUrl}/__unshared/interstitial-flow` and runs the modal's actions through the middleware's `/__unshared/verify-trigger` and `/__unshared/verify` routes. The secret key never leaves your server, and the user's identity is resolved server-side; the browser sends only the OTP. Configure the middleware's trusted `emailAddress` resolver (preferred over the `__unshared_email` cookie fallback).
+
+Publish the requested web flow for your company in the dashboard before enabling
+the modal; a draft/missing flow cannot render. A modal or blur alone is not access
+control: use server-side gate/403 enforcement for protected content. Verification
+rate limits and attempt budgets are existing platform controls, not new browser
+functionality; additional custom gates/rate limits belong to your app or gateway.
 
 ### `showInterstitial(opts?)`
 
@@ -279,9 +336,34 @@ const app = express();
 const client = new UnsharedClient({ apiKey: process.env.UNSHARED_API_KEY });
 
 app.use(express.json());
-app.use(unsharedBoundToUser(client, { userId: (req) => req.session?.user?.id }));
+// Mount your authentication/session middleware before the SDK.
+const middleware = unsharedBoundToUser(client, {
+  userId: (req) => req.session?.user?.id,
+  emailAddress: (req) => req.session?.user?.email,
+});
+app.use(middleware);
+// Call middleware.destroy() on server shutdown/test teardown/before re-mounting.
 ```
 
+Node `includePathPrefix` scopes ordinary checks/enforcement/events, not identity
+bootstrap or eligible HTML injection. For example, include `/api/article/` to gate
+article data while `/api/me/list` remains outside enforcement; the surrounding HTML
+can still bootstrap fingerprinting. Node `skipPaths` truly bypasses the SDK for
+matching application requests. These server options are separate from browser
+lifecycle path filters. See the [complete protection config](../node/README.md#protectionconfig).
+
+The Node middleware serves both `/__unshared/fp.js` (browser SDK) and
+`/__unshared/fingerprint.js` (agent); unavailable bundles return 503 with
+`Cache-Control: no-store`. The Web Standard handler instead requires a manually
+supplied `fingerprintSdkBundle` for `fp.js` and does not automatically serve
+`fingerprint.js` or `interstitial-flow`; wire those separately when needed.
+
+For the injected script, middleware `debug: true` exposes PII-free reason codes and
+optional HTTP status in `window.__unshared.lastDecision` and `[Unshared]` debug logs
+(for example `MISSING_UID`, `DEDUP_SKIPPED`, `ASSET_LOAD_ERROR`, `SUBMIT_SUCCESS`).
+Middleware `disableBotFilter: true` also reaches the inline submitter for E2E tests.
+Neither is a `BrowserConfig` option; the standalone SDK's bot filter is unchanged.
+
 ---
 
 ## Error handling

package/dist/browser.d.ts

@@ -172,6 +172,7 @@ export declare class UnsharedBrowser {
     /** True after init() with isPaidSubscriber:false — blocks every submission path. */
     private _doNotCollect;
     private _mpaHandler;
+    private readonly _lifecycleState;
     /** Interstitial auto-show config + live state. */
     private readonly _enableInterstitial;
     private readonly _interstitialFlowType;
@@ -179,22 +180,6 @@ export declare class UnsharedBrowser {
     private _interstitialHandle;
     /** Guards against rendering the modal more than once per flagged signal. */
     private _interstitialOpen;
-    /**
-     * Dedup key for the last fingerprint submission: `${userId}|${route}`.
-     * Modern SPAs fire pushState/replaceState multiple times during hydration
-     * with the same URL — without this guard each call would generate a
-     * redundant FP row with an identical stable_hash.
-     *
-     * This is the IN-MEMORY layer (collapses bursts from this one instance). It
-     * works alongside two other client-side layers keyed on the same identity:
-     * the sessionStorage `__unshared_last_submit` mirror (survives hard reloads
-     * and SDK re-instantiation within the tab) and the page-scoped
-     * `window.__unshared.lastKey` guard shared with the auto-injected inline
-     * script (see getSharedDedup). Dedup is CLIENT-SIDE ONLY: the middleware
-     * appends a timestamp to X-Idempotency-Key (submit-fp.ts), so the backend
-     * drops only PubSub redeliveries, never two distinct submissions.
-     */
-    private _lastSubmitKey;
     constructor(config?: BrowserConfig);
     /**
      * Initialize the SDK after user login.
@@ -299,8 +284,8 @@ export declare class UnsharedBrowser {
     private _getStoredEmail;
     private _getCachedFingerprint;
     private _getCachedRawFingerprint;
-    private _cacheFingerprint;
-    private _cacheRawFingerprint;
+    private _getLifecycleCollection;
+    private _getOrCollectFingerprint;
     private _storedVerificationId;
     private _storedVerificationIdentity;
     private _shouldProcessPath;