@crelora/mark 0.0.16

package/dist/node.es.js

@@ -0,0 +1,236 @@
+const d = "https://ingest.onelence.com", u = /* @__PURE__ */ new Set(["event_name", "user_id", "consent_state", "source", "is_conversion"]), h = /* @__PURE__ */ new Set([
+  "user_id",
+  "visitor_id",
+  "click_id",
+  "campaign_id",
+  "query",
+  "consent_state",
+  "source"
+]);
+class l {
+  constructor(t, e) {
+    this.deps = e, this.validateConfig(t), this.config = {
+      endpoint: t.endpoint ?? d,
+      ...t,
+      include_page_context: t.include_page_context ?? !0
+    }, this.consentRequirement = t.require_consent ?? !1, this.siteId = t.site_id, this.siteHost = t.site_host;
+  }
+  config;
+  consentRequirement;
+  siteId;
+  siteHost;
+  track(t, e = {}) {
+    return this.trackInternal(t, e, !1);
+  }
+  trackInternal(t, e = {}, s = !1) {
+    if (!t)
+      return this.config.debug && console.warn("[Mark] track called without event name"), !1;
+    if (!this.hasConsent())
+      return this.config.debug && console.warn("[Mark] Tracking blocked due to consent requirement."), !1;
+    const i = this.sanitizeTrackData(e), r = { ...i };
+    "query" in r && delete r.query, "site_id" in r && delete r.site_id, "site_host" in r && delete r.site_host;
+    const n = {
+      event_name: t,
+      ...this.getIdentityFields(i),
+      ...r
+    };
+    s && (n.is_conversion = !0);
+    const a = i.site_id ?? this.siteId, o = i.site_host ?? this.siteHost;
+    return a && (n.site_id = a), o && (n.site_host = o), this.config.include_page_context && typeof window < "u" && (this.applyPageContext(n), !o && n.site && (n.site_host = n.site)), this.deps.transport.send("/event", n), !0;
+  }
+  identify(t, e = {}) {
+    if (!t) {
+      this.config.debug && console.warn("[Mark] identify called without userId");
+      return;
+    }
+    if (!this.hasConsent()) {
+      this.config.debug && console.warn("[Mark] Identify blocked due to consent requirement.");
+      return;
+    }
+    const s = {
+      user_id: t,
+      ...this.sanitizeIdentifyTraits(e),
+      ...this.getIdentityFields()
+    };
+    this.siteId && (s.site_id = this.siteId), this.siteHost && (s.site_host = this.siteHost), this.deps.transport.send("/identify", s);
+  }
+  conversion(t, e = {}) {
+    return this.trackInternal(t, e, !0);
+  }
+  /**
+   * Returns the current visitor ID from storage, if any.
+   * Used by browser/Node wrappers to expose a stable pseudonymous ID for server-side attribution.
+   */
+  getVisitorId() {
+    return this.deps.storage.getVisitorId();
+  }
+  setConsent(t) {
+    this.deps.storage.setConsentStatus(t);
+    const e = {
+      visitor_id: this.deps.storage.getVisitorId(),
+      consent_state: t,
+      source: "sdk"
+    };
+    this.siteId && (e.site_id = this.siteId), this.siteHost && (e.site_host = this.siteHost), this.deps.transport.send("/consent", e);
+  }
+  getIdentityFields(t) {
+    const e = t?.visitor_id ?? this.deps.storage.getVisitorId(), s = t?.click_id ?? this.deps.storage.getLastClickId(), i = t?.campaign_id ?? this.deps.storage.getCampaignId(), r = this.deps.storage.getQueryParams() ?? {}, n = t?.query ?? {}, a = { ...r, ...n }, o = {};
+    return e && (o.visitor_id = e), s && (o.click_id = s), i && (o.campaign_id = i), Object.keys(a).length > 0 && (o.query = a), o;
+  }
+  hasConsent() {
+    if (!this.consentRequirement)
+      return !0;
+    const e = this.deps.storage.getConsentStatus();
+    return this.consentRequirement === "auto", e === "granted";
+  }
+  sanitizeTrackData(t) {
+    const e = {};
+    for (const [s, i] of Object.entries(t))
+      u.has(s) || (e[s] = i);
+    return e;
+  }
+  sanitizeIdentifyTraits(t) {
+    const e = {};
+    for (const [s, i] of Object.entries(t))
+      h.has(s) || (e[s] = i);
+    return e;
+  }
+  validateConfig(t) {
+    if (!t.key || !t.key.trim())
+      throw new Error("[Mark] `key` must be a non-empty string.");
+    if (t.endpoint)
+      try {
+        new URL(t.endpoint);
+      } catch {
+        throw new Error("[Mark] `endpoint` must be a valid absolute URL.");
+      }
+    if (typeof t.site_id == "string" && !t.site_id.trim())
+      throw new Error("[Mark] `site_id` cannot be an empty string.");
+    if (typeof t.site_host == "string" && !t.site_host.trim())
+      throw new Error("[Mark] `site_host` cannot be an empty string.");
+  }
+  applyPageContext(t) {
+    t.page || t.title || t.referrer || t.site || (t.site = window.location.host, t.page = window.location.pathname, t.title = document.title, document.referrer && (t.referrer = document.referrer));
+  }
+}
+class f {
+  config;
+  endpoint;
+  constructor(t) {
+    this.validateConfig(t), this.config = t, this.endpoint = t.endpoint ?? d;
+  }
+  async send(t, e) {
+    const s = this.joinUrl(this.endpoint, t), i = this.config.key, r = {
+      "Content-Type": "application/json",
+      [i.startsWith("sk_") ? "x-secret-key" : "x-publishable-key"]: i
+    };
+    if (this.config.debug && console.log("[Mark] Sending", s, e), typeof fetch != "function") {
+      this.config.debug && console.error("[Mark] Global fetch is not available in this runtime.");
+      return;
+    }
+    try {
+      const n = await fetch(s, {
+        method: "POST",
+        headers: r,
+        body: JSON.stringify(e),
+        keepalive: !0
+      });
+      if (!n.ok && this.config.debug) {
+        const a = await this.readErrorSnippet(n);
+        console.error("[Mark] Request rejected", {
+          url: s,
+          status: n.status,
+          statusText: n.statusText,
+          body: a
+        });
+      }
+    } catch (n) {
+      this.config.debug && console.error("[Mark] Failed to send", s, n);
+    }
+  }
+  joinUrl(t, e) {
+    const s = t.replace(/\/+$/, ""), i = e.replace(/^\/+/, "");
+    return `${s}/${i}`;
+  }
+  async readErrorSnippet(t) {
+    try {
+      return (await t.text()).slice(0, 300);
+    } catch {
+      return "";
+    }
+  }
+  validateConfig(t) {
+    if (!t.key || !t.key.trim())
+      throw new Error("[Mark] `key` must be a non-empty string.");
+    if (t.endpoint)
+      try {
+        new URL(t.endpoint);
+      } catch {
+        throw new Error("[Mark] `endpoint` must be a valid absolute URL.");
+      }
+  }
+}
+class _ {
+  constructor(t = {}) {
+    this.defaults = t;
+  }
+  getVisitorId() {
+    return this.defaults.visitor_id;
+  }
+  getLastClickId() {
+    return this.defaults.last_click_id;
+  }
+  getCampaignId() {
+    return this.defaults.campaign_id;
+  }
+  getQueryParams() {
+    return this.defaults.query_params;
+  }
+  getConsentStatus() {
+    return this.defaults.consent_status;
+  }
+  update() {
+  }
+  setConsentStatus() {
+  }
+}
+class g {
+  constructor(t) {
+    this.client = t;
+  }
+  track(t, e = {}) {
+    this.client.track(t, e);
+  }
+  conversion(t, e = {}) {
+    this.client.conversion(t, e);
+  }
+  identify(t, e = {}) {
+    this.client.identify(t, e);
+  }
+  setConsent(t) {
+    this.client.setConsent(t);
+  }
+  /**
+   * Returns the visitor ID from the configured storage, if any.
+   * With default StatelessStorage, this is the value passed via `storageDefaults.visitor_id` when creating the client.
+   * Use it to associate server-side events with the same visitor dimension as browser events.
+   */
+  getVisitorId() {
+    return this.client.getVisitorId();
+  }
+}
+const p = (c, t = {}) => {
+  const e = t.storage ?? new _({
+    visitor_id: t.storageDefaults?.visitor_id,
+    last_click_id: t.storageDefaults?.last_click_id,
+    campaign_id: t.storageDefaults?.campaign_id,
+    query_params: t.storageDefaults?.query_params,
+    consent_status: t.storageDefaults?.consent_status
+  }), s = t.transport ?? new f(c), i = new l(c, { storage: e, transport: s });
+  return new g(i);
+};
+export {
+  g as NodeMark,
+  _ as StatelessStorage,
+  p as createNodeMark
+};

package/dist/types/browser/BrowserStorage.d.ts

@@ -0,0 +1,32 @@
+import type { ConsentStatus, CrossDomainConfig, StorageData } from '../types';
+import type { StorageAdapter } from '../core/adapters';
+interface BrowserStorageOptions extends CrossDomainConfig {
+    storageKey?: string;
+}
+export declare class BrowserStorage implements StorageAdapter {
+    private data;
+    private readonly storageKey;
+    private readonly options;
+    private bridgeFrame?;
+    private bridgeReady;
+    private bridgeOrigin?;
+    constructor(options?: BrowserStorageOptions);
+    getVisitorId(): string | undefined;
+    getLastClickId(): string | undefined;
+    getCampaignId(): string | undefined;
+    getQueryParams(): Record<string, string> | undefined;
+    getConsentStatus(): ConsentStatus | undefined;
+    update(updates: Partial<StorageData>): void;
+    setConsentStatus(status: ConsentStatus): void;
+    private load;
+    private save;
+    private getCookie;
+    private setCookie;
+    private generateUUID;
+    private isCookieEnabled;
+    private setupBridge;
+    private handleBridgeMessage;
+    private postBridgeMessage;
+    private isDomainAllowed;
+}
+export {};

package/dist/types/browser/Mark.d.ts

@@ -0,0 +1,28 @@
+import type { MarkConfig, TrackEventData, IdentifyTraits, ConsentStatus } from '../types';
+import { MarkCore } from '../core/MarkCore';
+export declare class Mark {
+    private static client;
+    private static storage;
+    private static config;
+    private static pageviewTrackerInstalled;
+    private static lastPageviewHref;
+    private static emitAutoPageview;
+    private static pendingAttribution;
+    static init(config: MarkConfig): MarkCore;
+    static track(eventName: string, data?: TrackEventData): void;
+    static identify(userId: string, traits?: IdentifyTraits): void;
+    static conversion(eventName: string, data?: TrackEventData): void;
+    static setConsent(status: ConsentStatus): void;
+    /**
+     * Returns the current visitor ID when available.
+     * When consent is required (`require_consent: true` or `'auto'`), returns `undefined` until consent is granted.
+     * Use this to pass the visitor ID to your backend (e.g. in a header or request body) for server-side attribution
+     * when you do not have an authenticated user ID.
+     */
+    static getVisitorId(): string | undefined;
+    private static installPageviewTracking;
+    private static refreshAttribution;
+    private static flushPendingAttribution;
+    private static shouldPersistAttribution;
+    private static mergeAttributionUpdates;
+}

package/dist/types/browser/index.d.ts

@@ -0,0 +1,3 @@
+import { Mark } from './Mark';
+export { Mark };
+export default Mark;

package/dist/types/browser/urlAttribution.d.ts

@@ -0,0 +1,6 @@
+import type { StorageAdapter } from '../core/adapters';
+import type { MarkConfig, StorageData } from '../types';
+type AttributionCaptureConfig = Pick<MarkConfig, 'capture_query_params' | 'capture_all_query_params' | 'query_param_denylist' | 'max_captured_query_params' | 'max_query_param_value_length'>;
+export declare function captureAttributionFromUrl(storage: StorageAdapter, config?: AttributionCaptureConfig): void;
+export declare function extractAttributionFromSearch(search: string, config?: AttributionCaptureConfig): Partial<StorageData>;
+export {};

package/dist/types/core/HttpTransport.d.ts

@@ -0,0 +1,11 @@
+import type { MarkConfig } from '../types';
+import type { TransportAdapter } from './adapters';
+export declare class HttpTransport implements TransportAdapter {
+    private readonly config;
+    private readonly endpoint;
+    constructor(config: MarkConfig);
+    send(path: string, data: unknown): Promise<void>;
+    private joinUrl;
+    private readErrorSnippet;
+    private validateConfig;
+}

package/dist/types/core/MarkCore.d.ts

@@ -0,0 +1,26 @@
+import type { MarkConfig, TrackEventData, IdentifyTraits, ConsentStatus } from '../types';
+import type { MarkDependencies } from './adapters';
+export declare class MarkCore {
+    private readonly deps;
+    private config;
+    private consentRequirement;
+    private siteId?;
+    private siteHost?;
+    constructor(config: MarkConfig, deps: MarkDependencies);
+    track(eventName: string, data?: TrackEventData): boolean;
+    private trackInternal;
+    identify(userId: string, traits?: IdentifyTraits): void;
+    conversion(eventName: string, data?: TrackEventData): boolean;
+    /**
+     * Returns the current visitor ID from storage, if any.
+     * Used by browser/Node wrappers to expose a stable pseudonymous ID for server-side attribution.
+     */
+    getVisitorId(): string | undefined;
+    setConsent(status: ConsentStatus): void;
+    private getIdentityFields;
+    private hasConsent;
+    private sanitizeTrackData;
+    private sanitizeIdentifyTraits;
+    private validateConfig;
+    private applyPageContext;
+}

package/dist/types/core/adapters.d.ts

@@ -0,0 +1,18 @@
+import type { StorageData } from '../types';
+import type { ConsentStatus } from '../types';
+export interface StorageAdapter {
+    getVisitorId(): string | undefined;
+    getLastClickId(): string | undefined;
+    getCampaignId(): string | undefined;
+    getQueryParams(): Record<string, string> | undefined;
+    getConsentStatus(): ConsentStatus | undefined;
+    setConsentStatus(status: ConsentStatus): void;
+    update(updates: Partial<StorageData>): void;
+}
+export interface TransportAdapter {
+    send(path: string, data: unknown): Promise<void>;
+}
+export interface MarkDependencies {
+    storage: StorageAdapter;
+    transport: TransportAdapter;
+}

package/dist/types/core/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_ENDPOINT = "https://ingest.onelence.com";

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { Mark } from './browser/Mark';
+export { createNodeMark, NodeMark, StatelessStorage } from './node';
+export type * from './types';

package/dist/types/node/StatelessStorage.d.ts

@@ -0,0 +1,17 @@
+import type { ConsentStatus, StorageData } from '../types';
+import type { StorageAdapter } from '../core/adapters';
+/**
+ * Stateless storage adapter used by default in server runtimes.
+ * It simply exposes optional defaults and ignores updates.
+ */
+export declare class StatelessStorage implements StorageAdapter {
+    private defaults;
+    constructor(defaults?: StorageData);
+    getVisitorId(): string | undefined;
+    getLastClickId(): string | undefined;
+    getCampaignId(): string | undefined;
+    getQueryParams(): Record<string, string> | undefined;
+    getConsentStatus(): ConsentStatus | undefined;
+    update(): void;
+    setConsentStatus(): void;
+}

package/dist/types/node/index.d.ts

@@ -0,0 +1,25 @@
+import type { MarkConfig, TrackEventData, IdentifyTraits, StorageData, ConsentStatus } from '../types';
+import { MarkCore } from '../core/MarkCore';
+import type { StorageAdapter, TransportAdapter } from '../core/adapters';
+import { StatelessStorage } from './StatelessStorage';
+export interface NodeMarkOptions {
+    storage?: StorageAdapter;
+    transport?: TransportAdapter;
+    storageDefaults?: StorageData;
+}
+export declare class NodeMark {
+    private readonly client;
+    constructor(client: MarkCore);
+    track(eventName: string, data?: TrackEventData): void;
+    conversion(eventName: string, data?: TrackEventData): void;
+    identify(userId: string, traits?: IdentifyTraits): void;
+    setConsent(status: ConsentStatus): void;
+    /**
+     * Returns the visitor ID from the configured storage, if any.
+     * With default StatelessStorage, this is the value passed via `storageDefaults.visitor_id` when creating the client.
+     * Use it to associate server-side events with the same visitor dimension as browser events.
+     */
+    getVisitorId(): string | undefined;
+}
+export declare const createNodeMark: (config: MarkConfig, options?: NodeMarkOptions) => NodeMark;
+export { StatelessStorage };

package/dist/types/types.d.ts

@@ -0,0 +1,157 @@
+export interface AutocaptureConfig {
+    /**
+     * When true, automatically emit `page_view` on init and on SPA route changes.
+     * Defaults to false.
+     */
+    pageview?: boolean;
+}
+export interface MarkConfig {
+    /**
+     * Publishable or secret key identifying the customer account.
+     */
+    key: string;
+    /**
+     * Optional endpoint override.
+     * Defaults to 'https://ingest.onelence.com'.
+     */
+    endpoint?: string;
+    /**
+     * Enables verbose logging for debugging purposes.
+     */
+    debug?: boolean;
+    /**
+     * Optional cross-domain configuration.
+     */
+    cross_domain?: CrossDomainConfig;
+    /**
+     * Whether consent is required before tracking.
+     * - false (default): always track.
+     * - true: require explicit granted consent.
+     * - 'auto': honor stored consent; if none, treat as denied until provided.
+     */
+    require_consent?: boolean | 'auto';
+    /**
+     * Controls which events are automatically captured.
+     * Use { pageview: true } to emit page_view on init and SPA route changes.
+     */
+    autocapture?: AutocaptureConfig;
+    /**
+     * When autocapture.pageview is enabled, also track SPA route changes (pushState/replaceState/popstate).
+     * Defaults to true when autocapture.pageview is true.
+     */
+    track_route_changes?: boolean;
+    /**
+     * When true (default), browser SDK enriches events with page context (path, title, referrer, host).
+     * Full URL is only included when explicitly provided in the event payload.
+     */
+    include_page_context?: boolean;
+    /**
+     * Optional site identifier (UUID) for associating events with a registered site.
+     * When provided, this will be included in all event payloads as `site_id`.
+     */
+    site_id?: string;
+    /**
+     * Optional site host for audit/debug purposes.
+     * When provided, this will be included in all event payloads as `site_host`.
+     * If not provided, the SDK will use the host from page context (browser) or leave it undefined (Node).
+     */
+    site_host?: string;
+    /**
+     * Additional query parameter keys to capture for attribution.
+     * Keys are matched case-insensitively and stored in lowercase.
+     */
+    capture_query_params?: string[];
+    /**
+     * Capture every query string parameter (after denylist/limits are applied).
+     * Defaults to false.
+     */
+    capture_all_query_params?: boolean;
+    /**
+     * Lowercase query parameter keys that should never be captured.
+     * Defaults to sensitive keys such as email/phone/token/auth/password/code.
+     */
+    query_param_denylist?: string[];
+    /**
+     * Maximum number of query params persisted in attribution storage.
+     * Defaults to 30.
+     */
+    max_captured_query_params?: number;
+    /**
+     * Maximum length for each captured query param value.
+     * Defaults to 256.
+     */
+    max_query_param_value_length?: number;
+}
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface TrackEventData {
+    /**
+     * Optional explicit identifiers supplied by server runtimes.
+     */
+    visitor_id?: string;
+    click_id?: string;
+    campaign_id?: string;
+    query?: Record<string, string>;
+    /**
+     * Optional site identifier (UUID) for this specific event.
+     * Overrides the site_id from Mark.init() if provided.
+     */
+    site_id?: string;
+    /**
+     * Optional site host for this specific event.
+     * Overrides the site_host from Mark.init() if provided.
+     */
+    site_host?: string;
+    [key: string]: JsonValue | undefined;
+}
+export interface IdentifyTraits {
+    /**
+     * User's email address. Will be hashed server-side for privacy.
+     */
+    email?: string;
+    /**
+     * User's display name or full name.
+     */
+    display_name?: string;
+    /**
+     * User's preferred language (e.g., 'en', 'en-US', 'fr').
+     */
+    language?: string;
+    /**
+     * User's phone number. Will be hashed server-side for privacy.
+     */
+    phone?: string;
+    /**
+     * Additional custom traits. All traits are stored in the user profile and can be used for segmentation and personalization.
+     */
+    [key: string]: JsonValue | undefined;
+}
+export interface StorageData {
+    visitor_id?: string;
+    last_click_id?: string;
+    campaign_id?: string;
+    consent_status?: ConsentStatus;
+    query_params?: Record<string, string>;
+}
+export type DomainMode = 'single' | 'subdomain' | 'cross_domain';
+export interface CrossDomainConfig {
+    mode?: DomainMode;
+    /**
+     * Explicit cookie domain (e.g., ".example.com") for cross-subdomain tracking.
+     */
+    cookie_domain?: string;
+    /**
+     * Bridge configuration for cross-domain syncing using a first-party iframe service.
+     */
+    bridge?: {
+        url: string;
+        timeout_ms?: number;
+    };
+    /**
+     * Optional allowlist of domains that are permitted to interact via the bridge.
+     */
+    allowed_domains?: string[];
+}
+export type ConsentStatus = 'granted' | 'denied';

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crelora/mark",
+  "private": false,
+  "version": "0.0.16",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./dist/browser.umd.js",
+  "module": "./dist/browser.es.js",
+  "types": "./dist/types/browser/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/browser/index.d.ts",
+      "import": "./dist/browser.es.js",
+      "require": "./dist/browser.umd.js"
+    },
+    "./browser": {
+      "types": "./dist/types/browser/index.d.ts",
+      "import": "./dist/browser.es.js",
+      "require": "./dist/browser.umd.js"
+    },
+    "./node": {
+      "types": "./dist/types/node/index.d.ts",
+      "import": "./dist/node.es.js",
+      "require": "./dist/node.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "rimraf dist && tsc -p tsconfig.build.json && vite build --config vite.browser.config.ts && vite build --config vite.node.config.ts",
+    "preview": "vite preview",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "rimraf": "^6.1.2",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.18"
+  }
+}