@worknice/instrumentation 1.0.1

package/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2024 Worknice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @worknice/instrumentation
+
+Shared instrumentation and correlation ID management for Worknice applications.
+
+## Features
+
+- 🔍 **Correlation ID Tracking**: Request tracing across async boundaries using Node.js AsyncLocalStorage
+- 📊 **Next.js Instrumentation**: Error reporting with Axiom
+- 🔄 **Cross-Service Tracing**: Track requests across services (Notebook, MYOB, Micropay, Basics)
+
+## Installation
+
+This package is part of the Worknice monorepo and is automatically available to all apps:
+
+```bash
+pnpm add @worknice/instrumentation
+```
+
+## Getting Started
+
+### App Instrumentation
+
+For Next.js apps, create an `instrumentation.ts` file in the app root:
+
+```typescript
+// apps/$app-name/instrumentation.ts
+export { register, onRequestError } from "@worknice/instrumentation";
+```
+
+- `register()` - Initialises instrumentation. Automatically called by Next.js when instrumentation is enabled.
+- `onRequestError()` - Handles and logs request errors with correlation tracking. Automatically called by Next.js on errors.
+
+### Correlation ID Usage
+
+The package provides multiple ways to work with correlation IDs:
+
+#### Getting the current correlation ID
+
+```typescript
+import { getCorrelationId } from "@worknice/instrumentation";
+
+const correlationId = getCorrelationId();
+```
+
+#### Running code with a specific correlation ID
+
+```typescript
+import { runWithCorrelationId, getCorrelationId } from "@worknice/instrumentation";
+
+await runWithCorrelationId("$correlationId", async () => {
+  // All async operations here will have access to the correlation ID
+  const id = getCorrelationId(); // Returns "$correlationId"
+});
+```
+
+#### Getting or generating a correlation ID
+
+```typescript
+import { getOrGenerateCorrelationId } from "@worknice/instrumentation";
+
+const { correlationId, isNew } = getOrGenerateCorrelationId();
+```
+
+#### Extracting from HTTP headers
+
+Extract correlation ID from HTTP headers in order:
+
+- `x-request-id`
+- `x-correlation-id`
+- `request-id`
+- `correlation-id`
+
+```typescript
+import { extractCorrelationIdFromHeaders } from "@worknice/instrumentation";
+
+const correlationId = extractCorrelationIdFromHeaders(request.headers);
+```
+
+## Configuration
+
+### Environment Variables
+
+The package supports the following environment variables:
+
+- `AXIOM_DATASET`: Axiom dataset name for error logging
+- `AXIOM_TOKEN`: Axiom API token for authentication
+- `NODE_ENV`: Environment name (development, staging, production)
+
+When Axiom credentials are not provided, the package falls back to console logging.
+
+## Architecture
+
+### AsyncLocalStorage
+
+The package uses Node.js AsyncLocalStorage to maintain correlation context across async boundaries without explicitly passing IDs through function calls.
+This allows correlation IDs to automatically flow through:
+
+- GraphQL operations
+- Database queries
+- API calls
+- Background jobs
+- Nested async operations
+
+## Development
+
+### Building
+
+```bash
+pnpm --filter=@worknice/instrumentation build
+```
+
+### Development Mode
+
+```bash
+pnpm --filter=@worknice/instrumentation dev
+```
+
+### Testing & Linting
+
+```bash
+pnpm --filter=@worknice/instrumentation test:lint
+pnpm --filter=@worknice/instrumentation test:types
+pnpm --filter=@worknice/instrumentation test:format
+```
+
+## Use Cases
+
+### Cross-Service Request Tracing
+
+When a request flows through multiple services (e.g., Notebook → MYOB → External API), the correlation ID helps trace the entire request chain:
+
+**In Notebook app:**
+
+```typescript
+import { getOrGenerateCorrelationId } from "@worknice/instrumentation";
+
+const { correlationId } = getOrGenerateCorrelationId();
+await fetch("https://myob-service/api/endpoint", {
+  headers: {
+    "x-correlation-id": correlationId,
+  },
+});
+```
+
+**In MYOB service:**
+
+```typescript
+import { extractCorrelationIdFromHeaders, runWithCorrelationId } from "@worknice/instrumentation";
+
+const correlationId = extractCorrelationIdFromHeaders(req.headers);
+runWithCorrelationId(correlationId, async () => {
+  // All operations here share the same correlation ID
+  await processRequest();
+});
+```
+
+### Background Job Tracking
+
+Track background jobs initiated from web requests:
+
+**In API route:**
+
+```typescript
+import { getCorrelationId } from "@worknice/instrumentation";
+
+const correlationId = getCorrelationId();
+await inngest.send({
+  name: "process.data",
+  data: { correlationId, ...payload },
+});
+```
+
+**In Inngest function:**
+
+```typescript
+import { runWithCorrelationId } from "@worknice/instrumentation";
+
+export const processData = inngest.createFunction(
+  { id: "process-data" },
+  { event: "process.data" },
+  async ({ event }) => {
+    return runWithCorrelationId(event.data.correlationId, async () => {
+      // Job execution with correlation tracking
+    });
+  }
+);
+```
+
+## Troubleshooting
+
+### Correlation ID Not Available
+
+If `getCorrelationId()` returns undefined:
+
+1. Ensure you're within a correlation context (use `runWithCorrelationId`)
+2. Verify the context hasn't been lost (e.g., through `setTimeout` without binding)
+
+### Axiom Logs Not Appearing
+
+1. Verify `AXIOM_DATASET` and `AXIOM_TOKEN` environment variables are set
+2. Check console output on startup for "Axiom error logging enabled" message
+3. Ensure the Axiom dataset exists and token has write permissions

package/dist/correlation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Correlation ID management with lazy-loaded Node.js modules
+ * Node.js-specific imports are loaded inside functions to support Edge compilation
+ */
+/**
+ * Correlation context stored in AsyncLocalStorage
+ * Provides request-scoped correlation ID management
+ */
+interface CorrelationContext {
+    correlationId: string;
+}
+/**
+ * Initialise the AsyncLocalStorage instance
+ * Must be called once at app startup (e.g., in instrumentation.ts)
+ * Lazy loads the node:async_hooks module to avoid Edge compilation issues
+ */
+declare const initializeCorrelationStorage: () => Promise<void>;
+/**
+ * Get the current correlation ID from async context
+ * Returns undefined if not in a correlation context or if storage not initialised
+ * Note: initializeCorrelationStorage() must be called at app startup
+ */
+declare const getCorrelationId: () => string | undefined;
+/**
+ * Get the full correlation context
+ * Returns undefined if not in a correlation context or if storage not initialised
+ * Note: initializeCorrelationStorage() must be called at app startup
+ */
+declare const getCorrelationContext: () => CorrelationContext | undefined;
+/**
+ * Generate a new correlation ID
+ * Ensures consistent ID generation across the application
+ * Edge-safe: uses crypto.randomUUID() which works in both runtimes
+ *
+ * @returns A new UUID v4 correlation ID
+ */
+declare const generateCorrelationId: () => string;
+/**
+ * Run a function with a specific correlation ID
+ * Creates a new async context with the provided correlation ID
+ * Ensures storage is initialised before running
+ */
+declare function runWithCorrelationId<T>(correlationId: string, fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Get or generate a correlation ID
+ * Checks async context first, then generates a new UUID if needed
+ * Note: This does not set the correlation ID in async context.
+ * Use runWithCorrelationId to establish context.
+ */
+declare const getOrGenerateCorrelationId: () => {
+    correlationId: string;
+    isNew: boolean;
+};
+/**
+ * Check if we're currently in a correlation context
+ */
+declare const hasCorrelationContext: () => boolean;
+/**
+ * Extract correlation ID from HTTP headers
+ * Supports both Node.js IncomingHttpHeaders and Fetch API Headers
+ * Edge-safe: only uses header parsing, no Node.js-specific APIs
+ *
+ * @param headers - Either Node.js headers object or Fetch API Headers
+ * @returns The correlation ID if found, undefined otherwise
+ */
+declare const extractCorrelationIdFromHeaders: (headers: Headers | Record<string, string | string[] | undefined>) => string | undefined;
+
+export { type CorrelationContext, extractCorrelationIdFromHeaders, generateCorrelationId, getCorrelationContext, getCorrelationId, getOrGenerateCorrelationId, hasCorrelationContext, initializeCorrelationStorage, runWithCorrelationId };

package/dist/correlation.js

@@ -0,0 +1,96 @@
+let correlationStorage;
+let initializationPromise;
+const initializeCorrelationStorage = async () => {
+  if (correlationStorage) {
+    return;
+  }
+  if (initializationPromise) {
+    await initializationPromise;
+    return;
+  }
+  initializationPromise = (async () => {
+    try {
+      const { AsyncLocalStorage } = await import("node:async_hooks");
+      correlationStorage = new AsyncLocalStorage();
+      return correlationStorage;
+    } catch (error) {
+      console.warn("Failed to initialize AsyncLocalStorage (expected in Edge runtime):", error);
+      return void 0;
+    }
+  })();
+  await initializationPromise;
+};
+const getCorrelationId = () => {
+  if (!correlationStorage) {
+    return void 0;
+  }
+  return correlationStorage.getStore()?.correlationId;
+};
+const getCorrelationContext = () => {
+  if (!correlationStorage) {
+    return void 0;
+  }
+  return correlationStorage.getStore();
+};
+const generateCorrelationId = () => {
+  return crypto.randomUUID();
+};
+async function runWithCorrelationId(correlationId, fn) {
+  const context = {
+    correlationId
+  };
+  await initializeCorrelationStorage();
+  if (!correlationStorage) {
+    console.warn("AsyncLocalStorage not available, executing without context");
+    return fn();
+  }
+  return correlationStorage.run(context, fn);
+}
+const getOrGenerateCorrelationId = () => {
+  const existing = getCorrelationId();
+  if (existing) {
+    return { correlationId: existing, isNew: false };
+  }
+  return { correlationId: crypto.randomUUID(), isNew: true };
+};
+const hasCorrelationContext = () => {
+  return getCorrelationContext() !== void 0;
+};
+const CORRELATION_HEADERS = [
+  "x-request-id",
+  "x-correlation-id",
+  "request-id",
+  "correlation-id"
+];
+const extractCorrelationIdFromHeaders = (headers) => {
+  if (headers instanceof Headers) {
+    for (const headerName of CORRELATION_HEADERS) {
+      const value = headers.get(headerName);
+      if (value) return value;
+    }
+    return void 0;
+  }
+  for (const headerName of CORRELATION_HEADERS) {
+    const value = headers[headerName] || headers[headerName.toLowerCase()];
+    if (value) {
+      return Array.isArray(value) ? value[0] : value;
+    }
+    const upperHeaderName = headerName.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("-");
+    const upperValue = headers[upperHeaderName];
+    if (upperValue) {
+      return Array.isArray(upperValue) ? upperValue[0] : upperValue;
+    }
+  }
+  return void 0;
+};
+export {
+  extractCorrelationIdFromHeaders,
+  generateCorrelationId,
+  getCorrelationContext,
+  getCorrelationId,
+  getOrGenerateCorrelationId,
+  hasCorrelationContext,
+  initializeCorrelationStorage,
+  runWithCorrelationId
+};
+//# sourceMappingURL=correlation.js.map

package/dist/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/correlation.ts"],"sourcesContent":["/**\n * Correlation ID management with lazy-loaded Node.js modules\n * Node.js-specific imports are loaded inside functions to support Edge compilation\n */\n\n/**\n * Correlation context stored in AsyncLocalStorage\n * Provides request-scoped correlation ID management\n */\nexport interface CorrelationContext {\n  correlationId: string;\n}\n\n/**\n * Minimal type definition for AsyncLocalStorage methods used\n * Avoids module-level imports while maintaining type safety\n */\ninterface AsyncLocalStorageType {\n  getStore(): CorrelationContext | undefined;\n  run<T>(store: CorrelationContext, fn: () => T | Promise<T>): T | Promise<T>;\n}\n\n/**\n * Lazy-loaded AsyncLocalStorage instance\n * Only initialised when first accessed in Node.js runtime\n */\nlet correlationStorage: AsyncLocalStorageType | undefined;\n\n/**\n * Promise to ensure single initialisation of AsyncLocalStorage\n */\nlet initializationPromise: Promise<AsyncLocalStorageType | undefined> | undefined;\n\n/**\n * Initialise the AsyncLocalStorage instance\n * Must be called once at app startup (e.g., in instrumentation.ts)\n * Lazy loads the node:async_hooks module to avoid Edge compilation issues\n */\nexport const initializeCorrelationStorage = async (): Promise<void> => {\n  if (correlationStorage) {\n    return;\n  }\n\n  if (initializationPromise) {\n    await initializationPromise;\n    return;\n  }\n\n  initializationPromise = (async () => {\n    try {\n      const { AsyncLocalStorage } = await import(\"node:async_hooks\");\n      correlationStorage = new AsyncLocalStorage<CorrelationContext>();\n      return correlationStorage;\n    } catch (error) {\n      console.warn(\"Failed to initialize AsyncLocalStorage (expected in Edge runtime):\", error);\n      return undefined;\n    }\n  })();\n\n  await initializationPromise;\n};\n\n/**\n * Get the current correlation ID from async context\n * Returns undefined if not in a correlation context or if storage not initialised\n * Note: initializeCorrelationStorage() must be called at app startup\n */\nexport const getCorrelationId = (): string | undefined => {\n  if (!correlationStorage) {\n    return undefined;\n  }\n  return correlationStorage.getStore()?.correlationId;\n};\n\n/**\n * Get the full correlation context\n * Returns undefined if not in a correlation context or if storage not initialised\n * Note: initializeCorrelationStorage() must be called at app startup\n */\nexport const getCorrelationContext = (): CorrelationContext | undefined => {\n  if (!correlationStorage) {\n    return undefined;\n  }\n  return correlationStorage.getStore();\n};\n\n/**\n * Generate a new correlation ID\n * Ensures consistent ID generation across the application\n * Edge-safe: uses crypto.randomUUID() which works in both runtimes\n *\n * @returns A new UUID v4 correlation ID\n */\nexport const generateCorrelationId = (): string => {\n  return crypto.randomUUID();\n};\n\n/**\n * Run a function with a specific correlation ID\n * Creates a new async context with the provided correlation ID\n * Ensures storage is initialised before running\n */\nexport async function runWithCorrelationId<T>(\n  correlationId: string,\n  fn: () => T | Promise<T>,\n): Promise<T> {\n  const context: CorrelationContext = {\n    correlationId,\n  };\n\n  await initializeCorrelationStorage();\n\n  if (!correlationStorage) {\n    console.warn(\"AsyncLocalStorage not available, executing without context\");\n    return fn();\n  }\n\n  return correlationStorage.run(context, fn);\n}\n\n/**\n * Get or generate a correlation ID\n * Checks async context first, then generates a new UUID if needed\n * Note: This does not set the correlation ID in async context.\n * Use runWithCorrelationId to establish context.\n */\nexport const getOrGenerateCorrelationId = (): {\n  correlationId: string;\n  isNew: boolean;\n} => {\n  const existing = getCorrelationId();\n  if (existing) {\n    return { correlationId: existing, isNew: false };\n  }\n\n  return { correlationId: crypto.randomUUID(), isNew: true };\n};\n\n/**\n * Check if we're currently in a correlation context\n */\nexport const hasCorrelationContext = (): boolean => {\n  return getCorrelationContext() !== undefined;\n};\n\n/**\n * Standard header names for correlation IDs (in order of preference)\n * Note: Fetch API Headers.get() is case-insensitive, but Node.js headers are case-sensitive\n */\nconst CORRELATION_HEADERS = [\n  \"x-request-id\",\n  \"x-correlation-id\",\n  \"request-id\",\n  \"correlation-id\",\n] as const;\n\n/**\n * Extract correlation ID from HTTP headers\n * Supports both Node.js IncomingHttpHeaders and Fetch API Headers\n * Edge-safe: only uses header parsing, no Node.js-specific APIs\n *\n * @param headers - Either Node.js headers object or Fetch API Headers\n * @returns The correlation ID if found, undefined otherwise\n */\nexport const extractCorrelationIdFromHeaders = (\n  headers: Headers | Record<string, string | string[] | undefined>,\n): string | undefined => {\n  if (headers instanceof Headers) {\n    for (const headerName of CORRELATION_HEADERS) {\n      const value = headers.get(headerName);\n      if (value) return value;\n    }\n    return undefined;\n  }\n\n  for (const headerName of CORRELATION_HEADERS) {\n    const value = headers[headerName] || headers[headerName.toLowerCase()];\n    if (value) {\n      // Handle array values (Node.js can return arrays for headers)\n      return Array.isArray(value) ? value[0] : value;\n    }\n\n    const upperHeaderName = headerName\n      .split(\"-\")\n      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))\n      .join(\"-\");\n\n    const upperValue = headers[upperHeaderName];\n    if (upperValue) {\n      return Array.isArray(upperValue) ? upperValue[0] : upperValue;\n    }\n  }\n\n  return undefined;\n};\n"],"mappings":"AA0BA,IAAI;AAKJ,IAAI;AAOG,MAAM,+BAA+B,YAA2B;AACrE,MAAI,oBAAoB;AACtB;AAAA,EACF;AAEA,MAAI,uBAAuB;AACzB,UAAM;AACN;AAAA,EACF;AAEA,2BAAyB,YAAY;AACnC,QAAI;AACF,YAAM,EAAE,kBAAkB,IAAI,MAAM,OAAO,kBAAkB;AAC7D,2BAAqB,IAAI,kBAAsC;AAC/D,aAAO;AAAA,IACT,SAAS,OAAO;AACd,cAAQ,KAAK,sEAAsE,KAAK;AACxF,aAAO;AAAA,IACT;AAAA,EACF,GAAG;AAEH,QAAM;AACR;AAOO,MAAM,mBAAmB,MAA0B;AACxD,MAAI,CAAC,oBAAoB;AACvB,WAAO;AAAA,EACT;AACA,SAAO,mBAAmB,SAAS,GAAG;AACxC;AAOO,MAAM,wBAAwB,MAAsC;AACzE,MAAI,CAAC,oBAAoB;AACvB,WAAO;AAAA,EACT;AACA,SAAO,mBAAmB,SAAS;AACrC;AASO,MAAM,wBAAwB,MAAc;AACjD,SAAO,OAAO,WAAW;AAC3B;AAOA,eAAsB,qBACpB,eACA,IACY;AACZ,QAAM,UAA8B;AAAA,IAClC;AAAA,EACF;AAEA,QAAM,6BAA6B;AAEnC,MAAI,CAAC,oBAAoB;AACvB,YAAQ,KAAK,4DAA4D;AACzE,WAAO,GAAG;AAAA,EACZ;AAEA,SAAO,mBAAmB,IAAI,SAAS,EAAE;AAC3C;AAQO,MAAM,6BAA6B,MAGrC;AACH,QAAM,WAAW,iBAAiB;AAClC,MAAI,UAAU;AACZ,WAAO,EAAE,eAAe,UAAU,OAAO,MAAM;AAAA,EACjD;AAEA,SAAO,EAAE,eAAe,OAAO,WAAW,GAAG,OAAO,KAAK;AAC3D;AAKO,MAAM,wBAAwB,MAAe;AAClD,SAAO,sBAAsB,MAAM;AACrC;AAMA,MAAM,sBAAsB;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAUO,MAAM,kCAAkC,CAC7C,YACuB;AACvB,MAAI,mBAAmB,SAAS;AAC9B,eAAW,cAAc,qBAAqB;AAC5C,YAAM,QAAQ,QAAQ,IAAI,UAAU;AACpC,UAAI,MAAO,QAAO;AAAA,IACpB;AACA,WAAO;AAAA,EACT;AAEA,aAAW,cAAc,qBAAqB;AAC5C,UAAM,QAAQ,QAAQ,UAAU,KAAK,QAAQ,WAAW,YAAY,CAAC;AACrE,QAAI,OAAO;AAET,aAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,CAAC,IAAI;AAAA,IAC3C;AAEA,UAAM,kBAAkB,WACrB,MAAM,GAAG,EACT,IAAI,CAAC,SAAS,KAAK,OAAO,CAAC,EAAE,YAAY,IAAI,KAAK,MAAM,CAAC,CAAC,EAC1D,KAAK,GAAG;AAEX,UAAM,aAAa,QAAQ,eAAe;AAC1C,QAAI,YAAY;AACd,aAAO,MAAM,QAAQ,UAAU,IAAI,WAAW,CAAC,IAAI;AAAA,IACrD;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { extractCorrelationIdFromHeaders, generateCorrelationId, getCorrelationContext, getCorrelationId, getOrGenerateCorrelationId, hasCorrelationContext, runWithCorrelationId } from './correlation.js';
+export { onRequestError, register } from './instrumentation.js';
+export { default as withCorrelationId } from './serverAction.js';
+import 'next';

package/dist/index.js

@@ -0,0 +1,24 @@
+import {
+  extractCorrelationIdFromHeaders,
+  generateCorrelationId,
+  getCorrelationContext,
+  getCorrelationId,
+  getOrGenerateCorrelationId,
+  hasCorrelationContext,
+  runWithCorrelationId
+} from "./correlation.js";
+import { onRequestError, register } from "./instrumentation.js";
+import { withCorrelationId } from "./serverAction.js";
+export {
+  extractCorrelationIdFromHeaders,
+  generateCorrelationId,
+  getCorrelationContext,
+  getCorrelationId,
+  getOrGenerateCorrelationId,
+  hasCorrelationContext,
+  onRequestError,
+  register,
+  runWithCorrelationId,
+  withCorrelationId
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @worknice/instrumentation\n *\n * Shared instrumentation and correlation ID management for Worknice applications\n */\n\nexport {\n  extractCorrelationIdFromHeaders,\n  generateCorrelationId,\n  getCorrelationContext,\n  getCorrelationId,\n  getOrGenerateCorrelationId,\n  hasCorrelationContext,\n  runWithCorrelationId,\n} from \"./correlation.js\";\nexport { onRequestError, register } from \"./instrumentation.js\";\nexport { withCorrelationId } from \"./serverAction.js\";\n"],"mappings":"AAMA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,gBAAgB,gBAAgB;AACzC,SAAS,yBAAyB;","names":[]}

package/dist/instrumentation-node.d.ts

@@ -0,0 +1,12 @@
+import { Instrumentation } from 'next';
+
+/**
+ * Node.js-specific instrumentation
+ * This file is only loaded when running in Node.js runtime
+ * It has full access to Node.js APIs
+ */
+
+declare function register(): Promise<void>;
+declare const onRequestError: Instrumentation.onRequestError;
+
+export { onRequestError, register };

package/dist/instrumentation-node.js

@@ -0,0 +1,77 @@
+import { WinstonTransport as AxiomTransport } from "@axiomhq/winston";
+import winston from "winston";
+import {
+  extractCorrelationIdFromHeaders,
+  getCorrelationId,
+  initializeCorrelationStorage
+} from "./correlation.js";
+const dynamicMetaFormat = winston.format((info) => {
+  const correlationId = getCorrelationId();
+  return correlationId ? { ...info, correlationId } : info;
+});
+const createErrorLogger = () => {
+  const axiomDataset = process.env.AXIOM_DATASET;
+  const axiomToken = process.env.AXIOM_TOKEN;
+  return winston.createLogger({
+    level: "error",
+    format: winston.format.combine(dynamicMetaFormat(), winston.format.json()),
+    defaultMeta: {
+      source: "instrumentation",
+      environment: process.env.NODE_ENV || "development",
+      runtime: "nodejs"
+    },
+    transports: [
+      axiomDataset && axiomToken ? new AxiomTransport({
+        dataset: axiomDataset,
+        token: axiomToken
+      }) : new winston.transports.Console()
+    ]
+  });
+};
+const errorLogger = createErrorLogger();
+async function register() {
+  await initializeCorrelationStorage();
+  console.log("\n\n========================================");
+  console.log("[Instrumentation] Correlation tracking initialised (Node.js runtime)");
+  if (process.env.AXIOM_DATASET && process.env.AXIOM_TOKEN) {
+    console.log("[Instrumentation] Axiom error logging enabled");
+  } else {
+    console.log("[Instrumentation] Axiom not configured - using console for errors");
+  }
+  console.log("========================================\n\n");
+}
+const onRequestError = (error, request, context) => {
+  const typedError = error;
+  let correlationId = getCorrelationId();
+  if (!correlationId) {
+    correlationId = extractCorrelationIdFromHeaders(request.headers);
+  }
+  const errorData = {
+    correlationId,
+    digest: typedError.digest,
+    error: {
+      message: typedError.message,
+      stack: typedError.stack,
+      name: typedError.name
+    },
+    request: {
+      path: request.path,
+      method: request.method,
+      headers: request.headers
+    },
+    context: {
+      routerKind: context.routerKind,
+      routePath: context.routePath,
+      routeType: context.routeType,
+      renderSource: context.renderSource,
+      revalidateReason: context.revalidateReason
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  errorLogger.error("[Request Error]", errorData);
+};
+export {
+  onRequestError,
+  register
+};
+//# sourceMappingURL=instrumentation-node.js.map

package/dist/instrumentation-node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/instrumentation-node.ts"],"sourcesContent":["/**\n * Node.js-specific instrumentation\n * This file is only loaded when running in Node.js runtime\n * It has full access to Node.js APIs\n */\n\nimport { WinstonTransport as AxiomTransport } from \"@axiomhq/winston\";\nimport type { Instrumentation } from \"next\";\nimport winston from \"winston\";\n\nimport {\n  extractCorrelationIdFromHeaders,\n  getCorrelationId,\n  initializeCorrelationStorage,\n} from \"./correlation.js\";\n\nconst dynamicMetaFormat = winston.format((info) => {\n  const correlationId = getCorrelationId();\n  return correlationId ? { ...info, correlationId } : info;\n});\n\n/**\n * Create Axiom logger for error reporting\n * Falls back to console if Axiom credentials are not configured\n */\nconst createErrorLogger = () => {\n  const axiomDataset = process.env.AXIOM_DATASET;\n  const axiomToken = process.env.AXIOM_TOKEN;\n\n  return winston.createLogger({\n    level: \"error\",\n    format: winston.format.combine(dynamicMetaFormat(), winston.format.json()),\n    defaultMeta: {\n      source: \"instrumentation\",\n      environment: process.env.NODE_ENV || \"development\",\n      runtime: \"nodejs\",\n    },\n    transports: [\n      axiomDataset && axiomToken\n        ? new AxiomTransport({\n            dataset: axiomDataset,\n            token: axiomToken,\n          })\n        : new winston.transports.Console(),\n    ],\n  });\n};\n\nconst errorLogger = createErrorLogger();\n\nexport async function register() {\n  await initializeCorrelationStorage();\n\n  console.log(\"\\n\\n========================================\");\n  console.log(\"[Instrumentation] Correlation tracking initialised (Node.js runtime)\");\n  if (process.env.AXIOM_DATASET && process.env.AXIOM_TOKEN) {\n    console.log(\"[Instrumentation] Axiom error logging enabled\");\n  } else {\n    console.log(\"[Instrumentation] Axiom not configured - using console for errors\");\n  }\n  console.log(\"========================================\\n\\n\");\n}\n\nexport const onRequestError: Instrumentation.onRequestError = (error, request, context) => {\n  const typedError = error as Error & { digest?: string };\n\n  let correlationId = getCorrelationId();\n  if (!correlationId) {\n    correlationId = extractCorrelationIdFromHeaders(request.headers);\n  }\n\n  const errorData = {\n    correlationId,\n    digest: typedError.digest,\n    error: {\n      message: typedError.message,\n      stack: typedError.stack,\n      name: typedError.name,\n    },\n    request: {\n      path: request.path,\n      method: request.method,\n      headers: request.headers,\n    },\n    context: {\n      routerKind: context.routerKind,\n      routePath: context.routePath,\n      routeType: context.routeType,\n      renderSource: context.renderSource,\n      revalidateReason: context.revalidateReason,\n    },\n    timestamp: new Date().toISOString(),\n  };\n\n  errorLogger.error(\"[Request Error]\", errorData);\n};\n"],"mappings":"AAMA,SAAS,oBAAoB,sBAAsB;AAEnD,OAAO,aAAa;AAEpB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,oBAAoB,QAAQ,OAAO,CAAC,SAAS;AACjD,QAAM,gBAAgB,iBAAiB;AACvC,SAAO,gBAAgB,EAAE,GAAG,MAAM,cAAc,IAAI;AACtD,CAAC;AAMD,MAAM,oBAAoB,MAAM;AAC9B,QAAM,eAAe,QAAQ,IAAI;AACjC,QAAM,aAAa,QAAQ,IAAI;AAE/B,SAAO,QAAQ,aAAa;AAAA,IAC1B,OAAO;AAAA,IACP,QAAQ,QAAQ,OAAO,QAAQ,kBAAkB,GAAG,QAAQ,OAAO,KAAK,CAAC;AAAA,IACzE,aAAa;AAAA,MACX,QAAQ;AAAA,MACR,aAAa,QAAQ,IAAI,YAAY;AAAA,MACrC,SAAS;AAAA,IACX;AAAA,IACA,YAAY;AAAA,MACV,gBAAgB,aACZ,IAAI,eAAe;AAAA,QACjB,SAAS;AAAA,QACT,OAAO;AAAA,MACT,CAAC,IACD,IAAI,QAAQ,WAAW,QAAQ;AAAA,IACrC;AAAA,EACF,CAAC;AACH;AAEA,MAAM,cAAc,kBAAkB;AAEtC,eAAsB,WAAW;AAC/B,QAAM,6BAA6B;AAEnC,UAAQ,IAAI,8CAA8C;AAC1D,UAAQ,IAAI,sEAAsE;AAClF,MAAI,QAAQ,IAAI,iBAAiB,QAAQ,IAAI,aAAa;AACxD,YAAQ,IAAI,+CAA+C;AAAA,EAC7D,OAAO;AACL,YAAQ,IAAI,mEAAmE;AAAA,EACjF;AACA,UAAQ,IAAI,8CAA8C;AAC5D;AAEO,MAAM,iBAAiD,CAAC,OAAO,SAAS,YAAY;AACzF,QAAM,aAAa;AAEnB,MAAI,gBAAgB,iBAAiB;AACrC,MAAI,CAAC,eAAe;AAClB,oBAAgB,gCAAgC,QAAQ,OAAO;AAAA,EACjE;AAEA,QAAM,YAAY;AAAA,IAChB;AAAA,IACA,QAAQ,WAAW;AAAA,IACnB,OAAO;AAAA,MACL,SAAS,WAAW;AAAA,MACpB,OAAO,WAAW;AAAA,MAClB,MAAM,WAAW;AAAA,IACnB;AAAA,IACA,SAAS;AAAA,MACP,MAAM,QAAQ;AAAA,MACd,QAAQ,QAAQ;AAAA,MAChB,SAAS,QAAQ;AAAA,IACnB;AAAA,IACA,SAAS;AAAA,MACP,YAAY,QAAQ;AAAA,MACpB,WAAW,QAAQ;AAAA,MACnB,WAAW,QAAQ;AAAA,MACnB,cAAc,QAAQ;AAAA,MACtB,kBAAkB,QAAQ;AAAA,IAC5B;AAAA,IACA,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,EACpC;AAEA,cAAY,MAAM,mBAAmB,SAAS;AAChD;","names":[]}

package/dist/instrumentation.d.ts

@@ -0,0 +1,40 @@
+import { Instrumentation } from 'next';
+
+/**
+ * Next.js Instrumentation Entry Point
+ *
+ * This file serves as an Edge-safe entry point for instrumentation across all Next.js apps
+ * in the monorepo. It uses dynamic imports to prevent Node.js-specific modules from breaking
+ * Edge runtime compilation, even though our apps use Node.js runtime exclusively.
+ *
+ * Architecture:
+ * - instrumentation.ts (this file): Edge-safe entry point with dynamic imports
+ * - instrumentation-node.ts: Node.js implementation with Winston/Axiom logging
+ *
+ * The separation is necessary because Next.js compiles instrumentation for both runtimes
+ * regardless of the runtime configuration, and Winston/Axiom imports would cause Edge
+ * compilation errors if placed directly in this file.
+ *
+ * See https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation for more details.
+ */
+
+/**
+ * Initialize instrumentation for the application
+ *
+ * Dynamically loads the Node.js implementation which:
+ * - Initializes AsyncLocalStorage for correlation tracking
+ * - Sets up Winston logging with Axiom transport
+ * - Configures error reporting with correlation context
+ */
+declare function register(): Promise<void>;
+/**
+ * Handle request errors with correlation context
+ *
+ * Dynamically loads the Node.js error handler which:
+ * - Extracts or generates correlation ID
+ * - Logs errors to Axiom with full context
+ * - Maintains correlation ID for Winston logging
+ */
+declare const onRequestError: Instrumentation.onRequestError;
+
+export { onRequestError, register };

package/dist/instrumentation.js

@@ -0,0 +1,13 @@
+async function register() {
+  const { register: registerNode } = await import("./instrumentation-node.js");
+  return registerNode();
+}
+const onRequestError = async (error, request, context) => {
+  const { onRequestError: nodeHandler } = await import("./instrumentation-node.js");
+  return nodeHandler(error, request, context);
+};
+export {
+  onRequestError,
+  register
+};
+//# sourceMappingURL=instrumentation.js.map

package/dist/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/instrumentation.ts"],"sourcesContent":["/**\n * Next.js Instrumentation Entry Point\n *\n * This file serves as an Edge-safe entry point for instrumentation across all Next.js apps\n * in the monorepo. It uses dynamic imports to prevent Node.js-specific modules from breaking\n * Edge runtime compilation, even though our apps use Node.js runtime exclusively.\n *\n * Architecture:\n * - instrumentation.ts (this file): Edge-safe entry point with dynamic imports\n * - instrumentation-node.ts: Node.js implementation with Winston/Axiom logging\n *\n * The separation is necessary because Next.js compiles instrumentation for both runtimes\n * regardless of the runtime configuration, and Winston/Axiom imports would cause Edge\n * compilation errors if placed directly in this file.\n *\n * See https://nextjs.org/docs/app/api-reference/file-conventions/instrumentation for more details.\n */\n\nimport type { Instrumentation } from \"next\";\n\n/**\n * Initialize instrumentation for the application\n *\n * Dynamically loads the Node.js implementation which:\n * - Initializes AsyncLocalStorage for correlation tracking\n * - Sets up Winston logging with Axiom transport\n * - Configures error reporting with correlation context\n */\nexport async function register() {\n  const { register: registerNode } = await import(\"./instrumentation-node.js\");\n  return registerNode();\n}\n\n/**\n * Handle request errors with correlation context\n *\n * Dynamically loads the Node.js error handler which:\n * - Extracts or generates correlation ID\n * - Logs errors to Axiom with full context\n * - Maintains correlation ID for Winston logging\n */\nexport const onRequestError: Instrumentation.onRequestError = async (error, request, context) => {\n  const { onRequestError: nodeHandler } = await import(\"./instrumentation-node.js\");\n  return nodeHandler(error, request, context);\n};\n"],"mappings":"AA4BA,eAAsB,WAAW;AAC/B,QAAM,EAAE,UAAU,aAAa,IAAI,MAAM,OAAO,2BAA2B;AAC3E,SAAO,aAAa;AACtB;AAUO,MAAM,iBAAiD,OAAO,OAAO,SAAS,YAAY;AAC/F,QAAM,EAAE,gBAAgB,YAAY,IAAI,MAAM,OAAO,2BAA2B;AAChF,SAAO,YAAY,OAAO,SAAS,OAAO;AAC5C;","names":[]}

package/dist/serverAction.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Higher-order function for Next.js server actions with automatic correlation ID handling.
+ *
+ * This wrapper automatically establishes correlation context for server actions,
+ * eliminating the need for boilerplate correlation ID code in each action.
+ *
+ * @example
+ * ```typescript
+ * // Using withCorrelationId
+ * const myAction = async (data: Data) => {
+ *   // ... action logic (correlation context automatically available via getCorrelationId())
+ * };
+ * export default withCorrelationId(myAction);
+ * ```
+ */
+/**
+ * Wraps a server action function with automatic correlation ID context.
+ *
+ * The returned function:
+ * 1. Gets or generates a correlation ID
+ * 2. Establishes correlation context using runWithCorrelationId
+ * 3. Executes the original handler within that context
+ * 4. Returns the handler's result
+ *
+ * @param handler - The server action function to wrap
+ * @returns A wrapped version with automatic correlation context
+ */
+declare function withCorrelationId<T extends any[], R>(handler: (...args: T) => Promise<R>): (...args: T) => Promise<R>;
+
+export { withCorrelationId as default, withCorrelationId };

package/dist/serverAction.js

@@ -0,0 +1,13 @@
+import { getOrGenerateCorrelationId, runWithCorrelationId } from "./correlation.js";
+function withCorrelationId(handler) {
+  return async (...args) => {
+    const { correlationId } = getOrGenerateCorrelationId();
+    return runWithCorrelationId(correlationId, () => handler(...args));
+  };
+}
+var serverAction_default = withCorrelationId;
+export {
+  serverAction_default as default,
+  withCorrelationId
+};
+//# sourceMappingURL=serverAction.js.map

package/dist/serverAction.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/serverAction.ts"],"sourcesContent":["/**\n * Higher-order function for Next.js server actions with automatic correlation ID handling.\n *\n * This wrapper automatically establishes correlation context for server actions,\n * eliminating the need for boilerplate correlation ID code in each action.\n *\n * @example\n * ```typescript\n * // Using withCorrelationId\n * const myAction = async (data: Data) => {\n *   // ... action logic (correlation context automatically available via getCorrelationId())\n * };\n * export default withCorrelationId(myAction);\n * ```\n */\n\nimport { getOrGenerateCorrelationId, runWithCorrelationId } from \"./correlation.js\";\n\n/**\n * Wraps a server action function with automatic correlation ID context.\n *\n * The returned function:\n * 1. Gets or generates a correlation ID\n * 2. Establishes correlation context using runWithCorrelationId\n * 3. Executes the original handler within that context\n * 4. Returns the handler's result\n *\n * @param handler - The server action function to wrap\n * @returns A wrapped version with automatic correlation context\n */\nexport function withCorrelationId<T extends any[], R>(\n  handler: (...args: T) => Promise<R>,\n): (...args: T) => Promise<R> {\n  return async (...args: T): Promise<R> => {\n    const { correlationId } = getOrGenerateCorrelationId();\n    return runWithCorrelationId(correlationId, () => handler(...args));\n  };\n}\n\nexport default withCorrelationId;\n"],"mappings":"AAgBA,SAAS,4BAA4B,4BAA4B;AAc1D,SAAS,kBACd,SAC4B;AAC5B,SAAO,UAAU,SAAwB;AACvC,UAAM,EAAE,cAAc,IAAI,2BAA2B;AACrD,WAAO,qBAAqB,eAAe,MAAM,QAAQ,GAAG,IAAI,CAAC;AAAA,EACnE;AACF;AAEA,IAAO,uBAAQ;","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@worknice/instrumentation",
+  "version": "1.0.1",
+  "license": "MIT",
+  "private": false,
+  "description": "Shared instrumentation management for Worknice applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./*": {
+      "import": "./dist/*.js",
+      "types": "./dist/*.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@axiomhq/winston": "^1.2.0",
+    "next": "~15.5.0",
+    "winston": "^3.15.0"
+  },
+  "devDependencies": {
+    "@anolilab/semantic-release-pnpm": "^1.1.10",
+    "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^20.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.7.0",
+    "@typescript-eslint/parser": "^8.7.0",
+    "eslint": "^8.56.0",
+    "prettier": "^3.1.1",
+    "semantic-release": "^24.2.2",
+    "semantic-release-scope-filter": "^1.0.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "rm -rf ./dist && tsup",
+    "dev": "rm -rf ./dist && tsup --watch",
+    "fix": "exit 0",
+    "fix:lint": "eslint \"src/**/*.{js,ts,tsx}\" --fix",
+    "fix:format": "prettier '**/*.{js,ts,tsx,css}' --write",
+    "test": "exit 0",
+    "test:unit": "vitest run",
+    "test:format": "prettier '**/*.{js,ts,tsx,css}' --check",
+    "test:lint": "eslint \"src/**/*.{js,ts,tsx}\"",
+    "test:types": "tsc --noEmit --pretty"
+  }
+}