@autter/runtime-next 1.4.0 → 1.6.0

package/README.md

@@ -9,7 +9,8 @@ same-origin relay route, and a React error boundary.
 npm install @autter/runtime-next
 ```
 
-Set `AUTTER_RUNTIME_KEY` in your environment. Then three small files.
+Set `AUTTER_RUNTIME_KEY` in your environment. Then one line of
+`next.config` and three small files.
 
 The package has two entry points — this split is what keeps the Node
 OpenTelemetry SDK out of your browser bundle:
@@ -18,10 +19,33 @@ OpenTelemetry SDK out of your browser bundle:
   `instrumentation.ts`, route handlers, server components.
 - `@autter/runtime-next/client` — client components: browser tracker +
   error boundary. Never imports Node code.
+- `@autter/runtime-next/instrumentation` — `onRequestError` for
+  `instrumentation.ts`; safe on both the Node and edge runtimes.
+
+**`next.config`** — one copy of the Node SDK for `instrumentation.ts` and
+your routes:
+
+```js
+// next.config.mjs
+export default {
+  serverExternalPackages: ["@autter/runtime-node"],
+};
+```
+
+Next bundles server dependencies separately into `instrumentation.ts` and
+into each route. Without this line, code in routes, server components and
+server actions (`withRuntimeRequest`, `captureServerException`,
+`runtimeLogger`, `runtimeContext`, …) reaches a copy of the SDK that
+`registerAutter` never started: request summaries are printed to the
+console instead of being exported, and an error `withRuntimeRequest`
+reports is reported a second time by `onRequestError`. Next 14.2:
+`experimental: { serverComponentsExternalPackages: ["@autter/runtime-node"] }`.
 
 **1. `instrumentation.ts`** — server tracing/errors:
 
 ```ts
+import { autterOnRequestError } from "@autter/runtime-next/instrumentation";
+
 export async function register() {
   if (process.env.NEXT_RUNTIME === "nodejs") {
     const { registerAutter } = await import("@autter/runtime-next");
@@ -33,8 +57,49 @@ export async function register() {
     });
   }
 }
+
+// Next 15+: errors Next catches in server components, server actions, route
+// handlers and middleware, with their stack (otherwise: stackless 500s).
+export const onRequestError = autterOnRequestError({
+  // Edge runtime only (middleware, edge routes): no tracker runs there, so
+  // errors go straight to /v1/logs with these options.
+  edge: { apiKey: process.env.AUTTER_RUNTIME_KEY, service: "web-app" },
+});
 ```
 
+`@autter/runtime-next/instrumentation` is safe to import at the top of
+`instrumentation.ts`, which Next compiles for both runtimes: on the edge,
+bundlers resolve it (through the `edge-light`/`worker` export conditions) to a
+build with no Node imports, and the Node build loads `@autter/runtime-node`
+only inside a `process.env.NEXT_RUNTIME` branch Next removes from edge
+bundles. Without edge errors to report, `export { onRequestError } from
+"@autter/runtime-next/instrumentation"` is enough.
+
+On Node the error is recorded on the request span through the
+`registerAutter` tracker — once, even when `withRuntimeRequest` already
+reported it (Next's context is then added to that report). Recorded with
+it: `next.route_path` (the route template: `/blog/[slug]`, `/api/orders`;
+middleware is `/middleware` on Next 15 and `/proxy` on Next 16),
+`next.router_kind`, `next.route_type` (`render`, `route`, `action`,
+`middleware` on Next 15, `proxy` on Next 16), `next.render_source`
+(`react-server-components`, `react-server-components-payload`,
+`server-rendering`), `next.render_type`, `next.revalidate_reason`,
+`next.digest` (matches the `digest` your error boundary sees),
+`http.request.method` and `url.path` without its query string. Headers and
+cookies are never read. Next's control-flow signals (`redirect()`,
+`notFound()`, `forbidden()`, `unauthorized()`, dynamic bailouts) are
+skipped; `capture: true` or a predicate changes that.
+
+On the edge runtime, Next calls `onRequestError` inside the function for
+middleware and edge pages; the record goes out with the `edge` options and
+is also handed to the request's `waitUntil`, since Next does not await the
+hook for errors raised while rendering. Edge route handlers
+(`export const runtime = "edge"` in `route.ts`) are the exception: Next
+never calls the hook inside them. Self-hosted (`next start`), the Node
+server reports them instead, so the Node tracker records them with their
+own stack, `next.router_kind` `Pages Router` and `next.route_path` such as
+`/api/orders/route`.
+
 `registerAutter` passes options straight to `initAutterServer`, so the
 server SDK's defaults apply out of the box: exporters are flushed on
 process exit (`autoFlush`) and custom attributes are scrubbed for PII
@@ -81,7 +146,9 @@ Also re-exported for convenience: `captureException`, `captureMessage`,
 `@autter/runtime-next/client`) and `captureServerException`,
 `captureServerMessage`, `withProcessSpan`, `withLlmCall`, `trackLlmCall`,
 `instrumentLlmClient`, `emitLlmSelftestTrace` (from the root /
-`@autter/runtime-next/server`).
+`@autter/runtime-next/server`), plus the server error hooks for custom
+servers: `autterErrorHandler`, `autterFastifyErrors`, `autterKoa` and
+`captureRequestError`.
 
 > Importing the root entry from a client component pulls the Node OTel SDK
 > into the browser bundle and fails the build (`fs` cannot be resolved).
@@ -103,3 +170,51 @@ See the [operation logging guide](../../docs/OPERATION-LOGGING.md) for measured
 steps, explicit business outcomes, privacy and flushing. Ordinary error logs
 are diagnostics; captured exceptions and declared failed outcomes use tracing
 for issue grouping.
+
+## Requests, coded errors and edge middleware (1.5.0+)
+
+Route handlers become request summaries (always kept, request id echoed in
+`x-request-id`); the log flush is handed to Next's `after()` automatically
+(Next 15+, `unstable_after` on 14.2):
+
+```ts
+// app/api/checkout/route.ts
+import { withRuntimeRequest, runtimeContext, defineRuntimeErrors, toClientError } from "@autter/runtime-next";
+
+const billing = defineRuntimeErrors("billing", {
+  declined: { status: 402, message: "Payment declined", expected: true },
+});
+
+export const POST = withRuntimeRequest(async (request) => {
+  runtimeContext.set({ plan: "pro" });
+  const ok = await charge(await request.json());
+  if (!ok) {
+    const error = billing.declined();
+    return Response.json(toClientError(error, runtimeContext.requestId), { status: 402 });
+  }
+  return Response.json({ ok: true });
+}, { name: "checkout" });
+```
+
+Everything new in `@autter/runtime-node` 1.5.0 (`runtimeContext`,
+`RuntimeError`, `defineRuntimeErrors`, `runInBackground`, `initAutterLogging`,
+enrichers, sinks, …) is re-exported from `@autter/runtime-next` and
+`/server`. `@autter/runtime-next/client` adds `autterErrorFromResponse`.
+
+`middleware.ts` runs on the edge runtime — use `@autter/runtime-next/edge`
+(re-exports [`@autter/runtime-edge`](../runtime-edge)):
+
+```ts
+import { NextResponse } from "next/server";
+import { withAutter } from "@autter/runtime-next/edge";
+
+export default withAutter(
+  { apiKey: process.env.AUTTER_RUNTIME_KEY, service: "web-middleware" },
+  async (request, _event, _ctx, rt) => {
+    rt.set({ locale: request.headers.get("accept-language")?.slice(0, 2) });
+    return NextResponse.next();
+  },
+);
+```
+
+See [Requests, coded errors and background work](../../docs/REQUESTS-AND-ERRORS.md).

package/dist/chunk-CL2ENM4A.js

@@ -0,0 +1,85 @@
+// src/request-error.ts
+import { captureEdgeException } from "@autter/runtime-edge";
+var CONTROL_FLOW_DIGEST = /^(?:NEXT_REDIRECT|NEXT_NOT_FOUND|NEXT_HTTP_ERROR_FALLBACK|DYNAMIC_SERVER_USAGE|BAILOUT_TO_CLIENT_SIDE_RENDERING)\b/;
+function digestOf(error) {
+  try {
+    const digest = error?.digest;
+    return typeof digest === "string" ? digest : "";
+  } catch {
+    return "";
+  }
+}
+function shouldReport(error, rule) {
+  if (rule === true) return true;
+  if (rule === false) return false;
+  if (typeof rule === "function") {
+    try {
+      return rule(error) === true;
+    } catch {
+      return false;
+    }
+  }
+  return !CONTROL_FLOW_DIGEST.test(digestOf(error));
+}
+function requestErrorAttributes(error, request, context) {
+  const out = {};
+  const put = (key, read, max) => {
+    try {
+      const value = read();
+      if (typeof value === "string" && value) out[key] = value.slice(0, max);
+    } catch {
+    }
+  };
+  put("next.route_path", () => context?.routePath, 500);
+  put("next.router_kind", () => context?.routerKind, 40);
+  put("next.route_type", () => context?.routeType, 40);
+  put("next.render_source", () => context?.renderSource, 80);
+  put("next.render_type", () => context?.renderType, 40);
+  put("next.revalidate_reason", () => context?.revalidateReason, 40);
+  put("next.digest", () => digestOf(error), 100);
+  put("http.request.method", () => {
+    const method = request?.method;
+    return typeof method === "string" ? method.toUpperCase() : void 0;
+  }, 16);
+  put("url.path", () => {
+    const path = request?.path;
+    return typeof path === "string" ? path.split(/[?#]/)[0] ?? "" : void 0;
+  }, 1e3);
+  return out;
+}
+var warnedNoEdgeOptions = false;
+function nextWaitUntil() {
+  try {
+    const store = globalThis[/* @__PURE__ */ Symbol.for("@next/request-context")];
+    const context = typeof store?.get === "function" ? store.get() : void 0;
+    const waitUntil = context?.waitUntil;
+    if (typeof waitUntil !== "function") return void 0;
+    return (promise) => waitUntil.call(context, promise);
+  } catch {
+    return void 0;
+  }
+}
+async function reportOnEdge(edge, error, attributes) {
+  const options = typeof edge === "function" ? edge() : edge;
+  if (!options) {
+    if (!warnedNoEdgeOptions) {
+      warnedNoEdgeOptions = true;
+      console.warn(
+        "[autter-runtime] onRequestError ran on the edge runtime without edge options; use autterOnRequestError({ edge: { apiKey, service } }) to report edge errors"
+      );
+    }
+    return;
+  }
+  const delivery = captureEdgeException(options, error, attributes);
+  try {
+    nextWaitUntil()?.(delivery);
+  } catch {
+  }
+  await delivery;
+}
+
+export {
+  shouldReport,
+  requestErrorAttributes,
+  reportOnEdge
+};

package/dist/chunk-QFEFRAVO.js

@@ -0,0 +1,227 @@
+// src/server.ts
+import {
+  createBrowserRelayFetchHandler,
+  initAutterServer,
+  withRuntimeRequest as nodeWithRuntimeRequest
+} from "@autter/runtime-node";
+
+// package.json
+var package_default = {
+  name: "@autter/runtime-next",
+  version: "1.6.0",
+  description: "One-command Autter Runtime for Next.js: server OTel, request wide events, coded errors, browser tracker, relay route, edge middleware and React error boundary",
+  license: "MIT",
+  type: "module",
+  main: "./dist/index.cjs",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      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"
+    },
+    "./client": {
+      types: "./dist/client.d.ts",
+      import: "./dist/client.js",
+      require: "./dist/client.cjs"
+    },
+    "./edge": {
+      types: "./dist/edge.d.ts",
+      import: "./dist/edge.js",
+      require: "./dist/edge.cjs"
+    },
+    "./instrumentation": {
+      types: "./dist/instrumentation.d.ts",
+      "edge-light": {
+        import: "./dist/instrumentation-edge.js",
+        require: "./dist/instrumentation-edge.cjs"
+      },
+      worker: {
+        import: "./dist/instrumentation-edge.js",
+        require: "./dist/instrumentation-edge.cjs"
+      },
+      import: "./dist/instrumentation.js",
+      require: "./dist/instrumentation.cjs"
+    }
+  },
+  files: [
+    "dist"
+  ],
+  repository: {
+    type: "git",
+    url: "https://github.com/Autter-dev/autter-runtime.git",
+    directory: "packages/runtime-next"
+  },
+  scripts: {
+    build: `node ../../scripts/ensure-built.mjs runtime-node runtime-edge runtime-browser && node -e "require('node:fs').rmSync('dist',{recursive:true,force:true})" && tsup`,
+    test: "npm run build -w @autter/runtime-core && npm run build -w @autter/runtime-node && npm run build -w @autter/runtime-edge && npm run build -w @autter/runtime-browser && npm run build && node --test test/*.test.mjs"
+  },
+  dependencies: {
+    "@autter/runtime-browser": "^1.6.0",
+    "@autter/runtime-edge": "^1.1.0",
+    "@autter/runtime-node": "^1.6.0"
+  },
+  peerDependencies: {
+    react: ">=18"
+  },
+  devDependencies: {
+    "@types/react": "^18.3.0",
+    tsup: "^8.3.5",
+    typescript: "^5.7.0"
+  },
+  engines: {
+    node: ">=20"
+  },
+  publishConfig: {
+    access: "public",
+    provenance: true
+  },
+  homepage: "https://github.com/Autter-dev/autter-runtime#readme",
+  bugs: "https://github.com/Autter-dev/autter-runtime/issues",
+  keywords: [
+    "nextjs",
+    "error-tracking",
+    "telemetry",
+    "opentelemetry",
+    "react",
+    "error-boundary"
+  ]
+};
+
+// src/server.ts
+import {
+  createRuntimeLogger,
+  runtimeLogger,
+  withRuntimeOperation,
+  flushRuntimeLogs,
+  runtimeLogStats,
+  captureException,
+  captureMessage,
+  reportOutcome,
+  withProcessSpan,
+  withLlmCall,
+  trackLlmCall,
+  instrumentLlmClient,
+  emitLlmSelftestTrace,
+  makeSafeCapture,
+  installAutterAutoFlush,
+  redactAttributes,
+  runtimeContext,
+  runInBackground,
+  autterRequests,
+  autterFastify,
+  autterErrorResponse,
+  autterErrorHandler,
+  autterFastifyErrors,
+  autterKoa,
+  captureRequestError,
+  RuntimeError,
+  defineRuntimeErrors,
+  isRuntimeErrorLike,
+  toClientError,
+  errorAttributes,
+  CODE_PATTERN,
+  initAutterLogging,
+  enrichUserAgent,
+  enrichRequestSize,
+  enrichEdgeGeo,
+  enrichDeployment,
+  otlpSink,
+  consoleSink,
+  fileSink,
+  redactText,
+  addBreadcrumb
+} from "@autter/runtime-node";
+function registerAutter(options) {
+  return initAutterServer({
+    distro: { name: "@autter/runtime-next", version: package_default.version },
+    ...options
+  });
+}
+function createAutterRelayRoute(options) {
+  return { POST: createBrowserRelayFetchHandler(options) };
+}
+var after;
+var afterReady = (async () => {
+  try {
+    const specifier = "next/server";
+    const mod = await import(
+      /* webpackIgnore: true */
+      specifier
+    );
+    after = mod.after ?? mod.unstable_after ?? null;
+  } catch {
+    after = null;
+  }
+  return after;
+})();
+function scheduleAfter(promise) {
+  const run = (fn) => {
+    if (!fn) return;
+    try {
+      fn(promise);
+    } catch {
+    }
+  };
+  if (after !== void 0) run(after);
+  else void afterReady.then(run);
+}
+function withRuntimeRequest(handler, options = {}) {
+  return nodeWithRuntimeRequest(handler, {
+    ...options,
+    waitUntil: options.waitUntil ?? scheduleAfter
+  });
+}
+
+export {
+  registerAutter,
+  createAutterRelayRoute,
+  withRuntimeRequest,
+  createRuntimeLogger,
+  runtimeLogger,
+  withRuntimeOperation,
+  flushRuntimeLogs,
+  runtimeLogStats,
+  captureException,
+  captureMessage,
+  reportOutcome,
+  withProcessSpan,
+  withLlmCall,
+  trackLlmCall,
+  instrumentLlmClient,
+  emitLlmSelftestTrace,
+  makeSafeCapture,
+  installAutterAutoFlush,
+  redactAttributes,
+  runtimeContext,
+  runInBackground,
+  autterRequests,
+  autterFastify,
+  autterErrorResponse,
+  autterErrorHandler,
+  autterFastifyErrors,
+  autterKoa,
+  captureRequestError,
+  RuntimeError,
+  defineRuntimeErrors,
+  isRuntimeErrorLike,
+  toClientError,
+  errorAttributes,
+  CODE_PATTERN,
+  initAutterLogging,
+  enrichUserAgent,
+  enrichRequestSize,
+  enrichEdgeGeo,
+  enrichDeployment,
+  otlpSink,
+  consoleSink,
+  fileSink,
+  redactText,
+  addBreadcrumb
+};

package/dist/client.cjs

@@ -34,9 +34,13 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 var client_exports = {};
 __export(client_exports, {
   AutterErrorBoundary: () => AutterErrorBoundary,
+  addBreadcrumb: () => import_breadcrumbs.addBreadcrumb,
+  autterErrorFromResponse: () => import_runtime_browser2.autterErrorFromResponse,
   captureException: () => import_runtime_browser2.captureException,
   captureMessage: () => import_runtime_browser2.captureMessage,
   captureOutcome: () => import_runtime_browser2.captureOutcome,
+  clearBreadcrumbs: () => import_breadcrumbs.clearBreadcrumbs,
+  enableBreadcrumbs: () => import_breadcrumbs.enableBreadcrumbs,
   flush: () => import_runtime_browser2.flush,
   initAutterBrowser: () => import_runtime_browser2.initAutterBrowser,
   setContext: () => import_runtime_browser2.setContext,
@@ -45,6 +49,7 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 var import_runtime_browser2 = require("@autter/runtime-browser");
+var import_breadcrumbs = require("@autter/runtime-browser/breadcrumbs");
 
 // src/error-boundary.ts
 var React = __toESM(require("react"), 1);
@@ -76,9 +81,13 @@ var AutterErrorBoundary = class extends React.Component {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AutterErrorBoundary,
+  addBreadcrumb,
+  autterErrorFromResponse,
   captureException,
   captureMessage,
   captureOutcome,
+  clearBreadcrumbs,
+  enableBreadcrumbs,
   flush,
   initAutterBrowser,
   setContext,

package/dist/client.d.cts

@@ -0,0 +1,30 @@
+export { AutterSeverity, autterErrorFromResponse, captureException, captureMessage, captureOutcome, flush, initAutterBrowser, setContext, setUser, trackEvent } from '@autter/runtime-browser';
+export { Breadcrumb, BreadcrumbInput, BreadcrumbOptions, addBreadcrumb, clearBreadcrumbs, enableBreadcrumbs } from '@autter/runtime-browser/breadcrumbs';
+import * as React from 'react';
+
+/**
+ * React error boundary that reports render errors to Autter Runtime.
+ * React rendering errors do NOT hit `window.onerror`, so the browser
+ * tracker alone misses them — wrap your app:
+ *
+ *   <AutterErrorBoundary fallback={<ErrorPage />}>
+ *     <Application />
+ *   </AutterErrorBoundary>
+ */
+interface AutterErrorBoundaryProps {
+    fallback?: React.ReactNode;
+    /** Called after the error is reported (e.g. to show a toast). */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+    children?: React.ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+declare class AutterErrorBoundary extends React.Component<AutterErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+
+export { AutterErrorBoundary, type AutterErrorBoundaryProps };

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+export { AutterSeverity, autterErrorFromResponse, captureException, captureMessage, captureOutcome, flush, initAutterBrowser, setContext, setUser, trackEvent } from '@autter/runtime-browser';
+export { Breadcrumb, BreadcrumbInput, BreadcrumbOptions, addBreadcrumb, clearBreadcrumbs, enableBreadcrumbs } from '@autter/runtime-browser/breadcrumbs';
+import * as React from 'react';
+
+/**
+ * React error boundary that reports render errors to Autter Runtime.
+ * React rendering errors do NOT hit `window.onerror`, so the browser
+ * tracker alone misses them — wrap your app:
+ *
+ *   <AutterErrorBoundary fallback={<ErrorPage />}>
+ *     <Application />
+ *   </AutterErrorBoundary>
+ */
+interface AutterErrorBoundaryProps {
+    fallback?: React.ReactNode;
+    /** Called after the error is reported (e.g. to show a toast). */
+    onError?: (error: Error, info: React.ErrorInfo) => void;
+    children?: React.ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+declare class AutterErrorBoundary extends React.Component<AutterErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+
+export { AutterErrorBoundary, type AutterErrorBoundaryProps };

package/dist/client.js

@@ -12,8 +12,14 @@ import {
   trackEvent,
   setUser,
   setContext,
-  flush
+  flush,
+  autterErrorFromResponse
 } from "@autter/runtime-browser";
+import {
+  enableBreadcrumbs,
+  addBreadcrumb,
+  clearBreadcrumbs
+} from "@autter/runtime-browser/breadcrumbs";
 
 // src/error-boundary.ts
 import * as React from "react";
@@ -44,9 +50,13 @@ var AutterErrorBoundary = class extends React.Component {
 };
 export {
   AutterErrorBoundary,
+  addBreadcrumb,
+  autterErrorFromResponse,
   captureException2 as captureException,
   captureMessage,
   captureOutcome,
+  clearBreadcrumbs,
+  enableBreadcrumbs,
   flush,
   initAutterBrowser,
   setContext,

package/dist/edge.cjs

@@ -0,0 +1,20 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/edge.ts
+var edge_exports = {};
+module.exports = __toCommonJS(edge_exports);
+__reExport(edge_exports, require("@autter/runtime-edge"), module.exports);

package/dist/edge.d.cts

@@ -0,0 +1 @@
+export * from '@autter/runtime-edge';

package/dist/edge.d.ts

@@ -0,0 +1 @@
+export * from '@autter/runtime-edge';

package/dist/edge.js

@@ -0,0 +1,2 @@
+// src/edge.ts
+export * from "@autter/runtime-edge";