@interfere/next 9.0.2 → 10.0.0

package/README.md

@@ -2,16 +2,16 @@
   <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">
+      <img src="https://qyzkf4cgb8ydxtq1.public.blob.vercel-storage.com/v2/header/logo-light.png" height="64" alt="Interfere">
     </picture>
   </a>
   <h1 align="center">@interfere/next</h1>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@interfere/next"><img src="https://img.shields.io/npm/v/@interfere/next.svg" /></a>
-  <a href="https://github.com/interfere-inc/interfere/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@interfere/next.svg" /></a>
-  <a href="https://www.npmjs.com/package/@interfere/next"><img src="https://img.shields.io/npm/dm/@interfere/next.svg" /></a>
+  <a href="https://www.npmjs.com/package/@interfere/next"><img src="https://img.shields.io/npm/v/@interfere/next.svg" alt="npm version" /></a>
+  <a href="https://github.com/interfere-inc/interfere/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@interfere/next.svg" alt="License" /></a>
+  <a href="https://www.npmjs.com/package/@interfere/next"><img src="https://img.shields.io/npm/dm/@interfere/next.svg" alt="npm downloads" /></a>
 </p>
 
 <p align="center">
@@ -69,7 +69,7 @@ export { onRequestError } from "@interfere/next/server";
 
 ```ts
 // app/api/interfere/[[...path]]/route.ts
-export { GET, POST, OPTIONS } from "@interfere/next/route-handler";
+export * from "@interfere/next/route-handler";
 ```
 
 **4. Add the provider**
@@ -98,6 +98,34 @@ export default function RootLayout({
 | Variable | Required | Description |
 | --- | --- | --- |
 | `INTERFERE_API_KEY` | Yes | Your project API key |
+| `NEXT_PUBLIC_INTERFERE_ROUTE_PREFIX` | No | Override the proxy route prefix (default: `/api/interfere`). Must match the path you mount the route handler at — e.g. set this to `/__telemetry` and mount the handler at `app/__telemetry/[[...path]]/route.ts`. Read by both the server route handler and the client SDK. |
+
+## Custom Route Prefix
+
+By default the SDK proxies all telemetry through `/api/interfere`. You can move this to any path by setting `NEXT_PUBLIC_INTERFERE_ROUTE_PREFIX` and mounting the route handler at the matching location.
+
+**Why change it?** A custom prefix lets you avoid ad-blocker deny-lists that target well-known SDK paths, or align with your own API routing conventions.
+
+**1. Set the environment variable**
+
+```env
+NEXT_PUBLIC_INTERFERE_ROUTE_PREFIX=/__telemetry
+```
+
+**2. Mount the route handler at the matching path**
+
+```ts
+// app/__telemetry/[[...path]]/route.ts
+export * from "@interfere/next/route-handler";
+```
+
+**Normalization rules**
+
+| Input | Resolved |
+| --- | --- |
+| `/__telemetry` | `/__telemetry` |
+| `__telemetry/` | `/__telemetry` |
+| *(empty)* or `/` | `/api/interfere` (default) |
 
 ## Identity Management
 

package/dist/config.d.mts

@@ -1,16 +1,35 @@
-import { Envelope } from "@interfere/types/sdk/envelope";
+import { ReleaseSlug } from "@interfere/types/releases/slug";
 import { NextConfig } from "next";
 
 //#region src/config.d.ts
-interface InterfereConfig extends Partial<Pick<Envelope, "buildId" | "releaseId">> {}
 interface NextConfigWithInterfere extends NextConfig {
-  interfere?: InterfereConfig;
+  /**
+   * Reserved for future SDK config. Setting `buildId` here is rejected
+   * loudly — it caused server/client slug drift in 9.x. Override the
+   * commit SHA via the `INTERFERE_SOURCE_ID` env var (set on both build
+   * and runtime envs) instead.
+   */
+  interfere?: {
+    readonly buildId?: never;
+  };
 }
 interface ResolvedBuildConfig {
   readonly apiKey: string | null;
   readonly apiUrl: string;
+  /**
+   * Server-internal — the build pipeline still uses this to key R2
+   * source-map paths until Phase 7 re-keys them to slug. Never injected
+   * into the bundle; never exposed via env.
+   */
   readonly buildId: string | null;
-  readonly releaseId: string | null;
+  /**
+   * Deterministically derived from the leading 16 hex of the commit SHA, so
+   * the build step and the collector arrive at the same
+   * `rel_xxxxxxxxxxxxxxxx` without a round-trip. Stamped into the bundle as
+   * `__INTERFERE_RELEASE_SLUG__`. `null` when no commit SHA is available —
+   * release-pipeline calls bail in that case.
+   */
+  readonly releaseSlug: ReleaseSlug | null;
 }
 declare function withInterfere(nextConfig?: NextConfigWithInterfere): NextConfig;
 interface ProductionCompileContext {
@@ -18,4 +37,4 @@ interface ProductionCompileContext {
   readonly projectDir: string;
 }
 //#endregion
-export { InterfereConfig, NextConfigWithInterfere, ProductionCompileContext, ResolvedBuildConfig, withInterfere };
+export { NextConfigWithInterfere, ProductionCompileContext, ResolvedBuildConfig, withInterfere };

package/dist/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","names":[],"sources":["../src/config.ts"],"mappings":";;;;UAeiB,eAAA,SACP,OAAA,CAAQ,IAAA,CAAK,QAAA;AAAA,UAEN,uBAAA,SAAgC,UAAA;EAC/C,SAAA,GAAY,eAAA;AAAA;AAAA,UAGG,mBAAA;EAAA,SACN,MAAA;EAAA,SACA,MAAA;EAAA,SACA,OAAA;EAAA,SACA,SAAA;AAAA;AAAA,iBAGK,aAAA,CACd,UAAA,GAAY,uBAAA,GACX,UAAA;AAAA,UA6Fc,wBAAA;EAAA,SACN,OAAA;EAAA,SACA,UAAA;AAAA"}
+{"version":3,"file":"config.d.mts","names":[],"sources":["../src/config.ts"],"mappings":";;;;UAgBiB,uBAAA,SAAgC,UAAA;;AAAjD;;;;;EAOE,SAAA;IAAA,SAAuB,OAAA;EAAA;AAAA;AAAA,UAGR,mBAAA;EAAA,SACN,MAAA;EAAA,SACA,MAAA;EAcwB;;;;;EAAA,SARxB,OAAA;EAQwB;;AAGnC;;;;;EAHmC,SAAxB,WAAA,EAAa,WAAA;AAAA;AAAA,iBAGR,aAAA,CACd,UAAA,GAAY,uBAAA,GACX,UAAA;AAAA,UAwIc,wBAAA;EAAA,SACN,OAAA;EAAA,SACA,UAAA;AAAA"}

package/dist/config.mjs

@@ -1,79 +1,89 @@
 import { configureBuild } from "./internal/build/configure-build.mjs";
-import { log } from "./internal/logger.mjs";
-import { runGitCommand } from "./internal/build/release/git.mjs";
 import { readInterfereEnv } from "./internal/env.mjs";
+import { FatalError, log } from "./internal/logger.mjs";
+import { resolveReleaseSlug } from "./internal/release-slug.mjs";
+import { readNextMajorVersion, warnIfServerInstrumentationMissing } from "./internal/setup-warnings.mjs";
 import { omitUndefined } from "@interfere/helpers/omit-undefined";
-import { releaseDestinationIdEnvKeys, releaseSourceIdEnvKeys } from "@interfere/types/integrations";
-import { parseEnvValue, readFirstEnvValue } from "@interfere/types/sdk/env";
 //#region src/config.ts
+const NEXT_INSTRUMENTATION_HOOK_FLAG_LAST_MAJOR = 14;
 function withInterfere(nextConfig = {}) {
 	const { interfere, env: userEnv, webpack, turbopack, compiler, productionBrowserSourceMaps, ...rest } = nextConfig;
-	const config = resolveBuildConfig(interfere);
+	if (interfere && "buildId" in interfere && interfere.buildId !== void 0) return log.fatal("Removed: interfere.buildId", ["`interfere.buildId` was removed in SDK 10. It only worked at build time, so server-side spans drifted from the bundle's slug.", "Override the commit SHA via the `INTERFERE_SOURCE_ID` env var on both build and runtime envs instead."]);
+	const projectDir = process.cwd();
+	const config = resolveBuildConfig();
 	const forceEnable = !!process.env["NEXT_PUBLIC_INTERFERE_FORCE_ENABLE"];
 	const build = configureBuild({
 		existingWebpack: webpack,
 		existingTurbopack: turbopack,
-		projectDir: process.cwd(),
+		projectDir,
 		values: {
-			__INTERFERE_BUILD_ID__: config.buildId,
-			__INTERFERE_RELEASE_ID__: config.releaseId,
+			__INTERFERE_RELEASE_SLUG__: forceEnable ? "rel_local" : config.releaseSlug,
 			...forceEnable && { __INTERFERE_FORCE_ENABLE__: true }
 		}
 	});
 	if (config.apiKey !== null && !build.webpack && !build.turbopack) return log.fatal("Missing instrumentation client", ["INTERFERE_API_KEY is set but no instrumentation-client file was found.", "Create an instrumentation-client.ts file in your project root or src/ directory."]);
+	if (config.apiKey !== null) warnIfServerInstrumentationMissing(projectDir);
+	const nextMajor = readNextMajorVersion(projectDir);
+	const needsInstrumentationHookFlag = nextMajor === null || nextMajor <= NEXT_INSTRUMENTATION_HOOK_FLAG_LAST_MAJOR;
 	const existingHook = compiler?.runAfterProductionCompile;
 	const browserSourceMaps = config.apiKey === null ? productionBrowserSourceMaps : true;
+	if (config.apiKey !== null && productionBrowserSourceMaps === false) log.warn("Forcing productionBrowserSourceMaps", ["withInterfere() requires production source maps to symbolicate errors.", "Your `productionBrowserSourceMaps: false` was overridden to `true`."]);
 	return {
 		...rest,
-		env: mergeEnvConfig(userEnv, config),
+		...userEnv ? { env: userEnv } : {},
 		compiler: {
 			...omitUndefined(compiler ?? {}),
 			async runAfterProductionCompile(context) {
 				if (existingHook) await existingHook(context);
-				await runBuildReleasePipeline(context, config);
+				try {
+					await runBuildReleasePipeline(context, config);
+				} catch (error) {
+					if (error instanceof FatalError) throw error;
+					const message = error instanceof Error ? error.message : String(error);
+					log.warn("Skipping release pipeline", [
+						"Interfere encountered an unexpected error.",
+						"Build will continue, but this release's data will be ingested, but ignored as evidence when generating insights.",
+						`Error: ${message}`
+					]);
+				}
 			}
 		},
 		...omitUndefined({
 			productionBrowserSourceMaps: browserSourceMaps,
 			turbopack: build.turbopack,
 			webpack: build.webpack
-		})
+		}),
+		...needsInstrumentationHookFlag ? { experimental: {
+			...rest.experimental ?? {},
+			instrumentationHook: true
+		} } : {}
 	};
 }
-function resolveBuildConfig(interfere) {
+function resolveBuildConfig() {
 	const { apiKey, apiUrl } = readInterfereEnv();
-	const buildId = parseEnvValue(interfere?.buildId) ?? readFirstEnvValue(process.env, releaseSourceIdEnvKeys) ?? runGitCommand("git rev-parse HEAD");
-	const releaseId = parseEnvValue(interfere?.releaseId) ?? readFirstEnvValue(process.env, releaseDestinationIdEnvKeys) ?? buildId;
+	const { commitSha, slug } = resolveReleaseSlug();
 	return {
 		apiKey: apiKey ?? null,
 		apiUrl,
-		buildId,
-		releaseId
-	};
-}
-function mergeEnvConfig(userEnv, config) {
-	const merged = {};
-	if (config.buildId !== null) merged["NEXT_PUBLIC_INTERFERE_BUILD_ID"] = config.buildId;
-	if (config.releaseId !== null) merged["NEXT_PUBLIC_INTERFERE_RELEASE_ID"] = config.releaseId;
-	return {
-		...merged,
-		...userEnv
+		buildId: commitSha,
+		releaseSlug: slug
 	};
 }
 async function runBuildReleasePipeline(context, config) {
-	const { apiKey, buildId } = config;
+	const { apiKey, buildId, releaseSlug } = config;
 	if (!apiKey) return log.fatal("API key not set", [
 		"withInterfere() requires an API key to upload source maps during production builds.",
 		"Set the INTERFERE_API_KEY environment variable, or remove withInterfere() from your Next.js config.",
 		"See: https://support.interfere.com/docs/guides/next-js"
 	]);
-	if (!buildId) return log.fatal("Build ID missing", ["Could not resolve a build ID from config, environment variables, or git.", "Set INTERFERE_BUILD_ID, or ensure git is available in your build environment."]);
+	if (!(buildId && releaseSlug)) return log.fatal("Commit SHA missing", ["Could not resolve a commit SHA from environment variables or git.", "Set `INTERFERE_SOURCE_ID`, ensure your CI exposes its git SHA env var (e.g. `VERCEL_GIT_COMMIT_SHA`, `GITHUB_SHA`), or run inside a git checkout."]);
 	const { runBuildPipeline } = await import("./internal/build/pipeline.mjs");
 	try {
 		const result = await runBuildPipeline(context, {
 			...config,
 			apiKey,
-			buildId
+			buildId,
+			releaseSlug
 		});
 		if (!result.ready) {
 			log.warn("Skipping", ["No source maps found"]);

package/dist/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../src/config.ts"],"sourcesContent":["import { omitUndefined } from \"@interfere/helpers/omit-undefined\";\nimport {\n  releaseDestinationIdEnvKeys,\n  releaseSourceIdEnvKeys,\n} from \"@interfere/types/integrations\";\nimport { parseEnvValue, readFirstEnvValue } from \"@interfere/types/sdk/env\";\nimport type { Envelope } from \"@interfere/types/sdk/envelope\";\n\nimport type { NextConfig } from \"next\";\n\nimport { configureBuild } from \"./internal/build/configure-build.js\";\nimport { runGitCommand } from \"./internal/build/release/git.js\";\nimport { readInterfereEnv } from \"./internal/env.js\";\nimport { log } from \"./internal/logger.js\";\n\nexport interface InterfereConfig\n  extends Partial<Pick<Envelope, \"buildId\" | \"releaseId\">> {}\n\nexport interface NextConfigWithInterfere extends NextConfig {\n  interfere?: InterfereConfig;\n}\n\nexport interface ResolvedBuildConfig {\n  readonly apiKey: string | null;\n  readonly apiUrl: string;\n  readonly buildId: string | null;\n  readonly releaseId: string | null;\n}\n\nexport function withInterfere(\n  nextConfig: NextConfigWithInterfere = {}\n): NextConfig {\n  const {\n    interfere,\n    env: userEnv,\n    webpack,\n    turbopack,\n    compiler,\n    productionBrowserSourceMaps,\n    ...rest\n  } = nextConfig;\n\n  const config = resolveBuildConfig(interfere);\n  const forceEnable = !!process.env[\"NEXT_PUBLIC_INTERFERE_FORCE_ENABLE\"];\n  const build = configureBuild({\n    existingWebpack: webpack,\n    existingTurbopack: turbopack,\n    projectDir: process.cwd(),\n    values: {\n      __INTERFERE_BUILD_ID__: config.buildId,\n      __INTERFERE_RELEASE_ID__: config.releaseId,\n      ...(forceEnable && { __INTERFERE_FORCE_ENABLE__: true }),\n    },\n  });\n\n  if (config.apiKey !== null && !build.webpack && !build.turbopack) {\n    return log.fatal(\"Missing instrumentation client\", [\n      \"INTERFERE_API_KEY is set but no instrumentation-client file was found.\",\n      \"Create an instrumentation-client.ts file in your project root or src/ directory.\",\n    ]);\n  }\n\n  const existingHook = (compiler as NextCompilerWithProductionHook | undefined)\n    ?.runAfterProductionCompile;\n\n  const browserSourceMaps =\n    config.apiKey === null ? productionBrowserSourceMaps : true;\n\n  return {\n    ...rest,\n    env: mergeEnvConfig(userEnv, config),\n\n    compiler: {\n      ...omitUndefined(compiler ?? {}),\n      async runAfterProductionCompile(context: ProductionCompileContext) {\n        if (existingHook) {\n          await existingHook(context);\n        }\n\n        await runBuildReleasePipeline(context, config);\n      },\n    },\n\n    ...omitUndefined({\n      productionBrowserSourceMaps: browserSourceMaps,\n      turbopack: build.turbopack,\n      webpack: build.webpack,\n    }),\n  };\n}\n\nfunction resolveBuildConfig(interfere?: InterfereConfig): ResolvedBuildConfig {\n  const { apiKey, apiUrl } = readInterfereEnv();\n\n  const buildId =\n    parseEnvValue(interfere?.buildId) ??\n    readFirstEnvValue(process.env, releaseSourceIdEnvKeys) ??\n    runGitCommand(\"git rev-parse HEAD\");\n\n  const releaseId =\n    parseEnvValue(interfere?.releaseId) ??\n    readFirstEnvValue(process.env, releaseDestinationIdEnvKeys) ??\n    buildId;\n\n  return { apiKey: apiKey ?? null, apiUrl, buildId, releaseId };\n}\n\nfunction mergeEnvConfig(\n  userEnv: NextConfig[\"env\"] | undefined,\n  config: ResolvedBuildConfig\n): Record<string, string | undefined> {\n  const merged: Record<string, string> = {};\n\n  if (config.buildId !== null) {\n    merged[\"NEXT_PUBLIC_INTERFERE_BUILD_ID\"] = config.buildId;\n  }\n\n  if (config.releaseId !== null) {\n    merged[\"NEXT_PUBLIC_INTERFERE_RELEASE_ID\"] = config.releaseId;\n  }\n\n  return { ...merged, ...userEnv };\n}\n\nexport interface ProductionCompileContext {\n  readonly distDir: string;\n  readonly projectDir: string;\n}\n\ntype NextCompilerWithProductionHook = NonNullable<NextConfig[\"compiler\"]> & {\n  runAfterProductionCompile?: (\n    context: ProductionCompileContext\n  ) => void | Promise<void>;\n};\n\nasync function runBuildReleasePipeline(\n  context: ProductionCompileContext,\n  config: ResolvedBuildConfig\n): Promise<void> {\n  const { apiKey, buildId } = config;\n\n  if (!apiKey) {\n    return log.fatal(\"API key not set\", [\n      \"withInterfere() requires an API key to upload source maps during production builds.\",\n      \"Set the INTERFERE_API_KEY environment variable, or remove withInterfere() from your Next.js config.\",\n      \"See: https://support.interfere.com/docs/guides/next-js\",\n    ]);\n  }\n\n  if (!buildId) {\n    return log.fatal(\"Build ID missing\", [\n      \"Could not resolve a build ID from config, environment variables, or git.\",\n      \"Set INTERFERE_BUILD_ID, or ensure git is available in your build environment.\",\n    ]);\n  }\n\n  const { runBuildPipeline } = await import(\"./internal/build/pipeline.js\");\n\n  try {\n    const result = await runBuildPipeline(context, {\n      ...config,\n      apiKey,\n      buildId,\n    });\n\n    if (!result.ready) {\n      log.warn(\"Skipping\", [\"No source maps found\"]);\n      return;\n    }\n\n    log.info(\"Completed\", [\n      `https://interfere.com/~/${result.config?.org.slug}/surfaces/${result.config?.surface.slug}`,\n      `Release: ${result.release?.destination.slug ?? \"Unknown\"}`,\n      `Build: ${result.buildId}`,\n      `Artifacts: ${result.fileCount} source maps`,\n    ]);\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n\n    log.warn(\"Skipping release pipeline\", [\n      \"Interfere failed to process this release.\",\n      \"Events from this release will be ingested, but ignored as evidence when generating insights.\",\n      \"Please check https://status.interfere.com for any outages, or contact support@interfere.com if the problem persists.\",\n      `Error: ${message}`,\n    ]);\n\n    return;\n  }\n}\n"],"mappings":";;;;;;;;AA6BA,SAAgB,cACd,aAAsC,EAAE,EAC5B;CACZ,MAAM,EACJ,WACA,KAAK,SACL,SACA,WACA,UACA,6BACA,GAAG,SACD;CAEJ,MAAM,SAAS,mBAAmB,UAAU;CAC5C,MAAM,cAAc,CAAC,CAAC,QAAQ,IAAI;CAClC,MAAM,QAAQ,eAAe;EAC3B,iBAAiB;EACjB,mBAAmB;EACnB,YAAY,QAAQ,KAAK;EACzB,QAAQ;GACN,wBAAwB,OAAO;GAC/B,0BAA0B,OAAO;GACjC,GAAI,eAAe,EAAE,4BAA4B,MAAM;GACxD;EACF,CAAC;AAEF,KAAI,OAAO,WAAW,QAAQ,CAAC,MAAM,WAAW,CAAC,MAAM,UACrD,QAAO,IAAI,MAAM,kCAAkC,CACjD,0EACA,mFACD,CAAC;CAGJ,MAAM,eAAgB,UAClB;CAEJ,MAAM,oBACJ,OAAO,WAAW,OAAO,8BAA8B;AAEzD,QAAO;EACL,GAAG;EACH,KAAK,eAAe,SAAS,OAAO;EAEpC,UAAU;GACR,GAAG,cAAc,YAAY,EAAE,CAAC;GAChC,MAAM,0BAA0B,SAAmC;AACjE,QAAI,aACF,OAAM,aAAa,QAAQ;AAG7B,UAAM,wBAAwB,SAAS,OAAO;;GAEjD;EAED,GAAG,cAAc;GACf,6BAA6B;GAC7B,WAAW,MAAM;GACjB,SAAS,MAAM;GAChB,CAAC;EACH;;AAGH,SAAS,mBAAmB,WAAkD;CAC5E,MAAM,EAAE,QAAQ,WAAW,kBAAkB;CAE7C,MAAM,UACJ,cAAc,WAAW,QAAQ,IACjC,kBAAkB,QAAQ,KAAK,uBAAuB,IACtD,cAAc,qBAAqB;CAErC,MAAM,YACJ,cAAc,WAAW,UAAU,IACnC,kBAAkB,QAAQ,KAAK,4BAA4B,IAC3D;AAEF,QAAO;EAAE,QAAQ,UAAU;EAAM;EAAQ;EAAS;EAAW;;AAG/D,SAAS,eACP,SACA,QACoC;CACpC,MAAM,SAAiC,EAAE;AAEzC,KAAI,OAAO,YAAY,KACrB,QAAO,oCAAoC,OAAO;AAGpD,KAAI,OAAO,cAAc,KACvB,QAAO,sCAAsC,OAAO;AAGtD,QAAO;EAAE,GAAG;EAAQ,GAAG;EAAS;;AAclC,eAAe,wBACb,SACA,QACe;CACf,MAAM,EAAE,QAAQ,YAAY;AAE5B,KAAI,CAAC,OACH,QAAO,IAAI,MAAM,mBAAmB;EAClC;EACA;EACA;EACD,CAAC;AAGJ,KAAI,CAAC,QACH,QAAO,IAAI,MAAM,oBAAoB,CACnC,4EACA,gFACD,CAAC;CAGJ,MAAM,EAAE,qBAAqB,MAAM,OAAO;AAE1C,KAAI;EACF,MAAM,SAAS,MAAM,iBAAiB,SAAS;GAC7C,GAAG;GACH;GACA;GACD,CAAC;AAEF,MAAI,CAAC,OAAO,OAAO;AACjB,OAAI,KAAK,YAAY,CAAC,uBAAuB,CAAC;AAC9C;;AAGF,MAAI,KAAK,aAAa;GACpB,2BAA2B,OAAO,QAAQ,IAAI,KAAK,YAAY,OAAO,QAAQ,QAAQ;GACtF,YAAY,OAAO,SAAS,YAAY,QAAQ;GAChD,UAAU,OAAO;GACjB,cAAc,OAAO,UAAU;GAChC,CAAC;UACK,OAAO;EACd,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAEtE,MAAI,KAAK,6BAA6B;GACpC;GACA;GACA;GACA,UAAU;GACX,CAAC;AAEF"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../src/config.ts"],"sourcesContent":["import { omitUndefined } from \"@interfere/helpers/omit-undefined\";\nimport type { ReleaseSlug } from \"@interfere/types/releases/slug\";\n\nimport type { NextConfig } from \"next\";\n\nimport { configureBuild } from \"./internal/build/configure-build.js\";\nimport { readInterfereEnv } from \"./internal/env.js\";\nimport { FatalError, log } from \"./internal/logger.js\";\nimport { resolveReleaseSlug } from \"./internal/release-slug.js\";\nimport {\n  readNextMajorVersion,\n  warnIfServerInstrumentationMissing,\n} from \"./internal/setup-warnings.js\";\n\nconst NEXT_INSTRUMENTATION_HOOK_FLAG_LAST_MAJOR = 14;\n\nexport interface NextConfigWithInterfere extends NextConfig {\n  /**\n   * Reserved for future SDK config. Setting `buildId` here is rejected\n   * loudly — it caused server/client slug drift in 9.x. Override the\n   * commit SHA via the `INTERFERE_SOURCE_ID` env var (set on both build\n   * and runtime envs) instead.\n   */\n  interfere?: { readonly buildId?: never };\n}\n\nexport interface ResolvedBuildConfig {\n  readonly apiKey: string | null;\n  readonly apiUrl: string;\n  /**\n   * Server-internal — the build pipeline still uses this to key R2\n   * source-map paths until Phase 7 re-keys them to slug. Never injected\n   * into the bundle; never exposed via env.\n   */\n  readonly buildId: string | null;\n  /**\n   * Deterministically derived from the leading 16 hex of the commit SHA, so\n   * the build step and the collector arrive at the same\n   * `rel_xxxxxxxxxxxxxxxx` without a round-trip. Stamped into the bundle as\n   * `__INTERFERE_RELEASE_SLUG__`. `null` when no commit SHA is available —\n   * release-pipeline calls bail in that case.\n   */\n  readonly releaseSlug: ReleaseSlug | null;\n}\n\nexport function withInterfere(\n  nextConfig: NextConfigWithInterfere = {}\n): NextConfig {\n  const {\n    interfere,\n    env: userEnv,\n    webpack,\n    turbopack,\n    compiler,\n    productionBrowserSourceMaps,\n    ...rest\n  } = nextConfig;\n\n  if (interfere && \"buildId\" in interfere && interfere.buildId !== undefined) {\n    return log.fatal(\"Removed: interfere.buildId\", [\n      \"`interfere.buildId` was removed in SDK 10. It only worked at build time, so server-side spans drifted from the bundle's slug.\",\n      \"Override the commit SHA via the `INTERFERE_SOURCE_ID` env var on both build and runtime envs instead.\",\n    ]);\n  }\n\n  const projectDir = process.cwd();\n  const config = resolveBuildConfig();\n  const forceEnable = !!process.env[\"NEXT_PUBLIC_INTERFERE_FORCE_ENABLE\"];\n  // Force-enable overrides the derived slug with a known sentinel. `next\n  // dev` doesn't run the build pipeline, so any commit-derived slug\n  // wouldn't be preflight-confirmed at the collector. The sandbox/preview\n  // DB seeds `rel_local` as preflight-confirmed (see ENG-1353); prod\n  // collectors silently drop force-enabled batches by header (ENG-1356).\n  const releaseSlug = forceEnable ? \"rel_local\" : config.releaseSlug;\n  const build = configureBuild({\n    existingWebpack: webpack,\n    existingTurbopack: turbopack,\n    projectDir,\n    values: {\n      __INTERFERE_RELEASE_SLUG__: releaseSlug,\n      ...(forceEnable && { __INTERFERE_FORCE_ENABLE__: true }),\n    },\n  });\n\n  if (config.apiKey !== null && !build.webpack && !build.turbopack) {\n    return log.fatal(\"Missing instrumentation client\", [\n      \"INTERFERE_API_KEY is set but no instrumentation-client file was found.\",\n      \"Create an instrumentation-client.ts file in your project root or src/ directory.\",\n    ]);\n  }\n\n  if (config.apiKey !== null) {\n    warnIfServerInstrumentationMissing(projectDir);\n  }\n\n  // `experimental.instrumentationHook` is required to opt in to\n  // `instrumentation.ts` on Next 13–14, then becomes default-on (and the\n  // flag is removed) in 15+. Default to setting the flag if we can't read\n  // the version (monorepo hoist, weird resolve) — cheap on 15+ and avoids\n  // silent breakage on 13/14.\n  const nextMajor = readNextMajorVersion(projectDir);\n  const needsInstrumentationHookFlag =\n    nextMajor === null ||\n    nextMajor <= NEXT_INSTRUMENTATION_HOOK_FLAG_LAST_MAJOR;\n\n  const existingHook = (compiler as NextCompilerWithProductionHook | undefined)\n    ?.runAfterProductionCompile;\n\n  // Production source maps are required for symbolication. We force them\n  // on whenever an API key is present; flip the customer's explicit\n  // `false` to `true` and log so the change is visible.\n  const browserSourceMaps =\n    config.apiKey === null ? productionBrowserSourceMaps : true;\n  if (config.apiKey !== null && productionBrowserSourceMaps === false) {\n    log.warn(\"Forcing productionBrowserSourceMaps\", [\n      \"withInterfere() requires production source maps to symbolicate errors.\",\n      \"Your `productionBrowserSourceMaps: false` was overridden to `true`.\",\n    ]);\n  }\n\n  return {\n    ...rest,\n    ...(userEnv ? { env: userEnv } : {}),\n\n    compiler: {\n      ...omitUndefined(compiler ?? {}),\n      async runAfterProductionCompile(context: ProductionCompileContext) {\n        if (existingHook) {\n          await existingHook(context);\n        }\n\n        try {\n          await runBuildReleasePipeline(context, config);\n        } catch (error) {\n          if (error instanceof FatalError) {\n            throw error;\n          }\n\n          const message =\n            error instanceof Error ? error.message : String(error);\n\n          log.warn(\"Skipping release pipeline\", [\n            \"Interfere encountered an unexpected error.\",\n            \"Build will continue, but this release's data will be ingested, but ignored as evidence when generating insights.\",\n            `Error: ${message}`,\n          ]);\n        }\n      },\n    },\n\n    ...omitUndefined({\n      productionBrowserSourceMaps: browserSourceMaps,\n      turbopack: build.turbopack,\n      webpack: build.webpack,\n    }),\n\n    // `instrumentationHook` is a Next 13–14 flag — required to opt into\n    // `instrumentation.ts`, removed in 15+ where the hook is default-on. The\n    // current Next type defs (peer-dep `^16`) no longer declare it, so we\n    // cast through to set it without touching the input config's type.\n    ...(needsInstrumentationHookFlag\n      ? {\n          experimental: {\n            ...(rest.experimental ?? {}),\n            instrumentationHook: true,\n          } as NonNullable<NextConfig[\"experimental\"]>,\n        }\n      : {}),\n  };\n}\n\nfunction resolveBuildConfig(): ResolvedBuildConfig {\n  const { apiKey, apiUrl } = readInterfereEnv();\n  const { commitSha, slug } = resolveReleaseSlug();\n\n  return {\n    apiKey: apiKey ?? null,\n    apiUrl,\n    buildId: commitSha,\n    releaseSlug: slug,\n  };\n}\n\nexport interface ProductionCompileContext {\n  readonly distDir: string;\n  readonly projectDir: string;\n}\n\ntype NextCompilerWithProductionHook = NonNullable<NextConfig[\"compiler\"]> & {\n  runAfterProductionCompile?: (\n    context: ProductionCompileContext\n  ) => void | Promise<void>;\n};\n\nasync function runBuildReleasePipeline(\n  context: ProductionCompileContext,\n  config: ResolvedBuildConfig\n): Promise<void> {\n  const { apiKey, buildId, releaseSlug } = config;\n\n  if (!apiKey) {\n    return log.fatal(\"API key not set\", [\n      \"withInterfere() requires an API key to upload source maps during production builds.\",\n      \"Set the INTERFERE_API_KEY environment variable, or remove withInterfere() from your Next.js config.\",\n      \"See: https://support.interfere.com/docs/guides/next-js\",\n    ]);\n  }\n\n  if (!(buildId && releaseSlug)) {\n    return log.fatal(\"Commit SHA missing\", [\n      \"Could not resolve a commit SHA from environment variables or git.\",\n      \"Set `INTERFERE_SOURCE_ID`, ensure your CI exposes its git SHA env var (e.g. `VERCEL_GIT_COMMIT_SHA`, `GITHUB_SHA`), or run inside a git checkout.\",\n    ]);\n  }\n\n  const { runBuildPipeline } = await import(\"./internal/build/pipeline.js\");\n\n  try {\n    const result = await runBuildPipeline(context, {\n      ...config,\n      apiKey,\n      buildId,\n      releaseSlug,\n    });\n\n    if (!result.ready) {\n      log.warn(\"Skipping\", [\"No source maps found\"]);\n      return;\n    }\n\n    log.info(\"Completed\", [\n      `https://interfere.com/~/${result.config?.org.slug}/surfaces/${result.config?.surface.slug}`,\n      `Release: ${result.release?.destination.slug ?? \"Unknown\"}`,\n      `Build: ${result.buildId}`,\n      `Artifacts: ${result.fileCount} source maps`,\n    ]);\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n\n    log.warn(\"Skipping release pipeline\", [\n      \"Interfere failed to process this release.\",\n      \"Events from this release will be ingested, but ignored as evidence when generating insights.\",\n      \"Please check https://status.interfere.com for any outages, or contact support@interfere.com if the problem persists.\",\n      `Error: ${message}`,\n    ]);\n\n    return;\n  }\n}\n"],"mappings":"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"}

package/dist/instrument-client.d.mts

@@ -1,6 +1,17 @@
-import { ClientOptions, ClientOptions as ClientOptions$1, consent } from "@interfere/react/internal/client";
+import { capture, span } from "@interfere/react/api";
+import * as _$_interfere_types_sdk_plugins_manifest0 from "@interfere/types/sdk/plugins/manifest";
+import { ConsentCategory, ConsentState, GateableCategory } from "@interfere/types/sdk/plugins/manifest";
+import * as _$_interfere_react_internal_kernel0 from "@interfere/react/internal/kernel";
+import { Kernel, KernelInternalOptions, KernelOptions } from "@interfere/react/internal/kernel";
+import * as _$_interfere_types_sdk_identify0 from "@interfere/types/sdk/identify";
 
 //#region src/instrument-client.d.ts
-declare function init(opts?: ClientOptions$1): void;
+declare const close: () => Promise<void>, consent: {
+    get(): _$_interfere_types_sdk_plugins_manifest0.ConsentState | null;
+    set(value?: _$_interfere_types_sdk_plugins_manifest0.ConsentState): void;
+  }, getKernel: () => _$_interfere_react_internal_kernel0.Kernel, getKernelOrNull: () => _$_interfere_react_internal_kernel0.Kernel | null, identity: {
+    get(): _$_interfere_types_sdk_identify0.IdentifyParams | null;
+    set(params: _$_interfere_types_sdk_identify0.IdentifyParams): Promise<void>;
+  }, init: (opts?: _$_interfere_react_internal_kernel0.KernelOptions) => Promise<_$_interfere_react_internal_kernel0.Kernel | null>, subscribeToKernel: (listener: () => void) => () => void;
 //#endregion
-export { type ClientOptions, consent, init };
+export { type ConsentCategory, type ConsentState, type GateableCategory, type Kernel, type KernelInternalOptions, type KernelOptions, capture, close, consent, getKernel, getKernelOrNull, identity, init, span, subscribeToKernel };

package/dist/instrument-client.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-client.d.mts","names":[],"sources":["../src/instrument-client.ts"],"mappings":";;;iBAYgB,IAAA,CAAK,IAAA,GAAO,eAAA"}
+{"version":3,"file":"instrument-client.d.mts","names":[],"sources":["../src/instrument-client.ts"],"mappings":";;;;;;;;cAuBE,KAAA,QAAK,OAAA,QAAA,OAAA;WAAA,wCAAA,CAAA,YAAA;;0DAEI,MAAA,EAAA,eAAA,QAAA,mCAAA,CACM,MAAA,SAAA,QAAA;WAAA,gCAAA,CAAA,cAAA;;YAEX,IAAA,uCAAA,aAAA,KAAA,OAAA,CAAA,mCAAA,CAAA,MAAA,UAAA,iBAAA,GACa,QAAA"}

package/dist/instrument-client.mjs

@@ -1,11 +1,9 @@
 import { PRODUCER_VERSION } from "./internal/version.mjs";
-import { consent, init as init$1 } from "@interfere/react/internal/client";
-//#region src/instrument-client.ts
-function init(opts) {
-	init$1({
-		...opts,
-		_wrapperVersions: [PRODUCER_VERSION, ...opts?._wrapperVersions ?? []]
-	});
-}
+import { createWrapperSingleton } from "@interfere/react/internal/wrapper-singleton";
+import { capture, span } from "@interfere/react/api";
+const { close, consent, getKernel, getKernelOrNull, identity, init, subscribeToKernel } = createWrapperSingleton({
+	producerVersion: PRODUCER_VERSION,
+	initEntryName: "instrumentation-client"
+});
 //#endregion
-export { consent, init };
+export { capture, close, consent, getKernel, getKernelOrNull, identity, init, span, subscribeToKernel };

package/dist/instrument-client.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"instrument-client.mjs","names":[],"sources":["../src/instrument-client.ts"],"sourcesContent":["import { init as coreInit } from \"@interfere/react/internal/client\";\n\n// biome-ignore lint/performance/noBarrelFile: Next.js instrument-client entrypoint should be a direct re-export.\nexport {\n  type ClientOptions,\n  consent,\n} from \"@interfere/react/internal/client\";\n\nimport type { ClientOptions } from \"@interfere/react/internal/client\";\n\nimport { PRODUCER_VERSION } from \"./internal/version.js\";\n\nexport function init(opts?: ClientOptions): void {\n  coreInit({\n    ...opts,\n    _wrapperVersions: [PRODUCER_VERSION, ...(opts?._wrapperVersions ?? [])],\n  });\n}\n"],"mappings":";;;AAYA,SAAgB,KAAK,MAA4B;AAC/C,QAAS;EACP,GAAG;EACH,kBAAkB,CAAC,kBAAkB,GAAI,MAAM,oBAAoB,EAAE,CAAE;EACxE,CAAC"}
+{"version":3,"file":"instrument-client.mjs","names":[],"sources":["../src/instrument-client.ts"],"sourcesContent":["import { createWrapperSingleton } from \"@interfere/react/internal/wrapper-singleton\";\n\nimport { PRODUCER_VERSION } from \"./internal/version.js\";\n\n// biome-ignore lint/performance/noBarrelFile: customer-facing one-import surface — `@interfere/next` re-exports the runtime helpers so callers don't have to also import `@interfere/react/api`.\nexport { capture, span } from \"@interfere/react/api\";\nexport type {\n  Kernel,\n  KernelInternalOptions,\n  KernelOptions,\n} from \"@interfere/react/internal/kernel\";\nexport type {\n  ConsentCategory,\n  ConsentState,\n  GateableCategory,\n} from \"@interfere/types/sdk/plugins/manifest\";\n\nconst wrapper = createWrapperSingleton({\n  producerVersion: PRODUCER_VERSION,\n  initEntryName: \"instrumentation-client\",\n});\n\nexport const {\n  close,\n  consent,\n  getKernel,\n  getKernelOrNull,\n  identity,\n  init,\n  subscribeToKernel,\n} = wrapper;\n"],"mappings":";;;AAsBA,MAAa,EACX,OACA,SACA,WACA,iBACA,UACA,MACA,sBAZc,uBAAuB;CACrC,iBAAiB;CACjB,eAAe;CAChB,CAUG"}

package/dist/instrumentation-client.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/instrumentation-client.mjs

@@ -0,0 +1,22 @@
+import { init } from "./instrument-client.mjs";
+//#region src/instrumentation-client.ts
+/**
+* Side-effect entry for Next.js 15.3+ which auto-loads `instrumentation-client.ts`
+* on every page load. Customer's `instrumentation-client.ts` becomes:
+*
+* ```ts
+* import "@interfere/next/instrumentation-client";
+* ```
+*
+* That single import boots the kernel with sensible defaults. Customers who
+* need overrides can call `init({...})` from `@interfere/next` directly —
+* `init()` is idempotent so the side-effect call here turns into a no-op.
+*
+* The `.catch` surfaces sync boot errors in dev — production swallows them
+* (a misconfigured SDK shouldn't take the customer's app down).
+*/
+init().catch((error) => {
+	if (process.env["NODE_ENV"] !== "production") console.warn("[interfere] init() threw during boot", error);
+});
+//#endregion
+export {};

package/dist/instrumentation-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation-client.mjs","names":[],"sources":["../src/instrumentation-client.ts"],"sourcesContent":["import { init } from \"./instrument-client.js\";\n\n/**\n * Side-effect entry for Next.js 15.3+ which auto-loads `instrumentation-client.ts`\n * on every page load. Customer's `instrumentation-client.ts` becomes:\n *\n * ```ts\n * import \"@interfere/next/instrumentation-client\";\n * ```\n *\n * That single import boots the kernel with sensible defaults. Customers who\n * need overrides can call `init({...})` from `@interfere/next` directly —\n * `init()` is idempotent so the side-effect call here turns into a no-op.\n *\n * The `.catch` surfaces sync boot errors in dev — production swallows them\n * (a misconfigured SDK shouldn't take the customer's app down).\n */\ninit().catch((error: unknown) => {\n  if (process.env[\"NODE_ENV\"] !== \"production\") {\n    console.warn(\"[interfere] init() threw during boot\", error);\n  }\n});\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,MAAM,CAAC,OAAO,UAAmB;CAC/B,IAAI,QAAQ,IAAI,gBAAgB,cAC9B,QAAQ,KAAK,wCAAwC,MAAM;EAE7D"}

package/dist/instrumentation.d.mts

@@ -0,0 +1,134 @@
+import { ServerInstrumentationOptions } from "./internal/server/instrumentation-options.mjs";
+import { PrerenderSafeIdGenerator } from "./internal/server/id-generator.mjs";
+import { AttributeValue, TextMapPropagator } from "@opentelemetry/api";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+import { LogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { MetricReader } from "@opentelemetry/sdk-metrics";
+import { SpanProcessor } from "@opentelemetry/sdk-trace-base";
+
+//#region src/instrumentation.d.ts
+/**
+ * Composable building blocks the Interfere SDK contributes to OTel —
+ * span / log / metric processors, baggage propagator, undici
+ * instrumentation, plus the resource attributes and side-effect
+ * installers (console bridge + remote-config fetch).
+ *
+ * Use this when you want to plug Interfere into an existing OTel
+ * bootstrap (e.g. `@vercel/otel`'s `registerOTel({...})`, DataDog's
+ * `dd-trace-js`, or any custom `NodeTracerProvider` setup) instead of
+ * the standalone `register()` path. The kit holds no global state and
+ * touches no global slots — composition is the consumer's job.
+ *
+ * The standalone `register()` builds the kit internally and wires it
+ * into private providers, so customer DX stays a one-liner export.
+ *
+ * Returns `null` when `INTERFERE_API_KEY` is unset — callers can spread
+ * `kit?.spanProcessors ?? []` without a no-op guard.
+ */
+interface InterfereOtelKit {
+  /**
+   * Patches `console.{debug,log,info,warn,error}` to also emit OTel
+   * `LogRecord`s via the global `LoggerProvider`. Caller is responsible
+   * for ensuring a `LoggerProvider` is registered globally before
+   * calling — `register()` handles this; for composed setups, call
+   * after your bootstrap (`registerOTel({...})` etc.) has run. Returns
+   * a disposer that restores the original `console.*` methods.
+   */
+  enableConsoleBridge: () => () => void;
+  /**
+   * Fetches the SDK's remote plugin config and caches it for the
+   * runtime. Customer code's `isPluginEnabled(...)` checks read from
+   * the cache. Safe to call repeatedly.
+   */
+  fetchRemoteConfig: () => Promise<void>;
+  /**
+   * Instrumentations the SDK ships. Currently `UndiciInstrumentation`
+   * pre-configured with `propagateContextUrls` / `ignoreUrls` semantics
+   * from `ServerInstrumentationOptions`.
+   *
+   * **Composition with `@vercel/otel`**: `instrumentations: ["auto"]`
+   * registers Vercel's `globalThis.fetch` wrapper, which only
+   * auto-propagates `traceparent` to Vercel deployment URLs — outbound
+   * fetches to a different origin (e.g. `in.interfere.com`) get a
+   * span but no header injection unless
+   * `instrumentationConfig.fetch.propagateContextUrls` is set, and
+   * even then it doesn't cover the lower-level undici dispatcher path
+   * Next.js route handlers use. Spread `kit.instrumentations` after
+   * `"auto"` to layer this UndiciInstrumentation on top — propagation
+   * extends to every outbound undici call (filtered via `ignoreUrls`).
+   * Risk of double span emission on overlapping call sites is bounded:
+   * Vercel's fetch wraps `globalThis.fetch`, this hooks the undici
+   * dispatcher one layer lower, so duplicates only appear when both
+   * paths actually fire on the same call.
+   */
+  instrumentations: Instrumentation[];
+  logRecordProcessors: LogRecordProcessor[];
+  metricReaders: MetricReader[];
+  /**
+   * W3C baggage propagator. Trace context is intentionally *not*
+   * included — `@vercel/otel`'s `propagators: ["auto"]` already
+   * registers it, and standalone `register()` adds it itself when
+   * the global slot is empty. Composing this on top extends rather
+   * than overrides.
+   */
+  propagators: TextMapPropagator[];
+  /**
+   * Pre-built resource attribute set. Pass into your provider's
+   * `Resource` directly, or into `@vercel/otel`'s `attributes` field
+   * (which merges with Vercel's own auto-detected `vercel.*` attrs).
+   */
+  resourceAttributes: Record<string, AttributeValue>;
+  spanProcessors: SpanProcessor[];
+}
+/**
+ * Pure factory — no global registration, no provider construction. Returns
+ * the OTel primitives the SDK contributes so a host bootstrap (Vercel,
+ * DataDog, custom) can compose them in.
+ *
+ * Returns `null` when `INTERFERE_API_KEY` isn't set, so callers can
+ * unconditionally spread `kit?.spanProcessors ?? []` in dev where the
+ * SDK isn't configured.
+ */
+declare function buildInterfereOtelKit(opts?: ServerInstrumentationOptions): InterfereOtelKit | null;
+/**
+ * One-line server-side bootstrap for Next.js. Customers' `instrumentation.ts`
+ * becomes:
+ *
+ * ```ts
+ * export { register } from "@interfere/next/instrumentation";
+ * ```
+ *
+ * Or, with overrides:
+ *
+ * ```ts
+ * import { register as base } from "@interfere/next/instrumentation";
+ * export const register = () => base({ serviceName: "@my-org/api" });
+ * ```
+ *
+ * Customers who already run another OTel bootstrap (`@vercel/otel`,
+ * DataDog `dd-trace-js`, custom `NodeTracerProvider`) should use
+ * `buildInterfereOtelKit({...})` instead and compose the returned
+ * processors / readers / propagators into their existing setup —
+ * see the kit's JSDoc for examples.
+ *
+ * Constructs private `NodeTracerProvider` / `LoggerProvider` /
+ * `MeterProvider` and registers them on the global slots. Last writer
+ * wins on the globals, so customers running another OTel bootstrap
+ * alongside this one will end up with whichever booted last; the kit
+ * path avoids that fight entirely.
+ *
+ * Wired against the Node OTel SDK (`NodeTracerProvider`,
+ * `AsyncLocalStorageContextManager`) — so this entry only ships into the
+ * `nodejs` runtime bundle. The Edge runtime gets the no-op stub at
+ * `instrumentation.edge.ts` via `package.json`'s `edge-light` /
+ * `workerd` export conditions.
+ *
+ * Idempotent — repeat calls (e.g. HMR) short-circuit on the
+ * module-scoped `registered` flag.
+ *
+ * Bails silently when `INTERFERE_API_KEY` is unset so dev runs without
+ * the SDK configured don't crash.
+ */
+declare function register(opts?: ServerInstrumentationOptions): Promise<void>;
+//#endregion
+export { InterfereOtelKit, PrerenderSafeIdGenerator, type ServerInstrumentationOptions, buildInterfereOtelKit, register };

package/dist/instrumentation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.mts","names":[],"sources":["../src/instrumentation.ts"],"mappings":";;;;;;;;;;AAoFA;;;;;;;;;;;;;;;;;UAAiB,gBAAA;EAqCf;;;;;;;;EA5BA,mBAAA;EA4CA;;;;AAYF;EAlDE,iBAAA,QAAyB,OAAA;;;;;;;;AA0M3B;;;;;;;;;;;;;EArLE,gBAAA,EAAkB,eAAA;EAClB,mBAAA,EAAqB,kBAAA;EACrB,aAAA,EAAe,YAAA;;;;;;;;EAQf,WAAA,EAAa,iBAAA;;;;;;EAMb,kBAAA,EAAoB,MAAA,SAAe,cAAA;EACnC,cAAA,EAAgB,aAAA;AAAA;;;;;;;;;;iBAYF,qBAAA,CACd,IAAA,GAAM,4BAAA,GACL,gBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsJmB,QAAA,CACpB,IAAA,GAAM,4BAAA,GACL,OAAA"}

package/dist/instrumentation.edge.d.mts

@@ -0,0 +1,35 @@
+import { ServerInstrumentationOptions } from "./internal/server/instrumentation-options.mjs";
+import { InterfereOtelKit } from "./instrumentation.mjs";
+
+//#region src/instrumentation.edge.d.ts
+/**
+ * Edge-runtime entry for `@interfere/next/instrumentation`. Selected by
+ * `package.json`'s `edge-light` / `workerd` / `worker` export conditions
+ * — Next.js + Vercel pick this bundle when compiling
+ * `instrumentation.ts` for the Edge runtime.
+ *
+ * The Node entry (`instrumentation.ts`) is built around
+ * `NodeTracerProvider`, `AsyncLocalStorageContextManager`, undici
+ * instrumentation, and a console→OTel bridge — none of which work in
+ * the Edge runtime. Pulling that import graph into an Edge bundle would
+ * (a) trip Next's `node:*`-in-edge warnings (release-slug derivation
+ * uses `node:child_process` + `node:crypto`) and (b) crash on module
+ * load if the Edge bundle were ever actually invoked.
+ *
+ * Both `register()` and `buildInterfereOtelKit()` are exported as
+ * no-op stubs so customer TypeScript code compiles unchanged
+ * regardless of which runtime the file ends up in. Edge-runtime
+ * tracing (middleware spans, edge route handlers) needs an
+ * `@opentelemetry/sdk-trace-base`-based pipeline with a fetch-based
+ * exporter — tracked separately.
+ */
+declare function register(_opts?: ServerInstrumentationOptions): Promise<void>;
+/**
+ * Edge stub for the kit factory. Returns `null` so callers spreading
+ * `kit?.spanProcessors ?? []` into a host bootstrap behave as if the
+ * SDK is unconfigured — same shape as the Node entry returns when
+ * `INTERFERE_API_KEY` is unset.
+ */
+declare function buildInterfereOtelKit(_opts?: ServerInstrumentationOptions): null;
+//#endregion
+export { type InterfereOtelKit, type ServerInstrumentationOptions, buildInterfereOtelKit, register };

package/dist/instrumentation.edge.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.edge.d.mts","names":[],"sources":["../src/instrumentation.edge.ts"],"mappings":";;;;;AA0BA;;;;;;;;;AAYA;;;;;;;;;;;iBAZsB,QAAA,CACpB,KAAA,GAAO,4BAAA,GACN,OAAA;;;;;;;iBAUa,qBAAA,CACd,KAAA,GAAO,4BAAA"}

package/dist/instrumentation.edge.mjs

@@ -0,0 +1,34 @@
+//#region src/instrumentation.edge.ts
+/**
+* Edge-runtime entry for `@interfere/next/instrumentation`. Selected by
+* `package.json`'s `edge-light` / `workerd` / `worker` export conditions
+* — Next.js + Vercel pick this bundle when compiling
+* `instrumentation.ts` for the Edge runtime.
+*
+* The Node entry (`instrumentation.ts`) is built around
+* `NodeTracerProvider`, `AsyncLocalStorageContextManager`, undici
+* instrumentation, and a console→OTel bridge — none of which work in
+* the Edge runtime. Pulling that import graph into an Edge bundle would
+* (a) trip Next's `node:*`-in-edge warnings (release-slug derivation
+* uses `node:child_process` + `node:crypto`) and (b) crash on module
+* load if the Edge bundle were ever actually invoked.
+*
+* Both `register()` and `buildInterfereOtelKit()` are exported as
+* no-op stubs so customer TypeScript code compiles unchanged
+* regardless of which runtime the file ends up in. Edge-runtime
+* tracing (middleware spans, edge route handlers) needs an
+* `@opentelemetry/sdk-trace-base`-based pipeline with a fetch-based
+* exporter — tracked separately.
+*/
+async function register(_opts = {}) {}
+/**
+* Edge stub for the kit factory. Returns `null` so callers spreading
+* `kit?.spanProcessors ?? []` into a host bootstrap behave as if the
+* SDK is unconfigured — same shape as the Node entry returns when
+* `INTERFERE_API_KEY` is unset.
+*/
+function buildInterfereOtelKit(_opts = {}) {
+	return null;
+}
+//#endregion
+export { buildInterfereOtelKit, register };

package/dist/instrumentation.edge.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.edge.mjs","names":[],"sources":["../src/instrumentation.edge.ts"],"sourcesContent":["import type { ServerInstrumentationOptions } from \"./internal/server/instrumentation-options.js\";\n\nexport type { InterfereOtelKit } from \"./instrumentation.js\";\nexport type { ServerInstrumentationOptions } from \"./internal/server/instrumentation-options.js\";\n\n/**\n * Edge-runtime entry for `@interfere/next/instrumentation`. Selected by\n * `package.json`'s `edge-light` / `workerd` / `worker` export conditions\n * — Next.js + Vercel pick this bundle when compiling\n * `instrumentation.ts` for the Edge runtime.\n *\n * The Node entry (`instrumentation.ts`) is built around\n * `NodeTracerProvider`, `AsyncLocalStorageContextManager`, undici\n * instrumentation, and a console→OTel bridge — none of which work in\n * the Edge runtime. Pulling that import graph into an Edge bundle would\n * (a) trip Next's `node:*`-in-edge warnings (release-slug derivation\n * uses `node:child_process` + `node:crypto`) and (b) crash on module\n * load if the Edge bundle were ever actually invoked.\n *\n * Both `register()` and `buildInterfereOtelKit()` are exported as\n * no-op stubs so customer TypeScript code compiles unchanged\n * regardless of which runtime the file ends up in. Edge-runtime\n * tracing (middleware spans, edge route handlers) needs an\n * `@opentelemetry/sdk-trace-base`-based pipeline with a fetch-based\n * exporter — tracked separately.\n */\nexport async function register(\n  _opts: ServerInstrumentationOptions = {}\n): Promise<void> {\n  // Intentionally empty. See file header for the design rationale.\n}\n\n/**\n * Edge stub for the kit factory. Returns `null` so callers spreading\n * `kit?.spanProcessors ?? []` into a host bootstrap behave as if the\n * SDK is unconfigured — same shape as the Node entry returns when\n * `INTERFERE_API_KEY` is unset.\n */\nexport function buildInterfereOtelKit(\n  _opts: ServerInstrumentationOptions = {}\n): null {\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA0BA,eAAsB,SACpB,QAAsC,EAAE,EACzB;;;;;;;AAUjB,SAAgB,sBACd,QAAsC,EAAE,EAClC;CACN,OAAO"}