unshared-clientjs-sdk 2.0.0-rc.9 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # unshared-clientjs-sdk
 
-Server-side Node.js SDK for [Unshared Labs](https://unsharedlabs.com) — detect account sharing, analyze user events for fraud, and run email verification flows.
+Server-side Node.js SDK for [Unshared](https://unshared.ai) — detect account sharing, analyze user events for fraud, and run email verification flows.
 
 ---
 
@@ -17,9 +17,9 @@ npm install unshared-clientjs-sdk
 ## Quick Start
 
 ```typescript
-import { UnsharedLabsClient } from 'unshared-clientjs-sdk';
+import { UnsharedClient } from 'unshared-clientjs-sdk';
 
-const client = new UnsharedLabsClient({
+const client = new UnsharedClient({
   apiKey: process.env.UNSHARED_API_KEY, // usk_…
 });
 ```
@@ -112,44 +112,82 @@ await client.submitFingerprintEvent(fingerprint, {
 
 ---
 
-## Express Middleware
+## Protection Middleware (Recommended)
 
-The middleware adds a proxy route (`POST /unshared/submit-fingerprint-event`) that the browser SDK calls. It handles forwarding fingerprints to Unshared Labs and attaching your API key.
+`unsharedBoundToUser` is the full-featured middleware: auto-injects the fingerprint script, enforces verdicts, handles email verification flows, and dispatches events.
 
 ```typescript
-import { createUnsharedMiddleware } from 'unshared-clientjs-sdk/middleware';
+import { UnsharedClient, unsharedBoundToUser, flaggedResponse } from 'unshared-clientjs-sdk';
 
-// express.json() must come before this middleware
+app.set('trust proxy', 1);
 app.use(express.json());
 
-app.use(createUnsharedMiddleware(client, {
-  userIdExtractor: (req) => req.user?.id, // attach logged-in user
+const client = new UnsharedClient({ apiKey: process.env.UNSHARED_API_KEY! });
+
+app.use(unsharedBoundToUser(client, {
+  userId: (req) => req.cookies?.userId,
+  emailAddress: (req) => req.cookies?.email,
+  includePathPrefix: ['/api/'],
+  onFlagged: ({ emailAddress, res }) => {
+    res.status(403).json(flaggedResponse(emailAddress));
+  },
 }));
 ```
 
-**Prerequisites:**
-- Mount `express.json()` before the middleware
-- `user_id` is automatically removed from `req.body` after being read — downstream logging won't capture it
+**Smoke test:** `curl http://localhost:3000/__unshared/status` — returns `{ "status": "anonymous" | "ok" | "flagged" }`.
 
-**Options:**
+**Key options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `userId` | `(req) => string \| undefined` | — | **Required.** Resolve the current user's ID |
+| `emailAddress` | `(req) => string \| undefined` | — | Resolve the current user's email |
+| `routePrefix` | `string` | `"/__unshared"` | Route mount prefix |
+| `includePathPrefix` | `string[]` | — | Only these path prefixes trigger verdicts and events |
+| `onFlagged` | `(ctx) => void` | — | Called when a flagged user makes a request |
+| `disableBotFilter` | `boolean` | `false` | Skip bot UA filter (enable for E2E testing) |
+| `checkUserTimeoutMs` | `number` | `500` | Timeout (ms) for checkUser API calls; fails open on timeout |
+| `skipPaths` | `string[]` | — | Paths to skip entirely (static assets, health checks) |
+| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight |
+| `onError` | `(error, ctx) => void` | — | Called on background SDK errors for observability |
+
+See [quickstart](./docs/quickstart.md) and [flag semantics](./docs/flag-semantics.md) for full setup and testing details.
+
+---
+
+## Simple Fingerprint Middleware
+
+`createUnsharedMiddleware` is a lightweight alternative that only proxies fingerprint events — no verdicts, no script injection, no verification flows. Use `unsharedBoundToUser` unless you have a specific reason not to.
+
+```typescript
+import { createUnsharedMiddleware } from 'unshared-clientjs-sdk';
+
+app.use(express.json());
+app.use(createUnsharedMiddleware(client, {
+  userIdExtractor: (req) => req.user?.id,
+}));
+```
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `userIdExtractor` | `(req) => string \| undefined` | — | Pull user ID from your auth session |
 | `eventTypeExtractor` | `(req) => string \| undefined` | — | Override event type |
 | `sessionIdExtractor` | `(req) => string \| undefined` | — | Override session ID |
+| `ipAddressExtractor` | `(req) => string \| undefined` | — | Override IP address |
 | `defaultEventType` | `string` | `"browser_event"` | Fallback event type |
 | `routePrefix` | `string` | `"/unshared"` | Route mount prefix |
-| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight automatically |
+| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins |
+
+> **Note:** This middleware uses a different default prefix (`/unshared`) and route (`submit-fingerprint-event`) than `unsharedBoundToUser` (`/__unshared`, `submit-fp`).
 
 ---
 
 ## Configuration
 
 ```typescript
-new UnsharedLabsClient({
+new UnsharedClient({
   apiKey:     'usk_…',                               // required
-  baseUrl:    'https://api-ingress.unsharedlabs.com', // optional
+  baseUrl:    'https://api.unshared.ai', // optional
   timeout:    10_000,                                 // optional, ms
   maxRetries: 3,                                      // optional
 });

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
-export interface UnsharedLabsClientConfig {
+export interface UnsharedClientConfig {
     /**
      * Secret API key. Must be kept server-side.
      * Format: usk_…
@@ -7,7 +7,7 @@ export interface UnsharedLabsClientConfig {
     apiKey: string;
     /**
      * Base URL of the Unshared Labs V2 ingress.
-     * @default "https://api-ingress.unsharedlabs.com"
+     * @default "https://api.unshared.ai"
      */
     baseUrl?: string;
     /**
@@ -20,8 +20,28 @@ export interface UnsharedLabsClientConfig {
      * @default 3
      */
     maxRetries?: number;
+    /**
+     * Custom fetch implementation. Use this to configure connection pooling,
+     * custom HTTP agents, or proxies. Defaults to the global `fetch`.
+     *
+     * @example
+     * ```typescript
+     * import { Agent, fetch as undiciFetch } from 'undici';
+     *
+     * const agent = new Agent({
+     *   keepAliveTimeout: 30_000,
+     *   connections: 50,
+     * });
+     *
+     * const client = new UnsharedClient({
+     *   apiKey: 'usk_...',
+     *   fetch: (url, init) => undiciFetch(url, { ...init, dispatcher: agent }),
+     * });
+     * ```
+     */
+    fetch?: typeof globalThis.fetch;
 }
-export interface UnsharedLabsError {
+export interface UnsharedError {
     code: string;
     message: string;
     details?: Record<string, unknown>;
@@ -35,14 +55,27 @@ export interface UnsharedLabsError {
 export interface ApiResult<T = unknown> {
     success: boolean;
     data?: T;
-    error?: UnsharedLabsError;
+    error?: UnsharedError;
     status: number;
 }
 export interface SubmitFingerprintOptions {
     userId?: string;
+    /** SDK encrypts before sending. */
+    emailAddress?: string;
     sessionHash?: string;
     eventType?: string;
+    /** SDK encrypts before sending. */
     ipAddress?: string;
+    /** SDK encrypts before sending. */
+    userAgent?: string;
+    /**
+     * Client-supplied idempotency key. Forwarded verbatim as X-Idempotency-Key
+     * so the backend's ON CONFLICT (idempotency_key) catches duplicates across
+     * reloads, tabs, and concurrent SDK instances. When omitted, a fresh UUID
+     * is generated (best-effort dedup only within a single submitFingerprintEvent
+     * call's retries).
+     */
+    idempotencyKey?: string;
 }
 export interface SubmitFingerprintResult {
     hash: string;
@@ -53,12 +86,14 @@ export interface SubmitFingerprintResult {
 }
 export interface ProcessUserEventParams {
     eventType: string;
+    /** SDK encrypts before sending. */
     userId: string;
-    /** Plaintext — SDK does not encrypt this field. */
+    /** SDK encrypts before sending. */
     ipAddress: string;
     /** SDK encrypts before sending. */
     deviceId: string;
     sessionHash: string;
+    /** SDK encrypts before sending. */
     userAgent: string;
     /** SDK encrypts before sending. */
     emailAddress: string;
@@ -95,29 +130,14 @@ export interface VerifyResult {
     verified: boolean;
     reason?: 'not_found' | 'code_mismatch' | 'code_expired';
 }
-export interface VerificationFlowStep {
-    type: 'message' | 'email_input' | 'otp_input' | 'support_link';
-    title: string;
-    body: string;
-    buttonText?: string;
-    url?: string;
-}
-export interface VerificationFlowConfigResult {
-    steps: VerificationFlowStep[];
-    branding?: {
-        companyName?: string;
-        logoUrl?: string;
-        primaryColor?: string;
-        supportEmail?: string;
-    };
-}
-export declare class UnsharedLabsClient {
+export declare class UnsharedClient {
     private readonly _apiKey;
     private readonly _baseUrl;
     private readonly _timeout;
     private readonly _maxRetries;
     private readonly _encryptionKey;
-    constructor(config: UnsharedLabsClientConfig);
+    private readonly _customFetch;
+    constructor(config: UnsharedClientConfig);
     private _encrypt;
     /**
      * Core HTTP method with retry logic.
@@ -181,16 +201,4 @@ export declare class UnsharedLabsClient {
     verify(emailAddress: string, deviceId: string, code: string, opts?: {
         fingerprintId?: string;
     }): Promise<ApiResult<VerifyResult>>;
-    /**
-     * Fetch the verification flow configuration for this company.
-     * Maps to: GET /v2/verification-flow-config
-     *
-     * Returns the flow steps and branding configured by the Unshared Labs
-     * team for this company. The middleware uses this to render the
-     * verification overlay.
-     *
-     * Returns `null` on any failure (network error, 4xx, 5xx) so the
-     * middleware can fall back to the default flow.
-     */
-    getVerificationFlowConfig(): Promise<VerificationFlowConfigResult | null>;
 }

package/dist/client.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.UnsharedLabsClient=void 0;const crypto_1=require("crypto"),util_1=require("./util"),DEFAULT_BASE_URL="https://api-ingress.unsharedlabs.com",DEFAULT_TIMEOUT_MS=1e4,DEFAULT_MAX_RETRIES=3,MAX_DELAY_MS=3e4,BASE_DELAY_MS=1e3;function sleep(e){return new Promise(s=>setTimeout(s,e))}function retryDelay(e){const s=Math.min(1e3*Math.pow(2,e-1),3e4),t=s*(.5*Math.random()-.25);return Math.max(0,s+t)}async function parseErrorBody(e){const s=await e.text().catch(()=>"");try{const t=JSON.parse(s);return t?.error?.code?{code:t.error.code,message:t.error.message??"Unknown error",details:t.error.details}:{code:"UNKNOWN_ERROR",message:s||e.statusText}}catch{return{code:"UNKNOWN_ERROR",message:s||e.statusText}}}class UnsharedLabsClient{constructor(e){if(!e.apiKey||""===e.apiKey.trim())throw new Error("apiKey is required");this.i=e.apiKey,this.o=e.baseUrl?e.baseUrl.replace(/\/$/,""):DEFAULT_BASE_URL,this.h=e.timeout??1e4,this.u=e.maxRetries??3,this.l=(0,crypto_1.createHash)("sha256").update(e.apiKey).digest()}_(e){return(0,util_1.encryptData)(e,this.l)}async p(e,s){const t=this.u+1;let r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:"Request failed"}};for(let i=1;i<=t;i++){i>1&&await sleep(retryDelay(i-1));const t=new AbortController,n=setTimeout(()=>t.abort(),this.h);try{const i=await fetch(e,{method:s.method,headers:{"X-API-Key":this.i,...s.headers},body:s.body,signal:t.signal});if(clearTimeout(n),i.ok){const e=await i.text().catch(()=>"{}");let s;try{s=JSON.parse(e)}catch{s={}}const t="data"in s?s.data:s;return{success:!0,status:i.status,data:t}}const a=await parseErrorBody(i);if(i.status>=400&&i.status<500){if(429===i.status){const e=i.headers.get("Retry-After");if(null!=e){const s=parseInt(e,10);isNaN(s)||(a.retryAfter=s)}}return{success:!1,status:i.status,error:a}}r={success:!1,status:i.status,error:a}}catch(e){clearTimeout(n),r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:e instanceof Error?e.message:String(e)}}}}return r}async submitFingerprintEvent(e,s){const t={hash:e.full_hash,stable_hash:e.fingerprint_id,collected_at:e.timestamp,is_incognito:e.isIncognito,components:e.components,version:e.version};return null!=s?.userId&&(t.user_id=this._(s.userId)),null!=s?.sessionHash&&(t.session_hash=s.sessionHash),null!=s?.eventType&&(t.event_type=s.eventType),null!=s?.ipAddress&&(t.ip_address=s.ipAddress),this.p(`${this.o}/v2/submit-fingerprint-event`,{method:"POST",headers:{"Content-Type":"application/json","X-Idempotency-Key":(0,crypto_1.randomUUID)()},body:JSON.stringify(t)})}async processUserEvent(e){const s={event_type:e.eventType,user_id:e.userId,ip_address:e.ipAddress,device_id:this._(e.deviceId),session_hash:e.sessionHash,user_agent:e.userAgent,email_address:this._(e.emailAddress)};return null!=e.fingerprintId&&(s.fingerprint_id=this._(e.fingerprintId)),null!=e.subscriptionStatus&&(s.subscription_status=e.subscriptionStatus),null!=e.eventDetails&&(s.event_details=e.eventDetails),this.p(`${this.o}/v2/process-user-event`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)})}async checkUser(e,s){const t="string"==typeof s?{deviceId:s}:s;if(!t.deviceId&&!t.fingerprintId)return{success:!0,status:200,data:{is_user_flagged:!1}};const r=new URLSearchParams;r.set("email_address",this._(e)),t.deviceId&&r.set("device_id",this._(t.deviceId)),t.fingerprintId&&r.set("fingerprint_id",this._(t.fingerprintId));const i=await this.p(`${this.o}/v2/check-user?${r}`,{method:"GET"});return i.success?i:{success:!0,status:200,data:{is_user_flagged:!1}}}async triggerEmailVerification(e,s,t){const r={email_address:this._(e),device_id:this._(s)};t?.fingerprintId&&(r.fingerprint_id=this._(t.fingerprintId));const i=await this.p(`${this.o}/v2/trigger-email-verification`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(r)});return!i.success&&(0===i.status||i.status>=500)?{success:!1,status:i.status,error:{code:"DELIVERY_FAILED",message:i.error?.message??"Delivery failed"}}:i}async verify(e,s,t,r){const i={email_address:this._(e),device_id:this._(s),code:this._(t)};r?.fingerprintId&&(i.fingerprint_id=this._(r.fingerprintId));const n=await this.p(`${this.o}/v2/verify`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(i)});return!n.success&&(0===n.status||n.status>=500)?{success:!1,status:n.status,error:{code:"DELIVERY_FAILED",message:n.error?.message??"Delivery failed"}}:n.success&&!1===n.data?.verified?{success:!1,status:n.status,error:{code:"VERIFICATION_FAILED",message:"Code is incorrect or expired",details:n.data.reason?{reason:n.data.reason}:void 0}}:n}async getVerificationFlowConfig(){const e=await this.p(`${this.o}/v2/verification-flow-config`,{method:"GET"});return e.success&&e.data?e.data:null}}exports.UnsharedLabsClient=UnsharedLabsClient;
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.UnsharedClient=void 0;const crypto_1=require("crypto"),util_1=require("./util"),DEFAULT_BASE_URL="https://api.unshared.ai",DEFAULT_TIMEOUT_MS=1e4,DEFAULT_MAX_RETRIES=3,MAX_DELAY_MS=3e4,BASE_DELAY_MS=1e3;function sleep(e){return new Promise(s=>setTimeout(s,e))}function retryDelay(e){const s=Math.min(1e3*Math.pow(2,e-1),3e4),t=s*(.5*Math.random()-.25);return Math.max(0,s+t)}async function parseErrorBody(e){const s=await e.text().catch(()=>"");try{const t=JSON.parse(s);return t?.error?.code?{code:t.error.code,message:t.error.message??"Unknown error",details:t.error.details}:{code:"UNKNOWN_ERROR",message:s||e.statusText}}catch{return{code:"UNKNOWN_ERROR",message:s||e.statusText}}}class UnsharedClient{constructor(e){if(!e.apiKey||""===e.apiKey.trim())throw new Error("apiKey is required");this.i=e.apiKey,this.o=e.baseUrl?e.baseUrl.replace(/\/$/,""):DEFAULT_BASE_URL,this.h=e.timeout??1e4,this.u=e.maxRetries??3,this.l=(0,crypto_1.createHash)("sha256").update(e.apiKey).digest(),this._=e.fetch}p(e){return(0,util_1.encryptData)(e,this.l)}async m(e,s){const t=this.u+1;let r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:"Request failed"}};for(let i=1;i<=t;i++){i>1&&await sleep(retryDelay(i-1));const t=new AbortController,a=setTimeout(()=>t.abort(),this.h);try{const i=this._??globalThis.fetch,n=await i(e,{method:s.method,headers:{"X-API-Key":this.i,...s.headers},body:s.body,signal:t.signal});if(clearTimeout(a),n.ok){const e=await n.text().catch(()=>"{}");let s;try{s=JSON.parse(e)}catch{s={}}const t="data"in s?s.data:s;return{success:!0,status:n.status,data:t}}const o=await parseErrorBody(n);if(n.status>=400&&n.status<500){if(429===n.status){const e=n.headers.get("Retry-After");if(null!=e){const s=parseInt(e,10);isNaN(s)||(o.retryAfter=s)}}return{success:!1,status:n.status,error:o}}r={success:!1,status:n.status,error:o}}catch(e){clearTimeout(a),r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:e instanceof Error?e.message:String(e)}}}}return r}async submitFingerprintEvent(e,s){const t={hash:e.full_hash,stable_hash:e.fingerprint_id,collected_at:e.timestamp,is_incognito:e.isIncognito,components:e.components,version:e.version};return null!=s?.userId&&(t.user_id=this.p(s.userId)),null!=s?.emailAddress&&(t.email_address=this.p(s.emailAddress)),null!=s?.sessionHash&&(t.session_hash=s.sessionHash),null!=s?.eventType&&(t.event_type=s.eventType),null!=s?.ipAddress&&(t.ip_address=this.p(s.ipAddress)),null!=s?.userAgent&&(t.user_agent=this.p(s.userAgent)),this.m(`${this.o}/v2/submit-fingerprint-event`,{method:"POST",headers:{"Content-Type":"application/json","X-Idempotency-Key":s?.idempotencyKey??(0,crypto_1.randomUUID)()},body:JSON.stringify(t)})}async processUserEvent(e){const s={event_type:e.eventType,user_id:this.p(e.userId),ip_address:this.p(e.ipAddress),device_id:this.p(e.deviceId),session_hash:e.sessionHash,user_agent:this.p(e.userAgent),email_address:this.p(e.emailAddress)};return null!=e.fingerprintId&&(s.fingerprint_id=this.p(e.fingerprintId)),null!=e.subscriptionStatus&&(s.subscription_status=e.subscriptionStatus),null!=e.eventDetails&&(s.event_details=e.eventDetails),this.m(`${this.o}/v2/process-user-event`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)})}async checkUser(e,s){const t="string"==typeof s?{deviceId:s}:s;if(!t.deviceId&&!t.fingerprintId)return{success:!0,status:200,data:{is_user_flagged:!1}};const r=new URLSearchParams;r.set("email_address",this.p(e)),t.deviceId&&r.set("device_id",this.p(t.deviceId)),t.fingerprintId&&r.set("fingerprint_id",this.p(t.fingerprintId));const i=await this.m(`${this.o}/v2/check-user?${r}`,{method:"GET"});return i.success?i:{success:!0,status:200,data:{is_user_flagged:!1}}}async triggerEmailVerification(e,s,t){const r={email_address:this.p(e),device_id:this.p(s)};t?.fingerprintId&&(r.fingerprint_id=this.p(t.fingerprintId));const i=await this.m(`${this.o}/v2/trigger-email-verification`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(r)});return!i.success&&(0===i.status||i.status>=500)?{success:!1,status:i.status,error:{code:"DELIVERY_FAILED",message:i.error?.message??"Delivery failed"}}:i}async verify(e,s,t,r){const i={email_address:this.p(e),device_id:this.p(s),code:this.p(t)};r?.fingerprintId&&(i.fingerprint_id=this.p(r.fingerprintId));const a=await this.m(`${this.o}/v2/verify`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(i)});return!a.success&&(0===a.status||a.status>=500)?{success:!1,status:a.status,error:{code:"DELIVERY_FAILED",message:a.error?.message??"Delivery failed"}}:a.success&&!1===a.data?.verified?{success:!1,status:a.status,error:{code:"VERIFICATION_FAILED",message:"Code is incorrect or expired",details:a.data.reason?{reason:a.data.reason}:void 0}}:a}}exports.UnsharedClient=UnsharedClient;

package/dist/esm/client.d.mts

@@ -1,5 +1,5 @@
 import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
-export interface UnsharedLabsClientConfig {
+export interface UnsharedClientConfig {
     /**
      * Secret API key. Must be kept server-side.
      * Format: usk_…
@@ -7,7 +7,7 @@ export interface UnsharedLabsClientConfig {
     apiKey: string;
     /**
      * Base URL of the Unshared Labs V2 ingress.
-     * @default "https://api-ingress.unsharedlabs.com"
+     * @default "https://api.unshared.ai"
      */
     baseUrl?: string;
     /**
@@ -20,8 +20,28 @@ export interface UnsharedLabsClientConfig {
      * @default 3
      */
     maxRetries?: number;
+    /**
+     * Custom fetch implementation. Use this to configure connection pooling,
+     * custom HTTP agents, or proxies. Defaults to the global `fetch`.
+     *
+     * @example
+     * ```typescript
+     * import { Agent, fetch as undiciFetch } from 'undici';
+     *
+     * const agent = new Agent({
+     *   keepAliveTimeout: 30_000,
+     *   connections: 50,
+     * });
+     *
+     * const client = new UnsharedClient({
+     *   apiKey: 'usk_...',
+     *   fetch: (url, init) => undiciFetch(url, { ...init, dispatcher: agent }),
+     * });
+     * ```
+     */
+    fetch?: typeof globalThis.fetch;
 }
-export interface UnsharedLabsError {
+export interface UnsharedError {
     code: string;
     message: string;
     details?: Record<string, unknown>;
@@ -35,14 +55,27 @@ export interface UnsharedLabsError {
 export interface ApiResult<T = unknown> {
     success: boolean;
     data?: T;
-    error?: UnsharedLabsError;
+    error?: UnsharedError;
     status: number;
 }
 export interface SubmitFingerprintOptions {
     userId?: string;
+    /** SDK encrypts before sending. */
+    emailAddress?: string;
     sessionHash?: string;
     eventType?: string;
+    /** SDK encrypts before sending. */
     ipAddress?: string;
+    /** SDK encrypts before sending. */
+    userAgent?: string;
+    /**
+     * Client-supplied idempotency key. Forwarded verbatim as X-Idempotency-Key
+     * so the backend's ON CONFLICT (idempotency_key) catches duplicates across
+     * reloads, tabs, and concurrent SDK instances. When omitted, a fresh UUID
+     * is generated (best-effort dedup only within a single submitFingerprintEvent
+     * call's retries).
+     */
+    idempotencyKey?: string;
 }
 export interface SubmitFingerprintResult {
     hash: string;
@@ -53,12 +86,14 @@ export interface SubmitFingerprintResult {
 }
 export interface ProcessUserEventParams {
     eventType: string;
+    /** SDK encrypts before sending. */
     userId: string;
-    /** Plaintext — SDK does not encrypt this field. */
+    /** SDK encrypts before sending. */
     ipAddress: string;
     /** SDK encrypts before sending. */
     deviceId: string;
     sessionHash: string;
+    /** SDK encrypts before sending. */
     userAgent: string;
     /** SDK encrypts before sending. */
     emailAddress: string;
@@ -95,29 +130,14 @@ export interface VerifyResult {
     verified: boolean;
     reason?: 'not_found' | 'code_mismatch' | 'code_expired';
 }
-export interface VerificationFlowStep {
-    type: 'message' | 'email_input' | 'otp_input' | 'support_link';
-    title: string;
-    body: string;
-    buttonText?: string;
-    url?: string;
-}
-export interface VerificationFlowConfigResult {
-    steps: VerificationFlowStep[];
-    branding?: {
-        companyName?: string;
-        logoUrl?: string;
-        primaryColor?: string;
-        supportEmail?: string;
-    };
-}
-export declare class UnsharedLabsClient {
+export declare class UnsharedClient {
     private readonly _apiKey;
     private readonly _baseUrl;
     private readonly _timeout;
     private readonly _maxRetries;
     private readonly _encryptionKey;
-    constructor(config: UnsharedLabsClientConfig);
+    private readonly _customFetch;
+    constructor(config: UnsharedClientConfig);
     private _encrypt;
     /**
      * Core HTTP method with retry logic.
@@ -181,16 +201,4 @@ export declare class UnsharedLabsClient {
     verify(emailAddress: string, deviceId: string, code: string, opts?: {
         fingerprintId?: string;
     }): Promise<ApiResult<VerifyResult>>;
-    /**
-     * Fetch the verification flow configuration for this company.
-     * Maps to: GET /v2/verification-flow-config
-     *
-     * Returns the flow steps and branding configured by the Unshared Labs
-     * team for this company. The middleware uses this to render the
-     * verification overlay.
-     *
-     * Returns `null` on any failure (network error, 4xx, 5xx) so the
-     * middleware can fall back to the default flow.
-     */
-    getVerificationFlowConfig(): Promise<VerificationFlowConfigResult | null>;
 }

package/dist/esm/client.mjs

@@ -1 +1 @@
-import{createHash,randomUUID}from"crypto";import{encryptData}from"./util";const DEFAULT_BASE_URL="https://api-ingress.unsharedlabs.com",DEFAULT_TIMEOUT_MS=1e4,DEFAULT_MAX_RETRIES=3,MAX_DELAY_MS=3e4,BASE_DELAY_MS=1e3;function sleep(e){return new Promise(s=>setTimeout(s,e))}function retryDelay(e){const s=Math.min(1e3*Math.pow(2,e-1),3e4),t=s*(.5*Math.random()-.25);return Math.max(0,s+t)}async function parseErrorBody(e){const s=await e.text().catch(()=>"");try{const t=JSON.parse(s);return t?.error?.code?{code:t.error.code,message:t.error.message??"Unknown error",details:t.error.details}:{code:"UNKNOWN_ERROR",message:s||e.statusText}}catch{return{code:"UNKNOWN_ERROR",message:s||e.statusText}}}export class UnsharedLabsClient{constructor(e){if(!e.apiKey||""===e.apiKey.trim())throw new Error("apiKey is required");this.t=e.apiKey,this.i=e.baseUrl?e.baseUrl.replace(/\/$/,""):DEFAULT_BASE_URL,this.o=e.timeout??1e4,this.h=e.maxRetries??3,this.u=createHash("sha256").update(e.apiKey).digest()}l(e){return encryptData(e,this.u)}async _(e,s){const t=this.h+1;let r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:"Request failed"}};for(let i=1;i<=t;i++){i>1&&await sleep(retryDelay(i-1));const t=new AbortController,a=setTimeout(()=>t.abort(),this.o);try{const i=await fetch(e,{method:s.method,headers:{"X-API-Key":this.t,...s.headers},body:s.body,signal:t.signal});if(clearTimeout(a),i.ok){const e=await i.text().catch(()=>"{}");let s;try{s=JSON.parse(e)}catch{s={}}const t="data"in s?s.data:s;return{success:!0,status:i.status,data:t}}const n=await parseErrorBody(i);if(i.status>=400&&i.status<500){if(429===i.status){const e=i.headers.get("Retry-After");if(null!=e){const s=parseInt(e,10);isNaN(s)||(n.retryAfter=s)}}return{success:!1,status:i.status,error:n}}r={success:!1,status:i.status,error:n}}catch(e){clearTimeout(a),r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:e instanceof Error?e.message:String(e)}}}}return r}async submitFingerprintEvent(e,s){const t={hash:e.full_hash,stable_hash:e.fingerprint_id,collected_at:e.timestamp,is_incognito:e.isIncognito,components:e.components,version:e.version};return null!=s?.userId&&(t.user_id=this.l(s.userId)),null!=s?.sessionHash&&(t.session_hash=s.sessionHash),null!=s?.eventType&&(t.event_type=s.eventType),null!=s?.ipAddress&&(t.ip_address=s.ipAddress),this._(`${this.i}/v2/submit-fingerprint-event`,{method:"POST",headers:{"Content-Type":"application/json","X-Idempotency-Key":randomUUID()},body:JSON.stringify(t)})}async processUserEvent(e){const s={event_type:e.eventType,user_id:e.userId,ip_address:e.ipAddress,device_id:this.l(e.deviceId),session_hash:e.sessionHash,user_agent:e.userAgent,email_address:this.l(e.emailAddress)};return null!=e.fingerprintId&&(s.fingerprint_id=this.l(e.fingerprintId)),null!=e.subscriptionStatus&&(s.subscription_status=e.subscriptionStatus),null!=e.eventDetails&&(s.event_details=e.eventDetails),this._(`${this.i}/v2/process-user-event`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)})}async checkUser(e,s){const t="string"==typeof s?{deviceId:s}:s;if(!t.deviceId&&!t.fingerprintId)return{success:!0,status:200,data:{is_user_flagged:!1}};const r=new URLSearchParams;r.set("email_address",this.l(e)),t.deviceId&&r.set("device_id",this.l(t.deviceId)),t.fingerprintId&&r.set("fingerprint_id",this.l(t.fingerprintId));const i=await this._(`${this.i}/v2/check-user?${r}`,{method:"GET"});return i.success?i:{success:!0,status:200,data:{is_user_flagged:!1}}}async triggerEmailVerification(e,s,t){const r={email_address:this.l(e),device_id:this.l(s)};t?.fingerprintId&&(r.fingerprint_id=this.l(t.fingerprintId));const i=await this._(`${this.i}/v2/trigger-email-verification`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(r)});return!i.success&&(0===i.status||i.status>=500)?{success:!1,status:i.status,error:{code:"DELIVERY_FAILED",message:i.error?.message??"Delivery failed"}}:i}async verify(e,s,t,r){const i={email_address:this.l(e),device_id:this.l(s),code:this.l(t)};r?.fingerprintId&&(i.fingerprint_id=this.l(r.fingerprintId));const a=await this._(`${this.i}/v2/verify`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(i)});return!a.success&&(0===a.status||a.status>=500)?{success:!1,status:a.status,error:{code:"DELIVERY_FAILED",message:a.error?.message??"Delivery failed"}}:a.success&&!1===a.data?.verified?{success:!1,status:a.status,error:{code:"VERIFICATION_FAILED",message:"Code is incorrect or expired",details:a.data.reason?{reason:a.data.reason}:void 0}}:a}async getVerificationFlowConfig(){const e=await this._(`${this.i}/v2/verification-flow-config`,{method:"GET"});return e.success&&e.data?e.data:null}}
+import{createHash,randomUUID}from"crypto";import{encryptData}from"./util";const DEFAULT_BASE_URL="https://api.unshared.ai",DEFAULT_TIMEOUT_MS=1e4,DEFAULT_MAX_RETRIES=3,MAX_DELAY_MS=3e4,BASE_DELAY_MS=1e3;function sleep(e){return new Promise(s=>setTimeout(s,e))}function retryDelay(e){const s=Math.min(1e3*Math.pow(2,e-1),3e4),t=s*(.5*Math.random()-.25);return Math.max(0,s+t)}async function parseErrorBody(e){const s=await e.text().catch(()=>"");try{const t=JSON.parse(s);return t?.error?.code?{code:t.error.code,message:t.error.message??"Unknown error",details:t.error.details}:{code:"UNKNOWN_ERROR",message:s||e.statusText}}catch{return{code:"UNKNOWN_ERROR",message:s||e.statusText}}}export class UnsharedClient{constructor(e){if(!e.apiKey||""===e.apiKey.trim())throw new Error("apiKey is required");this.t=e.apiKey,this.i=e.baseUrl?e.baseUrl.replace(/\/$/,""):DEFAULT_BASE_URL,this.o=e.timeout??1e4,this.h=e.maxRetries??3,this.u=createHash("sha256").update(e.apiKey).digest(),this.l=e.fetch}_(e){return encryptData(e,this.u)}async p(e,s){const t=this.h+1;let r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:"Request failed"}};for(let i=1;i<=t;i++){i>1&&await sleep(retryDelay(i-1));const t=new AbortController,a=setTimeout(()=>t.abort(),this.o);try{const i=this.l??globalThis.fetch,n=await i(e,{method:s.method,headers:{"X-API-Key":this.t,...s.headers},body:s.body,signal:t.signal});if(clearTimeout(a),n.ok){const e=await n.text().catch(()=>"{}");let s;try{s=JSON.parse(e)}catch{s={}}const t="data"in s?s.data:s;return{success:!0,status:n.status,data:t}}const o=await parseErrorBody(n);if(n.status>=400&&n.status<500){if(429===n.status){const e=n.headers.get("Retry-After");if(null!=e){const s=parseInt(e,10);isNaN(s)||(o.retryAfter=s)}}return{success:!1,status:n.status,error:o}}r={success:!1,status:n.status,error:o}}catch(e){clearTimeout(a),r={success:!1,status:0,error:{code:"NETWORK_ERROR",message:e instanceof Error?e.message:String(e)}}}}return r}async submitFingerprintEvent(e,s){const t={hash:e.full_hash,stable_hash:e.fingerprint_id,collected_at:e.timestamp,is_incognito:e.isIncognito,components:e.components,version:e.version};return null!=s?.userId&&(t.user_id=this._(s.userId)),null!=s?.emailAddress&&(t.email_address=this._(s.emailAddress)),null!=s?.sessionHash&&(t.session_hash=s.sessionHash),null!=s?.eventType&&(t.event_type=s.eventType),null!=s?.ipAddress&&(t.ip_address=this._(s.ipAddress)),null!=s?.userAgent&&(t.user_agent=this._(s.userAgent)),this.p(`${this.i}/v2/submit-fingerprint-event`,{method:"POST",headers:{"Content-Type":"application/json","X-Idempotency-Key":s?.idempotencyKey??randomUUID()},body:JSON.stringify(t)})}async processUserEvent(e){const s={event_type:e.eventType,user_id:this._(e.userId),ip_address:this._(e.ipAddress),device_id:this._(e.deviceId),session_hash:e.sessionHash,user_agent:this._(e.userAgent),email_address:this._(e.emailAddress)};return null!=e.fingerprintId&&(s.fingerprint_id=this._(e.fingerprintId)),null!=e.subscriptionStatus&&(s.subscription_status=e.subscriptionStatus),null!=e.eventDetails&&(s.event_details=e.eventDetails),this.p(`${this.i}/v2/process-user-event`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(s)})}async checkUser(e,s){const t="string"==typeof s?{deviceId:s}:s;if(!t.deviceId&&!t.fingerprintId)return{success:!0,status:200,data:{is_user_flagged:!1}};const r=new URLSearchParams;r.set("email_address",this._(e)),t.deviceId&&r.set("device_id",this._(t.deviceId)),t.fingerprintId&&r.set("fingerprint_id",this._(t.fingerprintId));const i=await this.p(`${this.i}/v2/check-user?${r}`,{method:"GET"});return i.success?i:{success:!0,status:200,data:{is_user_flagged:!1}}}async triggerEmailVerification(e,s,t){const r={email_address:this._(e),device_id:this._(s)};t?.fingerprintId&&(r.fingerprint_id=this._(t.fingerprintId));const i=await this.p(`${this.i}/v2/trigger-email-verification`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(r)});return!i.success&&(0===i.status||i.status>=500)?{success:!1,status:i.status,error:{code:"DELIVERY_FAILED",message:i.error?.message??"Delivery failed"}}:i}async verify(e,s,t,r){const i={email_address:this._(e),device_id:this._(s),code:this._(t)};r?.fingerprintId&&(i.fingerprint_id=this._(r.fingerprintId));const a=await this.p(`${this.i}/v2/verify`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(i)});return!a.success&&(0===a.status||a.status>=500)?{success:!1,status:a.status,error:{code:"DELIVERY_FAILED",message:a.error?.message??"Delivery failed"}}:a.success&&!1===a.data?.verified?{success:!1,status:a.status,error:{code:"VERIFICATION_FAILED",message:"Code is incorrect or expired",details:a.data.reason?{reason:a.data.reason}:void 0}}:a}}

package/dist/esm/index.d.mts

@@ -1,6 +1,8 @@
-export { UnsharedLabsClient } from './client';
+export { UnsharedClient } from './client';
 export { createUnsharedMiddleware, assertTrustProxy } from './middleware';
 export type { MiddlewareOptions } from './middleware';
-export { unsharedBoundToUser, VerdictCache, } from './middleware/index';
+export { unsharedBoundToUser, VerdictCache, flaggedResponse, ACCOUNT_FLAGGED_ERROR, } from './middleware/index';
 export type { ProtectionConfig, Verdict } from './middleware/index';
-export type { UnsharedLabsClientConfig, ApiResult, UnsharedLabsError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, VerificationFlowStep, VerificationFlowConfigResult, } from './client';
+export type { UnsharedClientConfig, ApiResult, UnsharedError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, } from './client';
+export type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from './types';
+export { sendJson } from './middleware/utils/http-helpers';

package/dist/esm/index.mjs

@@ -1 +1 @@
-export{UnsharedLabsClient}from"./client";export{createUnsharedMiddleware,assertTrustProxy}from"./middleware";export{unsharedBoundToUser,VerdictCache}from"./middleware/index";
+export{UnsharedClient}from"./client";export{createUnsharedMiddleware,assertTrustProxy}from"./middleware";export{unsharedBoundToUser,VerdictCache,flaggedResponse,ACCOUNT_FLAGGED_ERROR}from"./middleware/index";export{sendJson}from"./middleware/utils/http-helpers";

package/dist/esm/middleware/dispatch-dedupe.d.mts

@@ -0,0 +1,11 @@
+export declare class DispatchDedupe {
+    private readonly _entries;
+    private readonly _ttlMs;
+    constructor(ttlMs?: number);
+    private _key;
+    mark(userId: string, eventType: string): void;
+    wasRecentlyDispatched(userId: string, eventType: string): boolean;
+    clear(): void;
+    get size(): number;
+    private _sweep;
+}

package/dist/esm/middleware/dispatch-dedupe.mjs

@@ -0,0 +1 @@
+const DEFAULT_TTL_MS=1e4,SWEEP_THRESHOLD=1e3;export class DispatchDedupe{constructor(t=1e4){this.t=new Map,this.i=t}h(t,s){return`${t}|${s}`}mark(t,s){this.t.set(this.h(t,s),Date.now()),this.t.size>1e3&&this.o()}wasRecentlyDispatched(t,s){const e=this.h(t,s),i=this.t.get(e);return!(void 0===i||Date.now()-i>this.i&&(this.t.delete(e),1))}clear(){this.t.clear()}get size(){return this.t.size}o(){const t=Date.now()-this.i;for(const[s,e]of this.t)e<t&&this.t.delete(s)}}

package/dist/esm/middleware/index.d.mts

@@ -1,19 +1,20 @@
-import type { Request, Response, NextFunction } from 'express';
-import type { UnsharedLabsClient } from '../client';
+import type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from '../types';
+import type { UnsharedClient } from '../client';
 import { VerdictCache } from './verdict-cache';
 import type { Verdict } from './verdict-cache';
-export interface ProtectionConfig {
+export { flaggedResponse, ACCOUNT_FLAGGED_ERROR } from './utils/flagged-response';
+export interface ProtectionConfig<TReq extends UnsharedRequest = UnsharedRequest> {
     /**
      * Required. Resolves the current user's ID from the request.
      * Return undefined for anonymous/logged-out visitors.
      */
-    userId: (req: Request) => string | undefined;
+    userId: (req: TReq) => string | undefined;
     /**
      * Resolves the current user's email address from the request.
      * Required in Tier 2 (backend-only). Recommended in Tier 1.
      * Falls back to HttpOnly cookie → req.body.email when not configured.
      */
-    emailAddress?: (req: Request) => string | undefined;
+    emailAddress?: (req: TReq) => string | undefined;
     /** Route prefix for internal routes. @default "/__unshared" */
     routePrefix?: string;
     /** Allowed CORS origins for /__unshared/* routes. */
@@ -22,13 +23,19 @@ export interface ProtectionConfig {
     cacheTTL?: number;
     /** Paths to skip entirely (static assets, health checks). */
     skipPaths?: string[];
+    /** When set, only paths matching one of these prefixes get events dispatched and checkUser called. */
+    includePathPrefix?: string[];
+    /** Skip the bot/crawler UA filter. Set to true in test environments so automated browsers (Playwright, Puppeteer, etc.) can observe verdicts. @default false */
+    disableBotFilter?: boolean;
+    /** Hard timeout (ms) for checkUser on cache miss. Fails open on timeout. @default 500 */
+    checkUserTimeoutMs?: number;
     /** Resolves a custom session ID. Falls back to __unshared_sid cookie. */
-    sessionId?: (req: Request) => string | undefined;
+    sessionId?: (req: TReq) => string | undefined;
     /**
      * Resolves a device ID from the request.
-     * Falls back to __unshared_fp_id cookie → X-Device-Id header.
+     * Falls back to X-Device-Id header → __unshared_fp_id cookie.
      */
-    deviceId?: (req: Request) => string | undefined;
+    deviceId?: (req: TReq) => string | undefined;
     /**
      * Called when a flagged, unverified user makes a request.
      * You own the response — block, redirect, or call next() to let it through.
@@ -40,11 +47,24 @@ export interface ProtectionConfig {
         userId: string;
         emailAddress: string;
         verdict: Verdict;
-        req: Request;
-        res: Response;
-        next: NextFunction;
+        req: TReq;
+        res: UnsharedResponse;
+        next: UnsharedNextFunction;
+    }) => void;
+    /**
+     * Called when a background SDK operation fails (fire-and-forget API calls,
+     * verdict refreshes, etc.). Use this to pipe errors to your logging or
+     * monitoring system for observability.
+     *
+     * Without this callback, background errors are silently swallowed (fail-open).
+     * The middleware never blocks requests due to these errors regardless.
+     */
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
     }) => void;
 }
 export type { Verdict };
 export { VerdictCache };
-export declare function unsharedBoundToUser(client: UnsharedLabsClient, config: ProtectionConfig): (req: Request, res: Response, next: NextFunction) => void;
+export declare function unsharedBoundToUser<TReq extends UnsharedRequest = UnsharedRequest>(client: UnsharedClient, config: ProtectionConfig<TReq>): (req: TReq, res: UnsharedResponse, next: UnsharedNextFunction) => void;

package/dist/esm/middleware/index.mjs

@@ -1 +1 @@
-import{readFileSync}from"fs";import{VerdictCache}from"./verdict-cache";import{RateLimitBackoff}from"./rate-limit-backoff";import{interceptResponse}from"./response-interceptor";import{generateFingerprintScript}from"./injection/fingerprint-script";import{handleSubmitFingerprint}from"./routes/submit-fp";import{handleVerifyTrigger,handleVerify}from"./routes/verify";import{isHtmlContentType}from"./utils/content-type";import{shouldSkipPath}from"./utils/skip-paths";export{VerdictCache};const CHECK_USER_TIMEOUT_MS=500;export function unsharedBoundToUser(e,t){if(!t.userId)throw new Error("[Unshared] userId resolver is required");if(!t.emailAddress){let e=!1;try{require.resolve("unshared-frontend-sdk"),e=!0}catch{}e||console.warn("[Unshared] Warning: emailAddress resolver is not configured and unshared-frontend-sdk is not installed.\nNo user events will be submitted. Either install unshared-frontend-sdk (Tier 1) or\nprovide emailAddress in your middleware config (Tier 2).")}const{userId:r,emailAddress:n,routePrefix:i="/__unshared",corsOrigins:o,cacheTTL:s=6e4,skipPaths:c,sessionId:d,deviceId:a,onFlagged:l}=t,u=new VerdictCache(s),p=new RateLimitBackoff,f=Date.now().toString(36),m=generateFingerprintScript(i,f);let h="";try{const e=require.resolve("unshared-frontend-sdk/dist/index.umd.js");h=readFileSync(e,"utf8")}catch{}const v=handleSubmitFingerprint({client:e,verdictCache:u,rateLimitBackoff:p,resolveUserId:r,resolveEmailAddress:n,resolveSessionId:d,resolveDeviceId:a}),C=handleVerifyTrigger({client:e,verdictCache:u,resolveEmailAddress:n,resolveDeviceId:a}),g=handleVerify({client:e,verdictCache:u,resolveEmailAddress:n,resolveDeviceId:a}),I=o?Array.isArray(o)?o:[o]:null,y=`${i}/fp.js`,k=`${i}/submit-fp`,S=`${i}/verify-trigger`,_=`${i}/verify`;return function(t,o,s){const f=t.path;if(f.startsWith(i+"/"))return function(e,t){if(!I)return;const r=e.headers.origin??"",n=I.includes("*");(n||I.includes(r))&&(t.setHeader("Access-Control-Allow-Origin",n?"*":r),t.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),t.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id, X-Device-Id"),t.setHeader("Access-Control-Allow-Credentials","true"))}(t,o),"OPTIONS"===t.method?void o.status(204).end():"GET"===t.method&&f===y?(o.setHeader("Content-Type","application/javascript"),o.setHeader("Cache-Control","public, max-age=3600"),void o.status(200).end(h)):"POST"===t.method&&f===k?void v(t,o):"POST"===t.method&&f===S?void C(t,o):"POST"===t.method&&f===_?void g(t,o):void o.status(404).json({success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}});if(shouldSkipPath(f,c))return void s();let A;try{A=r(t)}catch{}if(!A)return clearEmailCookieIfPresent(t,o),interceptForInjection(t,o,m),void s();const T=resolveEmail(t,n);if(setUserIdCookie(o,A),T&&setEmailCookie(o,T),!T)return interceptForInjection(t,o,m),void s();const E=extractSessionId(t,d),x=extractDeviceId(t,a),F=extractFingerprintId(t),w=t.headers["user-agent"]??"",P=t.ip??"";p.isPaused()||dispatchUserEvent(e,u,p,{userId:A,emailAddress:T,sessionId:E,deviceId:x,fingerprintId:F,userAgent:w,ipAddress:P,eventType:`${t.method} ${t.path}`});const O=u.get(A);O?(u.isStale(A)&&!u.isRefreshing(A)&&(u.markRefreshing(A),fetchAndCacheVerdict(e,u,A,T,x,F,E).finally(()=>u.clearRefreshing(A))),applyVerdict(O,A,T,t,o,s,m,l)):fetchAndCacheVerdict(e,u,A,T,x,F,E).then(e=>{applyVerdict(e,A,T,t,o,s,m,l)}).catch(()=>{interceptForInjection(t,o,m),s()})}}function resolveEmail(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=parseCookie(e,"__unshared_email");if(r)return r;const n=e.body?.email;return"string"==typeof n&&n?n:void 0}function applyVerdict(e,t,r,n,i,o,s,c){if(interceptForInjection(n,i,s),e.isFlagged&&!e.isVerified&&c)try{c({userId:t,emailAddress:r,verdict:e,req:n,res:i,next:o})}catch{o()}else o()}function preventHtmlCaching(e,t){delete e.headers["if-none-match"],delete e.headers["if-modified-since"];const r=t.writeHead.bind(t);t.writeHead=function(e,...n){const i=t.getHeader("content-type");return i&&String(i).includes("text/html")&&(t.setHeader("Cache-Control","no-store"),t.removeHeader("ETag"),t.removeHeader("Last-Modified")),r(e,...n)}}function interceptForInjection(e,t,r){preventHtmlCaching(e,t),interceptResponse(t,(e,t)=>{if(!isHtmlContentType(t))return null;const n=e.toString("utf8"),i=n.lastIndexOf("</body>");return-1===i?n+r:n.slice(0,i)+r+n.slice(i)})}function dispatchUserEvent(e,t,r,n){e.processUserEvent({eventType:n.eventType,userId:n.userId,emailAddress:n.emailAddress,ipAddress:n.ipAddress,deviceId:n.deviceId,fingerprintId:n.fingerprintId,sessionHash:n.sessionId,userAgent:n.userAgent}).then(e=>{e.success&&e.data?.analysis&&t.update(n.userId,{isFlagged:e.data.analysis.is_user_flagged}),!e.success&&e.error?.retryAfter&&r.pause(1e3*e.error.retryAfter)}).catch(()=>{})}async function fetchAndCacheVerdict(e,t,r,n,i,o,s){const c={};i&&"unknown"!==i&&(c.deviceId=i),o&&(c.fingerprintId=o);const d=await Promise.race([e.checkUser(n,c),new Promise(e=>setTimeout(()=>e(null),500))]);if(!d)return{isFlagged:!1,isVerified:!1,emailAddress:n,sessionId:s,cachedAt:0,ttl:0};const a=d.data?.is_user_flagged??!1;return t.set(r,{isFlagged:a,isVerified:!1,emailAddress:n,sessionId:s}),t.get(r)}function parseCookie(e,t){const r=e.headers.cookie;if(!r)return;const n=r.match(new RegExp(`(?:^|; )${t}=([^;]*)`));return n?decodeURIComponent(n[1]):void 0}function extractSessionId(e,t){if(t)try{const r=t(e);if(r)return r}catch{}return parseCookie(e,"__unshared_sid")??"unknown"}function extractDeviceId(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=parseCookie(e,"__unshared_fp_id");if(r)return r;const n=e.headers["x-device-id"];return"string"==typeof n&&n?n:"unknown"}function extractFingerprintId(e){return parseCookie(e,"__unshared_fingerprint_id")||void 0}function appendSetCookie(e,t){const r=e.getHeader("Set-Cookie");if(r){const n=Array.isArray(r)?[...r]:[String(r)];n.push(t),e.setHeader("Set-Cookie",n)}else e.setHeader("Set-Cookie",t)}function setUserIdCookie(e,t){appendSetCookie(e,`__unshared_uid=${encodeURIComponent(t)}; Path=/; SameSite=Lax`)}function setEmailCookie(e,t){appendSetCookie(e,`__unshared_email=${encodeURIComponent(t)}; HttpOnly; Path=/; SameSite=Lax`)}function clearEmailCookieIfPresent(e,t){parseCookie(e,"__unshared_email")&&appendSetCookie(t,"__unshared_email=; HttpOnly; Path=/; SameSite=Lax; Max-Age=0")}
+import{readFileSync}from"fs";import{VerdictCache}from"./verdict-cache";import{RateLimitBackoff}from"./rate-limit-backoff";import{DispatchDedupe}from"./dispatch-dedupe";import{interceptResponse}from"./response-interceptor";import{generateFingerprintScript}from"./injection/fingerprint-script";import{handleSubmitFingerprint}from"./routes/submit-fp";import{handleVerifyTrigger,handleVerify}from"./routes/verify";import{sendJson,sendEmpty,sendBody,getRequestPath}from"./utils/http-helpers";import{isHtmlContentType}from"./utils/content-type";import{shouldSkipPath}from"./utils/skip-paths";import{shouldIncludePath}from"./utils/include-path";import{isBot}from"./utils/is-bot";import{extractClientIp}from"./utils/client-ip";import{parseCookie}from"./utils/cookies";import{extractDeviceIdOrUndefined}from"./utils/device-id";import{isSecureRequest}from"./utils/secure";export{flaggedResponse,ACCOUNT_FLAGGED_ERROR}from"./utils/flagged-response";import{isSentinelUserId,SENTINEL_STICKINESS_TTL_MS}from"./utils/sentinel-user-id";export{VerdictCache};const CHECK_USER_TIMEOUT_MS=500;export function unsharedBoundToUser(e,t){if(!t.userId)throw new Error("[Unshared] userId resolver is required");if(!t.emailAddress){let e=!1;try{require.resolve("unshared-frontend-sdk"),e=!0}catch{}e||console.warn("[Unshared] Warning: emailAddress resolver is not configured and unshared-frontend-sdk is not installed.\nNo user events will be submitted. Either install unshared-frontend-sdk (Tier 1) or\nprovide emailAddress in your middleware config (Tier 2).")}const{userId:r,emailAddress:i,routePrefix:n="/__unshared",corsOrigins:s,cacheTTL:o=6e4,skipPaths:d,includePathPrefix:a,disableBotFilter:c=!1,checkUserTimeoutMs:u=CHECK_USER_TIMEOUT_MS,sessionId:l,deviceId:p,onFlagged:f,onError:m}=t,h=new VerdictCache(o),S=new RateLimitBackoff,I=new DispatchDedupe,_=Date.now().toString(36),v=generateFingerprintScript(n,_);let C="";try{const e=require.resolve("unshared-frontend-sdk/dist/index.umd.js");C=readFileSync(e,"utf8")}catch{}const g=handleSubmitFingerprint({client:e,verdictCache:h,rateLimitBackoff:S,dispatchDedupe:I,resolveUserId:r,resolveEmailAddress:i,resolveSessionId:l,resolveDeviceId:p,onError:m}),y=handleVerifyTrigger({client:e,verdictCache:h,resolveEmailAddress:i,resolveDeviceId:p,onError:m}),k=handleVerify({client:e,verdictCache:h,resolveEmailAddress:i,resolveDeviceId:p,onError:m}),A=s?Array.isArray(s)?s:[s]:null,E=`${n}/fp.js`,T=`${n}/submit-fp`,x=`${n}/verify-trigger`,U=`${n}/verify`,P=`${n}/status`;return function(t,s,o){const _=getRequestPath(t.url),w=t.url||_;if(_.startsWith(n+"/")){if(function(e,t){if(!A)return;const r=e.headers.origin??"",i=A.includes("*");(i||A.includes(r))&&(t.setHeader("Access-Control-Allow-Origin",i?"*":r),t.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),t.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id, X-Device-Id"),t.setHeader("Access-Control-Allow-Credentials","true"))}(t,s),"OPTIONS"===t.method)return void sendEmpty(s,204);if("GET"===t.method&&_===E)return s.setHeader("Content-Type","application/javascript"),s.setHeader("Cache-Control","public, max-age=3600"),void sendBody(s,200,C);if("POST"===t.method&&(_===T||_===x||_===U))return void 0===t.body?void sendJson(s,400,{success:!1,error:{code:"BODY_PARSER_MISSING",message:"req.body is undefined. Mount a JSON body-parsing middleware (e.g., express.json()) before the Unshared middleware."}}):_===T?void g(t,s):_===x?void y(t,s):void k(t,s);if("GET"===t.method&&_===P){let n;try{n=r(t)}catch{}if(!n)return void sendJson(s,200,{status:"anonymous"});const o=resolveEmail(t,i);return void(async()=>{let r=h.get(n);if((!r||h.isStale(n))&&o&&!S.isPaused()&&!h.isRefreshing(n)){h.markRefreshing(n);try{const i=extractDeviceIdOrUndefined(t,p),s=extractFingerprintId(t),d=extractSessionId(t,l),a=i??s??"unknown";await fetchAndCacheVerdict(e,h,n,o,a,s,d,u),r=h.get(n)}catch(e){m&&m(e,{operation:"checkUser",userId:n,emailAddress:o})}finally{h.clearRefreshing(n)}}r&&r.isFlagged&&!r.isVerified&&f&&o?sendJson(s,200,{status:"flagged",email:o}):sendJson(s,200,{status:"ok"})})()}return void sendJson(s,404,{success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}})}if(shouldSkipPath(_,d))return void o();if(!shouldIncludePath(_,a))return interceptForInjection(t,s,v),void o();let F;try{F=r(t)}catch{}if(isSentinelUserId(F)){const e=parseCookie(t,"__unshared_uid"),r=parseCookie(t,"__unshared_uid_at"),i=r?Number(r):NaN,n=Number.isFinite(i)&&Date.now()-i<=SENTINEL_STICKINESS_TTL_MS;F=e&&n?e:void 0}if(!F){const e=isSecureRequest(t)?"; Secure":"";return appendSetCookie(s,`__unshared_uid=; Path=/; SameSite=Lax; Max-Age=0${e}`),appendSetCookie(s,`__unshared_uid_at=; Path=/; SameSite=Lax; Max-Age=0${e}`),appendSetCookie(s,`__unshared_sid=; Path=/; SameSite=Lax; Max-Age=0${e}`),appendSetCookie(s,`__unshared_email=; Path=/; SameSite=Lax; Max-Age=0${e}`),interceptForInjection(t,s,v),void o()}const O=resolveEmail(t,i);if(setUserIdCookie(t,s,F),O&&setEmailCookie(t,s,O),!O)return interceptForInjection(t,s,v),void o();const R=extractSessionId(t,l),D=extractDeviceIdOrUndefined(t,p),N=extractFingerprintId(t),b=t.headers["user-agent"]??"",L=extractClientIp(t),M=D??N;if(!c&&isBot(b))return void o();const V=h.get(F);function $(){"unknown"!==R&&M&&(S.isPaused()||dispatchUserEvent(e,h,S,I,{userId:F,emailAddress:O,sessionId:R,deviceId:M,fingerprintId:N,userAgent:b,ipAddress:L,eventType:w},m))}V?(h.isStale(F)&&!h.isRefreshing(F)&&(h.markRefreshing(F),fetchAndCacheVerdict(e,h,F,O,M??"unknown",N,R,u).finally(()=>h.clearRefreshing(F))),V.isFlagged||$(),applyVerdict(V,F,O,t,s,o,v,f)):fetchAndCacheVerdict(e,h,F,O,M??"unknown",N,R,u).then(e=>{e.isFlagged||$(),applyVerdict(e,F,O,t,s,o,v,f)}).catch(()=>{$(),interceptForInjection(t,s,v),o()})}}function resolveEmail(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=parseCookie(e,"__unshared_email");if(r)return r;const i=e.body?.email;return"string"==typeof i&&i?i:void 0}function applyVerdict(e,t,r,i,n,s,o,d){if(interceptForInjection(i,n,o),e.isFlagged&&!e.isVerified&&d)try{d({userId:t,emailAddress:r,verdict:e,req:i,res:n,next:s})}catch{s()}else s()}function interceptForInjection(e,t,r){delete e.headers["if-none-match"],delete e.headers["if-modified-since"],interceptResponse(t,(e,t)=>{if(!isHtmlContentType(t))return null;const i=e.toString("utf8"),n=i.lastIndexOf("</body>");return-1===n?i+r:i.slice(0,n)+r+i.slice(n)},{preventCaching:!0})}function dispatchUserEvent(e,t,r,i,n,s){i.mark(n.userId,n.eventType),e.processUserEvent({eventType:n.eventType,userId:n.userId,emailAddress:n.emailAddress,ipAddress:n.ipAddress,deviceId:n.deviceId,fingerprintId:n.fingerprintId,sessionHash:n.sessionId,userAgent:n.userAgent}).then(e=>{e.success&&e.data?.analysis&&t.update(n.userId,{isFlagged:e.data.analysis.is_user_flagged}),!e.success&&e.error?.retryAfter&&r.pause(1e3*e.error.retryAfter)}).catch(e=>{s&&s(e,{operation:"processUserEvent",userId:n.userId,emailAddress:n.emailAddress})})}async function fetchAndCacheVerdict(e,t,r,i,n,s,o,d=CHECK_USER_TIMEOUT_MS){const a={};let c;n&&"unknown"!==n&&(a.deviceId=n),s&&(a.fingerprintId=s);const u=await Promise.race([e.checkUser(i,a),new Promise(e=>{c=setTimeout(()=>e(null),d)})]);if(clearTimeout(c),!u)return{isFlagged:!1,isVerified:!1,emailAddress:i,sessionId:o,cachedAt:0,ttl:0};const l=u.data?.is_user_flagged??!1;return t.set(r,{isFlagged:l,isVerified:!1,emailAddress:i,sessionId:o}),t.get(r)}function extractSessionId(e,t){if(t)try{const r=t(e);if(r)return r}catch{}return parseCookie(e,"__unshared_sid")??"unknown"}function extractFingerprintId(e){return parseCookie(e,"__unshared_fingerprint_id")||void 0}function appendSetCookie(e,t){const r=e.getHeader("Set-Cookie");if(r){const i=Array.isArray(r)?[...r]:[String(r)];i.push(t),e.setHeader("Set-Cookie",i)}else e.setHeader("Set-Cookie",t)}function setUserIdCookie(e,t,r){const i=isSecureRequest(e)?"; Secure":"";appendSetCookie(t,`__unshared_uid=${encodeURIComponent(r)}; Path=/; SameSite=Lax${i}`),appendSetCookie(t,`__unshared_uid_at=${Date.now()}; Path=/; SameSite=Lax${i}`)}function setEmailCookie(e,t,r){const i=isSecureRequest(e)?"; Secure":"";appendSetCookie(t,`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax${i}`)}

package/dist/esm/middleware/injection/fingerprint-script.d.mts

@@ -1,10 +1,16 @@
 /**
- * Generates a small inline loader script that:
- *   1. Loads the real fingerprint SDK from /__unshared/fp.js
- *   2. Collects a full fingerprint (31+ signals, MurmurHash3 Merkle tree)
- *   3. POSTs the result to /__unshared/submit-fp
+ * Generates an inline loader script that:
+ *   1. Loads the fingerprint SDK from /__unshared/fp.js
+ *   2. Collects a fingerprint and POSTs to /__unshared/submit-fp
+ *   3. Caches fingerprint in sessionStorage for reuse on SPA navigations
+ *   4. Patches History API to detect SPA route changes → re-submits fingerprint
+ *   5. Patches fetch/XHR to detect 403 account_flagged → dispatches "unshared:flagged" event
  *
  * The actual SDK UMD bundle is served by the middleware at /__unshared/fp.js.
- * This keeps the injected HTML small (~500 bytes) while using the full library.
+ *
+ * Event contract:
+ *   window.addEventListener("unshared:flagged", (e) => {
+ *     e.detail.email — the flagged user's email (from 403 response body)
+ *   });
  */
 export declare function generateFingerprintScript(routePrefix: string, version?: string): string;