is-incognito-mode 1.1.0 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+## 2.0.1
+
+### Patch Changes
+
+- Docs and housekeeping pass following the v2.0.0 release.
+  - README leads with a 30-second tour before the "why" section so readers see
+    action first; the detection-flow Mermaid diagram is collapsible; use-cases
+    promoted to a scenario table; fixed a stale code-sample strategy name
+    (`storage-quota`, not `storage-estimate`).
+  - Removed unused `detectCurrentBrowser()` export (no production caller) and
+    the corresponding test. Only `detectBrowser()` taking explicit args is used.
+  - Removed the never-returned `'unknown'` member from `DetectionStrategyName`.
+  - `.gitignore` adds `.claude/`.
+
+## 2.0.0
+
+### Major Changes
+
+- 11770a6: ## v2.0.0 — complete modernization
+
+  The detection vectors used by v1 (FileSystem API, IndexedDB error, localStorage
+  exception, PointerEvent heuristics) have all been patched out of mainline
+  browsers since 2019. v2 replaces them with `navigator.storage.estimate()` quota
+  thresholding, which is the current state-of-the-art technique and works across
+  Chromium, Firefox, and WebKit.
+
+  Other changes:
+  - Source rewritten in strict TypeScript. Full `.d.ts` ship.
+  - Dual ESM + CJS publish with a proper `exports` map. UMD bundle removed.
+  - New named exports: `detectIncognito()` (rich result), `IncognitoDetectionError`
+    (typed errors with `code`), `DEFAULT_PRIVATE_QUOTA_BYTES`.
+  - The default export is preserved for v1 drop-in compatibility.
+  - Zero runtime dependencies (was: `get-browser`).
+  - `engines.node >= 20`.
+
+  See `BREAKING_CHANGES.md` for migration recipes.
+
+All notable changes to this project are documented in this file. From v2.0.0
+onward, entries are generated by [Changesets](https://github.com/changesets/changesets);
+historical pre-v2 entries are preserved as-is.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [2.0.0] — Unreleased
+
+> Generated from the pending changeset at release time. See
+> `BREAKING_CHANGES.md` for migration recipes.
+
+### Added
+
+- `detectIncognito()` returning a rich `DetectionResult` (browser, confidence,
+  quota, strategy).
+- `IncognitoDetectionError` with stable `code` literal-union (`NOT_A_BROWSER`
+  / `UNSUPPORTED_BROWSER` / `PROBE_FAILED`).
+- `DEFAULT_PRIVATE_QUOTA_BYTES` and a `privateQuotaThresholdBytes` option for
+  tuning the detector.
+- TypeScript types ship with the package.
+- Dual ESM + CJS publish; `exports` map; npm provenance.
+
+### Changed
+
+- **Detection technique** rewritten around `navigator.storage.estimate()` quota
+  probing. The v1 vectors (FileSystem API, IndexedDB error path, localStorage
+  exception, PointerEvent heuristics) were patched by browser vendors between
+  2019 and 2023 and were returning incorrect results in current browsers.
+- Build chain replaced (Webpack 4 / Babel 7 → tsup / esbuild).
+- Package manager pinned to pnpm via `packageManager`.
+- `engines.node` bumped to `>= 20`.
+
+### Removed
+
+- UMD bundle (`dist/isIncognito.js`). Use the ESM build via a CDN for direct
+  `<script>` usage.
+- The `get-browser` runtime dependency (zero deps now).
+
+---
+
+## [1.1.0] — 2019
+
+- Update Firefox detection to fire callback correctly.
+- Update `get-browser` to correctly identify Chromium.
+
+## [1.0.0] — 2019
+
+- Initial public release.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Aliaksandr Yankouski
+Copyright (c) 2019-2026 Aliaksandr Yankouski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,75 +1,335 @@
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/yankouskia/is-incognito-mode/pulls) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/yankouskia/is-incognito-mode/blob/master/LICENSE)
+<div align="center">
 
-[![NPM](https://nodei.co/npm/is-incognito-mode.png?downloads=true)](https://www.npmjs.com/package/is-incognito-mode)
+# `is-incognito-mode`
 
-# is-incognito-mode
+### **Detect private / incognito browsing in 4 lines of code.**
 
-👤Function to identify whether browser is in incognito mode 👀
+_Zero dependencies — fully typed — dual ESM + CJS — ~1 kB gzipped._
 
-## How to use
+[![npm version](https://img.shields.io/npm/v/is-incognito-mode.svg?logo=npm&color=cb3837)](https://www.npmjs.com/package/is-incognito-mode)
+[![npm downloads](https://img.shields.io/npm/dm/is-incognito-mode.svg?color=cb3837)](https://www.npmjs.com/package/is-incognito-mode)
+[![CI](https://github.com/yankouskia/is-incognito-mode/actions/workflows/ci.yml/badge.svg)](https://github.com/yankouskia/is-incognito-mode/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen?logo=vitest)](./coverage)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/is-incognito-mode?label=min%2Bgzip&color=44cc11)](https://bundlephobia.com/package/is-incognito-mode)
+[![Types](https://img.shields.io/npm/types/is-incognito-mode.svg?logo=typescript&color=3178c6)](./src/index.ts)
+[![License](https://img.shields.io/npm/l/is-incognito-mode.svg?color=blue)](./LICENSE)
 
-To install library:
+<br />
+
+### **[Try the live demo →](https://yankouskia.github.io/is-incognito-mode/demo/)**
+
+_Open it in a normal window. Then re-open it in private/incognito mode. Watch the verdict flip._
+
+<br />
+
+</div>
+
+---
+
+## 30-second tour
 
 ```sh
-# yarn
-yarn add is-incognito-mode
+npm install is-incognito-mode
+```
+
+```ts
+import { isIncognito } from 'is-incognito-mode';
 
-# npm
-npm install is-incognito-mode --save
+if (await isIncognito()) {
+  showPaywall();
+} else {
+  trackVisit();
+}
 ```
 
-```js
-// ES6 modules
-import isIncognito from 'is-incognito-mode';
-
-// CommonJS modules
-const isIncognito = require('is-incognito-mode').default;
-
-/*
-  Function returns Promise, which could be:
-  - resolved with true, if Incognito mode is opened
-  - resolved with false, if regular window is opened
-  - rejected if no possibility to identify
-*/
-isIncognito()
-  .then(isPrivate => {
-    if (isPrivate) {
-      alert('There is no porn! Why are you using Incognito mode?');
-    } else {
-      console.log('Incognito mode is NOT activated')
+That's it. **One async call, one boolean.** Works on Chrome, Firefox, Safari,
+Edge, and (best-effort) the long tail of older WebKit shells.
+
+Need more than a yes/no? Use [`detectIncognito()`](#rich-detection-result) for
+a typed object with `browser`, `confidence`, `quota`, and `strategy` fields.
+
+---
+
+## Why you'd use this
+
+Browsers don't expose a "private mode" API on purpose — but private windows
+still leak the fact through **resource limits** and **storage shape**.
+`is-incognito-mode` packages the current state-of-the-art detection (quota
+probing via `navigator.storage.estimate()`) as a tiny, typed, zero-dep module,
+so you can stop hand-rolling heuristics that browsers patched out in 2019.
+
+A few real-world fits:
+
+| Scenario                  | What you do                                                 |
+| ------------------------- | ----------------------------------------------------------- |
+| **Soft paywall**          | Discourage incognito bypass without hard-blocking the user. |
+| **Respectful analytics**  | Skip beacon calls in private sessions to honor the signal.  |
+| **Long forms / surveys**  | Warn before storing state that will vanish on close.        |
+| **Fraud / abuse signals** | One input among many — never the sole decider.              |
+| **E2E test conditioning** | Branch tests based on whether you're driving a private tab. |
+
+---
+
+## Install
+
+```sh
+pnpm add is-incognito-mode      # or  npm i is-incognito-mode
+                                # or  yarn add is-incognito-mode
+                                # or  bun add is-incognito-mode
+```
+
+**No-install — straight from a CDN**:
+
+```html
+<script type="module">
+  import { isIncognito } from 'https://esm.sh/is-incognito-mode@2';
+  console.log(await isIncognito());
+</script>
+```
+
+---
+
+## See it run
+
+A ready-to-run demo page is hosted alongside the docs:
+
+> **https://yankouskia.github.io/is-incognito-mode/demo/**
+
+Open it once in a regular window, then once in incognito/private — the
+verdict, browser, confidence, quota, and strategy update live.
+Source: [`examples/browser/index.html`](./examples/browser/index.html) (single
+static file, no build step).
+
+---
+
+## How it decides (under the hood)
+
+The library tries the cleanest signal first and falls back to engine-specific
+probes for older browsers. Click to expand:
+
+<details>
+<summary>Detection flow diagram</summary>
+
+```mermaid
+flowchart TD
+    A[detectIncognito] --> B{navigator.storage<br/>.estimate available?}
+    B -- yes --> C{quota &lt; 120 MiB?}
+    C -- yes --> R1([private — high confidence])
+    C -- no --> R2([normal — high confidence])
+    B -- no --> D{which browser?}
+    D -- Safari/WebKit --> E[localStorage probe<br/>+ openDatabase probe]
+    D -- Firefox --> F[indexedDB.open error path]
+    D -- Edge legacy / IE --> G[PointerEvent + window.indexedDB heuristic]
+    D -- unknown --> X([throw UNSUPPORTED_BROWSER])
+    E --> R3([private/normal — medium])
+    F --> R4([private/normal — low])
+    G --> R5([private/normal — low])
+```
+
+</details>
+
+The default threshold is **120 MiB** — Chromium gives incognito tabs ~10 % of
+disk capped at 120 MiB, and Firefox / Safari private modes cap similarly.
+Devices with very small total storage can hit false positives; raise the
+threshold or lower-bound against `navigator.deviceMemory * 1 GiB` if that
+matters to you.
+
+---
+
+## Usage
+
+### Boolean verdict
+
+```ts
+import { isIncognito } from 'is-incognito-mode';
+
+const inPrivate = await isIncognito();
+```
+
+### Rich detection result
+
+```ts
+import { detectIncognito } from 'is-incognito-mode';
+
+const { isPrivate, browser, confidence, quota, strategy } =
+  await detectIncognito();
+
+console.log(
+  `${browser} (${confidence}) — strategy: ${strategy}, quota: ${quota}`,
+);
+// → "chromium (high) — strategy: storage-quota, quota: 33554432"
+```
+
+Fields on `DetectionResult`:
+
+| field        | type                          | notes                                                                                     |
+| ------------ | ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `isPrivate`  | `boolean`                     | Final verdict.                                                                            |
+| `browser`    | `BrowserName`                 | Coarse engine: `chromium`, `firefox`, `safari`, `webkit`, `edge-legacy`, `ie`, `unknown`. |
+| `confidence` | `'high' \| 'medium' \| 'low'` | `high` for direct quota signal; `low` for legacy heuristics.                              |
+| `quota`      | `number \| null`              | Total storage quota in bytes, when `storage.estimate()` was available.                    |
+| `strategy`   | `DetectionStrategyName`       | Which probe produced the verdict.                                                         |
+
+### Tuning the quota threshold
+
+```ts
+import {
+  detectIncognito,
+  DEFAULT_PRIVATE_QUOTA_BYTES,
+} from 'is-incognito-mode';
+
+const result = await detectIncognito({
+  privateQuotaThresholdBytes: DEFAULT_PRIVATE_QUOTA_BYTES * 2,
+});
+```
+
+Default is **120 MiB**. Raise it if you see false positives on small-disk
+devices.
+
+### Injecting globals (for testing)
+
+`detectIncognito` accepts a `globals` override so unit tests don't have to
+monkey-patch `navigator` or `window`:
+
+```ts
+import { detectIncognito } from 'is-incognito-mode';
+
+const result = await detectIncognito({
+  globals: {
+    navigator: {
+      userAgent: 'Mozilla/5.0 ... Chrome/131.0',
+      storage: {
+        estimate: () => Promise.resolve({ quota: 32 * 1024 * 1024 }),
+      },
+    },
+    window: {},
+  },
+});
+// result.isPrivate === true
+```
+
+### Error handling
+
+```ts
+import { isIncognito, IncognitoDetectionError } from 'is-incognito-mode';
+
+try {
+  const incognito = await isIncognito();
+  // ...
+} catch (error) {
+  if (error instanceof IncognitoDetectionError) {
+    switch (error.code) {
+      case 'NOT_A_BROWSER':
+        // Server-side render path
+        break;
+      case 'UNSUPPORTED_BROWSER':
+        // Probably a bot / curl / node-fetch
+        break;
+      case 'PROBE_FAILED':
+        // Storage API rejected, no fallback applied
+        break;
     }
-  })
-  .catch(e => {
-    console.log(e.message);
-  })
+  }
+}
+```
+
+### CommonJS
+
+```js
+const { isIncognito } = require('is-incognito-mode');
+
+// Default-import-style:
+const detect = require('is-incognito-mode').default;
 ```
 
+---
+
+## API at a glance
+
+| Export                          | Kind     | Description                                                                          |
+| ------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| `isIncognito(options?)`         | function | Resolves to `boolean`.                                                               |
+| `detectIncognito(options?)`     | function | Resolves to a rich `DetectionResult`.                                                |
+| `IncognitoDetectionError`       | class    | Typed error with `code: 'NOT_A_BROWSER' \| 'UNSUPPORTED_BROWSER' \| 'PROBE_FAILED'`. |
+| `DEFAULT_PRIVATE_QUOTA_BYTES`   | const    | Default threshold (`120 × 1024 × 1024`).                                             |
+| `BrowserName` (type)            | type     | Coarse engine name.                                                                  |
+| `DetectionResult` (type)        | type     | Rich result shape — see "Usage".                                                     |
+| `DetectionConfidence` (type)    | type     | `'high' \| 'medium' \| 'low'`.                                                       |
+| `DetectionStrategyName` (type)  | type     | Strategy identifier.                                                                 |
+| `DetectIncognitoOptions` (type) | type     | Options bag.                                                                         |
 
-## Demo
+Full generated reference: **<https://yankouskia.github.io/is-incognito-mode/>**
 
-[DEMO can be found here](https://yankouskia.github.io/is-incognito-mode/example/index.html)
+---
 
+## Compatibility
 
-Incognito Window            |  Regular Window
-:-------------------------:|:-------------------------:
-<img src="./resources/private.png" data-canonical-src="./resources/private.png" width="300" />  |  <img src="./resources/public.png" data-canonical-src="./resources/public.png" width="300" />
+### Browsers
 
+| Engine                 | Detection strategy              | Confidence |
+| ---------------------- | ------------------------------- | ---------- |
+| Chromium ≥ 80          | `navigator.storage.estimate`    | high       |
+| Firefox ≥ 75           | `navigator.storage.estimate`    | high       |
+| Safari ≥ 13            | `navigator.storage.estimate`    | high       |
+| Older Safari / WebKit  | `localStorage` + `openDatabase` | medium-low |
+| Older Firefox          | `indexedDB.open` error path     | low        |
+| Edge (legacy)          | `PointerEvent` heuristic        | low        |
+| IE 10–11               | `PointerEvent` heuristic        | low        |
+| All others (`unknown`) | throws `UNSUPPORTED_BROWSER`    | —          |
 
-## API
+### Node / runtimes
 
-`isIncognito: Promise<boolean>`
+Not supported at runtime — this is a **browser-only** package and will throw
+`NOT_A_BROWSER` if invoked without a `navigator`. The package _builds_ on
+Node ≥ 20.
 
-Result `Promise` is
-  - resolved with `true`, if Incognito mode is opened.
-  - resolved with `false`, if regular window is opened
-  - rejected if no possibility to identify
+### Bundlers & frameworks
 
+Ships ESM and CJS with proper `exports` map and `.d.ts` / `.d.cts`. Works
+out-of-the-box in Vite, Next.js (client components), Remix, Astro, Webpack,
+Rollup, esbuild, Bun, and Deno.
+
+---
+
+## What's new in v2
+
+|                     | v1.x                                                     | v2.0                                                         |
+| ------------------- | -------------------------------------------------------- | ------------------------------------------------------------ |
+| Detection technique | FileSystem API + IndexedDB + localStorage + PointerEvent | `navigator.storage.estimate()` quota (with legacy fallbacks) |
+| TypeScript          | shipped JS only                                          | strict TypeScript source, full `.d.ts`                       |
+| Module formats      | UMD + CJS                                                | ESM + CJS dual publish                                       |
+| Dependencies        | `get-browser`                                            | **zero**                                                     |
+| Bundle size         | ~3 kB min+gzip                                           | **~1 kB min+gzip**                                           |
+| Engines             | Node ≥ 8                                                 | Node ≥ 20                                                    |
+| Error model         | `throw 'string'`                                         | `IncognitoDetectionError` with `code`                        |
+
+See [`BREAKING_CHANGES.md`](./BREAKING_CHANGES.md) for migration recipes
+and [`DECISIONS.md`](./DECISIONS.md) for the reasoning behind each big call.
+
+---
+
+## Comparison with alternatives
+
+- **[`detectincognitojs`](https://github.com/Joe12387/detectIncognito)** —
+  excellent, similar in spirit. Pick that if you want a UMD bundle or a richer
+  per-browser breakdown.
+- **Inline UA sniff + `try/catch` around `localStorage`** — broken in every
+  modern browser. Don't.
+- **Just check `window.webkitRequestFileSystem`** — patched out of Chrome 76.
+  Don't.
+
+---
 
 ## Contributing
 
-`is-incognito-mode` is open-source library, opened for contributions
+Pull requests welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the dev
+loop, conventional commits, and the changeset workflow. Be excellent — the
+[Contributor Covenant 2.1](./CODE_OF_CONDUCT.md) applies.
+
+## Security
 
+Report vulnerabilities privately per [`SECURITY.md`](./SECURITY.md).
 
-### License
+## License
 
-`is-incognito-mode` is [MIT licensed](https://github.com/yankouskia/is-incognito-mode/blob/master/LICENSE)
+[MIT](./LICENSE) © Aliaksandr Yankouski