youeduc-sdk-messaging 0.0.0 → 0.5.0

package/dist/transport.js

@@ -0,0 +1,283 @@
+/**
+ * Send transport over the `@confluentinc/kafka-javascript` producer (KafkaJS-compatible API).
+ */
+import { NotStartedError, PublishError } from './errors.js';
+import { defaultLogger } from './logger.js';
+import { errorFields, errorMessage, formatSeconds, isPositiveFinite } from './util.js';
+/**
+ * Default factory: `new KafkaJS.Kafka().producer(config)` from `@confluentinc/kafka-javascript`.
+ * The native module is loaded on first use, so importing the SDK does not load librdkafka.
+ */
+export const createConfluentProducer = async (config) => {
+    const { KafkaJS } = (await import('@confluentinc/kafka-javascript')).default;
+    return new KafkaJS.Kafka({}).producer(config);
+};
+// ------------------------------------------------------------------------------ error classification
+/** librdkafka error codes (`ErrorCodes` of the client) used by the classification. */
+export const KafkaErrorCodes = Object.freeze({
+    ERR__MSG_TIMED_OUT: -192,
+    ERR__TIMED_OUT: -185,
+    ERR__QUEUE_FULL: -184,
+    ERR__TIMED_OUT_QUEUE: -166,
+    ERR__TRANSPORT: -195,
+    ERR__ALL_BROKERS_DOWN: -187,
+    ERR__UNKNOWN_TOPIC: -188,
+    ERR__RESOLVE: -193,
+    ERR_UNKNOWN_TOPIC_OR_PART: 3,
+    ERR_LEADER_NOT_AVAILABLE: 5,
+    ERR_NOT_LEADER_FOR_PARTITION: 6,
+    ERR_REQUEST_TIMED_OUT: 7,
+    ERR_MSG_SIZE_TOO_LARGE: 10,
+    ERR_NETWORK_EXCEPTION: 13,
+    ERR_TOPIC_EXCEPTION: 17,
+    ERR_RECORD_LIST_TOO_LARGE: 18,
+    ERR_NOT_ENOUGH_REPLICAS: 19,
+    ERR_NOT_ENOUGH_REPLICAS_AFTER_APPEND: 20,
+    ERR_TOPIC_AUTHORIZATION_FAILED: 29,
+    ERR_CLUSTER_AUTHORIZATION_FAILED: 31,
+    ERR_TOPIC_ALREADY_EXISTS: 36,
+    ERR_KAFKA_STORAGE_ERROR: 56,
+    ERR_FENCED_LEADER_EPOCH: 74,
+    ERR_UNKNOWN_LEADER_EPOCH: 75,
+});
+const C = KafkaErrorCodes;
+// Deterministic errors: repeating the same send does not help (Python: MessageSizeTooLargeError,
+// RecordTooLargeError, TopicAuthorizationFailedError, ClusterAuthorizationFailedError,
+// InvalidTopicError).
+const NON_RETRIABLE_CODES = new Set([
+    C.ERR_MSG_SIZE_TOO_LARGE,
+    C.ERR_RECORD_LIST_TOO_LARGE,
+    C.ERR_TOPIC_AUTHORIZATION_FAILED,
+    C.ERR_CLUSTER_AUTHORIZATION_FAILED,
+    C.ERR_TOPIC_EXCEPTION,
+]);
+// Timeouts are transient (Python: KafkaTimeoutError counts as retriable).
+const TIMEOUT_CODES = new Set([
+    C.ERR__MSG_TIMED_OUT,
+    C.ERR__TIMED_OUT,
+    C.ERR__TIMED_OUT_QUEUE,
+    C.ERR_REQUEST_TIMED_OUT,
+    C.ERR__QUEUE_FULL,
+]);
+// Transient broker/network conditions (Kafka's RetriableException family; aiokafka marks the
+// equivalent errors `retriable = True`). Used when the client does not flag retriability.
+const TRANSIENT_CODES = new Set([
+    C.ERR__TRANSPORT,
+    C.ERR__ALL_BROKERS_DOWN,
+    C.ERR__UNKNOWN_TOPIC,
+    C.ERR__RESOLVE,
+    C.ERR_UNKNOWN_TOPIC_OR_PART,
+    C.ERR_LEADER_NOT_AVAILABLE,
+    C.ERR_NOT_LEADER_FOR_PARTITION,
+    C.ERR_NETWORK_EXCEPTION,
+    C.ERR_NOT_ENOUGH_REPLICAS,
+    C.ERR_NOT_ENOUGH_REPLICAS_AFTER_APPEND,
+    C.ERR_KAFKA_STORAGE_ERROR,
+    C.ERR_FENCED_LEADER_EPOCH,
+    C.ERR_UNKNOWN_LEADER_EPOCH,
+]);
+/**
+ * Whether the value is an error raised by the Kafka client: `KafkaJSError` family (`name`
+ * starting with `KafkaJS`) or the raw `LibrdKafkaError` (`origin` `local`/`kafka`), both with
+ * a numeric librdkafka `code`.
+ */
+export function isKafkaClientError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const shape = error;
+    if (typeof shape.code !== 'number')
+        return false;
+    return ((typeof shape.name === 'string' && shape.name.startsWith('KafkaJS')) ||
+        shape.origin === 'local' ||
+        shape.origin === 'kafka' ||
+        typeof shape.isRetriable === 'boolean');
+}
+/**
+ * Whether repeating the send may work (Python `is_retriable`): deterministic errors (message
+ * too large, authorization, invalid topic) → `false`; timeouts → `true`; otherwise the
+ * client's own flag, then the known transient broker/network codes; anything else → `false`.
+ */
+export function isRetriable(error) {
+    if (!isKafkaClientError(error))
+        return false;
+    if (NON_RETRIABLE_CODES.has(error.code))
+        return false;
+    if (TIMEOUT_CODES.has(error.code))
+        return true;
+    if (error.isRetriable === true || error.retriable === true)
+        return true;
+    return TRANSIENT_CODES.has(error.code);
+}
+/** Converts the ordered header list to the KafkaJS object form (repeated names → arrays). */
+/**
+ * Largest record the SDK producers accept, in bytes (§11): the same limit as the Python SDK
+ * (aiokafka's `max_request_size`). librdkafka's own default (`message.max.bytes` = 1000000) would
+ * reject records that Python publishes, and a consumer routing one of them to retry/DLQ would stop.
+ */
+export const MAX_MESSAGE_BYTES = 1_048_576;
+/**
+ * Producer settings shared by {@link KafkaProducerSender} and `replayDlq` (§11): idempotent,
+ * `acks=all`, Java-compatible murmur2 partitioner and the {@link MAX_MESSAGE_BYTES} limit.
+ */
+export function producerClientConfig(config) {
+    return {
+        ...config.clientConfig(),
+        'enable.idempotence': true,
+        acks: -1,
+        // Java-compatible murmur2 (NULL key → random), the same partitioner as aiokafka (§11): a keyed
+        // message lands on the same partition whichever SDK publishes it. Without a `kafkaJS` block
+        // the confluent client keeps librdkafka's default (`consistent_random`, CRC32): set it here.
+        partitioner: 'murmur2_random',
+        'message.max.bytes': MAX_MESSAGE_BYTES,
+    };
+}
+export function toProducerHeaders(headers) {
+    const result = Object.create(null);
+    for (const [name, value] of headers) {
+        const existing = result[name];
+        if (existing === undefined)
+            result[name] = value;
+        else if (Array.isArray(existing))
+            existing.push(value);
+        else
+            result[name] = [existing, value];
+    }
+    return result;
+}
+function parseOffset(metadata) {
+    const raw = metadata.baseOffset ?? metadata.offset;
+    const value = raw === undefined ? Number.NaN : Number(raw);
+    return Number.isFinite(value) ? value : -1;
+}
+/**
+ * {@link MessageSender} with an idempotent producer (`acks=all`, `enable.idempotence=true`,
+ * `partitioner=murmur2_random`: keyed messages are partitioned like the Python SDK and Java).
+ *
+ * A single producer is shared by every send (no connection per message). No manual retry: the
+ * idempotent producer retries internally without duplicating. A timeout in `send` does not
+ * guarantee the message was not written (it may still be in the producer buffer):
+ * at-least-once semantics.
+ */
+export class KafkaProducerSender {
+    #config;
+    #sendTimeoutMs;
+    #lingerMs;
+    #compressionType;
+    #factory;
+    #logger;
+    #producer = null;
+    #lock = Promise.resolve();
+    constructor(config, options = {}) {
+        const sendTimeoutMs = options.sendTimeoutMs ?? 30_000;
+        const lingerMs = options.lingerMs ?? 5;
+        if (!isPositiveFinite(sendTimeoutMs)) {
+            throw new RangeError(`'send_timeout_ms' must be a finite number > 0; got ${String(sendTimeoutMs)}`);
+        }
+        if (!Number.isInteger(lingerMs) || lingerMs < 0) {
+            throw new RangeError(`'linger_ms' must be >= 0; got ${String(lingerMs)}`);
+        }
+        this.#config = config;
+        this.#sendTimeoutMs = sendTimeoutMs;
+        this.#lingerMs = lingerMs;
+        this.#compressionType = options.compressionType ?? 'none';
+        this.#factory = options.producerFactory ?? createConfluentProducer;
+        this.#logger = options.logger;
+    }
+    get started() {
+        return this.#producer !== null;
+    }
+    /** Final librdkafka configuration handed to the producer factory. */
+    producerConfig() {
+        return {
+            ...producerClientConfig(this.#config),
+            'linger.ms': this.#lingerMs,
+            'compression.type': this.#compressionType,
+        };
+    }
+    #exclusive(fn) {
+        const run = this.#lock.then(fn);
+        this.#lock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** Creates and connects the producer. Idempotent; after `stop()` creates a new one. */
+    start() {
+        return this.#exclusive(async () => {
+            if (this.#producer !== null)
+                return;
+            const producer = await this.#factory(this.producerConfig());
+            try {
+                await producer.connect();
+            }
+            catch (error) {
+                // Release what a failed connect may have allocated.
+                await this.#disconnectQuietly(producer);
+                throw error;
+            }
+            this.#producer = producer;
+        });
+    }
+    /** Flushes the buffer and disconnects the producer. Idempotent. */
+    stop() {
+        return this.#exclusive(async () => {
+            const producer = this.#producer;
+            this.#producer = null;
+            if (producer !== null)
+                await producer.disconnect();
+        });
+    }
+    async send(topic, value, options) {
+        const producer = this.#producer;
+        if (producer === null)
+            throw new NotStartedError('KafkaProducerSender is not started');
+        let timer;
+        let pending;
+        try {
+            // Everything inside the same try: the client may fail before queueing (sync throw).
+            pending = producer.send({
+                topic,
+                messages: [{ key: options.key, value, headers: toProducerHeaders(options.headers) }],
+            });
+        }
+        catch (error) {
+            pending = Promise.reject(error);
+        }
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new PublishError(topic, `no broker acknowledgement within ${formatSeconds(this.#sendTimeoutMs)}s`, {
+                    retriable: true,
+                }));
+            }, this.#sendTimeoutMs);
+        });
+        // After a timeout the delivery may still settle: never leave it unhandled.
+        pending.catch(() => undefined);
+        let metadata;
+        try {
+            metadata = await Promise.race([pending, timeout]);
+        }
+        catch (error) {
+            if (error instanceof PublishError)
+                throw error;
+            if (isKafkaClientError(error)) {
+                throw new PublishError(topic, errorMessage(error), { retriable: isRetriable(error), cause: error });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const record = metadata[0];
+        if (record === undefined) {
+            throw new PublishError(topic, 'broker returned no delivery report', { retriable: true });
+        }
+        return { topic: record.topicName, partition: record.partition, offset: parseOffset(record) };
+    }
+    async #disconnectQuietly(producer) {
+        try {
+            await producer.disconnect();
+        }
+        catch (error) {
+            (this.#logger ?? defaultLogger()).warn('kafka_producer_stop_failed', { error: errorFields(error) });
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Shared contracts (data types and interfaces), mirroring Python's `types.py`. No Kafka client
+ * dependency: implementations (and test fakes) are interchangeable through these interfaces.
+ */
+import type { KafkaHeaders, MessageHeaders } from './headers.js';
+export type ConsumeOutcome = 'success' | 'retry' | 'dlq' | 'deduplicated' | 'skipped';
+export type DlqReason = 'permanent_error' | 'max_retries' | 'invalid_payload' | 'schema_error' | 'routing_failed';
+export type PublishStatus = 'success' | 'error';
+export declare const CONSUME_OUTCOMES: readonly ConsumeOutcome[];
+export declare const DLQ_REASONS: readonly DlqReason[];
+/** A JSON object (schemas and payloads). */
+export type JsonObject = Record<string, unknown>;
+export interface PublishResult {
+    readonly messageId: string;
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: number;
+}
+export interface ConsumedMessage {
+    readonly messageId: string;
+    readonly eventType: string;
+    readonly schemaVersion: string;
+    readonly payload: JsonObject;
+    readonly key: string | null;
+    readonly correlationId: string;
+    readonly idempotencyKey: string | null;
+    readonly tenantId: string | null;
+    readonly producer: string;
+    readonly publishedAt: string;
+    /** Number of previous retries (0 on the first delivery). */
+    readonly retryCount: number;
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: number;
+    readonly headers: Readonly<MessageHeaders>;
+}
+/**
+ * Resolving = success. Rejecting with `PermanentProcessingError` = DLQ. Any other rejection =
+ * retry. The `signal` is aborted when the consumer gives up on the handler (processing timeout
+ * or shutdown deadline); handlers should stop their work when it fires.
+ */
+export type MessageHandler = (message: ConsumedMessage, signal: AbortSignal) => Promise<void>;
+export interface SentRecord {
+    readonly topic: string;
+    readonly partition: number;
+    readonly offset: number;
+}
+export interface SendOptions {
+    key: Buffer | null;
+    headers: KafkaHeaders;
+}
+export interface MessageSender {
+    /** Sends and waits for the broker ack. Failure → `PublishError`. */
+    send(topic: string, value: Buffer, options: SendOptions): Promise<SentRecord>;
+}
+export interface SchemaLoader {
+    /** `event` is the slug (`student-enrolled`). Missing → `SchemaNotFoundError`. */
+    load(domain: string, event: string, version: string): JsonObject;
+}
+export interface SchemaValidator {
+    /** Invalid → `SchemaValidationError` (no payload values in the message). */
+    validate(payload: unknown): void;
+}
+export type SchemaValidatorFactory = (schema: JsonObject) => SchemaValidator;
+export interface PayloadValidationRequest {
+    domain: string;
+    eventType: string;
+    version: string;
+    payload: unknown;
+}
+/** Validates an event payload; implemented by `SchemaRegistry`. */
+export interface PayloadValidator {
+    /** `SchemaNotFoundError` / `SchemaValidationError` when invalid. */
+    validate(request: PayloadValidationRequest): void;
+}
+/**
+ * Two-phase deduplication: query before, mark only after the handler succeeded. Retry and DLQ
+ * never mark: retries come back and the DLQ may be reprocessed.
+ */
+export interface DuplicateChecker {
+    isProcessed(key: string): Promise<boolean>;
+    markProcessed(key: string): Promise<void>;
+}
+/** Common attributes of spans and metrics. Never contains the payload (PII). */
+export interface MessageInfo {
+    readonly topic: string;
+    readonly eventType: string;
+    readonly messageId: string;
+    readonly schemaVersion: string;
+    /** Kept for the SDK's own use (`has_key` in logs); never emitted in spans/metrics/logs. */
+    readonly key: string | null;
+    readonly correlationId: string | null;
+    readonly tenantId: string | null;
+    readonly partition: number | null;
+    readonly offset: number | null;
+    readonly group: string | null;
+    readonly retryCount: number;
+}
+export interface MessageInfoInit {
+    topic: string;
+    eventType: string;
+    messageId: string;
+    schemaVersion?: string | undefined;
+    key?: string | null | undefined;
+    correlationId?: string | null | undefined;
+    tenantId?: string | null | undefined;
+    partition?: number | null | undefined;
+    offset?: number | null | undefined;
+    group?: string | null | undefined;
+    retryCount?: number | undefined;
+}
+/** Builds a frozen {@link MessageInfo} applying the same defaults as Python's dataclass. */
+export declare function createMessageInfo(init: MessageInfoInit): MessageInfo;
+export interface ConsumeSpan {
+    setOutcome(outcome: ConsumeOutcome): void;
+    recordError(error: unknown): void;
+}
+export interface PublishRecord {
+    status: PublishStatus;
+    durationMs: number;
+}
+export interface ConsumeRecord {
+    outcome: ConsumeOutcome;
+    durationMs: number;
+}
+export interface RetryRecord {
+    attempt: number;
+    retryTopic: string;
+}
+export interface DlqRecord {
+    reason: DlqReason;
+    dlqTopic: string;
+}
+/**
+ * Spans and metrics. The span methods replace Python's context managers: they run `fn` inside
+ * the span (active context), record a thrown error on it, end it and return/rethrow.
+ */
+export interface Telemetry {
+    /** PRODUCER span `send {topic}`; injects the W3C context into `headers` (mutates) before `fn`. */
+    publishSpan<T>(info: MessageInfo, headers: MessageHeaders, fn: () => Promise<T>): Promise<T>;
+    /** CONSUMER span `process {topic}` whose parent is extracted from `headers`. */
+    consumeSpan<T>(info: MessageInfo, headers: Readonly<MessageHeaders>, fn: (span: ConsumeSpan) => Promise<T>): Promise<T>;
+    recordPublish(info: MessageInfo, record: PublishRecord): void;
+    recordSchemaError(info: MessageInfo): void;
+    recordConsume(info: MessageInfo, record: ConsumeRecord): void;
+    recordRetry(info: MessageInfo, record: RetryRecord): void;
+    recordDlq(info: MessageInfo, record: DlqRecord): void;
+}

package/dist/types.js

@@ -0,0 +1,35 @@
+/**
+ * Shared contracts (data types and interfaces), mirroring Python's `types.py`. No Kafka client
+ * dependency: implementations (and test fakes) are interchangeable through these interfaces.
+ */
+export const CONSUME_OUTCOMES = [
+    'success',
+    'retry',
+    'dlq',
+    'deduplicated',
+    'skipped',
+];
+export const DLQ_REASONS = [
+    'permanent_error',
+    'max_retries',
+    'invalid_payload',
+    'schema_error',
+    'routing_failed',
+];
+/** Builds a frozen {@link MessageInfo} applying the same defaults as Python's dataclass. */
+export function createMessageInfo(init) {
+    return Object.freeze({
+        topic: init.topic,
+        eventType: init.eventType,
+        messageId: init.messageId,
+        schemaVersion: init.schemaVersion ?? '',
+        key: init.key ?? null,
+        correlationId: init.correlationId ?? null,
+        tenantId: init.tenantId ?? null,
+        partition: init.partition ?? null,
+        offset: init.offset ?? null,
+        group: init.group ?? null,
+        retryCount: init.retryCount ?? 0,
+    });
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,MAAM,CAAC,MAAM,gBAAgB,GAA8B;IACzD,SAAS;IACT,OAAO;IACP,KAAK;IACL,cAAc;IACd,SAAS;CACV,CAAC;AACF,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,iBAAiB;IACjB,aAAa;IACb,iBAAiB;IACjB,cAAc;IACd,gBAAgB;CACjB,CAAC;AAgIF,4FAA4F;AAC5F,MAAM,UAAU,iBAAiB,CAAC,IAAqB;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,EAAE;QACvC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,IAAI;QACrB,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI;QACzC,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;QAC/B,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;QACjC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;QAC3B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;QACzB,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC;KACjC,CAAC,CAAC;AACL,CAAC"}

package/dist/util.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Internal helpers shared by the modules (not part of the public API).
+ *
+ * Several of them exist only to keep texts and formats byte-compatible with the Python SDK
+ * (`repr()` quoting in error messages, character counting by code point, ISO 8601 timestamps
+ * in the shape produced by `datetime.isoformat()`).
+ */
+/**
+ * Python `repr()` of a string: single quotes unless the text contains `'` and no `"`; escapes
+ * backslash, the chosen quote, `\n`, `\r`, `\t` and non-printable control characters.
+ */
+export declare function pyRepr(value: string): string;
+/**
+ * A duration in milliseconds written in seconds as it appears in error texts (§15), the same in
+ * both SDKs: the shortest positional decimal of the value, no exponent (`20000` → `"20"`,
+ * `500` → `"0.5"`, `0.05` → `"0.00005"`).
+ */
+export declare function formatSeconds(ms: number): string;
+/** Truncates to `max` characters counted by Unicode code point (like Python `str[:max]`). */
+export declare function truncateChars(value: string, max: number): string;
+/**
+ * Name of the error "class" (spec §4.3 `x-last-error-type`): `error.name` (the SDK errors set
+ * it to their class name); a thrown value that is not an `Error` → `'Error'`.
+ */
+export declare function errorTypeName(error: unknown): string;
+/** Text of the error, the equivalent of Python `str(exc)`. */
+export declare function errorMessage(error: unknown): string;
+/** `{type, message}` grouping used in the `error` field of the logs. */
+export declare function errorFields(error: unknown, maxLength?: number): {
+    type: string;
+    message: string;
+};
+/** RFC 3339 UTC as written by the Node SDK (spec §4.1): `2026-10-06T12:34:56.789Z`. */
+export declare function formatIsoUtc(epochMs: number): string;
+/** Plain JSON object (prototype `Object.prototype` or `null`). */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Finite number strictly greater than zero. */
+export declare function isPositiveFinite(value: unknown): value is number;

package/dist/util.js

@@ -0,0 +1,112 @@
+/**
+ * Internal helpers shared by the modules (not part of the public API).
+ *
+ * Several of them exist only to keep texts and formats byte-compatible with the Python SDK
+ * (`repr()` quoting in error messages, character counting by code point, ISO 8601 timestamps
+ * in the shape produced by `datetime.isoformat()`).
+ */
+/**
+ * Python `repr()` of a string: single quotes unless the text contains `'` and no `"`; escapes
+ * backslash, the chosen quote, `\n`, `\r`, `\t` and non-printable control characters.
+ */
+export function pyRepr(value) {
+    const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+    let out = quote;
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        if (char === '\\')
+            out += '\\\\';
+        else if (char === quote)
+            out += `\\${quote}`;
+        else if (char === '\n')
+            out += '\\n';
+        else if (char === '\r')
+            out += '\\r';
+        else if (char === '\t')
+            out += '\\t';
+        else if (code < 0x20 || (code >= 0x7f && code <= 0xa0))
+            out += `\\x${code.toString(16).padStart(2, '0')}`;
+        else
+            out += char;
+    }
+    return out + quote;
+}
+/**
+ * A duration in milliseconds written in seconds as it appears in error texts (§15), the same in
+ * both SDKs: the shortest positional decimal of the value, no exponent (`20000` → `"20"`,
+ * `500` → `"0.5"`, `0.05` → `"0.00005"`).
+ */
+export function formatSeconds(ms) {
+    const text = String(ms / 1000);
+    const match = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/.exec(text);
+    if (match === null)
+        return text;
+    const [, sign = '', int = '', frac = '', exponent = '0'] = match;
+    const digits = int + frac;
+    const point = int.length + Number(exponent);
+    if (point <= 0)
+        return `${sign}0.${'0'.repeat(-point)}${digits}`;
+    if (point >= digits.length)
+        return sign + digits + '0'.repeat(point - digits.length);
+    return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+/** Truncates to `max` characters counted by Unicode code point (like Python `str[:max]`). */
+export function truncateChars(value, max) {
+    if (value.length <= max)
+        return value; // UTF-16 length >= code point count
+    let count = 0;
+    let end = 0;
+    for (const char of value) {
+        if (count === max)
+            break;
+        count += 1;
+        end += char.length;
+    }
+    return value.slice(0, end);
+}
+/**
+ * Name of the error "class" (spec §4.3 `x-last-error-type`): `error.name` (the SDK errors set
+ * it to their class name); a thrown value that is not an `Error` → `'Error'`.
+ */
+export function errorTypeName(error) {
+    if (error instanceof Error)
+        return error.name || 'Error';
+    return 'Error';
+}
+/** Text of the error, the equivalent of Python `str(exc)`. */
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    try {
+        return String(error);
+    }
+    catch {
+        return '';
+    }
+}
+/** `{type, message}` grouping used in the `error` field of the logs. */
+export function errorFields(error, maxLength) {
+    const message = errorMessage(error);
+    return {
+        type: errorTypeName(error),
+        message: maxLength === undefined ? message : truncateChars(message, maxLength),
+    };
+}
+/** RFC 3339 UTC as written by the Node SDK (spec §4.1): `2026-10-06T12:34:56.789Z`. */
+export function formatIsoUtc(epochMs) {
+    return new Date(epochMs).toISOString();
+}
+/** Plain JSON object (prototype `Object.prototype` or `null`). */
+export function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Finite number strictly greater than zero. */
+export function isPositiveFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

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

package/dist/w3c.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal W3C Trace Context (`traceparent`/`tracestate`) + W3C Baggage propagator, built only
+ * on `@opentelemetry/api`.
+ *
+ * Python's OpenTelemetry API defaults the global propagator to `tracecontext,baggage`; the JS
+ * API defaults to a no-op propagator until an SDK registers one. `OtelTelemetry` falls back to
+ * this propagator while the global one is the no-op, so a Node service propagates trace context
+ * exactly like a Python one even when the application only set a tracer provider.
+ */
+import { type Context, type TextMapGetter, type TextMapPropagator, type TextMapSetter } from '@opentelemetry/api';
+/** W3C `traceparent`, `tracestate` and `baggage`. */
+export declare class W3CPropagator implements TextMapPropagator {
+    inject(context: Context, carrier: unknown, setter: TextMapSetter): void;
+    extract(context: Context, carrier: unknown, getter: TextMapGetter): Context;
+    fields(): string[];
+}