@playstack/nest-audiences

Guarded NestJS audience routes and a validated remote-authority command consumer.

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@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

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

Configure

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

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.

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. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.