@crelora/mark 0.1.0 → 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
@@ -136,7 +143,7 @@ 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. |
@@ -147,6 +154,7 @@ All config options use snake_case. Stored event payloads and database columns ma
 | `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). |
+| `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). |
@@ -163,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 and clear stored attribution/cookie identity state.
-- 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
 
@@ -209,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.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crelora/mark",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "main": "./dist/browser.umd.js",