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

package/README.md

@@ -1,109 +1,179 @@
-# Unshared Labs SDK
+# @unshared-labs/sdk
 
-A lightweight, drop-in SDK for sending secure session and event data to the **Unshared Labs** platform.
-This package is designed for server environments (e.g., Express, Fastify, Next.js API routes) that need to track account sharing activity, session behavior, or suspicious usage patterns.
+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.**
 
 ---
 
 ## Installation
 
 ```bash
-npm install unshared-clientjs-sdk
-# or
-yarn add unshared-clientjs-sdk
+npm install @unshared-labs/sdk
 ```
 
+Requires Node.js ≥ 18.
+
 ---
 
-## Quick Example
+## Quick Start
 
-```ts
-import UnsharedLabsClient from "unshared-clientjs-sdk";
+```typescript
+import { UnsharedLabsClient } from '@unshared-labs/sdk';
 
 const client = new UnsharedLabsClient({
-  apiKey: process.env.UNSHARED_LABS_API_KEY!,
+  apiKey: process.env.UNSHARED_API_KEY!,
 });
 ```
 
----
+### CommonJS
 
-## API
-
-### `submitEvent(...)`
-
-```ts
-submitEvent(
-  eventType: string,
-  userId: string,
-  ipAddress: string,
-  deviceId: string,
-  sessionHash: string,
-  userAgent: string,
-  clientTimestamp: string,
-  eventDetails?: map<String,any> | null
-): Promise<any>
+```javascript
+const { UnsharedLabsClient } = require('@unshared-labs/sdk');
 ```
 
-**Parameters**
+---
 
-* `eventType` — string, e.g. `"login"`, `"heartbeat"`, `"logout"`
-* `userId` — string, unique user identifier (encrypted before sending)
-* `ipAddress` — string, client IP (encrypted)
-* `deviceId` — string, device identifier (encrypted)
-* `sessionHash` — string, session identifier or fingerprint (encrypted)
-* `userAgent` — string
-* `clientTimestamp` — ISO timestamp string (e.g. `new Date().toISOString()`).
-* `eventDetails` — optional map of objects (String,any) of additional details
+## Configuration
 
-**Returns**: A promise resolving Unshared Lab's DB insert result or rejecting with an error.
+```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
+});
+```
 
 ---
 
-## Example (Express)
+## Methods
 
-```ts
-import express from "express";
-import UnsharedLabsClient from "unshared-clientjs-sdk";
+### `submitFingerprintEvent(fingerprint, opts?)`
 
-const app = express();
-app.use(express.json());
+Submit a browser fingerprint collected by `@unshared-labs/frontend-fingerprint`. Returns 202 Accepted; the event is stored asynchronously.
 
-const client = new UnsharedLabsClient({
-  apiKey: process.env.UNSHARED_LABS_API_KEY!,
+```typescript
+const result = await client.submitFingerprintEvent(fingerprintData, {
+  userId: 'u_123',
+  sessionHash: 'sess_abc',
+  eventType: 'login',
 });
+// result.data: { hash, stable_hash, collected_at, version }
+```
+
+An `X-Idempotency-Key` is sent automatically. Retries with the same key are deduplicated at the backend.
+
+### `processUserEvent(params)`
 
-app.post("/login", async (req, res) => {
-  const { userId } = req.body;
-
-  try {
-    await client.submitEvent(
-      "login",
-      userId,
-      req.ip,
-      req.headers["x-device-id"]?.toString() || "unknown-device",
-      req.headers["x-session-hash"]?.toString() || "unknown-session",
-      req.headers["user-agent"] || "",
-      new Date().toISOString(),
-      new Map(Object.entries({"example": true, "source": 'test-server' }))
-    );
-
-    res.status(200).json({ message: "Login tracked" });
-  } catch (err) {
-    res.status(500).json({ error: err instanceof Error ? err.message : err });
-  }
+Record a user event and receive naughty-list analysis. `emailAddress` and `deviceId` are AES-256-GCM encrypted before sending.
+
+```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 } }
+```
+
+> **Note:** This endpoint has no server-side idempotency. Retries may insert duplicate rows.
+
+### `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.
 
-app.listen(3000, () => console.log("Server running on port 3000"));
+```typescript
+const result = await client.checkUser('user@example.com', 'device-uuid');
+if (result.data?.is_user_flagged) { /* … */ }
 ```
 
+### `triggerEmailVerification(emailAddress, deviceId)`
+
+Send a 6-digit verification code. Rate-limited to one request per `(email_address, device_id)` pair per 2 minutes.
+
+```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
+}
+```
+
+**Pre-condition:** sender settings must be configured via `createSender` + `validateSender` before this will succeed.
+
+### `verify(emailAddress, deviceId, code)`
+
+Verify the 6-digit code entered by the user. `success: true` with `verified: false` means the code was wrong — not a transport error.
+
+```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' */ }
+```
+
+---
+
+## Express Middleware (Browser Proxy)
+
+Mount this to handle fingerprint events forwarded from `@unshared-labs/frontend-fingerprint`:
+
+```typescript
+import { createUnsharedMiddleware } from '@unshared-labs/sdk/middleware';
+
+app.use(createUnsharedMiddleware(client, {
+  userIdExtractor: (req) => req.user?.id,
+  eventTypeExtractor: (req) => req.body.event_type,
+  routePrefix: '/unshared',  // default
+}));
+```
+
+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 }`
+
+---
+
+## Error Handling
+
+All methods return `ApiResult<T>`:
+
+```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
+}
+```
+
+- **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.
+
 ---
 
-## License
+## Encryption
 
-MIT © Unshared Labs
+`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`.
 
 ---
 
-## Support
+## Environment Variables
 
-For issues or onboarding help, contact Unshared Labs support.
+```bash
+UNSHARED_API_KEY=sk_live_…
+```

package/dist/client.d.ts

@@ -1,207 +1,158 @@
-/**
- * Configuration object for initializing the UnsharedLabsClient.
- *
- * @interface UnsharedLabsClientConfig
- * @property {string} apiKey - Your API key for authenticating with UnsharedLabs services
- * @property {string} clientId - Encrypted client ID for authentication
- * @property {string} [baseUrl] - Optional custom base URL for the API service
- * @property {string} [emailServiceUrl] - Optional custom URL for the email service
- */
+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_…
+     */
     apiKey: string;
-    clientId: string;
+    /**
+     * Base URL of the Unshared Labs V2 ingress.
+     * @default "https://api-ingress.unsharedlabs.com"
+     */
     baseUrl?: string;
-    emailServiceUrl?: string;
+    /**
+     * Per-request timeout in milliseconds.
+     * @default 10_000
+     */
+    timeout?: number;
+    /**
+     * Max retries for 5xx / network failures after the first attempt.
+     * @default 3
+     */
+    maxRetries?: number;
 }
-/**
- * Client for interacting with UnsharedLabs API services.
- *
- * This client provides methods to:
- * - Process user events for fraud detection and analysis
- * - Check if a user is flagged as an account sharer
- * - Trigger email verification
- * - Verify email verification codes
- *
- * All sensitive data (user IDs, IP addresses, etc.) is automatically encrypted
- * before being sent to the API using the provided API key.
- *
- * @class UnsharedLabsClient
- * @example
- * ```typescript
- * const client = new UnsharedLabsClient({
- *   apiKey: 'your-api-key',
- *   clientId: 'base64-encoded-client-id'
- * });
- * ```
- */
-export default class UnsharedLabsClient {
-    private _apiKey;
-    private _clientId;
-    private _apiBaseUrl;
-    private _emailServiceUrl;
+export interface UnsharedLabsError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
     /**
-     * Creates a new instance of UnsharedLabsClient.
-     *
-     * @param {UnsharedLabsClientConfig} config - Configuration object containing API credentials and optional service URLs
-     * @constructor
+     * Seconds to wait before retrying. Populated on 429 RATE_LIMIT_EXCEEDED
+     * responses by reading the `Retry-After` HTTP response header.
+     * Falls back to `details.retry_after_seconds` if the header is absent.
      */
+    retryAfter?: number;
+}
+export interface ApiResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: UnsharedLabsError;
+    status: number;
+}
+export interface SubmitFingerprintOptions {
+    userId?: string;
+    sessionHash?: string;
+    eventType?: string;
+}
+export interface SubmitFingerprintResult {
+    hash: string;
+    stable_hash: string;
+    collected_at: string;
+    /** Always present; set to "unknown" by the server if not provided. */
+    version: string;
+}
+export interface ProcessUserEventParams {
+    eventType: string;
+    userId: string;
+    /** Plaintext — SDK does not encrypt this field. */
+    ipAddress: string;
+    /** SDK encrypts before sending. */
+    deviceId: string;
+    sessionHash: string;
+    userAgent: string;
+    /** SDK encrypts before sending. */
+    emailAddress: string;
+    subscriptionStatus?: string | null;
+    eventDetails?: Record<string, unknown> | null;
+}
+export interface ProcessUserEventResult {
+    event: {
+        event_type: string;
+        user_id: string;
+        email_address: string;
+        ip_address: string;
+        device_id: string;
+        session_hash: string;
+        user_agent: string;
+        event_details?: string;
+        subscription_status?: string;
+    };
+    analysis: {
+        status: 'success' | 'error';
+        is_user_flagged: boolean;
+        status_details?: string;
+    };
+}
+export interface CheckUserResult {
+    is_user_flagged: boolean;
+}
+export interface TriggerEmailVerificationResult {
+    message: string;
+}
+export interface VerifyResult {
+    verified: boolean;
+    reason?: 'not_found' | 'code_mismatch' | 'code_expired';
+}
+export declare class UnsharedLabsClient {
+    private readonly _apiKey;
+    private readonly _baseUrl;
+    private readonly _timeout;
+    private readonly _maxRetries;
+    private readonly _encryptionKey;
     constructor(config: UnsharedLabsClientConfig);
-    private _getBasicAuthHeader;
+    private _encrypt;
     /**
-     * Submits a user event to the UnsharedLabs API for processing.
-     *
-     * @deprecated This method is deprecated and will be removed in a future version. Use `processUserEvent` instead.
-     *
-     * @param {string} eventType - Type of event being submitted (e.g., 'signup', 'login', 'purchase')
-     * @param {string} userId - Unique identifier for the user. Use email address if available.
-     * @param {string} ipAddress - IP address of the user
-     * @param {string} deviceId - Unique identifier for the device
-     * @param {string} sessionHash - Hash of the user's session
-     * @param {string} userAgent - User agent string from the browser/client
-     * @param {string} clientTimestamp - ISO 8601 timestamp when the event occurred on the client
-     * @param {Map<string, any> | null} [eventDetails] - Optional map of additional event details to include
-     *
-     * @returns {Promise<{status: number, statusText: string, data: any}>} Response object containing HTTP status, status text, and response data
-     *
-     * @throws {Error} Throws an error if the API request fails or returns a non-OK status
-     *
-     * @example
-     * ```typescript
-     * const result = await client.submitEvent(
-     *   'signup',
-     *   'user@example.com',
-     *   '192.168.1.1',
-     *   'device456',
-     *   'session789',
-     *   'Mozilla/5.0...',
-     *   '2024-01-01T00:00:00Z',
-     *   new Map([['source', 'web']])
-     * );
-     * ```
+     * Core HTTP method with retry logic.
+     * - 2xx → success result
+     * - 4xx → non-retryable, error result returned immediately
+     * - 5xx → retried up to maxRetries, last error result returned
+     * - Network/timeout → retried, NETWORK_ERROR result returned
      */
-    submitEvent(eventType: string, userId: string, ipAddress: string, deviceId: string, sessionHash: string, userAgent: string, clientTimestamp: string, eventDetails?: Map<string, any> | null): Promise<any>;
+    private _fetch;
     /**
-     * Processes a user event through the UnsharedLabs API, including fraud detection and analysis.
-     *
-     * This method encrypts all sensitive user data (user ID, IP address, device ID, etc.) before
-     * sending it to the API. The response includes both event processing results and analysis
-     * results that indicate if the user has been flagged for suspicious activity.
-     *
-     * @param {string} eventType - Type of event being processed (e.g., 'signup', 'login', 'purchase')
-     * @param {string} userId - Unique identifier for the user. Use email address if available.
-     * @param {string} ipAddress - IP address of the user
-     * @param {string} deviceId - Unique identifier for the device
-     * @param {string} sessionHash - Hash of the user's session
-     * @param {string} userAgent - User agent string from the browser/client
-     * @param {string} emailAddress - Email address of the user
-     * @param {string | null} [subscriptionStatus] - Optional subscription status string, (e.g. 'paid', 'free', 'trial', 'discounted')
-     * @param {Map<string, any> | null} [eventDetails] - Optional map of additional event details to include
-     *
-     * @returns {Promise<any>} Response object containing:
-     *   - success: Boolean indicating if the API call was successful
-     *   - event: Event processing result with status and event data (on success)
-     *   - analysis: Analysis result with flagging information (on success)
-     *   - error: Error message (on failure)
-     *
-     * @example
-     * ```typescript
-     * const response = await client.processUserEvent(
-     *   'signup',
-     *   'user@example.com',
-     *   '192.168.1.1',
-     *   'device456',
-     *   'session789',
-     *   'Mozilla/5.0...',
-     *   'user@example.com',
-     *   'paid',
-     *   new Map([['source', 'web']])
-     * );
-     *
-     * if (!response.success) {
-     *   console.error('Error:', response.error);
-     * } else if (response.analysis?.is_user_flagged) {
-     *   console.log('User flagged for suspicious activity');
-     * }
-     * ```
+     * Submit a browser fingerprint event. Publishes asynchronously via Pub/Sub.
+     * Maps to: POST /v2/submit-fingerprint-event
      */
-    processUserEvent(eventType: string, userId: string, ipAddress: string, deviceId: string, sessionHash: string, userAgent: string, emailAddress: string, subscriptionStatus?: string | null, eventDetails?: Map<string, any> | null): Promise<any>;
+    submitFingerprintEvent(fingerprint: FingerprintWireFormat, opts?: SubmitFingerprintOptions): Promise<ApiResult<SubmitFingerprintResult>>;
     /**
-     * Checks if a user is flagged as an account sharer based on their email address and device ID.
-     *
-     * This method encrypts the email address and device ID before sending them to the API.
-     * The response indicates whether the user has been flagged for suspicious activity.
-     *
-     * @param {string} emailAddress - Email address of the user to check
-     * @param {string} deviceId - Unique identifier for the device
-     *
-     * @returns {Promise<any>} Response object containing:
-     *   - success: Boolean indicating if the API call was successful
-     *   - status: String indicating the status ("success" or "error")
-     *   - is_user_flagged: Boolean indicating if the user was flagged as an account sharer
-     *   - status_details: String with error details (only present on error)
-     *   - error: Error message (only present on failure)
-     *
-     * @example
-     * ```typescript
-     * const response = await client.checkUser(
-     *   'user@example.com',
-     *   'device456'
-     * );
-     *
-     * if (!response.success) {
-     *   console.error('Error:', response.error || response.status_details);
-     * } else if (response.is_user_flagged) {
-     *   console.log('User is flagged for suspicious activity');
-     * }
-     * ```
+     * Record a user event and receive naughty-list analysis.
+     * Maps to: POST /v2/process-user-event
      */
-    checkUser(emailAddress: string, deviceId: string): Promise<any>;
+    processUserEvent(params: ProcessUserEventParams): Promise<ApiResult<ProcessUserEventResult>>;
     /**
-     * Triggers an email verification to be sent to the user.
-     *
-     * This method sends a verification email to the specified email address.
-     *
-     * @param {string} emailAddress - Email address to send the verification to
-     * @param {string} deviceId - device id for whom the code is being verified.
-     * @returns {Promise<any>} Response object from the email service containing verification details
-     *
-     * @throws {Error} Throws an error if:
-     *   - The emailAddress is not a valid email address
-     *   - The email service request fails or returns a non-OK status
-     *
-     * @example
-     * ```typescript
-     * await client.triggerEmailVerification('user@example.com');
-     * ```
+     * Check if a user is flagged in the naughty list.
+     * Maps to: GET /v2/check-user
+     *
+     * **Defensive default:** On any failure (network error, 4xx, 5xx, timeout) this
+     * method returns `{ success: true, data: { is_user_flagged: false } }` rather
+     * than surfacing the error. This ensures a backend outage never incorrectly
+     * blocks a legitimate user. As a consequence, a complete API outage is
+     * **invisible** to the caller — you cannot distinguish "user is clean" from
+     * "request failed" by inspecting the return value. Monitor API availability
+     * through your infrastructure metrics, not through this method's return value.
      */
-    triggerEmailVerification(emailAddress: string, deviceId: string): Promise<any>;
+    checkUser(emailAddress: string, deviceId: string): Promise<ApiResult<CheckUserResult>>;
     /**
-     * Verifies an email verification code for a user.
-     *
-     * This method validates a verification code that was sent to the user via email.
-     * The code is typically obtained from the user after they receive the verification email.
-     *
-     * @param {string} emailAddress - Email address for whom the code is being verified.
-     * @param {string} deviceId - device id for whom the code is being verified.
-     * @param {string} code - Verification code that was sent to the user's email
-     *
-     * @returns {Promise<any>} Response object from the verification service containing:
-     *   - Verification status (success/failure)
-     *   - Additional verification details
+     * 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>>;
+    /**
+     * Verify a 6-digit code submitted by the user.
+     * Maps to: POST /v2/verify
      *
-     * @throws {Error} Throws an error if:
-     *   - The verification service request fails
-     *   - The service returns a non-OK status (e.g., invalid code, expired code)
+     * **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:
      *
-     * @example
      * ```typescript
-     * try {
-     *   const result = await client.verify('user@example.com', '123456');
-     *   console.log('Verification successful:', result);
-     * } catch (error) {
-     *   console.error('Verification failed:', error.message);
-     * }
+     * 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 *\/ }
      * ```
+     *
+     * 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.
      */
-    verify(emailAddress: string, deviceId: string, code: string): Promise<any>;
+    verify(emailAddress: string, deviceId: string, code: string): Promise<ApiResult<VerifyResult>>;
 }

package/dist/client.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});const util_1=require("./util");class UnsharedLabsClient{constructor(t){this._apiBaseUrl="https://api.unsharedlabs.com",this._emailServiceUrl="https://emailservice.unsharedlabs.com",this._apiKey=t.apiKey,this._clientId=atob(t.clientId).trim(),t.baseUrl&&(this._apiBaseUrl=t.baseUrl),t.emailServiceUrl&&(this._emailServiceUrl=t.emailServiceUrl)}_getBasicAuthHeader(){const t=`${this._clientId}:${this._apiKey}`;return`Basic ${Buffer.from(t).toString("base64")}`}async submitEvent(t,e,i,r,a,s,n,o){try{const c=(0,util_1.encryptData)(e,this._apiKey),h=(0,util_1.encryptData)(i,this._apiKey),l=(0,util_1.encryptData)(r,this._apiKey),_=(0,util_1.encryptData)(a,this._apiKey),d=(0,util_1.encryptData)(s,this._apiKey),p={user_id:c,event_type:t,ip_address:h,device_id:l,session_hash:_,user_agent:d,client_timestamp:n,event_details:(0,util_1.encryptData)(o?JSON.stringify([...o.entries()]):null,this._apiKey)},y=await fetch(`${this._apiBaseUrl}/api/v1/submitEvent`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:this._getBasicAuthHeader()},body:JSON.stringify(p)});if(!y.ok){const t=await y.json().catch(()=>({error:y.statusText}));throw new Error(`API returned error: ${JSON.stringify(t)}`)}const u=await y.json();return{status:y.status,statusText:y.statusText,data:u}}catch(t){throw new Error(`Failed to call UnsharedLabs API: ${t instanceof Error?t.message:JSON.stringify(t)}`)}}async processUserEvent(t,e,i,r,a,s,n,o,c){try{const h=(0,util_1.encryptData)(e,this._apiKey),l=(0,util_1.encryptData)(i,this._apiKey),_=(0,util_1.encryptData)(r,this._apiKey),d=(0,util_1.encryptData)(a,this._apiKey),p=(0,util_1.encryptData)(s,this._apiKey),y=(0,util_1.encryptData)(n,this._apiKey),u={user_id:h,event_type:t,ip_address:l,device_id:_,session_hash:d,user_agent:p,email_address:y,event_details:(0,util_1.encryptData)(c?JSON.stringify([...c.entries()]):null,this._apiKey)};null!=o&&"string"==typeof o&&(u.subscription_status=o.trim());const f=await fetch(`${this._apiBaseUrl}/api/v1/processUserEvent`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:this._getBasicAuthHeader()},body:JSON.stringify(u)});return await f.json()}catch(t){return{success:!1,error:`Failed to process user event: ${t instanceof Error?t.message:JSON.stringify(t)}`}}}async checkUser(t,e){try{const i=(0,util_1.encryptData)(t,this._apiKey),r=(0,util_1.encryptData)(e,this._apiKey),a=new URLSearchParams({email_address:i||"",device_id:r||""}),s=await fetch(`${this._apiBaseUrl}/api/v1/checkUser?${a.toString()}`,{method:"GET",headers:{Authorization:this._getBasicAuthHeader()}});return await s.json()}catch(t){return{success:!1,error:`Failed to check user: ${t instanceof Error?t.message:JSON.stringify(t)}`}}}async triggerEmailVerification(t,e){try{if(!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(t))throw new Error("Invalid email address provided");const i=await fetch(`${this._emailServiceUrl}/api/send-email`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:this._getBasicAuthHeader()},body:JSON.stringify({email_address:t,device_id:e})});if(!i.ok){const t=await i.json().catch(()=>({error:i.statusText}));throw new Error(`Email service returned error: ${JSON.stringify(t)}`)}return await i.json()}catch(t){throw new Error(`Failed to trigger email verification: ${t instanceof Error?t.message:JSON.stringify(t)}`)}}async verify(t,e,i){try{const r=await fetch(`${this._emailServiceUrl}/api/verify`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:this._getBasicAuthHeader()},body:JSON.stringify({email_address:t,device_id:e,code:i})});if(!r.ok){const t=await r.json().catch(()=>({error:r.statusText}));throw new Error(`Verification service returned error: ${JSON.stringify(t)}`)}return await r.json()}catch(t){throw new Error(`Failed to verify code: ${t instanceof Error?t.message:JSON.stringify(t)}`)}}}exports.default=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,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;

package/dist/esm/client.d.mts

@@ -0,0 +1,158 @@
+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_…
+     */
+    apiKey: string;
+    /**
+     * Base URL of the Unshared Labs V2 ingress.
+     * @default "https://api-ingress.unsharedlabs.com"
+     */
+    baseUrl?: string;
+    /**
+     * Per-request timeout in milliseconds.
+     * @default 10_000
+     */
+    timeout?: number;
+    /**
+     * Max retries for 5xx / network failures after the first attempt.
+     * @default 3
+     */
+    maxRetries?: number;
+}
+export interface UnsharedLabsError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    /**
+     * Seconds to wait before retrying. Populated on 429 RATE_LIMIT_EXCEEDED
+     * responses by reading the `Retry-After` HTTP response header.
+     * Falls back to `details.retry_after_seconds` if the header is absent.
+     */
+    retryAfter?: number;
+}
+export interface ApiResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: UnsharedLabsError;
+    status: number;
+}
+export interface SubmitFingerprintOptions {
+    userId?: string;
+    sessionHash?: string;
+    eventType?: string;
+}
+export interface SubmitFingerprintResult {
+    hash: string;
+    stable_hash: string;
+    collected_at: string;
+    /** Always present; set to "unknown" by the server if not provided. */
+    version: string;
+}
+export interface ProcessUserEventParams {
+    eventType: string;
+    userId: string;
+    /** Plaintext — SDK does not encrypt this field. */
+    ipAddress: string;
+    /** SDK encrypts before sending. */
+    deviceId: string;
+    sessionHash: string;
+    userAgent: string;
+    /** SDK encrypts before sending. */
+    emailAddress: string;
+    subscriptionStatus?: string | null;
+    eventDetails?: Record<string, unknown> | null;
+}
+export interface ProcessUserEventResult {
+    event: {
+        event_type: string;
+        user_id: string;
+        email_address: string;
+        ip_address: string;
+        device_id: string;
+        session_hash: string;
+        user_agent: string;
+        event_details?: string;
+        subscription_status?: string;
+    };
+    analysis: {
+        status: 'success' | 'error';
+        is_user_flagged: boolean;
+        status_details?: string;
+    };
+}
+export interface CheckUserResult {
+    is_user_flagged: boolean;
+}
+export interface TriggerEmailVerificationResult {
+    message: string;
+}
+export interface VerifyResult {
+    verified: boolean;
+    reason?: 'not_found' | 'code_mismatch' | 'code_expired';
+}
+export declare class UnsharedLabsClient {
+    private readonly _apiKey;
+    private readonly _baseUrl;
+    private readonly _timeout;
+    private readonly _maxRetries;
+    private readonly _encryptionKey;
+    constructor(config: UnsharedLabsClientConfig);
+    private _encrypt;
+    /**
+     * Core HTTP method with retry logic.
+     * - 2xx → success result
+     * - 4xx → non-retryable, error result returned immediately
+     * - 5xx → retried up to maxRetries, last error result returned
+     * - Network/timeout → retried, NETWORK_ERROR result returned
+     */
+    private _fetch;
+    /**
+     * Submit a browser fingerprint event. Publishes asynchronously via Pub/Sub.
+     * Maps to: POST /v2/submit-fingerprint-event
+     */
+    submitFingerprintEvent(fingerprint: FingerprintWireFormat, opts?: SubmitFingerprintOptions): Promise<ApiResult<SubmitFingerprintResult>>;
+    /**
+     * Record a user event and receive naughty-list analysis.
+     * Maps to: POST /v2/process-user-event
+     */
+    processUserEvent(params: ProcessUserEventParams): Promise<ApiResult<ProcessUserEventResult>>;
+    /**
+     * Check if a user is flagged in the naughty list.
+     * Maps to: GET /v2/check-user
+     *
+     * **Defensive default:** On any failure (network error, 4xx, 5xx, timeout) this
+     * method returns `{ success: true, data: { is_user_flagged: false } }` rather
+     * than surfacing the error. This ensures a backend outage never incorrectly
+     * blocks a legitimate user. As a consequence, a complete API outage is
+     * **invisible** to the caller — you cannot distinguish "user is clean" from
+     * "request failed" by inspecting the return value. Monitor API availability
+     * through your infrastructure metrics, not through this method's return value.
+     */
+    checkUser(emailAddress: string, deviceId: 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>>;
+    /**
+     * 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:
+     *
+     * ```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 *\/ }
+     * ```
+     *
+     * 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.
+     */
+    verify(emailAddress: string, deviceId: string, code: string): Promise<ApiResult<VerifyResult>>;
+}

package/dist/esm/client.mjs

@@ -0,0 +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}}

package/dist/esm/index.d.mts

@@ -0,0 +1,2 @@
+export { UnsharedLabsClient } from './client';
+export type { UnsharedLabsClientConfig, ApiResult, UnsharedLabsError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, } from './client';

package/dist/esm/index.mjs

@@ -0,0 +1 @@
+export{UnsharedLabsClient}from"./client";

package/dist/esm/middleware.d.mts

@@ -0,0 +1,48 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { UnsharedLabsClient } from './client';
+export interface MiddlewareOptions {
+    /** Override userId extractor. Falls back to req.body.user_id. */
+    userIdExtractor?: (req: Request) => string | undefined;
+    /** Override eventType extractor. Falls back to req.body.event_type. */
+    eventTypeExtractor?: (req: Request) => string | undefined;
+    /** Override sessionId extractor. Falls back to X-Session-Id header, then req.body.session_id. */
+    sessionIdExtractor?: (req: Request) => string | undefined;
+    /** Default event type when none is extractable. @default "browser_event" */
+    defaultEventType?: string;
+    /**
+     * Route prefix the middleware is mounted under.
+     * @default "/unshared"
+     */
+    routePrefix?: string;
+}
+/**
+ * Creates an Express middleware that proxies browser fingerprint events to
+ * Unshared Labs. Mount this to handle the browser fingerprint route contract (§4 of spec).
+ *
+ * Handles POST <routePrefix>/submit-fingerprint-event.
+ * Passes all other requests to next().
+ *
+ * **Prerequisites:**
+ * - Mount `express.json()` (or equivalent body-parser) **before** this middleware,
+ *   otherwise `req.body` will be undefined and every request will return 400.
+ * - Configure CORS on your `/unshared/*` routes separately — this middleware
+ *   does not set any `Access-Control-*` headers.
+ * - Disable request body logging on `/unshared/*` routes. `user_id` arrives in
+ *   plaintext from the browser and must not be captured by logging middleware.
+ *
+ * **Error contract:** Never returns 5xx to the browser. Upstream failures are
+ * returned as HTTP 200 with { success: false, error: { code: "UPSTREAM_ERROR" } }.
+ * Standard HTTP-level monitoring will not surface proxy errors — monitor the
+ * rate of `success: false` responses in your application layer instead.
+ *
+ * @example
+ * ```typescript
+ * import { createUnsharedMiddleware } from "@unshared-labs/sdk/middleware";
+ *
+ * app.use(express.json());  // must come first
+ * app.use(createUnsharedMiddleware(client, {
+ *   userIdExtractor: (req) => req.user?.id,
+ * }));
+ * ```
+ */
+export declare function createUnsharedMiddleware(client: UnsharedLabsClient, options?: MiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/esm/middleware.mjs

@@ -0,0 +1 @@
+export function createUnsharedMiddleware(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:n,defaultEventType:c="browser_event",routePrefix:o="/unshared"}=r??{},i=`${o}/submit-fingerprint-event`;return async(r,o,a)=>{if("POST"===r.method&&r.path===i)try{const i=r.body??{};if(!i.hash||!i.stable_hash||!i.collected_at)return void o.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});const a={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 d,u,f;try{d=(s?s(r):void 0)??i.user_id}catch{d=i.user_id}try{u=(t?t(r):void 0)??i.event_type??c}catch{u=i.event_type??c}try{f=(n?n(r):void 0)??r.headers["x-session-id"]?.toString()??i.session_id}catch{f=r.headers["x-session-id"]?.toString()??i.session_id}const h=await e.submitFingerprintEvent(a,{userId:d,sessionHash:f,eventType:u});if(!h.success)return void o.status(200).json({success:!1,error:{code:"UPSTREAM_ERROR",message:h.error?.message??"Upstream request failed"}});o.status(202).json({success:!0,data:h.data})}catch(e){o.status(200).json({success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else a()}}

package/dist/esm/util.d.mts

@@ -0,0 +1 @@
+export declare function encryptData(data: string, key: Buffer): string;

package/dist/esm/util.mjs

@@ -0,0 +1 @@
+import{createCipheriv,randomBytes}from"crypto";export function encryptData(e,t){const r=randomBytes(12),a=createCipheriv("aes-256-gcm",t,r);let o=a.update(e,"utf8","base64");o+=a.final("base64");const s=a.getAuthTag();return r.toString("base64")+":"+s.toString("base64")+":"+o}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { UnsharedLabsClient } from './client';
+export type { UnsharedLabsClientConfig, ApiResult, UnsharedLabsError, SubmitFingerprintOptions, SubmitFingerprintResult, ProcessUserEventParams, ProcessUserEventResult, CheckUserResult, TriggerEmailVerificationResult, VerifyResult, } from './client';

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.UnsharedLabsClient=void 0;var client_1=require("./client");Object.defineProperty(exports,"UnsharedLabsClient",{enumerable:!0,get:function(){return client_1.UnsharedLabsClient}});

package/dist/middleware.d.ts

@@ -0,0 +1,48 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { UnsharedLabsClient } from './client';
+export interface MiddlewareOptions {
+    /** Override userId extractor. Falls back to req.body.user_id. */
+    userIdExtractor?: (req: Request) => string | undefined;
+    /** Override eventType extractor. Falls back to req.body.event_type. */
+    eventTypeExtractor?: (req: Request) => string | undefined;
+    /** Override sessionId extractor. Falls back to X-Session-Id header, then req.body.session_id. */
+    sessionIdExtractor?: (req: Request) => string | undefined;
+    /** Default event type when none is extractable. @default "browser_event" */
+    defaultEventType?: string;
+    /**
+     * Route prefix the middleware is mounted under.
+     * @default "/unshared"
+     */
+    routePrefix?: string;
+}
+/**
+ * Creates an Express middleware that proxies browser fingerprint events to
+ * Unshared Labs. Mount this to handle the browser fingerprint route contract (§4 of spec).
+ *
+ * Handles POST <routePrefix>/submit-fingerprint-event.
+ * Passes all other requests to next().
+ *
+ * **Prerequisites:**
+ * - Mount `express.json()` (or equivalent body-parser) **before** this middleware,
+ *   otherwise `req.body` will be undefined and every request will return 400.
+ * - Configure CORS on your `/unshared/*` routes separately — this middleware
+ *   does not set any `Access-Control-*` headers.
+ * - Disable request body logging on `/unshared/*` routes. `user_id` arrives in
+ *   plaintext from the browser and must not be captured by logging middleware.
+ *
+ * **Error contract:** Never returns 5xx to the browser. Upstream failures are
+ * returned as HTTP 200 with { success: false, error: { code: "UPSTREAM_ERROR" } }.
+ * Standard HTTP-level monitoring will not surface proxy errors — monitor the
+ * rate of `success: false` responses in your application layer instead.
+ *
+ * @example
+ * ```typescript
+ * import { createUnsharedMiddleware } from "@unshared-labs/sdk/middleware";
+ *
+ * app.use(express.json());  // must come first
+ * app.use(createUnsharedMiddleware(client, {
+ *   userIdExtractor: (req) => req.user?.id,
+ * }));
+ * ```
+ */
+export declare function createUnsharedMiddleware(client: UnsharedLabsClient, options?: MiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/middleware.js

@@ -0,0 +1 @@
+"use strict";function createUnsharedMiddleware(e,r){const{userIdExtractor:s,eventTypeExtractor:t,sessionIdExtractor:c,defaultEventType:n="browser_event",routePrefix:o="/unshared"}=r??{},a=`${o}/submit-fingerprint-event`;return async(r,o,i)=>{if("POST"===r.method&&r.path===a)try{const a=r.body??{};if(!a.hash||!a.stable_hash||!a.collected_at)return void o.status(400).json({success:!1,error:{code:"VALIDATION_ERROR",message:"Missing required fingerprint fields: hash, stable_hash, collected_at"}});const i={full_hash:a.hash,fingerprint_id:a.stable_hash,timestamp:a.collected_at,isIncognito:a.is_incognito??!1,components:a.components??{},version:a.version??"unknown"};let d,u,l;try{d=(s?s(r):void 0)??a.user_id}catch{d=a.user_id}try{u=(t?t(r):void 0)??a.event_type??n}catch{u=a.event_type??n}try{l=(c?c(r):void 0)??r.headers["x-session-id"]?.toString()??a.session_id}catch{l=r.headers["x-session-id"]?.toString()??a.session_id}const h=await e.submitFingerprintEvent(i,{userId:d,sessionHash:l,eventType:u});if(!h.success)return void o.status(200).json({success:!1,error:{code:"UPSTREAM_ERROR",message:h.error?.message??"Upstream request failed"}});o.status(202).json({success:!0,data:h.data})}catch(e){o.status(200).json({success:!1,error:{code:"MIDDLEWARE_ERROR",message:e instanceof Error?e.message:"Middleware error"}})}else i()}}Object.defineProperty(exports,"t",{value:!0}),exports.createUnsharedMiddleware=createUnsharedMiddleware;

package/dist/util.d.ts

@@ -1,2 +1 @@
-export declare function encryptData(data: string | null | undefined, clientCredentials: string): string;
-export declare function decryptData(encryptedData: string, clientCredentials: string): string | null;
+export declare function encryptData(data: string, key: Buffer): string;

package/dist/util.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.encryptData=encryptData,exports.decryptData=decryptData;const crypto_1=require("crypto");function encryptData(t,e){if(null==t)return"unknown";const r="string"==typeof t?t:JSON.stringify(t),a=(0,crypto_1.createHash)("sha256").update(e).digest(),n=(0,crypto_1.randomBytes)(16),c=(0,crypto_1.createCipheriv)("aes-256-cbc",a,n);let o=c.update(r,"utf8","base64");return o+=c.final("base64"),n.toString("base64")+":"+o}function decryptData(t,e){if("unknown"===t)return null;const r=t.split(":");if(2!==r.length)throw new Error("Invalid encrypted data format");const[a,n]=r,c=Buffer.from(a,"base64"),o=(0,crypto_1.createHash)("sha256").update(e).digest(),s=(0,crypto_1.createDecipheriv)("aes-256-cbc",o,c);let p=s.update(n,"base64","utf8");return p+=s.final("utf8"),p}
+"use strict";Object.defineProperty(exports,"t",{value:!0}),exports.encryptData=encryptData;const crypto_1=require("crypto");function encryptData(t,e){const c=(0,crypto_1.randomBytes)(12),r=(0,crypto_1.createCipheriv)("aes-256-gcm",e,c);let s=r.update(t,"utf8","base64");s+=r.final("base64");const o=r.getAuthTag();return c.toString("base64")+":"+o.toString("base64")+":"+s}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "unshared-clientjs-sdk",
-  "version": "1.0.13",
-  "description": "",
-  "main": "dist/client.js",
-  "types": "dist/client.d.ts",
+  "version": "2.0.0-rc.2",
+  "description": "Server-side Node.js SDK for the Unshared Labs V2 API",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.mjs",
+  "types": "dist/index.d.ts",
   "scripts": {
     "build": "node scripts/build.js",
     "build:tsc": "tsc",
@@ -17,9 +18,32 @@
     "dist",
     "README.md"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./middleware": {
+      "import": "./dist/esm/middleware.mjs",
+      "require": "./dist/middleware.js",
+      "types": "./dist/middleware.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "keywords": [],
   "author": "",
   "license": "MIT",
+  "peerDependencies": {
+    "@types/express": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^24.10.1",