@heycatch/sdk 0.6.0 → 0.7.0-dev.1029

package/dist/shared-CaIZ-Tgs.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Event properties a customer's app can send with `track`.
+ *
+ * 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.
+ */
+type HeyCatchProperties = Record<string, string | number | boolean | null>;
+/**
+ * Person properties, with the canonical keys the dashboard reads.
+ *
+ * The named keys are the contract: `email` and `name` drive how a person is
+ * displayed, `plan` powers plan-level breakdowns, `signup_date` anchors
+ * account age. Use these exact names whenever the app has the value -
+ * customer A writing `plan` while customer B writes `tier` is what makes
+ * every cross-project feature impossible.
+ *
+ * Everything else is deliberately open: extra context about the user
+ * (payment state, feature usage, whatever is useful) passes through as-is,
+ * nested values included - an unlisted key must never be a type error at
+ * the customer's call site.
+ */
+interface HeyCatchPersonProperties {
+    /** How the dashboard shows the person. A property - never the identity. */
+    email?: string;
+    /** Display name, alongside `email`. */
+    name?: string;
+    /** The app's own plan name (`free`, `pro`, …). Values are yours; the key is the contract. */
+    plan?: string;
+    /** ISO 8601. Belongs in set-once, so a later sign-in cannot move it. */
+    signup_date?: string;
+    /** Anything else useful about the user - passes through untouched. */
+    [key: string]: unknown;
+}
+/**
+ * Person properties, in the two flavours every analytics backend distinguishes.
+ *
+ * - `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.
+ */
+interface PersonPropertyUpdate {
+    set?: HeyCatchPersonProperties;
+    setOnce?: HeyCatchPersonProperties;
+}
+/**
+ * Options for `trackEvent`, as bundler-resolved projects see them. This is
+ * the shape behind the `browser` and `default` type conditions - and
+ * `moduleResolution: "bundler"` (Next.js, Vite) type-checks a whole
+ * project, route handlers included, against it, which is why `userId` must
+ * exist here even though the browser ignores it: one tsconfig cannot hold
+ * two type surfaces per file. Pure-Node backends (`nodenext`) resolve the
+ * `node` condition instead and get {@link ServerTrackOptions}, where the
+ * requirement is enforced at compile time.
+ *
+ * Delivery timing is deliberately not an option: the browser batches (and
+ * the transport flushes the queue on page unload), the server sends
+ * immediately - per-environment behaviour is the SDK's call, not the
+ * caller's.
+ */
+interface TrackOptions extends PersonPropertyUpdate {
+    /**
+     * Who the event belongs to. REQUIRED on the server - there is no ambient
+     * person in a webhook, and the server entry's own types (and its runtime
+     * guard) enforce it. Ignored in the browser, where the session already
+     * knows. Must be the same stable internal user id passed to
+     * `setIdentity`.
+     */
+    userId?: string;
+    /**
+     * Server only, and only meaningful when the event happens during the
+     * user's OWN request (an API route, a server action): pass the incoming
+     * request and the event joins their live browser session - the web SDK
+     * stamps a session header on same-origin requests automatically. A
+     * webhook has no request to pass. Ignored in the browser.
+     */
+    request?: TracingRequest;
+}
+/**
+ * The slice of an incoming request the server entry reads. Both shapes in
+ * the wild satisfy it: a Fetch `Request` (Next route handlers, Hono, Bun -
+ * `headers.get`) and a Node/Express `req` (`headers` as a plain
+ * lowercase-keyed object), so the same call works in either.
+ */
+interface TracingRequest {
+    headers: {
+        get: (name: string) => string | null;
+    } | Record<string, string | string[] | undefined>;
+}
+/**
+ * Options for the server `trackEvent` - REQUIRED, with a REQUIRED
+ * `userId`: a server process has no ambient person, so every event must
+ * say who it belongs to. Must be the same stable internal id the app
+ * passes to `setIdentity` in the browser; that is what joins the two. The
+ * server entry exports this shape as its `TrackOptions`.
+ */
+interface ServerTrackOptions extends TrackOptions {
+    userId: string;
+}
+
+/**
+ * Which HeyCatch backend this bundle was built against - `dev` or `prod`.
+ * Introspection for debugging ("which stage bundle is this page running?"),
+ * and stamped on every event as `heycatch_sdk_stage`. Describes OUR backend,
+ * not the customer's own app environment.
+ */
+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
+ * `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
+ * 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;
+    /**
+     * Hostnames of the app's own backends on OTHER origins (e.g.
+     * `api.example.com`) whose requests should carry the session header for
+     * server-side `trackEvent({ request })` linking. Same-origin requests
+     * 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 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.6.0",
+  "version": "0.7.0-dev.1029",
   "description": "HeyCatch SDK",
   "keywords": [
     "analytics",
@@ -23,25 +23,68 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "react-native": {
+        "types": "./dist/react-native.d.ts",
+        "import": "./dist/react-native.js",
+        "require": "./dist/react-native.cjs"
+      },
+      "browser": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs"
+      },
+      "node": {
+        "types": "./dist/server.d.ts",
+        "import": "./dist/server.js",
+        "require": "./dist/server.cjs"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    },
+    "./react-native": {
+      "types": "./dist/react-native.d.ts",
+      "import": "./dist/react-native.js",
+      "require": "./dist/react-native.cjs"
     }
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist/index.js",
-    "dist/index.cjs",
-    "dist/index.d.ts",
-    "dist/index.d.cts",
+    "dist/*.js",
+    "dist/*.cjs",
+    "dist/*.d.ts",
+    "dist/*.d.cts",
     "README.md",
-    "AGENTS.md",
-    "docs",
     "LICENSE",
     "THIRD-PARTY-LICENSES.md"
   ],
+  "dependencies": {
+    "posthog-react-native": "^4.61.1"
+  },
+  "peerDependencies": {
+    "expo-router": "*",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-router": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/AGENTS.md

@@ -1,132 +0,0 @@
-# @heycatch/sdk - setup guide
-
-Offline copy, bundled with this release. **If you can fetch URLs, follow
-https://heycatch.ai/agents.md instead** - it routes to a detailed guide per
-framework and is updated between releases. Use this file only when you cannot
-fetch.
-
-You need the user's project key - a string starting with `hck_`, included in
-the prompt that pointed you here. If you don't have one, stop and tell the
-user: "Copy the install prompt from your project's Install page in the HeyCatch
-dashboard - it includes your project key."
-
-## 1. Install the package
-
-Add the `@heycatch/sdk` npm package as a regular dependency, latest version,
-with whatever package manager the project uses. No shell available? Add it to
-`dependencies` in `package.json`; your platform installs it on rebuild. The
-package has no install scripts and no native code.
-
-## 2. Call `init` once at the client entry point
-
-```ts
-import { init } from '@heycatch/sdk';
-
-init({
-  projectKey: 'hck_…', // the key from the prompt, inlined
-  install: {
-    framework: 'nextjs', // the id from the table below (a real value)
-    frameworkVersion: '<major>', // the detected major, e.g. 16
-    agent: '<your-id>', // ← YOUR id, not a copied example. See below.
-  },
-});
-```
-
-Where that call goes - read `package.json` and pick the first matching row.
-Check **both** `dependencies` and `devDependencies`: `vite`, `astro` and most
-build-time frameworks are dev-only.
-
-| Project has             | framework id | `init` goes in                                                                                              |
-| ----------------------- | ------------ | ----------------------------------------------------------------------------------------------------------- |
-| `next` >= 15.3          | `nextjs`     | `instrumentation-client.ts` at the project root                                                             |
-| `next` < 15.3, `app/`   | `nextjs`     | a `'use client'` component in the root layout                                                               |
-| `next` < 15.3, `pages/` | `nextjs`     | top of `pages/_app.tsx`, module scope                                                                       |
-| `vite` and `react`      | `vite-react` | `src/main.tsx`, above the render call                                                                       |
-| `react` without `vite`  | `react`      | `src/index.tsx` / `.jsx` / `.js`, whichever exists, above the render call                                   |
-| `nuxt`                  | `vue`        | `plugins/heycatch.client.ts`                                                                                |
-| `vue` (plain Vite)      | `vue`        | `src/main.ts`                                                                                               |
-| `@sveltejs/kit`         | `svelte`     | `src/hooks.client.ts`                                                                                       |
-| `svelte` (plain Vite)   | `svelte`     | `src/main.ts`                                                                                               |
-| `astro`                 | `astro`      | a `<script>` in the base layout                                                                             |
-| `@angular/core`         | `angular`    | `src/main.ts`                                                                                               |
-| anything else           | `web`        | the client entry file that boots the app in the browser                                                     |
-| no `package.json`       | `web`        | `<script type="module">` in `<head>`, importing from `https://esm.sh/@heycatch/sdk@0.3.0` (pin the version) |
-
-Pick by what exists in the repo - if the entry file is named something else,
-use that. Pass that row's framework id and the framework's major version as
-`install.framework` / `install.frameworkVersion`. `install.agent` is who YOU
-are, lowercase: `lovable`, `bolt`, `v0`, `replit`, `cursor`, `claude-code`,
-`codex`, `windsurf`, or `other`. Omit any field you cannot determine.
-
-Rules for every framework:
-
-- Module scope. Not inside a component, `useEffect`, lifecycle hook, or
-  handler. The one exception is the pre-15.3 App Router row above.
-- Static import - no dynamic `import()`, no lazy chunk. Parts of the SDK act
-  the moment the bundle evaluates.
-- `init` is idempotent and SSR-safe - no guards needed.
-- Inline the key. It is a publishable key, safe in the client bundle by
-  design - do not build env-var plumbing for it.
-- Do not pass `apiHost` - the default is correct.
-- Autocapture starts immediately - do NOT instrument individual events, and do
-  not add route or history listeners.
-- Browser only. There is no server-side capture yet, so server routes,
-  handlers, and jobs are not tracked - do not build a substitute. If the
-  project is React Native, Flutter, another non-browser target, or a
-  server-only service with no frontend, stop and tell the user HeyCatch
-  doesn't support it yet.
-
-## 3. If the app has authentication, wire identity
-
-```ts
-import { identify, reset, setPersonProperties } from '@heycatch/sdk';
-
-// After sign-in. The ID is a stable internal user id - never an email or a
-// session token. Email and name go in the PROPERTIES, and sending them is
-// what makes the dashboard show "Olek Vons <olek@example.com>" instead of an
-// opaque id - always pass what the app has.
-identify(
-  user.id,
-  { email: user.email, name: user.name, plan: user.plan },
-  // Third arg is set-ONCE: written only if absent, so later sign-ins cannot
-  // overwrite it. Use for values that describe the beginning.
-  { signup_date: user.createdAt },
-);
-
-// When a property changes OUTSIDE sign-in (plan upgrade, name edit):
-setPersonProperties({ plan: 'pro' });
-
-reset(); // on sign-out, so the next visitor starts anonymous
-```
-
-Any auth provider works. All three are no-ops before `init` or on the server.
-Property values must be primitives (string / number / boolean / null). No auth
-in the app? Skip this step.
-
-## 4. Set up short links
-
-Short paths of 1-2 lowercase letters/digits are reserved for channel
-attribution and need one host redirect rule - follow
-[docs/short-links.md](./docs/short-links.md) (ships inside this package). If
-your tools cannot read or apply it, skip and tell the user short links still
-need setup.
-
-## 5. Verify
-
-Self-check - confirm every line before finishing:
-
-- [ ] `@heycatch/sdk` is in `dependencies` (not `devDependencies`)
-- [ ] `init` is called exactly once, statically imported, at the client entry
-- [ ] The project key is inlined and starts with `hck_`
-- [ ] `install` carries every field you could determine - the framework id, its
-      major version, and your own agent id. Omitting one you genuinely cannot
-      determine is fine; guessing is not
-- [ ] If the app has auth: `identify` on sign-in WITH the email/name the app
-      has as properties, `reset` on sign-out
-- [ ] Short links set up (or the user was told they still need setup)
-
-Then open or preview the app once so the first event fires. The browser console
-logs `[HeyCatch] SDK v<version> initialized → <apiHost>` on success, or a
-`[HeyCatch] …` error describing what's wrong. If you cannot run the app, tell
-the user to open it once. Then tell the user: "HeyCatch is installed - your
-dashboard will show data once people use the app."

package/docs/short-links.md

@@ -1,69 +0,0 @@
-# Short links
-
-HeyCatch attributes single-letter paths (`yoursite.com/x`) to marketing
-channels. The letter-to-channel mapping lives entirely on HeyCatch's side -
-your only job is routing:
-
-1. **Single-letter paths `/a`-`/z` are reserved for HeyCatch.** The app must
-   not have real routes there; rename any that exist (or exclude that letter
-   below).
-2. **Redirect every letter path to `/?hc=<letter>` (302).** The target must
-   carry `?hc=<letter>` - a bare redirect to `/` loses the attribution. (The
-   SDK strips the param from the URL bar after landing - nothing else to
-   clean up.)
-3. Set once - the rules never change when the user's channels change.
-
-## Add the rule for the host
-
-**Next.js** (`next.config.*`; redirects run before routes - exclude any real
-single-letter page from the regex, e.g. `([a-df-z])`):
-
-```js
-async redirects() {
-  return [{ source: '/:l([a-z])', destination: '/?hc=:l', permanent: false }];
-}
-```
-
-**Vercel (non-Next)** (`vercel.json`):
-
-```json
-{ "redirects": [{ "source": "/:l([a-z])", "destination": "/?hc=:l" }] }
-```
-
-**Netlify** (`_redirects`; the placeholder matches any single segment, but
-non-forced rules only fire when no real page matches - real routes always
-win, and a dead non-letter path like `/abou` just lands home with an `hc`
-value HeyCatch ignores. Keep this line above any `/*` catch-all):
-
-```text
-/:l  /?hc=:l  302
-```
-
-**Cloudflare Pages** (`_redirects` fires before assets - a placeholder would
-shadow real pages, so enumerate, skipping real routes):
-
-```text
-/a  /?hc=a  302
-/b  /?hc=b  302
-# ...one line per letter a-z
-```
-
-**GitHub Pages** (no redirect rules - `404.html` with an inline forward):
-
-```html
-<script>
-  var m = /^\/([a-z])\/?$/.exec(location.pathname);
-  if (m) location.replace('/?hc=' + m[1]);
-</script>
-```
-
-**Plain SPA** - no rule needed; the fallback below covers it.
-
-## Fallback: the SDK forwards by itself
-
-If you cannot edit host config on this platform, skip the rule - the SDK
-auto-forwards single-letter paths to `/?hc=<letter>` the moment it loads.
-The one requirement: unknown paths must serve a page that loads the SDK
-(automatic for SPAs and Next.js; on a static host add a catch-all fallback,
-e.g. Netlify `/* /index.html 200`). Host rules are still preferred - they
-forward before any paint, so the visitor never glimpses a not-found page.