@drarzter/kafka-client 0.10.0 → 0.11.0

package/dist/chunk-PQVBRDNV.mjs

@@ -0,0 +1,149 @@
+// src/client/message/serde.ts
+var JsonSerde = class {
+  /** JSON-stringify the validated payload. Returns a UTF-8 string. */
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  /** JSON-parse UTF-8 wire bytes into an object. */
+  deserialize(data) {
+    return JSON.parse(data.toString("utf8"));
+  }
+};
+
+// src/client/message/schema-registry.ts
+var SchemaRegistryClient = class {
+  constructor(options) {
+    this.options = options;
+    if (!options.baseUrl) {
+      throw new Error("SchemaRegistryClient: baseUrl is required");
+    }
+    this.fetchFn = options.fetchFn ?? fetch;
+    this.cacheTtlMs = options.cacheTtlMs ?? 3e5;
+  }
+  options;
+  fetchFn;
+  cacheTtlMs;
+  latestCache = /* @__PURE__ */ new Map();
+  /**
+   * `id → schema` cache. Schema ids are immutable in a Confluent-compatible
+   * registry (a given id always maps to the same schema string), so entries
+   * are cached for the lifetime of the client with no TTL.
+   */
+  byIdCache = /* @__PURE__ */ new Map();
+  headers() {
+    const h = {
+      "Content-Type": "application/vnd.schemaregistry.v1+json"
+    };
+    if (this.options.auth) {
+      const { username, password } = this.options.auth;
+      h["Authorization"] = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+    }
+    return h;
+  }
+  async request(method, path, body) {
+    const url = `${this.options.baseUrl.replace(/\/$/, "")}${path}`;
+    const res = await this.fetchFn(url, {
+      method,
+      headers: this.headers(),
+      ...body !== void 0 && { body: JSON.stringify(body) }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(
+        `SchemaRegistry ${method} ${path} failed: ${res.status} ${res.statusText}${text ? ` \u2014 ${text}` : ""}`
+      );
+    }
+    return await res.json();
+  }
+  /** Fetch the latest schema registered under `subject`. Cached for `cacheTtlMs`. */
+  async getLatestSchema(subject) {
+    const cached = this.latestCache.get(subject);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
+    const raw = await this.request("GET", `/subjects/${encodeURIComponent(subject)}/versions/latest`);
+    const value = {
+      id: raw.id,
+      version: raw.version,
+      schema: raw.schema
+    };
+    this.latestCache.set(subject, {
+      value,
+      expiresAt: Date.now() + this.cacheTtlMs
+    });
+    return value;
+  }
+  /**
+   * Fetch a schema by its globally unique registry id (`GET /schemas/ids/{id}`).
+   *
+   * Used by the Avro/Protobuf serdes on the deserialize path: the writer schema
+   * id is read from the Confluent wire-format prefix, then resolved here. Results
+   * are cached forever (schema ids are immutable), so a given id triggers exactly
+   * one registry round-trip regardless of how many messages reference it.
+   */
+  async getSchemaById(id) {
+    const cached = this.byIdCache.get(id);
+    if (cached) return cached;
+    const raw = await this.request(
+      "GET",
+      `/schemas/ids/${id}`
+    );
+    const value = { id, schema: raw.schema, schemaType: raw.schemaType };
+    this.byIdCache.set(id, value);
+    return value;
+  }
+  /** Fetch a specific schema version of a subject. */
+  async getSchemaVersion(subject, version) {
+    const raw = await this.request(
+      "GET",
+      `/subjects/${encodeURIComponent(subject)}/versions/${version}`
+    );
+    return { id: raw.id, version: raw.version, schema: raw.schema };
+  }
+  /**
+   * Register a schema under `subject` (idempotent — re-registering the same
+   * schema returns the existing id). Returns the registry-assigned schema id.
+   */
+  async registerSchema(subject, schema, schemaType = "JSON") {
+    this.latestCache.delete(subject);
+    return this.request(
+      "POST",
+      `/subjects/${encodeURIComponent(subject)}/versions`,
+      { schema, schemaType }
+    );
+  }
+  /**
+   * Test `schema` against the subject's compatibility policy without registering.
+   * Returns `true` when the registry reports the schema as compatible.
+   */
+  async checkCompatibility(subject, schema, schemaType = "JSON") {
+    const res = await this.request(
+      "POST",
+      `/compatibility/subjects/${encodeURIComponent(subject)}/versions/latest`,
+      { schema, schemaType }
+    );
+    return res.is_compatible;
+  }
+};
+function registrySchema(client, subject, options) {
+  const enforceVersion = options?.enforceVersion ?? true;
+  return {
+    async parse(data, ctx) {
+      const latest = await client.getLatestSchema(subject);
+      if (enforceVersion && ctx?.version !== void 0 && ctx.version > latest.version) {
+        throw new Error(
+          `registrySchema: message version ${ctx.version} for subject "${subject}" is newer than the latest registered version ${latest.version} \u2014 register the schema before producing with it`
+        );
+      }
+      if (options?.validator) {
+        return options.validator.parse(data, ctx);
+      }
+      return data;
+    }
+  };
+}
+
+export {
+  JsonSerde,
+  SchemaRegistryClient,
+  registrySchema
+};
+//# sourceMappingURL=chunk-PQVBRDNV.mjs.map

package/dist/chunk-PQVBRDNV.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client/message/serde.ts","../src/client/message/schema-registry.ts"],"sourcesContent":["import type { MessageHeaders } from \"../types\";\n\n/**\n * Context passed to `MessageSerde.serialize` / `deserialize`.\n *\n * Carries the topic name, decoded message headers, and which side of the\n * record is being (de)serialized. A Confluent Schema Registry serde uses\n * `topic` + `isKey` to derive the subject name (`<topic>-value` / `<topic>-key`)\n * and reads the schema id from the header/magic-byte prefix on `data`.\n */\nexport interface SerdeContext {\n  /** Topic the message is produced to / consumed from. */\n  topic: string;\n  /** Decoded message headers (envelope headers included). */\n  headers: MessageHeaders;\n  /**\n   * Which side of the Kafka record this call is (de)serializing.\n   * `false` / omitted → the value (default); `true` → the key.\n   * Used by schema-registry serdes to pick the `value` vs `key` subject.\n   */\n  isKey?: boolean;\n}\n\n/**\n * Pluggable serialization layer for message payloads.\n *\n * A `MessageSerde` converts a validated payload object to the wire form\n * (`Buffer` or `string`) on produce, and back to an object on consume.\n * The default is {@link JsonSerde}, which reproduces the client's historical\n * `JSON.stringify` / `JSON.parse` behaviour exactly.\n *\n * Serde only touches the message VALUE. Envelope metadata\n * (`x-event-id`, `x-correlation-id`, `x-lamport-clock`, `traceparent`, …)\n * always travels in headers and is never serialized through this layer.\n *\n * Set a client-wide serde via `KafkaClientOptions.serde`, or a per-topic\n * override via `topic(...).serde(mySerde)` — the per-topic serde wins for\n * that topic.\n *\n * @example\n * ```ts\n * const kafka = new KafkaClient(id, group, brokers, { serde: new JsonSerde() });\n * ```\n */\nexport interface MessageSerde {\n  /**\n   * Serialize a validated payload object to wire bytes (`Buffer`) or a\n   * `string`. Validation has already run on `value` before this is called.\n   */\n  serialize(\n    value: unknown,\n    ctx: SerdeContext,\n  ): Buffer | string | Promise<Buffer | string>;\n  /**\n   * Deserialize raw wire bytes into a payload object. Schema validation\n   * (if any) runs on the returned object afterwards.\n   */\n  deserialize(data: Buffer, ctx: SerdeContext): unknown | Promise<unknown>;\n}\n\n/**\n * Default {@link MessageSerde}: JSON via `JSON.stringify` / `JSON.parse`.\n *\n * Byte-for-byte identical to the client's historical serialization, so it is\n * a zero-behaviour-change default. Produces a UTF-8 `string` on serialize and\n * decodes UTF-8 bytes on deserialize.\n */\nexport class JsonSerde implements MessageSerde {\n  /** JSON-stringify the validated payload. Returns a UTF-8 string. */\n  serialize(value: unknown): string {\n    return JSON.stringify(value);\n  }\n\n  /** JSON-parse UTF-8 wire bytes into an object. */\n  deserialize(data: Buffer): unknown {\n    return JSON.parse(data.toString(\"utf8\"));\n  }\n}\n","import type { SchemaLike, SchemaParseContext } from \"./topic\";\n\n/** A schema registered in a Confluent-compatible Schema Registry. */\nexport interface RegisteredSchema {\n  /** Globally unique schema id assigned by the registry. */\n  id: number;\n  /** Version of the schema within its subject. */\n  version: number;\n  /** The schema definition string (JSON Schema / Avro / Protobuf source). */\n  schema: string;\n}\n\n/** Options for `SchemaRegistryClient`. */\nexport interface SchemaRegistryClientOptions {\n  /** Registry base URL, e.g. `http://localhost:8081` or a Confluent Cloud SR endpoint. */\n  baseUrl: string;\n  /** HTTP Basic credentials (Confluent Cloud SR API key/secret). */\n  auth?: { username: string; password: string };\n  /** Cache TTL for subject lookups in ms. Default: `300_000` (5 min). */\n  cacheTtlMs?: number;\n  /** Injectable fetch implementation (tests). Default: global `fetch`. */\n  fetchFn?: typeof fetch;\n}\n\n/** Schema type accepted by Confluent-compatible registries. */\nexport type RegistrySchemaType = \"JSON\" | \"AVRO\" | \"PROTOBUF\";\n\n/**\n * Minimal, dependency-free client for the Confluent Schema Registry REST API\n * (works with Confluent Platform/Cloud, Redpanda, Karapace, AWS Glue SR proxy).\n *\n * Scope: subject/version management, compatibility checks, and id->schema\n * lookups. Used to keep locally-defined schemas in lockstep with a central\n * registry, and as the backing lookup for the Avro/Protobuf serdes in\n * `@drarzter/kafka-client/serde` (which handle the wire-format framing).\n *\n * @example\n * ```ts\n * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });\n * const { id } = await registry.registerSchema(\n *   'order.created-value',\n *   JSON.stringify(orderJsonSchema),\n *   'JSON',\n * );\n * ```\n */\nexport class SchemaRegistryClient {\n  private readonly fetchFn: typeof fetch;\n  private readonly cacheTtlMs: number;\n  private readonly latestCache = new Map<\n    string,\n    { value: RegisteredSchema; expiresAt: number }\n  >();\n  /**\n   * `id → schema` cache. Schema ids are immutable in a Confluent-compatible\n   * registry (a given id always maps to the same schema string), so entries\n   * are cached for the lifetime of the client with no TTL.\n   */\n  private readonly byIdCache = new Map<\n    number,\n    { id: number; schema: string; schemaType?: string }\n  >();\n\n  constructor(private readonly options: SchemaRegistryClientOptions) {\n    if (!options.baseUrl) {\n      throw new Error(\"SchemaRegistryClient: baseUrl is required\");\n    }\n    this.fetchFn = options.fetchFn ?? fetch;\n    this.cacheTtlMs = options.cacheTtlMs ?? 300_000;\n  }\n\n  private headers(): Record<string, string> {\n    const h: Record<string, string> = {\n      \"Content-Type\": \"application/vnd.schemaregistry.v1+json\",\n    };\n    if (this.options.auth) {\n      const { username, password } = this.options.auth;\n      h[\"Authorization\"] =\n        \"Basic \" + Buffer.from(`${username}:${password}`).toString(\"base64\");\n    }\n    return h;\n  }\n\n  private async request<R>(\n    method: \"GET\" | \"POST\",\n    path: string,\n    body?: unknown,\n  ): Promise<R> {\n    const url = `${this.options.baseUrl.replace(/\\/$/, \"\")}${path}`;\n    const res = await this.fetchFn(url, {\n      method,\n      headers: this.headers(),\n      ...(body !== undefined && { body: JSON.stringify(body) }),\n    });\n    if (!res.ok) {\n      const text = await res.text().catch(() => \"\");\n      throw new Error(\n        `SchemaRegistry ${method} ${path} failed: ${res.status} ${res.statusText}${text ? ` — ${text}` : \"\"}`,\n      );\n    }\n    return (await res.json()) as R;\n  }\n\n  /** Fetch the latest schema registered under `subject`. Cached for `cacheTtlMs`. */\n  async getLatestSchema(subject: string): Promise<RegisteredSchema> {\n    const cached = this.latestCache.get(subject);\n    if (cached && cached.expiresAt > Date.now()) return cached.value;\n    const raw = await this.request<{\n      id: number;\n      version: number;\n      schema: string;\n    }>(\"GET\", `/subjects/${encodeURIComponent(subject)}/versions/latest`);\n    const value: RegisteredSchema = {\n      id: raw.id,\n      version: raw.version,\n      schema: raw.schema,\n    };\n    this.latestCache.set(subject, {\n      value,\n      expiresAt: Date.now() + this.cacheTtlMs,\n    });\n    return value;\n  }\n\n  /**\n   * Fetch a schema by its globally unique registry id (`GET /schemas/ids/{id}`).\n   *\n   * Used by the Avro/Protobuf serdes on the deserialize path: the writer schema\n   * id is read from the Confluent wire-format prefix, then resolved here. Results\n   * are cached forever (schema ids are immutable), so a given id triggers exactly\n   * one registry round-trip regardless of how many messages reference it.\n   */\n  async getSchemaById(\n    id: number,\n  ): Promise<{ id: number; schema: string; schemaType?: string }> {\n    const cached = this.byIdCache.get(id);\n    if (cached) return cached;\n    const raw = await this.request<{ schema: string; schemaType?: string }>(\n      \"GET\",\n      `/schemas/ids/${id}`,\n    );\n    const value = { id, schema: raw.schema, schemaType: raw.schemaType };\n    this.byIdCache.set(id, value);\n    return value;\n  }\n\n  /** Fetch a specific schema version of a subject. */\n  async getSchemaVersion(\n    subject: string,\n    version: number,\n  ): Promise<RegisteredSchema> {\n    const raw = await this.request<{\n      id: number;\n      version: number;\n      schema: string;\n    }>(\n      \"GET\",\n      `/subjects/${encodeURIComponent(subject)}/versions/${version}`,\n    );\n    return { id: raw.id, version: raw.version, schema: raw.schema };\n  }\n\n  /**\n   * Register a schema under `subject` (idempotent — re-registering the same\n   * schema returns the existing id). Returns the registry-assigned schema id.\n   */\n  async registerSchema(\n    subject: string,\n    schema: string,\n    schemaType: RegistrySchemaType = \"JSON\",\n  ): Promise<{ id: number }> {\n    this.latestCache.delete(subject);\n    return this.request<{ id: number }>(\n      \"POST\",\n      `/subjects/${encodeURIComponent(subject)}/versions`,\n      { schema, schemaType },\n    );\n  }\n\n  /**\n   * Test `schema` against the subject's compatibility policy without registering.\n   * Returns `true` when the registry reports the schema as compatible.\n   */\n  async checkCompatibility(\n    subject: string,\n    schema: string,\n    schemaType: RegistrySchemaType = \"JSON\",\n  ): Promise<boolean> {\n    const res = await this.request<{ is_compatible: boolean }>(\n      \"POST\",\n      `/compatibility/subjects/${encodeURIComponent(subject)}/versions/latest`,\n      { schema, schemaType },\n    );\n    return res.is_compatible;\n  }\n}\n\n/** Options for `registrySchema()`. */\nexport interface RegistrySchemaOptions<T> {\n  /**\n   * Local structural validator (Zod/Valibot/…) applied to every message.\n   * The registry governs schema *evolution*; this governs runtime *shape*.\n   */\n  validator?: SchemaLike<T>;\n  /**\n   * When `true` (default), the message's `x-schema-version` must not be newer\n   * than the latest version registered for the subject — a producer publishing\n   * an unregistered version fails loudly instead of drifting silently.\n   */\n  enforceVersion?: boolean;\n}\n\n/**\n * Bridge a Schema Registry subject to this library's `SchemaLike` seam.\n *\n * On each `parse` the adapter resolves the subject's latest registered version\n * (cached), optionally verifies the message's schema version does not exceed\n * it, and delegates structural validation to the provided local validator.\n * Attach the result to a `TopicDescriptor` like any other schema:\n *\n * @example\n * ```ts\n * const registry = new SchemaRegistryClient({ baseUrl: 'http://localhost:8081' });\n *\n * const OrderCreated = topic('order.created').schema(\n *   registrySchema(registry, 'order.created-value', {\n *     validator: z.object({ orderId: z.string() }),\n *   }),\n * );\n * ```\n */\nexport function registrySchema<T = any>(\n  client: SchemaRegistryClient,\n  subject: string,\n  options?: RegistrySchemaOptions<T>,\n): SchemaLike<T> {\n  const enforceVersion = options?.enforceVersion ?? true;\n  return {\n    async parse(data: unknown, ctx?: SchemaParseContext): Promise<T> {\n      const latest = await client.getLatestSchema(subject);\n      if (enforceVersion && ctx?.version !== undefined && ctx.version > latest.version) {\n        throw new Error(\n          `registrySchema: message version ${ctx.version} for subject \"${subject}\" ` +\n            `is newer than the latest registered version ${latest.version} — ` +\n            `register the schema before producing with it`,\n        );\n      }\n      if (options?.validator) {\n        return options.validator.parse(data, ctx);\n      }\n      return data as T;\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/cli/index.js

@@ -204,6 +204,18 @@ var ConfluentTransport = class {
   }
 };
 
+// src/client/message/serde.ts
+var JsonSerde = class {
+  /** JSON-stringify the validated payload. Returns a UTF-8 string. */
+  serialize(value) {
+    return JSON.stringify(value);
+  }
+  /** JSON-parse UTF-8 wire bytes into an object. */
+  deserialize(data) {
+    return JSON.parse(data.toString("utf8"));
+  }
+};
+
 // src/client/kafka.client/infra/dedup.store.ts
 var InMemoryDedupStore = class {
   constructor(states) {
@@ -328,6 +340,9 @@ var KafkaRetryExhaustedError = class extends KafkaProcessingError {
 };
 
 // src/client/kafka.client/producer/ops.ts
+function resolveSerde(topicOrDesc, clientSerde) {
+  return topicOrDesc?.__serde ?? clientSerde;
+}
 function resolveTopicName(topicOrDescriptor) {
   if (typeof topicOrDescriptor === "string") return topicOrDescriptor;
   if (topicOrDescriptor && typeof topicOrDescriptor === "object" && "__topic" in topicOrDescriptor) {
@@ -374,6 +389,7 @@ async function validateMessage(topicOrDesc, message, deps, ctx) {
 }
 async function buildSendPayload(topicOrDesc, messages, deps, compression) {
   const topic = resolveTopicName(topicOrDesc);
+  const serde = resolveSerde(topicOrDesc, deps.serde);
   const builtMessages = await Promise.all(
     messages.map(async (m) => {
       const envelopeHeaders = buildEnvelopeHeaders({
@@ -393,10 +409,13 @@ async function buildSendPayload(topicOrDesc, messages, deps, compression) {
         headers: envelopeHeaders,
         version: m.schemaVersion ?? 1
       };
+      const validated = await validateMessage(topicOrDesc, m.value, deps, sendCtx);
       return {
-        value: JSON.stringify(
-          await validateMessage(topicOrDesc, m.value, deps, sendCtx)
-        ),
+        value: await serde.serialize(validated, {
+          topic,
+          headers: envelopeHeaders,
+          isKey: false
+        }),
         // Explicit key wins; otherwise fall back to the descriptor's .key()
         // extractor (runs on the original, pre-validation payload).
         key: m.key ?? topicOrDesc?.__key?.(m.value) ?? null,
@@ -481,6 +500,15 @@ function buildSchemaMap(topics, schemaRegistry, optionSchemas, logger) {
   }
   return schemaMap;
 }
+function buildSerdeMap(topics) {
+  let serdeMap;
+  for (const t of topics) {
+    if (t?.__serde) {
+      (serdeMap ??= /* @__PURE__ */ new Map()).set(resolveTopicName(t), t.__serde);
+    }
+  }
+  return serdeMap;
+}
 
 // src/client/kafka.client/admin/ops.ts
 var AdminOps = class {
@@ -766,17 +794,6 @@ var AdminOps = class {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function parseJsonMessage(raw, topic, logger) {
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    logger.error(
-      `Failed to parse message from topic ${topic}:`,
-      toError(error).stack
-    );
-    return null;
-  }
-}
 async function validateWithSchema(message, raw, topic, schemaMap, interceptors, dlq, deps) {
   const schema = schemaMap.get(topic);
   if (!schema) return message;
@@ -1169,15 +1186,15 @@ async function replayDlqTopic(topic, deps, options = {}) {
           const originalHeaders = Object.fromEntries(
             Object.entries(headers).filter(([k]) => !deps.dlqHeaderKeys.has(k))
           );
-          const value = message.value.toString();
-          const shouldProcess = !options.filter || options.filter(headers, value);
+          const bytes = message.value;
+          const shouldProcess = !options.filter || options.filter(headers, bytes.toString("utf8"));
           if (!targetTopic || !shouldProcess) {
             skipped++;
           } else if (options.dryRun) {
             deps.logger.log(`[DLQ replay dry-run] Would replay to "${targetTopic}"`);
             replayed++;
           } else {
-            await deps.send(targetTopic, [{ value, headers: originalHeaders }]);
+            await deps.send(targetTopic, [{ value: bytes, headers: originalHeaders }]);
             replayed++;
           }
           const allDone = Array.from(highWatermarks.entries()).every(
@@ -2051,7 +2068,7 @@ async function waitForPartitionAssignment(consumer, topics, logger, timeoutMs =
     `Retry consumer did not receive partition assignments for [${topics.join(", ")}] within ${timeoutMs}ms`
   );
 }
-async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopics, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs) {
+async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopics, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs, serdeMap) {
   const {
     logger,
     producer,
@@ -2097,20 +2114,35 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         await sleep(remaining);
         consumer.resume([{ topic: levelTopic, partitions: [partition] }]);
       }
-      const raw = message.value.toString();
-      const parsed = parseJsonMessage(raw, levelTopic, logger);
-      if (parsed === null) {
-        await consumer.commitOffsets([nextOffset]);
-        return;
-      }
+      const rawBytes = message.value;
       const currentMaxRetries = parseInt(
         headers[RETRY_HEADER_MAX_RETRIES] ?? String(retry.maxRetries),
         10
       );
       const originalTopic = headers[RETRY_HEADER_ORIGINAL_TOPIC] ?? levelTopic.replace(/\.retry\.\d+$/, "");
+      const serde = serdeMap?.get(originalTopic) ?? deps.serde;
+      let parsed;
+      try {
+        parsed = await serde.deserialize(rawBytes, {
+          topic: originalTopic,
+          headers,
+          isKey: false
+        });
+      } catch (err) {
+        logger.error(
+          `Failed to deserialize retry message from topic ${levelTopic}:`,
+          toError(err).stack
+        );
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
+      if (parsed === null) {
+        await consumer.commitOffsets([nextOffset]);
+        return;
+      }
       const validated = await validateWithSchema(
         parsed,
-        raw,
+        rawBytes,
         originalTopic,
         schemaMap,
         interceptors,
@@ -2164,7 +2196,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
         const delay = Math.floor(Math.random() * cap);
         const { topic: rtTopic, messages: rtMsgs } = buildRetryTopicPayload(
           originalTopic,
-          [raw],
+          [rawBytes],
           nextLevel,
           currentMaxRetries,
           delay,
@@ -2206,7 +2238,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
       } else if (dlq) {
         const { topic: dTopic, messages: dMsgs } = buildDlqPayload(
           originalTopic,
-          raw,
+          rawBytes,
           {
             error,
             // +1 to account for the main consumer's initial attempt before routing.
@@ -2268,7 +2300,7 @@ async function startLevelConsumer(level, levelTopics, levelGroupId, originalTopi
     `Retry level ${level}/${retry.maxRetries} consumer started for: ${originalTopics.join(", ")} (group: ${levelGroupId})`
   );
 }
-async function startRetryTopicConsumers(originalTopics, originalGroupId, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs) {
+async function startRetryTopicConsumers(originalTopics, originalGroupId, handleMessage, retry, dlq, interceptors, schemaMap, deps, assignmentTimeoutMs, serdeMap) {
   const levelGroupIds = new Array(retry.maxRetries);
   await Promise.all(
     Array.from({ length: retry.maxRetries }, async (_, i) => {
@@ -2286,7 +2318,8 @@ async function startRetryTopicConsumers(originalTopics, originalGroupId, handleM
         interceptors,
         schemaMap,
         deps,
-        assignmentTimeoutMs
+        assignmentTimeoutMs,
+        serdeMap
       );
       levelGroupIds[i] = levelGroupId;
     })
@@ -2370,6 +2403,7 @@ async function setupConsumer(ctx, topics, mode, options) {
     optionSchemas,
     ctx.logger
   );
+  const serdeMap = buildSerdeMap(stringTopics);
   const topicNames = stringTopics.map((t) => resolveTopicName(t));
   const subscribeTopics = [...topicNames, ...regexTopics];
   await ensureConsumerTopics(ctx, topicNames, dlq, options.deduplication);
@@ -2387,7 +2421,7 @@ async function setupConsumer(ctx, topics, mode, options) {
   ctx.logger.log(
     `${mode === "eachBatch" ? "Batch consumer" : "Consumer"} subscribed to topics: ${displayTopics}`
   );
-  return { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, hasRegex, readyPromise };
+  return { consumer, schemaMap, serdeMap, topicNames, gid, dlq, interceptors, retry, hasRegex, readyPromise };
 }
 function resolveDeduplicationContext(ctx, groupId, options) {
   if (!options) return void 0;
@@ -2399,6 +2433,7 @@ function messageDepsFor(ctx, gid, options) {
   return {
     logger: ctx.logger,
     producer: ctx.producer,
+    serde: ctx.serde,
     instrumentation: ctx.instrumentation,
     onMessageLost: options?.onMessageLost ?? ctx.onMessageLost,
     onTtlExpired: ctx.onTtlExpired,
@@ -2416,6 +2451,7 @@ function buildRetryTopicDeps(ctx) {
   return {
     logger: ctx.logger,
     producer: ctx.producer,
+    serde: ctx.serde,
     instrumentation: ctx.instrumentation,
     onMessageLost: ctx.onMessageLost,
     onRetry: ctx.metrics.notifyRetry.bind(ctx.metrics),
@@ -2433,7 +2469,7 @@ async function makeEosMainContext(ctx, gid, consumer, options) {
   return { txProducer, consumer };
 }
 async function launchRetryChain(ctx, gid, topicNames, handleMessage, opts) {
-  const { retry, dlq, interceptors, schemaMap, assignmentTimeoutMs } = opts;
+  const { retry, dlq, interceptors, schemaMap, serdeMap, assignmentTimeoutMs } = opts;
   if (!ctx.autoCreateTopicsEnabled) {
     await ctx.adminOps.validateRetryTopicsExist(topicNames, retry.maxRetries);
   }
@@ -2457,7 +2493,8 @@ async function launchRetryChain(ctx, gid, topicNames, handleMessage, opts) {
         ctx.companionGroupIds.get(gid).push(levelGroupId);
       }
     },
-    assignmentTimeoutMs
+    assignmentTimeoutMs,
+    serdeMap
   );
 }
 
@@ -2515,18 +2552,29 @@ async function applyDeduplication(envelope, raw, dedup, dlq, deps) {
   }
   return false;
 }
-async function parseSingleMessage(message, topic, partition, schemaMap, interceptors, dlq, deps) {
+async function parseSingleMessage(message, topic, partition, schemaMap, interceptors, dlq, deps, serdeMap) {
   if (!message.value) {
     deps.logger.warn(`Received empty message from topic ${topic}`);
     return null;
   }
-  const raw = message.value.toString();
-  const parsed = parseJsonMessage(raw, topic, deps.logger);
-  if (parsed === null) return null;
+  const bytes = message.value;
   const headers = decodeHeaders(message.headers);
+  const serde = serdeMap?.get(topic) ?? deps.serde;
+  let parsed;
+  try {
+    parsed = await serde.deserialize(bytes, { topic, headers, isKey: false });
+  } catch (error) {
+    deps.logger.error(
+      `Failed to deserialize message from topic ${topic}:`,
+      toError(error).stack
+    );
+    return null;
+  }
+  if (parsed === null) return null;
   const validated = await validateWithSchema(
     parsed,
-    raw,
+    // Forward the ORIGINAL bytes to DLQ on validation failure (binary-safe).
+    bytes,
     topic,
     schemaMap,
     interceptors,
@@ -2540,6 +2588,7 @@ async function handleEachMessage(payload, opts, deps) {
   const { topic, partition, message } = payload;
   const {
     schemaMap,
+    serdeMap,
     handleMessage,
     interceptors,
     dlq,
@@ -2548,6 +2597,7 @@ async function handleEachMessage(payload, opts, deps) {
     timeoutMs,
     wrapWithTimeout
   } = opts;
+  const rawBytes = message.value;
   const eos = opts.eosMainContext;
   const nextOffsetStr = (parseInt(message.offset, 10) + 1).toString();
   const commitOffset = eos ? async () => {
@@ -2592,7 +2642,8 @@ async function handleEachMessage(payload, opts, deps) {
     schemaMap,
     interceptors,
     dlq,
-    deps
+    deps,
+    serdeMap
   );
   if (envelope === null) {
     await commitOffset?.();
@@ -2601,7 +2652,7 @@ async function handleEachMessage(payload, opts, deps) {
   if (opts.deduplication) {
     const isDuplicate = await applyDeduplication(
       envelope,
-      message.value.toString(),
+      rawBytes,
       opts.deduplication,
       dlq,
       deps
@@ -2618,7 +2669,7 @@ async function handleEachMessage(payload, opts, deps) {
         `[KafkaClient] TTL expired on ${topic}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
       );
       if (dlq) {
-        await sendToDlq(topic, message.value.toString(), deps, {
+        await sendToDlq(topic, rawBytes, deps, {
           error: new Error(`Message TTL expired: age ${ageMs}ms`),
           attempt: 0,
           originalHeaders: envelope.headers
@@ -2650,7 +2701,7 @@ async function handleEachMessage(payload, opts, deps) {
     },
     {
       envelope,
-      rawMessages: [message.value.toString()],
+      rawMessages: [rawBytes],
       interceptors,
       dlq,
       retry,
@@ -2663,6 +2714,7 @@ async function handleEachBatch(payload, opts, deps) {
   const { batch, heartbeat, resolveOffset, commitOffsetsIfNecessary } = payload;
   const {
     schemaMap,
+    serdeMap,
     handleBatch,
     interceptors,
     dlq,
@@ -2718,6 +2770,7 @@ async function handleEachBatch(payload, opts, deps) {
   const envelopes = [];
   const rawMessages = [];
   for (const message of batch.messages) {
+    const rawBytes = message.value;
     const envelope = await parseSingleMessage(
       message,
       batch.topic,
@@ -2725,14 +2778,14 @@ async function handleEachBatch(payload, opts, deps) {
       schemaMap,
       interceptors,
       dlq,
-      deps
+      deps,
+      serdeMap
     );
     if (envelope === null) continue;
     if (opts.deduplication) {
-      const raw = message.value.toString();
       const isDuplicate = await applyDeduplication(
         envelope,
-        raw,
+        rawBytes,
         opts.deduplication,
         dlq,
         deps
@@ -2746,7 +2799,7 @@ async function handleEachBatch(payload, opts, deps) {
           `[KafkaClient] TTL expired on ${batch.topic}: age ${ageMs}ms > ${opts.messageTtlMs}ms`
         );
         if (dlq) {
-          await sendToDlq(batch.topic, message.value.toString(), deps, {
+          await sendToDlq(batch.topic, rawBytes, deps, {
             error: new Error(`Message TTL expired: age ${ageMs}ms`),
             attempt: 0,
             originalHeaders: envelope.headers
@@ -2765,7 +2818,7 @@ async function handleEachBatch(payload, opts, deps) {
       }
     }
     envelopes.push(envelope);
-    rawMessages.push(message.value.toString());
+    rawMessages.push(rawBytes);
   }
   if (envelopes.length === 0) {
     await commitBatchOffset?.();
@@ -2928,7 +2981,7 @@ function resumeTopicAllPartitions(ctx, gid, topic) {
 async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
   validateTopicConsumerOpts(topics, options);
   const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
-  const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachMessage", setupOptions);
+  const { consumer, schemaMap, serdeMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachMessage", setupOptions);
   if (options.circuitBreaker)
     ctx.circuitBreaker.setConfig(gid, options.circuitBreaker);
   const deps = messageDepsFor(ctx, gid, options);
@@ -2939,6 +2992,7 @@ async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
         payload,
         {
           schemaMap,
+          serdeMap,
           handleMessage,
           interceptors,
           dlq,
@@ -2966,6 +3020,7 @@ async function startConsumerImpl(ctx, topics, handleMessage, options = {}) {
       dlq,
       interceptors,
       schemaMap,
+      serdeMap,
       assignmentTimeoutMs: options.retryTopicAssignmentTimeoutMs
     });
   }
@@ -2979,7 +3034,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
     );
   }
   const setupOptions = options.retryTopics ? { ...options, autoCommit: false } : options;
-  const { consumer, schemaMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachBatch", setupOptions);
+  const { consumer, schemaMap, serdeMap, topicNames, gid, dlq, interceptors, retry, readyPromise } = await setupConsumer(ctx, topics, "eachBatch", setupOptions);
   if (options.circuitBreaker)
     ctx.circuitBreaker.setConfig(gid, options.circuitBreaker);
   const deps = messageDepsFor(ctx, gid, options);
@@ -2990,6 +3045,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
         payload,
         {
           schemaMap,
+          serdeMap,
           handleBatch,
           interceptors,
           dlq,
@@ -3027,6 +3083,7 @@ async function startBatchConsumerImpl(ctx, topics, handleBatch, options = {}) {
       dlq,
       interceptors,
       schemaMap,
+      serdeMap,
       assignmentTimeoutMs: options.retryTopicAssignmentTimeoutMs
     });
   }
@@ -3039,7 +3096,7 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
     );
   }
   const setupOptions = { ...options, autoCommit: false };
-  const { consumer, schemaMap, gid, readyPromise } = await setupConsumer(
+  const { consumer, schemaMap, serdeMap, gid, readyPromise } = await setupConsumer(
     ctx,
     topics,
     "eachMessage",
@@ -3056,7 +3113,8 @@ async function startTransactionalConsumerImpl(ctx, topics, handler, options = {}
         schemaMap,
         options.interceptors ?? [],
         false,
-        deps
+        deps,
+        serdeMap
       );
       const nextOffset = String(Number.parseInt(message.offset, 10) + 1);
       if (envelope === null) {
@@ -3274,7 +3332,9 @@ async function startDelayedRelayImpl(ctx, topics, options) {
           topic: target,
           messages: [
             {
-              value: message.value.toString(),
+              // Forward the ORIGINAL wire bytes unchanged — no re-serialization,
+              // so binary payloads (Avro/Protobuf) are relayed losslessly.
+              value: message.value,
               key: message.key ? message.key.toString() : null,
               headers: forwardHeaders
             }
@@ -3601,6 +3661,7 @@ var KafkaClient = class {
     const consumers = /* @__PURE__ */ new Map();
     const consumerCreationOptions = /* @__PURE__ */ new Map();
     const schemaRegistry = /* @__PURE__ */ new Map();
+    const serde = options?.serde ?? new JsonSerde();
     const adminOps = new AdminOps({
       admin: transport.admin(),
       logger,
@@ -3627,6 +3688,7 @@ var KafkaClient = class {
       autoCreateTopicsEnabled: options?.autoCreateTopics ?? false,
       strictSchemasEnabled: options?.strictSchemas ?? true,
       numPartitions: options?.numPartitions ?? 1,
+      serde,
       txId: options?.transactionalId ?? `${clientId}-tx`,
       clockRecoveryTopics: options?.clockRecovery?.topics ?? [],
       clockRecoveryTimeoutMs: options?.clockRecovery?.timeoutMs ?? 3e4,
@@ -3661,6 +3723,7 @@ var KafkaClient = class {
         strictSchemasEnabled: options?.strictSchemas ?? true,
         instrumentation: options?.instrumentation ?? [],
         logger,
+        serde,
         nextLamportClock: () => 0
         // patched below
       },
@@ -3679,6 +3742,7 @@ var KafkaClient = class {
       strictSchemasEnabled: options?.strictSchemas ?? true,
       instrumentation: options?.instrumentation ?? [],
       logger,
+      serde,
       nextLamportClock: () => ++ctx._lamportClock
     };
     ctx.retryTopicDeps = buildRetryTopicDeps(ctx);