@babelqueue/pulsar 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -20,7 +20,7 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *     });
  *     const consumer = new PulsarConsumer(sub, {
  *       "urn:babel:orders:created": async (env) => { ... },
- *     });
+ *     }, { subscriptionType: "Shared" }); // declare it (or pass `client` together with `topic`): see PulsarConsumerOptions
  *     await consumer.run();
  *
  * This implements §5 of the broker-bindings contract: the canonical envelope is the message
@@ -28,7 +28,12 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
  * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
  * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
- * redelivered (at-least-once) and `getRedeliveryCount()` is incremented. Per §5.2 / §5.7 the
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented — up to `maxAttempts`
+ * deliveries (default 3, ADR-0036): the message that exhausts them is written to `<queue>.dlq`
+ * (when a `deadLetterProducer` is given) or acknowledged and dropped. A body that does not decode
+ * into an envelope (including an object with no valid identity) is poison: it never reaches a
+ * handler, and with dead-lettering on it is recorded in `<queue>.dlq` in the ADR-0035 shape without
+ * retry. Per §5.2 / §5.7 the
  * consumer routes on the `bq-job` property (the body's URN is used only when the property is
  * absent or blank) and takes `attempts` from the authoritative `bq-attempts` property (the
  * body's value is used only when the property is absent or not a plain ASCII-decimal integer
@@ -37,9 +42,12 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *
  * **Version gate (§5.7 step 3).** Before the body is decoded the consumer reads the
  * `bq-schema-version` property. A missing or blank value (empty or only ASCII whitespace) changes nothing; any value other than
- * the core's supported `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) rejects the message undecoded
- * through the same path as a non-conformant envelope — `onError` (with an error naming the
- * version, and an empty envelope since nothing was decoded) and a `negativeAcknowledge`.
+ * the core's supported `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) rejects the message undecoded:
+ * `onError` (with an error naming the version, and an empty envelope since nothing was decoded),
+ * then it is settled on its first delivery (ADR-0037 decision 1) — with a `deadLetterProducer` the
+ * body, byte for byte, goes to `<queue>.dlq` and the message is acknowledged after the write (a failed
+ * write is a `negativeAcknowledge`, never an acknowledgement); without one it is acknowledged and
+ * dropped (logged). Never retried, whatever `bq-attempts`, the redelivery count or `maxAttempts` say.
  *
  * **Out-of-band headers (ADR-0028).** A `headers` carrier (e.g. a W3C `traceparent` for cross-hop
  * span linkage) rides as additional native Pulsar **message properties** beside the contract `bq-*`
@@ -79,10 +87,27 @@ interface PulsarReceivedMessage {
  * satisfies it structurally; a fake satisfies it in tests.
  */
 interface PulsarConsumerClient {
+    /**
+     * The topic the subscription reads. pulsar-client's `Consumer` has **no** such method (only its `Producer`
+     * does), so with it the topic comes from the {@link PulsarConsumerOptions.topic} option; a custom
+     * subscription wrapper may provide this to make `topic` unnecessary.
+     */
+    getTopic?(): string;
     receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
     acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
     negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
 }
+/**
+ * The subset of the Pulsar client this adapter calls to build its own retry producer. A `Client` from
+ * `pulsar-client` satisfies it structurally.
+ */
+interface PulsarClientLike {
+    createProducer(config: {
+        topic: string;
+    }): Promise<PulsarProducer>;
+}
+/** The subscription type, as pulsar-client names it (`Key_Shared` is accepted as an alias of `KeyShared`). */
+type PulsarSubscriptionType = "Exclusive" | "Shared" | "Failover" | "KeyShared" | "Key_Shared";
 /**
  * Project the envelope's contract fields onto native Pulsar message properties
  * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
@@ -153,26 +178,129 @@ interface PulsarConsumerOptions {
      * rejects with) is swallowed — it never changes how the message is handled or acknowledged.
      */
     onRoutingMismatch?: (propertyUrn: string, bodyUrn: string, envelope: IncomingEnvelope) => unknown;
+    /**
+     * The total number of deliveries a message gets, the first included (default 3; `1` = no retry;
+     * ADR-0036 decision 1). A failing handler, an unmapped URN without {@link onUnknownUrn} and a poison
+     * body with dead-lettering off are retried (`negativeAcknowledge`) while `reconciled attempts + 1`
+     * is below it; the delivery that reaches it is dead-lettered (when {@link deadLetterProducer} is
+     * set) or acknowledged and dropped. Must be an integer of at least 1.
+     */
+    maxAttempts?: number;
+    /**
+     * A producer on the dead-letter topic (by convention `<queue>.dlq`). Dead-lettering is on exactly
+     * when it is set; the SDK does not use Pulsar's native `DeadLetterPolicy`. The original message is
+     * acknowledged only after the record was sent; a failed send leaves it negatively acknowledged so
+     * it is redelivered and the write is tried again.
+     */
+    deadLetterProducer?: PulsarProducer;
+    /**
+     * A producer on the consumer's **own** topic. A retry re-publishes the message to that topic with
+     * `bq-attempts` (and the body's `attempts`) raised to the counted value and then acknowledges the
+     * original — the Go model. The count then lives in the message itself, so the bound holds on every
+     * subscription type. Optional when {@link client} is given (the consumer builds the producer itself);
+     * a failed re-publish leaves the original negatively acknowledged (never lost).
+     *
+     * Without a producer or a client a retry is a `negativeAcknowledge`, which advances the native
+     * redelivery count only on `Shared` / `Key_Shared`: on `Exclusive` / `Failover` it stays 0 and the retry
+     * would never reach `maxAttempts`, so that combination is rejected at construction (see
+     * {@link subscriptionType}).
+     */
+    retryProducer?: PulsarProducer;
+    /**
+     * The Pulsar client the consumer builds its retry producer from, lazily on the first retry, on
+     * {@link topic}. Needs `topic` (pulsar-client's `Consumer` cannot tell its topic). Ignored when
+     * {@link retryProducer} is given.
+     */
+    client?: PulsarClientLike;
+    /**
+     * The topic the retry producer is created on — the topic the consumer reads. Required together with
+     * {@link client} (a pulsar-client `Consumer` has no `getTopic()`); a subscription wrapper that provides
+     * `getTopic()` makes it optional.
+     */
+    topic?: string;
+    /**
+     * The subscription type the consumer was created with. `Exclusive` and `Failover` cannot bound a
+     * nack-driven retry (a negative acknowledgement does not advance the redelivery count there), so with
+     * `maxAttempts > 1` they require a {@link retryProducer} or a {@link client}. **Not declaring it counts as
+     * `Exclusive`** (pulsar-client's own default, and the fail-closed choice): without a `retryProducer` or a
+     * `client` the constructor throws `BabelQueueError`. Declare `"Shared"` or `"Key_Shared"` to keep the
+     * `negativeAcknowledge` retry without a producer.
+     */
+    subscriptionType?: PulsarSubscriptionType;
+    /**
+     * The queue name written to `dead_letter.original_queue` of a poison record (a decodable envelope
+     * uses its own `meta.queue`). Defaults to the {@link deadLetterProducer} topic without its `.dlq`
+     * suffix.
+     */
+    queue?: string;
+    /** Receives the "message dropped" and "dead-letter write failed" warnings (default `console.warn`). */
+    onWarn?: (message: string) => void;
 }
+/** Default total number of deliveries (ADR-0036 decision 1). */
+declare const DEFAULT_MAX_ATTEMPTS = 3;
 /**
  * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
  * handler for its URN, and acknowledges it on success. A throwing handler
  * `negativeAcknowledge`s the message — the broker redelivers it and increments
- * `getRedeliveryCount()` (at-least-once). Routing uses the `bq-job` property (body URN as the
- * fallback); `attempts` is the `bq-attempts` property (body value as the fallback) reconciled to
- * `max(.., getRedeliveryCount())` for the handler.
+ * `getRedeliveryCount()` (at-least-once; with a `retryProducer` the message is instead re-published with
+ * `bq-attempts` + 1, which also bounds `Exclusive` / `Failover` subscriptions) — until `maxAttempts` deliveries are used up; the last one is
+ * dead-lettered to `<queue>.dlq` or acknowledged and dropped (ADR-0036). Routing uses the `bq-job`
+ * property (body URN as the fallback); `attempts` is the `bq-attempts` property (body value as the
+ * fallback) reconciled to `max(.., getRedeliveryCount())` for the handler.
  */
 declare class PulsarConsumer {
     private readonly consumer;
     private readonly handlers;
     private readonly options;
+    private readonly maxAttempts;
+    private builtRetryProducer;
+    private readonly warn;
     constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /**
+     * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+     * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+     */
+    private checkRetryBound;
+    private retryTopic;
+    /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+    private resolveRetryProducer;
     /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
     poll(): Promise<number>;
     /** Poll until `signal` aborts. */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * Settle a version-gated delivery on its first delivery (ADR-0037 decision 1, broker-bindings §5.7): it is
+     * never decoded, never reaches a handler or {@link PulsarConsumerOptions.onUnknownUrn}, and is never retried,
+     * whatever `bq-attempts`, the redelivery count or `maxAttempts` say. This consumer has no unknown-URN
+     * strategy option, so it behaves as `fail`: with a {@link PulsarConsumerOptions.deadLetterProducer} the body is
+     * written to `<queue>.dlq` exactly as received (no `dead_letter` block, no re-encoding) and acknowledged only
+     * after the write; without one it is acknowledged and dropped (logged). A failed write leaves the delivery
+     * negatively acknowledged (never acknowledged, never counted as a retry): the gate rejects the redelivery
+     * again, so the write is tried again.
+     */
+    private settleVersionGated;
+    /**
+     * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+     * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+     * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+     * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+     */
+    private settle;
+    /**
+     * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+     * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+     * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+     */
+    private retry;
+    private retryMessage;
+    /**
+     * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+     * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+     */
+    private deadLetter;
+    private deadLetterMessage;
     private notifyRoutingMismatch;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, headersOf, pulsarProperties, toPulsarMessage };
+export { type BabelHandler, type BabelHandlers, DEFAULT_MAX_ATTEMPTS, type PublishOptions, type PulsarClientLike, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, type PulsarSubscriptionType, headersOf, pulsarProperties, toPulsarMessage };

package/dist/index.d.ts

@@ -20,7 +20,7 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *     });
  *     const consumer = new PulsarConsumer(sub, {
  *       "urn:babel:orders:created": async (env) => { ... },
- *     });
+ *     }, { subscriptionType: "Shared" }); // declare it (or pass `client` together with `topic`): see PulsarConsumerOptions
  *     await consumer.run();
  *
  * This implements §5 of the broker-bindings contract: the canonical envelope is the message
@@ -28,7 +28,12 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
  * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
  * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
- * redelivered (at-least-once) and `getRedeliveryCount()` is incremented. Per §5.2 / §5.7 the
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented — up to `maxAttempts`
+ * deliveries (default 3, ADR-0036): the message that exhausts them is written to `<queue>.dlq`
+ * (when a `deadLetterProducer` is given) or acknowledged and dropped. A body that does not decode
+ * into an envelope (including an object with no valid identity) is poison: it never reaches a
+ * handler, and with dead-lettering on it is recorded in `<queue>.dlq` in the ADR-0035 shape without
+ * retry. Per §5.2 / §5.7 the
  * consumer routes on the `bq-job` property (the body's URN is used only when the property is
  * absent or blank) and takes `attempts` from the authoritative `bq-attempts` property (the
  * body's value is used only when the property is absent or not a plain ASCII-decimal integer
@@ -37,9 +42,12 @@ import { Envelope, HeaderCarrier, IncomingEnvelope } from '@babelqueue/core';
  *
  * **Version gate (§5.7 step 3).** Before the body is decoded the consumer reads the
  * `bq-schema-version` property. A missing or blank value (empty or only ASCII whitespace) changes nothing; any value other than
- * the core's supported `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) rejects the message undecoded
- * through the same path as a non-conformant envelope — `onError` (with an error naming the
- * version, and an empty envelope since nothing was decoded) and a `negativeAcknowledge`.
+ * the core's supported `SCHEMA_VERSION` (`"2"`, `"x"`, `"01"`, ...) rejects the message undecoded:
+ * `onError` (with an error naming the version, and an empty envelope since nothing was decoded),
+ * then it is settled on its first delivery (ADR-0037 decision 1) — with a `deadLetterProducer` the
+ * body, byte for byte, goes to `<queue>.dlq` and the message is acknowledged after the write (a failed
+ * write is a `negativeAcknowledge`, never an acknowledgement); without one it is acknowledged and
+ * dropped (logged). Never retried, whatever `bq-attempts`, the redelivery count or `maxAttempts` say.
  *
  * **Out-of-band headers (ADR-0028).** A `headers` carrier (e.g. a W3C `traceparent` for cross-hop
  * span linkage) rides as additional native Pulsar **message properties** beside the contract `bq-*`
@@ -79,10 +87,27 @@ interface PulsarReceivedMessage {
  * satisfies it structurally; a fake satisfies it in tests.
  */
 interface PulsarConsumerClient {
+    /**
+     * The topic the subscription reads. pulsar-client's `Consumer` has **no** such method (only its `Producer`
+     * does), so with it the topic comes from the {@link PulsarConsumerOptions.topic} option; a custom
+     * subscription wrapper may provide this to make `topic` unnecessary.
+     */
+    getTopic?(): string;
     receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
     acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
     negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
 }
+/**
+ * The subset of the Pulsar client this adapter calls to build its own retry producer. A `Client` from
+ * `pulsar-client` satisfies it structurally.
+ */
+interface PulsarClientLike {
+    createProducer(config: {
+        topic: string;
+    }): Promise<PulsarProducer>;
+}
+/** The subscription type, as pulsar-client names it (`Key_Shared` is accepted as an alias of `KeyShared`). */
+type PulsarSubscriptionType = "Exclusive" | "Shared" | "Failover" | "KeyShared" | "Key_Shared";
 /**
  * Project the envelope's contract fields onto native Pulsar message properties
  * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
@@ -153,26 +178,129 @@ interface PulsarConsumerOptions {
      * rejects with) is swallowed — it never changes how the message is handled or acknowledged.
      */
     onRoutingMismatch?: (propertyUrn: string, bodyUrn: string, envelope: IncomingEnvelope) => unknown;
+    /**
+     * The total number of deliveries a message gets, the first included (default 3; `1` = no retry;
+     * ADR-0036 decision 1). A failing handler, an unmapped URN without {@link onUnknownUrn} and a poison
+     * body with dead-lettering off are retried (`negativeAcknowledge`) while `reconciled attempts + 1`
+     * is below it; the delivery that reaches it is dead-lettered (when {@link deadLetterProducer} is
+     * set) or acknowledged and dropped. Must be an integer of at least 1.
+     */
+    maxAttempts?: number;
+    /**
+     * A producer on the dead-letter topic (by convention `<queue>.dlq`). Dead-lettering is on exactly
+     * when it is set; the SDK does not use Pulsar's native `DeadLetterPolicy`. The original message is
+     * acknowledged only after the record was sent; a failed send leaves it negatively acknowledged so
+     * it is redelivered and the write is tried again.
+     */
+    deadLetterProducer?: PulsarProducer;
+    /**
+     * A producer on the consumer's **own** topic. A retry re-publishes the message to that topic with
+     * `bq-attempts` (and the body's `attempts`) raised to the counted value and then acknowledges the
+     * original — the Go model. The count then lives in the message itself, so the bound holds on every
+     * subscription type. Optional when {@link client} is given (the consumer builds the producer itself);
+     * a failed re-publish leaves the original negatively acknowledged (never lost).
+     *
+     * Without a producer or a client a retry is a `negativeAcknowledge`, which advances the native
+     * redelivery count only on `Shared` / `Key_Shared`: on `Exclusive` / `Failover` it stays 0 and the retry
+     * would never reach `maxAttempts`, so that combination is rejected at construction (see
+     * {@link subscriptionType}).
+     */
+    retryProducer?: PulsarProducer;
+    /**
+     * The Pulsar client the consumer builds its retry producer from, lazily on the first retry, on
+     * {@link topic}. Needs `topic` (pulsar-client's `Consumer` cannot tell its topic). Ignored when
+     * {@link retryProducer} is given.
+     */
+    client?: PulsarClientLike;
+    /**
+     * The topic the retry producer is created on — the topic the consumer reads. Required together with
+     * {@link client} (a pulsar-client `Consumer` has no `getTopic()`); a subscription wrapper that provides
+     * `getTopic()` makes it optional.
+     */
+    topic?: string;
+    /**
+     * The subscription type the consumer was created with. `Exclusive` and `Failover` cannot bound a
+     * nack-driven retry (a negative acknowledgement does not advance the redelivery count there), so with
+     * `maxAttempts > 1` they require a {@link retryProducer} or a {@link client}. **Not declaring it counts as
+     * `Exclusive`** (pulsar-client's own default, and the fail-closed choice): without a `retryProducer` or a
+     * `client` the constructor throws `BabelQueueError`. Declare `"Shared"` or `"Key_Shared"` to keep the
+     * `negativeAcknowledge` retry without a producer.
+     */
+    subscriptionType?: PulsarSubscriptionType;
+    /**
+     * The queue name written to `dead_letter.original_queue` of a poison record (a decodable envelope
+     * uses its own `meta.queue`). Defaults to the {@link deadLetterProducer} topic without its `.dlq`
+     * suffix.
+     */
+    queue?: string;
+    /** Receives the "message dropped" and "dead-letter write failed" warnings (default `console.warn`). */
+    onWarn?: (message: string) => void;
 }
+/** Default total number of deliveries (ADR-0036 decision 1). */
+declare const DEFAULT_MAX_ATTEMPTS = 3;
 /**
  * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
  * handler for its URN, and acknowledges it on success. A throwing handler
  * `negativeAcknowledge`s the message — the broker redelivers it and increments
- * `getRedeliveryCount()` (at-least-once). Routing uses the `bq-job` property (body URN as the
- * fallback); `attempts` is the `bq-attempts` property (body value as the fallback) reconciled to
- * `max(.., getRedeliveryCount())` for the handler.
+ * `getRedeliveryCount()` (at-least-once; with a `retryProducer` the message is instead re-published with
+ * `bq-attempts` + 1, which also bounds `Exclusive` / `Failover` subscriptions) — until `maxAttempts` deliveries are used up; the last one is
+ * dead-lettered to `<queue>.dlq` or acknowledged and dropped (ADR-0036). Routing uses the `bq-job`
+ * property (body URN as the fallback); `attempts` is the `bq-attempts` property (body value as the
+ * fallback) reconciled to `max(.., getRedeliveryCount())` for the handler.
  */
 declare class PulsarConsumer {
     private readonly consumer;
     private readonly handlers;
     private readonly options;
+    private readonly maxAttempts;
+    private builtRetryProducer;
+    private readonly warn;
     constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /**
+     * Setup check: on `Exclusive` / `Failover` (and an undeclared type) a negative acknowledgement does not advance the native
+     * redelivery count, so a retry needs a re-publish. Fail loudly here instead of looping at run time.
+     */
+    private checkRetryBound;
+    private retryTopic;
+    /** The retry producer: the one given, else one built (once) from the client; undefined when neither exists. */
+    private resolveRetryProducer;
     /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
     poll(): Promise<number>;
     /** Poll until `signal` aborts. */
     run(signal?: AbortSignal): Promise<void>;
     private handle;
+    /**
+     * Settle a version-gated delivery on its first delivery (ADR-0037 decision 1, broker-bindings §5.7): it is
+     * never decoded, never reaches a handler or {@link PulsarConsumerOptions.onUnknownUrn}, and is never retried,
+     * whatever `bq-attempts`, the redelivery count or `maxAttempts` say. This consumer has no unknown-URN
+     * strategy option, so it behaves as `fail`: with a {@link PulsarConsumerOptions.deadLetterProducer} the body is
+     * written to `<queue>.dlq` exactly as received (no `dead_letter` block, no re-encoding) and acknowledged only
+     * after the write; without one it is acknowledged and dropped (logged). A failed write leaves the delivery
+     * negatively acknowledged (never acknowledged, never counted as a retry): the gate rejects the redelivery
+     * again, so the write is tried again.
+     */
+    private settleVersionGated;
+    /**
+     * The settle decision of a retryable outcome (ADR-0036 decisions 1 and 2). `counted` is the reconciled
+     * attempts plus one for this delivery. A poison body with dead-lettering on is recorded without retry;
+     * every other outcome retries (`negativeAcknowledge`: the native redelivery count advances, so the
+     * next delivery counts one more) while `counted < maxAttempts`, then dead-letters or drops.
+     */
+    private settle;
+    /**
+     * Retry one delivery. With a {@link PulsarConsumerOptions.retryProducer}: re-publish to the consumer's
+     * own topic carrying `bq-attempts = counted` (reconcile = max(bq-attempts, RedeliveryCount) on the next
+     * delivery), then acknowledge the original — only after the send succeeded. Otherwise `negativeAcknowledge`.
+     */
+    private retry;
+    private retryMessage;
+    /**
+     * Write the DLQ record, then acknowledge the original — only after the send succeeded. A failed send
+     * leaves the original negatively acknowledged, so it is redelivered and the write is tried again.
+     */
+    private deadLetter;
+    private deadLetterMessage;
     private notifyRoutingMismatch;
 }
 
-export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, headersOf, pulsarProperties, toPulsarMessage };
+export { type BabelHandler, type BabelHandlers, DEFAULT_MAX_ATTEMPTS, type PublishOptions, type PulsarClientLike, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, type PulsarSubscriptionType, headersOf, pulsarProperties, toPulsarMessage };