unshared-frontend-sdk 2.3.0 → 3.0.0-rc.15

package/README.md

@@ -20,7 +20,7 @@ await client.init({
 const { data } = await client.checkUser();
 if (data?.is_user_flagged) {
   await client.triggerEmailVerification();        // emails a 6-digit code
-  const result = await client.verify(codeFromUser); // → { verified: true }
+  const result = await client.verify(codeFromUser); // -> { verified: true }
 }
 ```
 
@@ -34,6 +34,12 @@ Direct-mode reads are protected server-side: the publishable key only answers fo
 npm install unshared-frontend-sdk
 ```
 
+The bundled fallback uses exact public npm dependency `unshared-fingerprint-lib@1.5.2`
+(Node >=18.20 for installation/tooling). No vendored tarball is required. S3-first
+loading remains the default. Version 1.5.2 filters components only in the library's
+own `sendFingerprint` reporter; this SDK preserves complete raw collection results
+and applies its existing payload-size policy instead.
+
 Or via CDN (no build step) — see [CDN / UMD usage](#cdn--umd-usage) below for the complete example.
 
 ---
@@ -54,7 +60,7 @@ const fingerprint = await client.collect();
 client.submitFingerprintEvent(fingerprint, { userId: currentUser?.id });
 ```
 
-That's it. The SDK handles retries, timeouts, and errors silently.
+That's it. The SDK handles timeouts and errors without throwing. Read-only calls may retry; Trigger and Verify never retry.
 
 > **Using this SDK alongside the Node `unsharedBoundToUser` middleware (Tier 1)?** The middleware
 > also auto-injects an inline fingerprint script into your HTML. That is expected — the two
@@ -74,13 +80,19 @@ 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). |
 | `publishableKey` | `string` | — | Direct mode: publishable key (`upk_…`) issued by Unshared Labs. When set, events bypass your backend and go straight to the platform. |
 | `apiUrl` | `string` | `https://api.unshared.ai` | Direct mode: Unshared Labs platform origin. |
-| `maxRetries` | `number` | `3` | How many times to retry on failure |
+| `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. |
 
@@ -98,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.
 
@@ -117,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`.
@@ -125,6 +182,14 @@ Collect a browser fingerprint. Returns a `FingerprintWireFormat` object ready to
 const fingerprint = await client.collect();
 ```
 
+### `collectRaw()`
+
+Collect the fingerprint library's complete JSON object without reducing it to the compatibility wire type.
+
+```typescript
+const rawFingerprint = await client.collectRaw();
+```
+
 ---
 
 ### `submitFingerprintEvent(fingerprint, opts?)`
@@ -154,17 +219,50 @@ if (!result.success) {
 
 ---
 
+### `submitFingerprint(payload)`
+
+Submit any JSON object without reshaping or filtering unknown fields. Direct mode encrypts the complete object with the publishable key; proxy mode keeps the browser-to-customer hop plaintext so middleware can add trusted context before encrypting the final request to Unshared.
+
+```typescript
+await client.submitFingerprint({
+  fingerprint: await client.collectRaw(),
+  context: {
+    identity: { user_id: currentUser?.id },
+    event: { type: location.pathname + location.search },
+  },
+});
+```
+
+The payload must be a non-null JSON object; arrays and primitives fail locally with `VALIDATION_ERROR`. Direct requests larger than 1 MiB fail locally with `REQUEST_TOO_LARGE`. Direct ingestion succeeds only on a strict `202` v3 acknowledgement.
+
+Proxy submissions have a fixed **100 KiB (102,400 serialized UTF-8 bytes)** limit,
+compatible with an upstream default `express.json()` without configuration or
+middleware reordering. Structured submissions send the full snapshot if it fits;
+otherwise they empty local/session storage lists while retaining all cookies, then
+omit `context.browser_storage` if still too large. The complete raw fingerprint,
+including future fields, and core identity/device/session/SDK/event metadata are
+never trimmed. Oversized core payloads return `REQUEST_TOO_LARGE` without sending;
+the inline submitter logs that code. Low-level `submitFingerprint(payload)` never
+reduces arbitrary caller objects: it sends them exactly or rejects above 100 KiB.
+Direct mode keeps full snapshots and its existing 1 MiB logical / 1.5 MiB encrypted
+limits. Duplicate fingerprint caches and legacy queues are excluded from snapshots.
+
+---
+
 ### Direct-mode API (requires `publishableKey`)
 
 All four methods default to the identity captured by `init()` (email + stable fingerprint hash as deviceId); pass `{ email, deviceId }` to override. In proxy mode they return `error.code === 'DIRECT_MODE_REQUIRED'` — proxy-mode apps get these flows from their own backend middleware.
 
 | Method | Retries | Returns |
 |--------|---------|---------|
-| `checkUser(opts?)` | yes | `{ is_user_flagged: boolean }` |
-| `triggerEmailVerification(opts?)` | **never** (each call emails a code) | `{ next_allowed_at, retry_after_seconds }`; rate-limited calls fail with `error.retryAfter` / `error.nextAllowedAt` for countdown UIs |
-| `verify(code, opts?)` | **never** (attempts are budgeted) | `{ verified: boolean, reason?: 'invalid_code' }` |
+| `checkUser(opts?)` | bounded availability failures only | `{ is_user_flagged, decision_id, decision_code }` |
+| `triggerEmailVerification(opts?)` | **never** (each call emails a code) | `{ verification_id, next_allowed_at, retry_after_seconds }`; the SDK retains the challenge for `verify(...)` |
+| `verify(code, opts?)` | **never** (attempts are budgeted) | Exact verified/not-verified result; UUIDv4 challenges and 6-digit OTPs are validated locally |
+| `verifyEmail({ verification_id, code })` | **never** | Verification for an explicit challenge ID; reconciles flagged state when retained identity is available |
 | `emailVerificationStatus(opts?)` | yes | `{ can_send: boolean, next_allowed_at }` |
 
+V3 methods require exact success/error envelopes and endpoint-specific status/result shapes. After `verified: true`, the SDK performs one no-retry `checkUser` reconciliation; sticky flagged state is cleared only by a strict available unflagged decision, never by Verify alone or `CHECK_UNAVAILABLE`.
+
 ---
 
 ## Interstitial modal
@@ -175,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?)`
 
@@ -232,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
@@ -248,7 +377,7 @@ const result = await client.submitFingerprintEvent(fingerprint);
 // result.error.code === 'DELIVERY_FAILED'
 ```
 
-Retries happen automatically on network errors, timeouts, and server errors (5xx). Client errors (4xx) are not retried.
+Read-only direct calls retry eligible network and 5xx failures. Fingerprint ingestion, Trigger, and Verify are never retried because an ambiguous request may already have committed. Failed ingestion is not queued for replay.
 
 ---
 
@@ -257,7 +386,7 @@ Retries happen automatically on network errors, timeouts, and server errors (5xx
 The UMD bundle exposes a `window.UnsharedBrowser` namespace object. Destructure the class from it first. If the bundle was built with `UNSHARED_PUBLISHABLE_API_KEY`, the client does not pass a key:
 
 ```html
-<script src="https://unpkg.com/unshared-frontend-sdk@2.0.0-rc.4/dist/index.umd.js"></script>
+<script src="https://unpkg.com/unshared-frontend-sdk@3.0.0/dist/index.umd.js"></script>
 <script>
   const { UnsharedBrowser } = window.UnsharedBrowser;
 
@@ -276,29 +405,6 @@ For proxy mode instead, pass `baseUrl` explicitly.
 
 ---
 
-## Local retry queue encryption
-
-When a fingerprint event still fails after all retry attempts, the browser SDK stores it in `localStorage` under `__unshared_event_queue` and retries it before the next regular fingerprint submission. Queue records are encrypted before storage so the event payload is not directly readable from browser devtools.
-
-Encryption details:
-
-- Algorithm: AES-GCM.
-- IV: random 12-byte IV per queued event.
-- Stored format: `v1:<base64 iv>:<base64 ciphertext>`.
-- Queue key derivation:
-
-```text
-SHA-256("unshared-browser-queue:" + (publishableKey || baseUrl) + ":" + sessionId)
-```
-
-That SHA-256 digest is imported as the AES-GCM key through Web Crypto. The SDK does **not** use `API_KEY_ENCRYPTION_SECRET`; that kind of secret must stay server-side and must not be shipped in browser code.
-
-This is intentionally best-effort local confidentiality, not a strong security boundary. In direct mode, the publishable key is public, and the session ID is browser-local state. That means the queue encryption protects against casual plaintext inspection of `localStorage`, but it does not protect against a user who can run JavaScript in their own browser context or inspect the loaded SDK. The browser SDK therefore treats queue encryption as obfuscation plus integrity protection for local retry data, not as secret storage.
-
-Using the publishable key in this derivation is acceptable for this limited purpose because no server secret is available in the browser. It should not be described as making local data unrecoverable from the end user. If stronger browser-local protection is required, the SDK would need a different design, such as server-held queued events, short-lived server-issued wrapping keys, or platform storage that never exposes plaintext to arbitrary page JavaScript.
-
----
-
 ## Real-browser acceptance coverage
 
 For Boston Globe style script-tag integration, split client-side browser tests into host-site flows and SDK-owned delivery behavior.
@@ -313,7 +419,4 @@ For Boston Globe style script-tag integration, split client-side browser tests i
 | Password reset completion failures | Wrong current password; mismatched new-password entries; password-rule failures; missing required values. | Host-site auth behavior. Test in the client's browser suite. |
 | Page navigation | Full page loads with script tag; link clicks; forward/back; refresh with same script tag injected. | SDK supports script-tag load, `init`, MPA `DOMContentLoaded`, and SPA route-change submission. Real-browser tests should assert the UMD bundle loads and the client page still renders. |
 | Event firing | Event fires where applicable after user identity is present. | Implemented by `init`, `onRouteChange`, MPA listener, and direct/proxy submit endpoints. Covered by unit tests; should also be verified in real browser against mocked or test backend responses. |
-| Retry | Failed event sends retry until `maxRetries` is exhausted. | Implemented and unit-tested. |
-| Encrypted local queue | After retry exhaustion, failed events are stored in local cache and are not directly readable as plaintext. | Implemented with AES-GCM encrypted `localStorage` queue and unit-tested. |
-| Local queue storage failure | Storage unavailable, quota exceeded, or crypto unavailable. | Implemented as never-throw best effort; event returns delivery failure and storage failure is swallowed. Unit-tested for storage failure. |
-| Queue flush | Stored events transmit on the next regular event opportunity. | Implemented by flushing the encrypted queue before the next fingerprint submission. Unit-tested. |
+| Retry | Read-only checks may retry; ingestion, Trigger, and Verify make one attempt and are never queued. | Implemented and unit-tested. |

package/dist/browser.d.ts

@@ -1,4 +1,4 @@
-import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
+import type { CheckUserResult, FingerprintWireFormat, IngestResult, JSONObject, VerifyEmailRequest, VerifyEmailResult } from './shared-types';
 export interface BrowserConfig {
     /**
      * Base URL of the customer's own backend.
@@ -78,11 +78,15 @@ export interface InitOptions {
 export interface SubmitFingerprintOptions {
     userId: string;
     eventType?: string;
+    permanentDeviceId?: string;
 }
 export interface SubmitFingerprintResult {
     hash: string;
     stable_hash: string;
     collected_at: string;
+    version: string;
+    event_id?: string;
+    endpoint_version?: 'v3';
 }
 export interface BrowserApiResult<T = unknown> {
     success: boolean;
@@ -101,18 +105,22 @@ export interface BrowserApiResult<T = unknown> {
 export interface DirectIdentityOptions {
     email?: string;
     deviceId?: string;
+    permanentDeviceId?: string;
+    stableHash?: string;
+    fullHash?: string;
 }
-export interface CheckUserData {
-    is_user_flagged: boolean;
+export interface CheckUserData extends CheckUserResult {
 }
 export interface TriggerVerificationData {
     message?: string;
+    verification_id?: string;
     next_allowed_at?: string;
     retry_after_seconds?: number;
 }
 export interface VerifyData {
     verified: boolean;
     reason?: string;
+    verification_scope?: 'email';
 }
 export interface VerificationStatusData {
     can_send: boolean;
@@ -121,6 +129,11 @@ export interface VerificationStatusData {
 export interface FlaggedInterceptorOptions {
     onFlagged: () => void;
 }
+interface CollectedFingerprint {
+    raw: JSONObject;
+    wire: FingerprintWireFormat;
+    source: 'remote' | 'bundled';
+}
 /**
  * Browser SDK for Unshared Labs.
  *
@@ -153,12 +166,13 @@ export declare class UnsharedBrowser {
     private readonly _resolveDeviceId?;
     private _sessionId;
     private _deviceId;
+    private _permanentDeviceId;
     private _userId;
     private _emailAddress;
     /** True after init() with isPaidSubscriber:false — blocks every submission path. */
     private _doNotCollect;
     private _mpaHandler;
-    private _flushingQueue;
+    private readonly _lifecycleState;
     /** Interstitial auto-show config + live state. */
     private readonly _enableInterstitial;
     private readonly _interstitialFlowType;
@@ -166,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.
@@ -211,17 +209,32 @@ export declare class UnsharedBrowser {
      */
     collect(options?: {
         exclude?: string[];
+        [key: string]: unknown;
     }): Promise<FingerprintWireFormat>;
+    /** Returns the fingerprint agent's JSON object without selecting or renaming fields. */
+    collectRaw(options?: {
+        exclude?: string[];
+        [key: string]: unknown;
+    }): Promise<JSONObject>;
+    /** Collect once, keeping the agent's raw object separate from normalized SDK metadata. */
+    collectWithMetadata(options?: {
+        exclude?: string[];
+        [key: string]: unknown;
+    }): Promise<CollectedFingerprint>;
+    private _collectFingerprint;
     /**
      * Submit a fingerprint event directly.
      * @deprecated Prefer sdk.init() and sdk.onRouteChange().
      */
     submitFingerprintEvent(fingerprint: FingerprintWireFormat, opts: SubmitFingerprintOptions): Promise<BrowserApiResult<SubmitFingerprintResult>>;
+    /** Submit any JSON object to the v3 fingerprint endpoint without changing it. */
+    submitFingerprint(payload: JSONObject): Promise<BrowserApiResult<IngestResult>>;
     /**
      * Check whether the current user is flagged for account sharing.
      * Direct mode only — proxy-mode apps get verdicts from their own backend.
      */
     checkUser(opts?: DirectIdentityOptions): Promise<BrowserApiResult<CheckUserData>>;
+    private _checkUser;
     /**
      * Send a 6-digit verification code to the user's email.
      * Never retried — each attempt sends a real email. Rate-limited responses
@@ -233,6 +246,8 @@ export declare class UnsharedBrowser {
      * budgeted server-side to block brute force.
      */
     verify(code: string, opts?: DirectIdentityOptions): Promise<BrowserApiResult<VerifyData>>;
+    verifyEmail(request: VerifyEmailRequest): Promise<BrowserApiResult<VerifyEmailResult>>;
+    private _verifyEmail;
     /** Report the email-send cooldown state without sending anything. */
     emailVerificationStatus(opts?: DirectIdentityOptions): Promise<BrowserApiResult<VerificationStatusData>>;
     /**
@@ -268,7 +283,11 @@ export declare class UnsharedBrowser {
     private _directApi;
     private _getStoredEmail;
     private _getCachedFingerprint;
-    private _cacheFingerprint;
+    private _getCachedRawFingerprint;
+    private _getLifecycleCollection;
+    private _getOrCollectFingerprint;
+    private _storedVerificationId;
+    private _storedVerificationIdentity;
     private _shouldProcessPath;
     private _submitEvent;
     /**
@@ -278,39 +297,10 @@ export declare class UnsharedBrowser {
     private _submitUrl;
     private _attachMpaListener;
     private _sendWithRetry;
-    private _piiKeyPromise;
-    /** AES-GCM key derived as SHA-256(publishable key) — the same derivation the
-     *  platform applies to SDK ciphertext, so it can decrypt at ingress. */
-    private _piiKey;
-    /**
-     * Encrypt a PII field (user_id, email_address) for direct-mode requests:
-     * AES-256-GCM keyed by SHA-256(publishable key), emitted as
-     * `base64(iv):base64(authTag):base64(ciphertext)` — byte-compatible with the
-     * Node SDK's encryptData, so the platform's existing ciphertext detection and
-     * decryption handle it unchanged. Returns the plaintext when WebCrypto is
-     * unavailable or fails: the ingress accepts both and always (re-)encrypts PII
-     * with the company secret key before anything is stored.
-     */
-    private _encryptPII;
-    private _queueKey;
-    private _encryptQueuedDelivery;
-    private _decryptQueuedDelivery;
-    private _readQueueRecords;
-    private _writeQueueRecords;
-    private _queueFailedDelivery;
-    /**
-     * Recover a batch orphaned by a crashed/killed tab mid-flush. A flush claims
-     * its batch by leasing it here BEFORE clearing the main queue (see
-     * _flushQueuedEvents); if the process dies before the `finally` that removes
-     * the lease runs, the claimed records would otherwise be lost forever. A
-     * STALE lease (older than INFLIGHT_LEASE_MS) is presumed orphaned and merged
-     * back into the main queue. A FRESH lease means another tab is genuinely
-     * mid-flight — leave it untouched, or this would recreate the double-send
-     * that the claim-then-clear scheme exists to prevent.
-     */
-    private _recoverStaleInflightLease;
-    private _flushQueuedEvents;
-    private _buildBody;
+    private _buildIdentifiers;
+    private _buildEventPayload;
+    private _ensurePermanentDeviceId;
+    private _isSameOriginProxy;
 }
 /**
  * Creates an Axios response error interceptor that calls onFlagged
@@ -338,3 +328,4 @@ export declare function createAxiosInterceptor(opts: FlaggedInterceptorOptions):
  * ```
  */
 export declare function createFetchInterceptor(originalFetch: typeof fetch, opts: FlaggedInterceptorOptions): typeof fetch;
+export {};

package/dist/fingerprint-agent.d.ts

@@ -1,5 +1,6 @@
-import type { FingerprintConfig, FingerprintResult } from 'unshared-fingerprint-lib';
-export type GetFingerprint = (config?: FingerprintConfig) => Promise<FingerprintResult>;
+import type { FingerprintConfig } from 'unshared-fingerprint-lib';
+import type { JSONObject } from './shared-types';
+export type GetFingerprint = (config?: FingerprintConfig) => Promise<JSONObject>;
 export interface ResolvedAgent {
     getFingerprint: GetFingerprint;
     source: 'remote' | 'bundled';