unshared-frontend-sdk 2.0.1 → 2.1.0-rc.3

package/README.md

@@ -1,6 +1,30 @@
 # unshared-frontend-sdk
 
-Browser SDK for [Unshared Labs](https://unsharedlabs.com) — collects a device fingerprint and sends it through your own backend. Your API key never touches the browser.
+Browser SDK for [Unshared Labs](https://unshared.ai) — collects a device fingerprint and delivers it in one of two modes:
+
+- **Proxy mode**: events go through your own backend (`baseUrl`). Your secret API key never touches the browser.
+- **Direct mode**: events go straight to the Unshared Labs platform, authenticated by a **publishable key** (`upk_…`). No customer backend required — the tag-manager-style integration (à la Adobe Launch / BlueConic). The publishable key is public by design and only grants event submission.
+
+> Client-specific script-tag builds can package `UNSHARED_PUBLISHABLE_API_KEY` into the UMD bundle. When the key is packaged, `new UnsharedBrowser({})` runs in direct mode. Use `baseUrl: ""` for same-origin proxy mode.
+
+```typescript
+// Direct mode — no backend integration needed
+const client = new UnsharedBrowser({ publishableKey: 'upk_your_key' });
+await client.init({
+  userId: currentUser.id,
+  emailAddress: currentUser.email,
+  isPaidSubscriber: currentUser.hasSubscription, // false → nothing is ever collected or sent
+});
+
+// Direct mode also exposes the read/verification API:
+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 }
+}
+```
+
+Direct-mode reads are protected server-side: the publishable key only answers for the identity+device the browser presents, origins are allowlisted, and every endpoint is rate-limited per IP (plus per-email cooldowns and code-attempt budgets).
 
 ---
 
@@ -17,13 +41,13 @@ Or via CDN (no build step) — see [CDN / UMD usage](#cdn--umd-usage) below for
 ## Quick Start
 
 ```typescript
-import { UnsharedLabsBrowser } from 'unshared-frontend-sdk';
+import { UnsharedBrowser } from 'unshared-frontend-sdk';
 
-// Same-origin (frontend served by the same backend): omit baseUrl
-const client = new UnsharedLabsBrowser({});
+// Same-origin proxy mode (frontend served by the same backend)
+const client = new UnsharedBrowser({ baseUrl: '' });
 
 // Cross-origin (separate domains): set baseUrl via env var
-// const client = new UnsharedLabsBrowser({ baseUrl: process.env.BACKEND_URL });
+// const client = new UnsharedBrowser({ baseUrl: process.env.BACKEND_URL });
 
 // On page load — fire and forget
 const fingerprint = await client.collect();
@@ -32,23 +56,62 @@ client.submitFingerprintEvent(fingerprint, { userId: currentUser?.id });
 
 That's it. The SDK handles retries, timeouts, and errors silently.
 
+> **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
+> submitters share a client-side dedup guard (`window.__unshared`) and emit **one** event per
+> `(user, route)`. You do **not** need to turn injection off. See
+> [_Fingerprint Collection: what loads what, who submits when_](../INTEGRATION_GUIDE.md#fingerprint-collection-what-loads-what-who-submits-when).
+
 ---
 
 ## Configuration
 
 ```typescript
-new UnsharedLabsBrowser({
-  baseUrl:    process.env.BACKEND_URL, // optional — omit for same-origin
-  maxRetries: 3,                       // optional, default: 3
-  timeout:    30_000,                  // optional, default: 30s per attempt
+new UnsharedBrowser({
+  baseUrl:    '',      // same-origin proxy mode
+  maxRetries: 3,       // optional, default: 3
+  timeout:    30_000,  // optional, default: 30s per attempt
 });
 ```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `baseUrl` | `string` | `""` (same-origin) | Base URL of your backend. Omit if your frontend and backend share the same domain. |
+| `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 |
 | `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. |
+
+### Packaged publishable key
+
+For a client-specific script-tag build, package the publishable key into the UMD bundle so the client does not pass it in page code. When `baseUrl` and `publishableKey` are omitted, the SDK resolves:
+
+1. Explicit `publishableKey`.
+2. Build-time `UNSHARED_PUBLISHABLE_API_KEY` baked in by `scripts/build.js` (client-specific builds only, e.g. the S3 flow).
+3. Otherwise **no key** — the SDK stays in same-origin proxy mode. There is no hardcoded fallback; builds made without the env var (including every npm release) never carry a usable key.
+
+Build a client-specific distribution with:
+
+```bash
+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.
+
+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.
+
+The browser build also runs a markdown confidentiality guard before producing dist files. It removes obvious generated metadata sections and fails if markdown contains confidential metadata markers. Mentions of known key names print warnings by default because those names are sometimes documented intentionally.
+
+Local overrides:
+
+```bash
+npm --prefix sdks/javascript/browser run build -- --allow-key-mentions
+npm --prefix sdks/javascript/browser run build -- --allow-confidential-docs
+```
+
+Use the confidential-docs override only for local investigation; do not commit markdown containing generated system metadata or real key values.
 
 ---
 
@@ -91,6 +154,70 @@ if (!result.success) {
 
 ---
 
+### 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' }` |
+| `emailVerificationStatus(opts?)` | yes | `{ can_send: boolean, next_allowed_at }` |
+
+---
+
+## Interstitial modal
+
+Instead of wiring your own remediation UI, the SDK can render a **server-driven
+interstitial modal** (e.g. an email-OTP verification flow) when a user is flagged. The
+flow is authored in the Unshared dashboard and stored per company; the SDK fetches the
+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`).
+
+**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.
+
+### `showInterstitial(opts?)`
+
+Fetch and render the published flow on demand. No-op if a modal is already open.
+
+```typescript
+const sdk = new UnsharedBrowser({ publishableKey: 'upk_…' });
+await sdk.init({ userId, emailAddress });
+
+// e.g. from your own flagged handler:
+await sdk.showInterstitial();                       // default flow_type, web variant
+await sdk.showInterstitial({ flowType: 'email_verification', container: myEl });
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `flowType` | `string` | constructor's `interstitialFlowType` or `email_verification` | Which published flow to fetch |
+| `container` | `HTMLElement` | `document.body` | Where to mount the modal |
+
+Returns `{ success, data: { shown } }`; rendering errors are swallowed (never-throw).
+`shown` is `false` when a modal was already open.
+
+### Auto-show
+
+Set `enableInterstitial: true` to render the modal automatically the first time the
+`unshared:flagged` event fires (dispatched by the proxy-mode injected script, or by your
+own code). If you detect flagging via [`createFetchInterceptor`](#error-handling) /
+`createAxiosInterceptor` instead, call `sdk.showInterstitial()` from your `onFlagged`
+handler.
+
+```typescript
+const sdk = new UnsharedBrowser({ publishableKey: 'upk_…', enableInterstitial: true });
+await sdk.init({ userId, emailAddress });
+// On the next `unshared:flagged` event, the modal renders itself.
+```
+
+`destroy()` removes any open modal and detaches the listener.
+
+---
+
 ## Backend requirement
 
 The SDK sends fingerprints to `{baseUrl}/unshared/submit-fingerprint-event`. Your backend must handle this route. If you're using `unshared-clientjs-sdk`, the `createUnsharedMiddleware` sets this up automatically:
@@ -127,18 +254,66 @@ Retries happen automatically on network errors, timeouts, and server errors (5xx
 
 ## CDN / UMD usage
 
-The UMD bundle exposes a `window.UnsharedLabsBrowser` namespace object. Destructure the class from it first:
+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>
-  const { UnsharedLabsBrowser } = window.UnsharedLabsBrowser;
+  const { UnsharedBrowser } = window.UnsharedBrowser;
 
-  // Omit baseUrl for same-origin. Set it for cross-origin: { baseUrl: 'https://api.example.com' }
-  const client = new UnsharedLabsBrowser({});
+  // Direct mode using the publishable key packaged into the UMD build.
+  const client = new UnsharedBrowser({});
 
-  client.collect().then(fp => {
-    client.submitFingerprintEvent(fp);
+  client.init({
+    userId: currentUser.id,
+    emailAddress: currentUser.email,
+    isPaidSubscriber: currentUser.hasSubscription,
   });
 </script>
 ```
+
+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.
+
+| Area | Cases | Implementation status |
+|------|-------|-----------------------|
+| Signup | Successful signup initiation; duplicate email; missing or invalid password rules. | Host-site auth behavior. Test in the client's browser suite; no SDK code required beyond confirming the script tag remains loaded and does not block the flow. |
+| Identity verification | Correct 6-digit code; wrong code; timeout/expired code. | Host-site or Unshared direct verification UI behavior, depending on who owns the screen. SDK exposes `triggerEmailVerification`, `verify`, and `emailVerificationStatus`; page-level form states must be tested in the client's browser suite. |
+| Signup completion | Success page/message; failure page/message with reason. | Host-site auth behavior. Test in the client's browser suite. |
+| Login | Valid login; wrong email; wrong password; unregistered email; missing password; missing email. | Host-site auth behavior. Test in the client's browser suite while verifying the SDK initializes only after a real identified user is available. |
+| Password reset | Successful reset initiation. | Host-site auth behavior. Test in the client's browser suite. |
+| 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. |

package/dist/__tests__/setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser.d.ts

@@ -2,13 +2,26 @@ import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
 export interface BrowserConfig {
     /**
      * Base URL of the customer's own backend.
-     * Omit when the backend serves the frontend from the same origin.
+     * Set to "" when the backend serves the frontend from the same origin.
+     * Omit only for direct mode.
      */
     baseUrl?: string;
     /** Max number of delivery retries per request. @default 3 */
     maxRetries?: number;
     /** Per-request fetch timeout in milliseconds. @default 30_000 */
     timeout?: number;
+    /**
+     * Publishable key (`upk_…`) issued by Unshared Labs. When set, the SDK runs in
+     * **direct mode**: events are sent straight to the Unshared Labs platform
+     * (`apiUrl`) instead of the customer's own backend (`baseUrl`). The key is
+     * public by design — it only grants event submission, never reads.
+     */
+    publishableKey?: string;
+    /**
+     * Unshared Labs platform origin used in direct mode.
+     * @default "https://api.unshared.ai"
+     */
+    apiUrl?: string;
     /** When set, events are only submitted for paths matching one of these prefixes. */
     includePathPrefix?: string[];
     /** Paths to skip entirely — prefix match against location.pathname. */
@@ -27,10 +40,40 @@ export interface BrowserConfig {
      * Falls back to existing localStorage/fingerprint behavior when undefined is returned.
      */
     deviceId?: () => string | undefined;
+    /**
+     * When `true`, the SDK auto-renders an interstitial modal (direct mode only)
+     * the first time the user is flagged — detected via the `unshared:flagged`
+     * window event. Default `false` (fully backward compatible). Apps that detect
+     * flagging themselves (e.g. via {@link createFetchInterceptor}) can instead
+     * call {@link UnsharedBrowser.showInterstitial} from their own handler.
+     */
+    enableInterstitial?: boolean;
+    /**
+     * Flow type to request for the auto-shown interstitial.
+     * @default "email_verification"
+     */
+    interstitialFlowType?: string;
+}
+/** Options for {@link UnsharedBrowser.showInterstitial}. */
+export interface ShowInterstitialOptions {
+    /** Flow type to fetch. @default the constructor's interstitialFlowType or "email_verification". */
+    flowType?: string;
+    /** Where to mount the modal. @default document.body. */
+    container?: HTMLElement;
+    /** Called when the flow reaches its terminal (success) screen. */
+    onComplete?: () => void;
+    /** Called when the modal is dismissed (programmatically / on success-dismiss). */
+    onDismiss?: () => void;
 }
 export interface InitOptions {
     userId: string;
     emailAddress: string;
+    /**
+     * Whether this user is a paying subscriber. When `false`, the SDK collects
+     * and submits **nothing** for this user — non-subscriber data must not be
+     * received. Omit (or pass `true`) for users whose data should flow.
+     */
+    isPaidSubscriber?: boolean;
 }
 export interface SubmitFingerprintOptions {
     userId: string;
@@ -47,16 +90,42 @@ export interface BrowserApiResult<T = unknown> {
     error?: {
         code: string;
         message: string;
+        /** Seconds until the call may be retried (rate-limited responses). */
+        retryAfter?: number;
+        /** RFC3339 timestamp of when the call may be retried (rate-limited responses). */
+        nextAllowedAt?: string;
     };
 }
+/** Identity override for the direct-mode API methods. Defaults to the identity
+ *  captured by init() (email) and the stable fingerprint hash (deviceId). */
+export interface DirectIdentityOptions {
+    email?: string;
+    deviceId?: string;
+}
+export interface CheckUserData {
+    is_user_flagged: boolean;
+}
+export interface TriggerVerificationData {
+    message?: string;
+    next_allowed_at?: string;
+    retry_after_seconds?: number;
+}
+export interface VerifyData {
+    verified: boolean;
+    reason?: string;
+}
+export interface VerificationStatusData {
+    can_send: boolean;
+    next_allowed_at?: string | null;
+}
 export interface FlaggedInterceptorOptions {
     onFlagged: () => void;
 }
 /**
  * Browser SDK for Unshared Labs.
  *
- * Routes fingerprint events through the customer's own backend — no API key
- * is ever present in the browser.
+ * Routes fingerprint events through the customer's own backend in proxy mode,
+ * or through the Unshared Labs platform in publishable-key direct mode.
  *
  * Never-throw contract: all public methods catch all errors and never reject.
  *
@@ -74,6 +143,8 @@ export interface FlaggedInterceptorOptions {
  */
 export declare class UnsharedBrowser {
     private readonly _baseUrl;
+    private readonly _publishableKey;
+    private readonly _apiUrl;
     private readonly _maxRetries;
     private readonly _timeout;
     private readonly _includePathPrefix;
@@ -84,18 +155,31 @@ export declare class UnsharedBrowser {
     private _deviceId;
     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;
+    private _interstitialListener;
+    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. Mirrors the same
-     * dedup behavior in the auto-injected inline script.
+     * redundant FP row with an identical stable_hash.
      *
-     * Persisted to sessionStorage so that hard reloads, framework double-boots,
-     * and SDK re-instantiation within the same tab all still dedupe. The backend
-     * `ON CONFLICT (idempotency_key)` check handles the cross-tab and cross-reload
-     * cases that sessionStorage can't (sessionStorage is tab-scoped).
+     * 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);
@@ -133,13 +217,88 @@ export declare class UnsharedBrowser {
      * @deprecated Prefer sdk.init() and sdk.onRouteChange().
      */
     submitFingerprintEvent(fingerprint: FingerprintWireFormat, opts: SubmitFingerprintOptions): Promise<BrowserApiResult<SubmitFingerprintResult>>;
+    /**
+     * 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>>;
+    /**
+     * Send a 6-digit verification code to the user's email.
+     * Never retried — each attempt sends a real email. Rate-limited responses
+     * carry `error.retryAfter` / `error.nextAllowedAt` for countdown UIs.
+     */
+    triggerEmailVerification(opts?: DirectIdentityOptions): Promise<BrowserApiResult<TriggerVerificationData>>;
+    /**
+     * Verify a code from triggerEmailVerification. Never retried — attempts are
+     * budgeted server-side to block brute force.
+     */
+    verify(code: string, opts?: DirectIdentityOptions): Promise<BrowserApiResult<VerifyData>>;
+    /** Report the email-send cooldown state without sending anything. */
+    emailVerificationStatus(opts?: DirectIdentityOptions): Promise<BrowserApiResult<VerificationStatusData>>;
+    /**
+     * Fetch the published interstitial flow and render it as a Shadow-DOM modal.
+     * Works in direct mode (publishableKey) AND proxy mode (baseUrl). In proxy mode
+     * the flow is fetched through the customer backend and the modal's actions run
+     * through the middleware verify routes — identity is resolved server-side, so the
+     * browser sends only the OTP. Returns a BrowserApiResult describing the fetch
+     * outcome; rendering errors are swallowed (never-throw). No-op if already open.
+     */
+    showInterstitial(opts?: ShowInterstitialOptions): Promise<BrowserApiResult<{
+        shown: boolean;
+    }>>;
+    /** Direct-mode flow fetch (publishable key → platform API). */
+    private _fetchDirectFlow;
+    /** Proxy-mode flow fetch (customer backend → secret key). */
+    private _fetchProxyFlow;
+    /**
+     * Proxy-mode actions adapter: routes the flow's operations to the middleware verify
+     * routes. Identity is resolved server-side, so only the OTP is sent. Throws on
+     * failure so the renderer shows an inline error.
+     */
+    private _buildProxyActionsAdapter;
+    /**
+     * Maps the flow's logical action operations to this SDK's direct-mode methods
+     * (see shared/specs/interstitial-actions.md). Resolves on success; throws on
+     * failure so the renderer can show an inline error.
+     */
+    private _buildActionsAdapter;
+    /** Attach the one-shot `unshared:flagged` listener that auto-shows the modal. */
+    private _attachInterstitialListener;
+    private _resolveDirectIdentity;
+    private _directApi;
     private _getStoredEmail;
     private _getCachedFingerprint;
     private _cacheFingerprint;
     private _shouldProcessPath;
     private _submitEvent;
+    /**
+     * Direct mode (publishableKey set) targets the Unshared Labs platform;
+     * proxy mode targets the customer's own backend middleware.
+     */
+    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;
+    private _flushQueuedEvents;
     private _buildBody;
 }
 /**