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

package/README.md

@@ -1,47 +1,26 @@
-# @unshared-labs/sdk
+# unshared-clientjs-sdk
 
-Server-side Node.js SDK for the Unshared Labs V2 API. Handles authentication, AES-256-GCM field encryption, retry logic, and structured error responses.
-
-**Keep the API key server-side — never expose it in browser code.**
+Server-side Node.js SDK for [Unshared Labs](https://unsharedlabs.com) — detect account sharing, analyze user events for fraud, and run email verification flows.
 
 ---
 
-## Installation
+## Install
 
 ```bash
-npm install @unshared-labs/sdk
+npm install unshared-clientjs-sdk
 ```
 
-Requires Node.js ≥ 18.
+**Requires Node.js 18+**
 
 ---
 
 ## Quick Start
 
 ```typescript
-import { UnsharedLabsClient } from '@unshared-labs/sdk';
+import { UnsharedLabsClient } from 'unshared-clientjs-sdk';
 
 const client = new UnsharedLabsClient({
-  apiKey: process.env.UNSHARED_API_KEY!,
-});
-```
-
-### CommonJS
-
-```javascript
-const { UnsharedLabsClient } = require('@unshared-labs/sdk');
-```
-
----
-
-## Configuration
-
-```typescript
-const client = new UnsharedLabsClient({
-  apiKey: 'sk_live_…',        // required — keep server-side
-  baseUrl: 'https://…',       // optional, default: https://api-ingress.unsharedlabs.com
-  timeout: 10_000,            // optional, ms — default: 10 s
-  maxRetries: 3,              // optional — retries on 5xx / network errors
+  apiKey: process.env.UNSHARED_API_KEY, // usk_…
 });
 ```
 
@@ -49,131 +28,150 @@ const client = new UnsharedLabsClient({
 
 ## Methods
 
-### `submitFingerprintEvent(fingerprint, opts?)`
+### `processUserEvent(params)`
 
-Submit a browser fingerprint collected by `@unshared-labs/frontend-fingerprint`. Returns 202 Accepted; the event is stored asynchronously.
+Record a user event and get a fraud signal back. Call this on login, signup, or any high-value action.
 
 ```typescript
-const result = await client.submitFingerprintEvent(fingerprintData, {
-  userId: 'u_123',
-  sessionHash: 'sess_abc',
-  eventType: 'login',
+const result = await client.processUserEvent({
+  eventType:    'login',
+  userId:       'user_123',
+  emailAddress: 'user@example.com',
+  deviceId:     'device_abc',
+  sessionHash:  'session_xyz',
+  ipAddress:    '1.2.3.4',         // plaintext — not encrypted
+  userAgent:    req.headers['user-agent'],
 });
-// result.data: { hash, stable_hash, collected_at, version }
+
+if (result.success && result.data?.analysis.is_user_flagged) {
+  // Block or challenge the user
+}
 ```
 
-An `X-Idempotency-Key` is sent automatically. Retries with the same key are deduplicated at the backend.
+**Fields encrypted before sending:** `emailAddress`, `deviceId`
 
-### `processUserEvent(params)`
+---
+
+### `checkUser(emailAddress, deviceId)`
 
-Record a user event and receive naughty-list analysis. `emailAddress` and `deviceId` are AES-256-GCM encrypted before sending.
+Quick check to see if a user is flagged. Useful in middleware or route guards.
 
 ```typescript
-const result = await client.processUserEvent({
-  eventType: 'login',
-  userId: 'u_123',
-  ipAddress: req.ip,
-  deviceId: 'device-uuid',
-  sessionHash: 'sess_abc',
-  userAgent: req.headers['user-agent'] ?? '',
-  emailAddress: 'user@example.com',
-  subscriptionStatus: 'paid',
-});
-// result.data: { event: { … }, analysis: { status, is_user_flagged } }
+const result = await client.checkUser('user@example.com', 'device_abc');
+
+if (result.data?.is_user_flagged) {
+  // Deny access
+}
 ```
 
-> **Note:** This endpoint has no server-side idempotency. Retries may insert duplicate rows.
+> **Safe default:** Returns `{ is_user_flagged: false }` on any failure (network error, outage). A backend outage will never accidentally block a legitimate user.
 
-### `checkUser(emailAddress, deviceId)`
+---
 
-Check if a user is flagged in the naughty list. Always returns `{ is_user_flagged: false }` on any failure — a backend outage never blocks a legitimate user.
+### `triggerEmailVerification(emailAddress, deviceId)`
+
+Send a 6-digit verification code to the user's email.
 
 ```typescript
-const result = await client.checkUser('user@example.com', 'device-uuid');
-if (result.data?.is_user_flagged) { /* … */ }
+await client.triggerEmailVerification('user@example.com', 'device_abc');
 ```
 
-### `triggerEmailVerification(emailAddress, deviceId)`
+---
 
-Send a 6-digit verification code. Rate-limited to one request per `(email_address, device_id)` pair per 2 minutes.
+### `verify(emailAddress, deviceId, code)`
+
+Validate the code the user submitted.
 
 ```typescript
-const result = await client.triggerEmailVerification('user@example.com', 'device-uuid');
-if (!result.success && result.error?.code === 'RATE_LIMIT_EXCEEDED') {
-  const waitSeconds = result.error.retryAfter ?? result.error.details?.retry_after_seconds;
-  // back off for waitSeconds
+const result = await client.verify('user@example.com', 'device_abc', '123456');
+
+if (!result.success) {
+  if (result.error?.code === 'VERIFICATION_FAILED') {
+    // Wrong or expired code — ask user to retry
+  } else {
+    // Transport error (DELIVERY_FAILED) — retry or show generic error
+  }
+} else {
+  // Verified — success: true means the code was correct
 }
 ```
 
-**Pre-condition:** sender settings must be configured via `createSender` + `validateSender` before this will succeed.
+---
 
-### `verify(emailAddress, deviceId, code)`
+### `submitFingerprintEvent(fingerprint, opts?)`
 
-Verify the 6-digit code entered by the user. `success: true` with `verified: false` means the code was wrong — not a transport error.
+Submit a browser fingerprint collected by `unshared-frontend-sdk`. Typically called by the middleware — you usually won't call this directly.
 
 ```typescript
-const result = await client.verify('user@example.com', 'device-uuid', '123456');
-if (result.data?.verified) { /* proceed */ }
-else { /* result.data.reason: 'not_found' | 'code_mismatch' | 'code_expired' */ }
+await client.submitFingerprintEvent(fingerprint, {
+  userId:      'user_123',
+  sessionHash: 'session_xyz',
+  eventType:   'page_view',
+});
 ```
 
 ---
 
-## Express Middleware (Browser Proxy)
+## Express Middleware
 
-Mount this to handle fingerprint events forwarded from `@unshared-labs/frontend-fingerprint`:
+The middleware adds a proxy route (`POST /unshared/submit-fingerprint-event`) that the browser SDK calls. It handles forwarding fingerprints to Unshared Labs and attaching your API key.
 
 ```typescript
-import { createUnsharedMiddleware } from '@unshared-labs/sdk/middleware';
+import { createUnsharedMiddleware } from 'unshared-clientjs-sdk/middleware';
+
+// express.json() must come before this middleware
+app.use(express.json());
 
 app.use(createUnsharedMiddleware(client, {
-  userIdExtractor: (req) => req.user?.id,
-  eventTypeExtractor: (req) => req.body.event_type,
-  routePrefix: '/unshared',  // default
+  userIdExtractor: (req) => req.user?.id, // attach logged-in user
 }));
 ```
 
-The middleware:
-- Handles `POST /unshared/submit-fingerprint-event`
-- Passes `next()` for all other routes
-- Never returns 5xx to the browser — upstream errors become `HTTP 200 { success: false }`
+**Prerequisites:**
+- Mount `express.json()` before the middleware
+- `user_id` is automatically removed from `req.body` after being read — downstream logging won't capture it
 
----
+**Options:**
 
-## Error Handling
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `userIdExtractor` | `(req) => string \| undefined` | — | Pull user ID from your auth session |
+| `eventTypeExtractor` | `(req) => string \| undefined` | — | Override event type |
+| `sessionIdExtractor` | `(req) => string \| undefined` | — | Override session ID |
+| `defaultEventType` | `string` | `"browser_event"` | Fallback event type |
+| `routePrefix` | `string` | `"/unshared"` | Route mount prefix |
+| `corsOrigins` | `string \| string[]` | — | Allowed CORS origins; handles OPTIONS preflight automatically |
 
-All methods return `ApiResult<T>`:
+---
+
+## Configuration
 
 ```typescript
-interface ApiResult<T> {
-  success: boolean;
-  data?: T;
-  error?: {
-    code: string;
-    message: string;
-    details?: Record<string, unknown>;
-    retryAfter?: number; // seconds — present on 429 RATE_LIMIT_EXCEEDED
-  };
-  status: number; // HTTP status, 0 for network errors
-}
+new UnsharedLabsClient({
+  apiKey:     'usk_…',                               // required
+  baseUrl:    'https://api-ingress.unsharedlabs.com', // optional
+  timeout:    10_000,                                 // optional, ms
+  maxRetries: 3,                                      // optional
+});
 ```
 
-- **4xx** — returned immediately, not retried
-- **5xx / network** — retried up to `maxRetries` with exponential backoff (base 1 s, ±25% jitter)
-- `triggerEmailVerification` and `verify` map 5xx / network errors to `{ code: 'DELIVERY_FAILED' }`
-
-See [Appendix A of the spec](../V2_CLIENT_SDK_SPEC.md) for the full error code list.
-
 ---
 
-## Encryption
+## Response shape
+
+All methods return `ApiResult<T>`:
 
-`emailAddress`, `deviceId`, and `code` are encrypted client-side before transmission using AES-256-GCM with a key derived from `SHA256(apiKey)`. Wire format: `<base64(iv)>:<base64(authTag)>:<base64(ciphertext)>` (colon-separated, standard Base64). The backend decrypts with `DecryptSDKField` in `lib/crypto.go`.
+```typescript
+{
+  success: boolean;
+  data?:   T;
+  error?:  { code: string; message: string; retryAfter?: number };
+  status:  number; // HTTP status code
+}
+```
 
 ---
 
-## Environment Variables
+## Security
 
-```bash
-UNSHARED_API_KEY=sk_live_…
-```
+All PII is encrypted with **AES-256-GCM** before leaving your server. The encryption key is derived from your API key with SHA-256. Your API key is sent as the `X-API-Key` header — never in a URL or browser context.

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
 export interface UnsharedLabsClientConfig {
     /**
      * Secret API key. Must be kept server-side.
-     * Format: sk_live_… or sk_test_…
+     * Format: usk_…
      */
     apiKey: string;
     /**
@@ -40,8 +40,14 @@ export interface ApiResult<T = unknown> {
 }
 export interface SubmitFingerprintOptions {
     userId?: string;
+    /** SDK encrypts before sending. */
+    emailAddress?: string;
     sessionHash?: string;
     eventType?: string;
+    /** SDK encrypts before sending. */
+    ipAddress?: string;
+    /** SDK encrypts before sending. */
+    userAgent?: string;
 }
 export interface SubmitFingerprintResult {
     hash: string;
@@ -52,15 +58,19 @@ export interface SubmitFingerprintResult {
 }
 export interface ProcessUserEventParams {
     eventType: string;
+    /** SDK encrypts before sending. */
     userId: string;
-    /** Plaintext — SDK does not encrypt this field. */
+    /** SDK encrypts before sending. */
     ipAddress: string;
     /** SDK encrypts before sending. */
     deviceId: string;
     sessionHash: string;
+    /** SDK encrypts before sending. */
     userAgent: string;
     /** SDK encrypts before sending. */
     emailAddress: string;
+    /** SDK encrypts before sending. */
+    fingerprintId?: string;
     subscriptionStatus?: string | null;
     eventDetails?: Record<string, unknown> | null;
 }
@@ -92,6 +102,22 @@ export interface VerifyResult {
     verified: boolean;
     reason?: 'not_found' | 'code_mismatch' | 'code_expired';
 }
+export interface VerificationFlowStep {
+    type: 'message' | 'email_input' | 'otp_input' | 'support_link';
+    title: string;
+    body: string;
+    buttonText?: string;
+    url?: string;
+}
+export interface VerificationFlowConfigResult {
+    steps: VerificationFlowStep[];
+    branding?: {
+        companyName?: string;
+        logoUrl?: string;
+        primaryColor?: string;
+        supportEmail?: string;
+    };
+}
 export declare class UnsharedLabsClient {
     private readonly _apiKey;
     private readonly _baseUrl;
@@ -131,28 +157,47 @@ export declare class UnsharedLabsClient {
      * through your infrastructure metrics, not through this method's return value.
      */
     checkUser(emailAddress: string, deviceId: string): Promise<ApiResult<CheckUserResult>>;
+    checkUser(emailAddress: string, opts: {
+        deviceId?: string;
+        fingerprintId?: string;
+    }): Promise<ApiResult<CheckUserResult>>;
     /**
      * Send a 6-digit verification code to the user's email address.
      * Maps to: POST /v2/trigger-email-verification
      */
-    triggerEmailVerification(emailAddress: string, deviceId: string): Promise<ApiResult<TriggerEmailVerificationResult>>;
+    triggerEmailVerification(emailAddress: string, deviceId: string, opts?: {
+        fingerprintId?: string;
+    }): Promise<ApiResult<TriggerEmailVerificationResult>>;
     /**
      * Verify a 6-digit code submitted by the user.
      * Maps to: POST /v2/verify
      *
-     * **Important:** `result.success` is `true` even when `result.data.verified`
-     * is `false`. A `false` verified result means the code was wrong or expired —
-     * not a transport failure. Always check `result.data.verified` explicitly:
+     * `result.success` reliably indicates whether verification succeeded:
+     * - `success: true`  → code was correct, user is verified
+     * - `success: false, error.code: "VERIFICATION_FAILED"` → wrong or expired code
+     * - `success: false, error.code: "DELIVERY_FAILED"` → network/server error
      *
      * ```typescript
      * const result = await client.verify(email, deviceId, code);
-     * if (!result.success) { /* transport/infra error *\/ }
-     * else if (!result.data?.verified) { /* wrong or expired code *\/ }
-     * else { /* verified *\/ }
+     * if (!result.success) {
+     *   if (result.error?.code === 'VERIFICATION_FAILED') { /* bad code *\/ }
+     *   else { /* transport error *\/ }
+     * } else { /* verified *\/ }
      * ```
+     */
+    verify(emailAddress: string, deviceId: string, code: string, opts?: {
+        fingerprintId?: string;
+    }): Promise<ApiResult<VerifyResult>>;
+    /**
+     * Fetch the verification flow configuration for this company.
+     * Maps to: GET /v2/verification-flow-config
+     *
+     * Returns the flow steps and branding configured by the Unshared Labs
+     * team for this company. The middleware uses this to render the
+     * verification overlay.
      *
-     * On network or 5xx errors, returns `{ success: false, error: { code: "DELIVERY_FAILED" } }`.
-     * On 4xx (e.g. rate limit), the server error is returned as-is.
+     * Returns `null` on any failure (network error, 4xx, 5xx) so the
+     * middleware can fall back to the default flow.
      */
-    verify(emailAddress: string, deviceId: string, code: string): Promise<ApiResult<VerifyResult>>;
+    getVerificationFlowConfig(): Promise<VerificationFlowConfigResult | null>;
 }

package/dist/client.js

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

package/dist/esm/client.d.mts

@@ -2,7 +2,7 @@ import type { FingerprintWireFormat } from '@unshared-labs/shared-types';
 export interface UnsharedLabsClientConfig {
     /**
      * Secret API key. Must be kept server-side.
-     * Format: sk_live_… or sk_test_…
+     * Format: usk_…
      */
     apiKey: string;
     /**
@@ -40,8 +40,14 @@ export interface ApiResult<T = unknown> {
 }
 export interface SubmitFingerprintOptions {
     userId?: string;
+    /** SDK encrypts before sending. */
+    emailAddress?: string;
     sessionHash?: string;
     eventType?: string;
+    /** SDK encrypts before sending. */
+    ipAddress?: string;
+    /** SDK encrypts before sending. */
+    userAgent?: string;
 }
 export interface SubmitFingerprintResult {
     hash: string;
@@ -52,15 +58,19 @@ export interface SubmitFingerprintResult {
 }
 export interface ProcessUserEventParams {
     eventType: string;
+    /** SDK encrypts before sending. */
     userId: string;
-    /** Plaintext — SDK does not encrypt this field. */
+    /** SDK encrypts before sending. */
     ipAddress: string;
     /** SDK encrypts before sending. */
     deviceId: string;
     sessionHash: string;
+    /** SDK encrypts before sending. */
     userAgent: string;
     /** SDK encrypts before sending. */
     emailAddress: string;
+    /** SDK encrypts before sending. */
+    fingerprintId?: string;
     subscriptionStatus?: string | null;
     eventDetails?: Record<string, unknown> | null;
 }
@@ -92,6 +102,22 @@ export interface VerifyResult {
     verified: boolean;
     reason?: 'not_found' | 'code_mismatch' | 'code_expired';
 }
+export interface VerificationFlowStep {
+    type: 'message' | 'email_input' | 'otp_input' | 'support_link';
+    title: string;
+    body: string;
+    buttonText?: string;
+    url?: string;
+}
+export interface VerificationFlowConfigResult {
+    steps: VerificationFlowStep[];
+    branding?: {
+        companyName?: string;
+        logoUrl?: string;
+        primaryColor?: string;
+        supportEmail?: string;
+    };
+}
 export declare class UnsharedLabsClient {
     private readonly _apiKey;
     private readonly _baseUrl;
@@ -131,28 +157,47 @@ export declare class UnsharedLabsClient {
      * through your infrastructure metrics, not through this method's return value.
      */
     checkUser(emailAddress: string, deviceId: string): Promise<ApiResult<CheckUserResult>>;
+    checkUser(emailAddress: string, opts: {
+        deviceId?: string;
+        fingerprintId?: string;
+    }): Promise<ApiResult<CheckUserResult>>;
     /**
      * Send a 6-digit verification code to the user's email address.
      * Maps to: POST /v2/trigger-email-verification
      */
-    triggerEmailVerification(emailAddress: string, deviceId: string): Promise<ApiResult<TriggerEmailVerificationResult>>;
+    triggerEmailVerification(emailAddress: string, deviceId: string, opts?: {
+        fingerprintId?: string;
+    }): Promise<ApiResult<TriggerEmailVerificationResult>>;
     /**
      * Verify a 6-digit code submitted by the user.
      * Maps to: POST /v2/verify
      *
-     * **Important:** `result.success` is `true` even when `result.data.verified`
-     * is `false`. A `false` verified result means the code was wrong or expired —
-     * not a transport failure. Always check `result.data.verified` explicitly:
+     * `result.success` reliably indicates whether verification succeeded:
+     * - `success: true`  → code was correct, user is verified
+     * - `success: false, error.code: "VERIFICATION_FAILED"` → wrong or expired code
+     * - `success: false, error.code: "DELIVERY_FAILED"` → network/server error
      *
      * ```typescript
      * const result = await client.verify(email, deviceId, code);
-     * if (!result.success) { /* transport/infra error *\/ }
-     * else if (!result.data?.verified) { /* wrong or expired code *\/ }
-     * else { /* verified *\/ }
+     * if (!result.success) {
+     *   if (result.error?.code === 'VERIFICATION_FAILED') { /* bad code *\/ }
+     *   else { /* transport error *\/ }
+     * } else { /* verified *\/ }
      * ```
+     */
+    verify(emailAddress: string, deviceId: string, code: string, opts?: {
+        fingerprintId?: string;
+    }): Promise<ApiResult<VerifyResult>>;
+    /**
+     * Fetch the verification flow configuration for this company.
+     * Maps to: GET /v2/verification-flow-config
+     *
+     * Returns the flow steps and branding configured by the Unshared Labs
+     * team for this company. The middleware uses this to render the
+     * verification overlay.
      *
-     * On network or 5xx errors, returns `{ success: false, error: { code: "DELIVERY_FAILED" } }`.
-     * On 4xx (e.g. rate limit), the server error is returned as-is.
+     * Returns `null` on any failure (network error, 4xx, 5xx) so the
+     * middleware can fall back to the default flow.
      */
-    verify(emailAddress: string, deviceId: string, code: string): Promise<ApiResult<VerifyResult>>;
+    getVerificationFlowConfig(): Promise<VerificationFlowConfigResult | null>;
 }

package/dist/esm/client.mjs

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

package/dist/esm/index.d.mts

@@ -1,2 +1,6 @@
 export { UnsharedLabsClient } from './client';
-export type { UnsharedLabsClientConfig, ApiResult, UnsharedLabsError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, } from './client';
+export { createUnsharedMiddleware, assertTrustProxy } from './middleware';
+export type { MiddlewareOptions } from './middleware';
+export { unsharedBoundToUser, VerdictCache, } from './middleware/index';
+export type { ProtectionConfig, Verdict } from './middleware/index';
+export type { UnsharedLabsClientConfig, ApiResult, UnsharedLabsError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, VerificationFlowStep, VerificationFlowConfigResult, } from './client';

package/dist/esm/index.mjs

@@ -1 +1 @@
-export{UnsharedLabsClient}from"./client";
+export{UnsharedLabsClient}from"./client";export{createUnsharedMiddleware,assertTrustProxy}from"./middleware";export{unsharedBoundToUser,VerdictCache}from"./middleware/index";

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

@@ -0,0 +1,50 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { UnsharedLabsClient } from '../client';
+import { VerdictCache } from './verdict-cache';
+import type { Verdict } from './verdict-cache';
+export interface ProtectionConfig {
+    /**
+     * 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.
+     * Required in Tier 2 (backend-only). Recommended in Tier 1.
+     * Falls back to HttpOnly cookie → req.body.email when not configured.
+     */
+    emailAddress?: (req: Request) => string | undefined;
+    /** 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[];
+    /** 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 __unshared_fp_id cookie → X-Device-Id header.
+     */
+    deviceId?: (req: Request) => string | undefined;
+    /**
+     * Called when a flagged, unverified user makes a request.
+     * You own the response — block, redirect, or call next() to let it through.
+     *
+     * If not provided, flagged requests pass through (data collection only).
+     * Exceptions are caught and swallowed — the request passes through on error.
+     */
+    onFlagged?: (context: {
+        userId: string;
+        emailAddress: string;
+        verdict: Verdict;
+        req: Request;
+        res: Response;
+        next: NextFunction;
+    }) => void;
+}
+export type { Verdict };
+export { VerdictCache };
+export declare function unsharedBoundToUser(client: UnsharedLabsClient, config: ProtectionConfig): (req: Request, res: Response, next: NextFunction) => void;