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

package/dist/middleware/utils/device-id.d.ts

@@ -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/middleware/utils/device-id.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.extractDeviceId=extractDeviceId,exports.extractDeviceIdOrUndefined=extractDeviceIdOrUndefined;const cookies_1=require("./cookies");function extractDeviceId(e,t){return extractDeviceIdOrUndefined(e,t)??"unknown"}function extractDeviceIdOrUndefined(e,t){if(t)try{const r=t(e);if(r)return r}catch{}const r=e.headers["x-device-id"];if("string"==typeof r&&r)return r;return(0,cookies_1.parseCookie)(e,"__unshared_fp_id")||void 0}

package/dist/middleware/utils/flagged-response.d.ts

@@ -0,0 +1,5 @@
+export declare const ACCOUNT_FLAGGED_ERROR: "account_flagged";
+export declare function flaggedResponse(email: string): {
+    readonly error: "account_flagged";
+    readonly email: string;
+};

package/dist/middleware/utils/flagged-response.js

@@ -0,0 +1 @@
+"use strict";function flaggedResponse(e){return{error:exports.ACCOUNT_FLAGGED_ERROR,email:e}}Object.defineProperty(exports,"o",{value:!0}),exports.ACCOUNT_FLAGGED_ERROR=void 0,exports.flaggedResponse=flaggedResponse,exports.ACCOUNT_FLAGGED_ERROR="account_flagged";

package/dist/middleware/utils/http-helpers.d.ts

@@ -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/middleware/utils/http-helpers.js

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

package/dist/middleware/utils/include-path.d.ts

@@ -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/middleware/utils/include-path.js

@@ -0,0 +1 @@
+"use strict";function shouldIncludePath(e,t){return!t||t.some(t=>e.startsWith(t))}Object.defineProperty(exports,"t",{value:!0}),exports.shouldIncludePath=shouldIncludePath;

package/dist/middleware/utils/is-bot.d.ts

@@ -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/middleware/utils/is-bot.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.isBot=isBot;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");function isBot(e){return!!e&&BOT_RE.test(e)}

package/dist/middleware/utils/secure.d.ts

@@ -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/middleware/utils/secure.js

@@ -0,0 +1 @@
+"use strict";function isSecureRequest(e){return!!e.socket?.encrypted||"https"===e.headers["x-forwarded-proto"]}Object.defineProperty(exports,"t",{value:!0}),exports.isSecureRequest=isSecureRequest;

package/dist/middleware/utils/sentinel-user-id.d.ts

@@ -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/middleware/utils/sentinel-user-id.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.SENTINEL_STICKINESS_TTL_MS=void 0,exports.isSentinelUserId=isSentinelUserId;const SENTINEL_USER_IDS=new Set(["__pre_auth__","anonymous","guest","undefined","null"]);function isSentinelUserId(e){return"string"==typeof e&&SENTINEL_USER_IDS.has(e)}exports.SENTINEL_STICKINESS_TTL_MS=3e4;

package/dist/middleware/utils/skip-paths.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.shouldSkipPath=shouldSkipPath;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"];function shouldSkipPath(t,s){if(s)for(const o of s)if(t.startsWith(o))return!0;const o=t.lastIndexOf(".");if(-1!==o){const s=t.slice(o).toLowerCase().split("?")[0];if(STATIC_EXTENSIONS.has(s))return!0}for(const s of STATIC_PATH_PREFIXES)if(t.startsWith(s))return!0;return!1}
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.shouldSkipPath=shouldSkipPath;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"];function shouldSkipPath(t,s){if(s)for(const o of s)if(t.startsWith(o))return!0;const o=t.lastIndexOf(".");if(-1!==o){const s=t.slice(o).toLowerCase().split("?")[0];if(STATIC_EXTENSIONS.has(s))return!0}for(const s of STATIC_PATH_PREFIXES)if(t.startsWith(s))return!0;return!1}

package/dist/middleware/verdict-cache.d.ts

@@ -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/middleware/verdict-cache.js

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

package/dist/middleware.d.ts

@@ -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).
@@ -62,7 +65,7 @@ export declare function assertTrustProxy(app: Application): void;
  *
  * @example
  * ```typescript
- * import { createUnsharedMiddleware } from "@unshared-labs/sdk/middleware";
+ * import { createUnsharedMiddleware } from "unshared-clientjs-sdk";
  *
  * app.use(express.json());  // must come first
  * app.use(createUnsharedMiddleware(client, {
@@ -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/middleware.js

@@ -1 +1 @@
-"use strict";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.')}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()}}Object.defineProperty(exports,"t",{value:!0}),exports.assertTrustProxy=assertTrustProxy,exports.createUnsharedMiddleware=createUnsharedMiddleware;
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.assertTrustProxy=assertTrustProxy,exports.createUnsharedMiddleware=createUnsharedMiddleware;const http_helpers_1=require("./middleware/utils/http-helpers");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.')}function createUnsharedMiddleware(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:o,ipAddressExtractor:n,defaultEventType:i="browser_event",routePrefix:d="/unshared",corsOrigins:c}=r??{},a=`${d}/submit-fingerprint-event`,h=c?Array.isArray(c)?c:[c]:null;return async(r,d,c)=>{const u=(0,http_helpers_1.getRequestPath)(r.url);if(h&&u===a){const e=r.headers.origin??"",s=h.includes("*");if((s||h.includes(e))&&(d.setHeader("Access-Control-Allow-Origin",s?"*":e),d.setHeader("Access-Control-Allow-Methods","POST, OPTIONS"),d.setHeader("Access-Control-Allow-Headers","Content-Type, X-Idempotency-Key, X-Session-Id")),"OPTIONS"===r.method)return void(0,http_helpers_1.sendEmpty)(d,204)}if("POST"===r.method&&u===a)try{if(void 0===r.body)return void(0,http_helpers_1.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=r.body??{};if(!c.hash||!c.stable_hash||!c.collected_at)return void(0,http_helpers_1.sendJson)(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});if(!r.headers["x-session-id"])return void(0,http_helpers_1.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 h,u,l,p;try{h=(s?s(r):void 0)??c.user_id}catch{h=c.user_id}if(r.body&&"object"==typeof r.body&&"user_id"in r.body&&delete r.body.user_id,!h)return void(0,http_helpers_1.sendJson)(d,400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}});try{u=(t?t(r):void 0)??c.event_type??i}catch{u=c.event_type??i}try{l=(o?o(r):void 0)??r.headers["x-session-id"]?.toString()??c.session_id}catch{l=r.headers["x-session-id"]?.toString()??c.session_id}const _=r.ip??r.socket?.remoteAddress??"";try{p=(n?n(r):void 0)??_}catch{p=_}const f=await e.submitFingerprintEvent(a,{userId:h,sessionHash:l,eventType:u,ipAddress:p});if(!f.success)return void(0,http_helpers_1.sendJson)(d,200,{success:!1,error:{code:"UPSTREAM_ERROR",message:f.error?.message??"Upstream request failed"}});(0,http_helpers_1.sendJson)(d,202,{success:!0,data:f.data})}catch(e){(0,http_helpers_1.sendJson)(d,200,{success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else c()}}

package/dist/types.d.ts

@@ -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/types.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0});

package/dist/web/index.d.ts

@@ -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/web/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.VerdictCache=exports.createWebProtectionMiddleware=exports.createWebSubmitHandler=void 0;var submit_handler_1=require("./submit-handler");Object.defineProperty(exports,"createWebSubmitHandler",{enumerable:!0,get:function(){return submit_handler_1.createWebSubmitHandler}});var protection_handler_1=require("./protection-handler");Object.defineProperty(exports,"createWebProtectionMiddleware",{enumerable:!0,get:function(){return protection_handler_1.createWebProtectionMiddleware}});var verdict_cache_1=require("../middleware/verdict-cache");Object.defineProperty(exports,"VerdictCache",{enumerable:!0,get:function(){return verdict_cache_1.VerdictCache}});

package/dist/web/protection-handler.d.ts

@@ -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/web/protection-handler.js

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

package/dist/web/submit-handler.d.ts

@@ -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/web/submit-handler.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.createWebSubmitHandler=createWebSubmitHandler;const web_helpers_1=require("./web-helpers");function createWebSubmitHandler(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:n,ipAddressExtractor:o,defaultEventType:c="browser_event",routePrefix:i="/unshared",corsOrigins:a}=r??{},d=`${i}/submit-fingerprint-event`,u=a?Array.isArray(a)?a:[a]:null;return async r=>{let i;try{i=new URL(r.url).pathname}catch{return(0,web_helpers_1.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 r=e.headers.get("origin")??"",s=u.includes("*");return s||u.includes(r)?{"Access-Control-Allow-Origin":s?"*":r,"Access-Control-Allow-Methods":"POST, OPTIONS","Access-Control-Allow-Headers":"Content-Type, X-Idempotency-Key, X-Session-Id"}:{}}(r):{};if("OPTIONS"===r.method&&i===d)return(0,web_helpers_1.emptyResponse)(204,a);if("POST"!==r.method||i!==d)return(0,web_helpers_1.jsonResponse)(404,{success:!1,error:{code:"NOT_FOUND",message:"Unknown route"}},a);try{let i;try{i=await r.json()}catch{return(0,web_helpers_1.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(0,web_helpers_1.jsonResponse)(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}},a);if(!r.headers.get("x-session-id"))return(0,web_helpers_1.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,l,_,h;try{u=(s?s(r):void 0)??i.user_id}catch{u=i.user_id}if(!u)return(0,web_helpers_1.jsonResponse)(400,{success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required field: user_id"}},a);try{l=(t?t(r):void 0)??i.event_type??c}catch{l=i.event_type??c}try{_=(n?n(r):void 0)??r.headers.get("x-session-id")??i.session_id}catch{_=r.headers.get("x-session-id")??i.session_id}const p=(0,web_helpers_1.extractClientIpFromRequest)(r);try{h=(o?o(r):void 0)??p}catch{h=p}const b=await e.submitFingerprintEvent(d,{userId:u,sessionHash:_,eventType:l,ipAddress:h});return b.success?(0,web_helpers_1.jsonResponse)(202,{success:!0,data:b.data},a):(0,web_helpers_1.jsonResponse)(200,{success:!1,error:{code:"UPSTREAM_ERROR",message:b.error?.message??"Upstream request failed"}},a)}catch(e){return(0,web_helpers_1.jsonResponse)(200,{success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Handler error"}},a)}}}

package/dist/web/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Web Standard Request/Response handler types for serverless/edge environments.
+ *
+ * These types use the global `Request` and `Response` from the Fetch API,
+ * available in: Next.js App Router Route Handlers, Vercel Edge Functions,
+ * Cloudflare Workers, Deno Deploy, Bun, and Node.js 18+.
+ *
+ * The DOM lib reference above scopes the Fetch API globals to this file only,
+ * avoiding `window`/`document` pollution in the Node.js middleware code.
+ */
+import type { Verdict } from '../middleware/verdict-cache';
+/** A downstream handler that returns a Response. */
+export type WebHandler = (request: Request) => Response | Promise<Response>;
+/** Middleware that wraps a downstream handler, optionally intercepting the response. */
+export type WebMiddleware = (request: Request, next: WebHandler) => Response | Promise<Response>;
+export interface WebSubmitOptions {
+    /** Override userId extractor. Falls back to body.user_id. */
+    userIdExtractor?: (req: Request) => string | undefined;
+    /** Override eventType extractor. Falls back to body.event_type. */
+    eventTypeExtractor?: (req: Request) => string | undefined;
+    /** Override sessionId extractor. Falls back to X-Session-Id header, then body.session_id. */
+    sessionIdExtractor?: (req: Request) => string | undefined;
+    /** Override IP address extractor. Falls back to CF-Connecting-IP / X-Real-IP / X-Forwarded-For headers. */
+    ipAddressExtractor?: (req: Request) => string | undefined;
+    /** Default event type when none is extractable. @default "browser_event" */
+    defaultEventType?: string;
+    /**
+     * Route prefix the handler responds under.
+     * @default "/unshared"
+     */
+    routePrefix?: string;
+    /**
+     * Allowed CORS origins for the fingerprint route.
+     * Use `"*"` to allow all origins, or pass a specific origin / array of origins.
+     * The handler handles OPTIONS preflight automatically when this is set.
+     */
+    corsOrigins?: string | string[];
+}
+export interface WebProtectionConfig {
+    /**
+     * Required. Resolves the current user's ID from the request.
+     * Return undefined for anonymous/logged-out visitors.
+     */
+    userId: (req: Request) => string | undefined;
+    /**
+     * Resolves the current user's email address from the request.
+     * Falls back to HttpOnly cookie → request body when not configured.
+     */
+    emailAddress?: (req: Request) => string | undefined;
+    /** Route prefix for internal routes. @default "/__unshared" */
+    routePrefix?: string;
+    /** Allowed CORS origins for /__unshared/* routes. */
+    corsOrigins?: string | string[];
+    /** Verdict cache TTL in ms. @default 60000 */
+    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[];
+    /** Resolves a custom session ID. Falls back to __unshared_sid cookie. */
+    sessionId?: (req: Request) => string | undefined;
+    /**
+     * Resolves a device ID from the request.
+     * Falls back to X-Device-Id header → __unshared_fp_id cookie.
+     */
+    deviceId?: (req: Request) => string | undefined;
+    /**
+     * Inline JavaScript bundle for the frontend SDK, served at /__unshared/fp.js.
+     *
+     * In Node.js environments the middleware reads this from node_modules via
+     * `require.resolve('unshared-frontend-sdk/dist/index.umd.js')`. Edge runtimes
+     * do not have filesystem access, so the bundle must be passed as a string
+     * (typically imported via a bundler):
+     *
+     * ```typescript
+     * import fingerprintSdkBundle from 'unshared-frontend-sdk/dist/index.umd.js?raw';
+     * createWebProtectionMiddleware(client, { ..., fingerprintSdkBundle });
+     * ```
+     *
+     * If omitted, the fp.js route returns 404. The inline script degrades
+     * gracefully — the cached-fingerprint path still works.
+     */
+    fingerprintSdkBundle?: string;
+    /**
+     * Called when a flagged, unverified user makes a request.
+     *
+     * Return a `Response` to block/redirect, or `null` to pass through (injection
+     * still happens). Exceptions are caught — the request passes through on error.
+     *
+     * This differs from the Node.js middleware: in Web Standard environments
+     * Response objects are immutable, so the callback returns a new Response
+     * rather than mutating an existing one.
+     */
+    onFlagged?: (context: {
+        userId: string;
+        emailAddress: string;
+        verdict: Verdict;
+        request: Request;
+    }) => Response | Promise<Response> | null;
+    /**
+     * 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.
+     */
+    onError?: (error: unknown, context: {
+        operation: 'processUserEvent' | 'submitFingerprintEvent' | 'checkUser' | 'verifyTrigger' | 'verify';
+        userId?: string;
+        emailAddress?: string;
+    }) => void;
+}

package/dist/web/types.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0});

package/dist/web/web-helpers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Thin adapter functions that bridge Web Standard `Request`/`Response` to the
+ * data shapes the rest of the SDK expects. These mirror the Node.js
+ * `src/middleware/utils/*` functions but read from Web Standard Headers
+ * instead of Node.js `req.headers` objects.
+ */
+/**
+ * Reads a single cookie value from the raw Cookie header.
+ * Mirrors `parseCookie(req, name)` in src/middleware/utils/cookies.ts.
+ */
+export declare function parseCookieFromRequest(request: Request, name: string): string | undefined;
+/**
+ * Extract the real client IP from proxy headers. Web Standard has no
+ * equivalent of `req.ip` or `req.socket.remoteAddress`, so we rely entirely
+ * on standard proxy headers (which all edge platforms populate).
+ *
+ * Priority: CF-Connecting-IP → X-Real-IP → X-Forwarded-For (first entry).
+ */
+export declare function extractClientIpFromRequest(request: Request): string;
+/**
+ * Resolves device ID from: custom resolver → X-Device-Id header → __unshared_fp_id cookie.
+ * Mirrors `extractDeviceIdOrUndefined` in src/middleware/utils/device-id.ts.
+ */
+export declare function extractDeviceIdFromRequest(request: Request, resolveDeviceId?: (req: Request) => string | undefined): string | undefined;
+/** Same as extractDeviceIdFromRequest but returns "unknown" when nothing is available. */
+export declare function extractDeviceIdFromRequestOrUnknown(request: Request, resolveDeviceId?: (req: Request) => string | undefined): string;
+/**
+ * Returns true if the request arrived over HTTPS.
+ *
+ * Web Standard has no `socket.encrypted`, so this checks:
+ * 1. The `x-forwarded-proto` header (set by reverse proxies / load balancers)
+ * 2. The URL protocol (for direct HTTPS requests)
+ */
+export declare function isSecureWebRequest(request: Request): boolean;
+/**
+ * Build a JSON response. Mirrors `sendJson(res, status, data)` in
+ * src/middleware/utils/http-helpers.ts, but returns a new Response instead
+ * of mutating one.
+ */
+export declare function jsonResponse(statusCode: number, data: unknown, extraHeaders?: HeadersInit): Response;
+/** Build a status-only response with no body. */
+export declare function emptyResponse(statusCode: number, extraHeaders?: HeadersInit): Response;
+/** Build a raw-body response (for the fp.js bundle). */
+export declare function bodyResponse(statusCode: number, body: string, extraHeaders?: HeadersInit): Response;
+/**
+ * Append a Set-Cookie header to a Headers object. Web Standard `Headers`
+ * supports multiple Set-Cookie values via `.append()`.
+ */
+export declare function appendCookieToHeaders(headers: Headers, cookieValue: string): void;
+/**
+ * Merge a downstream Response's headers with additional Set-Cookie entries
+ * and overrides. Preserves multiple Set-Cookie values from the source
+ * response via `getSetCookie()` (Node 20+, all modern edge runtimes).
+ */
+export declare function mergeResponseHeaders(source: Headers, overrides?: Record<string, string>, extraCookies?: string[]): Headers;

package/dist/web/web-helpers.js

@@ -0,0 +1 @@
+"use strict";function parseCookieFromRequest(e,t){const o=e.headers.get("cookie");if(!o)return;const n=o.match(new RegExp(`(?:^|; )${t}=([^;]*)`));return n?decodeURIComponent(n[1]):void 0}function extractClientIpFromRequest(e){const t=e.headers.get("cf-connecting-ip");if(t)return t;const o=e.headers.get("x-real-ip");if(o)return o;const n=e.headers.get("x-forwarded-for");if(n){const e=n.split(",")[0]?.trim();if(e)return e}return""}function extractDeviceIdFromRequest(e,t){if(t)try{const o=t(e);if(o)return o}catch{}const o=e.headers.get("x-device-id");if(o)return o;return parseCookieFromRequest(e,"__unshared_fp_id")||void 0}function extractDeviceIdFromRequestOrUnknown(e,t){return extractDeviceIdFromRequest(e,t)??"unknown"}function isSecureWebRequest(e){if("https"===e.headers.get("x-forwarded-proto"))return!0;try{return"https:"===new URL(e.url).protocol}catch{return!1}}function jsonResponse(e,t,o){const n=new Headers(o);return n.set("Content-Type","application/json"),new Response(JSON.stringify(t),{status:e,headers:n})}function emptyResponse(e,t){return new Response(null,{status:e,headers:new Headers(t)})}function bodyResponse(e,t,o){return new Response(t,{status:e,headers:new Headers(o)})}function appendCookieToHeaders(e,t){e.append("Set-Cookie",t)}function mergeResponseHeaders(e,t,o){const n=new Headers;e.forEach((e,t)=>{"set-cookie"!==t.toLowerCase()&&n.set(t,e)});const r="function"==typeof e.getSetCookie?e.getSetCookie():[];for(const e of r)n.append("Set-Cookie",e);if(o)for(const e of o)n.append("Set-Cookie",e);if(t)for(const[e,o]of Object.entries(t))n.set(e,o);return n}Object.defineProperty(exports,"t",{value:!0}),exports.parseCookieFromRequest=parseCookieFromRequest,exports.extractClientIpFromRequest=extractClientIpFromRequest,exports.extractDeviceIdFromRequest=extractDeviceIdFromRequest,exports.extractDeviceIdFromRequestOrUnknown=extractDeviceIdFromRequestOrUnknown,exports.isSecureWebRequest=isSecureWebRequest,exports.jsonResponse=jsonResponse,exports.emptyResponse=emptyResponse,exports.bodyResponse=bodyResponse,exports.appendCookieToHeaders=appendCookieToHeaders,exports.mergeResponseHeaders=mergeResponseHeaders;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unshared-clientjs-sdk",
-  "version": "2.0.0-rc.9",
+  "version": "2.0.1",
   "description": "Server-side Node.js SDK for the Unshared Labs V2 API",
   "main": "dist/index.js",
   "module": "dist/esm/index.mjs",
@@ -38,6 +38,11 @@
       "import": "./dist/esm/middleware/index.mjs",
       "require": "./dist/middleware/index.js",
       "types": "./dist/middleware/index.d.ts"
+    },
+    "./web": {
+      "import": "./dist/esm/web/index.mjs",
+      "require": "./dist/web/index.js",
+      "types": "./dist/web/index.d.ts"
     }
   },
   "engines": {
@@ -46,16 +51,8 @@
   "keywords": [],
   "author": "",
   "license": "MIT",
-  "peerDependencies": {
-    "@types/express": ">=4"
-  },
-  "peerDependenciesMeta": {
-    "@types/express": {
-      "optional": true
-    }
-  },
   "dependencies": {
-    "unshared-frontend-sdk": "file:../frontend-sdk"
+    "unshared-frontend-sdk": "2.0.1"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",