---
title: "@playstack/nest-audiences"
description: "Guarded NestJS audience routes and a validated remote-authority command consumer."
tags: ["package","communication","audiences","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-audiences` binds the portable audience service to guarded public consent routes, list-management routes, and a validated remote-command consumer. It does not choose sessions, CAPTCHA, rate limiting, queues, or page rendering.

## Install

```sh
npm install @playstack/nest-audiences @playstack/audiences @nestjs/common
```

## Configure

```ts
PlaystackAudiencesModule.forRoot({
  audiences,
  publicGuard: appAudienceAbuseGuard,
  managementGuard: accountAuthorizationGuard,
  subscribeSource: ({ listKey }) => `public:${listKey}`,
  onSubscriptionResult: ({ result }) => confirmationQueue.enqueue(result),
  context: (request) => request.operationContext,
  ip: (request) => request.ip,
  userAgent: (request) => request.headers['user-agent'],
})
```

Use `forRootAsync({ imports, inject, useFactory })` when the composition root resolves the service through Nest dependency injection. The module is non-global.

## Configuration reference

| `NestAudiencesOptions` property | Required | Purpose |
| --- | --- | --- |
| `audiences` | Yes | The configured core facade. |
| `publicGuard` | Yes | Application abuse policy for public consent routes. |
| `managementGuard` | Yes | Application account and role policy for management routes. |
| `subscribeSource` | Yes | Produces append-only consent-source evidence. |
| `onSubscriptionResult` | No | Receives trusted server results so the application can queue confirmation messages. |
| `context`, `ip`, `userAgent` | No | Extract operation and consent evidence from the application request shape. |

Public mutation responses never include subscriber IDs or signed tokens. GET confirmation and unsubscribe routes inspect token state only; POST routes perform mutations.

## Remote worker

```ts
await remoteConsumer.handle(job.data)
```

Call `PlaystackAudienceRemoteCommandConsumer.handle()` from the queue worker selected by the application. It validates the untrusted data-only envelope before delegating to `audiences.processRemote()`.

Inject `AUDIENCES_SERVICE` for the configured facade or `NEST_AUDIENCES_OPTIONS` for the binding options. These are escape hatches, not alternative ownership boundaries.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/nest-audiences@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-audiences` | `./dist/index.d.ts` |
| `@playstack/nest-audiences/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. |
| `@playstack/audiences` | `0.1.0-beta.1` | Required by the package. |
| `@playstack/core` | `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 */}