@usebetterdev/audit-next 0.6.0 → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 usebetter
+
+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/dist/index.cjs

@@ -37,27 +37,11 @@ var import_headers = require("next/headers");
 var import_server = require("next/server");
 var import_audit_core2 = require("@usebetterdev/audit-core");
 var AUDIT_ACTOR_HEADER = "x-better-audit-actor-id";
-var defaultExtractor = {
-  actor: (0, import_audit_core.fromBearerToken)("sub")
-};
-async function tryExtract(extractor, request, onError) {
-  if (!extractor) {
-    return void 0;
-  }
-  try {
-    return await extractor(request);
-  } catch (error) {
-    if (onError) {
-      onError(error);
-    }
-    return void 0;
-  }
-}
 function createAuditMiddleware(options = {}) {
-  const extractor = options.extractor ?? defaultExtractor;
+  const extractor = options.extractor ?? import_audit_core.defaultExtractor;
   const actorHeader = options.actorHeader ?? AUDIT_ACTOR_HEADER;
   return async (request) => {
-    const actorId = await tryExtract(
+    const actorId = await (0, import_audit_core.safeExtract)(
       extractor.actor,
       request,
       options.onError
@@ -73,9 +57,9 @@ function betterAuditNext(options = {}) {
   return createAuditMiddleware(options);
 }
 function withAuditRoute(handler, options = {}) {
-  const extractor = options.extractor ?? defaultExtractor;
+  const extractor = options.extractor ?? import_audit_core.defaultExtractor;
   return async (request, context) => {
-    const actorId = await tryExtract(
+    const actorId = await (0, import_audit_core.safeExtract)(
       extractor.actor,
       request,
       options.onError
@@ -88,7 +72,7 @@ function withAuditRoute(handler, options = {}) {
   };
 }
 function withAudit(action, options = {}) {
-  const extractor = options.extractor ?? defaultExtractor;
+  const extractor = options.extractor ?? import_audit_core.defaultExtractor;
   return async (...args) => {
     let actorId;
     try {
@@ -96,7 +80,7 @@ function withAudit(action, options = {}) {
       const syntheticRequest = new Request("http://localhost", {
         headers: headersList
       });
-      actorId = await tryExtract(
+      actorId = await (0, import_audit_core.safeExtract)(
         extractor.actor,
         syntheticRequest,
         options.onError

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  fromBearerToken,\n  getAuditContext,\n  runWithAuditContext,\n} from \"@usebetterdev/audit-core\";\nimport type {\n  AuditContext,\n  ContextExtractor,\n  ValueExtractor,\n} from \"@usebetterdev/audit-core\";\nimport { headers } from \"next/headers\";\nimport { NextResponse } from \"next/server\";\nimport type { NextRequest } from \"next/server\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type RouteContext = Record<string, unknown> | undefined;\n\nexport type NextMiddleware = (request: NextRequest) => Promise<NextResponse>;\n\n/**\n * Shared options across all audit wrappers.\n */\nexport interface BaseAuditOptions {\n  /** Context extractor for pulling actor identity from the request. */\n  extractor?: ContextExtractor;\n  /** Called when an extractor throws. Defaults to silent fail-open. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface CreateAuditMiddlewareOptions extends BaseAuditOptions {\n  /**\n   * Request header name used to forward the extracted actor id to downstream\n   * route handlers. Defaults to `AUDIT_ACTOR_HEADER`.\n   */\n  actorHeader?: string;\n}\n\nexport type WithAuditRouteOptions = BaseAuditOptions;\n\nexport type WithAuditOptions = BaseAuditOptions;\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Default header name used to forward the actor id from middleware to route\n * handlers.\n *\n * Use this constant to keep the middleware and route handler in sync:\n * ```ts\n * // middleware.ts\n * export default createAuditMiddleware(); // sets AUDIT_ACTOR_HEADER\n *\n * // app/api/orders/route.ts\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport const AUDIT_ACTOR_HEADER = \"x-better-audit-actor-id\";\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */\nconst defaultExtractor: ContextExtractor = {\n  actor: fromBearerToken(\"sub\"),\n};\n\n/**\n * Runs a value extractor safely, returning undefined on error (fail open).\n */\nasync function tryExtract(\n  extractor: ValueExtractor | undefined,\n  request: Request,\n  onError: ((error: unknown) => void) | undefined,\n): Promise<string | undefined> {\n  if (!extractor) {\n    return undefined;\n  }\n  try {\n    return await extractor(request);\n  } catch (error: unknown) {\n    if (onError) {\n      onError(error);\n    }\n    return undefined;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// createAuditMiddleware / betterAuditNext\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a Next.js edge middleware function that extracts audit context from\n * the incoming request and forwards the actor id as a request header to\n * downstream route handlers.\n *\n * **Important:** Next.js middleware runs in a separate Edge Runtime execution\n * context from route handlers — AsyncLocalStorage set here does NOT propagate.\n * This middleware forwards the extracted actor id via a request header\n * (`x-better-audit-actor-id` by default). Use `withAuditRoute` in your route\n * handlers to read that header and populate ALS.\n *\n * The middleware **always** overwrites the actor header on the forwarded\n * request — when extraction fails, it is set to an empty string. This prevents\n * clients from spoofing the actor id by sending the header directly.\n *\n * The middleware is non-blocking: if context extraction fails, the request\n * proceeds with an empty actor header (fail open).\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { createAuditMiddleware } from \"@usebetterdev/audit-next\";\n * export default createAuditMiddleware();\n * export const config = { matcher: \"/api/:path*\" };\n *\n * // app/api/orders/route.ts\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function createAuditMiddleware(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const actorHeader = options.actorHeader ?? AUDIT_ACTOR_HEADER;\n\n  return async (request) => {\n    const actorId = await tryExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    // Always forward with an explicit header value so clients cannot spoof\n    // the actor id by sending the header directly. When extraction fails the\n    // header is set to \"\" — fromHeader() treats empty values as undefined.\n    const requestHeaders = new Headers(request.headers);\n    requestHeaders.set(actorHeader, actorId ?? \"\");\n\n    return NextResponse.next({\n      request: { headers: requestHeaders },\n    });\n  };\n}\n\n/**\n * Convenience alias for `createAuditMiddleware`. Use as the default export\n * in `middleware.ts`.\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { betterAuditNext } from \"@usebetterdev/audit-next\";\n * export default betterAuditNext();\n * ```\n */\nexport function betterAuditNext(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  return createAuditMiddleware(options);\n}\n\n// ---------------------------------------------------------------------------\n// withAuditRoute\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js App Router route handler with audit context propagation.\n *\n * Extracts the actor identity from the incoming request (by default reads\n * `sub` from `Authorization: Bearer <jwt>`, or reads the\n * `x-better-audit-actor-id` header forwarded by `createAuditMiddleware`) and\n * runs the handler inside an AsyncLocalStorage scope so that `getAuditContext()`\n * returns the correct context within the handler.\n *\n * `NextRequest` is a Web `Request` subclass — extractors from audit-core\n * (`fromBearerToken`, `fromHeader`, `fromCookie`) work directly.\n *\n * The wrapper is non-blocking: if extraction fails, the handler runs without\n * audit context (fail open).\n *\n * @example\n * ```ts\n * // app/api/orders/route.ts — standalone (no middleware)\n * import { withAuditRoute } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler);\n *\n * // app/api/orders/route.ts — paired with createAuditMiddleware\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function withAuditRoute<C extends RouteContext = RouteContext>(\n  handler: (request: NextRequest, context: C) => Promise<Response>,\n  options: WithAuditRouteOptions = {},\n): (request: NextRequest, context: C) => Promise<Response> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (request, context) => {\n    const actorId = await tryExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    if (actorId === undefined) {\n      return handler(request, context);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => handler(request, context));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withAudit (server actions)\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js server action with audit context propagation.\n *\n * Server actions do not receive a `Request` object. This wrapper reads all\n * request headers via `next/headers` and constructs a synthetic `Request` to\n * run the configured extractor against, then wraps the action in an\n * AsyncLocalStorage scope so that `getAuditContext()` returns the correct\n * context within the action.\n *\n * The wrapper is non-blocking: if extraction fails (including when `headers()`\n * is unavailable), the action runs without audit context (fail open).\n *\n * @example\n * ```ts\n * // app/actions.ts\n * \"use server\";\n * import { withAudit } from \"@usebetterdev/audit-next\";\n *\n * export const createOrder = withAudit(async (formData: FormData) => {\n *   // getAuditContext() returns the actor here\n * });\n * ```\n */\nexport function withAudit<TArgs extends unknown[], TResult>(\n  action: (...args: TArgs) => Promise<TResult>,\n  options: WithAuditOptions = {},\n): (...args: TArgs) => Promise<TResult> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (...args) => {\n    let actorId: string | undefined;\n\n    try {\n      const headersList = await headers();\n      const syntheticRequest = new Request(\"http://localhost\", {\n        headers: headersList,\n      });\n      actorId = await tryExtract(\n        extractor.actor,\n        syntheticRequest,\n        options.onError,\n      );\n    } catch (error: unknown) {\n      // headers() throws outside Next.js request context — fail open\n      options.onError?.(error);\n    }\n\n    if (actorId === undefined) {\n      return action(...args);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => action(...args));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Re-exports\n// ---------------------------------------------------------------------------\n\nexport type { AuditContext, ContextExtractor, ValueExtractor };\nexport { fromBearerToken, fromCookie, fromHeader, getAuditContext, runWithAuditContext } from \"@usebetterdev/audit-core\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,wBAIO;AAMP,qBAAwB;AACxB,oBAA6B;AA2R7B,IAAAA,qBAA8F;AAvOvF,IAAM,qBAAqB;AAOlC,IAAM,mBAAqC;AAAA,EACzC,WAAO,mCAAgB,KAAK;AAC9B;AAKA,eAAe,WACb,WACA,SACA,SAC6B;AAC7B,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,EACT;AACA,MAAI;AACF,WAAO,MAAM,UAAU,OAAO;AAAA,EAChC,SAAS,OAAgB;AACvB,QAAI,SAAS;AACX,cAAQ,KAAK;AAAA,IACf;AACA,WAAO;AAAA,EACT;AACF;AAsCO,SAAS,sBACd,UAAwC,CAAC,GACzB;AAChB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,cAAc,QAAQ,eAAe;AAE3C,SAAO,OAAO,YAAY;AACxB,UAAM,UAAU,MAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAKA,UAAM,iBAAiB,IAAI,QAAQ,QAAQ,OAAO;AAClD,mBAAe,IAAI,aAAa,WAAW,EAAE;AAE7C,WAAO,2BAAa,KAAK;AAAA,MACvB,SAAS,EAAE,SAAS,eAAe;AAAA,IACrC,CAAC;AAAA,EACH;AACF;AAaO,SAAS,gBACd,UAAwC,CAAC,GACzB;AAChB,SAAO,sBAAsB,OAAO;AACtC;AAkCO,SAAS,eACd,SACA,UAAiC,CAAC,GACuB;AACzD,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,OAAO,SAAS,YAAY;AACjC,UAAM,UAAU,MAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,QAAQ,SAAS,OAAO;AAAA,IACjC;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,eAAO,uCAAoB,cAAc,MAAM,QAAQ,SAAS,OAAO,CAAC;AAAA,EAC1E;AACF;AA6BO,SAAS,UACd,QACA,UAA4B,CAAC,GACS;AACtC,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,UAAU,SAAS;AACxB,QAAI;AAEJ,QAAI;AACF,YAAM,cAAc,UAAM,wBAAQ;AAClC,YAAM,mBAAmB,IAAI,QAAQ,oBAAoB;AAAA,QACvD,SAAS;AAAA,MACX,CAAC;AACD,gBAAU,MAAM;AAAA,QACd,UAAU;AAAA,QACV;AAAA,QACA,QAAQ;AAAA,MACV;AAAA,IACF,SAAS,OAAgB;AAEvB,cAAQ,UAAU,KAAK;AAAA,IACzB;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,OAAO,GAAG,IAAI;AAAA,IACvB;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,eAAO,uCAAoB,cAAc,MAAM,OAAO,GAAG,IAAI,CAAC;AAAA,EAChE;AACF;","names":["import_audit_core"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  defaultExtractor,\n  fromBearerToken,\n  getAuditContext,\n  runWithAuditContext,\n  safeExtract,\n} from \"@usebetterdev/audit-core\";\nimport type {\n  AuditContext,\n  ContextExtractor,\n  ValueExtractor,\n} from \"@usebetterdev/audit-core\";\nimport { headers } from \"next/headers\";\nimport { NextResponse } from \"next/server\";\nimport type { NextRequest } from \"next/server\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type RouteContext = Record<string, unknown> | undefined;\n\nexport type NextMiddleware = (request: NextRequest) => Promise<NextResponse>;\n\n/**\n * Shared options across all audit wrappers.\n */\nexport interface BaseAuditOptions {\n  /** Context extractor for pulling actor identity from the request. */\n  extractor?: ContextExtractor;\n  /** Called when an extractor throws. Defaults to silent fail-open. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface CreateAuditMiddlewareOptions extends BaseAuditOptions {\n  /**\n   * Request header name used to forward the extracted actor id to downstream\n   * route handlers. Defaults to `AUDIT_ACTOR_HEADER`.\n   */\n  actorHeader?: string;\n}\n\nexport type WithAuditRouteOptions = BaseAuditOptions;\n\nexport type WithAuditOptions = BaseAuditOptions;\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Default header name used to forward the actor id from middleware to route\n * handlers.\n *\n * Use this constant to keep the middleware and route handler in sync:\n * ```ts\n * // middleware.ts\n * export default createAuditMiddleware(); // sets AUDIT_ACTOR_HEADER\n *\n * // app/api/orders/route.ts\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport const AUDIT_ACTOR_HEADER = \"x-better-audit-actor-id\";\n\n// ---------------------------------------------------------------------------\n// createAuditMiddleware / betterAuditNext\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a Next.js edge middleware function that extracts audit context from\n * the incoming request and forwards the actor id as a request header to\n * downstream route handlers.\n *\n * **Important:** Next.js middleware runs in a separate Edge Runtime execution\n * context from route handlers — AsyncLocalStorage set here does NOT propagate.\n * This middleware forwards the extracted actor id via a request header\n * (`x-better-audit-actor-id` by default). Use `withAuditRoute` in your route\n * handlers to read that header and populate ALS.\n *\n * The middleware **always** overwrites the actor header on the forwarded\n * request — when extraction fails, it is set to an empty string. This prevents\n * clients from spoofing the actor id by sending the header directly.\n *\n * The middleware is non-blocking: if context extraction fails, the request\n * proceeds with an empty actor header (fail open).\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { createAuditMiddleware } from \"@usebetterdev/audit-next\";\n * export default createAuditMiddleware();\n * export const config = { matcher: \"/api/:path*\" };\n *\n * // app/api/orders/route.ts\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function createAuditMiddleware(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const actorHeader = options.actorHeader ?? AUDIT_ACTOR_HEADER;\n\n  return async (request) => {\n    const actorId = await safeExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    // Always forward with an explicit header value so clients cannot spoof\n    // the actor id by sending the header directly. When extraction fails the\n    // header is set to \"\" — fromHeader() treats empty values as undefined.\n    const requestHeaders = new Headers(request.headers);\n    requestHeaders.set(actorHeader, actorId ?? \"\");\n\n    return NextResponse.next({\n      request: { headers: requestHeaders },\n    });\n  };\n}\n\n/**\n * Convenience alias for `createAuditMiddleware`. Use as the default export\n * in `middleware.ts`.\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { betterAuditNext } from \"@usebetterdev/audit-next\";\n * export default betterAuditNext();\n * ```\n */\nexport function betterAuditNext(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  return createAuditMiddleware(options);\n}\n\n// ---------------------------------------------------------------------------\n// withAuditRoute\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js App Router route handler with audit context propagation.\n *\n * Extracts the actor identity from the incoming request (by default reads\n * `sub` from `Authorization: Bearer <jwt>`, or reads the\n * `x-better-audit-actor-id` header forwarded by `createAuditMiddleware`) and\n * runs the handler inside an AsyncLocalStorage scope so that `getAuditContext()`\n * returns the correct context within the handler.\n *\n * `NextRequest` is a Web `Request` subclass — extractors from audit-core\n * (`fromBearerToken`, `fromHeader`, `fromCookie`) work directly.\n *\n * The wrapper is non-blocking: if extraction fails, the handler runs without\n * audit context (fail open).\n *\n * @example\n * ```ts\n * // app/api/orders/route.ts — standalone (no middleware)\n * import { withAuditRoute } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler);\n *\n * // app/api/orders/route.ts — paired with createAuditMiddleware\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function withAuditRoute<C extends RouteContext = RouteContext>(\n  handler: (request: NextRequest, context: C) => Promise<Response>,\n  options: WithAuditRouteOptions = {},\n): (request: NextRequest, context: C) => Promise<Response> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (request, context) => {\n    const actorId = await safeExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    if (actorId === undefined) {\n      return handler(request, context);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => handler(request, context));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withAudit (server actions)\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js server action with audit context propagation.\n *\n * Server actions do not receive a `Request` object. This wrapper reads all\n * request headers via `next/headers` and constructs a synthetic `Request` to\n * run the configured extractor against, then wraps the action in an\n * AsyncLocalStorage scope so that `getAuditContext()` returns the correct\n * context within the action.\n *\n * The wrapper is non-blocking: if extraction fails (including when `headers()`\n * is unavailable), the action runs without audit context (fail open).\n *\n * @example\n * ```ts\n * // app/actions.ts\n * \"use server\";\n * import { withAudit } from \"@usebetterdev/audit-next\";\n *\n * export const createOrder = withAudit(async (formData: FormData) => {\n *   // getAuditContext() returns the actor here\n * });\n * ```\n */\nexport function withAudit<TArgs extends unknown[], TResult>(\n  action: (...args: TArgs) => Promise<TResult>,\n  options: WithAuditOptions = {},\n): (...args: TArgs) => Promise<TResult> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (...args) => {\n    let actorId: string | undefined;\n\n    try {\n      const headersList = await headers();\n      const syntheticRequest = new Request(\"http://localhost\", {\n        headers: headersList,\n      });\n      actorId = await safeExtract(\n        extractor.actor,\n        syntheticRequest,\n        options.onError,\n      );\n    } catch (error: unknown) {\n      // headers() throws outside Next.js request context — fail open\n      options.onError?.(error);\n    }\n\n    if (actorId === undefined) {\n      return action(...args);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => action(...args));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Re-exports\n// ---------------------------------------------------------------------------\n\nexport type { AuditContext, ContextExtractor, ValueExtractor };\nexport { fromBearerToken, fromCookie, fromHeader, getAuditContext, runWithAuditContext } from \"@usebetterdev/audit-core\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,wBAMO;AAMP,qBAAwB;AACxB,oBAA6B;AA6P7B,IAAAA,qBAA8F;AAzMvF,IAAM,qBAAqB;AAsC3B,SAAS,sBACd,UAAwC,CAAC,GACzB;AAChB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,cAAc,QAAQ,eAAe;AAE3C,SAAO,OAAO,YAAY;AACxB,UAAM,UAAU,UAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAKA,UAAM,iBAAiB,IAAI,QAAQ,QAAQ,OAAO;AAClD,mBAAe,IAAI,aAAa,WAAW,EAAE;AAE7C,WAAO,2BAAa,KAAK;AAAA,MACvB,SAAS,EAAE,SAAS,eAAe;AAAA,IACrC,CAAC;AAAA,EACH;AACF;AAaO,SAAS,gBACd,UAAwC,CAAC,GACzB;AAChB,SAAO,sBAAsB,OAAO;AACtC;AAkCO,SAAS,eACd,SACA,UAAiC,CAAC,GACuB;AACzD,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,OAAO,SAAS,YAAY;AACjC,UAAM,UAAU,UAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,QAAQ,SAAS,OAAO;AAAA,IACjC;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,eAAO,uCAAoB,cAAc,MAAM,QAAQ,SAAS,OAAO,CAAC;AAAA,EAC1E;AACF;AA6BO,SAAS,UACd,QACA,UAA4B,CAAC,GACS;AACtC,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,UAAU,SAAS;AACxB,QAAI;AAEJ,QAAI;AACF,YAAM,cAAc,UAAM,wBAAQ;AAClC,YAAM,mBAAmB,IAAI,QAAQ,oBAAoB;AAAA,QACvD,SAAS;AAAA,MACX,CAAC;AACD,gBAAU,UAAM;AAAA,QACd,UAAU;AAAA,QACV;AAAA,QACA,QAAQ;AAAA,MACV;AAAA,IACF,SAAS,OAAgB;AAEvB,cAAQ,UAAU,KAAK;AAAA,IACzB;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,OAAO,GAAG,IAAI;AAAA,IACvB;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,eAAO,uCAAoB,cAAc,MAAM,OAAO,GAAG,IAAI,CAAC;AAAA,EAChE;AACF;","names":["import_audit_core"]}

package/dist/index.js

@@ -1,33 +1,18 @@
 // src/index.ts
 import {
-  fromBearerToken,
-  runWithAuditContext
+  defaultExtractor,
+  runWithAuditContext,
+  safeExtract
 } from "@usebetterdev/audit-core";
 import { headers } from "next/headers";
 import { NextResponse } from "next/server";
 import { fromBearerToken as fromBearerToken2, fromCookie, fromHeader, getAuditContext as getAuditContext2, runWithAuditContext as runWithAuditContext2 } from "@usebetterdev/audit-core";
 var AUDIT_ACTOR_HEADER = "x-better-audit-actor-id";
-var defaultExtractor = {
-  actor: fromBearerToken("sub")
-};
-async function tryExtract(extractor, request, onError) {
-  if (!extractor) {
-    return void 0;
-  }
-  try {
-    return await extractor(request);
-  } catch (error) {
-    if (onError) {
-      onError(error);
-    }
-    return void 0;
-  }
-}
 function createAuditMiddleware(options = {}) {
   const extractor = options.extractor ?? defaultExtractor;
   const actorHeader = options.actorHeader ?? AUDIT_ACTOR_HEADER;
   return async (request) => {
-    const actorId = await tryExtract(
+    const actorId = await safeExtract(
       extractor.actor,
       request,
       options.onError
@@ -45,7 +30,7 @@ function betterAuditNext(options = {}) {
 function withAuditRoute(handler, options = {}) {
   const extractor = options.extractor ?? defaultExtractor;
   return async (request, context) => {
-    const actorId = await tryExtract(
+    const actorId = await safeExtract(
       extractor.actor,
       request,
       options.onError
@@ -66,7 +51,7 @@ function withAudit(action, options = {}) {
       const syntheticRequest = new Request("http://localhost", {
         headers: headersList
       });
-      actorId = await tryExtract(
+      actorId = await safeExtract(
         extractor.actor,
         syntheticRequest,
         options.onError

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  fromBearerToken,\n  getAuditContext,\n  runWithAuditContext,\n} from \"@usebetterdev/audit-core\";\nimport type {\n  AuditContext,\n  ContextExtractor,\n  ValueExtractor,\n} from \"@usebetterdev/audit-core\";\nimport { headers } from \"next/headers\";\nimport { NextResponse } from \"next/server\";\nimport type { NextRequest } from \"next/server\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type RouteContext = Record<string, unknown> | undefined;\n\nexport type NextMiddleware = (request: NextRequest) => Promise<NextResponse>;\n\n/**\n * Shared options across all audit wrappers.\n */\nexport interface BaseAuditOptions {\n  /** Context extractor for pulling actor identity from the request. */\n  extractor?: ContextExtractor;\n  /** Called when an extractor throws. Defaults to silent fail-open. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface CreateAuditMiddlewareOptions extends BaseAuditOptions {\n  /**\n   * Request header name used to forward the extracted actor id to downstream\n   * route handlers. Defaults to `AUDIT_ACTOR_HEADER`.\n   */\n  actorHeader?: string;\n}\n\nexport type WithAuditRouteOptions = BaseAuditOptions;\n\nexport type WithAuditOptions = BaseAuditOptions;\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Default header name used to forward the actor id from middleware to route\n * handlers.\n *\n * Use this constant to keep the middleware and route handler in sync:\n * ```ts\n * // middleware.ts\n * export default createAuditMiddleware(); // sets AUDIT_ACTOR_HEADER\n *\n * // app/api/orders/route.ts\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport const AUDIT_ACTOR_HEADER = \"x-better-audit-actor-id\";\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */\nconst defaultExtractor: ContextExtractor = {\n  actor: fromBearerToken(\"sub\"),\n};\n\n/**\n * Runs a value extractor safely, returning undefined on error (fail open).\n */\nasync function tryExtract(\n  extractor: ValueExtractor | undefined,\n  request: Request,\n  onError: ((error: unknown) => void) | undefined,\n): Promise<string | undefined> {\n  if (!extractor) {\n    return undefined;\n  }\n  try {\n    return await extractor(request);\n  } catch (error: unknown) {\n    if (onError) {\n      onError(error);\n    }\n    return undefined;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// createAuditMiddleware / betterAuditNext\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a Next.js edge middleware function that extracts audit context from\n * the incoming request and forwards the actor id as a request header to\n * downstream route handlers.\n *\n * **Important:** Next.js middleware runs in a separate Edge Runtime execution\n * context from route handlers — AsyncLocalStorage set here does NOT propagate.\n * This middleware forwards the extracted actor id via a request header\n * (`x-better-audit-actor-id` by default). Use `withAuditRoute` in your route\n * handlers to read that header and populate ALS.\n *\n * The middleware **always** overwrites the actor header on the forwarded\n * request — when extraction fails, it is set to an empty string. This prevents\n * clients from spoofing the actor id by sending the header directly.\n *\n * The middleware is non-blocking: if context extraction fails, the request\n * proceeds with an empty actor header (fail open).\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { createAuditMiddleware } from \"@usebetterdev/audit-next\";\n * export default createAuditMiddleware();\n * export const config = { matcher: \"/api/:path*\" };\n *\n * // app/api/orders/route.ts\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function createAuditMiddleware(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const actorHeader = options.actorHeader ?? AUDIT_ACTOR_HEADER;\n\n  return async (request) => {\n    const actorId = await tryExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    // Always forward with an explicit header value so clients cannot spoof\n    // the actor id by sending the header directly. When extraction fails the\n    // header is set to \"\" — fromHeader() treats empty values as undefined.\n    const requestHeaders = new Headers(request.headers);\n    requestHeaders.set(actorHeader, actorId ?? \"\");\n\n    return NextResponse.next({\n      request: { headers: requestHeaders },\n    });\n  };\n}\n\n/**\n * Convenience alias for `createAuditMiddleware`. Use as the default export\n * in `middleware.ts`.\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { betterAuditNext } from \"@usebetterdev/audit-next\";\n * export default betterAuditNext();\n * ```\n */\nexport function betterAuditNext(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  return createAuditMiddleware(options);\n}\n\n// ---------------------------------------------------------------------------\n// withAuditRoute\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js App Router route handler with audit context propagation.\n *\n * Extracts the actor identity from the incoming request (by default reads\n * `sub` from `Authorization: Bearer <jwt>`, or reads the\n * `x-better-audit-actor-id` header forwarded by `createAuditMiddleware`) and\n * runs the handler inside an AsyncLocalStorage scope so that `getAuditContext()`\n * returns the correct context within the handler.\n *\n * `NextRequest` is a Web `Request` subclass — extractors from audit-core\n * (`fromBearerToken`, `fromHeader`, `fromCookie`) work directly.\n *\n * The wrapper is non-blocking: if extraction fails, the handler runs without\n * audit context (fail open).\n *\n * @example\n * ```ts\n * // app/api/orders/route.ts — standalone (no middleware)\n * import { withAuditRoute } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler);\n *\n * // app/api/orders/route.ts — paired with createAuditMiddleware\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function withAuditRoute<C extends RouteContext = RouteContext>(\n  handler: (request: NextRequest, context: C) => Promise<Response>,\n  options: WithAuditRouteOptions = {},\n): (request: NextRequest, context: C) => Promise<Response> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (request, context) => {\n    const actorId = await tryExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    if (actorId === undefined) {\n      return handler(request, context);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => handler(request, context));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withAudit (server actions)\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js server action with audit context propagation.\n *\n * Server actions do not receive a `Request` object. This wrapper reads all\n * request headers via `next/headers` and constructs a synthetic `Request` to\n * run the configured extractor against, then wraps the action in an\n * AsyncLocalStorage scope so that `getAuditContext()` returns the correct\n * context within the action.\n *\n * The wrapper is non-blocking: if extraction fails (including when `headers()`\n * is unavailable), the action runs without audit context (fail open).\n *\n * @example\n * ```ts\n * // app/actions.ts\n * \"use server\";\n * import { withAudit } from \"@usebetterdev/audit-next\";\n *\n * export const createOrder = withAudit(async (formData: FormData) => {\n *   // getAuditContext() returns the actor here\n * });\n * ```\n */\nexport function withAudit<TArgs extends unknown[], TResult>(\n  action: (...args: TArgs) => Promise<TResult>,\n  options: WithAuditOptions = {},\n): (...args: TArgs) => Promise<TResult> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (...args) => {\n    let actorId: string | undefined;\n\n    try {\n      const headersList = await headers();\n      const syntheticRequest = new Request(\"http://localhost\", {\n        headers: headersList,\n      });\n      actorId = await tryExtract(\n        extractor.actor,\n        syntheticRequest,\n        options.onError,\n      );\n    } catch (error: unknown) {\n      // headers() throws outside Next.js request context — fail open\n      options.onError?.(error);\n    }\n\n    if (actorId === undefined) {\n      return action(...args);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => action(...args));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Re-exports\n// ---------------------------------------------------------------------------\n\nexport type { AuditContext, ContextExtractor, ValueExtractor };\nexport { fromBearerToken, fromCookie, fromHeader, getAuditContext, runWithAuditContext } from \"@usebetterdev/audit-core\";\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EAEA;AAAA,OACK;AAMP,SAAS,eAAe;AACxB,SAAS,oBAAoB;AA2R7B,SAAS,mBAAAA,kBAAiB,YAAY,YAAY,mBAAAC,kBAAiB,uBAAAC,4BAA2B;AAvOvF,IAAM,qBAAqB;AAOlC,IAAM,mBAAqC;AAAA,EACzC,OAAO,gBAAgB,KAAK;AAC9B;AAKA,eAAe,WACb,WACA,SACA,SAC6B;AAC7B,MAAI,CAAC,WAAW;AACd,WAAO;AAAA,EACT;AACA,MAAI;AACF,WAAO,MAAM,UAAU,OAAO;AAAA,EAChC,SAAS,OAAgB;AACvB,QAAI,SAAS;AACX,cAAQ,KAAK;AAAA,IACf;AACA,WAAO;AAAA,EACT;AACF;AAsCO,SAAS,sBACd,UAAwC,CAAC,GACzB;AAChB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,cAAc,QAAQ,eAAe;AAE3C,SAAO,OAAO,YAAY;AACxB,UAAM,UAAU,MAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAKA,UAAM,iBAAiB,IAAI,QAAQ,QAAQ,OAAO;AAClD,mBAAe,IAAI,aAAa,WAAW,EAAE;AAE7C,WAAO,aAAa,KAAK;AAAA,MACvB,SAAS,EAAE,SAAS,eAAe;AAAA,IACrC,CAAC;AAAA,EACH;AACF;AAaO,SAAS,gBACd,UAAwC,CAAC,GACzB;AAChB,SAAO,sBAAsB,OAAO;AACtC;AAkCO,SAAS,eACd,SACA,UAAiC,CAAC,GACuB;AACzD,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,OAAO,SAAS,YAAY;AACjC,UAAM,UAAU,MAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,QAAQ,SAAS,OAAO;AAAA,IACjC;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,WAAO,oBAAoB,cAAc,MAAM,QAAQ,SAAS,OAAO,CAAC;AAAA,EAC1E;AACF;AA6BO,SAAS,UACd,QACA,UAA4B,CAAC,GACS;AACtC,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,UAAU,SAAS;AACxB,QAAI;AAEJ,QAAI;AACF,YAAM,cAAc,MAAM,QAAQ;AAClC,YAAM,mBAAmB,IAAI,QAAQ,oBAAoB;AAAA,QACvD,SAAS;AAAA,MACX,CAAC;AACD,gBAAU,MAAM;AAAA,QACd,UAAU;AAAA,QACV;AAAA,QACA,QAAQ;AAAA,MACV;AAAA,IACF,SAAS,OAAgB;AAEvB,cAAQ,UAAU,KAAK;AAAA,IACzB;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,OAAO,GAAG,IAAI;AAAA,IACvB;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,WAAO,oBAAoB,cAAc,MAAM,OAAO,GAAG,IAAI,CAAC;AAAA,EAChE;AACF;","names":["fromBearerToken","getAuditContext","runWithAuditContext"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  defaultExtractor,\n  fromBearerToken,\n  getAuditContext,\n  runWithAuditContext,\n  safeExtract,\n} from \"@usebetterdev/audit-core\";\nimport type {\n  AuditContext,\n  ContextExtractor,\n  ValueExtractor,\n} from \"@usebetterdev/audit-core\";\nimport { headers } from \"next/headers\";\nimport { NextResponse } from \"next/server\";\nimport type { NextRequest } from \"next/server\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type RouteContext = Record<string, unknown> | undefined;\n\nexport type NextMiddleware = (request: NextRequest) => Promise<NextResponse>;\n\n/**\n * Shared options across all audit wrappers.\n */\nexport interface BaseAuditOptions {\n  /** Context extractor for pulling actor identity from the request. */\n  extractor?: ContextExtractor;\n  /** Called when an extractor throws. Defaults to silent fail-open. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface CreateAuditMiddlewareOptions extends BaseAuditOptions {\n  /**\n   * Request header name used to forward the extracted actor id to downstream\n   * route handlers. Defaults to `AUDIT_ACTOR_HEADER`.\n   */\n  actorHeader?: string;\n}\n\nexport type WithAuditRouteOptions = BaseAuditOptions;\n\nexport type WithAuditOptions = BaseAuditOptions;\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/**\n * Default header name used to forward the actor id from middleware to route\n * handlers.\n *\n * Use this constant to keep the middleware and route handler in sync:\n * ```ts\n * // middleware.ts\n * export default createAuditMiddleware(); // sets AUDIT_ACTOR_HEADER\n *\n * // app/api/orders/route.ts\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport const AUDIT_ACTOR_HEADER = \"x-better-audit-actor-id\";\n\n// ---------------------------------------------------------------------------\n// createAuditMiddleware / betterAuditNext\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a Next.js edge middleware function that extracts audit context from\n * the incoming request and forwards the actor id as a request header to\n * downstream route handlers.\n *\n * **Important:** Next.js middleware runs in a separate Edge Runtime execution\n * context from route handlers — AsyncLocalStorage set here does NOT propagate.\n * This middleware forwards the extracted actor id via a request header\n * (`x-better-audit-actor-id` by default). Use `withAuditRoute` in your route\n * handlers to read that header and populate ALS.\n *\n * The middleware **always** overwrites the actor header on the forwarded\n * request — when extraction fails, it is set to an empty string. This prevents\n * clients from spoofing the actor id by sending the header directly.\n *\n * The middleware is non-blocking: if context extraction fails, the request\n * proceeds with an empty actor header (fail open).\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { createAuditMiddleware } from \"@usebetterdev/audit-next\";\n * export default createAuditMiddleware();\n * export const config = { matcher: \"/api/:path*\" };\n *\n * // app/api/orders/route.ts\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function createAuditMiddleware(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  const extractor = options.extractor ?? defaultExtractor;\n  const actorHeader = options.actorHeader ?? AUDIT_ACTOR_HEADER;\n\n  return async (request) => {\n    const actorId = await safeExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    // Always forward with an explicit header value so clients cannot spoof\n    // the actor id by sending the header directly. When extraction fails the\n    // header is set to \"\" — fromHeader() treats empty values as undefined.\n    const requestHeaders = new Headers(request.headers);\n    requestHeaders.set(actorHeader, actorId ?? \"\");\n\n    return NextResponse.next({\n      request: { headers: requestHeaders },\n    });\n  };\n}\n\n/**\n * Convenience alias for `createAuditMiddleware`. Use as the default export\n * in `middleware.ts`.\n *\n * @example\n * ```ts\n * // middleware.ts\n * import { betterAuditNext } from \"@usebetterdev/audit-next\";\n * export default betterAuditNext();\n * ```\n */\nexport function betterAuditNext(\n  options: CreateAuditMiddlewareOptions = {},\n): NextMiddleware {\n  return createAuditMiddleware(options);\n}\n\n// ---------------------------------------------------------------------------\n// withAuditRoute\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js App Router route handler with audit context propagation.\n *\n * Extracts the actor identity from the incoming request (by default reads\n * `sub` from `Authorization: Bearer <jwt>`, or reads the\n * `x-better-audit-actor-id` header forwarded by `createAuditMiddleware`) and\n * runs the handler inside an AsyncLocalStorage scope so that `getAuditContext()`\n * returns the correct context within the handler.\n *\n * `NextRequest` is a Web `Request` subclass — extractors from audit-core\n * (`fromBearerToken`, `fromHeader`, `fromCookie`) work directly.\n *\n * The wrapper is non-blocking: if extraction fails, the handler runs without\n * audit context (fail open).\n *\n * @example\n * ```ts\n * // app/api/orders/route.ts — standalone (no middleware)\n * import { withAuditRoute } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler);\n *\n * // app/api/orders/route.ts — paired with createAuditMiddleware\n * import { withAuditRoute, fromHeader, AUDIT_ACTOR_HEADER } from \"@usebetterdev/audit-next\";\n * export const GET = withAuditRoute(handler, {\n *   extractor: { actor: fromHeader(AUDIT_ACTOR_HEADER) },\n * });\n * ```\n */\nexport function withAuditRoute<C extends RouteContext = RouteContext>(\n  handler: (request: NextRequest, context: C) => Promise<Response>,\n  options: WithAuditRouteOptions = {},\n): (request: NextRequest, context: C) => Promise<Response> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (request, context) => {\n    const actorId = await safeExtract(\n      extractor.actor,\n      request,\n      options.onError,\n    );\n\n    if (actorId === undefined) {\n      return handler(request, context);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => handler(request, context));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withAudit (server actions)\n// ---------------------------------------------------------------------------\n\n/**\n * Wraps a Next.js server action with audit context propagation.\n *\n * Server actions do not receive a `Request` object. This wrapper reads all\n * request headers via `next/headers` and constructs a synthetic `Request` to\n * run the configured extractor against, then wraps the action in an\n * AsyncLocalStorage scope so that `getAuditContext()` returns the correct\n * context within the action.\n *\n * The wrapper is non-blocking: if extraction fails (including when `headers()`\n * is unavailable), the action runs without audit context (fail open).\n *\n * @example\n * ```ts\n * // app/actions.ts\n * \"use server\";\n * import { withAudit } from \"@usebetterdev/audit-next\";\n *\n * export const createOrder = withAudit(async (formData: FormData) => {\n *   // getAuditContext() returns the actor here\n * });\n * ```\n */\nexport function withAudit<TArgs extends unknown[], TResult>(\n  action: (...args: TArgs) => Promise<TResult>,\n  options: WithAuditOptions = {},\n): (...args: TArgs) => Promise<TResult> {\n  const extractor = options.extractor ?? defaultExtractor;\n\n  return async (...args) => {\n    let actorId: string | undefined;\n\n    try {\n      const headersList = await headers();\n      const syntheticRequest = new Request(\"http://localhost\", {\n        headers: headersList,\n      });\n      actorId = await safeExtract(\n        extractor.actor,\n        syntheticRequest,\n        options.onError,\n      );\n    } catch (error: unknown) {\n      // headers() throws outside Next.js request context — fail open\n      options.onError?.(error);\n    }\n\n    if (actorId === undefined) {\n      return action(...args);\n    }\n\n    const auditContext: AuditContext = { actorId };\n\n    return runWithAuditContext(auditContext, () => action(...args));\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Re-exports\n// ---------------------------------------------------------------------------\n\nexport type { AuditContext, ContextExtractor, ValueExtractor };\nexport { fromBearerToken, fromCookie, fromHeader, getAuditContext, runWithAuditContext } from \"@usebetterdev/audit-core\";\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EAGA;AAAA,EACA;AAAA,OACK;AAMP,SAAS,eAAe;AACxB,SAAS,oBAAoB;AA6P7B,SAAS,mBAAAA,kBAAiB,YAAY,YAAY,mBAAAC,kBAAiB,uBAAAC,4BAA2B;AAzMvF,IAAM,qBAAqB;AAsC3B,SAAS,sBACd,UAAwC,CAAC,GACzB;AAChB,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,cAAc,QAAQ,eAAe;AAE3C,SAAO,OAAO,YAAY;AACxB,UAAM,UAAU,MAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAKA,UAAM,iBAAiB,IAAI,QAAQ,QAAQ,OAAO;AAClD,mBAAe,IAAI,aAAa,WAAW,EAAE;AAE7C,WAAO,aAAa,KAAK;AAAA,MACvB,SAAS,EAAE,SAAS,eAAe;AAAA,IACrC,CAAC;AAAA,EACH;AACF;AAaO,SAAS,gBACd,UAAwC,CAAC,GACzB;AAChB,SAAO,sBAAsB,OAAO;AACtC;AAkCO,SAAS,eACd,SACA,UAAiC,CAAC,GACuB;AACzD,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,OAAO,SAAS,YAAY;AACjC,UAAM,UAAU,MAAM;AAAA,MACpB,UAAU;AAAA,MACV;AAAA,MACA,QAAQ;AAAA,IACV;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,QAAQ,SAAS,OAAO;AAAA,IACjC;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,WAAO,oBAAoB,cAAc,MAAM,QAAQ,SAAS,OAAO,CAAC;AAAA,EAC1E;AACF;AA6BO,SAAS,UACd,QACA,UAA4B,CAAC,GACS;AACtC,QAAM,YAAY,QAAQ,aAAa;AAEvC,SAAO,UAAU,SAAS;AACxB,QAAI;AAEJ,QAAI;AACF,YAAM,cAAc,MAAM,QAAQ;AAClC,YAAM,mBAAmB,IAAI,QAAQ,oBAAoB;AAAA,QACvD,SAAS;AAAA,MACX,CAAC;AACD,gBAAU,MAAM;AAAA,QACd,UAAU;AAAA,QACV;AAAA,QACA,QAAQ;AAAA,MACV;AAAA,IACF,SAAS,OAAgB;AAEvB,cAAQ,UAAU,KAAK;AAAA,IACzB;AAEA,QAAI,YAAY,QAAW;AACzB,aAAO,OAAO,GAAG,IAAI;AAAA,IACvB;AAEA,UAAM,eAA6B,EAAE,QAAQ;AAE7C,WAAO,oBAAoB,cAAc,MAAM,OAAO,GAAG,IAAI,CAAC;AAAA,EAChE;AACF;","names":["fromBearerToken","getAuditContext","runWithAuditContext"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usebetterdev/audit-next",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "repository": "github:usebetter-dev/usebetter",
   "bugs": "https://github.com/usebetter-dev/usebetter/issues",
   "homepage": "https://github.com/usebetter-dev/usebetter#readme",
@@ -23,15 +23,8 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "build:types": "tsc --build tsconfig.build.json",
-    "lint": "oxlint",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
-    "@usebetterdev/audit-core": "workspace:*"
+    "@usebetterdev/audit-core": "0.7.0"
   },
   "peerDependencies": {
     "next": ">=14.0.0"
@@ -41,9 +34,17 @@
     "next": "^15.5.2",
     "tsup": "^8.3.5",
     "typescript": "~5.7.2",
-    "vitest": "^2.1.6"
+    "vitest": "^2.1.6",
+    "@usebetterdev/test-utils": "^0.5.2"
   },
   "engines": {
     "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:types": "tsc --build tsconfig.build.json",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}