---
title: "@playstack/nest-audit"
description: "Explicit application-route audit declarations for NestJS."
tags: ["package","identity","audit","nestjs","pro"]
---

{/* package-access:start */}

> **Pro.** Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/nest-audit` makes route-level audit intent visible in NestJS metadata while reusing an existing `@playstack/audit` recorder and retention policy.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/nest-audit@0.1.0-beta.1
```

Check the peer requirements below before choosing a runtime or provider.

{/* package-install:end */}

## Compose explicit route audit

```ts
PlaystackAuditModule.forRoot({
  audit,
  onFailure: (error) => errors.captureError(error),
})

@UseInterceptors(PlaystackAuditInterceptor)
@Audited({
  map: (request, response) => ({
    scopeType: 'account',
    scopeId: request.playstackAccount.accountId,
    actorType: 'user',
    actorId: request.playstackSession.userId,
    action: 'project.created',
    resourceType: 'project',
    resourceId: response.id,
  }),
})
@Post('/projects')
create() {}
```

## Configuration and bridge properties

| Surface | Contract |
| --- | --- |
| `audit` | Recorder exposing validated `retention` and `record(input)`. |
| `onFailure` | Optional isolated sync/async observer for mapping or recording failures. |
| `AuditRouteDeclaration.map` | Receives the framework request and successful response; returns an `AuditEntryInput`. |

Module construction validates that the recorder carries an immutable `AuditRetentionPolicy`, failing before startup when it is absent or malformed. `forRootAsync({ imports, inject, useFactory })` supports DI-based composition.

The interceptor records successful responses only. It is queued/best effort: failures reach `onFailure` and never turn an already-committed mutation into an HTTP failure.

## Boundary

Use transactional `@playstack/events` audit handlers for security-critical package operations. This adapter does not infer important operations, replace domain events, install itself globally, or own persistence; application routes opt in explicitly.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/nest-audit@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/nest-audit` | `./dist/index.d.ts` |
| `@playstack/nest-audit/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

| Peer | Compatible range | When needed |
| --- | --- | --- |
| `@nestjs/common` | `^10.0.0 \|\| ^11.0.0` | Required by the package. |
| `@nestjs/core` | `^10.0.0 \|\| ^11.0.0` | Required by the package. |
| `@playstack/audit` | `0.1.0-beta.1` | Required by the package. |
| `reflect-metadata` | `^0.1.13 \|\| ^0.2.0` | Required by the package. |
| `rxjs` | `^7.0.0` | Required by the package. |

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}