@drarzter/kafka-client 0.1.7 → 0.1.9

package/README.md

@@ -13,6 +13,7 @@ An opinionated wrapper around kafkajs that integrates with NestJS as a DynamicMo
 ## Why?
 
 - **Typed topics** — you define a map of topic -> message shape, and the compiler won't let you send wrong data to wrong topic
+- **Topic descriptors** — `topic()` DX sugar lets you define topics as standalone typed objects instead of string keys
 - **NestJS-native** — `register()` / `registerAsync()`, DI injection, lifecycle hooks out of the box
 - **Idempotent producer** — `acks: -1`, `idempotent: true` by default
 - **Retry + DLQ** — configurable retries with backoff, dead letter queue for failed messages
@@ -21,6 +22,8 @@ An opinionated wrapper around kafkajs that integrates with NestJS as a DynamicMo
 - **Custom headers** — attach metadata headers to messages
 - **Transactions** — exactly-once semantics with `producer.transaction()`
 - **Consumer interceptors** — before/after/onError hooks for message processing
+- **Auto-create topics** — `autoCreateTopics: true` for dev mode — no need to pre-create topics
+- **Error classes** — `KafkaProcessingError` and `KafkaRetryExhaustedError` with topic, message, and attempt metadata
 - **Health check** — built-in health indicator for monitoring
 - **Multiple consumer groups** — named clients for different bounded contexts
 - **Declarative & imperative** — use `@SubscribeTo()` decorator or `startConsumer()` directly
@@ -126,6 +129,48 @@ export type OrdersTopicMap = {
 };
 ```
 
+#### Alternative: `topic()` descriptors
+
+Instead of a centralized topic map, define each topic as a standalone typed object:
+
+```typescript
+import { topic, TopicsFrom } from '@drarzter/kafka-client';
+
+export const OrderCreated = topic('order.created')<{
+  orderId: string;
+  userId: string;
+  amount: number;
+}>();
+
+export const OrderCompleted = topic('order.completed')<{
+  orderId: string;
+  completedAt: string;
+}>();
+
+// Combine into a topic map for KafkaModule generics
+export type OrdersTopicMap = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+```
+
+Topic descriptors work everywhere strings work — `sendMessage`, `sendBatch`, `transaction`, `startConsumer`, and `@SubscribeTo()`:
+
+```typescript
+// Sending
+await kafka.sendMessage(OrderCreated, { orderId: '123', userId: '456', amount: 100 });
+await kafka.sendBatch(OrderCreated, [{ value: { orderId: '1', userId: '10', amount: 50 } }]);
+
+// Transactions
+await kafka.transaction(async (tx) => {
+  await tx.send(OrderCreated, { orderId: '123', userId: '456', amount: 100 });
+});
+
+// Consuming (decorator)
+@SubscribeTo(OrderCreated)
+async handleOrder(message: OrdersTopicMap['order.created']) { ... }
+
+// Consuming (imperative)
+await kafka.startConsumer([OrderCreated], handler);
+```
+
 ### 2. Register the module
 
 ```typescript
@@ -138,12 +183,15 @@ import { OrdersTopicMap } from './orders.types';
       clientId: 'my-service',
       groupId: 'my-consumer-group',
       brokers: ['localhost:9092'],
+      autoCreateTopics: true, // auto-create topics on first use (dev mode)
     }),
   ],
 })
 export class OrdersModule {}
 ```
 
+`autoCreateTopics` calls `admin.createTopics()` (idempotent — no-op if topic already exists) before the first send/consume for each topic. Useful in development, not recommended for production.
+
 Or with `ConfigService`:
 
 ```typescript
@@ -416,6 +464,50 @@ Multiple interceptors run in order. All hooks are optional.
 | `dlq` | `false` | Send to `{topic}.dlq` after all retries exhausted |
 | `interceptors` | `[]` | Array of before/after/onError hooks |
 
+### Module options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `clientId` | — | Kafka client identifier |
+| `groupId` | — | Consumer group ID |
+| `brokers` | — | Array of broker addresses |
+| `name` | — | Named client for multi-group setups |
+| `isGlobal` | `false` | Make the client available in all modules |
+| `autoCreateTopics` | `false` | Auto-create topics on first send/consume |
+
+## Error classes
+
+When a consumer message handler fails after all retries, the library throws typed error objects:
+
+```typescript
+import { KafkaProcessingError, KafkaRetryExhaustedError } from '@drarzter/kafka-client';
+```
+
+**`KafkaProcessingError`** — base class for processing failures. Has `topic`, `originalMessage`, and supports `cause`:
+
+```typescript
+const err = new KafkaProcessingError('handler failed', 'order.created', rawMessage, { cause: originalError });
+err.topic;            // 'order.created'
+err.originalMessage;  // the parsed message object
+err.cause;            // the original error
+```
+
+**`KafkaRetryExhaustedError`** — thrown after all retries are exhausted. Extends `KafkaProcessingError` and adds `attempts`:
+
+```typescript
+// In an onError interceptor:
+const interceptor: ConsumerInterceptor<MyTopics> = {
+  onError: (message, topic, error) => {
+    if (error instanceof KafkaRetryExhaustedError) {
+      console.log(`Failed after ${error.attempts} attempts on ${error.topic}`);
+      console.log('Last error:', error.cause);
+    }
+  },
+};
+```
+
+When `retry.maxRetries` is set and all attempts fail, `KafkaRetryExhaustedError` is passed to `onError` interceptors automatically.
+
 ## Health check
 
 Monitor Kafka connectivity with the built-in health indicator:
@@ -464,7 +556,7 @@ Both suites run in CI on every push to `main`.
 
 ```
 src/
-├── client/         # KafkaClient, types, interfaces
+├── client/         # KafkaClient, types, topic(), error classes
 ├── module/         # KafkaModule, KafkaExplorer, DI constants
 ├── decorators/     # @InjectKafkaClient(), @SubscribeTo()
 ├── health/         # KafkaHealthIndicator

package/dist/index.d.mts

@@ -1,6 +1,50 @@
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 
+/**
+ * A typed topic descriptor that pairs a topic name with its message type.
+ * Created via the `topic()` factory function.
+ *
+ * @typeParam N - The literal topic name string.
+ * @typeParam M - The message payload type for this topic.
+ */
+interface TopicDescriptor<N extends string = string, M extends Record<string, any> = Record<string, any>> {
+    readonly __topic: N;
+    /** @internal Phantom type — never has a real value at runtime. */
+    readonly __type: M;
+}
+/**
+ * Define a typed topic descriptor.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created')<{ orderId: string; amount: number }>();
+ *
+ * // Use with KafkaClient:
+ * await kafka.sendMessage(OrderCreated, { orderId: '123', amount: 100 });
+ *
+ * // Use with @SubscribeTo:
+ * @SubscribeTo(OrderCreated)
+ * async handleOrder(msg) { ... }
+ * ```
+ */
+declare function topic<N extends string>(name: N): <M extends Record<string, any>>() => TopicDescriptor<N, M>;
+/**
+ * Build a topic-message map type from a union of TopicDescriptors.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created')<{ orderId: string }>();
+ * const OrderCompleted = topic('order.completed')<{ completedAt: string }>();
+ *
+ * type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+ * // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
+ * ```
+ */
+type TopicsFrom<D extends TopicDescriptor<any, any>> = {
+    [K in D as K["__topic"]]: K["__type"];
+};
+
 /**
  * Mapping of topic names to their message types.
  * Define this interface to get type-safe publish/subscribe across your app.
@@ -74,11 +118,17 @@ interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap
 /** Context passed to the `transaction()` callback with type-safe send methods. */
 interface TransactionContext<T extends TopicMapConstraint<T>> {
     send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<{
         value: T[K];
         key?: string;
         headers?: MessageHeaders;
     }>): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
+        value: D["__type"];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
 }
 /** Interface describing all public methods of the Kafka client. */
 interface IKafkaClient<T extends TopicMapConstraint<T>> {
@@ -86,6 +136,7 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
         topics: string[];
     }>;
     startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
     stopConsumer(): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<{
@@ -97,6 +148,12 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
     getClientId: () => ClientId;
     disconnect(): Promise<void>;
 }
+/** Options for `KafkaClient` constructor. */
+interface KafkaClientOptions {
+    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, `transaction`, or `startConsumer` for each topic. Useful for development — not recommended in production. */
+    autoCreateTopics?: boolean;
+}
+
 /**
  * Type-safe Kafka client for NestJS.
  * Wraps kafkajs with JSON serialization, retries, DLQ, transactions, and interceptors.
@@ -109,13 +166,22 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly consumer;
     private readonly admin;
     private readonly logger;
-    private isConsumerRunning;
+    private readonly autoCreateTopicsEnabled;
+    private readonly ensuredTopics;
     private isAdminConnected;
     readonly clientId: ClientId;
-    constructor(clientId: ClientId, groupId: GroupId, brokers: string[]);
-    /** Send a single typed message to a topic. */
+    constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
+    private resolveTopicName;
+    private ensureTopic;
+    /** Send a single typed message. Accepts a topic key or a TopicDescriptor. */
+    sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
-    /** Send multiple typed messages to a topic in one call. */
+    /** Send multiple typed messages in one call. Accepts a topic key or a TopicDescriptor. */
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
+        value: D["__type"];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<{
         value: T[K];
         key?: string;
@@ -128,6 +194,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     disconnectProducer(): Promise<void>;
     /** Subscribe to topics and start consuming messages with the given handler. */
     startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
     stopConsumer(): Promise<void>;
     /** Check broker connectivity and return available topics. */
     checkStatus(): Promise<{
@@ -136,6 +203,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     getClientId(): ClientId;
     /** Gracefully disconnect producer, consumer, and admin. */
     disconnect(): Promise<void>;
+    private processMessage;
     private sendToDlq;
     private sleep;
 }
@@ -152,12 +220,16 @@ interface KafkaModuleOptions {
     brokers: string[];
     /** If true, makes KAFKA_CLIENT available globally without importing KafkaModule in every feature module. */
     isGlobal?: boolean;
+    /** Auto-create topics via admin on first use (send/consume). Useful for development. */
+    autoCreateTopics?: boolean;
 }
 /** Async configuration for `KafkaModule.registerAsync()` with dependency injection. */
 interface KafkaModuleAsyncOptions {
     name?: string;
     /** If true, makes KAFKA_CLIENT available globally without importing KafkaModule in every feature module. */
     isGlobal?: boolean;
+    /** Auto-create topics via admin on first use (send/consume). Useful for development. */
+    autoCreateTopics?: boolean;
     imports?: any[];
     useFactory: (...args: any[]) => KafkaModuleOptions | Promise<KafkaModuleOptions>;
     inject?: any[];
@@ -173,6 +245,23 @@ declare class KafkaModule {
     static registerAsync<T extends TopicMapConstraint<T>>(asyncOptions: KafkaModuleAsyncOptions): DynamicModule;
 }
 
+/** Error thrown when a consumer message handler fails. */
+declare class KafkaProcessingError extends Error {
+    readonly topic: string;
+    readonly originalMessage: unknown;
+    readonly cause?: Error;
+    constructor(message: string, topic: string, originalMessage: unknown, options?: {
+        cause?: Error;
+    });
+}
+/** Error thrown when all retry attempts are exhausted for a message. */
+declare class KafkaRetryExhaustedError extends KafkaProcessingError {
+    readonly attempts: number;
+    constructor(topic: string, originalMessage: unknown, attempts: number, options?: {
+        cause?: Error;
+    });
+}
+
 /** Default DI token for the Kafka client. */
 declare const KAFKA_CLIENT = "KAFKA_CLIENT";
 /** Returns the DI token for a named (or default) Kafka client instance. */
@@ -190,7 +279,7 @@ declare const InjectKafkaClient: (name?: string) => ParameterDecorator;
  * Decorator that auto-subscribes a method to Kafka topics on module init.
  * The decorated method receives `(message, topic)` for each consumed message.
  */
-declare const SubscribeTo: (topics: string | string[], options?: ConsumerOptions & {
+declare const SubscribeTo: (topics: string | string[] | TopicDescriptor | TopicDescriptor[] | (string | TopicDescriptor)[], options?: ConsumerOptions & {
     clientName?: string;
 }) => MethodDecorator;
 
@@ -215,4 +304,4 @@ declare class KafkaHealthIndicator {
     check<T extends TopicMapConstraint<T>>(client: KafkaClient<T>): Promise<KafkaHealthResult>;
 }
 
-export { type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, type KafkaSubscriberMetadata, type MessageHeaders, type RetryOptions, type SendOptions, SubscribeTo, type TTopicMessageMap, type TopicMapConstraint, type TransactionContext, getKafkaClientToken };
+export { type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, type KafkaClientOptions, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, KafkaProcessingError, KafkaRetryExhaustedError, type KafkaSubscriberMetadata, type MessageHeaders, type RetryOptions, type SendOptions, SubscribeTo, type TTopicMessageMap, type TopicDescriptor, type TopicMapConstraint, type TopicsFrom, type TransactionContext, getKafkaClientToken, topic };

package/dist/index.d.ts

@@ -1,6 +1,50 @@
 import { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService, ModuleRef } from '@nestjs/core';
 
+/**
+ * A typed topic descriptor that pairs a topic name with its message type.
+ * Created via the `topic()` factory function.
+ *
+ * @typeParam N - The literal topic name string.
+ * @typeParam M - The message payload type for this topic.
+ */
+interface TopicDescriptor<N extends string = string, M extends Record<string, any> = Record<string, any>> {
+    readonly __topic: N;
+    /** @internal Phantom type — never has a real value at runtime. */
+    readonly __type: M;
+}
+/**
+ * Define a typed topic descriptor.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created')<{ orderId: string; amount: number }>();
+ *
+ * // Use with KafkaClient:
+ * await kafka.sendMessage(OrderCreated, { orderId: '123', amount: 100 });
+ *
+ * // Use with @SubscribeTo:
+ * @SubscribeTo(OrderCreated)
+ * async handleOrder(msg) { ... }
+ * ```
+ */
+declare function topic<N extends string>(name: N): <M extends Record<string, any>>() => TopicDescriptor<N, M>;
+/**
+ * Build a topic-message map type from a union of TopicDescriptors.
+ *
+ * @example
+ * ```ts
+ * const OrderCreated = topic('order.created')<{ orderId: string }>();
+ * const OrderCompleted = topic('order.completed')<{ completedAt: string }>();
+ *
+ * type MyTopics = TopicsFrom<typeof OrderCreated | typeof OrderCompleted>;
+ * // { 'order.created': { orderId: string }; 'order.completed': { completedAt: string } }
+ * ```
+ */
+type TopicsFrom<D extends TopicDescriptor<any, any>> = {
+    [K in D as K["__topic"]]: K["__type"];
+};
+
 /**
  * Mapping of topic names to their message types.
  * Define this interface to get type-safe publish/subscribe across your app.
@@ -74,11 +118,17 @@ interface ConsumerInterceptor<T extends TopicMapConstraint<T> = TTopicMessageMap
 /** Context passed to the `transaction()` callback with type-safe send methods. */
 interface TransactionContext<T extends TopicMapConstraint<T>> {
     send<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
+    send<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<{
         value: T[K];
         key?: string;
         headers?: MessageHeaders;
     }>): Promise<void>;
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
+        value: D["__type"];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
 }
 /** Interface describing all public methods of the Kafka client. */
 interface IKafkaClient<T extends TopicMapConstraint<T>> {
@@ -86,6 +136,7 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
         topics: string[];
     }>;
     startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
     stopConsumer(): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<{
@@ -97,6 +148,12 @@ interface IKafkaClient<T extends TopicMapConstraint<T>> {
     getClientId: () => ClientId;
     disconnect(): Promise<void>;
 }
+/** Options for `KafkaClient` constructor. */
+interface KafkaClientOptions {
+    /** Auto-create topics via admin before the first `sendMessage`, `sendBatch`, `transaction`, or `startConsumer` for each topic. Useful for development — not recommended in production. */
+    autoCreateTopics?: boolean;
+}
+
 /**
  * Type-safe Kafka client for NestJS.
  * Wraps kafkajs with JSON serialization, retries, DLQ, transactions, and interceptors.
@@ -109,13 +166,22 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     private readonly consumer;
     private readonly admin;
     private readonly logger;
-    private isConsumerRunning;
+    private readonly autoCreateTopicsEnabled;
+    private readonly ensuredTopics;
     private isAdminConnected;
     readonly clientId: ClientId;
-    constructor(clientId: ClientId, groupId: GroupId, brokers: string[]);
-    /** Send a single typed message to a topic. */
+    constructor(clientId: ClientId, groupId: GroupId, brokers: string[], options?: KafkaClientOptions);
+    private resolveTopicName;
+    private ensureTopic;
+    /** Send a single typed message. Accepts a topic key or a TopicDescriptor. */
+    sendMessage<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, message: D["__type"], options?: SendOptions): Promise<void>;
     sendMessage<K extends keyof T>(topic: K, message: T[K], options?: SendOptions): Promise<void>;
-    /** Send multiple typed messages to a topic in one call. */
+    /** Send multiple typed messages in one call. Accepts a topic key or a TopicDescriptor. */
+    sendBatch<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(descriptor: D, messages: Array<{
+        value: D["__type"];
+        key?: string;
+        headers?: MessageHeaders;
+    }>): Promise<void>;
     sendBatch<K extends keyof T>(topic: K, messages: Array<{
         value: T[K];
         key?: string;
@@ -128,6 +194,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     disconnectProducer(): Promise<void>;
     /** Subscribe to topics and start consuming messages with the given handler. */
     startConsumer<K extends Array<keyof T>>(topics: K, handleMessage: (message: T[K[number]], topic: K[number]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
+    startConsumer<D extends TopicDescriptor<string & keyof T, T[string & keyof T]>>(topics: D[], handleMessage: (message: D["__type"], topic: D["__topic"]) => Promise<void>, options?: ConsumerOptions<T>): Promise<void>;
     stopConsumer(): Promise<void>;
     /** Check broker connectivity and return available topics. */
     checkStatus(): Promise<{
@@ -136,6 +203,7 @@ declare class KafkaClient<T extends TopicMapConstraint<T>> implements IKafkaClie
     getClientId(): ClientId;
     /** Gracefully disconnect producer, consumer, and admin. */
     disconnect(): Promise<void>;
+    private processMessage;
     private sendToDlq;
     private sleep;
 }
@@ -152,12 +220,16 @@ interface KafkaModuleOptions {
     brokers: string[];
     /** If true, makes KAFKA_CLIENT available globally without importing KafkaModule in every feature module. */
     isGlobal?: boolean;
+    /** Auto-create topics via admin on first use (send/consume). Useful for development. */
+    autoCreateTopics?: boolean;
 }
 /** Async configuration for `KafkaModule.registerAsync()` with dependency injection. */
 interface KafkaModuleAsyncOptions {
     name?: string;
     /** If true, makes KAFKA_CLIENT available globally without importing KafkaModule in every feature module. */
     isGlobal?: boolean;
+    /** Auto-create topics via admin on first use (send/consume). Useful for development. */
+    autoCreateTopics?: boolean;
     imports?: any[];
     useFactory: (...args: any[]) => KafkaModuleOptions | Promise<KafkaModuleOptions>;
     inject?: any[];
@@ -173,6 +245,23 @@ declare class KafkaModule {
     static registerAsync<T extends TopicMapConstraint<T>>(asyncOptions: KafkaModuleAsyncOptions): DynamicModule;
 }
 
+/** Error thrown when a consumer message handler fails. */
+declare class KafkaProcessingError extends Error {
+    readonly topic: string;
+    readonly originalMessage: unknown;
+    readonly cause?: Error;
+    constructor(message: string, topic: string, originalMessage: unknown, options?: {
+        cause?: Error;
+    });
+}
+/** Error thrown when all retry attempts are exhausted for a message. */
+declare class KafkaRetryExhaustedError extends KafkaProcessingError {
+    readonly attempts: number;
+    constructor(topic: string, originalMessage: unknown, attempts: number, options?: {
+        cause?: Error;
+    });
+}
+
 /** Default DI token for the Kafka client. */
 declare const KAFKA_CLIENT = "KAFKA_CLIENT";
 /** Returns the DI token for a named (or default) Kafka client instance. */
@@ -190,7 +279,7 @@ declare const InjectKafkaClient: (name?: string) => ParameterDecorator;
  * Decorator that auto-subscribes a method to Kafka topics on module init.
  * The decorated method receives `(message, topic)` for each consumed message.
  */
-declare const SubscribeTo: (topics: string | string[], options?: ConsumerOptions & {
+declare const SubscribeTo: (topics: string | string[] | TopicDescriptor | TopicDescriptor[] | (string | TopicDescriptor)[], options?: ConsumerOptions & {
     clientName?: string;
 }) => MethodDecorator;
 
@@ -215,4 +304,4 @@ declare class KafkaHealthIndicator {
     check<T extends TopicMapConstraint<T>>(client: KafkaClient<T>): Promise<KafkaHealthResult>;
 }
 
-export { type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, type KafkaSubscriberMetadata, type MessageHeaders, type RetryOptions, type SendOptions, SubscribeTo, type TTopicMessageMap, type TopicMapConstraint, type TransactionContext, getKafkaClientToken };
+export { type ClientId, type ConsumerInterceptor, type ConsumerOptions, type GroupId, type IKafkaClient, InjectKafkaClient, KAFKA_CLIENT, KAFKA_SUBSCRIBER_METADATA, KafkaClient, type KafkaClientOptions, KafkaExplorer, KafkaHealthIndicator, type KafkaHealthResult, KafkaModule, type KafkaModuleAsyncOptions, type KafkaModuleOptions, KafkaProcessingError, KafkaRetryExhaustedError, type KafkaSubscriberMetadata, type MessageHeaders, type RetryOptions, type SendOptions, SubscribeTo, type TTopicMessageMap, type TopicDescriptor, type TopicMapConstraint, type TopicsFrom, type TransactionContext, getKafkaClientToken, topic };