@heavybit/shared-lib 2.1.0 → 2.7.0

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

@@ -2,7 +2,7 @@ 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';
+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)
@@ -13,72 +13,105 @@ export declare class UnroutableMessageError extends ServiceUnavailableError {
     readonly routingKey: string;
     constructor(exchange: string, routingKey: string);
 }
+/** True when `error` is an {@link UnroutableMessageError} (retryable; the target queue is missing). */
 export declare function isUnroutableError(error: unknown): error is UnroutableMessageError;
+/** Transport options for sending a pre-built envelope. */
+export interface SendOptions {
+    /** Sent as `x-correlation-id`; defaults to the active request context's. */
+    correlationId?: string;
+}
 /** 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>;
+    /** Builds the envelope (see `buildEnvelope`) and publishes it on the events exchange. */
+    publish<T extends object>(routingKey: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    /** Publishes a pre-built envelope (outbox relay). */
+    publishEnvelope(envelope: EventEnvelope, options?: SendOptions): Promise<void>;
 }
-/** Sends a command to the single service that owns it (e.g. `email:send`). */
+/** Sends a command to the single service that owns it (e.g. `mail: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>;
+    send<T extends object>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    /** Sends a pre-built command envelope (outbox relay). `envelope.routingKey` is the command name. */
+    sendEnvelope(envelope: EventEnvelope, options?: SendOptions): Promise<void>;
 }
-export interface QueueSendOptions {
+/** Options for direct queue sends and delayed sends. */
+export interface QueueSendOptions extends SendOptions {
     /** 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>;
 }
+/** Delivers a payload to a queue after a delay (MSG-4). */
+export interface DelayedSender {
+    /**
+     * @param queue Physical target queue (declared by its consumer).
+     * @param payload JSON body, delivered as-is.
+     * @param delayMs Delay in milliseconds (1 … {@link MAX_DELAY_MS}).
+     */
+    scheduleDelayed(queue: string, payload: unknown, delayMs: number, options?: QueueSendOptions): Promise<void>;
+}
+/** Largest delay `scheduleDelayed` accepts (AMQP per-message TTL is a 32-bit value). */
+export declare const MAX_DELAY_MS: number;
+/** Dependencies for {@link MessagePublisher}. */
 export interface PublisherOptions {
     connection: AmqpConnection;
     topology: Topology;
-    /** Service name stamped into every envelope's `source`. */
+    /** Service name, sent as the AMQP `appId`. */
     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.
+ * (or the outbox relay) can retry. Every message is persistent JSON with `messageId` = event id and the
+ * correlation id in the `x-correlation-id` header.
  *
  * 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 {
+export declare class MessagePublisher implements EventBus, CommandBus, QueueSender, DelayedSender {
     private readonly options;
     private handle;
     private readonly logger;
     /** Message ids the broker returned as unroutable, awaiting their confirm. */
     private readonly returned;
+    /** Delay queues already declared, per live channel (a reconnect gets a new channel). */
+    private readonly declaredDelayQueues;
     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>;
+    publish<T extends object>(routingKey: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    publishEnvelope(envelope: EventEnvelope, options?: SendOptions): Promise<void>;
+    send<T extends object>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    sendEnvelope(envelope: EventEnvelope, options?: SendOptions): 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>;
+    /**
+     * Parks `payload` in a delay queue with a per-message TTL; when it expires the broker dead-letters it
+     * into `queue` (MSG-4). Delay queues are bucketed by power of two (see `delayQueueName`). The target
+     * queue must exist when the TTL fires, or the broker drops the message.
+     *
+     * @throws RangeError when `delayMs` is not an integer in 1 … {@link MAX_DELAY_MS}.
+     */
+    scheduleDelayed(queue: string, payload: unknown, delayMs: number, options?: QueueSendOptions): Promise<void>;
+    private declareDelayQueue;
+    private channel;
     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;
+export declare class NoopMessageBus implements EventBus, CommandBus, QueueSender, DelayedSender {
     private readonly logger;
-    constructor(source: string, logger?: Logger);
-    publish<T>(type: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    constructor(logger?: Logger);
+    publish<T extends object>(routingKey: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
     publishEnvelope(envelope: EventEnvelope): Promise<void>;
-    send<T>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
+    send<T extends object>(command: string, data: T, meta?: EnvelopeMeta): Promise<EventEnvelope<T>>;
     sendEnvelope(envelope: EventEnvelope): Promise<void>;
     sendToQueue(queue: string): Promise<void>;
+    scheduleDelayed(queue: string, _payload: unknown, delayMs: number): Promise<void>;
 }
 //# sourceMappingURL=publisher.d.ts.map

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

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

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

@@ -11,20 +11,20 @@ import type { StaffRecipientResolver } from './staff-recipients.js';
  * The slice of a service's outbox the notifier needs.
  *
  * @typeParam E The service's transaction/executor type.
- * @example const outbox: CommandOutbox<Tx> = { command: (tx, name, data, meta) => outboxRepo.stageCommand(tx, name, data, meta) };
+ * @example const outbox: CommandOutbox<DbExecutor> = { command: (tx, name, data, meta) => enqueueOutbox(tx, name, data, { ...meta, exchange: 'commands' }).then(() => undefined) };
  */
 export interface CommandOutbox<E> {
-    command<T>(executor: E, command: string, data: T, meta?: EnvelopeMeta): Promise<void>;
+    command<T extends object>(executor: E, command: string, data: T, meta?: EnvelopeMeta): Promise<void>;
 }
 /**
  * One operational alert to the staff who hold a permission.
  *
- * @example { template: 'payout-failed', permission: 'payouts.manage', data: { reference: 'PO-1' } }
+ * @example { template: 'job-failed', permission: 'jobs.manage', data: { reference: 'J-1' } }
  */
 export interface StaffAlert<Ch extends string = string> {
     /** Seeded notification template slug. */
     template: string;
-    /** The permission its recipients hold (e.g. `orders.manage`). */
+    /** The permission its recipients hold (e.g. `reports.manage`). */
     permission: string;
     /** Template variables. */
     data: Record<string, DispatchValue>;
@@ -34,9 +34,9 @@ export interface StaffAlert<Ch extends string = string> {
 /**
  * Tracing for the staged commands; the actor is always the system.
  *
- * @example { correlationId: correlationId(req), aggregate: { type: 'payout', id: payout.id } }
+ * @example { correlationId: correlationId(req) }
  */
-export type StaffAlertMeta = Pick<EnvelopeMeta, 'correlationId' | 'aggregate'>;
+export type StaffAlertMeta = Pick<EnvelopeMeta, 'correlationId'>;
 /**
  * How the notifier stages commands. All app vocabulary is passed in; nothing is assumed.
  *
@@ -62,9 +62,9 @@ export interface StaffNotifierOptions<C extends string, Ch extends string> {
  * @typeParam C The app's dispatch categories.
  * @typeParam Ch The app's dispatch channels.
  * @example
- * const notifier = new StaffNotifier(outbox, new ConfiguredStaffRecipients({ 'payouts.manage': config.financeEmails }),
+ * const notifier = new StaffNotifier(outbox, new ConfiguredStaffRecipients({ 'jobs.manage': config.opsEmails }),
  *   { category: 'staff', defaultChannels: ['email'], logger });
- * await notifier.alert(tx, { template: 'payout-failed', permission: 'payouts.manage', data: { reference } }, { correlationId });
+ * await notifier.alert(tx, { template: 'job-failed', permission: 'jobs.manage', data: { reference } }, { correlationId });
  */
 export declare class StaffNotifier<E, C extends string = string, Ch extends string = string> {
     private readonly outbox;
@@ -79,7 +79,7 @@ export declare class StaffNotifier<E, C extends string = string, Ch extends stri
      *
      * @param executor The caller's open transaction; the commands commit or roll back with it.
      * @param alert Template, permission, variables and optional channels.
-     * @param meta Correlation id and aggregate for tracing; the actor is always the system.
+     * @param meta Correlation id for tracing; the actor is always the system.
      * @returns How many commands were staged (0 when nobody is configured).
      */
     alert(executor: E, alert: StaffAlert<Ch>, meta?: StaffAlertMeta): Promise<number>;

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

@@ -1 +1 @@
-{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,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;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;;;;GAKG;AACH,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;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACpD,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,GAAG,WAAW,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM;IACvE,yEAAyE;IACzE,QAAQ,EAAE,CAAC,CAAC;IACZ,iHAAiH;IACjH,eAAe,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IAO/E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAP7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EACnD,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,EAAE,CAAC;IAQtC;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoB5F"}
+{"version":3,"file":"staff-notifier.d.ts","sourceRoot":"","sources":["../../../src/messaging/staff-notifier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAEL,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;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtG;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACpD,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM;IACvE,yEAAyE;IACzE,QAAQ,EAAE,CAAC,CAAC;IACZ,iHAAiH;IACjH,eAAe,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,SAAS,MAAM,GAAG,MAAM;IAO/E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAP7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,UAAU,EAAE,sBAAsB,EACnD,OAAO,EAAE,oBAAoB,CAAC,CAAC,EAAE,EAAE,CAAC;IAQtC;;;;;;;OAOG;IACG,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;CAoB5F"}

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

@@ -42,8 +42,8 @@ export declare class ConfiguredStaffRecipients implements StaffRecipientResolver
  */
 export declare const staffEmailListSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string[], string | undefined>, string[], string | undefined>, {
     email: string;
-    userId?: string | null | undefined;
     name?: string | undefined;
+    userId?: string | null | undefined;
     locale?: string | null | undefined;
     timezone?: string | null | undefined;
 }[], string | undefined>;

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

@@ -1,23 +1,55 @@
 /**
- * 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.
+ * Naming for exchanges and queues, all derived from the app slug and the environment prefix
+ * (`QUEUE_PREFIX`), so two environments that share a broker or vhost never 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`
+ *   events exchange   {app}.{prefix}.events            (topic)  domain events, e.g. `thing.created`
+ *   commands exchange {app}.{prefix}.commands          (direct) work for one owner, e.g. `mail:send`
+ *   dead-letter exch. {app}.{prefix}.{service}.dlx     (direct) one per service
+ *   service queues    {prefix}.{service}.{purpose}              e.g. `dev.billing.thing-events`
+ *   dead-letter queue {queue}.dlq      retry queues {queue}.retry.{ms}      delay queues {queue}.delay.{ms}
  */
 export interface Topology {
     readonly app: string;
     readonly prefix: string;
     readonly eventsExchange: string;
     readonly commandsExchange: string;
-    /** Physical queue name for a logical name. */
+    /** Physical queue name for a logical name (adds the environment prefix once). */
     queue(name: string): string;
+    /** `{prefix}.{service}.{purpose}` — the name of a service's subscription queue. */
+    queueName(service: string, purpose: string): string;
+    /** `{app}.{prefix}.{service}.dlx` — the service's dead-letter exchange. */
+    deadLetterExchange(service: string): string;
 }
-export declare function createTopology(options: {
+/** Options for {@link createTopology}; values come from config, never literals in shared code. */
+export interface TopologyOptions {
+    /** App slug (lower-case letters, digits, `-`, `_`). */
     app: string;
+    /** Environment prefix, i.e. `QUEUE_PREFIX` (lower-case letters, digits, `-`, `_`). */
     prefix: string;
-}): Topology;
+}
+/**
+ * Builds the naming scheme for one app and environment.
+ *
+ * @param options App slug and environment prefix.
+ * @returns The {@link Topology}.
+ * @throws Error when a segment is empty or has other characters.
+ * @example const topology = createTopology({ app: config.APP_SLUG, prefix: config.QUEUE_PREFIX });
+ */
+export declare function createTopology(options: TopologyOptions): Topology;
+/** Retry queue for one delay: a fixed TTL, dead-lettering back into `queue`. */
 export declare const retryQueueName: (queue: string, delayMs: number) => string;
+/** Dead-letter queue of `queue`. */
 export declare const deadLetterQueueName: (queue: string) => string;
+/** Smallest delay bucket for {@link delayQueueName}. */
+export declare const MIN_DELAY_BUCKET_MS = 1000;
+/**
+ * Delay queue for `scheduleDelayed`: one per power-of-two bucket (1s, 2s, 4s …) at or above `delayMs`.
+ * Per-message TTLs only expire at the head of a queue, so bucketing bounds how long a short delay can
+ * wait behind a longer one (at most its own bucket size).
+ *
+ * @param queue Target queue (physical name).
+ * @param delayMs Requested delay in milliseconds.
+ * @returns `{queue}.delay.{bucketMs}`.
+ */
+export declare function delayQueueName(queue: string, delayMs: number): string;
 //# sourceMappingURL=topology.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/messaging/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;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,iFAAiF;IACjF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,mFAAmF;IACnF,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,2EAA2E;IAC3E,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7C;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CAYjE;AAED,gFAAgF;AAChF,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,WAAgC,CAAC;AAC9F,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,WAAmB,CAAC;AAErE,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrE"}

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

@@ -2,27 +2,63 @@ 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';
+import { type RedisKeyspace } from '../cache/keyspace.js';
+export * from './keys.js';
+/** Inputs to {@link createLimiter}. */
 export interface RateLimitOptions {
     points: number;
     durationSec: number;
-    /** Unique per limiter, e.g. `rl:auth:login-ip`. */
-    keyPrefix: string;
+    /** The service keyspace; limiter keys read `{prefix}rl:{scope}:{key}`. */
+    keyspace: RedisKeyspace;
+    /** Limit name, unique per limiter (lower-case kebab-case), e.g. `sign-in-ip`. */
+    scope: 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. */
+/**
+ * Redis limiter with an in-memory insurance limiter so a Redis outage never blocks traffic. Its
+ * keys come from the keyspace; pass already-encoded keys (see {@link limiterKey}) to `consume`.
+ *
+ * @param options Points, window, keyspace and scope.
+ * @returns The limiter.
+ * @example const limiter = createLimiter({ keyspace: ks, scope: 'sign-in-ip', points: 10, durationSec: 60, redis });
+ */
 export declare function createLimiter(options: RateLimitOptions): RateLimiterAbstract;
+/**
+ * Encodes a raw limiter key (user id, IP …) so it cannot add segments to the limiter's Redis key.
+ *
+ * @param raw Raw identifier.
+ * @returns The encoded key part.
+ * @example limiter.consume(limiterKey(req.ip))
+ */
+export declare const limiterKey: (raw: string) => string;
 /**
  * Consumes one point for `key`; throws TooManyRequestsError (429) when exhausted.
- * For in-service checks such as per-identifier login throttling.
+ * For in-service checks such as per-identifier sign-in throttling.
+ *
+ * @param limiter Limiter from {@link createLimiter}.
+ * @param key Encoded key (see {@link limiterKey}).
+ * @param message Optional public message for the 429.
+ * @throws TooManyRequestsError when the limit is exhausted; rethrows limiter failures.
+ * @example await consumeOrThrow(limiter, limiterKey(userId));
  */
 export declare function consumeOrThrow(limiter: RateLimiterAbstract, key: string, message?: string): Promise<void>;
+/** Inputs to {@link rateLimitMiddleware}: limiter options plus the request → key function. */
 export interface RateLimitMiddlewareOptions extends RateLimitOptions {
     /** Default: authenticated user ID, else client IP. */
     keyOf?: (req: Request) => string;
 }
+/**
+ * Express middleware that consumes one point per request. Sets `X-RateLimit-Limit` and
+ * `X-RateLimit-Remaining`; when exhausted answers 429 `RATE_LIMITED` with `Retry-After` (seconds).
+ * Fails open: a limiter error (not a rejection) is logged and the request continues.
+ *
+ * @param options Limiter options and `keyOf` (default user id, else client IP).
+ * @returns The middleware.
+ * @example router.post('/sessions', rateLimitMiddleware({ keyspace: ks, scope: 'sign-in-ip', points: 10, durationSec: 60, redis }), handler);
+ */
 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

@@ -1 +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"}
+{"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;AAChD,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGzE,cAAc,WAAW,CAAC;AAE1B,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,EAAE,aAAa,CAAC;IACxB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,mBAAmB,CAY5E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAA4B,CAAC;AAEtE;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO/G;AAED,8FAA8F;AAC9F,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IAClE,sDAAsD;IACtD,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,IAMvD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAiB9E;AAED,YAAY,EAAE,mBAAmB,EAAE,CAAC"}

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

@@ -0,0 +1,52 @@
+import { type RedisKey, type RedisKeyspace } from '../cache/keyspace.js';
+/**
+ * Rate-limit key builder and the sliding-window limiter contract. Dependency-free (exported from the
+ * package root as well as `/rate-limit`); the consuming service implements the sliding window.
+ */
+/** Purpose segment for every rate-limit key: `{prefix}rl:{scope}:…`. */
+export declare const RATE_LIMIT_PURPOSE = "rl";
+/** What a limit counts against. At least one dimension is required; they combine in a fixed order. */
+export interface RateLimitKeyInput {
+    /** Limit name, e.g. `sign-in` (lower-case kebab-case). */
+    scope: string;
+    ip?: string;
+    userId?: string;
+    /** Normalised (trimmed, lower-cased) and always hashed — never stored in clear. */
+    email?: string;
+    /** Request host, lower-cased. */
+    host?: string;
+    /** Route template, e.g. `/sessions` (encoded, so slashes cannot add segments). */
+    route?: string;
+}
+/**
+ * Builds `{prefix}rl:{scope}[:ip:{ip}][:user:{id}][:email:{hash}][:host:{host}][:route:{route}]`.
+ *
+ * @param keyspace The service keyspace.
+ * @param input Scope plus at least one dimension.
+ * @returns The rate-limit key.
+ * @throws ConfigError when no dimension is given or the scope is invalid.
+ * @example rateLimitKey(ks, { scope: 'sign-in', ip: req.ip, email: body.email })
+ */
+export declare function rateLimitKey(keyspace: RedisKeyspace, input: RateLimitKeyInput): RedisKey;
+/** Input to one sliding-window check. */
+export interface SlidingWindowCheck {
+    /** Key from {@link rateLimitKey}. */
+    key: RedisKey;
+    /** Requests allowed per window. */
+    limit: number;
+    /** Window length in milliseconds. */
+    windowMs: number;
+    /** Clock override for tests (epoch ms). */
+    now?: number;
+}
+/** Outcome of one sliding-window check. */
+export interface SlidingWindowResult {
+    allowed: boolean;
+    /** Requests left in the current window (0 when refused). */
+    remaining: number;
+    /** Milliseconds until the next request would be allowed (0 when allowed). */
+    retryAfterMs: number;
+}
+/** Sliding-window limiter contract; implemented by the consuming service (e.g. over Redis sorted sets). */
+export type SlidingWindowLimiter = (check: SlidingWindowCheck) => Promise<SlidingWindowResult>;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/rate-limit/keys.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,QAAQ,EAAqB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3G;;;GAGG;AAEH,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAeD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,iBAAiB,GAAG,QAAQ,CAUxF;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,GAAG,EAAE,QAAQ,CAAC;IACd,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,2GAA2G;AAC3G,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC"}

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

@@ -1,6 +1,11 @@
 import type { Server as HttpServer } from 'node:http';
+import type { Redis } from 'ioredis';
 import { Server, type ServerOptions, type Socket } from 'socket.io';
+import type { RedisKeyspace } from '../cache/keyspace.js';
+import { type IdentityProtocol } from '../identity/index.js';
 import type { AuthUser, Logger } from '../types/index.js';
+import { type SocketTicketClaims, type SocketTicketKeyOptions, type SocketTicketRejection } from './ticket.js';
+export * from './ticket.js';
 export interface SocketServerOptions {
     /** Socket.IO path, e.g. `/ws/notifications` (the gateway proxies the same path). */
     path: string;
@@ -23,8 +28,87 @@ export interface SocketEmitter {
     emitToRoom(room: string, event: string, payload: unknown): void;
     close(): Promise<void>;
 }
+/** Name of the private room every connection of `userId` joins. */
 export declare const userRoom: (userId: string) => string;
+/**
+ * Creates a Socket.IO server that authenticates every connection and joins it only to server-derived rooms.
+ * The verified user is in `socket.data.identity`.
+ *
+ * @example const sockets = createSocketServer(httpServer, { path: '/ws', authenticate: gatewaySocketAuth({ secret, protocol }) });
+ */
 export declare function createSocketServer(httpServer: HttpServer, options: SocketServerOptions): SocketEmitter;
-/** Trusts the gateway-signed identity headers forwarded on the WebSocket upgrade request. */
-export declare function gatewaySocketAuth(secret: string): (socket: Socket) => AuthUser | null;
+/**
+ * Trusts the gateway-signed (v2) identity headers forwarded on the WebSocket upgrade request. The gateway
+ * signs the upgrade as `GET <handshake path>` (query ignored).
+ *
+ * @param options The shared secret (at least 32 characters) and the app's identity protocol.
+ * @returns An `authenticate` function for {@link createSocketServer}.
+ * @example createSocketServer(server, { path: '/ws', authenticate: gatewaySocketAuth({ secret, protocol }) });
+ */
+export declare function gatewaySocketAuth(options: {
+    secret: string;
+    protocol: IdentityProtocol;
+}): (socket: Socket) => AuthUser | null;
+/** Why a ticket handshake was refused: a ticket problem, an origin problem or a replayed ticket. */
+export type SocketRejectionReason = SocketTicketRejection | 'origin_not_allowed' | 'replayed';
+/** Passed to `onRejected` so the service can log it and publish its security event. */
+export interface SocketRejection {
+    reason: SocketRejectionReason;
+    /** Known once the ticket verified (origin and replay rejections). */
+    userId: string | null;
+    /** The Socket.IO path that was refused. */
+    path: string;
+    origin: string | null;
+}
+/** Settings for {@link createTicketHandshake}. */
+export interface TicketHandshakeOptions extends SocketTicketKeyOptions {
+    /** Ticket audience(s) this server accepts. */
+    audience: string | readonly string[];
+    /** Browser origins allowed for this ticket holder (e.g. the app's origins, or a tenant's own domain). */
+    allowedOrigins: (claims: SocketTicketClaims) => readonly string[] | Promise<readonly string[]>;
+    /** Accept handshakes without an `Origin` header (non-browser clients). Default false. */
+    allowMissingOrigin?: boolean;
+    /** Returns false when the ticket id was already used (makes tickets single-use). */
+    isFirstUse?: (claims: SocketTicketClaims) => Promise<boolean>;
+    /** Called for every refused handshake. Must not throw. */
+    onRejected?: (rejection: SocketRejection) => void;
+    /** Socket.IO path, reported in rejections. */
+    path: string;
+}
+/**
+ * The handshake check on its own (testable without a server): verifies the ticket from
+ * `socket.handshake.auth.ticket`, then the browser origin against `allowedOrigins(claims)`, then
+ * single use.
+ *
+ * @param options Ticket keys, audience, origin rule, replay check and rejection hook.
+ * @returns `authenticate(socket)` resolving to the claims, or null when refused.
+ */
+export declare function createTicketHandshake(options: TicketHandshakeOptions): (socket: Pick<Socket, 'handshake'>) => Promise<SocketTicketClaims | null>;
+/** Settings for {@link createTicketSocketServer}. */
+export interface TicketSocketServerOptions extends Omit<TicketHandshakeOptions, 'isFirstUse'> {
+    httpServer: HttpServer;
+    /**
+     * Shared Redis: enables the `@socket.io/redis-adapter` fan-out across replicas (channel prefix from
+     * `keyspace`) and makes tickets single-use (`{keyspace}socket-ticket:{jti}`, TTL = ticket lifetime).
+     * Omit only for a single in-process instance (tests, local tools).
+     */
+    redis?: Redis;
+    /** The service's keyspace; required with `redis`. */
+    keyspace?: RedisKeyspace;
+    /** Extra rooms to join on connect, derived from the verified claims. `user:{userId}` is always joined. */
+    rooms?: (claims: SocketTicketClaims) => string[];
+    serverOptions?: Partial<ServerOptions>;
+    logger?: Logger;
+}
+/**
+ * Creates a Socket.IO server whose clients authenticate with a short-lived ticket
+ * (`io(url, { path, auth: (cb) => getTicket().then((ticket) => cb({ ticket })) })`). Each connection
+ * auto-joins `user:{userId}`; the verified claims are in `socket.data.identity` for later room checks
+ * with `canJoinScopeRoom`.
+ *
+ * @param options HTTP server, path, ticket keys, origin rule, Redis + keyspace, rejection hook.
+ * @returns The emitter.
+ * @example createTicketSocketServer({ httpServer, path: '/ws', secret, domain, audience: 'admin-app', redis, keyspace, allowedOrigins: () => origins, onRejected })
+ */
+export declare function createTicketSocketServer(options: TicketSocketServerOptions): SocketEmitter;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,oFAAoF;IACpF,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC7E;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC;IACrC,oEAAoE;IACpE,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,eAAO,MAAM,QAAQ,GAAI,QAAQ,MAAM,WAAqB,CAAC;AAE7D,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAmCtG;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,IACtC,QAAQ,MAAM,KAAG,QAAQ,GAAG,IAAI,CAIzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"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"}