@crelora/mark 0.0.16 → 0.1.0

package/README.md

@@ -90,10 +90,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.
 
@@ -135,8 +138,16 @@ All config options use snake_case. Stored event payloads and database columns ma
 | --- | --- | --- |
 | `key` | `string` | Publishable (browser) or secret (server) key issued in the Crelora dashboard. |
 | `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. |
+| `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,7 +163,7 @@ Server runtimes can also pass `storage`, `storageDefaults`, or `transport` via `
 
 ## Consent & Privacy
 
-- Call `setConsent('denied')` to immediately halt tracking when visitors opt out.
+- 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.
@@ -196,14 +207,6 @@ Mark.identify('user_123', {
 - Autocapture (optional): set `autocapture: { pageview: true }` (and optionally `track_route_changes: true`) to emit on first load and SPA route changes. If consent is required and not yet granted, initial pageview is deferred and emitted once consent is granted.
 - All SDK config and event fields use snake_case (`site_id`, `site_host`, etc.) and map directly to stored payloads and database columns.
 
-## Breaking changes (snake_case API)
-
-The SDK uses snake_case for all config options and reserved event fields, aligning with analytics ecosystem conventions (e.g. GA4, Mixpanel). If migrating from an older version:
-
-- Config: `requireConsent` → `require_consent`, `autoPageview` → `autocapture: { pageview: true }`, `trackRouteChanges` → `track_route_changes`, `includePageContext` → `include_page_context`, `siteId`/`siteHost` → `site_id`/`site_host`, `crossDomain` → `cross_domain`, etc.
-- Track payload: use `site_id` and `site_host` for per-event overrides.
-- Node `storageDefaults`: use `visitor_id`, `last_click_id`, `campaign_id`, `query_params`, `consent_status`.
-
 ## 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.