@crelora/mark 0.1.1 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+Use it to feed [**OneLence**](https://onelence.com) 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
 
@@ -104,6 +104,7 @@ The Node factory accepts optional custom storage or transport adapters so you ca
 - `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 }`.
+- `setInternal(value)` / `getInternal()` – flags the current visitor as internal traffic (QA, staff, smoke tests). While set, every outgoing event is stamped with `is_internal: true` so the backend can exclude it from customer-facing reports by default. See [Flagging internal traffic](#flagging-internal-traffic).
 
 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.
 
@@ -223,6 +224,77 @@ 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.
 
+## Extended autocapture (browser)
+
+All of the following are **opt-in** under `autocapture`. They respect the same consent, DNT/GPC, and sampling rules as `track()` (see `sample_rate`: conversions are exempt; these modes are **not** conversion events). They are registered when `Mark.init()` runs.
+
+| Flag | Event name(s) | Behavior |
+| --- | --- | --- |
+| `click` | `data-mark-event` value, or `click` | Listens for clicks. **Default:** only elements matching `[data-mark-event]`; set `click: { selector: '.my-tracked' }` to use a custom selector. Sends `element_id`, `element_classes`, truncated `text`, and `href` when applicable. |
+| `form_submit` | `form_submit` | Listens for `submit`; sends `form_id`, `form_name`, `action`. |
+| `outbound_link` | `outbound_link_click` | On click, if the link target is another origin, sends `href`. Uses `preferBeacon: true` so the event is more likely to fire before navigation. |
+| `scroll_depth` | `scroll_depth` | Fires at **25%, 50%, 75%, and 100%** of vertical scroll depth (once each per page load). Payload includes `percent`. |
+| `web_vitals` | `web_vital` | Lazy-loads the `web-vitals` dependency and reports **LCP, CLS, INP, and TTFB** with `metric`, `value`, optional `rating`, and `metric_id`. If the module fails to load, only `debug: true` logs a warning. |
+
+Example:
+
+```ts
+Mark.init({
+  key: 'pk_xxxxx',
+  require_consent: 'auto',
+  autocapture: {
+    pageview: true,
+    click: true,
+    // or: click: { selector: '[data-analytics]' },
+    form_submit: true,
+    outbound_link: true,
+    scroll_depth: true,
+    web_vitals: true,
+  },
+});
+```
+
+## Flagging internal traffic
+
+Use the `is_internal` marker to keep QA sessions, staff testing, or automated smoke tests out of customer-facing reports without dropping them on the client. The SDK supports it in two complementary ways:
+
+**1. Per-event field.** Any `track` / `conversion` call can carry `is_internal: true`:
+
+```ts
+Mark.track('checkout_started', { value: 1299, is_internal: true });
+```
+
+**2. Persistent visitor flag.** Set it once and every subsequent event is stamped automatically:
+
+```ts
+Mark.setInternal(true);  // stamps is_internal: true on all future events
+Mark.setInternal(false); // stops stamping
+Mark.getInternal();      // boolean
+```
+
+The persistent flag is stored in the SDK's browser storage so it survives reloads. It is cleared automatically by `Mark.reset()` and by `Mark.setConsent('denied')`.
+
+**Design note.** The SDK intentionally does *not* read a magic URL parameter or write to a well-known `localStorage` key on its own — that would let anyone opt themselves out of your analytics just by visiting a URL, and it would bake a specific policy into every integration. Instead, your app decides when to flip the flag. A common pattern is a URL query parameter for staff onboarding:
+
+```ts
+// After Mark.init(...)
+const params = new URLSearchParams(window.location.search);
+if (params.get('onelence_internal') === '1') Mark.setInternal(true);
+if (params.get('onelence_internal') === '0') Mark.setInternal(false);
+```
+
+Other reasonable triggers: an authenticated admin/staff role, an internal IP range detected server-side, a feature flag, or an explicit toggle in your own settings UI.
+
+**Server-side** the same API is available on `NodeMark`:
+
+```ts
+const mark = createNodeMark({ key: process.env.MARK_SECRET_KEY! });
+mark.setInternal(true);
+mark.track('backoffice_action'); // is_internal: true
+```
+
+`is_internal` is a first-class field on the backend: events are still ingested (so you can audit and debug integrations), but excluded from customer-facing reports by default.
+
 ## Support
 
 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.