youeduc-sdk-messaging 0.0.0 → 0.5.0

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAYxB,uCAAuC;AACvC,MAAM,CAAC,MAAM,UAAU,GAAW,MAAM,CAAC,MAAM,CAAC;IAC9C,KAAK,KAAI,CAAC;IACV,IAAI,KAAI,CAAC;IACT,IAAI,KAAI,CAAC;IACT,KAAK,KAAI,CAAC;CACX,CAAC,CAAC;AAUH,8FAA8F;AAC9F,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,UAAU,EAAE,OAAO;QACnB,UAAU,EAAE,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE;QACpD,SAAS,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO;KACzC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,QAAmB;IAC5C,MAAM,MAAM,GAAa,QAAQ,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAChE,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,KAAK,CAAC;QAC3D,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,EAAE,KAAK,CAAC;QACzD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,EAAE,KAAK,CAAC;QACzD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,EAAE,KAAK,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,IAAI,MAA0B,CAAC;AAE/B,qEAAqE;AACrE,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,UAAU,EAAE,CAAC;IACxB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,MAAM,GAAG,MAAM,CAAC;AAClB,CAAC"}

package/dist/messaging.d.ts

@@ -0,0 +1,145 @@
+/** Facade: one shared producer, publisher and consumers already wired. */
+import { type AdminFactory } from './admin.js';
+import type { KafkaConfig } from './config.js';
+import { type AutoOffsetReset, Consumer, type ConsumerHandlers } from './consumer.js';
+import type { ConsumerClientFactory } from './consumer-client.js';
+import { type Logger } from './logger.js';
+import { Publisher, type PublishOptions } from './publisher.js';
+import { RetryPolicy } from './retry.js';
+import type { DuplicateChecker, MessageSender, PayloadValidator, PublishResult, SchemaLoader, Telemetry } from './types.js';
+/** A sender with a lifecycle (`KafkaProducerSender` or a test fake). */
+export interface ManagedSender extends MessageSender {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Anything `Messaging.stop()` must stop before the producer (consumers created through the
+ * facade). They use the shared producer to route retries/DLQ while draining.
+ */
+export interface StoppableConsumer {
+    stop(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+}
+export interface MessagingOptions {
+    /** Kebab-case name: `producer` header, default consumer group, `service` metric label. */
+    service: string;
+    /** `environment` label / `deployment.environment.name`. */
+    environment: string;
+    /** `FileSystemSchemaLoader`, `InMemorySchemaLoader` or a custom `load(domain, event, version)`. */
+    schemaLoader: SchemaLoader;
+    /** Default `new OtelTelemetry(service, environment)` (global OTel providers; no-op if unset). */
+    telemetry?: Telemetry;
+    /** Maximum wait for the broker ack. Default 30 000 ms (ignored when `sender` is given). */
+    sendTimeoutMs?: number;
+    /** Default `new KafkaProducerSender(kafka, {sendTimeoutMs})`. */
+    sender?: ManagedSender;
+    /** Default: the SDK default logger. */
+    logger?: Logger;
+    /** Admin factory used by `ensureTopics` (tests inject fakes). */
+    adminFactory?: AdminFactory;
+    /**
+     * Resource prefix (spec §2.7), e.g. `hmg`/`prd`: first segment of every topic and group id of
+     * the facade (publisher, consumers, `ensureTopics`). Use it when environments share a cluster.
+     * Default: none.
+     */
+    resourcePrefix?: string | null;
+}
+export interface MessagingEnsureTopicsOptions {
+    /** Consumer group whose retry/DLQ topics are created. Default: the service name. */
+    group?: string;
+    /** Use the **same** policy as the consumer. Default `new RetryPolicy()`. */
+    retryPolicy?: RetryPolicy;
+    /** Partitions of the main topic. Default 3. */
+    numPartitions?: number;
+    /** Partitions of the retry topics. Default: `numPartitions`. */
+    retryNumPartitions?: number;
+    /** Partitions of the DLQ. Default: `numPartitions`. */
+    dlqNumPartitions?: number;
+    /** Default 1. */
+    replicationFactor?: number;
+    /** Configs of every created topic (e.g. `{"max.message.bytes": "1048576"}`). */
+    topicConfigs?: Readonly<Record<string, string>>;
+    /** Main topic configs, merged over `topicConfigs` (these keys win). */
+    mainTopicConfigs?: Readonly<Record<string, string>>;
+    /** Retry topic configs, merged over `topicConfigs` (these keys win). */
+    retryTopicConfigs?: Readonly<Record<string, string>>;
+    /** DLQ configs, merged over `topicConfigs` (these keys win). */
+    dlqTopicConfigs?: Readonly<Record<string, string>>;
+}
+/** Options of {@link Messaging.consumer} (spec §17); see `ConsumerOptions` for each one. */
+export interface MessagingConsumerOptions {
+    domain: string;
+    version: string;
+    handlers: ConsumerHandlers;
+    /** Default: the service name. */
+    group?: string | undefined;
+    retryPolicy?: RetryPolicy | undefined;
+    duplicateChecker?: DuplicateChecker | null | undefined;
+    processingTimeoutMs?: number | null | undefined;
+    maxPollRecords?: number | undefined;
+    maxPollIntervalMs?: number | undefined;
+    autoOffsetReset?: AutoOffsetReset | undefined;
+    pollTimeoutMs?: number | undefined;
+    routingFailureBackoffMs?: number | undefined;
+    consumerFactory?: ConsumerClientFactory | undefined;
+    /** Clock in epoch milliseconds. Default `Date.now`. */
+    clock?: (() => number) | undefined;
+}
+/**
+ * SDK entry point.
+ *
+ * A single idempotent producer is used to publish and to route retries/DLQ of every consumer
+ * created by the facade. `stop()` stops the consumers (draining the in-flight work) and then
+ * the producer.
+ *
+ * Without an explicit `telemetry` it uses {@link OtelTelemetry} with the global OpenTelemetry
+ * providers: spans/metrics are emitted if the application configured OpenTelemetry and it is a
+ * no-op otherwise.
+ */
+export declare class Messaging {
+    #private;
+    readonly kafka: KafkaConfig;
+    readonly service: string;
+    readonly environment: string;
+    readonly telemetry: Telemetry;
+    /** Payload validator shared by publisher and consumers (schema cache per process). */
+    readonly registry: PayloadValidator;
+    /** The shared producer (publish + retry/DLQ routing). */
+    readonly sender: ManagedSender;
+    readonly publisher: Publisher;
+    /** Resource prefix applied to topics and group ids (`null` = none). */
+    readonly resourcePrefix: string | null;
+    /** Consumers created by the facade; `stop()` stops them before the producer. */
+    protected readonly consumers: StoppableConsumer[];
+    constructor(kafka: KafkaConfig, options: MessagingOptions);
+    /** The logger used by the facade and the components it creates. */
+    get logger(): Logger;
+    start(): Promise<void>;
+    /**
+     * Stops the consumers (in parallel, draining up to `drainTimeoutMs`) and then the producer,
+     * which they use to send retries/DLQ while draining. The first consumer failure is rethrown
+     * after the producer is stopped.
+     */
+    stop(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+    /** Shortcut for {@link Publisher.publish}. */
+    publish(domain: string, aggregate: string, event: string, version: string, payload: Readonly<Record<string, unknown>>, options?: PublishOptions): Promise<PublishResult>;
+    /**
+     * Creates (without starting) a {@link Consumer} bound to this facade: shared producer for
+     * retry/DLQ, the schema registry, the telemetry and the logger. `group` defaults to the service
+     * name. `stop()` stops it before the producer.
+     */
+    consumer(options: MessagingConsumerOptions): Consumer;
+    /**
+     * Creates (if missing) the domain topic and the retry and DLQ topics of the group (default
+     * = service name, like the consumer), with the facade's resource prefix. For environments where
+     * the topology does not come from IaC. Returns the topics created (spec §2.6).
+     *
+     * `numPartitions` applies to the main topic; `retryNumPartitions` / `dlqNumPartitions` (default
+     * `numPartitions`) to retry / DLQ. `topicConfigs` applies to all; `mainTopicConfigs` /
+     * `retryTopicConfigs` / `dlqTopicConfigs` are merged over it. Existing topics are not changed.
+     */
+    ensureTopics(domain: string, version: string, options?: MessagingEnsureTopicsOptions): Promise<string[]>;
+}

package/dist/messaging.js

@@ -0,0 +1,164 @@
+/** Facade: one shared producer, publisher and consumers already wired. */
+import { createTopics } from './admin.js';
+import { Consumer } from './consumer.js';
+import { defaultLogger } from './logger.js';
+import * as naming from './naming.js';
+import { Publisher } from './publisher.js';
+import { RetryPolicy } from './retry.js';
+import { SchemaRegistry } from './schema.js';
+import { OtelTelemetry } from './telemetry.js';
+import { KafkaProducerSender } from './transport.js';
+const DEFAULT_RETRY_POLICY = new RetryPolicy();
+/**
+ * SDK entry point.
+ *
+ * A single idempotent producer is used to publish and to route retries/DLQ of every consumer
+ * created by the facade. `stop()` stops the consumers (draining the in-flight work) and then
+ * the producer.
+ *
+ * Without an explicit `telemetry` it uses {@link OtelTelemetry} with the global OpenTelemetry
+ * providers: spans/metrics are emitted if the application configured OpenTelemetry and it is a
+ * no-op otherwise.
+ */
+export class Messaging {
+    kafka;
+    service;
+    environment;
+    telemetry;
+    /** Payload validator shared by publisher and consumers (schema cache per process). */
+    registry;
+    /** The shared producer (publish + retry/DLQ routing). */
+    sender;
+    publisher;
+    /** Resource prefix applied to topics and group ids (`null` = none). */
+    resourcePrefix;
+    #logger;
+    #adminFactory;
+    /** Consumers created by the facade; `stop()` stops them before the producer. */
+    consumers = [];
+    constructor(kafka, options) {
+        this.kafka = kafka;
+        this.service = naming.serviceName(options.service);
+        this.resourcePrefix = naming.resourcePrefix(options.resourcePrefix);
+        this.environment = options.environment;
+        this.telemetry = options.telemetry ?? new OtelTelemetry(options.service, options.environment);
+        this.#logger = options.logger;
+        this.#adminFactory = options.adminFactory;
+        this.registry = new SchemaRegistry(options.schemaLoader);
+        this.sender =
+            options.sender ??
+                new KafkaProducerSender(kafka, {
+                    ...(options.sendTimeoutMs === undefined ? {} : { sendTimeoutMs: options.sendTimeoutMs }),
+                    ...(options.logger === undefined ? {} : { logger: options.logger }),
+                });
+        this.publisher = new Publisher(this.sender, this.registry, {
+            producer: this.service,
+            telemetry: this.telemetry,
+            logger: options.logger,
+            resourcePrefix: this.resourcePrefix,
+        });
+    }
+    /** The logger used by the facade and the components it creates. */
+    get logger() {
+        return this.#logger ?? defaultLogger();
+    }
+    async start() {
+        await this.sender.start();
+    }
+    /**
+     * Stops the consumers (in parallel, draining up to `drainTimeoutMs`) and then the producer,
+     * which they use to send retries/DLQ while draining. The first consumer failure is rethrown
+     * after the producer is stopped.
+     */
+    async stop(options = {}) {
+        const drainTimeoutMs = options.drainTimeoutMs ?? 30_000;
+        try {
+            const results = await Promise.allSettled(this.consumers.map((consumer) => consumer.stop({ drainTimeoutMs })));
+            const failure = results.find((result) => result.status === 'rejected');
+            if (failure !== undefined)
+                throw failure.reason;
+        }
+        finally {
+            await this.sender.stop();
+        }
+    }
+    /** Shortcut for {@link Publisher.publish}. */
+    publish(domain, aggregate, event, version, payload, options = {}) {
+        return this.publisher.publish(domain, aggregate, event, version, payload, options);
+    }
+    /**
+     * Creates (without starting) a {@link Consumer} bound to this facade: shared producer for
+     * retry/DLQ, the schema registry, the telemetry and the logger. `group` defaults to the service
+     * name. `stop()` stops it before the producer.
+     */
+    consumer(options) {
+        const consumer = new Consumer(this.kafka, {
+            group: options.group || this.service,
+            domain: options.domain,
+            version: options.version,
+            handlers: options.handlers,
+            validator: this.registry,
+            sender: this.sender,
+            retryPolicy: options.retryPolicy,
+            duplicateChecker: options.duplicateChecker,
+            telemetry: this.telemetry,
+            processingTimeoutMs: options.processingTimeoutMs,
+            maxPollRecords: options.maxPollRecords,
+            maxPollIntervalMs: options.maxPollIntervalMs,
+            autoOffsetReset: options.autoOffsetReset,
+            pollTimeoutMs: options.pollTimeoutMs,
+            routingFailureBackoffMs: options.routingFailureBackoffMs,
+            consumerFactory: options.consumerFactory,
+            clock: options.clock,
+            logger: this.#logger,
+            resourcePrefix: this.resourcePrefix,
+        });
+        this.consumers.push(consumer);
+        return consumer;
+    }
+    /**
+     * Creates (if missing) the domain topic and the retry and DLQ topics of the group (default
+     * = service name, like the consumer), with the facade's resource prefix. For environments where
+     * the topology does not come from IaC. Returns the topics created (spec §2.6).
+     *
+     * `numPartitions` applies to the main topic; `retryNumPartitions` / `dlqNumPartitions` (default
+     * `numPartitions`) to retry / DLQ. `topicConfigs` applies to all; `mainTopicConfigs` /
+     * `retryTopicConfigs` / `dlqTopicConfigs` are merged over it. Existing topics are not changed.
+     */
+    async ensureTopics(domain, version, options = {}) {
+        const numPartitions = options.numPartitions ?? 3;
+        for (const [name, value] of [
+            ['num_partitions', numPartitions],
+            ['retry_num_partitions', options.retryNumPartitions],
+            ['dlq_num_partitions', options.dlqNumPartitions],
+        ]) {
+            if (value !== undefined && (typeof value !== 'number' || !Number.isInteger(value) || value < 1)) {
+                throw new RangeError(`'${name}' must be >= 1; got ${String(value)}`);
+            }
+        }
+        const main = naming.topic(domain, version, { resourcePrefix: this.resourcePrefix });
+        // Empty or absent → service (like consumer() and Python's `group or service`).
+        const group = options.group || this.service;
+        const retryPolicy = options.retryPolicy ?? DEFAULT_RETRY_POLICY;
+        const base = options.topicConfigs ?? {};
+        const specs = [
+            { topic: main, numPartitions, topicConfigs: { ...base, ...options.mainTopicConfigs } },
+            ...retryPolicy.retryTopics(main, group).map((topic) => ({
+                topic,
+                numPartitions: options.retryNumPartitions ?? numPartitions,
+                topicConfigs: { ...base, ...options.retryTopicConfigs },
+            })),
+            {
+                topic: naming.dlqTopic(main, group),
+                numPartitions: options.dlqNumPartitions ?? numPartitions,
+                topicConfigs: { ...base, ...options.dlqTopicConfigs },
+            },
+        ];
+        return createTopics(this.kafka, specs, {
+            ...(options.replicationFactor === undefined ? {} : { replicationFactor: options.replicationFactor }),
+            ...(this.#adminFactory === undefined ? {} : { adminFactory: this.#adminFactory }),
+            ...(this.#logger === undefined ? {} : { logger: this.#logger }),
+        });
+    }
+}
+//# sourceMappingURL=messaging.js.map

package/dist/messaging.js.map

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

package/dist/naming.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Naming convention (single source). No other module builds names by hand.
+ *
+ * Main topic:        {domain}.events.{version}              enrollment.events.v1
+ * event_type:        {aggregate}.{event}                    student.enrolled
+ * schema slug:       {aggregate}-{event}                    student-enrolled
+ * Retry (per group): {topic}.{group}.retry.{label}          enrollment.events.v1.learning-worker.retry.30s
+ * DLQ (per group):   {topic}.{group}.dlq                    enrollment.events.v1.learning-worker.dlq
+ *
+ * Resource prefix (optional, environment; spec §2.7): first segment of the main topic and of the
+ * group id (`hmg.enrollment.events.v1`, `hmg.learning-worker`). Retry and DLQ derive from the
+ * already prefixed main topic and the bare group, so the prefix appears only once.
+ *
+ * Invalid input throws `TypeError` (Python: `ValueError`) with the same message as Python.
+ * Delays are in milliseconds (`Ms`) and must be whole seconds: the label of a retry topic is
+ * built from seconds, exactly like Python (`30000` → `30s`, `120000` → `2m`, `3600000` → `1h`).
+ */
+/** Kafka limit for topic names. */
+export declare const MAX_TOPIC_LENGTH = 249;
+/** Options of the naming functions that accept the resource prefix (spec §2.7). */
+export interface ResourcePrefixOptions {
+    /** Environment prefix (`hmg`, `prd`); `null`/absent = no prefix. */
+    resourcePrefix?: string | null | undefined;
+}
+/**
+ * Validates the resource prefix (kebab-case); `null`/`undefined` → `null` (no prefix).
+ * Invalid → `TypeError` (Python: `ValueError`).
+ */
+export declare function resourcePrefix(value: string | null | undefined): string | null;
+/** `{domain}.events.{version}`; with a prefix, `{prefix}.{domain}.events.{version}`. */
+export declare function topic(domain: string, version: string, options?: ResourcePrefixOptions): string;
+/** `{aggregate}.{event}`; `event` is a fact in the past (`student.enrolled`). */
+export declare function eventType(aggregate: string, event: string): string;
+/** Inverse of {@link eventType}; validates the format. */
+export declare function splitEventType(value: string): [aggregate: string, event: string];
+/** `student.enrolled` → `student-enrolled` (directory of the schema). */
+export declare function schemaSlug(eventTypeValue: string): string;
+/** 30000 → '30s', 120000 → '2m', 3600000 → '1h'. Uses the largest exact unit. */
+export declare function delayLabel(delayMs: number): string;
+/** Inverse of {@link delayLabel}: '2m' → 120000 (milliseconds). */
+export declare function parseDelayLabel(label: string): number;
+/**
+ * Regex source that matches the main topic and **all** retry topics of the group, including
+ * delays that left the `RetryPolicy` (no orphan retries).
+ *
+ * Same alternatives and anchors as Python's `retry_topic_pattern`; the escaping follows JS
+ * (`-` is not escaped), so the string is not byte-identical to Python's `re.escape` output.
+ */
+export declare function retryTopicPattern(mainTopic: string, group: string): string;
+/** Delay (ms) of a retry topic of the group, or `null` if it is not one. */
+export declare function retryDelayOf(topicName: string, mainTopic: string, group: string): number | null;
+/** `{main}.{group}.retry.{label}`. */
+export declare function retryTopic(mainTopic: string, group: string, delayMs: number): string;
+/** `{main}.{group}.dlq`. */
+export declare function dlqTopic(mainTopic: string, group: string): string;
+/** Name of the producing service (header `producer`), kebab-case. */
+export declare function serviceName(service: string): string;
+/**
+ * Prefix of the system/environment in a shared store (`hmgcatalogo_api`): 1-100 characters among
+ * letters, digits, `_`, `.`, `-`, starting with a letter or digit; no `:`.
+ */
+export declare function dedupNamespace(namespace: string): string;
+/** Kafka `group.id`: the validated logical name; with a prefix, `{prefix}.{group}`. */
+export declare function consumerGroup(group: string, options?: ResourcePrefixOptions): string;

package/dist/naming.js

@@ -0,0 +1,167 @@
+/**
+ * Naming convention (single source). No other module builds names by hand.
+ *
+ * Main topic:        {domain}.events.{version}              enrollment.events.v1
+ * event_type:        {aggregate}.{event}                    student.enrolled
+ * schema slug:       {aggregate}-{event}                    student-enrolled
+ * Retry (per group): {topic}.{group}.retry.{label}          enrollment.events.v1.learning-worker.retry.30s
+ * DLQ (per group):   {topic}.{group}.dlq                    enrollment.events.v1.learning-worker.dlq
+ *
+ * Resource prefix (optional, environment; spec §2.7): first segment of the main topic and of the
+ * group id (`hmg.enrollment.events.v1`, `hmg.learning-worker`). Retry and DLQ derive from the
+ * already prefixed main topic and the bare group, so the prefix appears only once.
+ *
+ * Invalid input throws `TypeError` (Python: `ValueError`) with the same message as Python.
+ * Delays are in milliseconds (`Ms`) and must be whole seconds: the label of a retry topic is
+ * built from seconds, exactly like Python (`30000` → `30s`, `120000` → `2m`, `3600000` → `1h`).
+ */
+import { pyRepr } from './util.js';
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const VERSION_RE = /^v[1-9][0-9]*$/;
+const DELAY_LABEL_RE = /^([1-9][0-9]*)([smh])$/;
+const NAMESPACE_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600 };
+/** Kafka limit for topic names. */
+export const MAX_TOPIC_LENGTH = 249;
+function requireKebab(value, field) {
+    if (typeof value !== 'string' || !KEBAB_RE.test(value)) {
+        throw new TypeError(`${pyRepr(field)} must be kebab-case (lowercase letters, digits, hyphens); got ${describe(value)}`);
+    }
+}
+function requireVersion(value) {
+    if (typeof value !== 'string' || !VERSION_RE.test(value)) {
+        throw new TypeError(`'version' must look like 'v1', 'v2', ...; got ${describe(value)}`);
+    }
+}
+function describe(value) {
+    return typeof value === 'string' ? pyRepr(value) : String(value);
+}
+function checkedTopic(name) {
+    if (name.length > MAX_TOPIC_LENGTH) {
+        throw new TypeError(`topic name exceeds ${MAX_TOPIC_LENGTH} characters: ${pyRepr(name)}`);
+    }
+    return name;
+}
+/**
+ * Validates the resource prefix (kebab-case); `null`/`undefined` → `null` (no prefix).
+ * Invalid → `TypeError` (Python: `ValueError`).
+ */
+export function resourcePrefix(value) {
+    if (value === null || value === undefined)
+        return null;
+    requireKebab(value, 'resourcePrefix');
+    return value;
+}
+function prefixed(name, options) {
+    const prefix = resourcePrefix(options?.resourcePrefix);
+    return prefix === null ? name : `${prefix}.${name}`;
+}
+/** `{domain}.events.{version}`; with a prefix, `{prefix}.{domain}.events.{version}`. */
+export function topic(domain, version, options) {
+    requireKebab(domain, 'domain');
+    requireVersion(version);
+    return checkedTopic(prefixed(`${domain}.events.${version}`, options));
+}
+/** `{aggregate}.{event}`; `event` is a fact in the past (`student.enrolled`). */
+export function eventType(aggregate, event) {
+    requireKebab(aggregate, 'aggregate');
+    requireKebab(event, 'event');
+    return `${aggregate}.${event}`;
+}
+/** Inverse of {@link eventType}; validates the format. */
+export function splitEventType(value) {
+    const index = typeof value === 'string' ? value.indexOf('.') : -1;
+    if (index < 0) {
+        throw new TypeError(`event_type must be '<aggregate>.<event>'; got ${describe(value)}`);
+    }
+    const aggregate = value.slice(0, index);
+    const event = value.slice(index + 1);
+    eventType(aggregate, event);
+    return [aggregate, event];
+}
+/** `student.enrolled` → `student-enrolled` (directory of the schema). */
+export function schemaSlug(eventTypeValue) {
+    const [aggregate, event] = splitEventType(eventTypeValue);
+    return `${aggregate}-${event}`;
+}
+/** 30000 → '30s', 120000 → '2m', 3600000 → '1h'. Uses the largest exact unit. */
+export function delayLabel(delayMs) {
+    if (typeof delayMs !== 'number' ||
+        !Number.isFinite(delayMs) ||
+        delayMs <= 0 ||
+        !Number.isInteger(delayMs / 1000)) {
+        throw new TypeError(`delay must be a positive whole number of seconds; got ${String(delayMs)}ms`);
+    }
+    const seconds = delayMs / 1000;
+    if (seconds % 3600 === 0)
+        return `${seconds / 3600}h`;
+    if (seconds % 60 === 0)
+        return `${seconds / 60}m`;
+    return `${seconds}s`;
+}
+/** Inverse of {@link delayLabel}: '2m' → 120000 (milliseconds). */
+export function parseDelayLabel(label) {
+    const match = typeof label === 'string' ? DELAY_LABEL_RE.exec(label) : null;
+    if (match === null)
+        throw new TypeError(`invalid delay label ${describe(label)}`);
+    return Number(match[1]) * (UNIT_SECONDS[match[2] ?? 's'] ?? 1) * 1000;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Regex source that matches the main topic and **all** retry topics of the group, including
+ * delays that left the `RetryPolicy` (no orphan retries).
+ *
+ * Same alternatives and anchors as Python's `retry_topic_pattern`; the escaping follows JS
+ * (`-` is not escaped), so the string is not byte-identical to Python's `re.escape` output.
+ */
+export function retryTopicPattern(mainTopic, group) {
+    requireKebab(group, 'group');
+    const main = escapeRegExp(mainTopic);
+    return `^${main}$|^${main}\\.${escapeRegExp(group)}\\.retry\\.[1-9][0-9]*[smh]$`;
+}
+/** Delay (ms) of a retry topic of the group, or `null` if it is not one. */
+export function retryDelayOf(topicName, mainTopic, group) {
+    const prefix = `${mainTopic}.${group}.retry.`;
+    if (!topicName.startsWith(prefix))
+        return null;
+    try {
+        return parseDelayLabel(topicName.slice(prefix.length));
+    }
+    catch {
+        return null;
+    }
+}
+/** `{main}.{group}.retry.{label}`. */
+export function retryTopic(mainTopic, group, delayMs) {
+    requireKebab(group, 'group');
+    return checkedTopic(`${mainTopic}.${group}.retry.${delayLabel(delayMs)}`);
+}
+/** `{main}.{group}.dlq`. */
+export function dlqTopic(mainTopic, group) {
+    requireKebab(group, 'group');
+    return checkedTopic(`${mainTopic}.${group}.dlq`);
+}
+/** Name of the producing service (header `producer`), kebab-case. */
+export function serviceName(service) {
+    requireKebab(service, 'service');
+    return service;
+}
+/**
+ * Prefix of the system/environment in a shared store (`hmgcatalogo_api`): 1-100 characters among
+ * letters, digits, `_`, `.`, `-`, starting with a letter or digit; no `:`.
+ */
+export function dedupNamespace(namespace) {
+    if (typeof namespace !== 'string' || !NAMESPACE_RE.test(namespace)) {
+        throw new TypeError("'namespace' must be 1-100 chars of letters, digits, '_', '.', '-'" +
+            ` starting with a letter or digit (no ':'); got ${describe(namespace)}`);
+    }
+    return namespace;
+}
+/** Kafka `group.id`: the validated logical name; with a prefix, `{prefix}.{group}`. */
+export function consumerGroup(group, options) {
+    requireKebab(group, 'group');
+    return prefixed(group, options);
+}
+//# sourceMappingURL=naming.js.map

package/dist/naming.js.map

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

package/dist/payload.d.ts

@@ -0,0 +1,8 @@
+/** Decoding of a consumed record value (spec §3). For the consumer and the DLQ replay. */
+import type { JsonObject } from './types.js';
+/**
+ * Value bytes → JSON object. Strict UTF-8 (a single leading BOM is ignored), strict JSON
+ * (no NaN/Infinity, no trailing garbage); duplicate keys: the last wins. Failures throw
+ * `InvalidPayloadError` with the exact spec messages, never quoting payload bytes.
+ */
+export declare function decodePayload(value: Uint8Array | null | undefined): JsonObject;

package/dist/payload.js

@@ -0,0 +1,32 @@
+/** Decoding of a consumed record value (spec §3). For the consumer and the DLQ replay. */
+import { InvalidPayloadError } from './errors.js';
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false });
+function jsonTypeName(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value; // string | number | boolean
+}
+/**
+ * Value bytes → JSON object. Strict UTF-8 (a single leading BOM is ignored), strict JSON
+ * (no NaN/Infinity, no trailing garbage); duplicate keys: the last wins. Failures throw
+ * `InvalidPayloadError` with the exact spec messages, never quoting payload bytes.
+ */
+export function decodePayload(value) {
+    if (value === null || value === undefined) {
+        throw new InvalidPayloadError('payload is empty (null record value)');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(strictUtf8.decode(value));
+    }
+    catch {
+        throw new InvalidPayloadError('payload is not valid UTF-8 JSON');
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        throw new InvalidPayloadError(`payload must be a JSON object; got ${jsonTypeName(payload)}`);
+    }
+    return payload;
+}
+//# sourceMappingURL=payload.js.map

package/dist/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../src/payload.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,UAAU,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAE/E,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,OAAO,OAAO,KAAK,CAAC,CAAC,4BAA4B;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAoC;IAChE,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,mBAAmB,CAAC,sCAAsC,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,mBAAmB,CAAC,iCAAiC,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,mBAAmB,CAAC,sCAAsC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,OAAqB,CAAC;AAC/B,CAAC"}