@indiebob/tracker 0.3.0 → 0.4.1

package/README.md

@@ -1,574 +1,178 @@
 # @indiebob/tracker
 
-Privacy-first analytics SDK for web applications. Under 5KB gzipped. No cookies. GDPR/CCPA/GPC compliant.
+The analytics script for [IndieBob](https://www.indiebob.com): page views, traffic sources, events,
+signups and revenue. About 5.7 KB gzipped, no dependencies, no cookies. By default it stores nothing
+in the visitor's browser.
 
-## Installation
+## Install
 
-```bash
-npm install @indiebob/tracker
-# or
-pnpm add @indiebob/tracker
-```
-
-Or via script tag (CDN) — one line, nothing else to write:
+**Script tag** — one line before `</head>`. It counts every page, including navigation in a
+single-page app.
 
 ```html
-<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js" data-project="proj_your16charId" defer></script>
-```
-
-The tag initialises itself from `data-project` and tracks this page plus every
-SPA navigation. See [Script tag](#vanilla-js-script-tag) for the options.
-
-## Quick Start
-
-Three lines to start tracking:
-
-```js
-import { IndieBob } from '@indiebob/tracker'
-
-const bob = IndieBob.init({ projectId: 'proj_your16charId' })
-bob.page()
+<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js" data-project="proj_…" defer></script>
 ```
 
-That's it. Page views are now tracked. UTM parameters are auto-captured.
-
-## Configuration
-
-```ts
-const bob = IndieBob.init({
-  projectId: 'proj_your16charId',  // Required. From your IndieBob dashboard.
-  endpoint: 'https://indiebob.com/api/collect',  // Optional. Default shown.
-  debug: false,           // Optional. Logs events to console when true.
-  respectDnt: true,       // Optional. Honor browser Do Not Track. Default: true.
-  respectGpc: true,       // Optional. Honor Global Privacy Control. Default: true.
-  autoDetect: true,       // Optional. Auto-detect signups, logins, checkouts, etc. Default: true.
-  hashMode: false,        // Optional. Treat the URL hash as part of the path (/#/route routers). Default: false.
-})
-```
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `projectId` | `string` | **required** | Your SDK project ID from the dashboard |
-| `endpoint` | `string` | `'https://indiebob.com/api/collect'` | Override for self-hosted instances |
-| `debug` | `boolean` | `false` | Log all events to browser console |
-| `respectDnt` | `boolean` | `true` | Honor the browser's Do Not Track header |
-| `respectGpc` | `boolean` | `true` | Honor Global Privacy Control signal (legally binding in CA/GDPR) |
-| `autoDetect` | `boolean \| object` | `true` | Auto-detect user intent from URL patterns, form submissions, outbound clicks, file downloads, and data attributes. See [Auto-Detection](#auto-detection). |
-| `hashMode` | `boolean` | `false` | Count a hash-only change as a new page and report the hash in the path. For hash routers (`/#/settings`). |
-
-## API Reference
-
-### `IndieBob.init(config)`
+| Attribute | |
+|---|---|
+| `data-project` | Your project id (IndieBob › your project › Connect). Required. |
+| `data-persistence="local"` | Full attribution (see below). Only with the visitor's consent. |
+| `data-hash-mode="true"` | Your routes live after a `#` (`/#/pricing`). |
+| `data-auto-page="false"` | Start the tracker but count pages yourself. |
+| `data-api="…"` | Send to another endpoint. |
 
-Creates and returns a tracker instance. Call once at app startup.
+**npm**
 
-```ts
-const bob = IndieBob.init({ projectId: 'proj_abc123def456ghij' })
+```sh
+npm install @indiebob/tracker
 ```
 
-Calling `init()` again with the same `projectId` returns the instance that is
-already running (the first config wins), so nothing is ever counted twice —
-for example a `data-project` script tag plus your own `init()` call.
-
----
-
-### `bob.page(overrides?)`
-
-Track a page view. Call this on every page load and SPA navigation.
-
 ```ts
-bob.page()                           // Auto-detects path, title, referrer
-bob.page({ path: '/pricing' })       // Override path
-bob.page({ title: 'Pricing Page' }) // Override title
-```
-
-**Auto-detected:** URL path, page title, referrer, UTM parameters, device type.
-
-A `page()` for the path you are already on (same pathname + query) is skipped,
-so a framework hook that fires twice, or a hash-only change, never counts a
-second view. A page restored from the back/forward cache counts again. A page
-that is prerendered or opened in a background tab is counted when it is first
-shown, not before.
-
----
-
-### `bob.track(event, properties?)`
-
-Track a custom event.
+import { IndieBob } from '@indiebob/tracker'
 
-```ts
-bob.track('signup_started')
-bob.track('trial_activated', { plan: 'pro' })
-bob.track('feature_used', { feature: 'csv_export', count: 3 })
-bob.track('checkout_completed', { revenue: 29.00, currency: 'USD', plan: 'pro-monthly' })
+const bob = IndieBob.init({ projectId: 'proj_…' })
+bob.page()
 ```
 
-**`event`** — string, required. Max 256 characters. Use `snake_case` by convention.
+## Privacy mode and full attribution
 
-**`properties`** — plain object, optional. Values must be JSON-serializable.
-
----
+|  | Privacy mode (default) | Full attribution |
+|---|---|---|
+| Stored in the visitor's browser | nothing | a visitor id, a session id, the first and last UTM, the first referrer |
+| A visitor is recognised | for one day | across days |
+| A signup is credited to a visit on an earlier day | no | yes |
+| Needs the visitor's consent in the EU | no | yes |
 
-### `bob.identify(userId, traits?)`
+In privacy mode IndieBob's server identifies a visitor by hashing a random daily salt together with
+the project, the IP address and the user agent. Each day's salt is deleted, and the IP address is
+not stored.
 
-Associate the current anonymous visitor with a known user ID. Call this after login or signup.
+Full attribution stores an id on the visitor's device, which needs consent in the EU (ePrivacy
+Directive, Art. 5(3); localStorage counts the same as a cookie). Switch it on from your consent
+banner:
 
 ```ts
-bob.identify('user_123', {
-  email: 'jane@example.com',
-  name: 'Jane Smith',
-  plan: 'pro',
-  createdAt: '2026-01-15',
-})
+bob.setPersistence('local')  // the visitor accepted
+bob.setPersistence('none')   // consent withdrawn: removes everything the tracker stored
 ```
 
-**`userId`** — string, required. Your internal user ID. Never pass PII as the userId directly.
-
-**`traits`** — plain object, optional. Can include `email` for attribution linking.
-
-After `identify()`, all subsequent events are linked to this userId until the session ends.
-
----
-
-### `bob.revenue(data)`
+If consent is already known when the page loads, pass `persistence: 'local'` to `init()` or put
+`data-persistence="local"` on the tag.
 
-Track a revenue event. Use alongside Stripe webhooks for complete attribution.
+## Configuration
 
 ```ts
-bob.revenue({
-  amount: 29.00,           // Required. Positive number.
-  currency: 'USD',         // Optional. Default: 'USD'. ISO 4217 code.
-  plan: 'pro-monthly',     // Optional. Your plan name.
-  type: 'new',             // Optional. 'new' | 'renewal' | 'upgrade' | 'downgrade'
+IndieBob.init({
+  projectId: 'proj_…',        // required
+  persistence: 'none',        // 'none' (privacy mode) | 'local' (full attribution)
+  autoDetect: true,           // automatic events, below; false turns them off
+  hashMode: false,            // routes after a #
+  respectDnt: true,           // send nothing when Do Not Track is on
+  respectGpc: true,           // send nothing when Global Privacy Control is on
+  endpoint: 'https://www.indiebob.com/api/collect',
+  debug: false,               // log every event to the console
 })
 ```
 
----
-
-### Privacy Controls
-
-```ts
-bob.optOut()       // Stop all tracking. Clears all stored identifiers.
-bob.optIn()        // Re-enable tracking.
-bob.isOptedOut()   // Returns boolean.
-bob.isIgnored()    // True if this browser excluded itself with ?ib_ignore=1.
-```
-
-### Exclude your own visits (`ib_ignore`)
+A misspelled or unknown option logs a warning instead of being silently ignored.
 
-Open your site once with `?ib_ignore=1` on the URL
-(`https://yoursite.com/?ib_ignore=1`). That browser stops being counted — on
-every page, from then on — and the console says
-`IndieBob: this browser is excluded from analytics (ib_ignore)` on each page
-load so you can see it working. Open any page with `?ib_ignore=0` to be counted
-again. It is stored in `localStorage` as `ib_ignore`, so it is per browser and
-per site. Your identifiers are kept (unlike `optOut()`).
+## API
 
-Browsers driven by automation (`navigator.webdriver` — Playwright, Selenium,
-Puppeteer, headless test runners) send nothing at all.
-
----
-
-### Debug / Testing
-
-```ts
-bob.getAnonymousId()  // Returns the current anonymous ID
-bob.getSessionId()    // Returns the current session ID
-bob.getConfig()       // Returns a read-only copy of the config
-bob.flush()           // Force-send all queued events immediately
-```
-
----
-
-## Auto-Detection
-
-The SDK automatically fires semantic events out of the box — no manual `bob.track()` calls needed for common user journeys. This powers IndieBob's attribution funnels (visit → signup → checkout → paid).
-
-### URL Intent Detection
-
-When `bob.page()` is called, the SDK checks the URL path against known patterns (multilingual: EN, ES, FR, DE, PT, IT, NL) and fires the corresponding event:
-
-| Event | Triggered By |
+| Call | |
 |---|---|
-| `signup_start` | `/signup`, `/register`, `/join`, `/registro`, `/inscription`, `/anmeldung`, ... |
-| `login_view` | `/login`, `/sign-in`, `/iniciar-sesion`, `/connexion`, `/anmelden`, ... |
-| `pricing_view` | `/pricing`, `/plans`, `/precios`, `/tarifs`, `/preise`, ... |
-| `checkout_view` | `/checkout`, `/cart`, `/basket`, `/panier`, `/warenkorb`, `/kasse`, ... |
-| `success_view` | `/success`, `/thank-you`, `/confirmation`, `/danke`, `/merci`, ... |
-| `onboarding_view` | `/onboarding`, `/welcome`, `/getting-started`, `/bienvenido`, ... |
-| `contact_view` | `/contact`, `/contacto`, `/kontakt`, `/nous-contacter`, ... |
-
-### Signup vs Login Detection
-
-When `bob.identify()` is called:
-- **First call** for this visitor fires `signup` (new user)
-- **Subsequent calls** fire `login` (returning user)
-
-This uses a localStorage flag — no server round-trip needed.
-
-### Form Submit Detection
-
-On signup, login, and checkout pages, form submissions are automatically tracked:
-- `signup_submit` — form submitted on a signup page
-- `login_submit` — form submitted on a login page
-- `checkout_submit` — form submitted on a checkout page
-
-### Outbound Click Tracking
-
-Clicks on links pointing to external domains automatically fire `outbound_click` with `{ url, hostname }` properties.
-
-### File Download Tracking
-
-A click on a link whose path ends in a file extension fires `file_download`
-with `{ url, path, ext }` — on your own host or any other (a GitHub release,
-a CDN). `url` is the link without its query string or hash, so a signed
-download token never reaches your analytics. A download on another host fires
-only `file_download`, not `outbound_click` as well.
-
-Extensions: `pdf zip dmg exe msi pkg apk ipa deb rpm appimage gz tgz bz2 xz
-tar 7z rar csv xls xlsx doc docx ppt pptx txt epub mp3 wav mp4 mov iso`.
-
-```html
-<a href="/downloads/MyApp-2.1.dmg">Download for Mac</a>
-<!-- → track('file_download', { url: 'https://yoursite.com/downloads/MyApp-2.1.dmg',
-                                path: '/downloads/MyApp-2.1.dmg', ext: 'dmg', auto: true }) -->
-```
-
-Turn it off with `autoDetect: { fileDownloads: false }`.
-
-### Engagement (time on page and scroll depth)
-
-After `page()`, the SDK measures how long the page was **visible and focused**
-(a background tab or another focused window does not count) and how far down
-it was read (the deepest point seen, as a percentage of the page height). It
-sends this as an `engagement` event — never a pageview — with the context of
-the page it describes:
-
-- when the tab is hidden or the page is closed (by beacon, like every last event);
-- right before an SPA navigation, for the page being left.
-
-It is sent only when there is something new: the scroll depth grew, or at
-least 3 seconds of engaged time accumulated since the last one. The counters
-start again for every page. Nothing to set up.
-
-### Data Attribute Tracking
-
-Add `data-ib-event` to any element for zero-JS custom event tracking:
-
-```html
-<button data-ib-event="add_to_cart" data-ib-plan="pro" data-ib-price="29">
-  Add to Cart
-</button>
-```
-
-This fires `track('add_to_cart', { plan: 'pro', price: '29' })` on click. All `data-ib-*` attributes (except `data-ib-event`) become event properties.
-
-### Customizing Auto-Detection
+| `IndieBob.init(config)` | Starts the tracker and returns it. Called again for the same project, it returns the running one. |
+| `bob.page(overrides?)` | Counts a page view. The same path twice in a row counts once. `overrides`: `{ path, title, referrer }`. |
+| `bob.track(name, properties?)` | A named event: `bob.track('csv_exported', { rows: 1240 })`. |
+| `bob.identify(userId, traits?, { isNew? })` | After signup or login. Links the visit to your user id and sends `signup` or `login`. Pass `isNew: true` after a registration and `false` on a login — in privacy mode it is required for the `signup`/`login` event. Use your own id, never an email address, as `userId`. |
+| `bob.revenue({ amount, currency, plan, type })` | A payment, if Stripe is not connected to IndieBob. `type`: `new`, `renewal`, `upgrade`, `downgrade`. |
+| `bob.setPersistence('none' \| 'local')` | Switches mode, above. |
+| `bob.enableAutoPage()` | Counts a page on every history change (the script tag does this itself). |
+| `bob.optOut()`, `bob.optIn()`, `bob.isOptedOut()` | The visitor's own opt-out; `optOut()` removes everything stored. |
+| `bob.isIgnored()` | Whether this browser is excluded with `?ib_ignore=1`. |
+| `bob.flush()` | Sends queued events now. |
+
+Events are sent in batches every 5 seconds and when the page is hidden or closed.
+
+## Collected automatically
+
+| Event | When |
+|---|---|
+| `page` | Every page view, including a page restored with the Back button. |
+| `engagement` | When a page is left or hidden: how long it was visible and focused, and how far it was scrolled. |
+| `outbound_click` | A link to another site is clicked. |
+| `file_download` | A link to a file (pdf, zip, dmg, exe, apk, …) is clicked. |
+| `signup_start`, `login_view`, `pricing_view`, `checkout_view`, `success_view`, `onboarding_view`, `contact_view` | The page's path matches `/signup`, `/login`, `/pricing`, … or their Spanish, French, German, Portuguese, Italian or Dutch words. |
+| `signup_submit`, `login_submit`, `checkout_submit` | A form is submitted on one of those pages. |
+| any name | An element with `data-ib-event="name"` is clicked; its other `data-ib-*` attributes become properties. |
 
-Override the default URL patterns or disable specific features:
+Turn parts off or replace the path patterns:
 
 ```ts
-const bob = IndieBob.init({
-  projectId: 'proj_abc123',
-  autoDetect: {
-    // Custom URL patterns — strings or RegExp (override defaults)
-    signupPaths: ['/my-signup-page'],         // string: matched via path.includes()
-    checkoutPaths: [/\/buy|\/purchase/i],     // RegExp: matched via .test()
-
-    // Disable specific features
-    outboundClicks: false,
-    fileDownloads: false,
-    formSubmit: false,
-    dataAttributes: false,
-  },
-})
+autoDetect: { fileDownloads: false, outboundClicks: false, formSubmit: false, dataAttributes: false,
+              signupPaths: [/\/start-trial/] }
 ```
 
-Set `autoDetect: false` to disable all auto-detection entirely.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `signupPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for signup pages |
-| `loginPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for login pages |
-| `pricingPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for pricing pages |
-| `checkoutPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for checkout/cart pages |
-| `successPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for success/thank-you pages |
-| `onboardingPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for onboarding pages |
-| `contactPaths` | `(string \| RegExp)[]` | built-in i18n | URL patterns for contact pages |
-| `dataAttributes` | `boolean` | `true` | Track clicks on `data-ib-event` elements |
-| `formSubmit` | `boolean` | `true` | Track form submissions on intent pages |
-| `outboundClicks` | `boolean` | `true` | Track clicks on external links |
-| `fileDownloads` | `boolean` | `true` | Track clicks on links to files as `file_download` |
-
----
-
-## Framework Integrations
-
-### Vue / Nuxt
-
-```ts
-// main.ts or plugins/tracker.client.ts
-import { IndieBobPlugin } from '@indiebob/tracker/vue'
-
-app.use(IndieBobPlugin, { projectId: 'proj_abc123def456ghij' })
-```
+## What is sent
 
-Then in any component:
+- The page's path and URL, keeping only the `utm_*` and `ref` query parameters. Anything else in a
+  query string — sign-in tokens, reset codes, email addresses, ad click ids — is removed before it
+  leaves the page, and IndieBob's server removes it again from older versions of the tracker.
+- The page title; the referrer's origin and path; the screen size class; the browser's language and
+  time zone; your event's properties.
+- IndieBob adds the country, region and city (looked up from the IP address, which is not stored),
+  the browser, the operating system and the device type.
 
-```ts
-import { useTracker } from '@indiebob/tracker/vue'
+Nothing is sent from a browser with Do Not Track or Global Privacy Control on, after `optOut()`,
+from automated browsers, or from your own browser once you open your site with `?ib_ignore=1`
+(`?ib_ignore=0` undoes it).
 
-const bob = useTracker()
-bob.track('button_clicked', { button: 'cta_hero' })
-```
+IndieBob processes this data for you, in the EU (Frankfurt). A data processing agreement is
+available from info@indiebob.com.
 
-**Nuxt plugin** (`plugins/tracker.client.ts`):
+## Vue and Nuxt
 
 ```ts
+// plugins/indiebob.client.ts (Nuxt) — or app.use(...) after the router in a Vue app
 import { IndieBobPlugin } from '@indiebob/tracker/vue'
 
 export default defineNuxtPlugin((nuxtApp) => {
-  nuxtApp.vueApp.use(IndieBobPlugin, {
-    projectId: useRuntimeConfig().public.trackerProjectId,
-  })
+  nuxtApp.vueApp.use(IndieBobPlugin, { projectId: 'proj_…' })
 })
 ```
 
-Page views auto-track on vue-router navigation.
-
-### React
+Page views follow vue-router. In a component: `const bob = useTracker()` from
+`@indiebob/tracker/vue`.
 
-```tsx
-import { IndieBob } from '@indiebob/tracker'
-import { useEffect } from 'react'
+## React
 
-// Initialize once at app root
-const bob = IndieBob.init({ projectId: 'proj_abc123def456ghij' })
+There is no React package; call `page()` when the route changes:
 
-// In a page component or layout
-useEffect(() => {
-  bob.page()
-}, [pathname])
-```
-
-### Vanilla JS (Script Tag)
-
-One tag, before `</head>` on every page:
-
-```html
-<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js" data-project="proj_abc123def456ghij" defer></script>
-```
-
-It initialises itself and tracks the page plus every SPA navigation
-(`pushState` / back / forward) — no `init()` or `page()` call. Attributes:
-
-| Attribute | Meaning |
-|---|---|
-| `data-project` | Your project ID. Without it the tag does nothing on its own. |
-| `data-api` | Ingestion endpoint override (self-hosted). |
-| `data-auto-page="false"` | Initialise only; you call `page()` yourself. |
-| `data-hash-mode="true"` | Same as the `hashMode` option. |
-
-To call `track()` / `identify()` from your own script, ask for the running
-instance — `init()` with the same project ID returns it. With `defer`, the
-global exists once the document has been parsed:
-
-```html
-<script>
-  document.addEventListener('DOMContentLoaded', function () {
-    var bob = IndieBob.init({ projectId: 'proj_abc123def456ghij' })
-    bob.track('newsletter_signup')
-  })
-</script>
-```
-
-The classic install keeps working unchanged:
-
-```html
-<script src="https://assets.indiebob.com/tracker/latest/indiebob.min.js"></script>
-<script>
-  const bob = IndieBob.init({ projectId: 'proj_abc123def456ghij' })
-  bob.page()
-</script>
+```tsx
+const pathname = usePathname()
+useEffect(() => { bob.page() }, [pathname])
 ```
 
-If you add `data-project` to that same tag (leave out `defer` while the inline
-call is there — a deferred script runs after it), nothing is counted twice:
-`init()` returns the running instance and the second `page()` for the same
-path is skipped.
+## Server
 
-### Server-Side (Node.js)
+For events with no browser — a webhook, a job:
 
 ```ts
 import { IndieBob } from '@indiebob/tracker/server'
 
-const bob = IndieBob.initServer({ projectId: 'proj_abc123def456ghij' })
-bob.track('server_event', { source: 'cron_job' })
+const bob = IndieBob.initServer({ projectId: 'proj_…' })
+await bob.track('trial_started', { plan: 'pro' }, 'user_123')
+await bob.identify('user_123', { plan: 'pro' })
 ```
 
----
-
-## How It Works
-
-### Anonymous ID
-
-A random 21-character ID is generated on first visit and stored in `localStorage`. This persists across sessions so you can track a visitor's journey before they sign up.
-
-- Stored as `_ib_anon` in localStorage
-- Falls back to sessionStorage if localStorage is blocked
-- Never uses cookies — no consent banner required
-- Cleared when `optOut()` is called
-
-### Session ID
-
-A session ID is generated per browser tab/window using `crypto.randomUUID()`. Sessions expire after 30 minutes of inactivity or when the tab closes.
-
-### UTM Attribution
-
-UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`) are captured from the URL automatically on `init()`.
-
-- **First-touch** attribution stored in `_ib_first_utm` — never overwritten
-- **Last-touch** attribution in `_ib_last_utm` — updated each time UTMs are present in the URL
-- Enables "which campaign drove this paying customer?" — the core attribution question
-
-### Event IDs
-
-Every event carries a random, url-safe `id` (21 characters). It stays the same
-when a batch is retried or replayed from the offline queue, so the server
-stores each event once.
-
-### Event Batching
-
-Events are batched for efficiency:
-- Sent when 10 events accumulate
-- Sent every 5 seconds regardless
-- Sent immediately when the page becomes hidden (tab switch, close)
-- Queued in localStorage when offline; flushed when back online
-
-### Privacy by Default
-
-The SDK respects:
-- **Do Not Track** (`navigator.doNotTrack === '1'`): no events sent, `respectDnt: true` by default
-- **Global Privacy Control** (`navigator.globalPrivacyControl`): legally binding under CCPA in California, `respectGpc: true` by default
-- Neither cookies nor fingerprinting is used at any point
-- IP addresses are never stored by the server — only the country code derived at ingestion time
-
----
-
-## What Is and Isn't Collected
-
-### Automatically collected (on `page()`)
-
-| Data | What | Stored As |
-|---|---|---|
-| Page path | `/pricing`, `/blog/post-1` | String |
-| Page title | `document.title` | String |
-| Referrer | `document.referrer` | String |
-| UTM params | From URL query string | Object |
-| Screen size | `window.innerWidth/Height` | Numbers |
-| Device type | Derived from screen size | `'desktop'` \| `'mobile'` \| `'tablet'` |
-| Engaged time | Visible-and-focused milliseconds on the page (`engagement` event) | Number |
-| Scroll depth | Deepest point of the page seen, % of its height (`engagement` event) | Number |
-| Browser locale | `navigator.language` | String |
-| Timezone | `Intl.DateTimeFormat().resolvedOptions().timeZone` | String |
-| Country | Derived server-side from IP | String (e.g. `'US'`) |
-
-### Auto-detected events (when `autoDetect` is enabled)
-
-| Event | Trigger |
-|---|---|
-| `signup_start` | User visits a signup/register page |
-| `signup_submit` | User submits a form on a signup page |
-| `signup` | First `identify()` call (new user) |
-| `login_view` | User visits a login page |
-| `login_submit` | User submits a form on a login page |
-| `login` | Subsequent `identify()` call (returning user) |
-| `pricing_view` | User visits a pricing page |
-| `checkout_view` | User visits a checkout/cart page |
-| `checkout_submit` | User submits a form on a checkout page |
-| `success_view` | User visits a success/thank-you page |
-| `onboarding_view` | User visits an onboarding page |
-| `contact_view` | User visits a contact page |
-| `outbound_click` | User clicks an external link |
-| `file_download` | User clicks a link to a file (pdf, zip, dmg, …) |
-| Custom via `data-ib-event` | User clicks an element with the attribute |
-
-### NOT collected
-
-- IP addresses (never stored, used only for country lookup then discarded)
-- Browser fingerprint
-- Cookies
-- Personal data (name, email, etc.) unless you pass it to `identify()`
-- Cross-site tracking data
-
----
-
-## Privacy & Compliance
-
-### GDPR (EU)
-
-The SDK does not use cookies and does not collect personal data by default. The `anonymousId` is a random identifier with no link to personal identity. Under GDPR, anonymous analytics may not require a consent banner — but consult your legal team.
-
-When a user calls `optOut()`, all stored keys are cleared: `_ib_anon`, `_ib_session`, `_ib_first_utm`, `_ib_last_utm`, `_ib_referrer`, `_ib_queue`.
-
-`ib_ignore` (the site owner's own self-exclusion, see above) is the one key the
-SDK writes that is not an identifier; it is removed with `?ib_ignore=0`.
-
-### CCPA (California)
-
-Global Privacy Control (GPC) is automatically honored. If a user has GPC enabled in their browser, the SDK sends no events. This is the legally correct behavior under CCPA as amended by CPRA.
-
-### Cookie Law (EU ePrivacy Directive)
-
-No cookies are set. The localStorage identifiers are not cookies and fall outside the scope of the Cookie Law.
-
----
-
-## Self-Hosting
-
-Point the SDK at your own IndieBob instance:
-
-```ts
-const bob = IndieBob.init({
-  projectId: 'proj_abc123def456ghij',
-  endpoint: 'https://your-indiebob.example.com/api/collect',
-})
-```
-
----
-
-## Versioning & Backwards Compatibility
-
-This SDK follows [Semantic Versioning](https://semver.org/).
-
-**1.x guarantee**: All public methods listed in this README are stable. We will never:
-- Remove a method in a 1.x release
-- Change the behavior of an existing method without a deprecation period
-- Break the wire format for events that include `v: 1`
-
-**Upgrade path**: `npm update @indiebob/tracker` — no code changes required within 1.x.
-
-**Deprecation process**: Methods marked `@deprecated` in JSDoc will log a warning in `debug: true` mode. They remain functional until the next major version.
-
----
-
-## Bundle Size
-
-| Bundle | Size (gzip -9) |
-|---|---|
-| Browser IIFE (`indiebob.min.js`) | < 5KB (5,076 bytes in 0.3.0) |
-| ESM (`index.js`) | ~5KB (5,135 bytes in 0.3.0; your bundler minifies and tree-shakes it further) |
-| Server (Node.js) | No limit |
-
-Zero runtime dependencies.
-
-## Browser Support
+## Versions
 
-The script-tag bundle targets ES2020: Chrome/Edge 80+, Firefox 74+, Safari
-13.1+ (iOS 13.4+). The npm build (ESM/CJS) targets ES2018 and is transpiled
-further by your bundler if you need older browsers.
+`/tracker/latest/indiebob.min.js` is always the newest release. To stay on one version, load
+`/tracker/v0.4.1/indiebob.min.js`; a versioned file never changes. The npm package follows
+[semver](https://semver.org/); while it is 0.x, a minor release (0.3 → 0.4) can change behaviour, so
+read [CHANGELOG.md](./CHANGELOG.md) before upgrading.
 
----
+Browsers: the script tag needs Chrome 80, Firefox 74 or Safari 13.1 or newer; the npm build targets
+ES2018.
 
 ## License