---
title: "@playstack/nest-analytics"
description: "Queued NestJS delivery for server-originated Playstack analytics events."
tags: ["package","operations","analytics","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-analytics` keeps provider I/O outside request handlers by validating server-originated analytics and dispatching one idempotent queue job per eligible provider.

{/* 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-analytics@0.1.0-beta.1
```

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

{/* package-install:end */}

## Compose the module

```ts
const core = configureAnalytics({ drivers: [serverPostHogProvider] })
const analyticsQueue = createQueue('analytics', {
  app: 'billing',
  environment: 'production',
  driver: queueDriver,
})

PlaystackAnalyticsModule.forRoot({
  queue: analyticsQueue,
  drivers: [asServerAnalyticsDriver(core.driver('posthog'))],
  onError: (failure) => errors.captureError(failure.error),
})
```

`asServerAnalyticsDriver` is an explicit assertion that the injected client supports server ingestion. Do not mark a browser-only driver merely because it has a structural `track` method.

## Module and driver properties

| Surface | Contract |
| --- | --- |
| `queue` | Application-owned `@playstack/queues` queue. |
| `drivers` | Unique server drivers with `id`, native `client`, `runtime: 'server'`, consent requirement, and `track`. |
| `onError` | Isolated observer for validation, enqueue, or delivery failures. |

Use `forRootAsync({ imports, inject, useFactory })` for DI-resolved composition.

## Dispatch events

```ts
analytics.track({
  id: `renewal-${invoice.id}`,
  event: 'subscription_renewed',
  properties: { account_id: account.id, plan: 'pro', value: invoice.total },
  consent: account.analyticsConsent,
})
```

IDs are required URL-safe strings up to 48 characters. They become portable `event_id` and per-driver queue keys `analytics-<eventId>-<driverId>`, deduplicating each provider independently. Because `event_id` occupies one of 30 property slots, supply at most 29 additional properties.

Consent-required drivers are skipped unless the event carries `granted`; skipped calls are not replayed. `track` returns synchronously and never fails the originating request.

## Worker bridge

Register `PlaystackAnalyticsDeliveryJob` with the application queue processor using the Nest-managed instance. Each provider gets a separate job with five exponential-backoff attempts. Invalid payloads and unknown drivers are non-retryable; provider failures are retryable and exhausted delivery reaches `onError`.

## Boundary

The module emits no domain events and owns no queue lifecycle. It does not persist consent or make browser and server calls equivalent automatically. To deduplicate the same logical event across runtimes, propagate a provider-supported common event ID or choose one authoritative path.

{/* package-reference:start */}

## API entry points and requirements

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