youeduc-sdk-messaging 0.0.0 → 0.5.0

package/dist/dlq.js

@@ -0,0 +1,341 @@
+/**
+ * Replay of a consumer group's DLQ (spec §9; Python `dlq.py`).
+ *
+ * The message goes back through the group's **first current retry topic**, with the retry/DLQ
+ * state removed from the headers (`x-retry-count`, `x-retry-due-at`, `x-dlq-reason`,
+ * `x-last-error`, `x-last-error-type`). Without `x-retry-due-at` it is due immediately and the
+ * group's consumer processes it with `retryCount = 0`. Only that group receives it: the shared
+ * main topic is never touched.
+ *
+ * Deduplication does not get in the way: the consumer never marks a key on a DLQ outcome.
+ *
+ * With `resourcePrefix` (spec §2.7) the DLQ, the target and the reader's group id use the prefixed
+ * names (`hmg.enrollment.events.v1.learning-worker.dlq`, `hmg.learning-worker.dlq-replay`).
+ *
+ * Progress: the reader uses its own group id `{group}.dlq-replay` and commits `offset + 1` of each
+ * record **after** the send was acknowledged (synchronous commit: a failure propagates). A new run
+ * continues where the previous one stopped. The commit is a position: records skipped (outside
+ * `reasons`) before a replayed record stay behind in that group id.
+ *
+ * The end offsets are captured at the start: what comes back to the DLQ during the replay (a new
+ * failure) is not read again in the same run.
+ */
+import { partitionKey } from './consumer-client.js';
+import * as hdr from './headers.js';
+import { defaultLogger } from './logger.js';
+import * as naming from './naming.js';
+import { RetryPolicy } from './retry.js';
+import { producerClientConfig, toProducerHeaders } from './transport.js';
+import { DLQ_REASONS } from './types.js';
+import { pyRepr } from './util.js';
+const DEFAULT_RETRY_POLICY = new RetryPolicy();
+const ALL_REASONS = new Set(DLQ_REASONS);
+const DEFAULT_EXCLUDED = new Set(['invalid_payload']);
+const STRIPPED_HEADERS = new Set([
+    hdr.RETRY_COUNT,
+    hdr.RETRY_DUE_AT,
+    hdr.DLQ_REASON,
+    hdr.LAST_ERROR,
+    hdr.LAST_ERROR_TYPE,
+]);
+const REPLAY_GROUP_SUFFIX = '.dlq-replay';
+/** Safe characters for a group.id (same alphabet as topic names). */
+const GROUP_ID_RE = /^[a-zA-Z0-9._-]{1,249}$/;
+const POLL_TIMEOUT_MS = 500;
+const MAX_POLL_RECORDS = 500;
+/** group.id of the replay reader: `{group}.dlq-replay` (with a prefix, `{prefix}.{group}.dlq-replay`). */
+export function replayGroupId(group, options) {
+    const groupId = naming.consumerGroup(group, options) + REPLAY_GROUP_SUFFIX;
+    if (!GROUP_ID_RE.test(groupId))
+        throw new TypeError(`invalid replay group id ${pyRepr(groupId)}`);
+    return groupId;
+}
+/** Headers of the replayed record: no retry/DLQ state, everything else preserved. */
+export function replayHeaders(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (!STRIPPED_HEADERS.has(name))
+            result[name] = value;
+    }
+    return result;
+}
+/** `null` = every reason except `invalid_payload` (includes records without a reason). */
+function selectedReasons(reasons) {
+    if (reasons === null || reasons === undefined)
+        return null;
+    if (typeof reasons === 'string') {
+        throw new TypeError("'reasons' must be an iterable of DLQ reasons, not a string");
+    }
+    const selected = new Set(reasons);
+    if (selected.size === 0)
+        throw new TypeError("'reasons' must not be empty (use null for the default)");
+    const unknown = [...selected].filter((reason) => !ALL_REASONS.has(reason)).sort();
+    if (unknown.length > 0) {
+        throw new TypeError(`unknown DLQ reason(s) [${unknown.map((r) => pyRepr(String(r))).join(', ')}];` +
+            ` valid: [${[...ALL_REASONS].sort().map(pyRepr).join(', ')}]`);
+    }
+    return selected;
+}
+function isSelected(reason, selected) {
+    if (selected === null)
+        return reason === undefined || !DEFAULT_EXCLUDED.has(reason);
+    return reason !== undefined && selected.has(reason);
+}
+/**
+ * Resends DLQ messages of the group to its first retry topic.
+ *
+ * `dryRun: true` (default) only counts what would be resent: nothing is sent nor committed.
+ * `maxMessages` limits the resends (or `wouldReplay`) of this run. A send failure propagates;
+ * that record is not committed.
+ */
+export async function replayDlq(config, options) {
+    const prefix = { resourcePrefix: options.resourcePrefix };
+    const main = naming.topic(options.domain, options.version, prefix);
+    const dlq = naming.dlqTopic(main, options.group);
+    const groupId = replayGroupId(options.group, prefix);
+    const retryPolicy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+    const firstDelay = retryPolicy.delaysMs[0];
+    if (firstDelay === undefined) {
+        throw new TypeError('retryPolicy has no delays: there is no retry topic to replay into');
+    }
+    const target = naming.retryTopic(main, options.group, firstDelay);
+    const selected = selectedReasons(options.reasons);
+    const maxMessages = options.maxMessages ?? null;
+    if (maxMessages !== null &&
+        (typeof maxMessages !== 'number' || !Number.isInteger(maxMessages) || maxMessages < 1)) {
+        throw new RangeError(`'maxMessages' must be an integer >= 1; got ${String(maxMessages)}`);
+    }
+    const dryRun = options.dryRun ?? true;
+    const logger = options.logger ?? defaultLogger();
+    const consumer = await (options.consumerFactory ?? createConfluentReplayConsumer)({
+        ...config.clientConfig(),
+        'group.id': groupId,
+        'enable.auto.commit': false,
+        'enable.auto.offset.store': false,
+        'auto.offset.reset': 'earliest',
+    });
+    // Same producer settings as KafkaProducerSender (partitioner, idempotence, acks, size limit, §11).
+    const producer = await (options.producerFactory ?? createConfluentReplayProducer)(producerClientConfig(config));
+    let replayed = 0;
+    let skipped = 0;
+    let wouldReplay = 0;
+    const logCtx = { dlq_topic: dlq, target_topic: target, group_id: groupId, dry_run: dryRun };
+    logger.info('dlq_replay_started', {
+        messaging: {
+            ...logCtx,
+            reasons: selected === null ? null : [...selected].sort(),
+            max_messages: maxMessages,
+        },
+    });
+    const limitReached = () => maxMessages !== null && replayed + wouldReplay >= maxMessages;
+    try {
+        await producer.connect();
+        await consumer.connect();
+        // Fails when the DLQ does not exist.
+        const partitionIds = [...(await producer.partitionsFor(dlq))].sort((a, b) => a - b);
+        const partitions = partitionIds.map((partition) => ({ topic: dlq, partition }));
+        consumer.assign(partitions);
+        const ends = await consumer.endOffsets(partitions);
+        const pending = new Map();
+        for (const [index, tp] of partitions.entries()) {
+            const end = ends[index] ?? 0;
+            if ((await consumer.position(tp)) < end)
+                pending.set(partitionKey(tp), { tp, end });
+            else
+                consumer.pause([tp]);
+        }
+        while (pending.size > 0 && !limitReached()) {
+            const records = await consumer.poll({
+                partitions: [...pending.values()].map((entry) => entry.tp),
+                timeoutMs: POLL_TIMEOUT_MS,
+            });
+            const byPartition = new Map();
+            for (const record of records) {
+                const key = partitionKey(record);
+                const list = byPartition.get(key);
+                if (list === undefined)
+                    byPartition.set(key, [record]);
+                else
+                    list.push(record);
+            }
+            for (const [key, list] of byPartition) {
+                const entry = pending.get(key);
+                if (entry === undefined)
+                    continue;
+                for (const record of [...list].sort((a, b) => a.offset - b.offset)) {
+                    if (record.offset >= entry.end || limitReached())
+                        break;
+                    const headers = hdr.decode(record.headers);
+                    const reason = headers[hdr.DLQ_REASON];
+                    const fields = {
+                        ...logCtx,
+                        partition: record.partition,
+                        offset: record.offset,
+                        message_id: headers[hdr.MESSAGE_ID] ?? '',
+                        event_type: headers[hdr.EVENT_TYPE] ?? '',
+                        dlq_reason: reason ?? null,
+                    };
+                    if (record.value === null || !isSelected(reason, selected)) {
+                        skipped += 1;
+                        logger.info('dlq_record_skipped', {
+                            messaging: fields,
+                            skip_cause: record.value === null ? 'null_value' : 'reason_not_selected',
+                        });
+                        continue;
+                    }
+                    if (dryRun) {
+                        wouldReplay += 1;
+                        logger.info('dlq_record_replayed', { messaging: fields });
+                        continue;
+                    }
+                    await producer.send(target, record.value, {
+                        key: record.key,
+                        headers: hdr.encode(replayHeaders(headers)),
+                    });
+                    // Only after the ack: a crash here resends at most this record.
+                    await consumer.commit([
+                        { topic: record.topic, partition: record.partition, offset: record.offset + 1 },
+                    ]);
+                    replayed += 1;
+                    logger.info('dlq_record_replayed', { messaging: fields });
+                }
+            }
+            // End of the partition by position (covers offset gaps, e.g. compaction).
+            for (const [key, entry] of [...pending]) {
+                if ((await consumer.position(entry.tp)) >= entry.end) {
+                    pending.delete(key);
+                    consumer.pause([entry.tp]);
+                }
+            }
+        }
+    }
+    finally {
+        try {
+            await consumer.disconnect();
+        }
+        finally {
+            await producer.disconnect();
+        }
+    }
+    const report = Object.freeze({ targetTopic: target, replayed, skipped, wouldReplay });
+    logger.info('dlq_replay_finished', {
+        messaging: logCtx,
+        replayed: report.replayed,
+        skipped: report.skipped,
+        would_replay: report.wouldReplay,
+    });
+    return report;
+}
+// ------------------------------------------------------------------------------ default clients
+const OFFSET_INVALID = -1001;
+const TIMEOUT_MS = 10_000;
+function promisify(fn) {
+    return new Promise((resolve, reject) => {
+        try {
+            fn((error, value) => (error ? reject(error) : resolve(value)));
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+/** DLQ reader over the callback `KafkaConsumer` (manual assignment, synchronous commits). */
+export class ConfluentReplayConsumer {
+    #raw;
+    constructor(raw) {
+        this.#raw = raw;
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            this.#raw.connect(null, (error) => (error ? reject(error) : resolve()));
+        });
+    }
+    assign(partitions) {
+        this.#raw.assign(partitions.map((tp) => ({ topic: tp.topic, partition: tp.partition })));
+    }
+    async endOffsets(partitions) {
+        return Promise.all(partitions.map(async (tp) => {
+            const marks = await promisify((cb) => this.#raw.queryWatermarkOffsets(tp.topic, tp.partition, TIMEOUT_MS, cb));
+            return marks.highOffset;
+        }));
+    }
+    async position(partition) {
+        const current = this.#raw.position([{ topic: partition.topic, partition: partition.partition }])[0]
+            ?.offset;
+        if (typeof current === 'number' && current >= 0)
+            return current;
+        // Nothing fetched yet: the start is the committed offset (else, or when out of range, earliest).
+        const [committed] = await promisify((cb) => this.#raw.committed([{ topic: partition.topic, partition: partition.partition }], TIMEOUT_MS, cb));
+        const marks = await promisify((cb) => this.#raw.queryWatermarkOffsets(partition.topic, partition.partition, TIMEOUT_MS, cb));
+        const start = committed?.offset ?? OFFSET_INVALID;
+        return start >= marks.lowOffset ? start : marks.lowOffset;
+    }
+    pause(partitions) {
+        this.#raw.pause(partitions.map((tp) => ({ topic: tp.topic, partition: tp.partition })));
+    }
+    async poll(options) {
+        const wanted = new Set(options.partitions.map(partitionKey));
+        this.#raw.setDefaultConsumeTimeout(options.timeoutMs);
+        const messages = await promisify((cb) => this.#raw.consume(MAX_POLL_RECORDS, cb));
+        return (messages ?? [])
+            .filter((message) => wanted.has(partitionKey(message)))
+            .map((message) => {
+            const headers = [];
+            for (const header of message.headers ?? []) {
+                for (const [name, value] of Object.entries(header))
+                    headers.push([name, value]);
+            }
+            const key = message.key;
+            return {
+                topic: message.topic,
+                partition: message.partition,
+                offset: message.offset,
+                key: key === null || key === undefined ? null : typeof key === 'string' ? Buffer.from(key) : key,
+                value: message.value ?? null,
+                headers,
+            };
+        });
+    }
+    async commit(offsets) {
+        this.#raw.commitSync(offsets.map((o) => ({ topic: o.topic, partition: o.partition, offset: o.offset })));
+    }
+    async disconnect() {
+        if (!this.#raw.isConnected())
+            return;
+        await new Promise((resolve) => {
+            this.#raw.disconnect(() => resolve());
+        });
+    }
+}
+/** Default reader: the callback `KafkaConsumer` of `@confluentinc/kafka-javascript`. */
+export const createConfluentReplayConsumer = async (config) => {
+    const kafka = (await import('@confluentinc/kafka-javascript')).default;
+    return new ConfluentReplayConsumer(new kafka.KafkaConsumer(config));
+};
+/** Default producer: idempotent KafkaJS producer (acks=all); partitions from its metadata. */
+export const createConfluentReplayProducer = async (config) => {
+    const { KafkaJS } = (await import('@confluentinc/kafka-javascript')).default;
+    const producer = new KafkaJS.Kafka({}).producer(config);
+    return {
+        connect: () => producer.connect(),
+        disconnect: () => producer.disconnect(),
+        async partitionsFor(topic) {
+            const admin = producer.dependentAdmin();
+            await admin.connect();
+            try {
+                const [metadata] = await admin.fetchTopicMetadata({ topics: [topic], timeout: TIMEOUT_MS });
+                return (metadata?.partitions ?? []).map((p) => p.partitionId);
+            }
+            finally {
+                await admin.disconnect();
+            }
+        },
+        async send(topic, value, options) {
+            await producer.send({
+                topic,
+                messages: [{ key: options.key, value, headers: toProducerHeaders(options.headers) }],
+            });
+        },
+    };
+};
+//# sourceMappingURL=dlq.js.map

package/dist/dlq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dlq.js","sourceRoot":"","sources":["../src/dlq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,YAAY,EAAkD,MAAM,sBAAsB,CAAC;AACpG,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,aAAa,EAA+B,MAAM,aAAa,CAAC;AACzE,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAkB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAiFnC,MAAM,oBAAoB,GAAG,IAAI,WAAW,EAAE,CAAC;AAC/C,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;AAC9D,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAC3E,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IACpD,GAAG,CAAC,WAAW;IACf,GAAG,CAAC,YAAY;IAChB,GAAG,CAAC,UAAU;IACd,GAAG,CAAC,UAAU;IACd,GAAG,CAAC,eAAe;CACpB,CAAC,CAAC;AACH,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAC1C,qEAAqE;AACrE,MAAM,WAAW,GAAG,yBAAyB,CAAC;AAC9C,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,0GAA0G;AAC1G,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,OAAsC;IACjF,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAAC;IAC3E,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,2BAA2B,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClG,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,OAAqC;IACjE,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,SAAS,eAAe,CAAC,OAA+C;IACtE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3D,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,CAAC;IAC1C,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;IACvG,MAAM,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,SAAS,CACjB,0BAA0B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC5E,YAAY,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,UAAU,CAAC,MAA0B,EAAE,QAAoC;IAClF,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,MAAM,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpF,OAAO,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAmB,EAAE,OAAyB;IAC5E,MAAM,MAAM,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAChE,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAChD,IACE,WAAW,KAAK,IAAI;QACpB,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,EACtF,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,8CAA8C,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACtC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;IAEjD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,IAAI,6BAA6B,CAAC,CAAC;QAChF,GAAG,MAAM,CAAC,YAAY,EAAE;QACxB,UAAU,EAAE,OAAO;QACnB,oBAAoB,EAAE,KAAK;QAC3B,0BAA0B,EAAE,KAAK;QACjC,mBAAmB,EAAE,UAAU;KAChC,CAAC,CAAC;IACH,mGAAmG;IACnG,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,IAAI,6BAA6B,CAAC,CAC/E,oBAAoB,CAAC,MAAM,CAAC,CAC7B,CAAC;IACF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,MAAM,MAAM,GAAc,EAAE,SAAS,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACvG,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE;QAChC,SAAS,EAAE;YACT,GAAG,MAAM;YACT,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE;YACxD,YAAY,EAAE,WAAW;SAC1B;KACF,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,GAAY,EAAE,CAAC,WAAW,KAAK,IAAI,IAAI,QAAQ,GAAG,WAAW,IAAI,WAAW,CAAC;IAElG,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;QACzB,qCAAqC;QACrC,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACpF,MAAM,UAAU,GAAqB,YAAY,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAClG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA+C,CAAC;QACvE,KAAK,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;YAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG;gBAAE,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;;gBAC/E,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,CAAC;QAED,OAAO,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC;gBAClC,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1D,SAAS,EAAE,eAAe;aAC3B,CAAC,CAAC;YACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAA0B,CAAC;YACtD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;gBACjC,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClC,IAAI,IAAI,KAAK,SAAS;oBAAE,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;;oBAClD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YACD,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,WAAW,EAAE,CAAC;gBACtC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC/B,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;oBACnE,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,YAAY,EAAE;wBAAE,MAAM;oBACxD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;oBAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;oBACvC,MAAM,MAAM,GAAc;wBACxB,GAAG,MAAM;wBACT,SAAS,EAAE,MAAM,CAAC,SAAS;wBAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;wBACrB,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE;wBACzC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE;wBACzC,UAAU,EAAE,MAAM,IAAI,IAAI;qBAC3B,CAAC;oBACF,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;wBAC3D,OAAO,IAAI,CAAC,CAAC;wBACb,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE;4BAChC,SAAS,EAAE,MAAM;4BACjB,UAAU,EAAE,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,qBAAqB;yBACzE,CAAC,CAAC;wBACH,SAAS;oBACX,CAAC;oBACD,IAAI,MAAM,EAAE,CAAC;wBACX,WAAW,IAAI,CAAC,CAAC;wBACjB,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;wBAC1D,SAAS;oBACX,CAAC;oBACD,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE;wBACxC,GAAG,EAAE,MAAM,CAAC,GAAG;wBACf,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;qBAC5C,CAAC,CAAC;oBACH,gEAAgE;oBAChE,MAAM,QAAQ,CAAC,MAAM,CAAC;wBACpB,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE;qBAChF,CAAC,CAAC;oBACH,QAAQ,IAAI,CAAC,CAAC;oBACd,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC5D,CAAC;YACH,CAAC;YACD,0EAA0E;YAC1E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;gBACxC,IAAI,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;oBACrD,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACpB,QAAQ,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC7B,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC9B,CAAC;gBAAS,CAAC;YACT,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAiB,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACpG,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE;QACjC,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,YAAY,EAAE,MAAM,CAAC,WAAW;KACjC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iGAAiG;AAEjG,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC;AAC7B,MAAM,UAAU,GAAG,MAAM,CAAC;AAqC1B,SAAS,SAAS,CAAI,EAAgC;IACpD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,IAAI,CAAC;YACH,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,6FAA6F;AAC7F,MAAM,OAAO,uBAAuB;IACzB,IAAI,CAAoB;IAEjC,YAAY,GAAsB;QAChC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;IAClB,CAAC;IAED,OAAO;QACL,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,UAA4B;QACjC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,UAA4B;QAC3C,OAAO,OAAO,CAAC,GAAG,CAChB,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YAC1B,MAAM,KAAK,GAAG,MAAM,SAAS,CAAyB,CAAC,EAAE,EAAE,EAAE,CAC3D,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,CACxE,CAAC;YACF,OAAO,KAAK,CAAC,UAAU,CAAC;QAC1B,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,SAAyB;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACjG,EAAE,MAAM,CAAC;QACX,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC;YAAE,OAAO,OAAO,CAAC;QAChE,iGAAiG;QACjG,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,SAAS,CAA6B,CAAC,EAAE,EAAE,EAAE,CACrE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,CAClG,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,SAAS,CAAwB,CAAC,EAAE,EAAE,EAAE,CAC1D,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,CACtF,CAAC;QACF,MAAM,KAAK,GAAG,SAAS,EAAE,MAAM,IAAI,cAAc,CAAC;QAClD,OAAO,KAAK,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,UAA4B;QAChC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAA4D;QACrE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,wBAAwB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAe,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,CAAC;QAChG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;aACtD,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;YACf,MAAM,OAAO,GAAqC,EAAE,CAAC;YACrD,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBAC3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;oBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YAClF,CAAC;YACD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;YACxB,OAAO;gBACL,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,GAAG,EAAE,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG;gBAChG,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;gBAC5B,OAAO;aACR,CAAC;QACJ,CAAC,CAAC,CAAC;IACP,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAA+B;QAC1C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAC3G,CAAC;IAED,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YAAE,OAAO;QACrC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,6BAA6B,GAA0B,KAAK,EAAE,MAAM,EAAE,EAAE;IACnF,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC,CAAC,OAAO,CAAC;IACvE,OAAO,IAAI,uBAAuB,CAChC,IAAI,KAAK,CAAC,aAAa,CAAC,MAAe,CAAiC,CACzE,CAAC;AACJ,CAAC,CAAC;AAmBF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,6BAA6B,GAA0B,KAAK,EAAE,MAAM,EAAE,EAAE;IACnF,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC7E,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAqC,CAAC;IAC5F,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE;QACjC,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE;QACvC,KAAK,CAAC,aAAa,CAAC,KAAK;YACvB,MAAM,KAAK,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC;YACxC,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,KAAK,CAAC,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC5F,OAAO,CAAC,QAAQ,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;YAChE,CAAC;oBAAS,CAAC;gBACT,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO;YAC9B,MAAM,QAAQ,CAAC,IAAI,CAAC;gBAClB,KAAK;gBACL,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;aACrF,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * SDK errors. Same names and messages as the Python SDK (`exceptions.py`, plus the errors that
+ * Python defines in `consumer.py` and `integrations/redis.py`).
+ *
+ * Every class sets `name` to its own class name, so `error.name` (and the `x-last-error-type`
+ * header) matches Python's `type(exc).__name__`.
+ */
+/** Base of every SDK error. */
+export declare class MessagingError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** The operation requires a started component (`start()`) that was not stopped yet. */
+export declare class NotStartedError extends MessagingError {
+}
+/** Thrown by a handler to flag a non-recoverable error: the message goes straight to the DLQ. */
+export declare class PermanentProcessingError extends MessagingError {
+}
+/**
+ * Payload rejected by the JSON Schema (or not serializable as JSON, or the schema itself is
+ * invalid). `field` is a JSON pointer (`""` = root); `reason` never contains payload values.
+ */
+export declare class SchemaValidationError extends MessagingError {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
+/** No schema for `{domain}/{event}/{version}.json` (`event` is the slug, `student-enrolled`). */
+export declare class SchemaNotFoundError extends MessagingError {
+    readonly domain: string;
+    readonly event: string;
+    readonly version: string;
+    constructor(domain: string, event: string, version: string);
+}
+/**
+ * The broker did not acknowledge the send (acks=all) within the timeout, or the client failed.
+ *
+ * `retriable === false` flags a deterministic error (message too large, not authorized,
+ * invalid topic): repeating the same send will not work. A timeout (`retriable === true`) does
+ * not guarantee that the message was not written.
+ */
+export declare class PublishError extends MessagingError {
+    readonly topic: string;
+    readonly reason: string;
+    readonly retriable: boolean;
+    constructor(topic: string, reason: string, options?: {
+        retriable?: boolean;
+        cause?: unknown;
+    });
+}
+/** Payload missing, not UTF-8 JSON or not a JSON object. The message never carries payload values. */
+export declare class InvalidPayloadError extends MessagingError {
+}
+/** The handler itself ended cancelled/aborted (without the consumer cancelling it). */
+export declare class HandlerCancelledError extends MessagingError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** Misconfigured handler (could not be called, did not return a promise): goes to the DLQ. */
+export declare class InvalidHandlerError extends PermanentProcessingError {
+}
+/**
+ * The deduplication store did not answer in time or failed. The message never contains the
+ * dedup key (it may be PII); the original error is kept in `cause`.
+ */
+export declare class DedupUnavailableError extends MessagingError {
+    readonly operation: string;
+    readonly namespace: string;
+    readonly group: string;
+    readonly reason: string;
+    constructor(operation: string, namespace: string, group: string, reason: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,95 @@
+/**
+ * SDK errors. Same names and messages as the Python SDK (`exceptions.py`, plus the errors that
+ * Python defines in `consumer.py` and `integrations/redis.py`).
+ *
+ * Every class sets `name` to its own class name, so `error.name` (and the `x-last-error-type`
+ * header) matches Python's `type(exc).__name__`.
+ */
+import { pyRepr } from './util.js';
+/** Base of every SDK error. */
+export class MessagingError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** The operation requires a started component (`start()`) that was not stopped yet. */
+export class NotStartedError extends MessagingError {
+}
+/** Thrown by a handler to flag a non-recoverable error: the message goes straight to the DLQ. */
+export class PermanentProcessingError extends MessagingError {
+}
+/**
+ * Payload rejected by the JSON Schema (or not serializable as JSON, or the schema itself is
+ * invalid). `field` is a JSON pointer (`""` = root); `reason` never contains payload values.
+ */
+export class SchemaValidationError extends MessagingError {
+    field;
+    reason;
+    constructor(field, reason) {
+        const location = field ? ` at ${pyRepr(field)}` : '';
+        super(`schema validation error${location}: ${reason}`);
+        this.field = field;
+        this.reason = reason;
+    }
+}
+/** No schema for `{domain}/{event}/{version}.json` (`event` is the slug, `student-enrolled`). */
+export class SchemaNotFoundError extends MessagingError {
+    domain;
+    event;
+    version;
+    constructor(domain, event, version) {
+        super(`schema not found: ${domain}/${event}/${version}.json`);
+        this.domain = domain;
+        this.event = event;
+        this.version = version;
+    }
+}
+/**
+ * The broker did not acknowledge the send (acks=all) within the timeout, or the client failed.
+ *
+ * `retriable === false` flags a deterministic error (message too large, not authorized,
+ * invalid topic): repeating the same send will not work. A timeout (`retriable === true`) does
+ * not guarantee that the message was not written.
+ */
+export class PublishError extends MessagingError {
+    topic;
+    reason;
+    retriable;
+    constructor(topic, reason, options = {}) {
+        super(`failed to publish to topic ${pyRepr(topic)}: ${reason}`, options.cause === undefined ? undefined : { cause: options.cause });
+        this.topic = topic;
+        this.reason = reason;
+        this.retriable = options.retriable ?? true;
+    }
+}
+/** Payload missing, not UTF-8 JSON or not a JSON object. The message never carries payload values. */
+export class InvalidPayloadError extends MessagingError {
+}
+/** The handler itself ended cancelled/aborted (without the consumer cancelling it). */
+export class HandlerCancelledError extends MessagingError {
+    constructor(message = 'handler task was cancelled', options) {
+        super(message, options);
+    }
+}
+/** Misconfigured handler (could not be called, did not return a promise): goes to the DLQ. */
+export class InvalidHandlerError extends PermanentProcessingError {
+}
+/**
+ * The deduplication store did not answer in time or failed. The message never contains the
+ * dedup key (it may be PII); the original error is kept in `cause`.
+ */
+export class DedupUnavailableError extends MessagingError {
+    operation;
+    namespace;
+    group;
+    reason;
+    constructor(operation, namespace, group, reason, options) {
+        super(`dedup store unavailable: ${operation} failed (namespace=${pyRepr(namespace)}, group=${pyRepr(group)}): ${reason}`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.operation = operation;
+        this.namespace = namespace;
+        this.group = group;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/headers.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Message headers. In Kafka headers are bytes; in the SDK they travel as a `string → string`
+ * map, (de)coded as UTF-8 at the edge. Header names and value formats are protocol: identical
+ * to the Python SDK.
+ */
+export declare const MESSAGE_ID = "message_id";
+export declare const EVENT_TYPE = "event_type";
+export declare const SCHEMA_VERSION = "schema_version";
+export declare const PUBLISHED_AT = "published_at";
+export declare const PRODUCER = "producer";
+export declare const CORRELATION_ID = "correlation_id";
+export declare const IDEMPOTENCY_KEY = "idempotency_key";
+export declare const TENANT_ID = "x-tenant-id";
+export declare const RETRY_COUNT = "x-retry-count";
+/** Epoch in milliseconds. */
+export declare const RETRY_DUE_AT = "x-retry-due-at";
+export declare const FIRST_FAILED_AT = "x-first-failed-at";
+export declare const LAST_ERROR = "x-last-error";
+export declare const LAST_ERROR_TYPE = "x-last-error-type";
+export declare const ORIGINAL_TOPIC = "x-original-topic";
+export declare const ORIGINAL_PARTITION = "x-original-partition";
+export declare const ORIGINAL_OFFSET = "x-original-offset";
+export declare const DLQ_REASON = "x-dlq-reason";
+/** Error messages are truncated (in characters / code points, like Python) to keep headers small. */
+export declare const MAX_ERROR_LENGTH = 1024;
+/** Headers in the SDK: name → UTF-8 text. */
+export type MessageHeaders = Record<string, string>;
+/** Headers on the wire, in order (the equivalent of Python's `list[tuple[str, bytes]]`). */
+export type KafkaHeaders = ReadonlyArray<readonly [name: string, value: Buffer]>;
+type RawHeaderValue = Buffer | Uint8Array | string | null | undefined;
+/**
+ * Headers as received from a Kafka client: a list of `[name, value]` pairs or the KafkaJS
+ * object form (`{name: Buffer | Buffer[]}`, repeated names become arrays).
+ */
+export type RawHeaders = ReadonlyArray<readonly [string, RawHeaderValue]> | Readonly<Record<string, RawHeaderValue | readonly RawHeaderValue[]>> | null | undefined;
+/** Clock in epoch milliseconds (injectable for tests). */
+export type EpochClock = () => number;
+/** Epoch milliseconds now. */
+export declare function nowMs(): number;
+/** `MessageHeaders` → wire format (UTF-8), keeping insertion order. */
+export declare function encode(headers: Readonly<MessageHeaders>): Array<[string, Buffer]>;
+/**
+ * Last occurrence wins; invalid UTF-8 is replaced (U+FFFD); `null` values become `''`.
+ * The result has no prototype, so a header named `__proto__` is kept as a plain entry.
+ */
+export declare function decode(raw: RawHeaders): MessageHeaders;
+/** Integer header (`x-retry-count`, `x-retry-due-at`): absent, empty or invalid → 0. */
+export declare function parseHeaderInt(value: string | undefined): number;
+/** Reads `x-retry-count` tolerating absence/invalid values (→ 0); negative → 0. */
+export declare function retryCount(headers: Readonly<MessageHeaders>): number;
+/** Reads `x-retry-due-at` (epoch ms); absent or invalid → 0 (= already due). */
+export declare function retryDueAtMs(headers: Readonly<MessageHeaders>): number;
+/**
+ * Dedup key (spec §8.1): `idempotency_key` if not empty, else `message_id` if not empty, else
+ * `null` (no dedup). Used verbatim.
+ */
+export declare function dedupKey(headers: Readonly<MessageHeaders>): string | null;
+export interface PublishHeadersInit {
+    eventType: string;
+    schemaVersion: string;
+    producer: string;
+    correlationId?: string | null | undefined;
+    idempotencyKey?: string | null | undefined;
+    tenantId?: string | null | undefined;
+    /** Clock (epoch ms) for `published_at`. Default `Date.now`. */
+    clock?: EpochClock | undefined;
+    /** UUID generator for `message_id`/`correlation_id`. Default `crypto.randomUUID`. */
+    newId?: (() => string) | undefined;
+}
+/** Headers of a new publication: fresh UUID4 `message_id`, `correlation_id` given or new. */
+export declare function buildPublishHeaders(init: PublishHeadersInit): MessageHeaders;
+/** Position of the consumption that failed. */
+export interface FailurePosition {
+    topic: string;
+    partition: number;
+    offset: number;
+    /** Clock (epoch ms) for `x-first-failed-at`. Default `Date.now`. */
+    clock?: EpochClock | undefined;
+}
+export interface RetryHeadersInit extends FailurePosition {
+    /** When the retry becomes due, epoch milliseconds (truncated to an integer). */
+    dueAtMs: number;
+}
+/** Headers for the next retry: increments `x-retry-count`, sets `x-retry-due-at` (epoch ms). */
+export declare function buildRetryHeaders(headers: Readonly<MessageHeaders>, error: unknown, init: RetryHeadersInit): MessageHeaders;
+export interface DlqHeadersInit extends FailurePosition {
+    /** `x-dlq-reason` (`permanent_error`, `max_retries`, ...). */
+    reason: string;
+}
+/** Headers for the DLQ: removes `x-retry-due-at`, sets `x-dlq-reason`, keeps `x-retry-count`. */
+export declare function buildDlqHeaders(headers: Readonly<MessageHeaders>, error: unknown, init: DlqHeadersInit): MessageHeaders;
+export {};