@confluentinc/mcp-confluent 1.4.0 → 1.6.0

package/dist/confluent/oauth-resource-resolvers.js

@@ -37,6 +37,30 @@ export async function resolveSchemaRegistryEndpoint(cloudClient, clusterId, envI
     }
     return httpEndpoint;
 }
+/**
+ * Resolves the cloud provider + region of a Flink compute pool, used to derive
+ * the regional Flink REST host under OAuth. The Flink REST URL is regional
+ * (`https://flink.<region>.<cloud>.<base-domain>`), so unlike the cloud/
+ * telemetry surfaces it can't be wired once at construction — it has to be
+ * resolved per call from the compute pool the agent is targeting.
+ */
+export async function resolveFlinkComputePoolRegion(cloudClient, computePoolId, envId) {
+    const { data, error } = await cloudClient.GET("/fcpm/v2/compute-pools/{id}", {
+        params: { path: { id: computePoolId }, query: { environment: envId } },
+    });
+    if (error !== undefined) {
+        throw new Error(`Failed to read Flink compute pool ${computePoolId} in environment ${envId}: ${JSON.stringify(error)}`);
+    }
+    const cloud = data?.spec?.cloud;
+    const region = data?.spec?.region;
+    if (typeof cloud !== "string" ||
+        cloud.length === 0 ||
+        typeof region !== "string" ||
+        region.length === 0) {
+        throw new Error(`Compute pool ${computePoolId} in environment ${envId} has no cloud/region in its spec`);
+    }
+    return { cloud, region };
+}
 export async function resolveSchemaRegistryClusterId(cloudClient, envId) {
     const { data, error } = await cloudClient.GET("/srcm/v3/clusters", {
         params: { query: { environment: envId } },

package/dist/confluent/oauth-resource-resolvers.js.map

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

package/dist/confluent/schema-registry-helper.d.ts

@@ -3,7 +3,17 @@
  * It handles schema registration, serialization, and deserialization of messages
  * using various schema formats (AVRO, JSON, PROTOBUF).
  */
-import { Deserializer, SchemaRegistryClient, SerdeType, Serializer } from "@confluentinc/schemaregistry";
+import type { MutableRegistry } from "@bufbuild/protobuf";
+import type { IHeaders } from "@confluentinc/kafka-javascript/types/kafkajs.js";
+import type { Deserializer, SchemaRegistryClient, Serializer, SerializerConfig } from "@confluentinc/schemaregistry";
+import { SerdeType } from "@confluentinc/schemaregistry";
+/**
+ * Where the Schema Registry schema ID rides on the wire. "payload" embeds it as
+ * magic bytes at the front of the serialized payload (the default Confluent
+ * wire format); "header" writes the schema GUID to the __value_schema_id /
+ * __key_schema_id Kafka record header and leaves the payload as bare bytes.
+ */
+export type SchemaIdLocation = "payload" | "header";
 /**
  * Supported schema types for Confluent Schema Registry.
  * AVRO: Apache Avro binary format with schema evolution support
@@ -21,18 +31,32 @@ export interface SchemaRegistryOptions {
     schema?: string;
     subject?: string;
     normalize?: boolean;
+    /**
+     * Fully-qualified Protobuf message type to encode the payload as
+     * (e.g. `com.example.User`). Required when `schemaType` is `PROTOBUF`,
+     * ignored otherwise.
+     */
+    messageName?: string;
+    schemaIdLocation?: SchemaIdLocation;
 }
 /**
  * Options for message serialization/deserialization.
  * Includes the message payload and schema registry configuration.
  */
 export type MessageOptions = {
-    message: Buffer | object | string;
+    message: Buffer | object | string | number | boolean;
     useSchemaRegistry?: boolean;
     schemaType?: SchemaType;
     schema?: string;
     subject?: string;
     normalize?: boolean;
+    /**
+     * Fully-qualified Protobuf message type to encode the payload as
+     * (e.g. `com.example.User`). Required when `schemaType` is `PROTOBUF`,
+     * ignored otherwise.
+     */
+    messageName?: string;
+    schemaIdLocation?: SchemaIdLocation;
 };
 /**
  * Result of checking if a schema is needed for a message.
@@ -48,16 +72,25 @@ export type SchemaCheckResult = {
 } | null;
 /**
  * Creates and returns the appropriate serializer instance based on schema type.
- * The serializer is configured to use either a specific schema ID or the latest version.
+ *
+ * This is a pure factory: it maps a {@link SchemaType} to its serializer
+ * constructor and forwards the caller-built {@link SerializerConfig}. The
+ * format-specific *decisions* — schema-id vs. use-latest for AVRO/JSON, plus the descriptor registry for PROTOBUF — live
+ * with the callers ({@link serializeMessage}, {@link serializeProtobufMessage}),
+ * which is why the config arrives ready-made. For PROTOBUF the descriptor
+ * registry rides inside the config as its optional `registry` field
+ * (`ProtobufSerializerConfig = SerializerConfig & { registry?: MutableRegistry }`).
  *
  * @param schemaType - The type of schema (AVRO, JSON, PROTOBUF)
  * @param registry - The schema registry client instance
  * @param serdeType - Whether this is for key or value serialization
- * @param schemaId - Optional schema ID to use for serialization
+ * @param serializerConfig - The serializer configuration to forward (use-latest,
+ *   use-schema-id, the optional `schemaIdLocation` header serializer, and/or the
+ *   PROTOBUF descriptor registry)
  * @returns The appropriate Serializer instance
  * @throws Error if the schema type is unknown or unsupported
  */
-export declare function getSerializer(schemaType: SchemaType | undefined, registry: SchemaRegistryClient, serdeType: SerdeType, schemaId?: number): Serializer;
+export declare function getSerializer(schemaType: SchemaType | undefined, registry: SchemaRegistryClient, serdeType: SerdeType, serializerConfig: SerializerConfig): Serializer;
 /**
  * Creates and returns the appropriate deserializer instance based on schema type.
  * The deserializer is configured to handle schema evolution and compatibility.
@@ -96,6 +129,81 @@ export declare function getLatestSchemaIfExists(registry: SchemaRegistryClient,
     schema: string;
     schemaType: SchemaType;
 } | null>;
+/**
+ * Fetches the latest registered schema for a subject and asserts it matches the
+ * requested schema type. Without this guard a use-latest produce against a
+ * subject registered with a different format fails deep inside the serializer
+ * with an opaque parse/decode error (e.g. an AvroSerializer trying to parse a
+ * JSON schema string, or the Protobuf path base64-decoding an Avro schema);
+ * surfacing the mismatch here gives the caller an actionable message instead.
+ *
+ * @param registry - The schema registry client instance
+ * @param subject - The resolved Schema Registry subject
+ * @param expected - The schema type the caller asked to produce with
+ * @returns The latest schema string and (matching) schema type
+ * @throws Error if no schema is registered for the subject, or the registered
+ *   schema type differs from `expected`
+ */
+export declare function getLatestSchemaOfTypeOrThrow(registry: SchemaRegistryClient, subject: string, expected: SchemaType): Promise<{
+    schema: string;
+    schemaType: SchemaType;
+}>;
+/**
+ * Builds a `@bufbuild/protobuf` descriptor registry from raw `.proto` schema text.
+ *
+ * The `@confluentinc/schemaregistry` ProtobufSerializer encodes locally against
+ * a descriptor registry, so we parse the `.proto` text with protobufjs, export
+ * it to a canonical `FileDescriptorSet` (the standard `google.protobuf` wire
+ * format), and read that into a registry. This is the path used when the caller
+ * supplies the schema on a produce.
+ *
+ * @param protoText - The `.proto` schema definition (proto3)
+ * @returns A mutable descriptor registry the serializer can consume
+ * @throws Error if the `.proto` text cannot be parsed
+ */
+export declare function protobufRegistryFromProto(protoText: string): MutableRegistry;
+/**
+ * Builds a descriptor registry from a Protobuf schema as stored in Schema
+ * Registry — a base64-encoded `FileDescriptorProto` (the "serialized" format
+ * this SDK reads/writes). Used on the use-latest produce path, where the schema
+ * was previously registered by the serializer rather than supplied as text.
+ *
+ * @param serializedSchema - base64-encoded `FileDescriptorProto`
+ * @returns A mutable descriptor registry the serializer can consume
+ * @throws Error if the stored schema cannot be decoded
+ */
+export declare function protobufRegistryFromSerialized(serializedSchema: string): MutableRegistry;
+/**
+ * Builds a descriptor registry from a Protobuf schema as stored in Schema
+ * Registry, regardless of which client registered it. Two formats are in the
+ * wild for the same subject: this SDK's own serializer stores a base64
+ * `FileDescriptorProto` (see {@link protobufRegistryFromSerialized}), while the
+ * standard Schema Registry REST API (and other clients) store literal `.proto`
+ * source text (see {@link protobufRegistryFromProto}). The stored schema
+ * carries no explicit tag for which one it is, so this tries the serialized
+ * form first and falls back to `.proto` text parsing on failure.
+ *
+ * @param storedSchema - The schema string as returned by the registry for the
+ *   subject (either base64 `FileDescriptorProto` or `.proto` text)
+ * @returns A mutable descriptor registry the serializer can consume
+ * @throws Error if the stored schema matches neither format
+ */
+export declare function protobufRegistryFromStoredSchema(storedSchema: string): MutableRegistry;
+/**
+ * Converts a plain JS payload into a typed `@bufbuild/protobuf` message (carrying
+ * the `$typeName` the ProtobufSerializer requires) using a descriptor registry.
+ *
+ * @param registry - Descriptor registry containing the target message type
+ * @param messageName - Fully-qualified message type name (e.g. `com.example.User`)
+ * @param payload - The payload to encode. Keys may use either the proto field
+ *   name (`user_id`) or its auto-generated camelCase JSON name (`userId`):
+ *   `fromJson` accepts both and maps them onto the same field. Keys that match
+ *   neither are rejected as unknown fields.
+ * @returns The typed protobuf message
+ * @throws Error if `messageName` does not match a message in the registry (the
+ *   error lists the available names)
+ */
+export declare function protobufMessageFrom(registry: MutableRegistry, messageName: string, payload: object): object;
 /**
  * Serializes a message using the provided options and schema registry configuration.
  * This function:
@@ -108,10 +216,13 @@ export declare function getLatestSchemaIfExists(registry: SchemaRegistryClient,
  * @param options - The message options including schema, type, and payload
  * @param serdeType - Whether this is for key or value serialization
  * @param registry - The schema registry client instance (if used)
+ * @param recordHeaders - Mutable record-header accumulator. Required for
+ *   `schemaIdLocation: "header"`, where the serializer writes the schema-id
+ *   header into it; ignored by the payload format and the raw (non-registry) path.
  * @returns The serialized message as a Buffer or string
  * @throws Error if serialization fails, schema registration fails, or message type is invalid
  */
-export declare function serializeMessage(topicName: string, options: MessageOptions, serdeType: SerdeType, registry: SchemaRegistryClient | undefined): Promise<Buffer | string>;
+export declare function serializeMessage(topicName: string, options: MessageOptions, serdeType: SerdeType, registry: SchemaRegistryClient | undefined, recordHeaders?: IHeaders): Promise<Buffer | string>;
 /**
  * Deserializes a message using Schema Registry.
  * This function:
@@ -123,8 +234,21 @@ export declare function serializeMessage(topicName: string, options: MessageOpti
  * @param schemaType - The schema type (AVRO, JSON, PROTOBUF)
  * @param registry - The schema registry client
  * @param serdeType - Whether this is key or value
+ * @param headers - Raw record headers. When present, the default dual
+ *   deserializer reads a header-located schema ID (__value_schema_id /
+ *   __key_schema_id) before falling back to the magic-byte prefix.
  * @returns The deserialized object
  * @throws Error if deserialization fails
  */
-export declare function deserializeMessage(topic: string, message: Buffer, schemaType: SchemaType, registry: SchemaRegistryClient, serdeType: SerdeType): Promise<unknown>;
+export declare function deserializeMessage(topic: string, message: Buffer, schemaType: SchemaType, registry: SchemaRegistryClient, serdeType: SerdeType, headers?: IHeaders): Promise<unknown>;
+/**
+ * Decode a header-located schema-id record-header value into its canonical
+ * schema GUID string. The header wire format (written by the serde library's
+ * HeaderSchemaIdSerializer) is MAGIC_BYTE_V1 followed by the 16-byte GUID; the
+ * schema type only governs the Protobuf message-index tail that the GUID read
+ * ignores, so a fixed type is safe here. Returns null when the bytes aren't a
+ * recognizable GUID header (e.g. a payload-format magic-byte-0 buffer, or
+ * garbage), letting the caller fall back to echoing the raw value.
+ */
+export declare function decodeSchemaGuidHeader(headerValue: Buffer): string | null;
 //# sourceMappingURL=schema-registry-helper.d.ts.map

package/dist/confluent/schema-registry-helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-registry-helper.d.ts","sourceRoot":"","sources":["../../src/confluent/schema-registry-helper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGL,YAAY,EAMZ,oBAAoB,EACpB,SAAS,EACT,UAAU,EAEX,MAAM,8BAA8B,CAAC;AAGtC;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,UAAU,CAkBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,GACnB,YAAY,CAed;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,OAAO,CAAC,iBAAiB,CAAC,CAa5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GAAG,IAAI,CAAC,CAiB5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,oBAAoB,GAAG,SAAS,GACzC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAgE1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,OAAO,CAAC,CAOlB"}
+{"version":3,"file":"schema-registry-helper.d.ts","sourceRoot":"","sources":["../../src/confluent/schema-registry-helper.ts"],"names":[],"mappings":"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"}