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

package/dist/esm/middleware/routes/submit-fp.d.mts

@@ -1,15 +1,22 @@
-import type { Request, Response } from 'express';
-import type { UnsharedLabsClient } from '../../client';
+import type { UnsharedRequest, UnsharedResponse } from '../../types';
+import type { UnsharedClient } from '../../client';
 import type { VerdictCache } from '../verdict-cache';
 import type { RateLimitBackoff } from '../rate-limit-backoff';
-export interface SubmitFingerprintDependencies {
-    client: UnsharedLabsClient;
+import type { DispatchDedupe } from '../dispatch-dedupe';
+export interface SubmitFingerprintDependencies<TReq extends UnsharedRequest = UnsharedRequest> {
+    client: UnsharedClient;
     verdictCache: VerdictCache;
     rateLimitBackoff: RateLimitBackoff;
-    resolveUserId?: (req: Request) => string | undefined;
-    resolveEmailAddress?: (req: Request) => string | undefined;
-    resolveSessionId?: (req: Request) => string | undefined;
-    resolveDeviceId?: (req: Request) => string | undefined;
+    dispatchDedupe: DispatchDedupe;
+    resolveUserId?: (req: TReq) => string | undefined;
+    resolveEmailAddress?: (req: TReq) => string | undefined;
+    resolveSessionId?: (req: TReq) => string | undefined;
+    resolveDeviceId?: (req: TReq) => string | undefined;
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
+    }) => void;
 }
 /**
  * Handles POST /__unshared/submit-fp
@@ -21,4 +28,4 @@ export interface SubmitFingerprintDependencies {
  *
  * Always returns 200 (fire-and-forget from browser's perspective).
  */
-export declare function handleSubmitFingerprint(dependencies: SubmitFingerprintDependencies): (req: Request, res: Response) => Promise<void>;
+export declare function handleSubmitFingerprint<TReq extends UnsharedRequest = UnsharedRequest>(dependencies: SubmitFingerprintDependencies<TReq>): (req: TReq, res: UnsharedResponse) => Promise<void>;

package/dist/esm/middleware/routes/submit-fp.mjs

@@ -1 +1 @@
-export function handleSubmitFingerprint(e){return async(n,t)=>{try{const i=n.body??{},o={full_hash:i.hash??"",fingerprint_id:i.stable_hash??"",timestamp:i.collected_at??(new Date).toISOString(),isIncognito:i.is_incognito??!1,components:i.components??{},version:i.version??"inline-1.0.0"};let s,r,a;try{s=e.resolveUserId?e.resolveUserId(n):void 0}catch{}s=s??i.user_id??void 0;try{r=e.resolveEmailAddress?e.resolveEmailAddress(n):void 0}catch{}r=r??parseCookie(n,"__unshared_email")??i.email??void 0;try{a=e.resolveSessionId?e.resolveSessionId(n):void 0}catch{}a=a??i.session_id??parseCookie(n,"__unshared_sid");const c=n.ip??"",d=n.headers["user-agent"]??"",_=extractDeviceId(n,e.resolveDeviceId),u=o.fingerprint_id||void 0,p=[];if(u&&!parseCookie(n,"__unshared_fingerprint_id")&&p.push(`__unshared_fingerprint_id=${encodeURIComponent(u)}; HttpOnly; Path=/; SameSite=Lax`),r&&!parseCookie(n,"__unshared_email")&&p.push(`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax`),p.length>0){const e=t.getHeader("Set-Cookie");if(e){const n=Array.isArray(e)?[...e]:[String(e)];n.push(...p),t.setHeader("Set-Cookie",n)}else t.setHeader("Set-Cookie",p)}s&&e.client.submitFingerprintEvent(o,{userId:s,sessionHash:a,eventType:"auto_collect",ipAddress:c}).catch(()=>{}),s&&r&&!e.rateLimitBackoff.isPaused()&&e.client.processUserEvent({eventType:"auto_collect",userId:s,emailAddress:r,ipAddress:c,deviceId:_,fingerprintId:u,sessionHash:a??"unknown",userAgent:d}).then(n=>{n.success&&n.data?.analysis&&e.verdictCache.update(s,{isFlagged:n.data.analysis.is_user_flagged}),!n.success&&n.error?.retryAfter&&e.rateLimitBackoff.pause(1e3*n.error.retryAfter)}).catch(()=>{}),t.status(200).json({success:!0})}catch{t.status(200).json({success:!0})}}}function extractDeviceId(e,n){if(n)try{const t=n(e);if(t)return t}catch{}const t=parseCookie(e,"__unshared_fp_id");if(t)return t;const i=e.headers["x-device-id"];return"string"==typeof i&&i?i:"unknown"}function parseCookie(e,n){const t=e.headers.cookie;if(!t)return;const i=t.match(new RegExp(`(?:^|; )${n}=([^;]*)`));return i?decodeURIComponent(i[1]):void 0}
+import{isBot}from"../utils/is-bot";import{extractClientIp}from"../utils/client-ip";import{parseCookie}from"../utils/cookies";import{extractDeviceId}from"../utils/device-id";import{isSecureRequest}from"../utils/secure";import{isSentinelUserId}from"../utils/sentinel-user-id";import{sendJson}from"../utils/http-helpers";export function handleSubmitFingerprint(e){return async(i,t)=>{try{const s=i.body??{},n={full_hash:s.hash??"",fingerprint_id:s.stable_hash??"",timestamp:s.collected_at??(new Date).toISOString(),isIncognito:s.is_incognito??!1,components:s.components??{},version:s.version??"inline-1.0.0"};let o,r,d;try{const t=e.resolveUserId?e.resolveUserId(i):void 0;t&&!isSentinelUserId(t)&&(o=t)}catch{}if(!o){const e="string"==typeof s.user_id?s.user_id:void 0;e&&!isSentinelUserId(e)&&(o=e)}if(!o){const e=parseCookie(i,"__unshared_uid");e&&!isSentinelUserId(e)&&(o=e)}try{r=e.resolveEmailAddress?e.resolveEmailAddress(i):void 0}catch{}r=r??parseCookie(i,"__unshared_email")??s.email??void 0;try{d=e.resolveSessionId?e.resolveSessionId(i):void 0}catch{}d=d??s.session_id??parseCookie(i,"__unshared_sid");const a=extractClientIp(i),c=i.headers["user-agent"]??"";if(isBot(c))return void sendJson(t,200,{success:!0});const p=(n.fingerprint_id&&n.fingerprint_id.length>0?n.fingerprint_id:void 0)??extractDeviceId(i,e.resolveDeviceId),u=n.fingerprint_id||void 0,l=n.full_hash||void 0,m=isSecureRequest(i)?"; Secure":"",_=[];if(l&&!parseCookie(i,"__unshared_fingerprint_id")&&_.push(`__unshared_fingerprint_id=${encodeURIComponent(l)}; HttpOnly; Path=/; SameSite=Lax${m}`),u){const e=parseCookie(i,"__unshared_fp_id");e&&e===u||_.push(`__unshared_fp_id=${encodeURIComponent(u)}; Path=/; SameSite=Lax; Max-Age=31536000${m}`)}if(r&&!parseCookie(i,"__unshared_email")&&_.push(`__unshared_email=${encodeURIComponent(r)}; HttpOnly; Path=/; SameSite=Lax${m}`),_.length>0){const e=t.getHeader("Set-Cookie");if(e){const i=Array.isArray(e)?[...e]:[String(e)];i.push(..._),t.setHeader("Set-Cookie",i)}else t.setHeader("Set-Cookie",_)}let f;if("string"==typeof s.event_type&&s.event_type)f=s.event_type;else{const e=i.headers.referer??i.headers.referrer;let t="unknown";if("string"==typeof e&&e.length>0)try{const i=new URL(e);t=(i.pathname||"/")+(i.search||"")}catch{}f=t}const h=i.headers["x-idempotency-key"],v="string"==typeof h&&h.length>0?h:void 0,y=Date.now(),I=v?`${v}|${y}`:u&&o?`${u}|${o}|${f}|${y}`:void 0;if(o&&e.client.submitFingerprintEvent(n,{userId:o,emailAddress:r,sessionHash:d,eventType:f,ipAddress:a,userAgent:c,idempotencyKey:I}).catch(i=>{e.onError&&e.onError(i,{operation:"submitFingerprintEvent",userId:o,emailAddress:r})}),o&&r&&!e.rateLimitBackoff.isPaused()&&!e.dispatchDedupe.wasRecentlyDispatched(o,f))try{const i=await e.client.processUserEvent({eventType:f,userId:o,emailAddress:r,ipAddress:a,deviceId:p,fingerprintId:u,sessionHash:d??"unknown",userAgent:c});i.success&&i.data?.analysis&&e.verdictCache.update(o,{isFlagged:i.data.analysis.is_user_flagged}),!i.success&&i.error?.retryAfter&&e.rateLimitBackoff.pause(1e3*i.error.retryAfter)}catch(i){e.onError&&e.onError(i,{operation:"processUserEvent",userId:o,emailAddress:r})}sendJson(t,200,{success:!0})}catch{sendJson(t,200,{success:!0})}}}

package/dist/esm/middleware/routes/verify.d.mts

@@ -1,11 +1,16 @@
-import type { Request, Response } from 'express';
-import type { UnsharedLabsClient } from '../../client';
+import type { UnsharedRequest, UnsharedResponse } from '../../types';
+import type { UnsharedClient } from '../../client';
 import type { VerdictCache } from '../verdict-cache';
-export interface VerificationDependencies {
-    client: UnsharedLabsClient;
+export interface VerificationDependencies<TReq extends UnsharedRequest = UnsharedRequest> {
+    client: UnsharedClient;
     verdictCache: VerdictCache;
-    resolveEmailAddress?: (req: Request) => string | undefined;
-    resolveDeviceId?: (req: Request) => string | undefined;
+    resolveEmailAddress?: (req: TReq) => string | undefined;
+    resolveDeviceId?: (req: TReq) => string | undefined;
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
+    }) => void;
 }
 /**
  * POST /__unshared/verify-trigger
@@ -15,7 +20,7 @@ export interface VerificationDependencies {
  *
  * The deviceId is resolved via extractDeviceId (same as the middleware).
  */
-export declare function handleVerifyTrigger(dependencies: VerificationDependencies): (req: Request, res: Response) => Promise<void>;
+export declare function handleVerifyTrigger<TReq extends UnsharedRequest = UnsharedRequest>(dependencies: VerificationDependencies<TReq>): (req: TReq, res: UnsharedResponse) => Promise<void>;
 /**
  * POST /__unshared/verify
  * Validates OTP code. Called by the blocker overlay UI.
@@ -25,4 +30,4 @@ export declare function handleVerifyTrigger(dependencies: VerificationDependenci
  * On successful verification, updates the verdict cache to mark
  * the user as verified so subsequent requests pass through.
  */
-export declare function handleVerify(dependencies: VerificationDependencies): (req: Request, res: Response) => Promise<void>;
+export declare function handleVerify<TReq extends UnsharedRequest = UnsharedRequest>(dependencies: VerificationDependencies<TReq>): (req: TReq, res: UnsharedResponse) => Promise<void>;

package/dist/esm/middleware/routes/verify.mjs

@@ -1 +1 @@
-export function handleVerifyTrigger(e){return async(r,i)=>{try{const s=resolveEmail(r,r.body??{},e.resolveEmailAddress);if(!s)return void i.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}});const n=extractDeviceId(r,e.resolveDeviceId),o=parseCookie(r,"__unshared_fingerprint_id")||void 0,t=await e.client.triggerEmailVerification(s,n,{fingerprintId:o});t.success?i.status(200).json({success:!0,data:t.data}):i.status(200).json({success:!1,error:t.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}})}catch{i.status(200).json({success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}})}}}export function handleVerify(e){return async(r,i)=>{try{const s=r.body??{},n=resolveEmail(r,s,e.resolveEmailAddress),o=s.code;if(!n||!o)return void i.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Email and code are required"}});const t=extractDeviceId(r,e.resolveDeviceId),c=parseCookie(r,"__unshared_fingerprint_id")||void 0,a=await e.client.verify(n,t,o,{fingerprintId:c});if(a.success){const s=parseCookie(r,"__unshared_uid");s&&e.verdictCache.update(s,{isVerified:!0}),i.status(200).json({success:!0,data:{verified:!0}})}else i.status(200).json({success:!1,error:a.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}})}catch{i.status(200).json({success:!1,error:{code:"INTERNAL_ERROR",message:"Verification failed"}})}}}function resolveEmail(e,r,i){if(i)try{const r=i(e);if(r)return r}catch{}const s=parseCookie(e,"__unshared_email");if(s)return s;const n=r.email;return"string"==typeof n&&n?n:void 0}function extractDeviceId(e,r){if(r)try{const i=r(e);if(i)return i}catch{}const i=parseCookie(e,"__unshared_fp_id");if(i)return i;const s=e.headers["x-device-id"];return"string"==typeof s&&s?s:"unknown"}function parseCookie(e,r){const i=e.headers.cookie;if(!i)return;const s=i.match(new RegExp(`(?:^|; )${r}=([^;]*)`));return s?decodeURIComponent(s[1]):void 0}
+import{parseCookie}from"../utils/cookies";import{extractDeviceId}from"../utils/device-id";import{sendJson}from"../utils/http-helpers";export function handleVerifyTrigger(e){return async(r,s)=>{try{const i=resolveEmail(r,r.body??{},e.resolveEmailAddress);if(!i)return void sendJson(s,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}});const o=extractDeviceId(r,e.resolveDeviceId),n=parseCookie(r,"__unshared_fingerprint_id")||void 0,t=await e.client.triggerEmailVerification(i,o,{fingerprintId:n});t.success?sendJson(s,200,{success:!0,data:t.data}):sendJson(s,200,{success:!1,error:t.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}})}catch(r){e.onError&&e.onError(r,{operation:"verifyTrigger"}),sendJson(s,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}})}}}export function handleVerify(e){return async(r,s)=>{try{const i=r.body??{},o=resolveEmail(r,i,e.resolveEmailAddress),n=i.code;if(!o||!n)return void sendJson(s,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email and code are required"}});const t=extractDeviceId(r,e.resolveDeviceId),c=parseCookie(r,"__unshared_fingerprint_id")||void 0,a=await e.client.verify(o,t,n,{fingerprintId:c});if(a.success){const i=parseCookie(r,"__unshared_uid");i&&e.verdictCache.update(i,{isVerified:!0}),sendJson(s,200,{success:!0,data:{verified:!0}})}else sendJson(s,200,{success:!1,error:a.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}})}catch(r){e.onError&&e.onError(r,{operation:"verify"}),sendJson(s,200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Verification failed"}})}}}function resolveEmail(e,r,s){if(s)try{const r=s(e);if(r)return r}catch{}const i=parseCookie(e,"__unshared_email");if(i)return i;const o=r.email;return"string"==typeof o&&o?o:void 0}

package/dist/esm/middleware/utils/client-ip.d.mts

@@ -0,0 +1,6 @@
+import type { UnsharedRequest } from '../../types';
+/**
+ * Extract the real client IP from proxy headers, falling back to req.ip or socket address.
+ * Checked in order: CF-Connecting-IP (Cloudflare) → X-Real-IP (nginx/ALB) → req.ip → socket.
+ */
+export declare function extractClientIp(req: UnsharedRequest): string;

package/dist/esm/middleware/utils/client-ip.mjs

@@ -0,0 +1 @@
+export function extractClientIp(t){const n=t.headers["cf-connecting-ip"];if("string"==typeof n&&n)return n;const r=t.headers["x-real-ip"];return"string"==typeof r&&r?r:t.ip??t.socket?.remoteAddress??""}

package/dist/esm/middleware/utils/cookies.d.mts

@@ -0,0 +1,6 @@
+import type { UnsharedRequest } from '../../types';
+/**
+ * Reads a single cookie value from the raw Cookie header.
+ * Works without cookie-parser middleware.
+ */
+export declare function parseCookie(req: UnsharedRequest, name: string): string | undefined;

package/dist/esm/middleware/utils/cookies.mjs

@@ -0,0 +1 @@
+export function parseCookie(e,o){const n=e.headers.cookie;if(!n)return;const t=n.match(new RegExp(`(?:^|; )${o}=([^;]*)`));return t?decodeURIComponent(t[1]):void 0}

package/dist/esm/middleware/utils/device-id.d.mts

@@ -0,0 +1,19 @@
+import type { UnsharedRequest } from '../../types';
+/**
+ * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
+ *
+ * Returns the literal string `"unknown"` when no source provides a value.
+ * Callers that can tolerate a tri-state should use `extractDeviceIdOrUndefined`
+ * instead — the "unknown" sentinel polluted 19% of FP rows in production
+ * because it was being dispatched as-if-real during the first request of a
+ * session, before the inline script had a chance to set `__unshared_fp_id`.
+ * Kept for API compatibility.
+ */
+export declare function extractDeviceId<TReq extends UnsharedRequest = UnsharedRequest>(req: TReq, resolveDeviceId?: (req: TReq) => string | undefined): string;
+/**
+ * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
+ * Returns `undefined` when nothing is available. Use this at any call site
+ * that can take a "skip dispatch" branch during the bootstrap window, so we
+ * stop writing `device_id="unknown"` rows to the analytics table on first request.
+ */
+export declare function extractDeviceIdOrUndefined<TReq extends UnsharedRequest = UnsharedRequest>(req: TReq, resolveDeviceId?: (req: TReq) => string | undefined): string | undefined;

package/dist/esm/middleware/utils/device-id.mjs

@@ -0,0 +1 @@
+import{parseCookie}from"./cookies";export function extractDeviceId(e,r){return extractDeviceIdOrUndefined(e,r)??"unknown"}export function extractDeviceIdOrUndefined(e,r){if(r)try{const t=r(e);if(t)return t}catch{}const t=e.headers["x-device-id"];if("string"==typeof t&&t)return t;return parseCookie(e,"__unshared_fp_id")||void 0}

package/dist/esm/middleware/utils/http-helpers.d.mts

@@ -0,0 +1,21 @@
+import type { UnsharedResponse } from '../../types';
+/**
+ * Send a JSON response. Framework-agnostic replacement for Express's
+ * `res.status(code).json(data)`.
+ */
+export declare function sendJson(res: UnsharedResponse, statusCode: number, data: unknown): void;
+/**
+ * Send an empty response with a status code. Replacement for Express's
+ * `res.status(code).end()`.
+ */
+export declare function sendEmpty(res: UnsharedResponse, statusCode: number): void;
+/**
+ * Send a response with a specific body. Replacement for Express's
+ * `res.status(code).end(body)`.
+ */
+export declare function sendBody(res: UnsharedResponse, statusCode: number, body: string | Buffer): void;
+/**
+ * Extract the pathname from a request URL, stripping query string.
+ * Framework-agnostic replacement for Express's `req.path`.
+ */
+export declare function getRequestPath(url: string | undefined): string;

package/dist/esm/middleware/utils/http-helpers.mjs

@@ -0,0 +1 @@
+export function sendJson(n,t,o){const e=JSON.stringify(o);n.statusCode=t,n.setHeader("Content-Type","application/json"),n.end(e)}export function sendEmpty(n,t){n.statusCode=t,n.end()}export function sendBody(n,t,o){n.statusCode=t,n.end(o)}export function getRequestPath(n){if(!n)return"/";const t=n.indexOf("?");return-1===t?n:n.slice(0,t)}

package/dist/esm/middleware/utils/include-path.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Returns true if the path matches at least one of the includePathPrefix entries.
+ * When includePathPrefix is undefined, returns true (all paths match — preserves default behavior).
+ * When includePathPrefix is an empty array, returns false (no paths match).
+ */
+export declare function shouldIncludePath(path: string, includePathPrefix?: string[]): boolean;

package/dist/esm/middleware/utils/include-path.mjs

@@ -0,0 +1 @@
+export function shouldIncludePath(n,t){return!t||t.some(t=>n.startsWith(t))}

package/dist/esm/middleware/utils/is-bot.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Returns true if the User-Agent string matches a known bot, crawler,
+ * scanner, or HTTP client library pattern.
+ */
+export declare function isBot(userAgent: string): boolean;

package/dist/esm/middleware/utils/is-bot.mjs

@@ -0,0 +1 @@
+const BOT_PATTERNS=["googlebot","bingbot","slurp","baiduspider","duckduckbot","yandex","sogou","exabot","ia_archiver","curl","wget","python-requests","python-urllib","axios","node-fetch","go-http-client","java/","libwww-perl","okhttp","apache-httpclient","http_request","httpie","headlesschrome","phantomjs","puppeteer","playwright","cypress","selenium","webdriver","electron","jsdom","vercel-screenshot","screenshot","prerender","lighthouse","chrome-lighthouse","pagespeed","gtmetrix","pingdom","nessus","nikto","sqlmap","burp","zap","qualys","openvas","nmap","masscan","facebookexternalhit","twitterbot","linkedinbot","whatsapp","telegrambot","slackbot","discordbot","bot","crawl","spider","scrape","fetch","scan"],BOT_RE=new RegExp(BOT_PATTERNS.join("|"),"i");export function isBot(e){return!!e&&BOT_RE.test(e)}

package/dist/esm/middleware/utils/secure.d.mts

@@ -0,0 +1,3 @@
+import type { UnsharedRequest } from '../../types';
+/** Returns true if the request arrived over HTTPS (direct or via reverse proxy). */
+export declare function isSecureRequest(req: UnsharedRequest): boolean;

package/dist/esm/middleware/utils/secure.mjs

@@ -0,0 +1 @@
+export function isSecureRequest(e){return!!e.socket?.encrypted||"https"===e.headers["x-forwarded-proto"]}

package/dist/esm/middleware/utils/sentinel-user-id.d.mts

@@ -0,0 +1,10 @@
+/**
+ * Stickiness window: if the resolver returns a sentinel but the
+ * `__unshared_uid` cookie was set within this many milliseconds, we prefer
+ * the cookie value (assuming it's a hydration race on the same tab).
+ * Outside the window, the cookie is considered stale and we fall through
+ * to the "no userId" branch — without clearing the cookie, because clearing
+ * on every hydration blip is exactly the bug we're fixing.
+ */
+export declare const SENTINEL_STICKINESS_TTL_MS = 30000;
+export declare function isSentinelUserId(value: string | undefined | null): boolean;

package/dist/esm/middleware/utils/sentinel-user-id.mjs

@@ -0,0 +1 @@
+const SENTINEL_USER_IDS=new Set(["__pre_auth__","anonymous","guest","undefined","null"]);export const SENTINEL_STICKINESS_TTL_MS=3e4;export function isSentinelUserId(e){return"string"==typeof e&&SENTINEL_USER_IDS.has(e)}

package/dist/esm/middleware/utils/skip-paths.mjs

@@ -1 +1 @@
-const STATIC_EXTENSIONS=new Set([".js",".mjs",".cjs",".css",".map",".png",".jpg",".jpeg",".gif",".svg",".ico",".webp",".avif",".woff",".woff2",".ttf",".otf",".eot",".mp3",".mp4",".webm",".ogg",".wasm",".json",".xml",".txt",".pdf"]),STATIC_PATH_PREFIXES=["/static/","/assets/","/public/","/_next/","/__vite/","/favicon"];export function shouldSkipPath(t,f){if(f)for(const o of f)if(t.startsWith(o))return!0;const o=t.lastIndexOf(".");if(-1!==o){const f=t.slice(o).toLowerCase().split("?")[0];if(STATIC_EXTENSIONS.has(f))return!0}for(const f of STATIC_PATH_PREFIXES)if(t.startsWith(f))return!0;return!1}
+const STATIC_EXTENSIONS=new Set([".js",".mjs",".cjs",".css",".map",".png",".jpg",".jpeg",".gif",".svg",".ico",".webp",".avif",".woff",".woff2",".ttf",".otf",".eot",".mp3",".mp4",".webm",".ogg",".wasm",".xml",".txt",".pdf"]),STATIC_PATH_PREFIXES=["/static/","/assets/","/public/","/_next/","/__vite/","/favicon"];export function shouldSkipPath(t,f){if(f)for(const o of f)if(t.startsWith(o))return!0;const o=t.lastIndexOf(".");if(-1!==o){const f=t.slice(o).toLowerCase().split("?")[0];if(STATIC_EXTENSIONS.has(f))return!0}for(const f of STATIC_PATH_PREFIXES)if(t.startsWith(f))return!0;return!1}

package/dist/esm/middleware/verdict-cache.d.mts

@@ -10,7 +10,9 @@ export declare class VerdictCache {
     private readonly _entries;
     private readonly _activeRefreshes;
     private readonly _defaultTtlMs;
-    constructor(defaultTTL?: number);
+    private readonly _maxSize;
+    private _sweepTimer;
+    constructor(defaultTTL?: number, maxSize?: number);
     get(userId: string): Verdict | undefined;
     set(userId: string, verdict: Omit<Verdict, 'cachedAt' | 'ttl'>, ttl?: number): void;
     /**
@@ -33,4 +35,13 @@ export declare class VerdictCache {
     /** Number of cached entries. */
     get size(): number;
     clear(): void;
+    /**
+     * Stops the periodic sweep timer. Call this when shutting down
+     * or when the middleware is no longer needed (e.g., in tests).
+     */
+    destroy(): void;
+    /** Remove all entries that are past their TTL + a 2x grace period. */
+    private _sweep;
+    /** Evict the oldest entry by cachedAt to make room. */
+    private _evictOldest;
 }

package/dist/esm/middleware/verdict-cache.mjs

@@ -1 +1 @@
-export class VerdictCache{constructor(t=6e4){this.t=new Map,this.i=new Set,this.h=t}get(t){return this.t.get(t)}set(t,e,s){this.t.set(t,{...e,cachedAt:Date.now(),ttl:s??this.h})}update(t,e){const s=this.t.get(t);s?(void 0!==e.isFlagged&&(s.isFlagged=e.isFlagged),void 0!==e.isVerified&&(s.isVerified=e.isVerified),s.cachedAt=Date.now()):this.t.set(t,{isFlagged:e.isFlagged??!1,isVerified:e.isVerified??!1,emailAddress:"",sessionId:"",cachedAt:Date.now(),ttl:this.h})}delete(t){this.t.delete(t),this.i.delete(t)}isStale(t){const e=this.t.get(t);return!!e&&Date.now()-e.cachedAt>e.ttl}isRefreshing(t){return this.i.has(t)}markRefreshing(t){this.i.add(t)}clearRefreshing(t){this.i.delete(t)}get size(){return this.t.size}clear(){this.t.clear(),this.i.clear()}}
+const DEFAULT_TTL_MS=6e4,DEFAULT_MAX_SIZE=1e4,SWEEP_INTERVAL_MS=3e5;export class VerdictCache{constructor(t=6e4,s=1e4){this.t=new Map,this.i=new Set,this.h=null,this.l=t,this.o=s,this.h=setInterval(()=>this.u(),3e5),this.h&&"function"==typeof this.h.unref&&this.h.unref()}get(t){return this.t.get(t)}set(t,s,i){!this.t.has(t)&&this.t.size>=this.o&&this._(),this.t.set(t,{...s,cachedAt:Date.now(),ttl:i??this.l})}update(t,s){const i=this.t.get(t);i?(void 0!==s.isFlagged&&(i.isFlagged=s.isFlagged),void 0!==s.isVerified&&(i.isVerified=s.isVerified),i.cachedAt=Date.now()):(this.t.size>=this.o&&this._(),this.t.set(t,{isFlagged:s.isFlagged??!1,isVerified:s.isVerified??!1,emailAddress:"",sessionId:"",cachedAt:Date.now(),ttl:this.l}))}delete(t){this.t.delete(t),this.i.delete(t)}isStale(t){const s=this.t.get(t);return!!s&&Date.now()-s.cachedAt>s.ttl}isRefreshing(t){return this.i.has(t)}markRefreshing(t){this.i.add(t)}clearRefreshing(t){this.i.delete(t)}get size(){return this.t.size}clear(){this.t.clear(),this.i.clear()}destroy(){this.h&&(clearInterval(this.h),this.h=null),this.clear()}u(){const t=Date.now();for(const[s,i]of this.t)t-i.cachedAt>2*i.ttl&&(this.t.delete(s),this.i.delete(s))}_(){let t=null,s=1/0;for(const[i,e]of this.t)e.cachedAt<s&&(s=e.cachedAt,t=i);t&&(this.t.delete(t),this.i.delete(t))}}

package/dist/esm/middleware.d.mts

@@ -1,14 +1,14 @@
-import type { Request, Response, NextFunction, Application } from 'express';
-import type { UnsharedLabsClient } from './client';
-export interface MiddlewareOptions {
+import type { UnsharedRequest, UnsharedResponse, UnsharedNextFunction } from './types';
+import type { UnsharedClient } from './client';
+export interface MiddlewareOptions<TReq extends UnsharedRequest = UnsharedRequest> {
     /** Override userId extractor. Falls back to req.body.user_id. */
-    userIdExtractor?: (req: Request) => string | undefined;
+    userIdExtractor?: (req: TReq) => string | undefined;
     /** Override eventType extractor. Falls back to req.body.event_type. */
-    eventTypeExtractor?: (req: Request) => string | undefined;
+    eventTypeExtractor?: (req: TReq) => string | undefined;
     /** Override sessionId extractor. Falls back to X-Session-Id header, then req.body.session_id. */
-    sessionIdExtractor?: (req: Request) => string | undefined;
+    sessionIdExtractor?: (req: TReq) => string | undefined;
     /** Override IP address extractor. Falls back to req.ip. */
-    ipAddressExtractor?: (req: Request) => string | undefined;
+    ipAddressExtractor?: (req: TReq) => string | undefined;
     /** Default event type when none is extractable. @default "browser_event" */
     defaultEventType?: string;
     /**
@@ -29,6 +29,9 @@ export interface MiddlewareOptions {
  * Asserts that Express `trust proxy` is configured on the app.
  * Call this once during application startup, before mounting any middleware.
  *
+ * **Express-specific utility.** Other frameworks handle proxy trust differently;
+ * consult your framework's documentation for equivalent configuration.
+ *
  * Throws synchronously if the setting is missing, killing the process before
  * any requests are served.
  *
@@ -39,7 +42,7 @@ export interface MiddlewareOptions {
  * app.use(createUnsharedMiddleware(client, options));
  * ```
  */
-export declare function assertTrustProxy(app: Application): void;
+export declare function assertTrustProxy(app: any): void;
 /**
  * Creates an Express middleware that proxies browser fingerprint events to
  * Unshared Labs. Mount this to handle the browser fingerprint route contract (§4 of spec).
@@ -70,4 +73,4 @@ export declare function assertTrustProxy(app: Application): void;
  * }));
  * ```
  */
-export declare function createUnsharedMiddleware(client: UnsharedLabsClient, options?: MiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+export declare function createUnsharedMiddleware<TReq extends UnsharedRequest = UnsharedRequest>(client: UnsharedClient, options?: MiddlewareOptions<TReq>): (req: TReq, res: UnsharedResponse, next: UnsharedNextFunction) => Promise<void>;

package/dist/esm/middleware.mjs

@@ -1 +1 @@
-export function assertTrustProxy(e){if(!e.get("trust proxy"))throw new Error('[unshared-labs] Express "trust proxy" is not set. Add `app.set("trust proxy", 1)` before calling assertTrustProxy, otherwise req.ip will reflect the proxy\'s IP instead of the real client IP.')}export function createUnsharedMiddleware(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:o,ipAddressExtractor:i,defaultEventType:n="browser_event",routePrefix:c="/unshared",corsOrigins:d}=r??{},a=`${c}/submit-fingerprint-event`,l=d?Array.isArray(d)?d:[d]:null;let u=!1;return async(r,c,d)=>{if(!u&&(u=!0,r.app&&!r.app.get("trust proxy")))throw new Error('[unshared-labs] Express "trust proxy" is not set. Add `app.set("trust proxy", 1)` before mounting this middleware, otherwise req.ip will reflect the proxy\'s IP instead of the real client IP.');if(l&&r.path===a){const e=r.headers.origin??"",s=l.includes("*");if((s||l.includes(e))&&(c.setHeader("Access-Control-Allow-Origin",s?"*":e),c.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),c.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id")),"OPTIONS"===r.method)return void c.status(204).end()}if("POST"===r.method&&r.path===a)try{const d=r.body??{};if(!d.hash||!d.stable_hash||!d.collected_at)return void c.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});if(!r.headers["x-session-id"])return void c.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required header: X-Session-Id"}});const a={full_hash:d.hash,fingerprint_id:d.stable_hash,timestamp:d.collected_at,isIncognito:d.is_incognito??!1,components:d.components??{},version:d.version??"unknown"};let l,u,p,f;try{l=(s?s(r):void 0)??d.user_id}catch{l=d.user_id}if(r.body&&"object"==typeof r.body&&"user_id"in r.body&&delete r.body.user_id,!l)return void c.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}});try{u=(t?t(r):void 0)??d.event_type??n}catch{u=d.event_type??n}try{p=(o?o(r):void 0)??r.headers["x-session-id"]?.toString()??d.session_id}catch{p=r.headers["x-session-id"]?.toString()??d.session_id}try{f=(i?i(r):void 0)??r.ip}catch{f=r.ip}const h=await e.submitFingerprintEvent(a,{userId:l,sessionHash:p,eventType:u,ipAddress:f});if(!h.success)return void c.status(200).json({success:!1,error:{code:"UPSTREAM_ERROR",message:h.error?.message??"Upstream request failed"}});c.status(202).json({success:!0,data:h.data})}catch(e){c.status(200).json({success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else d()}}
+import{sendJson,sendEmpty,getRequestPath}from"./middleware/utils/http-helpers";export function assertTrustProxy(e){if(!e?.get?.("trust proxy"))throw new Error('[unshared-labs] Express "trust proxy" is not set.\n\n  Fix: add this line before mounting any middleware:\n    app.set("trust proxy", 1);\n\n  Why: without it, req.ip returns the proxy/load-balancer IP instead of\n  the real client IP, which degrades account-sharing detection accuracy.\n  Set to 1 if behind a single reverse proxy (Nginx, ALB, CloudFront),\n  or the number of trusted proxies in your chain.')}export function createUnsharedMiddleware(e,s){const{userIdExtractor:r,eventTypeExtractor:t,sessionIdExtractor:n,ipAddressExtractor:o,defaultEventType:i="browser_event",routePrefix:d="/unshared",corsOrigins:c}=s??{},a=`${d}/submit-fingerprint-event`,u=c?Array.isArray(c)?c:[c]:null;return async(s,d,c)=>{const l=getRequestPath(s.url);if(u&&l===a){const e=s.headers.origin??"",r=u.includes("*");if((r||u.includes(e))&&(d.setHeader("Access-Control-Allow-Origin",r?"*":e),d.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),d.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id")),"OPTIONS"===s.method)return void sendEmpty(d,204)}if("POST"===s.method&&l===a)try{if(void 0===s.body)return void sendJson(d,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."}});const c=s.body??{};if(!c.hash||!c.stable_hash||!c.collected_at)return void sendJson(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});if(!s.headers["x-session-id"])return void sendJson(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required header: X-Session-Id"}});const a={full_hash:c.hash,fingerprint_id:c.stable_hash,timestamp:c.collected_at,isIncognito:c.is_incognito??!1,components:c.components??{},version:c.version??"unknown"};let u,l,h,p;try{u=(r?r(s):void 0)??c.user_id}catch{u=c.user_id}if(s.body&&"object"==typeof s.body&&"user_id"in s.body&&delete s.body.user_id,!u)return void sendJson(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}});try{l=(t?t(s):void 0)??c.event_type??i}catch{l=c.event_type??i}try{h=(n?n(s):void 0)??s.headers["x-session-id"]?.toString()??c.session_id}catch{h=s.headers["x-session-id"]?.toString()??c.session_id}const f=s.ip??s.socket?.remoteAddress??"";try{p=(o?o(s):void 0)??f}catch{p=f}const y=await e.submitFingerprintEvent(a,{userId:u,sessionHash:h,eventType:l,ipAddress:p});if(!y.success)return void sendJson(d,200,{success:!1,error:{code:"UPSTREAM_ERROR",message:y.error?.message??"Upstream request failed"}});sendJson(d,202,{success:!0,data:y.data})}catch(e){sendJson(d,200,{success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else c()}}

package/dist/esm/types.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Framework-agnostic HTTP types for the Unshared Labs middleware.
+ *
+ * These interfaces are structurally compatible with Express, Fastify (via raw),
+ * Koa (via ctx.req/ctx.res), and raw Node.js http.IncomingMessage/ServerResponse.
+ */
+import type { IncomingHttpHeaders } from 'http';
+/**
+ * Minimal request interface for framework-agnostic middleware.
+ *
+ * Express, Fastify's `request.raw`, Koa's `ctx.req`, and Node.js
+ * `http.IncomingMessage` all satisfy this interface via structural typing.
+ */
+export interface UnsharedRequest {
+    method?: string;
+    url?: string;
+    headers: IncomingHttpHeaders;
+    body?: any;
+    /** Client IP address, if the framework provides it (e.g. Express `req.ip`). */
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+        encrypted?: boolean;
+    };
+}
+/**
+ * Minimal response interface for framework-agnostic middleware.
+ *
+ * Express `Response`, Fastify's `reply.raw`, Koa's `ctx.res`, and Node.js
+ * `http.ServerResponse` all satisfy this interface via structural typing.
+ */
+export interface UnsharedResponse {
+    statusCode: number;
+    setHeader(name: string, value: string | number | string[]): any;
+    getHeader(name: string): string | number | string[] | undefined;
+    removeHeader(name: string): void;
+    write(chunk: any, encodingOrCallback?: any, callback?: any): boolean;
+    end(chunk?: any, encodingOrCallback?: any, callback?: any): any;
+    writeHead(statusCode: number, ...args: any[]): any;
+}
+/**
+ * Middleware next function. Compatible with Express, Connect, and Koa.
+ */
+export type UnsharedNextFunction = (err?: any) => void;

package/dist/esm/types.mjs

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

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

@@ -0,0 +1,17 @@
+/**
+ * Web Standard Request/Response handlers for serverless/edge environments.
+ *
+ * Use this entry point in Next.js App Router, Vercel Edge Functions,
+ * Cloudflare Workers, Deno Deploy, Bun, or any other runtime that uses
+ * the Web Standard Fetch API (`Request`/`Response` globals).
+ *
+ * For Node.js HTTP frameworks (Express, Fastify, Koa, Next.js Pages Router),
+ * use the default `unshared-clientjs-sdk` entry point instead — its middleware
+ * is compatible with all frameworks that expose `http.IncomingMessage`/
+ * `http.ServerResponse` objects.
+ */
+export { createWebSubmitHandler } from './submit-handler';
+export { createWebProtectionMiddleware } from './protection-handler';
+export type { WebHandler, WebMiddleware, WebSubmitOptions, WebProtectionConfig, } from './types';
+export { VerdictCache } from '../middleware/verdict-cache';
+export type { Verdict } from '../middleware/verdict-cache';

package/dist/esm/web/index.mjs

@@ -0,0 +1 @@
+export{createWebSubmitHandler}from"./submit-handler";export{createWebProtectionMiddleware}from"./protection-handler";export{VerdictCache}from"../middleware/verdict-cache";

package/dist/esm/web/protection-handler.d.mts

@@ -0,0 +1,28 @@
+import type { UnsharedClient } from '../client';
+import type { WebMiddleware, WebProtectionConfig } from './types';
+/**
+ * Web Standard equivalent of `unsharedBoundToUser` from src/middleware/index.ts.
+ *
+ * Returns a middleware `(request, next) => Promise<Response>` suitable for
+ * Next.js App Router, Vercel Edge Functions, Cloudflare Workers, Deno Deploy,
+ * and other Web Standard runtimes.
+ *
+ * Unlike the Node.js middleware which mutates the response object, this
+ * handler calls `next(request)` to get the downstream Response, transforms
+ * it (injects the fingerprint script into HTML), and returns a new Response.
+ *
+ * @example Next.js App Router (in middleware.ts)
+ * ```typescript
+ * import { createWebProtectionMiddleware } from 'unshared-clientjs-sdk/web';
+ *
+ * const protect = createWebProtectionMiddleware(client, {
+ *   userId: (req) => parseJwt(req.headers.get('authorization'))?.sub,
+ *   emailAddress: (req) => parseJwt(req.headers.get('authorization'))?.email,
+ * });
+ *
+ * export async function middleware(request: Request) {
+ *   return protect(request, async () => NextResponse.next());
+ * }
+ * ```
+ */
+export declare function createWebProtectionMiddleware(client: UnsharedClient, config: WebProtectionConfig): WebMiddleware;

package/dist/esm/web/protection-handler.mjs

@@ -0,0 +1 @@
+import{VerdictCache}from"../middleware/verdict-cache";import{RateLimitBackoff}from"../middleware/rate-limit-backoff";import{DispatchDedupe}from"../middleware/dispatch-dedupe";import{generateFingerprintScript}from"../middleware/injection/fingerprint-script";import{isHtmlContentType}from"../middleware/utils/content-type";import{shouldSkipPath}from"../middleware/utils/skip-paths";import{shouldIncludePath}from"../middleware/utils/include-path";import{isBot}from"../middleware/utils/is-bot";import{isSentinelUserId,SENTINEL_STICKINESS_TTL_MS}from"../middleware/utils/sentinel-user-id";import{parseCookieFromRequest,extractClientIpFromRequest,extractDeviceIdFromRequest,extractDeviceIdFromRequestOrUnknown,isSecureWebRequest,jsonResponse,emptyResponse,bodyResponse,mergeResponseHeaders}from"./web-helpers";const CHECK_USER_TIMEOUT_MS=500;export function createWebProtectionMiddleware(e,s){if(!s.userId)throw new Error("[Unshared] userId resolver is required");const{userId:r,emailAddress:t,routePrefix:n="/__unshared",corsOrigins:i,cacheTTL:o=6e4,skipPaths:a,includePathPrefix:d,sessionId:c,deviceId:u,fingerprintSdkBundle:l="",onFlagged:p,onError:m}=s,f=new VerdictCache(o),h=new RateLimitBackoff,_=new DispatchDedupe,R=Date.now().toString(36),I=generateFingerprintScript(n,R),g=`${n}/fp.js`,v=`${n}/submit-fp`,S=`${n}/verify-trigger`,y=`${n}/verify`,C=`${n}/status`,w=i?Array.isArray(i)?i:[i]:null;return async function(s,i){let o,R,A;try{const e=new URL(s.url);o=e.pathname,R=e.search}catch{return i(s)}if(o.startsWith(n+"/")){const n=function(e){if(!w)return{};const s=e.headers.get("origin")??"",r=w.includes("*");return r||w.includes(s)?{"Access-Control-Allow-Origin":r?"*":s,"Access-Control-Allow-Methods":"POST, OPTIONS","Access-Control-Allow-Headers":"Content-Type, X-Idempotency-Key, X-Session-Id, X-Device-Id","Access-Control-Allow-Credentials":"true"}:{}}(s);if("OPTIONS"===s.method)return emptyResponse(204,n);if("GET"===s.method&&o===g)return l?bodyResponse(200,l,{...n,"Content-Type":"application/javascript","Cache-Control":"public, max-age=3600"}):jsonResponse(404,{success:!1,error:{code:"NOT_FOUND",message:"Fingerprint SDK bundle not configured. Pass fingerprintSdkBundle in config."}},n);if("POST"===s.method&&(o===v||o===S||o===y)){let i;try{i=await s.json()}catch{return jsonResponse(400,{success:!1,error:{code:"BODY_PARSER_MISSING",message:"Request body is not valid JSON."}},n)}return o===v?handleSubmitFp(s,i,{client:e,verdictCache:f,rateLimitBackoff:h,dispatchDedupe:_,resolveUserId:r,resolveEmailAddress:t,resolveSessionId:c,resolveDeviceId:u,onError:m},n):o===S?handleVerifyTriggerWeb(s,i,{client:e,verdictCache:f,resolveEmailAddress:t,resolveDeviceId:u,onError:m},n):handleVerifyWeb(s,i,{client:e,verdictCache:f,resolveEmailAddress:t,resolveDeviceId:u,onError:m},n)}if("GET"===s.method&&o===C){let e;try{e=r(s)}catch{}if(!e)return jsonResponse(200,{status:"anonymous"},n);const i=resolveEmail(s,t),o=f.get(e);return o&&o.isFlagged&&!o.isVerified&&p&&i?jsonResponse(403,{error:"account_flagged",email:i},n):jsonResponse(200,{status:"ok"},n)}return jsonResponse(404,{success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}},n)}if(shouldSkipPath(o,a))return i(s);if(!shouldIncludePath(o,d))return injectIntoHtmlResponse(await i(s),I);try{A=r(s)}catch{}if(isSentinelUserId(A)){const e=parseCookieFromRequest(s,"__unshared_uid"),r=parseCookieFromRequest(s,"__unshared_uid_at"),t=r?Number(r):NaN,n=Number.isFinite(t)&&Date.now()-t<=SENTINEL_STICKINESS_TTL_MS;A=e&&n?e:void 0}if(!A){const e=isSecureWebRequest(s)?"; Secure":"",r=[`__unshared_uid=; Path=/; SameSite=Lax; Max-Age=0${e}`,`__unshared_uid_at=; Path=/; SameSite=Lax; Max-Age=0${e}`,`__unshared_sid=; Path=/; SameSite=Lax; Max-Age=0${e}`,`__unshared_email=; Path=/; SameSite=Lax; Max-Age=0${e}`];return injectIntoHtmlResponse(await i(s),I,r)}const E=resolveEmail(s,t),F=[],T=isSecureWebRequest(s)?"; Secure":"";if(F.push(`__unshared_uid=${encodeURIComponent(A)}; Path=/; SameSite=Lax${T}`),F.push(`__unshared_uid_at=${Date.now()}; Path=/; SameSite=Lax${T}`),E&&F.push(`__unshared_email=${encodeURIComponent(E)}; HttpOnly; Path=/; SameSite=Lax${T}`),!E)return injectIntoHtmlResponse(await i(s),I,F);const k=extractSessionIdFromRequest(s,c),q=extractDeviceIdFromRequest(s,u),x=parseCookieFromRequest(s,"__unshared_fingerprint_id")||void 0,O=s.headers.get("user-agent")??"",j=extractClientIpFromRequest(s),D=q??x;if(isBot(O))return i(s);let L=f.get(A);if(L)f.isStale(A)&&!f.isRefreshing(A)&&(f.markRefreshing(A),fetchAndCacheVerdict(e,f,A,E,D??"unknown",x,k).finally(()=>f.clearRefreshing(A)));else try{L=await fetchAndCacheVerdict(e,f,A,E,D??"unknown",x,k)}catch{return injectIntoHtmlResponse(await i(s),I,F)}if(L.isFlagged&&!L.isVerified&&p)try{const e=await p({userId:A,emailAddress:E,verdict:L,request:s});if(e)return injectIntoHtmlResponse(e,I,F)}catch(e){m&&m(e,{operation:"checkUser",userId:A,emailAddress:E})}return L.isFlagged||"unknown"===k||!D||h.isPaused()||dispatchUserEvent(e,f,h,_,{userId:A,emailAddress:E,sessionId:k,deviceId:D,fingerprintId:x,userAgent:O,ipAddress:j,eventType:o+R},m),injectIntoHtmlResponse(await i(s),I,F)}}async function injectIntoHtmlResponse(e,s,r){const t=e.headers.get("content-type");if(!isHtmlContentType(t??void 0)){if(!r||0===r.length)return e;const s=mergeResponseHeaders(e.headers,void 0,r);return new Response(e.body,{status:e.status,statusText:e.statusText,headers:s})}const n=await e.text(),i=n.lastIndexOf("</body>"),o=-1===i?n+s:n.slice(0,i)+s+n.slice(i),a=mergeResponseHeaders(e.headers,{"Cache-Control":"no-store","Content-Length":String((new TextEncoder).encode(o).length)},r);return a.delete("ETag"),a.delete("Last-Modified"),a.delete("Content-Encoding"),new Response(o,{status:e.status,statusText:e.statusText,headers:a})}function resolveEmail(e,s){if(s)try{const r=s(e);if(r)return r}catch{}const r=parseCookieFromRequest(e,"__unshared_email");if(r)return r}function resolveEmailWithBody(e,s,r){const t=resolveEmail(e,r);if(t)return t;const n=s.email;return"string"==typeof n&&n?n:void 0}function extractSessionIdFromRequest(e,s){if(s)try{const r=s(e);if(r)return r}catch{}return parseCookieFromRequest(e,"__unshared_sid")??"unknown"}function dispatchUserEvent(e,s,r,t,n,i){t.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&&s.update(n.userId,{isFlagged:e.data.analysis.is_user_flagged}),!e.success&&e.error?.retryAfter&&r.pause(1e3*e.error.retryAfter)}).catch(e=>{i&&i(e,{operation:"processUserEvent",userId:n.userId,emailAddress:n.emailAddress})})}async function fetchAndCacheVerdict(e,s,r,t,n,i,o){const a={};let d;n&&"unknown"!==n&&(a.deviceId=n),i&&(a.fingerprintId=i);const c=await Promise.race([e.checkUser(t,a),new Promise(e=>{d=setTimeout(()=>e(null),500)})]);if(clearTimeout(d),!c)return{isFlagged:!1,isVerified:!1,emailAddress:t,sessionId:o,cachedAt:0,ttl:0};const u=c.data?.is_user_flagged??!1;return s.set(r,{isFlagged:u,isVerified:!1,emailAddress:t,sessionId:o}),s.get(r)}async function handleSubmitFp(e,s,r,t){try{const n={full_hash:s.hash??"",fingerprint_id:s.stable_hash??"",timestamp:s.collected_at??(new Date).toISOString(),isIncognito:s.is_incognito??!1,components:s.components??{},version:s.version??"inline-1.0.0"};let i,o,a;try{const s=r.resolveUserId(e);s&&!isSentinelUserId(s)&&(i=s)}catch{}if(!i){const e="string"==typeof s.user_id?s.user_id:void 0;e&&!isSentinelUserId(e)&&(i=e)}if(!i){const s=parseCookieFromRequest(e,"__unshared_uid");s&&!isSentinelUserId(s)&&(i=s)}try{o=r.resolveEmailAddress?r.resolveEmailAddress(e):void 0}catch{}o=o??parseCookieFromRequest(e,"__unshared_email")??s.email??void 0;try{a=r.resolveSessionId?r.resolveSessionId(e):void 0}catch{}a=a??s.session_id??parseCookieFromRequest(e,"__unshared_sid");const d=extractClientIpFromRequest(e),c=e.headers.get("user-agent")??"";if(isBot(c))return jsonResponse(200,{success:!0},t);const u=(n.fingerprint_id&&n.fingerprint_id.length>0?n.fingerprint_id:void 0)??extractDeviceIdFromRequestOrUnknown(e,r.resolveDeviceId),l=n.fingerprint_id||void 0,p=n.full_hash||void 0,m=isSecureWebRequest(e)?"; Secure":"",f=[];if(p&&!parseCookieFromRequest(e,"__unshared_fingerprint_id")&&f.push(`__unshared_fingerprint_id=${encodeURIComponent(p)}; HttpOnly; Path=/; SameSite=Lax${m}`),l){const s=parseCookieFromRequest(e,"__unshared_fp_id");s&&s===l||f.push(`__unshared_fp_id=${encodeURIComponent(l)}; Path=/; SameSite=Lax; Max-Age=31536000${m}`)}let h;if(o&&!parseCookieFromRequest(e,"__unshared_email")&&f.push(`__unshared_email=${encodeURIComponent(o)}; HttpOnly; Path=/; SameSite=Lax${m}`),"string"==typeof s.event_type&&s.event_type)h=s.event_type;else{const s=e.headers.get("referer")??e.headers.get("referrer");let r="unknown";if(s)try{const e=new URL(s);r=(e.pathname||"/")+(e.search||"")}catch{}h=r}const _=e.headers.get("x-idempotency-key")||void 0,R=Date.now(),I=_?`${_}|${R}`:l&&i?`${l}|${i}|${h}|${R}`:void 0;i&&r.client.submitFingerprintEvent(n,{userId:i,emailAddress:o,sessionHash:a,eventType:h,ipAddress:d,userAgent:c,idempotencyKey:I}).catch(e=>{r.onError&&r.onError(e,{operation:"submitFingerprintEvent",userId:i,emailAddress:o})}),i&&o&&!r.rateLimitBackoff.isPaused()&&!r.dispatchDedupe.wasRecentlyDispatched(i,h)&&r.client.processUserEvent({eventType:h,userId:i,emailAddress:o,ipAddress:d,deviceId:u,fingerprintId:l,sessionHash:a??"unknown",userAgent:c}).then(e=>{e.success&&e.data?.analysis&&r.verdictCache.update(i,{isFlagged:e.data.analysis.is_user_flagged}),!e.success&&e.error?.retryAfter&&r.rateLimitBackoff.pause(1e3*e.error.retryAfter)}).catch(e=>{r.onError&&r.onError(e,{operation:"processUserEvent",userId:i,emailAddress:o})});const g={...t,"Content-Type":"application/json"},v=new Response(JSON.stringify({success:!0}),{status:200,headers:g});for(const e of f)v.headers.append("Set-Cookie",e);return v}catch{return jsonResponse(200,{success:!0},t)}}async function handleVerifyTriggerWeb(e,s,r,t){try{const n=resolveEmailWithBody(e,s??{},r.resolveEmailAddress);if(!n)return jsonResponse(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email is required"}},t);const i=extractDeviceIdFromRequestOrUnknown(e,r.resolveDeviceId),o=parseCookieFromRequest(e,"__unshared_fingerprint_id")||void 0,a=await r.client.triggerEmailVerification(n,i,{fingerprintId:o});return a.success?jsonResponse(200,{success:!0,data:a.data},t):jsonResponse(200,{success:!1,error:a.error??{code:"TRIGGER_FAILED",message:"Failed to send verification email"}},t)}catch(e){return r.onError&&r.onError(e,{operation:"verifyTrigger"}),jsonResponse(200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Failed to trigger verification"}},t)}}async function handleVerifyWeb(e,s,r,t){try{const n=resolveEmailWithBody(e,s??{},r.resolveEmailAddress),i=s?.code;if(!n||!i)return jsonResponse(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Email and code are required"}},t);const o=extractDeviceIdFromRequestOrUnknown(e,r.resolveDeviceId),a=parseCookieFromRequest(e,"__unshared_fingerprint_id")||void 0,d=await r.client.verify(n,o,i,{fingerprintId:a});if(d.success){const s=parseCookieFromRequest(e,"__unshared_uid");return s&&r.verdictCache.update(s,{isVerified:!0}),jsonResponse(200,{success:!0,data:{verified:!0}},t)}return jsonResponse(200,{success:!1,error:d.error??{code:"VERIFICATION_FAILED",message:"Verification failed"}},t)}catch(e){return r.onError&&r.onError(e,{operation:"verify"}),jsonResponse(200,{success:!1,error:{code:"INTERNAL_ERROR",message:"Verification failed"}},t)}}

package/dist/esm/web/submit-handler.d.mts

@@ -0,0 +1,27 @@
+import type { UnsharedClient } from '../client';
+import type { WebSubmitOptions } from './types';
+/**
+ * Web Standard equivalent of `createUnsharedMiddleware` from src/middleware.ts.
+ *
+ * Returns a handler `(request: Request) => Promise<Response>` suitable for
+ * Next.js App Router Route Handlers, Vercel Edge Functions, Cloudflare
+ * Workers, Deno Deploy, and any other Web Standard runtime.
+ *
+ * @example Next.js App Router
+ * ```typescript
+ * // app/unshared/submit-fingerprint-event/route.ts
+ * import { createWebSubmitHandler } from 'unshared-clientjs-sdk/web';
+ * import { UnsharedClient } from 'unshared-clientjs-sdk';
+ *
+ * const client = new UnsharedClient({ apiKey: '...', clientId: '...' });
+ * const handler = createWebSubmitHandler(client);
+ *
+ * export const POST = handler;
+ * export const OPTIONS = handler;
+ * ```
+ *
+ * **Error contract:** Never returns 5xx. Upstream failures return HTTP 200
+ * with `{ success: false, error: { code: "UPSTREAM_ERROR" } }`. Same contract
+ * as the Node.js middleware.
+ */
+export declare function createWebSubmitHandler(client: UnsharedClient, options?: WebSubmitOptions): (request: Request) => Promise<Response>;

package/dist/esm/web/submit-handler.mjs

@@ -0,0 +1 @@
+import{jsonResponse,emptyResponse,extractClientIpFromRequest}from"./web-helpers";export function createWebSubmitHandler(e,s){const{userIdExtractor:r,eventTypeExtractor:n,sessionIdExtractor:o,ipAddressExtractor:t,defaultEventType:c="browser_event",routePrefix:i="/unshared",corsOrigins:a}=s??{},d=`${i}/submit-fingerprint-event`,u=a?Array.isArray(a)?a:[a]:null;return async s=>{let i;try{i=new URL(s.url).pathname}catch{return jsonResponse(400,{success:!1,error:{code:"INVALID_URL",message:"Unable to parse request URL"}})}const a=u&&i===d?function(e){if(!u)return{};const s=e.headers.get("origin")??"",r=u.includes("*");return r||u.includes(s)?{"Access-Control-Allow-Origin":r?"*":s,"Access-Control-Allow-Methods":"POST, OPTIONS","Access-Control-Allow-Headers":"Content-Type, X-Idempotency-Key, X-Session-Id"}:{}}(s):{};if("OPTIONS"===s.method&&i===d)return emptyResponse(204,a);if("POST"!==s.method||i!==d)return jsonResponse(404,{success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}},a);try{let i;try{i=await s.json()}catch{return jsonResponse(400,{success:!1,error:{code:"BODY_PARSER_MISSING",message:"Request body is not valid JSON."}},a)}if(!(i&&i.hash&&i.stable_hash&&i.collected_at))return jsonResponse(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}},a);if(!s.headers.get("x-session-id"))return jsonResponse(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required header: X-Session-Id"}},a);const d={full_hash:i.hash,fingerprint_id:i.stable_hash,timestamp:i.collected_at,isIncognito:i.is_incognito??!1,components:i.components??{},version:i.version??"unknown"};let u,R,p,l;try{u=(r?r(s):void 0)??i.user_id}catch{u=i.user_id}if(!u)return jsonResponse(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}},a);try{R=(n?n(s):void 0)??i.event_type??c}catch{R=i.event_type??c}try{p=(o?o(s):void 0)??s.headers.get("x-session-id")??i.session_id}catch{p=s.headers.get("x-session-id")??i.session_id}const I=extractClientIpFromRequest(s);try{l=(t?t(s):void 0)??I}catch{l=I}const m=await e.submitFingerprintEvent(d,{userId:u,sessionHash:p,eventType:R,ipAddress:l});return m.success?jsonResponse(202,{success:!0,data:m.data},a):jsonResponse(200,{success:!1,error:{code:"UPSTREAM_ERROR",message:m.error?.message??"Upstream request failed"}},a)}catch(e){return jsonResponse(200,{success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Handler error"}},a)}}}