@interfere/vite 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+<p align="center">
+  <a href="https://interfere.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://qyzkf4cgb8ydxtq1.public.blob.vercel-storage.com/v2/header/logo-dark.png">
+      <img src="https://qyzkf4cgb8ydxtq1.public.blob.vercel-storage.com/v2/header/logo-light.png" height="64">
+    </picture>
+  </a>
+  <h1 align="center">@interfere/vite</h1>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@interfere/vite"><img src="https://img.shields.io/npm/v/@interfere/vite.svg" /></a>
+  <a href="https://github.com/interfere-inc/interfere/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@interfere/vite.svg" /></a>
+  <a href="https://www.npmjs.com/package/@interfere/vite"><img src="https://img.shields.io/npm/dm/@interfere/vite.svg" /></a>
+</p>
+
+<p align="center">
+  Vite build plugin and client initialization for <a href="https://interfere.com">Interfere</a> — error tracking, session replay, and analytics for modern product teams.
+</p>
+
+<p align="center">
+  <a href="https://support.interfere.com/docs">Documentation</a>
+  ·
+  <a href="https://support.interfere.com/roadmap">Feature Requests</a>
+  ·
+  <a href="https://support.interfere.com/requests">Report a Bug</a>
+  ·
+  <a href="mailto:support@interfere.com">Get Help</a>
+</p>
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Vite `>=5`
+- React `>=19`
+- [`@interfere/react`](https://www.npmjs.com/package/@interfere/react) for the React provider and hooks
+
+### Installation
+
+```bash
+npm install @interfere/vite @interfere/react
+```
+
+### Quick Start
+
+**1. Add the Vite plugin**
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { interfere } from "@interfere/vite/plugin";
+
+export default defineConfig({
+  plugins: [react(), interfere()],
+});
+```
+
+The plugin automatically injects your build ID and release ID into the page at build time. By default the build ID is resolved from `git rev-parse HEAD`; you can override it via plugin options or the `VITE_INTERFERE_BUILD_ID` environment variable.
+
+**2. Initialize the client**
+
+```ts
+// src/main.tsx
+import { init } from "@interfere/vite/init";
+
+init();
+```
+
+Call `init()` before mounting your React tree so the SDK is ready to capture errors from first render.
+
+**3. Add the React provider**
+
+```tsx
+// src/App.tsx
+import { InterfereProvider } from "@interfere/react/provider";
+
+function App() {
+  return (
+    <InterfereProvider>
+      <YourApp />
+    </InterfereProvider>
+  );
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `VITE_INTERFERE_PUBLIC_KEY` | Yes | Your project public key (injected into the page by the plugin) |
+| `VITE_INTERFERE_BUILD_ID` | No | Override the auto-detected build ID |
+
+## Plugin Options
+
+```ts
+interfere({
+  buildId: "custom-build-id",
+  releaseId: "v1.2.3",
+});
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `buildId` | `VITE_INTERFERE_BUILD_ID` → Git SHA → random UUID | Unique identifier for this build |
+| `releaseId` | Same as `buildId` | Semantic release identifier for grouping errors by deploy |
+
+## Identity Management
+
+Link sessions to your authenticated users with `identity.set()`:
+
+```tsx
+import { useInterfere } from "@interfere/react/provider";
+
+function useInterfereIdentity() {
+  const { identity } = useInterfere();
+
+  // Clerk, Auth0, etc.
+  const { user } = useAuthProvider();
+
+  useEffect(() => {
+    if (user) {
+      identity.set({
+        identifier: user.id,
+        name: user.name,
+        email: user.email,
+        source: { type: "clerk", name: "Clerk" },
+      });
+    } else {
+      identity.clear();
+    }
+  }, [user]);
+
+  return null;
+}
+```
+
+### Parameters
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `identifier` | Yes | Unique user ID (your internal ID, not email) |
+| `source` | Yes | Auth source: `{ type: "clerk", name: "Clerk" }`, `{ type: "auth0", name: "Auth0" }`, or `{ type: "custom", name: "Your Provider" }` |
+| `name` | No | Display name |
+| `email` | No | Email address |
+| `avatar` | No | Avatar URL |
+| `traits` | No | Arbitrary key-value metadata (`Record<string, unknown>`) |
+
+### API
+
+| Method | Description |
+| --- | --- |
+| `identity.set(params)` | Link the current session to a user. Deduplicated per session — only the first call sends a request. |
+| `identity.get()` | Returns the current `IdentifyParams`, or `null` if no identity has been set. |
+
+Identity is automatically cleared when the SDK is closed or the session rotates.
+
+## Consent Management
+
+By default, all SDK features are active. To gate features behind user consent, pass a `consent` prop to the provider:
+
+```tsx
+import { InterfereProvider } from "@interfere/react/provider";
+
+function App() {
+  return (
+    <InterfereProvider consent={{ analytics: true, replay: false }}>
+      <YourApp />
+    </InterfereProvider>
+  );
+}
+```
+
+### Consent categories
+
+| Category | Plugins | Gated? |
+| --- | --- | --- |
+| `necessary` | Error tracking | Always on |
+| `analytics` | Page events, rage clicks, fingerprint | Yes |
+| `replay` | Session replay | Yes |
+
+Omitting the `consent` prop disables gating entirely (all features load). Passing it enables gating — only `necessary` plugins plus explicitly consented categories will activate.
+
+### Imperative API
+
+Use `consent.set()` and `consent.get()` from the `useInterfere` hook:
+
+```tsx
+const { consent } = useInterfere();
+
+consent.set({ analytics: true, replay: true }); // selective
+consent.set();                                   // grant all
+consent.get();                                   // current state, or null if no gating
+```
+
+### Initial consent via init
+
+To set consent before React renders (avoiding any window where non-consented plugins might load), pass it to `init()`:
+
+```ts
+import { init } from "@interfere/vite/init";
+
+init({ consent: { analytics: false, replay: false } });
+```
+
+The provider's `consent` prop will then keep it in sync as the user updates their preferences.
+
+## What's Included
+
+- **Build metadata injection** — automatically tags each build with a Git SHA-derived build and release ID
+- **Error tracking** — automatic capture of uncaught errors and unhandled rejections
+- **Session replay** — full visual playback of user sessions
+- **Page analytics** — SPA-aware pageviews and UI interaction events
+- **Rage click detection** — surface frustrated user behavior
+- **Consent gating** — fine-grained control over which features activate
+
+## License
+
+MIT

package/dist/init.d.mts

@@ -0,0 +1,7 @@
+import { ClientOptions, ClientOptions as ClientOptions$1, consent } from "@interfere/react/internal/client";
+import { ConsentCategory, ConsentState, GateableCategory } from "@interfere/types/sdk/plugins/manifest";
+
+//#region src/init.d.ts
+declare function init(opts?: ClientOptions$1): void;
+//#endregion
+export { type ClientOptions, type ConsentCategory, type ConsentState, type GateableCategory, consent, init };

package/dist/init.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.mts","names":[],"sources":["../src/init.ts"],"mappings":";;;;iBAcgB,IAAA,CAAK,IAAA,GAAO,eAAA"}

package/dist/init.mjs

@@ -0,0 +1,7 @@
+import { consent, init as init$1 } from "@interfere/react/internal/client";
+//#region src/init.ts
+function init(opts) {
+	init$1(opts);
+}
+//#endregion
+export { consent, init };

package/dist/init.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.mjs","names":[],"sources":["../src/init.ts"],"sourcesContent":["import {\n  type ClientOptions,\n  init as coreInit,\n} from \"@interfere/react/internal/client\";\n\nexport type { ClientOptions } from \"@interfere/react/internal/client\";\n// biome-ignore lint/performance/noBarrelFile: init entrypoint must re-export consent for SDK consumers.\nexport { consent } from \"@interfere/react/internal/client\";\nexport type {\n  ConsentCategory,\n  ConsentState,\n  GateableCategory,\n} from \"@interfere/types/sdk/plugins/manifest\";\n\nexport function init(opts?: ClientOptions): void {\n  coreInit(opts);\n}\n"],"mappings":";;AAcA,SAAgB,KAAK,MAA4B;AAC/C,QAAS,KAAK"}

package/dist/plugin.d.mts

@@ -0,0 +1,10 @@
+import { Plugin } from "vite";
+
+//#region src/plugin.d.ts
+interface InterfereViteOptions {
+  buildId?: string;
+  releaseId?: string;
+}
+declare function interfere(options?: InterfereViteOptions): Plugin;
+//#endregion
+export { InterfereViteOptions, interfere as default, interfere };

package/dist/plugin.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.mts","names":[],"sources":["../src/plugin.ts"],"mappings":";;;UAGiB,oBAAA;EACf,OAAA;EACA,SAAA;AAAA;AAAA,iBAWc,SAAA,CAAU,OAAA,GAAU,oBAAA,GAAuB,MAAA"}

package/dist/plugin.mjs

@@ -0,0 +1,34 @@
+import { execSync } from "node:child_process";
+//#region src/plugin.ts
+function resolveGitSha() {
+	try {
+		return execSync("git rev-parse HEAD", { encoding: "utf8" }).trim();
+	} catch {
+		return null;
+	}
+}
+function interfere(options) {
+	let buildId;
+	let releaseId;
+	let publicKey;
+	return {
+		name: "interfere",
+		enforce: "pre",
+		configResolved(config) {
+			buildId = options?.buildId ?? config.env["VITE_INTERFERE_BUILD_ID"] ?? resolveGitSha() ?? crypto.randomUUID();
+			releaseId = options?.releaseId ?? buildId;
+			publicKey = config.env["VITE_INTERFERE_PUBLIC_KEY"];
+		},
+		transformIndexHtml() {
+			const assignments = [`globalThis["__INTERFERE_BUILD_ID__"]=${JSON.stringify(buildId)};`, `globalThis["__INTERFERE_RELEASE_ID__"]=${JSON.stringify(releaseId)};`];
+			if (publicKey) assignments.push(`globalThis["__INTERFERE_PUBLIC_KEY__"]=${JSON.stringify(publicKey)};`);
+			return [{
+				tag: "script",
+				children: assignments.join(""),
+				injectTo: "head-prepend"
+			}];
+		}
+	};
+}
+//#endregion
+export { interfere as default, interfere };

package/dist/plugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.mjs","names":[],"sources":["../src/plugin.ts"],"sourcesContent":["import { execSync } from \"node:child_process\";\nimport type { HtmlTagDescriptor, Plugin } from \"vite\";\n\nexport interface InterfereViteOptions {\n  buildId?: string;\n  releaseId?: string;\n}\n\nfunction resolveGitSha(): string | null {\n  try {\n    return execSync(\"git rev-parse HEAD\", { encoding: \"utf8\" }).trim();\n  } catch {\n    return null;\n  }\n}\n\nexport function interfere(options?: InterfereViteOptions): Plugin {\n  let buildId: string;\n  let releaseId: string;\n  let publicKey: string | undefined;\n\n  return {\n    name: \"interfere\",\n    enforce: \"pre\",\n\n    configResolved(config) {\n      buildId =\n        options?.buildId ??\n        config.env[\"VITE_INTERFERE_BUILD_ID\"] ??\n        resolveGitSha() ??\n        crypto.randomUUID();\n\n      releaseId = options?.releaseId ?? buildId;\n\n      publicKey = config.env[\"VITE_INTERFERE_PUBLIC_KEY\"];\n    },\n\n    transformIndexHtml() {\n      const assignments = [\n        `globalThis[\"__INTERFERE_BUILD_ID__\"]=${JSON.stringify(buildId)};`,\n        `globalThis[\"__INTERFERE_RELEASE_ID__\"]=${JSON.stringify(releaseId)};`,\n      ];\n\n      if (publicKey) {\n        assignments.push(\n          `globalThis[\"__INTERFERE_PUBLIC_KEY__\"]=${JSON.stringify(publicKey)};`\n        );\n      }\n\n      return [\n        {\n          tag: \"script\",\n          children: assignments.join(\"\"),\n          injectTo: \"head-prepend\",\n        },\n      ] satisfies HtmlTagDescriptor[];\n    },\n  };\n}\n\nexport default interfere;\n"],"mappings":";;AAQA,SAAS,gBAA+B;AACtC,KAAI;AACF,SAAO,SAAS,sBAAsB,EAAE,UAAU,QAAQ,CAAC,CAAC,MAAM;SAC5D;AACN,SAAO;;;AAIX,SAAgB,UAAU,SAAwC;CAChE,IAAI;CACJ,IAAI;CACJ,IAAI;AAEJ,QAAO;EACL,MAAM;EACN,SAAS;EAET,eAAe,QAAQ;AACrB,aACE,SAAS,WACT,OAAO,IAAI,8BACX,eAAe,IACf,OAAO,YAAY;AAErB,eAAY,SAAS,aAAa;AAElC,eAAY,OAAO,IAAI;;EAGzB,qBAAqB;GACnB,MAAM,cAAc,CAClB,wCAAwC,KAAK,UAAU,QAAQ,CAAC,IAChE,0CAA0C,KAAK,UAAU,UAAU,CAAC,GACrE;AAED,OAAI,UACF,aAAY,KACV,0CAA0C,KAAK,UAAU,UAAU,CAAC,GACrE;AAGH,UAAO,CACL;IACE,KAAK;IACL,UAAU,YAAY,KAAK,GAAG;IAC9B,UAAU;IACX,CACF;;EAEJ"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@interfere/vite",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Vite build plugin and client initialization for Interfere.",
+  "keywords": [
+    "observability",
+    "typescript",
+    "vite",
+    "error-tracking",
+    "session-replay"
+  ],
+  "homepage": "https://interfere.com",
+  "bugs": {
+    "url": "mailto:support@interfere.com"
+  },
+  "author": "Interfere <support@interfere.com> (https://interfere.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/interfere-inc/interfere.git",
+    "directory": "src/packages/public/vite"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    "./plugin": {
+      "@source": "./src/plugin.ts",
+      "types": "./dist/plugin.d.mts",
+      "default": "./dist/plugin.mjs"
+    },
+    "./init": {
+      "@source": "./src/init.ts",
+      "types": "./dist/init.d.mts",
+      "default": "./dist/init.mjs"
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit --incremental"
+  },
+  "dependencies": {
+    "@interfere/react": "^8.1.0",
+    "@interfere/types": "^8.1.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "devDependencies": {
+    "@interfere/typescript-config": "^8.1.0",
+    "@interfere/test-utils": "^1.0.0",
+    "@types/node": "^24.12.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "tsdown": "^0.21.6",
+    "typescript": "6.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.2"
+  }
+}