@dudousxd/nestjs-diagnostics 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.8.0
+
+### Minor Changes
+
+- [#71](https://github.com/DavideCarvalho/nestjs-diagnostics/pull/71) [`f4c910b`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/f4c910b0651ee9419aa452268f23646533d10306) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add `subscribeOfficial(lib, types | 'all', fn)`, which subscribes to the first-party `nestjs:<lib>:<type>` channels (`@nestjs/resilience`, `workflows`, `authentication`, `authorization`, `mail`) and wraps each raw payload in the Aviary envelope, with `traceId` from the context accessor and `source: 'nestjs'`. The channel lists are exported per lib (`NESTJS_*_CHANNELS`, `OFFICIAL_CHANNELS`), pinned to `OFFICIAL_PACKAGE_VERSIONS`, and guarded by a drift test. Aviary never publishes on `nestjs:*`.
+
 ## 0.7.2
 
 ### Patch Changes

package/README.md

@@ -94,6 +94,45 @@ const off = onChannelRegistered(subscribe);
 This is exactly how `@dudousxd/nestjs-diagnostics-telescope`'s single generic
 watcher records every diagnostic event in the Telescope dashboard.
 
+## First-party `nestjs:*` channels
+
+The official NestJS packages publish their own events on
+`diagnostics_channel` with the convention `nestjs:<lib>:<type>`: a raw
+payload, with no envelope and no traceId (see
+[docs.nestjs.com](https://docs.nestjs.com)). **`nestjs:*` is the first-party
+convention, and Aviary never publishes on it.** `aviary:*` is only for what the
+official packages don't emit.
+
+`subscribeOfficial` lets one consumer record both. It wraps each official
+payload in the Aviary envelope, with `traceId` taken from the context accessor
+and `source: 'nestjs'`:
+
+```ts
+import { subscribeOfficial } from '@dudousxd/nestjs-diagnostics';
+
+const off = subscribeOfficial('resilience', ['retry', 'circuit-open'], (event, channel) => {
+  // event: { v, ts, lib: 'resilience', event: 'retry', traceId, payload, source: 'nestjs' }
+});
+subscribeOfficial('authentication', 'all', record);
+off();
+```
+
+The channel lists are exported per lib in one file, pinned to the official
+versions they were verified against (`OFFICIAL_PACKAGE_VERSIONS`). A test
+re-reads the installed packages and fails if a channel is added or renamed.
+
+| Lib | Constant | Channels |
+| --- | --- | --- |
+| `@nestjs/resilience` 0.0.3 | `NESTJS_RESILIENCE_CHANNELS` | 9 |
+| `@nestjs/workflows` 0.0.5 | `NESTJS_WORKFLOWS_CHANNELS` | 19 |
+| `@nestjs/authentication` 0.1.5 | `NESTJS_AUTHENTICATION_CHANNELS` | 13 |
+| `@nestjs/authorization` 0.1.3 | `NESTJS_AUTHORIZATION_CHANNELS` | 1 (`denied`) |
+| `@nestjs/mail` 0.0.2 | `NESTJS_MAIL_CHANNELS` | 2 (`sent`, `failed`) |
+
+These channels are not added to the `aviary:*` registry
+(`registeredChannels`/`onChannelRegistered`). Their lists are fixed, so subscribe
+to them explicitly.
+
 ## API
 
 | Export | Description |
@@ -106,7 +145,9 @@ watcher records every diagnostic event in the Telescope dashboard.
 | `onChannelRegistered(cb)` | Notified once per future channel registration; returns an unsubscribe. |
 | `setContextAccessor(accessor \| null)` | Register the accessor `emit` reads `traceId` from. |
 | `CONTEXT_ACCESSOR` | Shared DI token for the optional context accessor. |
-| `DiagnosticEvent`, `EmitOptions`, `ContextAccessor` | Types. |
+| `subscribeOfficial(lib, types \| 'all', fn)` | Subscribe to first-party `nestjs:<lib>:<type>` channels, each payload wrapped in the envelope (+ `source: 'nestjs'`). Returns an unsubscribe. |
+| `OFFICIAL_CHANNELS`, `NESTJS_*_CHANNELS`, `OFFICIAL_PACKAGE_VERSIONS`, `officialChannelNames()` | The pinned first-party channel lists. |
+| `DiagnosticEvent`, `EmitOptions`, `ContextAccessor`, `OfficialDiagnosticEvent` | Types. |
 
 ## Reacting to events in NestJS — `@OnDiagnostic`
 

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from '.
 export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
 export { assertCapabilityNaming } from './conformance.js';
 export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, getContextAccessor, resolveTraceId, setContextAccessor, type UserRef, } from './context-accessor.js';
+export { NESTJS_AUTHENTICATION_CHANNELS, NESTJS_AUTHORIZATION_CHANNELS, NESTJS_MAIL_CHANNELS, NESTJS_RESILIENCE_CHANNELS, NESTJS_WORKFLOWS_CHANNELS, OFFICIAL_CHANNEL_PREFIX, OFFICIAL_CHANNELS, OFFICIAL_PACKAGE_VERSIONS, type OfficialChannelName, type OfficialDiagnosticEvent, type OfficialLib, type OfficialListener, type OfficialType, officialChannelNames, subscribeOfficial, } from './official.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
 export { SPAN_SCHEMA_VERSION, trace, type TraceChannelNames, traceChannelNames, type TracingChannel, tracingChannel, } from './trace.js';
 export type { ChannelRegistry, DiagnosticEvent, EmitOptions, EventOf, LibOf, PayloadOf, SpanEvent, SpanPhase, TraceOptions, } from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from '.
 export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
 export { assertCapabilityNaming } from './conformance.js';
 export { CONTEXT_ACCESSOR, getContextAccessor, resolveTraceId, setContextAccessor, } from './context-accessor.js';
+export { NESTJS_AUTHENTICATION_CHANNELS, NESTJS_AUTHORIZATION_CHANNELS, NESTJS_MAIL_CHANNELS, NESTJS_RESILIENCE_CHANNELS, NESTJS_WORKFLOWS_CHANNELS, OFFICIAL_CHANNEL_PREFIX, OFFICIAL_CHANNELS, OFFICIAL_PACKAGE_VERSIONS, officialChannelNames, subscribeOfficial, } from './official.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
 export { SPAN_SCHEMA_VERSION, trace, traceChannelNames, tracingChannel, } from './trace.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,iBAAiB,EACjB,yBAAyB,EAMzB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/official.d.ts

@@ -0,0 +1,83 @@
+import type { DiagnosticEvent } from './types.js';
+/**
+ * The first-party NestJS packages publish raw events on `node:diagnostics_channel`
+ * under the fixed convention `nestjs:<lib>:<type>`: no envelope, no traceId. This
+ * file is the ONE place their channel lists live. Each list was read from the
+ * published tarball of the version in {@link OFFICIAL_PACKAGE_VERSIONS}, and
+ * `test/official.spec.ts` re-reads the installed (pinned) packages and fails when
+ * a channel is added, renamed or removed.
+ *
+ * Aviary never publishes on `nestjs:*`. It only subscribes, through
+ * {@link subscribeOfficial}. `aviary:*` is for what the official packages don't emit.
+ */
+export declare const OFFICIAL_CHANNEL_PREFIX = "nestjs";
+/** `nestjs:<lib>:<type>`, the first-party channel name. */
+export type OfficialChannelName<L extends string, T extends string> = `nestjs:${L}:${T}`;
+type ChannelMap<L extends string, T extends readonly string[]> = {
+    readonly [K in T[number]]: OfficialChannelName<L, K>;
+};
+/** `@nestjs/resilience`: the 9 fixed channels of `events/resilience.channels.js`. */
+export declare const NESTJS_RESILIENCE_CHANNELS: ChannelMap<"resilience", readonly ["retry", "timeout", "circuit-open", "circuit-half-open", "circuit-closed", "circuit-rejected", "bulkhead-rejected", "rate-limited", "fallback"]>;
+/** `@nestjs/workflows`: `channelFor(event.type)` over the 19 `WorkflowEvent` types. */
+export declare const NESTJS_WORKFLOWS_CHANNELS: ChannelMap<"workflows", readonly ["workflow-started", "workflow-resumed", "workflow-suspended", "workflow-compensating", "workflow-completed", "workflow-failed", "workflow-cancelled", "workflow-compensation-failed", "step-completed", "step-failed", "step-compensated", "child-started", "signal-received", "signal-timed-out", "journal-large", "custom-status", "workflow-retried", "workflow-deleted", "schedule-skipped"]>;
+/** `@nestjs/authentication`: `channelFor(event.type)` over the 13 `AuthenticationEvent` types. */
+export declare const NESTJS_AUTHENTICATION_CHANNELS: ChannelMap<"authentication", readonly ["sign-in", "sign-out", "mfa-verified", "mfa-failed", "mfa-enabled", "mfa-disabled", "recovery-codes-generated", "refresh-token-reused", "password-reset-requested", "password-reset", "email-verified", "magic-link-refused", "session-touch-failed"]>;
+/** `@nestjs/authorization`: the single `deniedChannel`. */
+export declare const NESTJS_AUTHORIZATION_CHANNELS: ChannelMap<"authorization", readonly ["denied"]>;
+/** `@nestjs/mail`: `channels.sent` and `channels.failed`. */
+export declare const NESTJS_MAIL_CHANNELS: ChannelMap<"mail", readonly ["sent", "failed"]>;
+/** Every known first-party lib → its `type → channel name` map. */
+export declare const OFFICIAL_CHANNELS: Readonly<{
+    resilience: ChannelMap<"resilience", readonly ["retry", "timeout", "circuit-open", "circuit-half-open", "circuit-closed", "circuit-rejected", "bulkhead-rejected", "rate-limited", "fallback"]>;
+    workflows: ChannelMap<"workflows", readonly ["workflow-started", "workflow-resumed", "workflow-suspended", "workflow-compensating", "workflow-completed", "workflow-failed", "workflow-cancelled", "workflow-compensation-failed", "step-completed", "step-failed", "step-compensated", "child-started", "signal-received", "signal-timed-out", "journal-large", "custom-status", "workflow-retried", "workflow-deleted", "schedule-skipped"]>;
+    authentication: ChannelMap<"authentication", readonly ["sign-in", "sign-out", "mfa-verified", "mfa-failed", "mfa-enabled", "mfa-disabled", "recovery-codes-generated", "refresh-token-reused", "password-reset-requested", "password-reset", "email-verified", "magic-link-refused", "session-touch-failed"]>;
+    authorization: ChannelMap<"authorization", readonly ["denied"]>;
+    mail: ChannelMap<"mail", readonly ["sent", "failed"]>;
+}>;
+/** The official package version each list above was verified against. */
+export declare const OFFICIAL_PACKAGE_VERSIONS: Readonly<{
+    resilience: string;
+    workflows: string;
+    authentication: string;
+    authorization: string;
+    mail: string;
+}>;
+/** A first-party lib whose channels are listed here. */
+export type OfficialLib = keyof typeof OFFICIAL_CHANNELS;
+/** The event types `L` publishes, e.g. `'retry' | 'timeout' | …` for `'resilience'`. */
+export type OfficialType<L extends OfficialLib> = keyof (typeof OFFICIAL_CHANNELS)[L] & string;
+/** Every first-party channel name, flattened. */
+export declare function officialChannelNames(): string[];
+/**
+ * The Aviary envelope wrapped around an official payload: the usual
+ * {@link DiagnosticEvent} plus `source: 'nestjs'`, so an observer that records
+ * both kinds (Telescope's `DiagnosticWatcher`) can tell them apart. Aviary's own
+ * `emit()` envelopes carry no `source`.
+ */
+export interface OfficialDiagnosticEvent<TPayload = unknown> extends DiagnosticEvent<TPayload> {
+    source: 'nestjs';
+}
+/** Receives each wrapped official event and the `nestjs:*` channel it came from. */
+export type OfficialListener = (event: OfficialDiagnosticEvent, channel: string) => void;
+/**
+ * Subscribe to first-party `nestjs:<lib>:<type>` channels and receive each raw
+ * payload wrapped in the Aviary envelope `{ v, ts, lib, event, traceId, payload,
+ * source: 'nestjs' }`:
+ *
+ * - `traceId` comes from the registered context accessor. Official publishers run
+ *   subscribers synchronously in the caller's async context, so it is the
+ *   request's traceId;
+ * - `durationMs` is copied from the payload when it carries a numeric one
+ *   (e.g. workflows' `step-completed`).
+ *
+ * Returns an unsubscribe function. A throwing `fn` never reaches the official
+ * publisher. Subscribing only reads `nestjs:*`; Aviary never publishes there.
+ *
+ * ```ts
+ * const off = subscribeOfficial('resilience', ['retry', 'circuit-open'], (e) => log(e));
+ * subscribeOfficial('authentication', 'all', record);
+ * ```
+ */
+export declare function subscribeOfficial<L extends OfficialLib>(lib: L, types: readonly OfficialType<L>[] | 'all', fn: OfficialListener): () => void;
+export {};
+//# sourceMappingURL=official.d.ts.map

package/dist/official.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"official.d.ts","sourceRoot":"","sources":["../src/official.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD,2DAA2D;AAC3D,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;AAEzF,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,SAAS,MAAM,EAAE,IAAI;IAC/D,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC;CACrD,CAAC;AAWF,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,qLAUrC,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,qaAoBpC,CAAC;AAEH,kGAAkG;AAClG,eAAO,MAAM,8BAA8B,+RAczC,CAAC;AAEH,2DAA2D;AAC3D,eAAO,MAAM,6BAA6B,kDAA0C,CAAC;AAErF,6DAA6D;AAC7D,eAAO,MAAM,oBAAoB,iDAAyC,CAAC;AAE3E,mEAAmE;AACnE,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,yBAAyB;;;;;;EAME,CAAC;AAEzC,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAEzD,wFAAwF;AACxF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,WAAW,IAAI,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;AAE/F,iDAAiD;AACjD,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,QAAQ,GAAG,OAAO,CAAE,SAAQ,eAAe,CAAC,QAAQ,CAAC;IAC5F,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACrD,GAAG,EAAE,CAAC,EACN,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EACzC,EAAE,EAAE,gBAAgB,GACnB,MAAM,IAAI,CA8CZ"}

package/dist/official.js

@@ -0,0 +1,159 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { SCHEMA_VERSION } from './channel.js';
+import { resolveTraceId } from './context-accessor.js';
+/**
+ * The first-party NestJS packages publish raw events on `node:diagnostics_channel`
+ * under the fixed convention `nestjs:<lib>:<type>`: no envelope, no traceId. This
+ * file is the ONE place their channel lists live. Each list was read from the
+ * published tarball of the version in {@link OFFICIAL_PACKAGE_VERSIONS}, and
+ * `test/official.spec.ts` re-reads the installed (pinned) packages and fails when
+ * a channel is added, renamed or removed.
+ *
+ * Aviary never publishes on `nestjs:*`. It only subscribes, through
+ * {@link subscribeOfficial}. `aviary:*` is for what the official packages don't emit.
+ */
+export const OFFICIAL_CHANNEL_PREFIX = 'nestjs';
+function channelsOf(lib, types) {
+    return Object.freeze(Object.fromEntries(types.map((type) => [type, `${OFFICIAL_CHANNEL_PREFIX}:${lib}:${type}`])));
+}
+/** `@nestjs/resilience`: the 9 fixed channels of `events/resilience.channels.js`. */
+export const NESTJS_RESILIENCE_CHANNELS = channelsOf('resilience', [
+    'retry',
+    'timeout',
+    'circuit-open',
+    'circuit-half-open',
+    'circuit-closed',
+    'circuit-rejected',
+    'bulkhead-rejected',
+    'rate-limited',
+    'fallback',
+]);
+/** `@nestjs/workflows`: `channelFor(event.type)` over the 19 `WorkflowEvent` types. */
+export const NESTJS_WORKFLOWS_CHANNELS = channelsOf('workflows', [
+    'workflow-started',
+    'workflow-resumed',
+    'workflow-suspended',
+    'workflow-compensating',
+    'workflow-completed',
+    'workflow-failed',
+    'workflow-cancelled',
+    'workflow-compensation-failed',
+    'step-completed',
+    'step-failed',
+    'step-compensated',
+    'child-started',
+    'signal-received',
+    'signal-timed-out',
+    'journal-large',
+    'custom-status',
+    'workflow-retried',
+    'workflow-deleted',
+    'schedule-skipped',
+]);
+/** `@nestjs/authentication`: `channelFor(event.type)` over the 13 `AuthenticationEvent` types. */
+export const NESTJS_AUTHENTICATION_CHANNELS = channelsOf('authentication', [
+    'sign-in',
+    'sign-out',
+    'mfa-verified',
+    'mfa-failed',
+    'mfa-enabled',
+    'mfa-disabled',
+    'recovery-codes-generated',
+    'refresh-token-reused',
+    'password-reset-requested',
+    'password-reset',
+    'email-verified',
+    'magic-link-refused',
+    'session-touch-failed',
+]);
+/** `@nestjs/authorization`: the single `deniedChannel`. */
+export const NESTJS_AUTHORIZATION_CHANNELS = channelsOf('authorization', ['denied']);
+/** `@nestjs/mail`: `channels.sent` and `channels.failed`. */
+export const NESTJS_MAIL_CHANNELS = channelsOf('mail', ['sent', 'failed']);
+/** Every known first-party lib → its `type → channel name` map. */
+export const OFFICIAL_CHANNELS = Object.freeze({
+    resilience: NESTJS_RESILIENCE_CHANNELS,
+    workflows: NESTJS_WORKFLOWS_CHANNELS,
+    authentication: NESTJS_AUTHENTICATION_CHANNELS,
+    authorization: NESTJS_AUTHORIZATION_CHANNELS,
+    mail: NESTJS_MAIL_CHANNELS,
+});
+/** The official package version each list above was verified against. */
+export const OFFICIAL_PACKAGE_VERSIONS = Object.freeze({
+    resilience: '0.0.3',
+    workflows: '0.0.5',
+    authentication: '0.1.5',
+    authorization: '0.1.3',
+    mail: '0.0.2',
+});
+/** Every first-party channel name, flattened. */
+export function officialChannelNames() {
+    return Object.values(OFFICIAL_CHANNELS).flatMap((map) => Object.values(map));
+}
+/**
+ * Subscribe to first-party `nestjs:<lib>:<type>` channels and receive each raw
+ * payload wrapped in the Aviary envelope `{ v, ts, lib, event, traceId, payload,
+ * source: 'nestjs' }`:
+ *
+ * - `traceId` comes from the registered context accessor. Official publishers run
+ *   subscribers synchronously in the caller's async context, so it is the
+ *   request's traceId;
+ * - `durationMs` is copied from the payload when it carries a numeric one
+ *   (e.g. workflows' `step-completed`).
+ *
+ * Returns an unsubscribe function. A throwing `fn` never reaches the official
+ * publisher. Subscribing only reads `nestjs:*`; Aviary never publishes there.
+ *
+ * ```ts
+ * const off = subscribeOfficial('resilience', ['retry', 'circuit-open'], (e) => log(e));
+ * subscribeOfficial('authentication', 'all', record);
+ * ```
+ */
+export function subscribeOfficial(lib, types, fn) {
+    const map = OFFICIAL_CHANNELS[lib];
+    if (!map) {
+        throw new TypeError(`subscribeOfficial: unknown first-party lib '${String(lib)}'`);
+    }
+    const selected = types === 'all' ? Object.keys(map) : [...new Set(types)];
+    if (selected.length === 0) {
+        throw new TypeError(`subscribeOfficial: no '${lib}' channel selected; pass one or more types, or 'all'`);
+    }
+    const subscriptions = [];
+    for (const type of selected) {
+        const name = map[type];
+        if (name === undefined) {
+            throw new TypeError(`subscribeOfficial: '${lib}' publishes no '${type}' channel`);
+        }
+        const listener = (message) => {
+            try {
+                const duration = message?.durationMs;
+                const event = {
+                    v: SCHEMA_VERSION,
+                    ts: Date.now(),
+                    lib,
+                    event: type,
+                    traceId: resolveTraceId(),
+                    payload: message,
+                    source: 'nestjs',
+                    ...(typeof duration === 'number' && { durationMs: duration }),
+                };
+                fn(event, name);
+            }
+            catch {
+                // An observer must never change the outcome of the call it observes.
+            }
+        };
+        diagnostics_channel.subscribe(name, listener);
+        subscriptions.push([name, listener]);
+    }
+    let active = true;
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        for (const [name, listener] of subscriptions) {
+            diagnostics_channel.unsubscribe(name, listener);
+        }
+    };
+}
+//# sourceMappingURL=official.js.map

package/dist/official.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"official.js","sourceRoot":"","sources":["../src/official.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,19 @@
     "url": "git+https://github.com/DavideCarvalho/nestjs-diagnostics.git",
     "directory": "packages/core"
   },
+  "homepage": "https://davidecarvalho.github.io/aviary/docs/diagnostics",
+  "bugs": {
+    "url": "https://github.com/DavideCarvalho/nestjs-diagnostics/issues"
+  },
+  "keywords": [
+    "nestjs",
+    "diagnostics",
+    "diagnostics-channel",
+    "observability",
+    "telemetry",
+    "events",
+    "tanstack-intent"
+  ],
   "author": "Davi Carvalho <davi@goflip.ai>",
   "type": "module",
   "main": "./dist/index.js",
@@ -58,9 +71,14 @@
     "**/trace.ts"
   ],
   "devDependencies": {
-    "@nestjs/common": "12.0.1",
-    "@nestjs/core": "12.0.1",
-    "@nestjs/testing": "12.0.1",
+    "@nestjs/authentication": "0.1.5",
+    "@nestjs/authorization": "0.1.3",
+    "@nestjs/common": "12.0.4",
+    "@nestjs/core": "12.0.4",
+    "@nestjs/mail": "0.0.2",
+    "@nestjs/resilience": "0.0.3",
+    "@nestjs/testing": "12.0.4",
+    "@nestjs/workflows": "0.0.5",
     "@types/node": "20.19.43",
     "reflect-metadata": "0.2.2",
     "typescript": "5.9.3",
@@ -70,15 +88,6 @@
   "engines": {
     "node": ">=20"
   },
-  "keywords": [
-    "nestjs",
-    "diagnostics",
-    "diagnostics-channel",
-    "observability",
-    "telemetry",
-    "events",
-    "tanstack-intent"
-  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",

package/skills/observe-channels/SKILL.md

@@ -162,3 +162,12 @@ The core swallows errors in `emit`/`registerChannel`, but a listener you attach
 directly runs inside the synchronous `publish` — guard it yourself, as the
 Telescope watcher's `safeRecord` does.
 Source: `packages/telescope/src/diagnostic.watcher.ts` (`safeRecord`).
+
+## First-party `nestjs:*` channels
+
+The official NestJS packages (`@nestjs/resilience`, `workflows`,
+`authentication`, `authorization`, `mail`) publish raw payloads on
+`nestjs:<lib>:<type>`. These channels are not in the registry. Use
+`subscribeOfficial(lib, types | 'all', fn)`, which wraps each payload in the
+envelope with `traceId` and `source: 'nestjs'`. Never publish on `nestjs:*`
+yourself. Lists: `OFFICIAL_CHANNELS` / `NESTJS_*_CHANNELS`.