@danetix/sentinel 1.0.0 → 1.0.1

package/README.md

@@ -1,217 +1,136 @@
-# @danetix/sentinel
+<p align="center">
+  <a href="https://danetix.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://danetix.com/logo-white.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://danetix.com/logo-dark.svg">
+      <img src="https://danetix.com/logo-dark.svg" alt="Danetix" width="260">
+    </picture>
+  </a>
+</p>
+
+<h3 align="center">Device Intelligence SDK</h3>
+
+<p align="center">
+  Generates a stable device identifier that persists across sessions, tabs, and browsing modes.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@danetix/sentinel"><img src="https://img.shields.io/npm/v/@danetix/sentinel.svg" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/@danetix/sentinel"><img src="https://img.shields.io/npm/dm/@danetix/sentinel.svg" alt="downloads"></a>
+  <a href="https://www.npmjs.com/package/@danetix/sentinel"><img src="https://img.shields.io/bundlephobia/minzip/@danetix/sentinel" alt="size"></a>
+</p>
 
-Device intelligence SDK by [Danetix](https://danetix.com). Collects 155+ browser signals for device identification, bot detection, and anti-tamper analysis.
-
-## Features
-
-- **155+ browser signals** — canvas, audio, WebGL, WebGPU, fonts, and more
-- **Bot detection** — headless browsers, automation tools, CDP, Playwright, Puppeteer
-- **Anti-tamper** — proxy detection, descriptor integrity, prototype chain validation
-- **Anti-detect browser detection** — Multilogin, GoLogin, AdsPower
-- **Self-contained** — zero runtime dependencies, ~60KB gzipped
-- **All formats** — IIFE, ESM, CJS, UMD
+---
 
-## Quick Start
+## Get Started
 
-```html
-<script type="module">
-  const sentinel = import('https://your-domain.com/stl.esm.min.js')
-    .then(S => S.start({
-      apiKey: 'YOUR_API_KEY',
-      endpoint: 'https://your-domain.com/ingest'
-    }))
+Create a free account at **[danetix.com](https://danetix.com)** to get your API key.
 
-  sentinel
-    .then(s => s.get())
-    .then(result => {
-      console.log(result.requestId)
-      console.log(result.deviceId)
-    })
-</script>
-```
-
-## Installation
+### NPM
 
 ```bash
 npm install @danetix/sentinel
-# or
-pnpm add @danetix/sentinel
-# or
-yarn add @danetix/sentinel
 ```
 
-## Usage
-
-### ESM (recommended)
-
 ```js
-import { start } from '@danetix/sentinel'
+import Sentinel from '@danetix/sentinel'
 
-const sentinel = start({
-  apiKey: 'YOUR_API_KEY',
-  endpoint: 'https://your-domain.com/ingest',
-  cache: { ttl: 300 }   // optional: cache results for 5 minutes
+// Initialize at application startup
+const stl = Sentinel.start({
+  apiKey: 'your-api-key',
+  endpoint: 'https://your-domain.com/ingest'
 })
 
-const result = await sentinel.get()
-console.log(result.deviceId)
+// Get the device identifier when you need it
+const result = await stl.get()
+console.log(result.deviceId) // → "Abs2d8F0gTk9l..."
 ```
 
-### Script Tag
+### CDN
 
 ```html
-<script src="https://your-domain.com/stl.min.js"></script>
 <script>
-  var sentinel = Sentinel.start({
-    apiKey: 'YOUR_API_KEY',
-    endpoint: '/ingest'
-  })
-
-  sentinel.get().then(function(result) {
-    console.log(result.deviceId)
-  })
+  const stlPromise = import('https://your-domain.com/stl.esm.min.js')
+    .then(S => S.start({
+      apiKey: 'your-api-key',
+      endpoint: '/ingest'
+    }))
+
+  stlPromise
+    .then(stl => stl.get())
+    .then(result => console.log(result.deviceId))
 </script>
 ```
 
-### SPA (Single Page Application)
+---
+
+## Caching
+
+Enable caching to avoid redundant requests in single-page applications:
 
 ```js
-const sentinel = start({
-  apiKey: 'YOUR_API_KEY',
+const stl = Sentinel.start({
+  apiKey: 'your-api-key',
   endpoint: '/ingest',
-  cache: { ttl: 300, location: 'sessionStorage' }
-})
-
-// Call on each route change
-router.afterEach(() => {
-  sentinel.get()
+  cache: {
+    ttl: 300,                  // seconds
+    location: 'sessionStorage' // or 'memory' (default), 'localStorage'
+  }
 })
-
-// Force fresh request
-sentinel.get({ ignoreCache: true })
-
-// Clear cache manually
-sentinel.clearCache()
 ```
 
-## API
-
-### `start(options): SentinelInstance`
-
-Initialize the SDK. Starts signal collection immediately.
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiKey` | `string` | *required* | Workspace API key |
-| `endpoint` | `string` | *required* | Ingest endpoint URL |
-| `cache` | `CacheOptions` | — | Enable result caching |
-| `cache.ttl` | `number` | `0` | Cache TTL in seconds |
-| `cache.location` | `'memory' \| 'localStorage' \| 'sessionStorage'` | `'memory'` | Cache storage |
-| `debug` | `boolean` | `false` | Enable debug logging |
-| `proxyDetection` | `'light' \| 'high'` | `'high'` | Anti-detect detection mode |
-
-### `SentinelInstance.get(options?): Promise<CaptureResult>`
-
-Capture device signals, send to endpoint, return result.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `ignoreCache` | `boolean` | Skip cache, force fresh request |
-| `linkedId` | `string` | Custom identifier (user login, order ID) |
-| `tag` | `Record<string, unknown>` | Custom metadata |
-
-### `SentinelInstance.clearCache(): void`
-
-Clear cached result. Next `.get()` will make a fresh request.
-
-### `CaptureResult`
-
-```ts
-{
-  requestId: string       // Unique event ID
-  deviceId: string        // Stable device identifier
-  signedDeviceToken: string  // Signed token for persistence
-}
+```js
+await stl.get()                        // → server request
+await stl.get()                        // → instant (cached)
+await stl.get({ ignoreCache: true })   // → force fresh request
+stl.clearCache()                       // → invalidate manually
 ```
 
-## Browser Support
-
-| Browser | Version |
-|---------|---------|
-| Chrome | 80+ |
-| Firefox | 113+ |
-| Safari | 16.4+ |
-| Edge | 80+ |
-| Samsung Internet | 14+ |
-
-## Bundle Sizes
-
-| Format | File | Size | Gzipped |
-|--------|------|------|---------|
-| IIFE | `stl.min.js` | 190 KB | ~60 KB |
-| ESM | `stl.esm.min.js` | 196 KB | ~62 KB |
-| CJS | `stl.cjs.min.js` | 196 KB | ~62 KB |
-| UMD | `stl.umd.min.js` | 190 KB | ~60 KB |
-
-## License
-
-Proprietary. See LICENSE for details.
-
 ---
 
-# @danetix/sentinel (RU)
+## API Reference
 
-SDK для анализа устройств от [Danetix](https://danetix.com). Собирает 155+ сигналов браузера для идентификации устройств, обнаружения ботов и защиты от подмены.
+### `Sentinel.start(options)`
 
-## Быстрый старт
+Returns a `SentinelInstance`.
 
-```html
-<script type="module">
-  const sentinel = import('https://your-domain.com/stl.esm.min.js')
-    .then(S => S.start({
-      apiKey: 'ВАШ_API_КЛЮЧ',
-      endpoint: 'https://your-domain.com/ingest'
-    }))
+| Parameter | Type | Required | Description |
+|:----------|:-----|:---------|:------------|
+| `apiKey` | `string` | Yes | Your API key |
+| `endpoint` | `string` | Yes | Ingest endpoint URL |
+| `cache.ttl` | `number` | — | Cache lifetime in seconds |
+| `cache.location` | `string` | — | `'memory'` \| `'localStorage'` \| `'sessionStorage'` |
 
-  sentinel
-    .then(s => s.get())
-    .then(result => {
-      console.log(result.requestId)
-      console.log(result.deviceId)
-    })
-</script>
-```
+### `stl.get(options?)`
 
-## Установка
+Returns `Promise<Result>`.
 
-```bash
-npm install @danetix/sentinel
-```
+| Parameter | Type | Description |
+|:----------|:-----|:------------|
+| `ignoreCache` | `boolean` | Skip cache |
+| `linkedId` | `string` | Link to your own user/session ID |
+| `tag` | `object` | Attach custom metadata |
 
-## Использование в SPA
+### Result
 
 ```js
-import { start } from '@danetix/sentinel'
-
-const sentinel = start({
-  apiKey: 'ВАШ_API_КЛЮЧ',
-  endpoint: '/ingest',
-  cache: { ttl: 300, location: 'sessionStorage' }
-})
-
-// Вызывать при каждой смене роута
-router.afterEach(() => sentinel.get())
+{
+  requestId: "abc123...",          // unique event ID
+  deviceId: "Abs2d8F0gTk9l...",   // stable device identifier
+  signedDeviceToken: "eyJ..."     // signed token for verification
+}
 ```
 
-## Опции кеширования
+---
 
-| Опция | Тип | Описание |
-|-------|-----|----------|
-| `ttl` | `number` | Время жизни кеша в секундах |
-| `location` | `'memory' \| 'localStorage' \| 'sessionStorage'` | Где хранить кеш |
+## Browser Support
 
-Без `cache` — каждый `.get()` отправляет запрос на сервер.
+| | Chrome | Firefox | Safari | Edge | Samsung Internet |
+|:-|:------:|:-------:|:------:|:----:|:----------------:|
+| **Version** | 80+ | 113+ | 16.4+ | 80+ | 14+ |
 
-## Лицензия
+---
 
-Проприетарная. Подробности в файле LICENSE.
+<p align="center">
+  <sub>Copyright &copy; 2026 Danetix. All rights reserved.</sub>
+</p>