@heycatch/sdk 0.7.0 → 0.7.1-dev.1123

package/dist/{shared-B8y8fJCD.d.cts → shared-BFhHwsG8.d.cts}

@@ -113,15 +113,66 @@ interface ServerTrackOptions extends TrackOptions {
  */
 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";
 /**
- * Frameworks the install guides can detect. Kept as a type alias, not a
- * runtime array: `apps/landing-web/tests/agent-install-guides.spec.ts`
- * reads this source text and asserts the set matches the guides' tables,
- * so docs, types, and reported values cannot drift.
+ * 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
+ * `apps/landing-web/tests/agent-install-guides.spec.ts` matches this
+ * declaration as source text to assert the set agrees with the guide's
+ * detection table. Collapsing it to `(typeof …)[number]` leaves that guard
+ * matching nothing.
+ *
+ * For the same reason, do not restate the declaration's opening line anywhere
+ * above it - including in a comment. The guard takes the FIRST match in the
+ * file, so a prose copy of it wins and yields zero ids. (Written here after
+ * doing exactly that; the spec's vacuity check is what caught it.)
  */
 type KnownFramework = 'nextjs' | 'vite-react' | 'react' | 'vue' | 'svelte' | 'astro' | 'angular' | 'react-native' | 'web';
 /** Coding agents that run the install. `other` is the catch-all. */
 type KnownInstallAgent = 'lovable' | 'bolt' | 'v0' | 'replit' | 'cursor' | 'claude-code' | 'codex' | 'windsurf' | 'other';
+/**
+ * The same two sets at RUNTIME, for code that has to ask "is this reported
+ * value one we recognise?" - a question a type union cannot answer, because
+ * `install.framework` is deliberately `KnownFramework | (string & {})` so an
+ * unlisted framework still installs cleanly.
+ *
+ * The consumer is the internal stats page, which flags an unrecognised or
+ * missing value rather than silently rendering it as though it were expected.
+ *
+ * Drift between each array and its union is a **compile error** (see the
+ * assertions below), so this is a second spelling, not a second source.
+ */
+declare const KNOWN_FRAMEWORKS: readonly ["nextjs", "vite-react", "react", "vue", "svelte", "astro", "angular", "react-native", "web"];
+declare const KNOWN_INSTALL_AGENTS: readonly ["lovable", "bolt", "v0", "replit", "cursor", "claude-code", "codex", "windsurf", "other"];
 /**
  * Who installed the SDK and into what. Stamped as super-properties on
  * every event - the dashboard reads them off the event stream, so there
@@ -152,6 +203,66 @@ 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;
+    /**
+     * Batch captured events for a few seconds before sending (the default).
+     * Set `false` on a multi-page site - one where each click is a full page
+     * load - because a visitor who navigates away inside the batch window
+     * takes the batch with them; iOS Safari in particular does not reliably
+     * let the unload send through. A single-page app can leave it unset.
+     * Browser only.
+     */
+    requestBatching?: boolean;
+    /**
+     * How long captured events wait for a batch, in milliseconds. Defaults to
+     * 3000; the accepted range is 250-5000, and a value outside it falls back
+     * to the default with a console warning. The gentler alternative to
+     * `requestBatching: false` when you want to keep batching but shrink the
+     * window. Browser only.
+     */
+    flushIntervalMs?: number;
 }
 
-export { type HeyCatchConfig as H, type PersonPropertyUpdate as P, SDK_VERSION as S, type TrackOptions as T, type HeyCatchPersonProperties as a, type HeyCatchProperties as b, STAGE as c, type ServerTrackOptions as d };
+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-B8y8fJCD.d.ts → shared-BFhHwsG8.d.ts}

@@ -113,15 +113,66 @@ interface ServerTrackOptions extends TrackOptions {
  */
 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";
 /**
- * Frameworks the install guides can detect. Kept as a type alias, not a
- * runtime array: `apps/landing-web/tests/agent-install-guides.spec.ts`
- * reads this source text and asserts the set matches the guides' tables,
- * so docs, types, and reported values cannot drift.
+ * 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
+ * `apps/landing-web/tests/agent-install-guides.spec.ts` matches this
+ * declaration as source text to assert the set agrees with the guide's
+ * detection table. Collapsing it to `(typeof …)[number]` leaves that guard
+ * matching nothing.
+ *
+ * For the same reason, do not restate the declaration's opening line anywhere
+ * above it - including in a comment. The guard takes the FIRST match in the
+ * file, so a prose copy of it wins and yields zero ids. (Written here after
+ * doing exactly that; the spec's vacuity check is what caught it.)
  */
 type KnownFramework = 'nextjs' | 'vite-react' | 'react' | 'vue' | 'svelte' | 'astro' | 'angular' | 'react-native' | 'web';
 /** Coding agents that run the install. `other` is the catch-all. */
 type KnownInstallAgent = 'lovable' | 'bolt' | 'v0' | 'replit' | 'cursor' | 'claude-code' | 'codex' | 'windsurf' | 'other';
+/**
+ * The same two sets at RUNTIME, for code that has to ask "is this reported
+ * value one we recognise?" - a question a type union cannot answer, because
+ * `install.framework` is deliberately `KnownFramework | (string & {})` so an
+ * unlisted framework still installs cleanly.
+ *
+ * The consumer is the internal stats page, which flags an unrecognised or
+ * missing value rather than silently rendering it as though it were expected.
+ *
+ * Drift between each array and its union is a **compile error** (see the
+ * assertions below), so this is a second spelling, not a second source.
+ */
+declare const KNOWN_FRAMEWORKS: readonly ["nextjs", "vite-react", "react", "vue", "svelte", "astro", "angular", "react-native", "web"];
+declare const KNOWN_INSTALL_AGENTS: readonly ["lovable", "bolt", "v0", "replit", "cursor", "claude-code", "codex", "windsurf", "other"];
 /**
  * Who installed the SDK and into what. Stamped as super-properties on
  * every event - the dashboard reads them off the event stream, so there
@@ -152,6 +203,66 @@ 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;
+    /**
+     * Batch captured events for a few seconds before sending (the default).
+     * Set `false` on a multi-page site - one where each click is a full page
+     * load - because a visitor who navigates away inside the batch window
+     * takes the batch with them; iOS Safari in particular does not reliably
+     * let the unload send through. A single-page app can leave it unset.
+     * Browser only.
+     */
+    requestBatching?: boolean;
+    /**
+     * How long captured events wait for a batch, in milliseconds. Defaults to
+     * 3000; the accepted range is 250-5000, and a value outside it falls back
+     * to the default with a console warning. The gentler alternative to
+     * `requestBatching: false` when you want to keep batching but shrink the
+     * window. Browser only.
+     */
+    flushIntervalMs?: number;
 }
 
-export { type HeyCatchConfig as H, type PersonPropertyUpdate as P, SDK_VERSION as S, type TrackOptions as T, type HeyCatchPersonProperties as a, type HeyCatchProperties as b, STAGE as c, type ServerTrackOptions as d };
+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",
+  "version": "0.7.1-dev.1123",
   "description": "HeyCatch SDK",
   "keywords": [
     "analytics",
@@ -82,6 +82,9 @@
       "optional": true
     }
   },
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"