@eventferry/schema-registry 3.2.3 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @eventferry/schema-registry
 
+## 3.4.0
+
+### Minor Changes
+
+- 0f328d2: Typed authentication for the Schema Registry HTTP API. New `auth?: SchemaRegistryAuth` option on `SchemaRegistrySerializer` with two shapes:
+
+  - `{ type: "basic", username, password }` — HTTP Basic, forwarded straight to the underlying client's `auth` config (the conventional Confluent Cloud + commercial-registry shape).
+  - `{ type: "bearer", token: string | () => string | Promise<string> }` — adds an `Authorization: Bearer <token>` header via a small middleware on the upstream client. Callable tokens are resolved on **every** request, so rotation logic lives in the caller's provider (cache inside your callable if rotation cost matters).
+
+  Ignored when an already-constructed `registry` client is injected — configure auth there yourself. mTLS to the registry stays out of scope: it's handled by a custom `https.Agent` on a self-constructed client (registry TLS is independent of broker TLS, and we don't want to fold an unrelated knob into this surface).
+
+  The middleware factory is exported as `bearerAuthMiddleware` for testing only — not part of the supported public API and may move in a future version.
+
+### Patch Changes
+
+- Updated dependencies [715523f]
+- Updated dependencies [fb0549d]
+  - @eventferry/core@3.4.0
+
+## 3.3.0
+
+### Minor Changes
+
+- d983d90: Schema Registry serializer gains three production-grade controls without breaking the existing API:
+
+  - **Subject naming strategy** — `subjectStrategy: "TopicNameStrategy" | "RecordNameStrategy" | "TopicRecordNameStrategy"` mirrors Confluent's three built-ins. The two record-based strategies take a `recordName: (record, isKey) => string` resolver. Default stays `TopicNameStrategy`; the existing `subject` callable still wins when set (now optionally receiving `(topic, isKey, record)` — the single-arg legacy form keeps working).
+  - **Avro key serialization** — new `keySchemas` option + `serializeKey(record): Promise<Buffer | null>` method. Returns `null` for keyless records (matching the kafka "no key" semantics) and uses the `-key` subject by default. Key and value subject ids cache independently. Not wired into the relay automatically — call it from your publish glue when you want Avro-encoded keys instead of UTF-8 strings.
+  - **`autoRegister: false`** — never call `register()`, always resolve schemas via `getLatestSchemaId` on the computed subject. Locally supplied `schemas` / `keySchemas` bytes become docs-only in this mode. Matches `auto.register.schemas=false` on every Confluent client, for production clusters where schemas are managed out-of-band.
+
 ## 3.2.3
 
 ### Patch Changes

package/README.md

@@ -32,6 +32,95 @@ Topics without a configured schema use the subject's latest registered schema
 (default subject: `${topic}-value`). On the consumer, decode with the same client:
 `await registry.decode(message.value)`.
 
+## Authentication
+
+The serializer accepts the two HTTP auth shapes Confluent Schema Registry installations use:
+
+```ts
+// HTTP Basic — Confluent Cloud + most commercial registries.
+new SchemaRegistrySerializer({
+  host,
+  auth: { type: "basic", username: "<api-key>", password: "<api-secret>" },
+});
+
+// Bearer token — OIDC, custom SR proxies, etc.
+new SchemaRegistrySerializer({
+  host,
+  auth: { type: "bearer", token: "eyJhbGc..." },
+});
+
+// Rotating bearer token (refresh per request — cache inside your provider).
+new SchemaRegistrySerializer({
+  host,
+  auth: {
+    type: "bearer",
+    token: async () => await getCachedAccessToken(),
+  },
+});
+```
+
+Bearer tokens are injected via a small middleware on the underlying client — the provider is invoked on **every** request, so you control rotation. `auth` is ignored when you pass an already-constructed `registry` client (configure auth there yourself).
+
+For **mTLS** to the registry, supply a custom `https.Agent` on a self-constructed client and pass it via the `registry` option. The serializer does not surface a separate `tls` block — registry TLS is independent of broker TLS and `https.Agent` is the standard Node entry point.
+
+## Subject naming strategies
+
+Pick one of Confluent's three built-in strategies (default `TopicNameStrategy`):
+
+```ts
+new SchemaRegistrySerializer({
+  host,
+  subjectStrategy: "RecordNameStrategy",     // subject = recordName
+  // or: "TopicRecordNameStrategy"           // subject = `${topic}-${recordName}`
+  recordName: (record) => `com.example.${record.aggregateType}.Created`,
+});
+```
+
+`recordName` is required for the `RecordName` and `TopicRecordName` strategies — typical implementation reads `${namespace}.${name}` from your avsc.
+
+Need full control? Skip the preset and pass an explicit `subject` function:
+
+```ts
+new SchemaRegistrySerializer({
+  host,
+  subject: (topic, isKey, record) => `acme.${topic}.${isKey ? "key" : "value"}`,
+});
+```
+
+## Avro key serialization
+
+Configure per-topic key schemas and call `serializeKey` from your publish path:
+
+```ts
+const serializer = new SchemaRegistrySerializer({
+  host,
+  schemas:    { "orders.created": { type: "AVRO", schema: valueAvsc } },
+  keySchemas: { "orders.created": { type: "AVRO", schema: keyAvsc } },
+});
+
+// Inside your custom publish glue:
+const encodedValue = await serializer.serialize(record);
+const encodedKey   = await serializer.serializeKey(record); // null when record.key is null
+```
+
+The relay does NOT call `serializeKey` automatically — Avro keys are an application-level convention, and adding them silently would break consumers expecting UTF-8 string keys. Wire it in your publish path explicitly.
+
+Key and value subjects cache their schema ids independently — registering one doesn't affect the other.
+
+## Auto-register toggle
+
+For production clusters where schemas are managed out-of-band (Confluent Cloud, regulated environments), turn auto-registration off:
+
+```ts
+new SchemaRegistrySerializer({
+  host,
+  schemas: { /* ignored when autoRegister is false */ },
+  autoRegister: false,
+});
+```
+
+With `autoRegister: false`, the serializer ALWAYS resolves by `getLatestSchemaId` on the computed subject — locally supplied `schemas` / `keySchemas` bytes are ignored. Matches the Confluent client's `auto.register.schemas=false`.
+
 📖 **Full documentation:** [github.com/SametGoktepe/eventferry](https://github.com/SametGoktepe/eventferry#readme)
 
 ## License

package/dist/index.cjs

@@ -30,7 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  SchemaRegistrySerializer: () => SchemaRegistrySerializer
+  SchemaRegistrySerializer: () => SchemaRegistrySerializer,
+  bearerAuthMiddleware: () => bearerAuthMiddleware
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -39,8 +40,14 @@ var DEFAULT_CONTENT_TYPE = "application/vnd.confluent.avro";
 var SchemaRegistrySerializer = class {
   contentType;
   schemas;
-  subject;
+  keySchemas;
+  subjectStrategy;
+  recordName;
+  subjectFn;
   host;
+  auth;
+  autoRegister;
+  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.
   idCache = /* @__PURE__ */ new Map();
   registry;
   constructor(opts) {
@@ -51,35 +58,107 @@ var SchemaRegistrySerializer = class {
     }
     this.registry = opts.registry ?? null;
     this.host = opts.host ?? null;
+    this.auth = opts.auth ?? null;
     this.schemas = opts.schemas ?? {};
-    this.subject = opts.subject ?? ((topic) => `${topic}-value`);
+    this.keySchemas = opts.keySchemas ?? {};
+    this.subjectStrategy = opts.subjectStrategy ?? "TopicNameStrategy";
+    this.recordName = opts.recordName ?? null;
+    this.subjectFn = opts.subject ?? null;
     this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;
+    this.autoRegister = opts.autoRegister ?? true;
   }
   async serialize(record) {
     const registry = await this.getRegistry();
-    const id = await this.schemaId(registry, record.topic);
+    const subject = this.resolveSubject(record, false);
+    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);
     return registry.encode(id, record.payload);
   }
-  schemaId(registry, topic) {
-    const cached = this.idCache.get(topic);
+  /**
+   * Avro-encode the record's KEY using the registered key schema. Returns
+   * `null` when the record has no key (kafkajs/confluent treat null keys
+   * as the producer-side "no key" signal).
+   *
+   * Not part of the core `Serializer` interface — callers wire it into
+   * their publish path manually when they want Avro keys instead of raw
+   * UTF-8 strings.
+   */
+  async serializeKey(record) {
+    if (record.key === null || record.key === void 0) return null;
+    const registry = await this.getRegistry();
+    const subject = this.resolveSubject(record, true);
+    const id = await this.schemaId(
+      registry,
+      subject,
+      this.keySchemas[record.topic],
+      true,
+      record.topic
+    );
+    return registry.encode(id, record.key);
+  }
+  /**
+   * Resolve the subject for this (record, isKey) tuple. Order of
+   * precedence: explicit `subject` function → `subjectStrategy` preset.
+   */
+  resolveSubject(record, isKey) {
+    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);
+    switch (this.subjectStrategy) {
+      case "TopicNameStrategy":
+        return `${record.topic}-${isKey ? "key" : "value"}`;
+      case "RecordNameStrategy":
+        return this.recordNameFor(record, isKey);
+      case "TopicRecordNameStrategy":
+        return `${record.topic}-${this.recordNameFor(record, isKey)}`;
+    }
+  }
+  recordNameFor(record, isKey) {
+    if (!this.recordName) {
+      throw new Error(
+        `SchemaRegistrySerializer: subjectStrategy "${this.subjectStrategy}" requires a \`recordName\` resolver.`
+      );
+    }
+    return this.recordName(record, isKey);
+  }
+  schemaId(registry, subject, spec, isKey, topic) {
+    const cacheKey = `${topic}:${isKey ? "key" : "value"}`;
+    const cached = this.idCache.get(cacheKey);
     if (cached) return cached;
-    const subject = this.subject(topic);
-    const spec = this.schemas[topic];
-    const lookup = spec ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
+    const lookup = spec && this.autoRegister ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
     const guarded = lookup.catch((err) => {
-      this.idCache.delete(topic);
+      this.idCache.delete(cacheKey);
       throw err;
     });
-    this.idCache.set(topic, guarded);
+    this.idCache.set(cacheKey, guarded);
     return guarded;
   }
   async getRegistry() {
     if (this.registry) return this.registry;
     const mod = await importSchemaRegistry();
-    this.registry = new mod.SchemaRegistry({ host: this.host });
+    const cfg = {
+      host: this.host
+    };
+    if (this.auth) {
+      if (this.auth.type === "basic") {
+        cfg.auth = {
+          username: this.auth.username,
+          password: this.auth.password
+        };
+      } else {
+        cfg.middlewares = [bearerAuthMiddleware(this.auth.token)];
+      }
+    }
+    this.registry = new mod.SchemaRegistry(cfg);
     return this.registry;
   }
 };
+function bearerAuthMiddleware(token) {
+  return () => ({
+    async prepareRequest(next) {
+      const request = await next();
+      const value = typeof token === "function" ? await token() : token;
+      return request.enhance({ headers: { Authorization: `Bearer ${value}` } });
+    }
+  });
+}
 async function importSchemaRegistry() {
   try {
     return await import("@kafkajs/confluent-schema-registry");
@@ -91,6 +170,7 @@ async function importSchemaRegistry() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  SchemaRegistrySerializer
+  SchemaRegistrySerializer,
+  bearerAuthMiddleware
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/serializer.ts"],"sourcesContent":["export * from \"./serializer.js\";\n","import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /** Per-topic schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */\n  subject?: (topic: string) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per topic is resolved once and cached.\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly subject: (topic: string) => string;\n  private readonly host: string | null;\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.subject = opts.subject ?? ((topic) => `${topic}-value`);\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const id = await this.schemaId(registry, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    topic: string,\n  ): Promise<number> {\n    const cached = this.idCache.get(topic);\n    if (cached) return cached;\n\n    const subject = this.subject(topic);\n    const spec = this.schemas[topic];\n    const lookup = spec\n      ? registry\n          .register({ type: spec.type, schema: spec.schema }, { subject })\n          .then((r) => r.id)\n      : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(topic);\n      throw err;\n    });\n    this.idCache.set(topic, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    this.registry = new mod.SchemaRegistry({ host: this.host as string });\n    return this.registry;\n  }\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (cfg: { host: string }) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACoCA,IAAM,uBAAuB;AAOtB,IAAM,2BAAN,MAAqD;AAAA,EACjD;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU,oBAAI,IAA6B;AAAA,EACpD;AAAA,EAER,YAAY,MAAuC;AACjD,QAAI,CAAC,KAAK,YAAY,CAAC,KAAK,MAAM;AAChC,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,WAAW,KAAK,YAAY;AACjC,SAAK,OAAO,KAAK,QAAQ;AACzB,SAAK,UAAU,KAAK,WAAW,CAAC;AAChC,SAAK,UAAU,KAAK,YAAY,CAAC,UAAU,GAAG,KAAK;AACnD,SAAK,cAAc,KAAK,eAAe;AAAA,EACzC;AAAA,EAEA,MAAM,UAAU,QAAuC;AACrD,UAAM,WAAW,MAAM,KAAK,YAAY;AACxC,UAAM,KAAK,MAAM,KAAK,SAAS,UAAU,OAAO,KAAK;AACrD,WAAO,SAAS,OAAO,IAAI,OAAO,OAAO;AAAA,EAC3C;AAAA,EAEQ,SACN,UACA,OACiB;AACjB,UAAM,SAAS,KAAK,QAAQ,IAAI,KAAK;AACrC,QAAI,OAAQ,QAAO;AAEnB,UAAM,UAAU,KAAK,QAAQ,KAAK;AAClC,UAAM,OAAO,KAAK,QAAQ,KAAK;AAC/B,UAAM,SAAS,OACX,SACG,SAAS,EAAE,MAAM,KAAK,MAAM,QAAQ,KAAK,OAAO,GAAG,EAAE,QAAQ,CAAC,EAC9D,KAAK,CAAC,MAAM,EAAE,EAAE,IACnB,SAAS,kBAAkB,OAAO;AAItC,UAAM,UAAU,OAAO,MAAM,CAAC,QAAQ;AACpC,WAAK,QAAQ,OAAO,KAAK;AACzB,YAAM;AAAA,IACR,CAAC;AACD,SAAK,QAAQ,IAAI,OAAO,OAAO;AAC/B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,cAA6C;AACzD,QAAI,KAAK,SAAU,QAAO,KAAK;AAC/B,UAAM,MAAM,MAAM,qBAAqB;AACvC,SAAK,WAAW,IAAI,IAAI,eAAe,EAAE,MAAM,KAAK,KAAe,CAAC;AACpE,WAAO,KAAK;AAAA,EACd;AACF;AAEA,eAAe,uBAEZ;AACD,MAAI;AAEF,WAAQ,MAAM,OAAO,oCAAoC;AAAA,EAC3D,QAAQ;AACN,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/serializer.ts"],"sourcesContent":["export * from \"./serializer.js\";\n","import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * Subject naming strategy. Mirrors Confluent's three built-ins:\n *\n * - `\"TopicNameStrategy\"` (default) — `${topic}-value` / `${topic}-key`.\n *   The conventional default; one schema per (topic, isKey) tuple.\n * - `\"RecordNameStrategy\"` — `${recordName}`. Same record type can flow\n *   on multiple topics. Requires a `recordName` resolver.\n * - `\"TopicRecordNameStrategy\"` — `${topic}-${recordName}`. Multiple record\n *   types per topic. Requires a `recordName` resolver.\n *\n * Set `subject` (function form) to override entirely.\n */\nexport type SubjectNameStrategy =\n  | \"TopicNameStrategy\"\n  | \"RecordNameStrategy\"\n  | \"TopicRecordNameStrategy\";\n\n/**\n * Authentication for the Schema Registry HTTP API.\n *\n * - `\"basic\"` — HTTP Basic Auth. The shape Confluent Cloud and most\n *   commercial registries use; passed straight through to the underlying\n *   client's `auth` config.\n * - `\"bearer\"` — `Authorization: Bearer <token>` header. The `token`\n *   field accepts either a static string OR a callable that resolves a\n *   fresh token on every request (cache inside your callable to amortise\n *   cost; we don't memoize for you, so OAuth refresh-loop logic lives\n *   on your side).\n *\n * mTLS for the registry connection itself is handled by Node's `tls`\n * stack — supply a custom `https.Agent` via the upstream client's\n * `agent` option (use the `registry` injection here and configure it\n * yourself), separate from the broker TLS the publisher uses.\n */\nexport type SchemaRegistryAuth =\n  | { type: \"basic\"; username: string; password: string }\n  | {\n      type: \"bearer\";\n      token: string | (() => string | Promise<string>);\n    };\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /**\n   * Optional authentication for the Schema Registry HTTP API. See\n   * {@link SchemaRegistryAuth} for the two supported shapes. Ignored\n   * when `registry` is provided (configure auth on the injected client\n   * yourself in that case).\n   */\n  auth?: SchemaRegistryAuth;\n  /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /**\n   * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes\n   * the record key for the matching topic. Topics omitted here fall back\n   * to the subject's latest (or, with `autoRegister: false`, ALWAYS the\n   * subject's latest).\n   */\n  keySchemas?: Record<string, SchemaSpec>;\n  /**\n   * Subject naming strategy preset. Default `\"TopicNameStrategy\"`.\n   * Setting `subject` (function) overrides this entirely.\n   */\n  subjectStrategy?: SubjectNameStrategy;\n  /**\n   * Resolve the schema's record name (used by `RecordNameStrategy` and\n   * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to\n   * one of those — throws on first serialize if absent.\n   *\n   * Typical implementation: read `${namespace}.${name}` from the avsc you\n   * already supply via `schemas` / `keySchemas`.\n   */\n  recordName?: (record: OutboxRecord, isKey: boolean) => string;\n  /**\n   * Custom subject function — overrides BOTH `subjectStrategy` and\n   * `recordName`. Receives `(topic, isKey, record)` for full flexibility.\n   *\n   * Backwards-compatible with the single-argument legacy form\n   * `(topic) => string` — extra args are ignored by JavaScript.\n   */\n  subject?: (\n    topic: string,\n    isKey?: boolean,\n    record?: OutboxRecord,\n  ) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n  /**\n   * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.\n   * Default `true` — matches Confluent client behavior.\n   *\n   * Set to `false` for production clusters where schemas are managed\n   * out-of-band (Confluent Cloud, regulated environments). With\n   * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`\n   * on the computed subject — and the locally-supplied schema bytes are\n   * ignored.\n   */\n  autoRegister?: boolean;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per (topic, isKey) tuple is resolved once\n * and cached.\n *\n * Also exposes `serializeKey(record)` for users who want Avro-encoded message\n * keys — call it manually when building the publish path; the relay does NOT\n * call it automatically (key encoding is application-level by convention).\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly keySchemas: Record<string, SchemaSpec>;\n  private readonly subjectStrategy: SubjectNameStrategy;\n  private readonly recordName:\n    | ((record: OutboxRecord, isKey: boolean) => string)\n    | null;\n  private readonly subjectFn:\n    | ((topic: string, isKey?: boolean, record?: OutboxRecord) => string)\n    | null;\n  private readonly host: string | null;\n  private readonly auth: SchemaRegistryAuth | null;\n  private readonly autoRegister: boolean;\n  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.auth = opts.auth ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.keySchemas = opts.keySchemas ?? {};\n    this.subjectStrategy = opts.subjectStrategy ?? \"TopicNameStrategy\";\n    this.recordName = opts.recordName ?? null;\n    this.subjectFn = opts.subject ?? null;\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n    this.autoRegister = opts.autoRegister ?? true;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, false);\n    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  /**\n   * Avro-encode the record's KEY using the registered key schema. Returns\n   * `null` when the record has no key (kafkajs/confluent treat null keys\n   * as the producer-side \"no key\" signal).\n   *\n   * Not part of the core `Serializer` interface — callers wire it into\n   * their publish path manually when they want Avro keys instead of raw\n   * UTF-8 strings.\n   */\n  async serializeKey(record: OutboxRecord): Promise<Buffer | null> {\n    if (record.key === null || record.key === undefined) return null;\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, true);\n    const id = await this.schemaId(\n      registry,\n      subject,\n      this.keySchemas[record.topic],\n      true,\n      record.topic,\n    );\n    return registry.encode(id, record.key);\n  }\n\n  /**\n   * Resolve the subject for this (record, isKey) tuple. Order of\n   * precedence: explicit `subject` function → `subjectStrategy` preset.\n   */\n  private resolveSubject(record: OutboxRecord, isKey: boolean): string {\n    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);\n    switch (this.subjectStrategy) {\n      case \"TopicNameStrategy\":\n        return `${record.topic}-${isKey ? \"key\" : \"value\"}`;\n      case \"RecordNameStrategy\":\n        return this.recordNameFor(record, isKey);\n      case \"TopicRecordNameStrategy\":\n        return `${record.topic}-${this.recordNameFor(record, isKey)}`;\n    }\n  }\n\n  private recordNameFor(record: OutboxRecord, isKey: boolean): string {\n    if (!this.recordName) {\n      throw new Error(\n        `SchemaRegistrySerializer: subjectStrategy \"${this.subjectStrategy}\" requires a \\`recordName\\` resolver.`,\n      );\n    }\n    return this.recordName(record, isKey);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    subject: string,\n    spec: SchemaSpec | undefined,\n    isKey: boolean,\n    topic: string,\n  ): Promise<number> {\n    const cacheKey = `${topic}:${isKey ? \"key\" : \"value\"}`;\n    const cached = this.idCache.get(cacheKey);\n    if (cached) return cached;\n\n    // autoRegister=false → ALWAYS resolve by latest; the local spec\n    // (if any) is ignored. Matches Confluent's auto.register.schemas=false.\n    const lookup =\n      spec && this.autoRegister\n        ? registry\n            .register({ type: spec.type, schema: spec.schema }, { subject })\n            .then((r) => r.id)\n        : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(cacheKey);\n      throw err;\n    });\n    this.idCache.set(cacheKey, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    const cfg: SchemaRegistryConstructorConfig = {\n      host: this.host as string,\n    };\n    if (this.auth) {\n      if (this.auth.type === \"basic\") {\n        // Confluent SR client accepts `auth: { username, password }`\n        // and the mappersmith basic-auth middleware builds the header.\n        cfg.auth = {\n          username: this.auth.username,\n          password: this.auth.password,\n        };\n      } else {\n        // Bearer: SR doesn't ship a built-in middleware. Inject our own\n        // so every API call carries `Authorization: Bearer <token>`.\n        cfg.middlewares = [bearerAuthMiddleware(this.auth.token)];\n      }\n    }\n    this.registry = new mod.SchemaRegistry(cfg);\n    return this.registry;\n  }\n}\n\n/**\n * Mappersmith middleware shape — the structural subset the Confluent\n * SR client passes through. We don't depend on mappersmith types\n * directly so the package compiles without the optional peer installed.\n */\ninterface MmRequest {\n  enhance(args: { headers?: Record<string, string> }): MmRequest;\n}\n\n/**\n * Build a mappersmith middleware that adds `Authorization: Bearer <token>`.\n *\n * Exported for testing only — not part of the public API surface. The\n * middleware resolves the token on EVERY request, so callable token\n * providers can rotate without re-constructing the serializer. Cache\n * inside your provider if rotation cost matters.\n */\nexport function bearerAuthMiddleware(\n  token: string | (() => string | Promise<string>),\n) {\n  return () => ({\n    async prepareRequest(next: () => Promise<MmRequest>): Promise<MmRequest> {\n      const request = await next();\n      const value = typeof token === \"function\" ? await token() : token;\n      return request.enhance({ headers: { Authorization: `Bearer ${value}` } });\n    },\n  });\n}\n\n/**\n * Structural shape the SR client's constructor accepts. Mirrors\n * `SchemaRegistryAPIClientArgs` from the upstream package without\n * importing the type directly (optional peer).\n */\ninterface SchemaRegistryConstructorConfig {\n  host: string;\n  auth?: { username: string; password: string };\n  middlewares?: Array<() => unknown>;\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (\n    cfg: SchemaRegistryConstructorConfig,\n  ) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -6,6 +6,44 @@ interface SchemaSpec {
     /** Schema definition string (avsc JSON / .proto / JSON Schema). */
     schema: string;
 }
+/**
+ * Subject naming strategy. Mirrors Confluent's three built-ins:
+ *
+ * - `"TopicNameStrategy"` (default) — `${topic}-value` / `${topic}-key`.
+ *   The conventional default; one schema per (topic, isKey) tuple.
+ * - `"RecordNameStrategy"` — `${recordName}`. Same record type can flow
+ *   on multiple topics. Requires a `recordName` resolver.
+ * - `"TopicRecordNameStrategy"` — `${topic}-${recordName}`. Multiple record
+ *   types per topic. Requires a `recordName` resolver.
+ *
+ * Set `subject` (function form) to override entirely.
+ */
+type SubjectNameStrategy = "TopicNameStrategy" | "RecordNameStrategy" | "TopicRecordNameStrategy";
+/**
+ * Authentication for the Schema Registry HTTP API.
+ *
+ * - `"basic"` — HTTP Basic Auth. The shape Confluent Cloud and most
+ *   commercial registries use; passed straight through to the underlying
+ *   client's `auth` config.
+ * - `"bearer"` — `Authorization: Bearer <token>` header. The `token`
+ *   field accepts either a static string OR a callable that resolves a
+ *   fresh token on every request (cache inside your callable to amortise
+ *   cost; we don't memoize for you, so OAuth refresh-loop logic lives
+ *   on your side).
+ *
+ * mTLS for the registry connection itself is handled by Node's `tls`
+ * stack — supply a custom `https.Agent` via the upstream client's
+ * `agent` option (use the `registry` injection here and configure it
+ * yourself), separate from the broker TLS the publisher uses.
+ */
+type SchemaRegistryAuth = {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "bearer";
+    token: string | (() => string | Promise<string>);
+};
 /**
  * The subset of a Confluent Schema Registry client this serializer uses. The
  * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.
@@ -27,29 +65,121 @@ interface SchemaRegistrySerializerOptions {
     registry?: SchemaRegistryClient;
     /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */
     host?: string;
-    /** Per-topic schema to register. Topics omitted here use the subject's latest. */
+    /**
+     * Optional authentication for the Schema Registry HTTP API. See
+     * {@link SchemaRegistryAuth} for the two supported shapes. Ignored
+     * when `registry` is provided (configure auth on the injected client
+     * yourself in that case).
+     */
+    auth?: SchemaRegistryAuth;
+    /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */
     schemas?: Record<string, SchemaSpec>;
-    /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */
-    subject?: (topic: string) => string;
+    /**
+     * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes
+     * the record key for the matching topic. Topics omitted here fall back
+     * to the subject's latest (or, with `autoRegister: false`, ALWAYS the
+     * subject's latest).
+     */
+    keySchemas?: Record<string, SchemaSpec>;
+    /**
+     * Subject naming strategy preset. Default `"TopicNameStrategy"`.
+     * Setting `subject` (function) overrides this entirely.
+     */
+    subjectStrategy?: SubjectNameStrategy;
+    /**
+     * Resolve the schema's record name (used by `RecordNameStrategy` and
+     * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to
+     * one of those — throws on first serialize if absent.
+     *
+     * Typical implementation: read `${namespace}.${name}` from the avsc you
+     * already supply via `schemas` / `keySchemas`.
+     */
+    recordName?: (record: OutboxRecord, isKey: boolean) => string;
+    /**
+     * Custom subject function — overrides BOTH `subjectStrategy` and
+     * `recordName`. Receives `(topic, isKey, record)` for full flexibility.
+     *
+     * Backwards-compatible with the single-argument legacy form
+     * `(topic) => string` — extra args are ignored by JavaScript.
+     */
+    subject?: (topic: string, isKey?: boolean, record?: OutboxRecord) => string;
     /** content-type header value. Default "application/vnd.confluent.avro". */
     contentType?: string;
+    /**
+     * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.
+     * Default `true` — matches Confluent client behavior.
+     *
+     * Set to `false` for production clusters where schemas are managed
+     * out-of-band (Confluent Cloud, regulated environments). With
+     * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`
+     * on the computed subject — and the locally-supplied schema bytes are
+     * ignored.
+     */
+    autoRegister?: boolean;
 }
 /**
  * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry
  * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s
- * `serializer` option. The schema id per topic is resolved once and cached.
+ * `serializer` option. The schema id per (topic, isKey) tuple is resolved once
+ * and cached.
+ *
+ * Also exposes `serializeKey(record)` for users who want Avro-encoded message
+ * keys — call it manually when building the publish path; the relay does NOT
+ * call it automatically (key encoding is application-level by convention).
  */
 declare class SchemaRegistrySerializer implements Serializer {
     readonly contentType: string;
     private readonly schemas;
-    private readonly subject;
+    private readonly keySchemas;
+    private readonly subjectStrategy;
+    private readonly recordName;
+    private readonly subjectFn;
     private readonly host;
+    private readonly auth;
+    private readonly autoRegister;
     private readonly idCache;
     private registry;
     constructor(opts: SchemaRegistrySerializerOptions);
     serialize(record: OutboxRecord): Promise<Buffer>;
+    /**
+     * Avro-encode the record's KEY using the registered key schema. Returns
+     * `null` when the record has no key (kafkajs/confluent treat null keys
+     * as the producer-side "no key" signal).
+     *
+     * Not part of the core `Serializer` interface — callers wire it into
+     * their publish path manually when they want Avro keys instead of raw
+     * UTF-8 strings.
+     */
+    serializeKey(record: OutboxRecord): Promise<Buffer | null>;
+    /**
+     * Resolve the subject for this (record, isKey) tuple. Order of
+     * precedence: explicit `subject` function → `subjectStrategy` preset.
+     */
+    private resolveSubject;
+    private recordNameFor;
     private schemaId;
     private getRegistry;
 }
+/**
+ * Mappersmith middleware shape — the structural subset the Confluent
+ * SR client passes through. We don't depend on mappersmith types
+ * directly so the package compiles without the optional peer installed.
+ */
+interface MmRequest {
+    enhance(args: {
+        headers?: Record<string, string>;
+    }): MmRequest;
+}
+/**
+ * Build a mappersmith middleware that adds `Authorization: Bearer <token>`.
+ *
+ * Exported for testing only — not part of the public API surface. The
+ * middleware resolves the token on EVERY request, so callable token
+ * providers can rotate without re-constructing the serializer. Cache
+ * inside your provider if rotation cost matters.
+ */
+declare function bearerAuthMiddleware(token: string | (() => string | Promise<string>)): () => {
+    prepareRequest(next: () => Promise<MmRequest>): Promise<MmRequest>;
+};
 
-export { type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType };
+export { type SchemaRegistryAuth, type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType, type SubjectNameStrategy, bearerAuthMiddleware };

package/dist/index.d.ts

@@ -6,6 +6,44 @@ interface SchemaSpec {
     /** Schema definition string (avsc JSON / .proto / JSON Schema). */
     schema: string;
 }
+/**
+ * Subject naming strategy. Mirrors Confluent's three built-ins:
+ *
+ * - `"TopicNameStrategy"` (default) — `${topic}-value` / `${topic}-key`.
+ *   The conventional default; one schema per (topic, isKey) tuple.
+ * - `"RecordNameStrategy"` — `${recordName}`. Same record type can flow
+ *   on multiple topics. Requires a `recordName` resolver.
+ * - `"TopicRecordNameStrategy"` — `${topic}-${recordName}`. Multiple record
+ *   types per topic. Requires a `recordName` resolver.
+ *
+ * Set `subject` (function form) to override entirely.
+ */
+type SubjectNameStrategy = "TopicNameStrategy" | "RecordNameStrategy" | "TopicRecordNameStrategy";
+/**
+ * Authentication for the Schema Registry HTTP API.
+ *
+ * - `"basic"` — HTTP Basic Auth. The shape Confluent Cloud and most
+ *   commercial registries use; passed straight through to the underlying
+ *   client's `auth` config.
+ * - `"bearer"` — `Authorization: Bearer <token>` header. The `token`
+ *   field accepts either a static string OR a callable that resolves a
+ *   fresh token on every request (cache inside your callable to amortise
+ *   cost; we don't memoize for you, so OAuth refresh-loop logic lives
+ *   on your side).
+ *
+ * mTLS for the registry connection itself is handled by Node's `tls`
+ * stack — supply a custom `https.Agent` via the upstream client's
+ * `agent` option (use the `registry` injection here and configure it
+ * yourself), separate from the broker TLS the publisher uses.
+ */
+type SchemaRegistryAuth = {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "bearer";
+    token: string | (() => string | Promise<string>);
+};
 /**
  * The subset of a Confluent Schema Registry client this serializer uses. The
  * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.
@@ -27,29 +65,121 @@ interface SchemaRegistrySerializerOptions {
     registry?: SchemaRegistryClient;
     /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */
     host?: string;
-    /** Per-topic schema to register. Topics omitted here use the subject's latest. */
+    /**
+     * Optional authentication for the Schema Registry HTTP API. See
+     * {@link SchemaRegistryAuth} for the two supported shapes. Ignored
+     * when `registry` is provided (configure auth on the injected client
+     * yourself in that case).
+     */
+    auth?: SchemaRegistryAuth;
+    /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */
     schemas?: Record<string, SchemaSpec>;
-    /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */
-    subject?: (topic: string) => string;
+    /**
+     * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes
+     * the record key for the matching topic. Topics omitted here fall back
+     * to the subject's latest (or, with `autoRegister: false`, ALWAYS the
+     * subject's latest).
+     */
+    keySchemas?: Record<string, SchemaSpec>;
+    /**
+     * Subject naming strategy preset. Default `"TopicNameStrategy"`.
+     * Setting `subject` (function) overrides this entirely.
+     */
+    subjectStrategy?: SubjectNameStrategy;
+    /**
+     * Resolve the schema's record name (used by `RecordNameStrategy` and
+     * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to
+     * one of those — throws on first serialize if absent.
+     *
+     * Typical implementation: read `${namespace}.${name}` from the avsc you
+     * already supply via `schemas` / `keySchemas`.
+     */
+    recordName?: (record: OutboxRecord, isKey: boolean) => string;
+    /**
+     * Custom subject function — overrides BOTH `subjectStrategy` and
+     * `recordName`. Receives `(topic, isKey, record)` for full flexibility.
+     *
+     * Backwards-compatible with the single-argument legacy form
+     * `(topic) => string` — extra args are ignored by JavaScript.
+     */
+    subject?: (topic: string, isKey?: boolean, record?: OutboxRecord) => string;
     /** content-type header value. Default "application/vnd.confluent.avro". */
     contentType?: string;
+    /**
+     * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.
+     * Default `true` — matches Confluent client behavior.
+     *
+     * Set to `false` for production clusters where schemas are managed
+     * out-of-band (Confluent Cloud, regulated environments). With
+     * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`
+     * on the computed subject — and the locally-supplied schema bytes are
+     * ignored.
+     */
+    autoRegister?: boolean;
 }
 /**
  * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry
  * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s
- * `serializer` option. The schema id per topic is resolved once and cached.
+ * `serializer` option. The schema id per (topic, isKey) tuple is resolved once
+ * and cached.
+ *
+ * Also exposes `serializeKey(record)` for users who want Avro-encoded message
+ * keys — call it manually when building the publish path; the relay does NOT
+ * call it automatically (key encoding is application-level by convention).
  */
 declare class SchemaRegistrySerializer implements Serializer {
     readonly contentType: string;
     private readonly schemas;
-    private readonly subject;
+    private readonly keySchemas;
+    private readonly subjectStrategy;
+    private readonly recordName;
+    private readonly subjectFn;
     private readonly host;
+    private readonly auth;
+    private readonly autoRegister;
     private readonly idCache;
     private registry;
     constructor(opts: SchemaRegistrySerializerOptions);
     serialize(record: OutboxRecord): Promise<Buffer>;
+    /**
+     * Avro-encode the record's KEY using the registered key schema. Returns
+     * `null` when the record has no key (kafkajs/confluent treat null keys
+     * as the producer-side "no key" signal).
+     *
+     * Not part of the core `Serializer` interface — callers wire it into
+     * their publish path manually when they want Avro keys instead of raw
+     * UTF-8 strings.
+     */
+    serializeKey(record: OutboxRecord): Promise<Buffer | null>;
+    /**
+     * Resolve the subject for this (record, isKey) tuple. Order of
+     * precedence: explicit `subject` function → `subjectStrategy` preset.
+     */
+    private resolveSubject;
+    private recordNameFor;
     private schemaId;
     private getRegistry;
 }
+/**
+ * Mappersmith middleware shape — the structural subset the Confluent
+ * SR client passes through. We don't depend on mappersmith types
+ * directly so the package compiles without the optional peer installed.
+ */
+interface MmRequest {
+    enhance(args: {
+        headers?: Record<string, string>;
+    }): MmRequest;
+}
+/**
+ * Build a mappersmith middleware that adds `Authorization: Bearer <token>`.
+ *
+ * Exported for testing only — not part of the public API surface. The
+ * middleware resolves the token on EVERY request, so callable token
+ * providers can rotate without re-constructing the serializer. Cache
+ * inside your provider if rotation cost matters.
+ */
+declare function bearerAuthMiddleware(token: string | (() => string | Promise<string>)): () => {
+    prepareRequest(next: () => Promise<MmRequest>): Promise<MmRequest>;
+};
 
-export { type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType };
+export { type SchemaRegistryAuth, type SchemaRegistryClient, SchemaRegistrySerializer, type SchemaRegistrySerializerOptions, type SchemaSpec, type SchemaType, type SubjectNameStrategy, bearerAuthMiddleware };

package/dist/index.js

@@ -3,8 +3,14 @@ var DEFAULT_CONTENT_TYPE = "application/vnd.confluent.avro";
 var SchemaRegistrySerializer = class {
   contentType;
   schemas;
-  subject;
+  keySchemas;
+  subjectStrategy;
+  recordName;
+  subjectFn;
   host;
+  auth;
+  autoRegister;
+  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.
   idCache = /* @__PURE__ */ new Map();
   registry;
   constructor(opts) {
@@ -15,35 +21,107 @@ var SchemaRegistrySerializer = class {
     }
     this.registry = opts.registry ?? null;
     this.host = opts.host ?? null;
+    this.auth = opts.auth ?? null;
     this.schemas = opts.schemas ?? {};
-    this.subject = opts.subject ?? ((topic) => `${topic}-value`);
+    this.keySchemas = opts.keySchemas ?? {};
+    this.subjectStrategy = opts.subjectStrategy ?? "TopicNameStrategy";
+    this.recordName = opts.recordName ?? null;
+    this.subjectFn = opts.subject ?? null;
     this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;
+    this.autoRegister = opts.autoRegister ?? true;
   }
   async serialize(record) {
     const registry = await this.getRegistry();
-    const id = await this.schemaId(registry, record.topic);
+    const subject = this.resolveSubject(record, false);
+    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);
     return registry.encode(id, record.payload);
   }
-  schemaId(registry, topic) {
-    const cached = this.idCache.get(topic);
+  /**
+   * Avro-encode the record's KEY using the registered key schema. Returns
+   * `null` when the record has no key (kafkajs/confluent treat null keys
+   * as the producer-side "no key" signal).
+   *
+   * Not part of the core `Serializer` interface — callers wire it into
+   * their publish path manually when they want Avro keys instead of raw
+   * UTF-8 strings.
+   */
+  async serializeKey(record) {
+    if (record.key === null || record.key === void 0) return null;
+    const registry = await this.getRegistry();
+    const subject = this.resolveSubject(record, true);
+    const id = await this.schemaId(
+      registry,
+      subject,
+      this.keySchemas[record.topic],
+      true,
+      record.topic
+    );
+    return registry.encode(id, record.key);
+  }
+  /**
+   * Resolve the subject for this (record, isKey) tuple. Order of
+   * precedence: explicit `subject` function → `subjectStrategy` preset.
+   */
+  resolveSubject(record, isKey) {
+    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);
+    switch (this.subjectStrategy) {
+      case "TopicNameStrategy":
+        return `${record.topic}-${isKey ? "key" : "value"}`;
+      case "RecordNameStrategy":
+        return this.recordNameFor(record, isKey);
+      case "TopicRecordNameStrategy":
+        return `${record.topic}-${this.recordNameFor(record, isKey)}`;
+    }
+  }
+  recordNameFor(record, isKey) {
+    if (!this.recordName) {
+      throw new Error(
+        `SchemaRegistrySerializer: subjectStrategy "${this.subjectStrategy}" requires a \`recordName\` resolver.`
+      );
+    }
+    return this.recordName(record, isKey);
+  }
+  schemaId(registry, subject, spec, isKey, topic) {
+    const cacheKey = `${topic}:${isKey ? "key" : "value"}`;
+    const cached = this.idCache.get(cacheKey);
     if (cached) return cached;
-    const subject = this.subject(topic);
-    const spec = this.schemas[topic];
-    const lookup = spec ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
+    const lookup = spec && this.autoRegister ? registry.register({ type: spec.type, schema: spec.schema }, { subject }).then((r) => r.id) : registry.getLatestSchemaId(subject);
     const guarded = lookup.catch((err) => {
-      this.idCache.delete(topic);
+      this.idCache.delete(cacheKey);
       throw err;
     });
-    this.idCache.set(topic, guarded);
+    this.idCache.set(cacheKey, guarded);
     return guarded;
   }
   async getRegistry() {
     if (this.registry) return this.registry;
     const mod = await importSchemaRegistry();
-    this.registry = new mod.SchemaRegistry({ host: this.host });
+    const cfg = {
+      host: this.host
+    };
+    if (this.auth) {
+      if (this.auth.type === "basic") {
+        cfg.auth = {
+          username: this.auth.username,
+          password: this.auth.password
+        };
+      } else {
+        cfg.middlewares = [bearerAuthMiddleware(this.auth.token)];
+      }
+    }
+    this.registry = new mod.SchemaRegistry(cfg);
     return this.registry;
   }
 };
+function bearerAuthMiddleware(token) {
+  return () => ({
+    async prepareRequest(next) {
+      const request = await next();
+      const value = typeof token === "function" ? await token() : token;
+      return request.enhance({ headers: { Authorization: `Bearer ${value}` } });
+    }
+  });
+}
 async function importSchemaRegistry() {
   try {
     return await import("@kafkajs/confluent-schema-registry");
@@ -54,6 +132,7 @@ async function importSchemaRegistry() {
   }
 }
 export {
-  SchemaRegistrySerializer
+  SchemaRegistrySerializer,
+  bearerAuthMiddleware
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/serializer.ts"],"sourcesContent":["import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /** Per-topic schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /** Subject naming. Default TopicNameStrategy: `${topic}-value`. */\n  subject?: (topic: string) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per topic is resolved once and cached.\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly subject: (topic: string) => string;\n  private readonly host: string | null;\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.subject = opts.subject ?? ((topic) => `${topic}-value`);\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const id = await this.schemaId(registry, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    topic: string,\n  ): Promise<number> {\n    const cached = this.idCache.get(topic);\n    if (cached) return cached;\n\n    const subject = this.subject(topic);\n    const spec = this.schemas[topic];\n    const lookup = spec\n      ? registry\n          .register({ type: spec.type, schema: spec.schema }, { subject })\n          .then((r) => r.id)\n      : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(topic);\n      throw err;\n    });\n    this.idCache.set(topic, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    this.registry = new mod.SchemaRegistry({ host: this.host as string });\n    return this.registry;\n  }\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (cfg: { host: string }) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":";AAoCA,IAAM,uBAAuB;AAOtB,IAAM,2BAAN,MAAqD;AAAA,EACjD;AAAA,EACQ;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU,oBAAI,IAA6B;AAAA,EACpD;AAAA,EAER,YAAY,MAAuC;AACjD,QAAI,CAAC,KAAK,YAAY,CAAC,KAAK,MAAM;AAChC,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,WAAW,KAAK,YAAY;AACjC,SAAK,OAAO,KAAK,QAAQ;AACzB,SAAK,UAAU,KAAK,WAAW,CAAC;AAChC,SAAK,UAAU,KAAK,YAAY,CAAC,UAAU,GAAG,KAAK;AACnD,SAAK,cAAc,KAAK,eAAe;AAAA,EACzC;AAAA,EAEA,MAAM,UAAU,QAAuC;AACrD,UAAM,WAAW,MAAM,KAAK,YAAY;AACxC,UAAM,KAAK,MAAM,KAAK,SAAS,UAAU,OAAO,KAAK;AACrD,WAAO,SAAS,OAAO,IAAI,OAAO,OAAO;AAAA,EAC3C;AAAA,EAEQ,SACN,UACA,OACiB;AACjB,UAAM,SAAS,KAAK,QAAQ,IAAI,KAAK;AACrC,QAAI,OAAQ,QAAO;AAEnB,UAAM,UAAU,KAAK,QAAQ,KAAK;AAClC,UAAM,OAAO,KAAK,QAAQ,KAAK;AAC/B,UAAM,SAAS,OACX,SACG,SAAS,EAAE,MAAM,KAAK,MAAM,QAAQ,KAAK,OAAO,GAAG,EAAE,QAAQ,CAAC,EAC9D,KAAK,CAAC,MAAM,EAAE,EAAE,IACnB,SAAS,kBAAkB,OAAO;AAItC,UAAM,UAAU,OAAO,MAAM,CAAC,QAAQ;AACpC,WAAK,QAAQ,OAAO,KAAK;AACzB,YAAM;AAAA,IACR,CAAC;AACD,SAAK,QAAQ,IAAI,OAAO,OAAO;AAC/B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,cAA6C;AACzD,QAAI,KAAK,SAAU,QAAO,KAAK;AAC/B,UAAM,MAAM,MAAM,qBAAqB;AACvC,SAAK,WAAW,IAAI,IAAI,eAAe,EAAE,MAAM,KAAK,KAAe,CAAC;AACpE,WAAO,KAAK;AAAA,EACd;AACF;AAEA,eAAe,uBAEZ;AACD,MAAI;AAEF,WAAQ,MAAM,OAAO,oCAAoC;AAAA,EAC3D,QAAQ;AACN,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/serializer.ts"],"sourcesContent":["import type { OutboxRecord, Serializer } from \"@eventferry/core\";\n\nexport type SchemaType = \"AVRO\" | \"PROTOBUF\" | \"JSON\";\n\nexport interface SchemaSpec {\n  type: SchemaType;\n  /** Schema definition string (avsc JSON / .proto / JSON Schema). */\n  schema: string;\n}\n\n/**\n * Subject naming strategy. Mirrors Confluent's three built-ins:\n *\n * - `\"TopicNameStrategy\"` (default) — `${topic}-value` / `${topic}-key`.\n *   The conventional default; one schema per (topic, isKey) tuple.\n * - `\"RecordNameStrategy\"` — `${recordName}`. Same record type can flow\n *   on multiple topics. Requires a `recordName` resolver.\n * - `\"TopicRecordNameStrategy\"` — `${topic}-${recordName}`. Multiple record\n *   types per topic. Requires a `recordName` resolver.\n *\n * Set `subject` (function form) to override entirely.\n */\nexport type SubjectNameStrategy =\n  | \"TopicNameStrategy\"\n  | \"RecordNameStrategy\"\n  | \"TopicRecordNameStrategy\";\n\n/**\n * Authentication for the Schema Registry HTTP API.\n *\n * - `\"basic\"` — HTTP Basic Auth. The shape Confluent Cloud and most\n *   commercial registries use; passed straight through to the underlying\n *   client's `auth` config.\n * - `\"bearer\"` — `Authorization: Bearer <token>` header. The `token`\n *   field accepts either a static string OR a callable that resolves a\n *   fresh token on every request (cache inside your callable to amortise\n *   cost; we don't memoize for you, so OAuth refresh-loop logic lives\n *   on your side).\n *\n * mTLS for the registry connection itself is handled by Node's `tls`\n * stack — supply a custom `https.Agent` via the upstream client's\n * `agent` option (use the `registry` injection here and configure it\n * yourself), separate from the broker TLS the publisher uses.\n */\nexport type SchemaRegistryAuth =\n  | { type: \"basic\"; username: string; password: string }\n  | {\n      type: \"bearer\";\n      token: string | (() => string | Promise<string>);\n    };\n\n/**\n * The subset of a Confluent Schema Registry client this serializer uses. The\n * `@kafkajs/confluent-schema-registry` `SchemaRegistry` satisfies it structurally.\n */\nexport interface SchemaRegistryClient {\n  register(\n    schema: { type: string; schema: string },\n    opts?: { subject: string },\n  ): Promise<{ id: number }>;\n  getLatestSchemaId(subject: string): Promise<number>;\n  encode(registryId: number, payload: unknown): Promise<Buffer>;\n}\n\nexport interface SchemaRegistrySerializerOptions {\n  /** Inject a ready client (tests, custom config). */\n  registry?: SchemaRegistryClient;\n  /** Or construct one from a host (requires @kafkajs/confluent-schema-registry). */\n  host?: string;\n  /**\n   * Optional authentication for the Schema Registry HTTP API. See\n   * {@link SchemaRegistryAuth} for the two supported shapes. Ignored\n   * when `registry` is provided (configure auth on the injected client\n   * yourself in that case).\n   */\n  auth?: SchemaRegistryAuth;\n  /** Per-topic VALUE schema to register. Topics omitted here use the subject's latest. */\n  schemas?: Record<string, SchemaSpec>;\n  /**\n   * Per-topic KEY schema. When set, `serializeKey(record)` Avro-encodes\n   * the record key for the matching topic. Topics omitted here fall back\n   * to the subject's latest (or, with `autoRegister: false`, ALWAYS the\n   * subject's latest).\n   */\n  keySchemas?: Record<string, SchemaSpec>;\n  /**\n   * Subject naming strategy preset. Default `\"TopicNameStrategy\"`.\n   * Setting `subject` (function) overrides this entirely.\n   */\n  subjectStrategy?: SubjectNameStrategy;\n  /**\n   * Resolve the schema's record name (used by `RecordNameStrategy` and\n   * `TopicRecordNameStrategy`). REQUIRED when `subjectStrategy` is set to\n   * one of those — throws on first serialize if absent.\n   *\n   * Typical implementation: read `${namespace}.${name}` from the avsc you\n   * already supply via `schemas` / `keySchemas`.\n   */\n  recordName?: (record: OutboxRecord, isKey: boolean) => string;\n  /**\n   * Custom subject function — overrides BOTH `subjectStrategy` and\n   * `recordName`. Receives `(topic, isKey, record)` for full flexibility.\n   *\n   * Backwards-compatible with the single-argument legacy form\n   * `(topic) => string` — extra args are ignored by JavaScript.\n   */\n  subject?: (\n    topic: string,\n    isKey?: boolean,\n    record?: OutboxRecord,\n  ) => string;\n  /** content-type header value. Default \"application/vnd.confluent.avro\". */\n  contentType?: string;\n  /**\n   * Auto-register schemas when one is supplied via `schemas` / `keySchemas`.\n   * Default `true` — matches Confluent client behavior.\n   *\n   * Set to `false` for production clusters where schemas are managed\n   * out-of-band (Confluent Cloud, regulated environments). With\n   * autoRegister off, the serializer ALWAYS resolves by `getLatestSchemaId`\n   * on the computed subject — and the locally-supplied schema bytes are\n   * ignored.\n   */\n  autoRegister?: boolean;\n}\n\nconst DEFAULT_CONTENT_TYPE = \"application/vnd.confluent.avro\";\n\n/**\n * A core {@link Serializer} that encodes payloads with a Confluent Schema Registry\n * (Avro / Protobuf / JSON Schema). Drop it into `Relay`/`PostgresStreamingRelay`'s\n * `serializer` option. The schema id per (topic, isKey) tuple is resolved once\n * and cached.\n *\n * Also exposes `serializeKey(record)` for users who want Avro-encoded message\n * keys — call it manually when building the publish path; the relay does NOT\n * call it automatically (key encoding is application-level by convention).\n */\nexport class SchemaRegistrySerializer implements Serializer {\n  readonly contentType: string;\n  private readonly schemas: Record<string, SchemaSpec>;\n  private readonly keySchemas: Record<string, SchemaSpec>;\n  private readonly subjectStrategy: SubjectNameStrategy;\n  private readonly recordName:\n    | ((record: OutboxRecord, isKey: boolean) => string)\n    | null;\n  private readonly subjectFn:\n    | ((topic: string, isKey?: boolean, record?: OutboxRecord) => string)\n    | null;\n  private readonly host: string | null;\n  private readonly auth: SchemaRegistryAuth | null;\n  private readonly autoRegister: boolean;\n  // Keyed by `${topic}:${isKey}` to keep value- and key-subject ids distinct.\n  private readonly idCache = new Map<string, Promise<number>>();\n  private registry: SchemaRegistryClient | null;\n\n  constructor(opts: SchemaRegistrySerializerOptions) {\n    if (!opts.registry && !opts.host) {\n      throw new Error(\n        \"SchemaRegistrySerializer requires either a `registry` client or a `host`.\",\n      );\n    }\n    this.registry = opts.registry ?? null;\n    this.host = opts.host ?? null;\n    this.auth = opts.auth ?? null;\n    this.schemas = opts.schemas ?? {};\n    this.keySchemas = opts.keySchemas ?? {};\n    this.subjectStrategy = opts.subjectStrategy ?? \"TopicNameStrategy\";\n    this.recordName = opts.recordName ?? null;\n    this.subjectFn = opts.subject ?? null;\n    this.contentType = opts.contentType ?? DEFAULT_CONTENT_TYPE;\n    this.autoRegister = opts.autoRegister ?? true;\n  }\n\n  async serialize(record: OutboxRecord): Promise<Buffer> {\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, false);\n    const id = await this.schemaId(registry, subject, this.schemas[record.topic], false, record.topic);\n    return registry.encode(id, record.payload);\n  }\n\n  /**\n   * Avro-encode the record's KEY using the registered key schema. Returns\n   * `null` when the record has no key (kafkajs/confluent treat null keys\n   * as the producer-side \"no key\" signal).\n   *\n   * Not part of the core `Serializer` interface — callers wire it into\n   * their publish path manually when they want Avro keys instead of raw\n   * UTF-8 strings.\n   */\n  async serializeKey(record: OutboxRecord): Promise<Buffer | null> {\n    if (record.key === null || record.key === undefined) return null;\n    const registry = await this.getRegistry();\n    const subject = this.resolveSubject(record, true);\n    const id = await this.schemaId(\n      registry,\n      subject,\n      this.keySchemas[record.topic],\n      true,\n      record.topic,\n    );\n    return registry.encode(id, record.key);\n  }\n\n  /**\n   * Resolve the subject for this (record, isKey) tuple. Order of\n   * precedence: explicit `subject` function → `subjectStrategy` preset.\n   */\n  private resolveSubject(record: OutboxRecord, isKey: boolean): string {\n    if (this.subjectFn) return this.subjectFn(record.topic, isKey, record);\n    switch (this.subjectStrategy) {\n      case \"TopicNameStrategy\":\n        return `${record.topic}-${isKey ? \"key\" : \"value\"}`;\n      case \"RecordNameStrategy\":\n        return this.recordNameFor(record, isKey);\n      case \"TopicRecordNameStrategy\":\n        return `${record.topic}-${this.recordNameFor(record, isKey)}`;\n    }\n  }\n\n  private recordNameFor(record: OutboxRecord, isKey: boolean): string {\n    if (!this.recordName) {\n      throw new Error(\n        `SchemaRegistrySerializer: subjectStrategy \"${this.subjectStrategy}\" requires a \\`recordName\\` resolver.`,\n      );\n    }\n    return this.recordName(record, isKey);\n  }\n\n  private schemaId(\n    registry: SchemaRegistryClient,\n    subject: string,\n    spec: SchemaSpec | undefined,\n    isKey: boolean,\n    topic: string,\n  ): Promise<number> {\n    const cacheKey = `${topic}:${isKey ? \"key\" : \"value\"}`;\n    const cached = this.idCache.get(cacheKey);\n    if (cached) return cached;\n\n    // autoRegister=false → ALWAYS resolve by latest; the local spec\n    // (if any) is ignored. Matches Confluent's auto.register.schemas=false.\n    const lookup =\n      spec && this.autoRegister\n        ? registry\n            .register({ type: spec.type, schema: spec.schema }, { subject })\n            .then((r) => r.id)\n        : registry.getLatestSchemaId(subject);\n\n    // Cache the in-flight promise so concurrent first calls don't double-register;\n    // drop it on failure so a transient error can be retried.\n    const guarded = lookup.catch((err) => {\n      this.idCache.delete(cacheKey);\n      throw err;\n    });\n    this.idCache.set(cacheKey, guarded);\n    return guarded;\n  }\n\n  private async getRegistry(): Promise<SchemaRegistryClient> {\n    if (this.registry) return this.registry;\n    const mod = await importSchemaRegistry();\n    const cfg: SchemaRegistryConstructorConfig = {\n      host: this.host as string,\n    };\n    if (this.auth) {\n      if (this.auth.type === \"basic\") {\n        // Confluent SR client accepts `auth: { username, password }`\n        // and the mappersmith basic-auth middleware builds the header.\n        cfg.auth = {\n          username: this.auth.username,\n          password: this.auth.password,\n        };\n      } else {\n        // Bearer: SR doesn't ship a built-in middleware. Inject our own\n        // so every API call carries `Authorization: Bearer <token>`.\n        cfg.middlewares = [bearerAuthMiddleware(this.auth.token)];\n      }\n    }\n    this.registry = new mod.SchemaRegistry(cfg);\n    return this.registry;\n  }\n}\n\n/**\n * Mappersmith middleware shape — the structural subset the Confluent\n * SR client passes through. We don't depend on mappersmith types\n * directly so the package compiles without the optional peer installed.\n */\ninterface MmRequest {\n  enhance(args: { headers?: Record<string, string> }): MmRequest;\n}\n\n/**\n * Build a mappersmith middleware that adds `Authorization: Bearer <token>`.\n *\n * Exported for testing only — not part of the public API surface. The\n * middleware resolves the token on EVERY request, so callable token\n * providers can rotate without re-constructing the serializer. Cache\n * inside your provider if rotation cost matters.\n */\nexport function bearerAuthMiddleware(\n  token: string | (() => string | Promise<string>),\n) {\n  return () => ({\n    async prepareRequest(next: () => Promise<MmRequest>): Promise<MmRequest> {\n      const request = await next();\n      const value = typeof token === \"function\" ? await token() : token;\n      return request.enhance({ headers: { Authorization: `Bearer ${value}` } });\n    },\n  });\n}\n\n/**\n * Structural shape the SR client's constructor accepts. Mirrors\n * `SchemaRegistryAPIClientArgs` from the upstream package without\n * importing the type directly (optional peer).\n */\ninterface SchemaRegistryConstructorConfig {\n  host: string;\n  auth?: { username: string; password: string };\n  middlewares?: Array<() => unknown>;\n}\n\nasync function importSchemaRegistry(): Promise<{\n  SchemaRegistry: new (\n    cfg: SchemaRegistryConstructorConfig,\n  ) => SchemaRegistryClient;\n}> {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    return (await import(\"@kafkajs/confluent-schema-registry\")) as any;\n  } catch {\n    throw new Error(\n      'SchemaRegistrySerializer with `host` needs the \"@kafkajs/confluent-schema-registry\" package. Run: npm i @kafkajs/confluent-schema-registry',\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventferry/schema-registry",
-  "version": "3.2.3",
+  "version": "3.4.0",
   "description": "Confluent Schema Registry serializer for @eventferry (Avro/Protobuf/JSON Schema)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,6 +17,9 @@
     "dist",
     "CHANGELOG.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "outbox",
     "transactional-outbox",
@@ -45,7 +48,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@eventferry/core": "3.3.1"
+    "@eventferry/core": "3.4.0"
   },
   "peerDependencies": {
     "@kafkajs/confluent-schema-registry": "^3.0.0"
@@ -59,8 +62,8 @@
     "@kafkajs/confluent-schema-registry": "^3.0.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
-    "@eventferry/core": "3.3.1"
+    "vitest": "^3.2.6",
+    "@eventferry/core": "3.4.0"
   },
   "scripts": {
     "build": "tsup",