@heavybit/shared-lib 0.0.0-stage → 1.2.0

package/dist/types/logging/index.d.ts

@@ -0,0 +1,22 @@
+import winston from 'winston';
+import type { Logger } from '../types/index.js';
+/** Keys whose values are replaced with `[REDACTED]` anywhere in log metadata. */
+export declare const DEFAULT_REDACT_KEYS: string[];
+export interface LoggerOptions {
+    level?: string;
+    /** `json` for machines (default in production), `pretty` for humans. */
+    format?: 'json' | 'pretty';
+    redactKeys?: string[];
+}
+/** Structured logger with secret redaction. JSON to stdout in production, pretty otherwise. */
+export declare function createLogger(service: string, options?: LoggerOptions): winston.Logger & Logger;
+/** Logger that discards everything — handy default for libraries and tests. */
+export declare const silentLogger: Logger;
+/**
+ * A logger that adds `context` (for example pipeline IDs) to every line it writes; a line's own
+ * meta wins on a key clash. `undefined` context values are dropped so lines never carry empty keys.
+ * Works over any {@link Logger} (winston, a test spy, or another child), so handlers can create one
+ * per message and pass it down.
+ */
+export declare function childLogger(logger: Logger, context: Record<string, unknown>): Logger;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/logging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,UAG/B,CAAC;AA6BF,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,MAAM,CAiBlG;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY,EAAE,MAA6E,CAAC;AAEzG;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKpF"}

package/dist/types/messaging/connection.d.ts

@@ -0,0 +1,48 @@
+import type { Channel, ConfirmChannel } from 'amqplib';
+import type { Logger } from '../types/index.js';
+export interface ChannelHandle<C extends Channel = Channel> {
+    readonly name: string;
+    /** The live channel, or null while disconnected. */
+    current(): C | null;
+}
+export interface AmqpConnectionOptions {
+    url: string;
+    /** Shown in the RabbitMQ management UI (`connection_name`). */
+    connectionName: string;
+    logger?: Logger;
+    heartbeatSec?: number;
+    /** Delay before reconnect attempt n (1-based). Default: 1s, 2s, 4s … capped at 30s. */
+    reconnectDelayMs?: (attempt: number) => number;
+}
+/**
+ * One AMQP connection per process with automatic reconnect. Components register channels
+ * with a `setup` callback (assert topology, start consuming); setups re-run after every
+ * reconnect so consumers and publishers heal without restarts.
+ */
+export declare class AmqpConnection {
+    private readonly options;
+    private model;
+    private readonly registrations;
+    private closing;
+    private connecting;
+    private readonly logger;
+    constructor(options: AmqpConnectionOptions);
+    get isConnected(): boolean;
+    /** Registers a channel. If already connected it is opened immediately. */
+    registerChannel<C extends Channel = Channel>(name: string, setup: (channel: C) => Promise<void>, options?: {
+        confirm?: boolean;
+    }): Promise<ChannelHandle<C>>;
+    /**
+     * Connects, retrying with back-off until it succeeds or `close()` is called. Resolves once the
+     * first connection is up; later drops reconnect in the background.
+     */
+    connect(): Promise<void>;
+    /** Throws when the broker is not reachable — used by readiness checks. */
+    assertReady(): void;
+    close(): Promise<void>;
+    private connectWithRetry;
+    private establish;
+    private openChannel;
+}
+export type { Channel, ConfirmChannel };
+//# sourceMappingURL=connection.d.ts.map

package/dist/types/messaging/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/messaging/connection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC;CACrB;AASD,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CAChD;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAOb,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,OAAO,EAAE,qBAAqB;IAI3D,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,0EAA0E;IACpE,eAAe,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAOtK;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,0EAA0E;IAC1E,WAAW,IAAI,IAAI;IAIb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAUd,gBAAgB;YAahB,SAAS;YAoBT,WAAW;CAe1B;AAED,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/types/messaging/consumer.d.ts

@@ -0,0 +1,56 @@
+import type { ConsumeMessage } from 'amqplib';
+import type { ZodTypeAny } from 'zod';
+import type { EventEnvelope, Logger } from '../types/index.js';
+import type { AmqpConnection } from './connection.js';
+import type { IdempotencyStore } from './idempotency.js';
+import { type Topology } from './topology.js';
+export interface Binding {
+    /** `events` (topic, pattern keys like `auth.user.*`) or `commands` (exact command name). */
+    exchange: 'events' | 'commands';
+    routingKey: string;
+}
+export interface InboundMessage<T = unknown> {
+    /** Envelope `data`, validated against `schema` when one is given. */
+    data: T;
+    envelope: EventEnvelope | null;
+    routingKey: string;
+    /** How many times this message has been retried before (0 on first delivery). */
+    attempt: number;
+    raw: ConsumeMessage;
+}
+export interface SubscriptionOptions<T = unknown> {
+    /** Logical queue name; the environment prefix is added. Convention: `<service>:<source>.<topic>`. */
+    queue: string;
+    bindings: Binding[];
+    handler: (message: InboundMessage<T>) => Promise<void>;
+    /** Validates `data`; failures dead-letter immediately (a bad payload never succeeds on retry). */
+    schema?: ZodTypeAny;
+    prefetch?: number;
+    /** Delay before each retry. Length = max retries. Default: 1s, 5s, 25s. */
+    retryDelaysMs?: number[];
+    /** Enables duplicate suppression keyed on `<queue>:<eventId>`. */
+    idempotency?: IdempotencyStore;
+    idempotencyTtlSec?: number;
+}
+/**
+ * Durable subscriptions with bounded retries and dead-lettering:
+ *
+ *   <queue> ──fail──▶ <queue>.retry.<delay>  (TTL, dead-letters back into <queue>)
+ *           ──fail after last retry / non-retryable──▶ <queue>.dlq
+ *
+ * One fixed TTL per retry queue avoids head-of-line blocking of per-message TTLs.
+ */
+export declare class MessageConsumer {
+    private readonly connection;
+    private readonly topology;
+    private readonly handles;
+    private readonly logger;
+    constructor(connection: AmqpConnection, topology: Topology, logger?: Logger);
+    /** Physical DLQ names for every subscription (for monitoring). */
+    readonly deadLetterQueues: string[];
+    subscribe<T = unknown>(options: SubscriptionOptions<T>): Promise<void>;
+    private dispatch;
+    private retryOrDeadLetter;
+    private deadLetter;
+}
+//# sourceMappingURL=consumer.d.ts.map

package/dist/types/messaging/consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../../../src/messaging/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAGtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAuC,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnF,MAAM,WAAW,OAAO;IACtB,4FAA4F;IAC5F,QAAQ,EAAE,QAAQ,GAAG,UAAU,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,qEAAqE;IACrE,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,cAAc,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,kGAAkG;IAClG,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,kEAAkE;IAClE,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAKD;;;;;;;GAOG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAkB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAHlF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,UAAU,EAAE,cAAc,EAAmB,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM;IAI7G,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAM;IAEnC,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAiC9D,QAAQ;IAgDtB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,UAAU;CASnB"}

package/dist/types/messaging/envelope.d.ts

@@ -0,0 +1,16 @@
+import type { EventEnvelope } from '../types/index.js';
+export interface EnvelopeMeta {
+    actorId?: string | null;
+    correlationId?: string;
+    aggregate?: {
+        type: string;
+        id: string;
+        version?: number;
+    };
+    version?: number;
+    /** Deterministic ID for idempotent re-publishing (defaults to a new ULID). */
+    eventId?: string;
+}
+export declare function buildEnvelope<T>(type: string, data: T, source: string, meta?: EnvelopeMeta): EventEnvelope<T>;
+export declare function isEnvelope(value: unknown): value is EventEnvelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/types/messaging/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../../src/messaging/envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,aAAa,CAAC,CAAC,CAAC,CAYjH;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAGjE"}

package/dist/types/messaging/idempotency.d.ts

@@ -0,0 +1,29 @@
+import type { Redis } from 'ioredis';
+export type ClaimResult = 'claimed' | 'done' | 'in-flight';
+/**
+ * At-least-once delivery means duplicates. Consumers claim `consumer:eventId` before handling:
+ * - `claimed`   → process it, then `complete()` (or `abandon()` on failure so a retry can run)
+ * - `done`      → already processed; ack and skip
+ * - `in-flight` → another worker holds the lease; retry later
+ */
+export interface IdempotencyStore {
+    begin(key: string, leaseSec: number): Promise<ClaimResult>;
+    complete(key: string, ttlSec: number): Promise<void>;
+    abandon(key: string): Promise<void>;
+}
+export declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: Redis, prefix?: string);
+    begin(key: string, leaseSec: number): Promise<ClaimResult>;
+    complete(key: string, ttlSec: number): Promise<void>;
+    abandon(key: string): Promise<void>;
+}
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly entries;
+    private read;
+    begin(key: string, leaseSec: number): Promise<ClaimResult>;
+    complete(key: string, ttlSec: number): Promise<void>;
+    abandon(key: string): Promise<void>;
+}
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/types/messaging/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/messaging/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAKD,qBAAa,qBAAsB,YAAW,gBAAgB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAS,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAArC,KAAK,EAAE,KAAK,EAAmB,MAAM,SAAU;IAEtE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAO1D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAK1C;AAED,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;IAEnF,OAAO,CAAC,IAAI;IASN,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAS1D,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}

package/dist/types/messaging/index.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from '../types/index.js';
+import { AmqpConnection } from './connection.js';
+import { MessageConsumer } from './consumer.js';
+import { QueueMonitor } from './monitor.js';
+import { MessagePublisher } from './publisher.js';
+import { RpcClient, RpcServer } from './rpc.js';
+import { type Topology } from './topology.js';
+export * from './connection.js';
+export * from './topology.js';
+export * from './envelope.js';
+export * from './publisher.js';
+export * from './consumer.js';
+export * from './idempotency.js';
+export * from './rpc.js';
+export * from './outbox.js';
+export * from './monitor.js';
+export * from './staff-notifier.js';
+export interface MessagingOptions {
+    url: string;
+    app: string;
+    prefix: string;
+    service: string;
+    logger?: Logger;
+}
+export interface Messaging {
+    topology: Topology;
+    connection: AmqpConnection;
+    publisher: MessagePublisher;
+    consumer: MessageConsumer;
+    rpcServer: RpcServer;
+    rpcClient: RpcClient;
+    monitor: QueueMonitor;
+    /** Registers the publisher, RPC client and monitor, then connects (retrying until up). */
+    start(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Wires one connection with a publisher, consumer, RPC server/client and DLQ monitor. */
+export declare function createMessaging(options: MessagingOptions): Messaging;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/messaging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/messaging/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9D,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AAEpC,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,0FAA0F;IAC1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA0BpE"}

package/dist/types/messaging/monitor.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from '../types/index.js';
+import type { AmqpConnection } from './connection.js';
+export interface QueueStat {
+    queue: string;
+    messages: number;
+    consumers: number;
+}
+/**
+ * Reports queue depth (typically DLQs) for `/health` details and alerting. Uses its own
+ * channel because `checkQueue` on a missing queue closes the channel it runs on.
+ */
+export declare class QueueMonitor {
+    private readonly connection;
+    private readonly queues;
+    private handle;
+    private readonly logger;
+    private last;
+    constructor(connection: AmqpConnection, queues: () => string[], logger?: Logger);
+    init(): Promise<void>;
+    check(): Promise<QueueStat[]>;
+    get lastStats(): QueueStat[];
+}
+//# sourceMappingURL=monitor.d.ts.map

package/dist/types/messaging/monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../../../src/messaging/monitor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AAErE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAkB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJhF,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,IAAI,CAAmB;gBAEF,UAAU,EAAE,cAAc,EAAmB,MAAM,EAAE,MAAM,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM;IAI3G,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,KAAK,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAkBnC,IAAI,SAAS,IAAI,SAAS,EAAE,CAE3B;CACF"}

package/dist/types/messaging/outbox.d.ts

@@ -0,0 +1,51 @@
+import type { Knex } from 'knex';
+import type { EventEnvelope, Logger } from '../types/index.js';
+import { type CommandBus, type EventBus } from './publisher.js';
+export declare const DEFAULT_OUTBOX_TABLE = "event_outbox";
+export type OutboxKind = 'event' | 'command';
+/** Outbox `routing_key` column value: the event type, or `command:<name>` for commands. */
+export declare function outboxRoutingKey(envelope: Pick<EventEnvelope, 'type'>, kind?: OutboxKind): string;
+/**
+ * Transactional outbox: write the domain change and the event in one DB transaction, then a
+ * relay publishes pending rows with broker confirms. Closes the "row committed, event lost"
+ * gap of publish-after-commit. Consumers must be idempotent (they are: see IdempotencyStore).
+ *
+ * Table (see `createOutboxTable` in `@heavybit/shared-lib/knex`):
+ *   id CHAR(26) PK = eventId, routing_key, payload JSON, attempts, last_error, created_at, published_at
+ */
+export declare function enqueueOutbox(db: Knex | Knex.Transaction, envelope: EventEnvelope, options?: {
+    kind?: OutboxKind;
+    table?: string;
+}): Promise<void>;
+export interface OutboxRelayOptions {
+    knex: Knex;
+    bus: EventBus & CommandBus;
+    table?: string;
+    batchSize?: number;
+    /** Safety-net poll interval; `trigger()` after commits gives low latency. */
+    intervalMs?: number;
+    logger?: Logger;
+}
+export declare class OutboxRelay {
+    private readonly options;
+    private timer;
+    private running;
+    private rerun;
+    private readonly logger;
+    private readonly table;
+    constructor(options: OutboxRelayOptions);
+    start(): void;
+    stop(): void;
+    /** Publishes pending rows now. Concurrent triggers coalesce into one follow-up run. */
+    trigger(): Promise<void>;
+    /** One batch. Returns how many rows were published. */
+    flush(): Promise<number>;
+    /**
+     * Logged on the 1st, 2nd, 4th, 8th… failure of a row (the attempt count before this one is in `attempts`),
+     * so a queue that stays missing for hours is still visible without a line every tick.
+     */
+    private reportUnroutable;
+    /** Deletes published rows older than `olderThanDays`. */
+    prune(olderThanDays?: number): Promise<number>;
+}
+//# sourceMappingURL=outbox.d.ts.map

package/dist/types/messaging/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../../src/messaging/outbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAqB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAA+B,MAAM,gBAAgB,CAAC;AAEhH,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAI7C,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,EAAE,IAAI,GAAE,UAAoB,GAAG,MAAM,CAE1G;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5J;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IAOV,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEF,OAAO,EAAE,kBAAkB;IAKxD,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;IAKZ,uFAAuF;IACjF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,uDAAuD;IACjD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAwC9B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB,yDAAyD;IACnD,KAAK,CAAC,aAAa,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;CAIhD"}

package/dist/types/messaging/publisher.d.ts

@@ -0,0 +1,84 @@
+import { ServiceUnavailableError } from '../common/errors.js';
+import type { EventEnvelope, Logger } from '../types/index.js';
+import type { AmqpConnection } from './connection.js';
+import { type EnvelopeMeta } from './envelope.js';
+import type { Topology } from './topology.js';
+/**
+ * The broker accepted a `mandatory` message but no queue was bound to receive it (the consumer has never
+ * started, or its binding is wrong). Retryable: the message is not lost — the caller (or the outbox relay)
+ * keeps it and tries again, and it goes through once the owner declares its queue.
+ */
+export declare class UnroutableMessageError extends ServiceUnavailableError {
+    readonly exchange: string;
+    readonly routingKey: string;
+    constructor(exchange: string, routingKey: string);
+}
+export declare function isUnroutableError(error: unknown): error is UnroutableMessageError;
+/** Publishes domain events (fan-out to any interested consumer). */
+export interface EventBus {
+    publish<T>(type: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    publishEnvelope(envelope: EventEnvelope): Promise<void>;
+}
+/** Sends a command to the single service that owns it (e.g. `email:send`). */
+export interface CommandBus {
+    send<T>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    /** Sends a pre-built command envelope (outbox relay). `envelope.type` is the command name. */
+    sendEnvelope(envelope: EventEnvelope): Promise<void>;
+}
+export interface QueueSendOptions {
+    /** Defaults to a new ULID. */
+    messageId?: string;
+    correlationId?: string;
+}
+/** Sends a plain JSON payload straight to a named queue, for a consumer outside the shared topology. */
+export interface QueueSender {
+    sendToQueue(queue: string, payload: unknown, options?: QueueSendOptions): Promise<void>;
+}
+export interface PublisherOptions {
+    connection: AmqpConnection;
+    topology: Topology;
+    /** Service name stamped into every envelope's `source`. */
+    source: string;
+    logger?: Logger;
+}
+/**
+ * Event and command publisher on a confirm channel: `publish()` resolves only once the broker
+ * has persisted the message, and rejects with 503 when the broker is unreachable so callers
+ * (or the outbox relay) can retry.
+ *
+ * Commands and direct queue sends are `mandatory`: a command has exactly one owner, so one that no
+ * queue receives is a fault, not a no-op. The broker returns it (`basic.return`, always before its
+ * confirm), and the send rejects with `UnroutableMessageError` instead of resolving as if delivered.
+ * Events stay non-mandatory: a topic event with no subscriber yet is normal fan-out.
+ */
+export declare class MessagePublisher implements EventBus, CommandBus, QueueSender {
+    private readonly options;
+    private handle;
+    private readonly logger;
+    /** Message ids the broker returned as unroutable, awaiting their confirm. */
+    private readonly returned;
+    constructor(options: PublisherOptions);
+    init(): Promise<void>;
+    publish<T>(type: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    publishEnvelope(envelope: EventEnvelope): Promise<void>;
+    send<T>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    sendEnvelope(envelope: EventEnvelope): Promise<void>;
+    /**
+     * Sends `payload` as-is (no envelope) to `queue` through the default exchange. The queue is the
+     * consumer's to declare, so it is not asserted here; a missing queue rejects as unroutable.
+     */
+    sendToQueue(queue: string, payload: unknown, options?: QueueSendOptions): Promise<void>;
+    private write;
+}
+/** Stand-in when messaging is disabled (local tooling, tests): logs and drops. */
+export declare class NoopMessageBus implements EventBus, CommandBus, QueueSender {
+    private readonly source;
+    private readonly logger;
+    constructor(source: string, logger?: Logger);
+    publish<T>(type: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    publishEnvelope(envelope: EventEnvelope): Promise<void>;
+    send<T>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    sendEnvelope(envelope: EventEnvelope): Promise<void>;
+    sendToQueue(queue: string): Promise<void>;
+}
+//# sourceMappingURL=publisher.d.ts.map

package/dist/types/messaging/publisher.d.ts.map

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

package/dist/types/messaging/rpc.d.ts

@@ -0,0 +1,46 @@
+import type { Logger } from '../types/index.js';
+import type { AmqpConnection } from './connection.js';
+import type { Topology } from './topology.js';
+export interface RpcContext {
+    correlationId?: string;
+    callerService?: string;
+}
+/**
+ * Request/response over RabbitMQ for the few synchronous cross-service calls that must fail
+ * cleanly (e.g. "create the profile before committing the account"). Uses direct reply-to, so
+ * no reply queue is declared per call, and sets the request TTL to the caller's timeout so a
+ * request the caller has given up on is never executed late.
+ */
+export declare class RpcServer {
+    private readonly connection;
+    private readonly topology;
+    private readonly handles;
+    private readonly logger;
+    constructor(connection: AmqpConnection, topology: Topology, logger?: Logger);
+    handle<P, R>(method: string, handler: (payload: P, context: RpcContext) => Promise<R>, options?: {
+        prefetch?: number;
+    }): Promise<void>;
+    private respond;
+}
+export interface RpcCaller {
+    call<P, R>(method: string, payload: P, options?: {
+        timeoutMs?: number;
+    }): Promise<R>;
+}
+export declare class RpcClient implements RpcCaller {
+    private readonly connection;
+    private readonly topology;
+    private readonly callerService;
+    private handle;
+    private readonly pending;
+    private readonly logger;
+    constructor(connection: AmqpConnection, topology: Topology, callerService: string, logger?: Logger);
+    init(): Promise<void>;
+    call<P, R>(method: string, payload: P, options?: {
+        timeoutMs?: number;
+        correlationId?: string;
+    }): Promise<R>;
+    private onReply;
+    private failAll;
+}
+//# sourceMappingURL=rpc.d.ts.map

package/dist/types/messaging/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../../src/messaging/rpc.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,iBAAiB,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C,MAAM,WAAW,UAAU;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAkB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAHlF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,UAAU,EAAE,cAAc,EAAmB,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM;IAIvG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;YAUlI,OAAO;CAiBtB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtF;AAED,qBAAa,SAAU,YAAW,SAAS;IAK7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAkB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAAY,OAAO,CAAC,QAAQ,CAAC,aAAa;IAJ5H,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0H;IAClJ,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,UAAU,EAAE,cAAc,EAAmB,QAAQ,EAAE,QAAQ,EAAmB,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAI/I,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAuBhH,OAAO,CAAC,OAAO;IAcf,OAAO,CAAC,OAAO;CAOhB"}

package/dist/types/messaging/staff-notifier.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { type DispatchChannel, type DispatchRecipient, type DispatchValue } from '../contracts/notification-dispatch.js';
+import type { Logger } from '../types/index.js';
+import type { EnvelopeMeta } from './envelope.js';
+/** The slice of a service's outbox the notifier needs; `E` is that service's transaction type. */
+export interface CommandOutbox<E> {
+    command<T>(executor: E, command: string, data: T, meta?: EnvelopeMeta): Promise<void>;
+}
+/** Who holds a permission, as staff alert recipients. Configured lists today; an auth-admin lookup later. */
+export interface StaffRecipientResolver {
+    resolve(permission: string): Promise<DispatchRecipient[]>;
+}
+/** Recipients from configuration (env), keyed by the permission an alert targets. */
+export declare class ConfiguredStaffRecipients implements StaffRecipientResolver {
+    private readonly byPermission;
+    constructor(byPermission: Readonly<Record<string, readonly DispatchRecipient[]>>);
+    resolve(permission: string): Promise<DispatchRecipient[]>;
+}
+export interface StaffAlert {
+    /** Seeded notification template slug. */
+    template: string;
+    /** The permission its recipients hold (e.g. `newsdesk.policy.manage`). */
+    permission: string;
+    /** Template variables. */
+    data: Record<string, DispatchValue>;
+    /** Defaults to email: staff addresses have no account, so the in-app feed cannot reach them. */
+    channels?: DispatchChannel[];
+}
+/** Tracing for the staged commands; the actor is always the system. */
+export type StaffAlertMeta = Pick<EnvelopeMeta, 'correlationId' | 'aggregate'>;
+/**
+ * Stages one `notification:dispatch` per recipient through the outbox, in the caller's transaction, so an
+ * alert is sent if and only if the state change that raised it commits. Never sends email itself.
+ * An alert that resolves to nobody is logged as a warning (an unconfigured list must not fail silently).
+ */
+export declare class StaffNotifier<E> {
+    private readonly outbox;
+    private readonly recipients;
+    private readonly logger;
+    constructor(outbox: CommandOutbox<E>, recipients: StaffRecipientResolver, logger?: Logger);
+    /** Returns how many commands were staged. */
+    alert(executor: E, alert: StaffAlert, meta?: StaffAlertMeta): Promise<number>;
+}
+/**
+ * A comma-separated staff address list from env (`"a@x.io, b@y.io"`): trimmed, blanks dropped,
+ * de-duplicated case-insensitively. An invalid address fails validation, so a typo is caught at boot
+ * instead of dead-lettering in notification-service when the alert finally fires.
+ */
+export declare const staffEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>, {
+    email: string;
+    name?: string | undefined;
+    userId?: string | null | undefined;
+    locale?: string | null | undefined;
+    timezone?: string | null | undefined;
+}[], string | undefined>;
+//# sourceMappingURL=staff-notifier.d.ts.map

package/dist/types/messaging/staff-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,kGAAkG;AAClG,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvF;AAED,6GAA6G;AAC7G,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CAC3D;AAED,qFAAqF;AACrF,qBAAa,yBAA0B,YAAW,sBAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC;IAE3F,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAGhE;AAED,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,WAAW,CAAC,CAAC;AAE/E;;;;GAIG;AACH,qBAAa,aAAa,CAAC,CAAC;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EAClC,MAAM,GAAE,MAAqB;IAGhD,6CAA6C;IACvC,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoBxF;AAID;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;wBAegD,CAAC"}

package/dist/types/messaging/topology.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Naming for exchanges and queues. Every name carries the environment prefix so two
+ * environments that accidentally share a vhost still cannot see each other's traffic.
+ *
+ *   events exchange   <app>.<prefix>.events     (topic)  domain events: `auth.user.registered`
+ *   commands exchange <app>.<prefix>.commands   (direct) work for one owner: `email:send`
+ *   queues            <prefix>.<name>                    e.g. `prod.notification-service:auth.events`
+ */
+export interface Topology {
+    readonly app: string;
+    readonly prefix: string;
+    readonly eventsExchange: string;
+    readonly commandsExchange: string;
+    /** Physical queue name for a logical name. */
+    queue(name: string): string;
+}
+export declare function createTopology(options: {
+    app: string;
+    prefix: string;
+}): Topology;
+export declare const retryQueueName: (queue: string, delayMs: number) => string;
+export declare const deadLetterQueueName: (queue: string) => string;
+//# sourceMappingURL=topology.d.ts.map

package/dist/types/messaging/topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/messaging/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8CAA8C;IAC9C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAWjF;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,WAAgC,CAAC;AAC9F,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,WAAmB,CAAC"}

package/dist/types/metrics/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Prometheus metrics. Re-exports prom-client so every service runs one version of it;
+ * services keep their own metric definitions behind a narrow interface.
+ */
+export { Counter, Gauge, Histogram, Registry, Summary, collectDefaultMetrics } from 'prom-client';
+export type { CounterConfiguration, GaugeConfiguration, HistogramConfiguration, SummaryConfiguration } from 'prom-client';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/metrics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/metrics/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAClG,YAAY,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/rate-limit/index.d.ts

@@ -0,0 +1,28 @@
+import type { NextFunction, Request, Response } from 'express';
+import type { Redis } from 'ioredis';
+import { type RateLimiterAbstract } from 'rate-limiter-flexible';
+import type { Logger } from '../types/index.js';
+export interface RateLimitOptions {
+    points: number;
+    durationSec: number;
+    /** Unique per limiter, e.g. `rl:auth:login-ip`. */
+    keyPrefix: string;
+    redis?: Redis | null;
+    /** Lock the key for this long once exhausted (default: none). */
+    blockDurationSec?: number;
+    logger?: Logger;
+}
+/** Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. */
+export declare function createLimiter(options: RateLimitOptions): RateLimiterAbstract;
+/**
+ * Consumes one point for `key`; throws TooManyRequestsError (429) when exhausted.
+ * For in-service checks such as per-identifier login throttling.
+ */
+export declare function consumeOrThrow(limiter: RateLimiterAbstract, key: string, message?: string): Promise<void>;
+export interface RateLimitMiddlewareOptions extends RateLimitOptions {
+    /** Default: authenticated user ID, else client IP. */
+    keyOf?: (req: Request) => string;
+}
+export declare function rateLimitMiddleware(options: RateLimitMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+export type { RateLimiterAbstract };
+//# sourceMappingURL=index.d.ts.map

package/dist/types/rate-limit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAuC,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAItG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,mBAAmB,CAW5E;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;AAED,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,sDAAsD;IACtD,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,IAKvD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAiB9E;AAED,YAAY,EAAE,mBAAmB,EAAE,CAAC"}