@crelora/mark 0.0.18 → 0.1.1

package/README.md

@@ -2,6 +2,13 @@
 
 Mark is Crelora's lightweight attribution SDK for capturing user journeys, conversions, and consent across browsers and server-side runtimes. The npm package includes both browser and Node entry points so you can send consistent data from any surface.
 
+Use it to feed **OneLence** with first‑party behavioral and conversion data so you can build **analytics**, **insights**, **signals**, and **decisions** on top of a unified event stream.
+
+### API keys and documentation
+
+- **Keys:** Publishable keys (`pk_…`) for browser and secret keys (`sk_…`) for server-side use are available in the OneLence dashboard: [API keys](https://onelence.com/dash/settings/api-keys).
+- **Guides:** For integration patterns, alternative integration types (e.g. server-only, tag managers), and deeper technical documentation, see the [Integrations overview](https://onelence.com/docs/integrations/overview).
+
 ## Installation
 
 ```bash
@@ -90,10 +97,13 @@ The Node factory accepts optional custom storage or transport adapters so you ca
 
 - `Mark.init(config)` / `createNodeMark(config)` – bootstraps the client with your publishable or secret key.
 - `track(eventName, payload?)` – records custom events with arbitrary properties (numbers, strings, arrays, objects). Use `site_id` and `site_host` for per-event site overrides.
-- `conversion(eventName, payload?)` – records conversion events. Currently behaves like `track` but tags the event with `is_conversion: true`.
+- `conversion(eventName, payload?)` – records conversion events (same endpoint path as track, with `is_conversion: true` for backend compatibility).
 - `identify(userId, traits?)` – ties a known user identifier to previous anonymous activity. Recommended traits: `email`, `display_name`, `language`. Custom traits are also supported.
 - `setConsent(status)` – enforces consent gating; pass `'granted'` or `'denied'`.
 - `getVisitorId()` – returns the current pseudonymous visitor ID when available. On the browser, returns `undefined` until consent is granted when `require_consent` is set. Use it to send the ID to your backend (e.g. in a header or body) for server-side attribution when you don't have an authenticated user ID.
+- `flush()` – flushes queued/persisted delivery items.
+- `reset()` – clears user/session/attribution state and rotates visitor identity for logout flows.
+- `getStats()` – returns runtime delivery stats `{ queued, sent, failed, dropped }`.
 
 Reserved SDK fields (for example `event_name`, `user_id`, `consent_state`, and internal identity metadata) are sanitized from user payloads/traits and cannot override SDK-managed values.
 
@@ -133,10 +143,19 @@ All config options use snake_case. Stored event payloads and database columns ma
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `key` | `string` | Publishable (browser) or secret (server) key issued in the Crelora dashboard. |
+| `key` | `string` | Publishable (browser) or secret (server) key from [OneLence API keys](https://onelence.com/dash/settings/api-keys). |
 | `debug` | `boolean` | Enables verbose console logging to help with integration tests. |
+| `before_send` | `(event) => event \| null` | Mutate/redact payloads before send, or return `null` to drop events. |
+| `on_error` | `(error, event?) => void` | Hook for transport and queue failures. |
+| `sample_rate` | `number` | Fraction (`0..1`) for `track` event sampling. `identify` and `conversion` are never sampled. |
+| `honor_dnt` | `boolean` | When true, blocks tracking when browser DNT/GPC is enabled. |
+| `session_timeout_ms` | `number` | Inactivity window for rotating `session_id` (default 30 minutes). |
+| `request_timeout_ms` | `number` | HTTP timeout per request in milliseconds (default `10000`). |
+| `rotate_visitor_on_consent_change` | `boolean` | Rotate `visitor_id` after denied -> granted transition. |
+| `batching` | `{ enabled?: boolean, max_size?: number, flush_interval_ms?: number, endpoint_path?: string }` | Optional batch mode (`/events` by default). |
 | `require_consent` | `boolean \| 'auto'` | `true` blocks tracking until consent is granted, `'auto'` requires stored granted consent and treats missing consent as denied, default `false` (`'auto'` recommended for production). |
-| `autocapture` | `{ pageview?: boolean }` | When `pageview: true`, automatically sends `page_view` on init and SPA route changes. If consent is required, the first `page_view` is sent as soon as consent becomes granted. |
+| `consent_source` | `{ type: 'tcf', purposes: number[] }` | Optional **IAB TCF v2** integration: the SDK listens for CMP updates and only allows tracking when the listed numeric purpose IDs are consented. Combine with `require_consent` and `setConsent` as your legal team requires. |
+| `autocapture` | `{ pageview?: boolean, click?: boolean \| { selector?: string }, form_submit?: boolean, outbound_link?: boolean, scroll_depth?: boolean, web_vitals?: boolean }` | Auto-capture toggles for page views and optional interaction/perf signals. |
 | `track_route_changes` | `boolean` | When `autocapture.pageview` is true, also emits on SPA route changes (pushState/replaceState/popstate); defaults to `true`. |
 | `include_page_context` | `boolean` | When true (default), enriches events with `page`, `title`, `referrer`, `site` (full `url` is only sent if you pass it explicitly in payload). |
 | `cross_domain` | `CrossDomainConfig` | Controls cookie domain, bridge URL, and allowlist for multi-domain attribution. |
@@ -152,13 +171,21 @@ Server runtimes can also pass `storage`, `storageDefaults`, or `transport` via `
 
 ## Consent & Privacy
 
-- Call `setConsent('denied')` to immediately halt tracking when visitors opt out.
-- Use `require_consent: true` (or `'auto'`) to make the SDK wait until a positive consent signal is received.
-- In `'auto'` mode, missing consent is treated as denied until consent is explicitly granted.
-- Event payloads cannot bypass consent checks.
-- Attribution parameters are not persisted pre-consent; they are held in runtime memory until consent is granted.
-- Cross-domain mode supports first-party iframe bridges so identifiers remain in your control.
-- IP/Geo: IP is never taken from the browser; it is captured server-side, hashed, and used to derive coarse geo (country/region/city, coarse lat/lon) when allowed by consent/tenant settings.
+These behaviors matter for **compliance-sensitive** setups (GDPR-style consent, CMPs, enterprise security reviews):
+
+- **Consent gating:** Use `require_consent: true` or `'auto'` so events and `identify` only run after a positive consent signal. In `'auto'` mode, missing consent is treated as denied until `setConsent('granted')`.
+- **TCF v2:** Set `consent_source: { type: 'tcf', purposes: [/* IAB purpose IDs */] }` so tracking follows your CMP’s current purpose consents (the SDK subscribes to CMP updates rather than relying on a one-time read).
+- **Withdrawal:** `setConsent('denied')` stops tracking and clears stored attribution plus cookie-backed visitor identity where applicable.
+- **Stricter identity hygiene:** Enable `rotate_visitor_on_consent_change` if you want a fresh `visitor_id` after a denied → granted transition.
+- **DNT / GPC:** `honor_dnt: true` blocks tracking when the browser reports Do Not Track or Global Privacy Control.
+- **Data minimization:** Use `before_send` to strip or redact fields before they leave the client; use `on_error` for observability without logging raw payloads.
+- **Payloads cannot bypass consent** via event properties; reserved fields are sanitized.
+- **Pre-consent attribution:** URL attribution is held in memory only until consent is granted, then persisted.
+- **Cross-domain:** First-party iframe bridges keep identifiers under your control.
+- **Delivery without long-lived local queues:** Failed sends can be retried from a browser outbox with a **48-hour TTL**; on tab hide / unload, pending items are flushed with **`sendBeacon`** where possible to improve delivery without weakening consent checks.
+- **IP / geo:** IP is not read in the browser; it is taken server-side, hashed, and used for coarse geo only when allowed by consent and tenant settings.
+
+For product-level privacy commitments and processor terms, rely on your OneLence agreement and [documentation](https://onelence.com/docs/integrations/overview); this README describes SDK behavior only.
 
 ## Visitor ID for server attribution
 
@@ -198,5 +225,5 @@ Mark.identify('user_123', {
 
 ## Support
 
-Need help? Reach out through your Crelora account team or file a ticket via the dashboard. Please include the SDK version, runtime (browser or Node), and any reproduction steps so we can assist quickly.
+Need help? Reach out through your account team or file a ticket via the OneLence dashboard. Please include the SDK version, runtime (browser or Node), and any reproduction steps so we can assist quickly.