@heycatch/sdk 0.7.0-dev.714 → 0.7.0-dev.974

package/dist/{shared-X3O5yyhh.d.cts → shared-CaIZ-Tgs.d.cts}

@@ -115,6 +115,34 @@ declare const STAGE: "dev" | "prod";
 declare const SDK_VERSION: string;
 /** Stamped when the installer could not determine a value. */
 declare const UNKNOWN_INSTALL_VALUE: "unknown";
+/**
+ * One captured event, as {@link HeyCatchBeforeSend} sees it just before it
+ * is queued for sending.
+ *
+ * Declared structurally, listing only the fields the SDK can promise. The
+ * index signature carries the underlying transport's own extra keys through
+ * untouched, so nothing is lost and nothing here has to move when they
+ * change.
+ */
+interface HeyCatchCapturedEvent {
+    /** Event name - an autocapture name like `$autocapture`, or your own. */
+    event: string;
+    /** The event's property bag, as it will be sent. */
+    properties: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Runs on every event right before it is queued. Return the event to keep
+ * it (mutated or not), or `null` to drop it.
+ *
+ * The SDK never calls this itself and never reads its return value - it
+ * forwards the function to the transport, whose own code calls it.
+ */
+type HeyCatchBeforeSend = (event: HeyCatchCapturedEvent | null) => HeyCatchCapturedEvent | null;
+/** The transport's older, deprecated hook. Prefer {@link HeyCatchBeforeSend}. */
+type HeyCatchSanitizeProperties = (properties: Record<string, unknown>, eventName: string) => Record<string, unknown>;
+/** Where the SDK may persist the distinct id and super properties. */
+type HeyCatchPersistence = 'localStorage' | 'cookie' | 'memory' | 'localStorage+cookie' | 'sessionStorage';
 /**
  * Frameworks the install guides can detect. **Written out as a union, not
  * derived from the array below**, because
@@ -175,6 +203,49 @@ interface HeyCatchConfig {
      * are covered automatically - omit this unless the API lives elsewhere.
      */
     tracingHosts?: string[];
+    /**
+     * Turn off autocapture (clicks and form submissions). Pageviews,
+     * page-leaves, and rage-clicks are captured separately and are NOT
+     * affected by this one. Costs the recap's friction signals - the web
+     * entry logs this once at `init()` so the tradeoff isn't silent.
+     */
+    autocapture?: boolean;
+    /**
+     * Strip autocaptured elements' text content. Costs the recap's friction
+     * labels - logged once at `init()`.
+     */
+    maskAllText?: boolean;
+    /**
+     * Strip autocaptured elements' attributes. Costs debugging context on
+     * autocaptured events - logged once at `init()`.
+     */
+    maskAllElementAttributes?: boolean;
+    /**
+     * Property keys to drop from every captured event. HeyCatch's own
+     * `heycatch_*` attribution keys cannot be denylisted - they are what
+     * attributes an event to your project, so they are filtered back out
+     * (and named in the console) rather than silently honoured.
+     */
+    propertyDenylist?: string[];
+    /** @deprecated Superseded by {@link HeyCatchConfig.beforeSend}. */
+    sanitizeProperties?: HeyCatchSanitizeProperties;
+    /** Runs on every event right before it is queued; return `null` to drop it. */
+    beforeSend?: HeyCatchBeforeSend | HeyCatchBeforeSend[];
+    /** Where the SDK persists the distinct id and super properties. */
+    persistence?: HeyCatchPersistence;
+    /** Disable persistence entirely - every pageload starts a new anonymous person. */
+    disablePersistence?: boolean;
+    /** Days before the persistence cookie expires. Defaults to 365. */
+    cookieExpirationDays?: number;
+    /**
+     * Start with capturing off until the app calls
+     * `analytics.optInCapturing()` - a proper consent gate instead of the
+     * "don't call init" workaround. Browser storage is held off too, not
+     * just sending, so no distinct id is written before consent.
+     */
+    optOutCapturingByDefault?: boolean;
+    /** Honor the browser's Do Not Track signal. */
+    respectDnt?: boolean;
 }
 
-export { type HeyCatchConfig as H, KNOWN_FRAMEWORKS as K, type PersonPropertyUpdate as P, SDK_VERSION as S, type TrackOptions as T, UNKNOWN_INSTALL_VALUE as U, type HeyCatchPersonProperties as a, type HeyCatchProperties as b, KNOWN_INSTALL_AGENTS as c, STAGE as d, type ServerTrackOptions as e };
+export { type HeyCatchBeforeSend as H, KNOWN_FRAMEWORKS as K, type PersonPropertyUpdate as P, SDK_VERSION as S, type TrackOptions as T, UNKNOWN_INSTALL_VALUE as U, type HeyCatchCapturedEvent as a, type HeyCatchConfig as b, type HeyCatchPersistence as c, type HeyCatchPersonProperties as d, type HeyCatchProperties as e, type HeyCatchSanitizeProperties as f, KNOWN_INSTALL_AGENTS as g, STAGE as h, type ServerTrackOptions as i };

package/dist/{shared-X3O5yyhh.d.ts → shared-CaIZ-Tgs.d.ts}

@@ -115,6 +115,34 @@ declare const STAGE: "dev" | "prod";
 declare const SDK_VERSION: string;
 /** Stamped when the installer could not determine a value. */
 declare const UNKNOWN_INSTALL_VALUE: "unknown";
+/**
+ * One captured event, as {@link HeyCatchBeforeSend} sees it just before it
+ * is queued for sending.
+ *
+ * Declared structurally, listing only the fields the SDK can promise. The
+ * index signature carries the underlying transport's own extra keys through
+ * untouched, so nothing is lost and nothing here has to move when they
+ * change.
+ */
+interface HeyCatchCapturedEvent {
+    /** Event name - an autocapture name like `$autocapture`, or your own. */
+    event: string;
+    /** The event's property bag, as it will be sent. */
+    properties: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Runs on every event right before it is queued. Return the event to keep
+ * it (mutated or not), or `null` to drop it.
+ *
+ * The SDK never calls this itself and never reads its return value - it
+ * forwards the function to the transport, whose own code calls it.
+ */
+type HeyCatchBeforeSend = (event: HeyCatchCapturedEvent | null) => HeyCatchCapturedEvent | null;
+/** The transport's older, deprecated hook. Prefer {@link HeyCatchBeforeSend}. */
+type HeyCatchSanitizeProperties = (properties: Record<string, unknown>, eventName: string) => Record<string, unknown>;
+/** Where the SDK may persist the distinct id and super properties. */
+type HeyCatchPersistence = 'localStorage' | 'cookie' | 'memory' | 'localStorage+cookie' | 'sessionStorage';
 /**
  * Frameworks the install guides can detect. **Written out as a union, not
  * derived from the array below**, because
@@ -175,6 +203,49 @@ interface HeyCatchConfig {
      * are covered automatically - omit this unless the API lives elsewhere.
      */
     tracingHosts?: string[];
+    /**
+     * Turn off autocapture (clicks and form submissions). Pageviews,
+     * page-leaves, and rage-clicks are captured separately and are NOT
+     * affected by this one. Costs the recap's friction signals - the web
+     * entry logs this once at `init()` so the tradeoff isn't silent.
+     */
+    autocapture?: boolean;
+    /**
+     * Strip autocaptured elements' text content. Costs the recap's friction
+     * labels - logged once at `init()`.
+     */
+    maskAllText?: boolean;
+    /**
+     * Strip autocaptured elements' attributes. Costs debugging context on
+     * autocaptured events - logged once at `init()`.
+     */
+    maskAllElementAttributes?: boolean;
+    /**
+     * Property keys to drop from every captured event. HeyCatch's own
+     * `heycatch_*` attribution keys cannot be denylisted - they are what
+     * attributes an event to your project, so they are filtered back out
+     * (and named in the console) rather than silently honoured.
+     */
+    propertyDenylist?: string[];
+    /** @deprecated Superseded by {@link HeyCatchConfig.beforeSend}. */
+    sanitizeProperties?: HeyCatchSanitizeProperties;
+    /** Runs on every event right before it is queued; return `null` to drop it. */
+    beforeSend?: HeyCatchBeforeSend | HeyCatchBeforeSend[];
+    /** Where the SDK persists the distinct id and super properties. */
+    persistence?: HeyCatchPersistence;
+    /** Disable persistence entirely - every pageload starts a new anonymous person. */
+    disablePersistence?: boolean;
+    /** Days before the persistence cookie expires. Defaults to 365. */
+    cookieExpirationDays?: number;
+    /**
+     * Start with capturing off until the app calls
+     * `analytics.optInCapturing()` - a proper consent gate instead of the
+     * "don't call init" workaround. Browser storage is held off too, not
+     * just sending, so no distinct id is written before consent.
+     */
+    optOutCapturingByDefault?: boolean;
+    /** Honor the browser's Do Not Track signal. */
+    respectDnt?: boolean;
 }
 
-export { type HeyCatchConfig as H, KNOWN_FRAMEWORKS as K, type PersonPropertyUpdate as P, SDK_VERSION as S, type TrackOptions as T, UNKNOWN_INSTALL_VALUE as U, type HeyCatchPersonProperties as a, type HeyCatchProperties as b, KNOWN_INSTALL_AGENTS as c, STAGE as d, type ServerTrackOptions as e };
+export { type HeyCatchBeforeSend as H, KNOWN_FRAMEWORKS as K, type PersonPropertyUpdate as P, SDK_VERSION as S, type TrackOptions as T, UNKNOWN_INSTALL_VALUE as U, type HeyCatchCapturedEvent as a, type HeyCatchConfig as b, type HeyCatchPersistence as c, type HeyCatchPersonProperties as d, type HeyCatchProperties as e, type HeyCatchSanitizeProperties as f, KNOWN_INSTALL_AGENTS as g, STAGE as h, type ServerTrackOptions as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heycatch/sdk",
-  "version": "0.7.0-dev.714",
+  "version": "0.7.0-dev.974",
   "description": "HeyCatch SDK",
   "keywords": [
     "analytics",