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

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
@@ -79,7 +85,7 @@ new UnsharedBrowser({
 | `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 |
 | `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. |
@@ -125,6 +131,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 +168,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
@@ -248,7 +295,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 +304,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 +323,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 +337,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,12 @@ 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;
     /** Interstitial auto-show config + live state. */
     private readonly _enableInterstitial;
     private readonly _interstitialFlowType;
@@ -211,17 +224,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 +261,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 +298,11 @@ export declare class UnsharedBrowser {
     private _directApi;
     private _getStoredEmail;
     private _getCachedFingerprint;
+    private _getCachedRawFingerprint;
     private _cacheFingerprint;
+    private _cacheRawFingerprint;
+    private _storedVerificationId;
+    private _storedVerificationIdentity;
     private _shouldProcessPath;
     private _submitEvent;
     /**
@@ -278,39 +312,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 +343,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';