@spritz-finance/context-browser 0.0.1

package/README.md

@@ -0,0 +1,72 @@
+# @spritz-finance/context-browser
+
+Browser SDK for device context headers.
+
+## Usage
+
+```typescript
+import { createContext } from '@spritz-finance/context-browser';
+
+const ctx = createContext({ sandbox: true }); // or omit for prod
+await ctx.init();
+
+// Add to fetch requests
+fetch('/api/endpoint', {
+  headers: {
+    ...ctx.getHeader(), // { 'x-meta-sess': '...' }
+  },
+});
+```
+
+## API
+
+```typescript
+const ctx = createContext(config?)
+```
+
+| Config | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sandbox` | `boolean` | `false` | Use sandbox keys |
+| `debug` | `boolean` | `false` | Log to console |
+| `signals.canvas` | `boolean` | `true` | Collect canvas hash |
+| `signals.webgl` | `boolean` | `true` | Collect WebGL renderer |
+
+```typescript
+await ctx.init()        // Initialize (required before use)
+ctx.getHeader()         // Returns { 'x-meta-sess': string } or {}
+ctx.getClaimedId()      // Returns persistent device ID
+ctx.isReady()           // Returns true after init
+await ctx.recompute()   // Refresh signals (called automatically every 5min)
+```
+
+## Payload Structure
+
+After decrypting `x-meta-sess`, backend receives:
+
+```typescript
+{
+  timestamp: number,
+  nonce: string,
+  identifiers: {
+    claimed_id: string,   // Persistent device ID
+    actual_fp: string,    // Signal hash
+  },
+  signals: {
+    screen, timezone, language, platform, cores, memory,
+    canvas, webgl,        // Hashed/raw values
+    automation: {         // Bot detection
+      webdriver, chromePresent, pluginCount,
+      phantomjs, selenium, playwright, puppeteer,
+      headlessUA, nativeFnTampered
+    },
+    _meta: {              // Collection diagnostics
+      [signal]: { status: 'ok'|'blocked'|'errored', ms?, error? }
+    }
+  },
+  storage: {              // ID storage consistency
+    sources: ['local'|'session'|'cookie'][],
+    allMatch: boolean,
+    divergent?: Record<string, string>
+  }
+}
+```