@heycatch/sdk 0.6.0 → 0.7.0-dev.1029

package/dist/index.d.cts

@@ -1,70 +1,27 @@
-/**
- * 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.
- */
-type KnownFramework = 'nextjs' | 'vite-react' | 'react' | 'vue' | 'svelte' | 'astro' | 'angular' | 'web';
-/** Coding agents that run the install. `other` is the catch-all. */
-type KnownInstallAgent = '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
- * is no separate install call to make or to fail.
- *
- * `(string & {})` keeps the known ids as editor completions while still
- * accepting anything: a framework we haven't listed yet must not block
- * an install.
- */
-interface HeyCatchInstall {
-    /** Framework id from the install guide, e.g. `nextjs`. */
-    framework?: KnownFramework | (string & {});
-    /** That framework's major version, e.g. `15`. */
-    frameworkVersion?: string;
-    /** The agent doing the install, e.g. `claude-code`. */
-    agent?: KnownInstallAgent | (string & {});
-}
-/** Configuration for {@link init}. */
-interface HeyCatchConfig {
-    /** Your project's publishable key (`hck_pk_...`). */
-    projectKey: string;
-    /** Install metadata, stamped on every event. Omit any field you can't determine. */
-    install?: HeyCatchInstall;
-}
-
-/**
- * Initialize HeyCatch. Call once at the client-side entry point -
- * autocapture starts immediately, nothing else to instrument.
- * Idempotent and a safe no-op on the server.
- */
-declare function init(config: HeyCatchConfig): void;
+import { d as HeyCatchPersonProperties, b as HeyCatchConfig, e as HeyCatchProperties, T as TrackOptions } from './shared-CaIZ-Tgs.cjs';
+export { H as HeyCatchBeforeSend, a as HeyCatchCapturedEvent, c as HeyCatchPersistence, f as HeyCatchSanitizeProperties, K as KNOWN_FRAMEWORKS, g as KNOWN_INSTALL_AGENTS, P as PersonPropertyUpdate, S as SDK_VERSION, h as STAGE, i as ServerTrackOptions, U as UNKNOWN_INSTALL_VALUE } from './shared-CaIZ-Tgs.cjs';
 
 /**
- * Person and event properties a customer's app can send.
+ * Starts capturing after `optOutCapturingByDefault` gated `init()` from
+ * sending anything - the consent-gate alternative to skipping `init()`
+ * entirely (the "don't call init" workaround this replaces for customers
+ * under GDPR/CookieYes-style consent banners). Call once consent is
+ * granted.
+ *
+ * Also releases the browser-storage half of the gate, since `init()` pairs
+ * `opt_out_persistence_by_default` with the capture opt-out.
  *
- * Deliberately not `unknown`: these values are serialised onto the wire and
- * rendered in a dashboard, so a nested object or a function would either be
- * dropped upstream or arrive as `[object Object]`. Restricting the type puts
- * that failure at the call site, in the customer's editor.
+ * Warns and does nothing before `init()` - see the note above.
  */
-type HeyCatchProperties = Record<string, string | number | boolean | null>;
+declare function optInCapturing(): void;
 /**
- * Person properties, in the two flavours every analytics backend distinguishes.
+ * Stops capturing again, for a visitor who WITHDRAWS consent - the other
+ * half of a consent banner, and the only one that can act on the current
+ * pageload (not loading the SDK next time cannot un-capture this one).
  *
- * - `set` overwrites on every send - use for values that change (`plan`,
- *   `last_seen_at`).
- * - `setOnce` writes only if the person does not already have the key - use for
- *   values that describe the beginning and must not be overwritten by a later
- *   visit (`signup_date`, `initial_referrer`).
- *
- * Named `set` / `setOnce` rather than the transport's own `$set` / `$set_once`:
- * the `$` names are an implementation detail of who we send to, and this is a
- * published customer-facing API that must not change if that ever does.
+ * Warns and does nothing before `init()` - see the note above.
  */
-interface PersonPropertyUpdate {
-    set?: HeyCatchProperties;
-    setOnce?: HeyCatchProperties;
-}
+declare function optOutCapturing(): void;
 
 /**
  * Link the anonymous visitor to your authenticated user. Call once
@@ -82,28 +39,20 @@ interface PersonPropertyUpdate {
  * those as regular properties would reset them on every login.
  *
  * @example
- * identify(user.id,
+ * setIdentity(user.id,
  *   { email: user.email, plan: 'pro' },
  *   { signup_date: user.createdAt },
  * );
  */
-declare function identify(userId: string, properties?: HeyCatchProperties, propertiesOnce?: HeyCatchProperties): void;
+declare function setIdentity(userId: string, properties?: HeyCatchPersonProperties, propertiesOnce?: HeyCatchPersonProperties): void;
 /**
  * Clear the current identity. Call on sign-out so the next visitor on
  * this browser starts anonymous.
  */
-declare function reset(): void;
+declare function resetIdentity(): void;
+
+declare function init(config: HeyCatchConfig): void;
 
-interface TrackOptions extends PersonPropertyUpdate {
-    /**
-     * Send this event immediately instead of batching it.
-     *
-     * Only worth setting when the page is about to unload - a sign-up redirect,
-     * a checkout hand-off - where a batched event would be lost. It costs a
-     * request per event, so it is not the default.
-     */
-    sendInstantly?: boolean;
-}
 /**
  * Record a product event.
  *
@@ -123,7 +72,7 @@ interface TrackOptions extends PersonPropertyUpdate {
  *
  * No-op before `init()` or on the server.
  */
-declare function track(event: string, properties?: HeyCatchProperties, options?: TrackOptions): void;
+declare function trackEvent(event: string, properties?: HeyCatchProperties, options?: TrackOptions): void;
 /**
  * Update the current person's properties without sending a product event, and
  * without changing who they are.
@@ -137,6 +86,24 @@ declare function track(event: string, properties?: HeyCatchProperties, options?:
  *
  * No-op before `init()` or on the server.
  */
-declare function setPersonProperties(set?: HeyCatchProperties, setOnce?: HeyCatchProperties): void;
+declare function setPersonProperties(set?: HeyCatchPersonProperties, setOnce?: HeyCatchPersonProperties): void;
+
+/**
+ * The analytics surface, as one namespace. The package is HeyCatch's
+ * product SDK - analytics is its first capability, not its identity - so
+ * the API ships as `analytics.*` and a future capability arrives as a
+ * sibling namespace instead of more loose top-level functions. The server
+ * entry exports the same-shaped object, which is what keeps isomorphic
+ * code resolving under every `exports` condition.
+ */
+declare const analytics: {
+    readonly init: typeof init;
+    readonly optInCapturing: typeof optInCapturing;
+    readonly optOutCapturing: typeof optOutCapturing;
+    readonly resetIdentity: typeof resetIdentity;
+    readonly setIdentity: typeof setIdentity;
+    readonly setPersonProperties: typeof setPersonProperties;
+    readonly trackEvent: typeof trackEvent;
+};
 
-export { type HeyCatchConfig, type HeyCatchProperties, type PersonPropertyUpdate, type TrackOptions, identify, init, reset, setPersonProperties, track };
+export { HeyCatchConfig, HeyCatchPersonProperties, HeyCatchProperties, TrackOptions, analytics };

package/dist/index.d.ts

@@ -1,70 +1,27 @@
-/**
- * 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.
- */
-type KnownFramework = 'nextjs' | 'vite-react' | 'react' | 'vue' | 'svelte' | 'astro' | 'angular' | 'web';
-/** Coding agents that run the install. `other` is the catch-all. */
-type KnownInstallAgent = '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
- * is no separate install call to make or to fail.
- *
- * `(string & {})` keeps the known ids as editor completions while still
- * accepting anything: a framework we haven't listed yet must not block
- * an install.
- */
-interface HeyCatchInstall {
-    /** Framework id from the install guide, e.g. `nextjs`. */
-    framework?: KnownFramework | (string & {});
-    /** That framework's major version, e.g. `15`. */
-    frameworkVersion?: string;
-    /** The agent doing the install, e.g. `claude-code`. */
-    agent?: KnownInstallAgent | (string & {});
-}
-/** Configuration for {@link init}. */
-interface HeyCatchConfig {
-    /** Your project's publishable key (`hck_pk_...`). */
-    projectKey: string;
-    /** Install metadata, stamped on every event. Omit any field you can't determine. */
-    install?: HeyCatchInstall;
-}
-
-/**
- * Initialize HeyCatch. Call once at the client-side entry point -
- * autocapture starts immediately, nothing else to instrument.
- * Idempotent and a safe no-op on the server.
- */
-declare function init(config: HeyCatchConfig): void;
+import { d as HeyCatchPersonProperties, b as HeyCatchConfig, e as HeyCatchProperties, T as TrackOptions } from './shared-CaIZ-Tgs.js';
+export { H as HeyCatchBeforeSend, a as HeyCatchCapturedEvent, c as HeyCatchPersistence, f as HeyCatchSanitizeProperties, K as KNOWN_FRAMEWORKS, g as KNOWN_INSTALL_AGENTS, P as PersonPropertyUpdate, S as SDK_VERSION, h as STAGE, i as ServerTrackOptions, U as UNKNOWN_INSTALL_VALUE } from './shared-CaIZ-Tgs.js';
 
 /**
- * Person and event properties a customer's app can send.
+ * Starts capturing after `optOutCapturingByDefault` gated `init()` from
+ * sending anything - the consent-gate alternative to skipping `init()`
+ * entirely (the "don't call init" workaround this replaces for customers
+ * under GDPR/CookieYes-style consent banners). Call once consent is
+ * granted.
+ *
+ * Also releases the browser-storage half of the gate, since `init()` pairs
+ * `opt_out_persistence_by_default` with the capture opt-out.
  *
- * Deliberately not `unknown`: these values are serialised onto the wire and
- * rendered in a dashboard, so a nested object or a function would either be
- * dropped upstream or arrive as `[object Object]`. Restricting the type puts
- * that failure at the call site, in the customer's editor.
+ * Warns and does nothing before `init()` - see the note above.
  */
-type HeyCatchProperties = Record<string, string | number | boolean | null>;
+declare function optInCapturing(): void;
 /**
- * Person properties, in the two flavours every analytics backend distinguishes.
+ * Stops capturing again, for a visitor who WITHDRAWS consent - the other
+ * half of a consent banner, and the only one that can act on the current
+ * pageload (not loading the SDK next time cannot un-capture this one).
  *
- * - `set` overwrites on every send - use for values that change (`plan`,
- *   `last_seen_at`).
- * - `setOnce` writes only if the person does not already have the key - use for
- *   values that describe the beginning and must not be overwritten by a later
- *   visit (`signup_date`, `initial_referrer`).
- *
- * Named `set` / `setOnce` rather than the transport's own `$set` / `$set_once`:
- * the `$` names are an implementation detail of who we send to, and this is a
- * published customer-facing API that must not change if that ever does.
+ * Warns and does nothing before `init()` - see the note above.
  */
-interface PersonPropertyUpdate {
-    set?: HeyCatchProperties;
-    setOnce?: HeyCatchProperties;
-}
+declare function optOutCapturing(): void;
 
 /**
  * Link the anonymous visitor to your authenticated user. Call once
@@ -82,28 +39,20 @@ interface PersonPropertyUpdate {
  * those as regular properties would reset them on every login.
  *
  * @example
- * identify(user.id,
+ * setIdentity(user.id,
  *   { email: user.email, plan: 'pro' },
  *   { signup_date: user.createdAt },
  * );
  */
-declare function identify(userId: string, properties?: HeyCatchProperties, propertiesOnce?: HeyCatchProperties): void;
+declare function setIdentity(userId: string, properties?: HeyCatchPersonProperties, propertiesOnce?: HeyCatchPersonProperties): void;
 /**
  * Clear the current identity. Call on sign-out so the next visitor on
  * this browser starts anonymous.
  */
-declare function reset(): void;
+declare function resetIdentity(): void;
+
+declare function init(config: HeyCatchConfig): void;
 
-interface TrackOptions extends PersonPropertyUpdate {
-    /**
-     * Send this event immediately instead of batching it.
-     *
-     * Only worth setting when the page is about to unload - a sign-up redirect,
-     * a checkout hand-off - where a batched event would be lost. It costs a
-     * request per event, so it is not the default.
-     */
-    sendInstantly?: boolean;
-}
 /**
  * Record a product event.
  *
@@ -123,7 +72,7 @@ interface TrackOptions extends PersonPropertyUpdate {
  *
  * No-op before `init()` or on the server.
  */
-declare function track(event: string, properties?: HeyCatchProperties, options?: TrackOptions): void;
+declare function trackEvent(event: string, properties?: HeyCatchProperties, options?: TrackOptions): void;
 /**
  * Update the current person's properties without sending a product event, and
  * without changing who they are.
@@ -137,6 +86,24 @@ declare function track(event: string, properties?: HeyCatchProperties, options?:
  *
  * No-op before `init()` or on the server.
  */
-declare function setPersonProperties(set?: HeyCatchProperties, setOnce?: HeyCatchProperties): void;
+declare function setPersonProperties(set?: HeyCatchPersonProperties, setOnce?: HeyCatchPersonProperties): void;
+
+/**
+ * The analytics surface, as one namespace. The package is HeyCatch's
+ * product SDK - analytics is its first capability, not its identity - so
+ * the API ships as `analytics.*` and a future capability arrives as a
+ * sibling namespace instead of more loose top-level functions. The server
+ * entry exports the same-shaped object, which is what keeps isomorphic
+ * code resolving under every `exports` condition.
+ */
+declare const analytics: {
+    readonly init: typeof init;
+    readonly optInCapturing: typeof optInCapturing;
+    readonly optOutCapturing: typeof optOutCapturing;
+    readonly resetIdentity: typeof resetIdentity;
+    readonly setIdentity: typeof setIdentity;
+    readonly setPersonProperties: typeof setPersonProperties;
+    readonly trackEvent: typeof trackEvent;
+};
 
-export { type HeyCatchConfig, type HeyCatchProperties, type PersonPropertyUpdate, type TrackOptions, identify, init, reset, setPersonProperties, track };
+export { HeyCatchConfig, HeyCatchPersonProperties, HeyCatchProperties, TrackOptions, analytics };