unshared-clientjs-sdk 2.0.0-rc.21 → 2.0.0-rc.23

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.21",
+  "version": "2.0.0-rc.23",
   "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": "2.0.0-rc.21"
+    "unshared-frontend-sdk": "2.0.0-rc.23"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",