nextly 0.0.1 → 0.0.2-alpha.1

package/dist/observability/index.d.ts

@@ -0,0 +1,87 @@
+import { O as OnErrorHook } from '../_dts-chunks/on-error.d-CHIKWNxd.d.ts';
+export { g as getGlobalOnError, s as setGlobalOnError } from '../_dts-chunks/on-error.d-CHIKWNxd.d.ts';
+import '../errors/index.d.ts';
+
+/**
+ * Structured logger seam used by nextly.
+ *
+ * The default implementation writes JSON to console.{error,warn,info,debug}.
+ * Works on every serverless and edge runtime without setup. Developers swap
+ * it for Pino/Winston/Bunyan/etc. via `setNextlyLogger`.
+ *
+ * Full observability design (dev-vs-prod formatting, scrub list, audit log,
+ */
+interface NextlyLogger {
+    error(payload: object): void;
+    warn(payload: object): void;
+    info(payload: object): void;
+    debug(payload: object): void;
+}
+/**
+ * Replace the active logger. Pass `undefined` to restore the default JSON-to-console implementation.
+ *
+ * Typical use lives in `app/instrumentation.ts` via `createNextlyInstrumentation({ logger })`,
+ * but this setter is exposed for direct wiring or testing.
+ */
+declare function setNextlyLogger(logger: NextlyLogger | undefined): void;
+/** The currently registered logger. Used internally by withErrorHandler / withAction / instrumentation. */
+declare function getNextlyLogger(): NextlyLogger;
+
+type InstrumentationOptions = {
+    /** Process-wide observability hook (Sentry/Datadog/OTEL wiring). */
+    onError?: OnErrorHook;
+    /** Replace the default JSON-to-console logger. */
+    logger?: NextlyLogger;
+};
+type RequestSummary = {
+    path: string;
+    method: string;
+    headers: Headers;
+};
+type RouteContext = {
+    routerKind: string;
+    routePath: string;
+    routeType: string;
+};
+/**
+ * Helper for the developer's `app/instrumentation.ts`. Registers the logger
+ * and global onError hook, and returns an `onRequestError` to re-export
+ * from instrumentation so Next.js's framework-level error capture
+ * (Server Components, middleware, Pages Router) flows through the unified
+ * pipeline and pairs `error.digest` with our `requestId`.
+ *
+ * **Idempotency:** calling this twice in the same runtime overwrites the
+ * prior logger / onError registration. In practice `instrumentation.ts`
+ * runs once per Next.js runtime (Node and Edge get their own module graph),
+ * so this is fine — but later calls win.
+ *
+ * **Framework-kind error wrapping:** when the global onError hook fires
+ * with `kind: "framework"`, the `err` is always a NextlyError. If the
+ * original framework error wasn't already a NextlyError, it gets wrapped
+ * via `NextlyError.internal({ cause })`. Sentry-style handlers should read
+ * `err.cause ?? err` to surface the original.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * // app/instrumentation.ts
+ * import { createNextlyInstrumentation } from "nextly/observability";
+ * import * as Sentry from "@sentry/nextjs";
+ *
+ * const nextly = createNextlyInstrumentation({
+ *   onError: (err, ctx) =>
+ *     Sentry.captureException(err.cause ?? err, {
+ *       tags: { code: err.code, kind: ctx.kind },
+ *       extra: { requestId: ctx.requestId, ...err.logContext },
+ *     }),
+ * });
+ *
+ * export const onRequestError = nextly.onRequestError;
+ * ```
+ */
+declare function createNextlyInstrumentation(opts?: InstrumentationOptions): {
+    onRequestError: (error: unknown, request: RequestSummary, context: RouteContext) => Promise<void>;
+};
+
+export { OnErrorHook, createNextlyInstrumentation, getNextlyLogger, setNextlyLogger };
+export type { NextlyLogger };

package/dist/observability/index.mjs

@@ -0,0 +1,57 @@
+import {
+  getGlobalOnError,
+  setGlobalOnError
+} from "../chunk-2TFX4ND3.mjs";
+import {
+  getNextlyLogger,
+  setNextlyLogger
+} from "../chunk-W4MGXIRR.mjs";
+import {
+  NextlyError
+} from "../chunk-NRUWQ5Z7.mjs";
+import "../chunk-7P6ASYW6.mjs";
+
+// src/observability/instrumentation.ts
+function createNextlyInstrumentation(opts) {
+  if (opts?.logger) setNextlyLogger(opts.logger);
+  if (opts?.onError) setGlobalOnError(opts.onError);
+  return {
+    onRequestError: async (error, request, _context) => {
+      const requestId = request.headers.get("x-request-id") ?? request.headers.get("x-vercel-id") ?? request.headers.get("cf-ray") ?? "req_unknown";
+      const digest = error.digest;
+      getNextlyLogger().error({
+        kind: "next.requestError",
+        requestId,
+        digest,
+        path: request.path,
+        method: request.method,
+        cause: error instanceof Error ? {
+          name: error.name,
+          message: error.message,
+          stack: error.stack
+        } : { value: String(error) }
+      });
+      const onError = getGlobalOnError();
+      if (onError) {
+        const nextlyErr = NextlyError.is(error) ? error : NextlyError.internal({ cause: error });
+        try {
+          await onError(nextlyErr, { kind: "framework", requestId });
+        } catch (hookErr) {
+          getNextlyLogger().warn({
+            kind: "onError-hook-failed",
+            layer: "global",
+            requestId,
+            err: String(hookErr)
+          });
+        }
+      }
+    }
+  };
+}
+export {
+  createNextlyInstrumentation,
+  getGlobalOnError,
+  getNextlyLogger,
+  setGlobalOnError,
+  setNextlyLogger
+};

package/dist/permissions-3DZZQZMI.mjs

@@ -0,0 +1,39 @@
+import {
+  seedPermissions
+} from "./chunk-UOP63Q54.mjs";
+import "./chunk-NSEFNNU4.mjs";
+import "./chunk-3FA7FKAV.mjs";
+import "./chunk-AGJ6F2T3.mjs";
+import "./chunk-KIMNCZGV.mjs";
+import "./chunk-AK6Z23OX.mjs";
+import "./chunk-INV7QKLG.mjs";
+import "./chunk-GZ6DCQKC.mjs";
+import "./chunk-SBACDPNX.mjs";
+import "./chunk-RJLLGGPG.mjs";
+import "./chunk-V4EQTOA4.mjs";
+import "./chunk-I4JMR3UR.mjs";
+import "./chunk-XZKLBMN6.mjs";
+import "./chunk-IZWPRDC3.mjs";
+import "./chunk-DNNG377Z.mjs";
+import "./chunk-5HMZ644B.mjs";
+import "./chunk-W5KKPZT5.mjs";
+import "./chunk-56WO4WX7.mjs";
+import "./chunk-2W3DVD7S.mjs";
+import "./chunk-TS7GHTG2.mjs";
+import "./chunk-H26B4FYG.mjs";
+import "./chunk-DP3G27G5.mjs";
+import "./chunk-DV6WVX2Q.mjs";
+import "./chunk-UJ2IMJ4W.mjs";
+import "./chunk-EGXBZCGC.mjs";
+import "./chunk-G2AA4QLC.mjs";
+import "./chunk-4MJLT6PZ.mjs";
+import "./chunk-IUDOC7N7.mjs";
+import "./chunk-LAZXX4HR.mjs";
+import "./chunk-D5HQBNUB.mjs";
+import "./chunk-NRUWQ5Z7.mjs";
+import "./chunk-VTJADRO3.mjs";
+import "./chunk-5APFUGAD.mjs";
+import "./chunk-7P6ASYW6.mjs";
+export {
+  seedPermissions
+};

package/dist/pipeline-YOML7SWF.mjs

@@ -0,0 +1,29 @@
+import {
+  _resetApplyDesiredSchemaForTests,
+  applyDesiredSchema,
+  buildDesiredSchemaFromRegistry,
+  buildDesiredSchemaFromRegistryAsync
+} from "./chunk-XGI4EMS3.mjs";
+import "./chunk-VJ66NCL4.mjs";
+import "./chunk-AGJ6F2T3.mjs";
+import "./chunk-AK6Z23OX.mjs";
+import "./chunk-SBACDPNX.mjs";
+import "./chunk-V4EQTOA4.mjs";
+import "./chunk-IZWPRDC3.mjs";
+import "./chunk-DNNG377Z.mjs";
+import "./chunk-TS7GHTG2.mjs";
+import "./chunk-H26B4FYG.mjs";
+import "./chunk-DP3G27G5.mjs";
+import "./chunk-DV6WVX2Q.mjs";
+import "./chunk-UJ2IMJ4W.mjs";
+import "./chunk-LAZXX4HR.mjs";
+import "./chunk-D5HQBNUB.mjs";
+import "./chunk-NRUWQ5Z7.mjs";
+import "./chunk-5APFUGAD.mjs";
+import "./chunk-7P6ASYW6.mjs";
+export {
+  _resetApplyDesiredSchemaForTests,
+  applyDesiredSchema,
+  buildDesiredSchemaFromRegistry,
+  buildDesiredSchemaFromRegistryAsync
+};

package/dist/preview-ZZTR3QGS.mjs

@@ -0,0 +1,9 @@
+import {
+  previewDesiredSchema
+} from "./chunk-GZ6DCQKC.mjs";
+import "./chunk-SBACDPNX.mjs";
+import "./chunk-DNNG377Z.mjs";
+import "./chunk-7P6ASYW6.mjs";
+export {
+  previewDesiredSchema
+};