@blokjs/trigger-pubsub 0.2.3 → 0.6.1

package/src/adapters/AWSSNSAdapter.ts

@@ -14,10 +14,27 @@
  * - SQS_MAX_MESSAGES: Max messages per receive (default: 10)
  */
 
+import type { MessageAttributeValue, SQSClient } from "@aws-sdk/client-sqs";
 import type { PubSubTriggerOpts } from "@blokjs/helper";
 import { v4 as uuid } from "uuid";
 import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
 
+/**
+ * Shape of an SNS notification when delivered to an SQS subscription.
+ * SNS-to-SQS subscriptions wrap the publisher's payload inside a JSON
+ * envelope; the receiver parses `msg.Body` as this envelope and reads
+ * `Message` (the actual payload) plus the SNS-side attributes.
+ */
+interface SNSNotificationEnvelope {
+	Type?: string;
+	MessageId?: string;
+	TopicArn?: string;
+	Message?: string;
+	Subject?: string;
+	Timestamp?: string;
+	MessageAttributes?: Record<string, { Type?: string; Value?: string }>;
+}
+
 /**
  * AWS SNS/SQS configuration
  */
@@ -33,12 +50,23 @@ export interface AWSSNSConfig {
 export class AWSSNSAdapter implements PubSubAdapter {
 	readonly provider = "aws" as const;
 
-	private sqsClient: any;
+	private sqsClient: SQSClient | undefined;
 	private connected = false;
 	private config: AWSSNSConfig;
 	private pollingIntervals: Map<string, NodeJS.Timeout> = new Map();
 	private shouldStop = false;
 
+	/**
+	 * Type-narrowing accessor for `this.sqsClient`. Field is undefined
+	 * until `connect()` runs.
+	 */
+	private requireSqsClient(): SQSClient {
+		if (!this.sqsClient) {
+			throw new Error("[AWSSNSAdapter] SQS client is not initialised — call connect() first");
+		}
+		return this.sqsClient;
+	}
+
 	constructor(config?: Partial<AWSSNSConfig>) {
 		this.config = {
 			region: config?.region || process.env.AWS_REGION || "us-east-1",
@@ -66,8 +94,7 @@ export class AWSSNSAdapter implements PubSubAdapter {
 			console.log(`[AWSSNSAdapter] Connected to AWS SNS/SQS: ${this.config.region}`);
 		} catch (error) {
 			throw new Error(
-				`Failed to connect to AWS: ${(error as Error).message}. ` +
-					`Make sure @aws-sdk/client-sqs is installed: npm install @aws-sdk/client-sqs`,
+				`Failed to connect to AWS: ${(error as Error).message}. Make sure @aws-sdk/client-sqs is installed: npm install @aws-sdk/client-sqs`,
 			);
 		}
 	}
@@ -99,7 +126,10 @@ export class AWSSNSAdapter implements PubSubAdapter {
 			throw new Error("Not connected to AWS. Call connect() first.");
 		}
 
-		// In AWS, subscription is the SQS queue URL that's subscribed to the SNS topic
+		// In AWS, subscription is the SQS queue URL that's subscribed to the SNS topic.
+		if (!config.subscription) {
+			throw new Error("[AWSSNSAdapter] `subscription` is required — must be the SQS queue URL bound to the SNS topic.");
+		}
 		const queueUrl = config.subscription;
 
 		// Start polling the SQS queue
@@ -129,16 +159,16 @@ export class AWSSNSAdapter implements PubSubAdapter {
 				AttributeNames: ["All"],
 			});
 
-			const response = await this.sqsClient.send(command);
+			const response = await this.requireSqsClient().send(command);
 
 			if (response.Messages && response.Messages.length > 0) {
 				for (const msg of response.Messages) {
 					// Parse SNS message wrapper
-					let snsMessage: any;
+					let snsMessage: SNSNotificationEnvelope;
 					let body: unknown;
 
 					try {
-						snsMessage = JSON.parse(msg.Body || "{}");
+						snsMessage = JSON.parse(msg.Body || "{}") as SNSNotificationEnvelope;
 						// SNS wraps the actual message in a "Message" field
 						if (snsMessage.Type === "Notification" && snsMessage.Message) {
 							try {
@@ -160,14 +190,15 @@ export class AWSSNSAdapter implements PubSubAdapter {
 					// SQS message attributes
 					if (msg.MessageAttributes) {
 						for (const [key, attr] of Object.entries(msg.MessageAttributes)) {
-							attributes[key] = (attr as any).StringValue || "";
+							const sqsAttr = attr as MessageAttributeValue;
+							attributes[key] = sqsAttr.StringValue || "";
 						}
 					}
 
 					// SNS message attributes (if present)
 					if (snsMessage.MessageAttributes) {
 						for (const [key, attr] of Object.entries(snsMessage.MessageAttributes)) {
-							attributes[`sns_${key}`] = (attr as any).Value || "";
+							attributes[`sns_${key}`] = attr.Value || "";
 						}
 					}
 
@@ -185,7 +216,7 @@ export class AWSSNSAdapter implements PubSubAdapter {
 								QueueUrl: queueUrl,
 								ReceiptHandle: msg.ReceiptHandle,
 							});
-							await this.sqsClient.send(deleteCommand);
+							await this.requireSqsClient().send(deleteCommand);
 						},
 						nack: async () => {
 							// Let the visibility timeout expire to return the message
@@ -196,7 +227,7 @@ export class AWSSNSAdapter implements PubSubAdapter {
 								ReceiptHandle: msg.ReceiptHandle,
 								VisibilityTimeout: 0,
 							});
-							await this.sqsClient.send(changeCommand);
+							await this.requireSqsClient().send(changeCommand);
 						},
 					};
 
@@ -238,6 +269,39 @@ export class AWSSNSAdapter implements PubSubAdapter {
 		return this.connected;
 	}
 
+	/**
+	 * v0.7 PR 6 — publish to an SNS topic.
+	 *
+	 * `topic` must be the SNS topic ARN. `partitionKey` /
+	 * `orderingKey` map to the FIFO `MessageGroupId` field for
+	 * `.fifo` topics; ignored otherwise.
+	 */
+	async publish(
+		topic: string,
+		payload: unknown,
+		opts?: { partitionKey?: string; orderingKey?: string },
+	): Promise<void> {
+		if (!this.connected) throw new Error("[blok][pubsub-aws] not connected. Call connect() first.");
+		const moduleName = "@aws-sdk/client-sns";
+		// biome-ignore lint/suspicious/noExplicitAny: SDK loaded at runtime as a peer dep.
+		const sns: any = await import(moduleName);
+		const client = new sns.SNSClient({ region: this.config.region });
+		const isFifo = topic.endsWith(".fifo");
+		const params: Record<string, unknown> = {
+			TopicArn: topic,
+			Message: typeof payload === "string" ? payload : JSON.stringify(payload),
+		};
+		if (isFifo) {
+			params.MessageGroupId = opts?.partitionKey ?? opts?.orderingKey ?? "default";
+			params.MessageDeduplicationId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+		}
+		try {
+			await client.send(new sns.PublishCommand(params));
+		} finally {
+			client.destroy?.();
+		}
+	}
+
 	/**
 	 * Health check - verify AWS connectivity
 	 */
@@ -247,7 +311,7 @@ export class AWSSNSAdapter implements PubSubAdapter {
 		try {
 			const { ListQueuesCommand } = await import("@aws-sdk/client-sqs");
 			const command = new ListQueuesCommand({ MaxResults: 1 });
-			await this.sqsClient.send(command);
+			await this.requireSqsClient().send(command);
 			return true;
 		} catch {
 			return false;

package/src/adapters/AzureServiceBusAdapter.ts

@@ -9,6 +9,12 @@
  * - AZURE_SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE: Fully qualified namespace (if using DefaultAzureCredential)
  */
 
+import type {
+	ProcessErrorArgs,
+	ServiceBusClient,
+	ServiceBusReceivedMessage,
+	ServiceBusReceiver,
+} from "@azure/service-bus";
 import type { PubSubTriggerOpts } from "@blokjs/helper";
 import { v4 as uuid } from "uuid";
 import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
@@ -27,11 +33,22 @@ export interface AzureServiceBusConfig {
 export class AzureServiceBusAdapter implements PubSubAdapter {
 	readonly provider = "azure" as const;
 
-	private client: any;
-	private receivers: Map<string, any> = new Map();
+	private client: ServiceBusClient | undefined;
+	private receivers: Map<string, ServiceBusReceiver> = new Map();
 	private connected = false;
 	private config: AzureServiceBusConfig;
 
+	/**
+	 * Type-narrowing accessor for `this.client`. Field is undefined until
+	 * `connect()` runs.
+	 */
+	private requireClient(): ServiceBusClient {
+		if (!this.client) {
+			throw new Error("[AzureServiceBusAdapter] client is not initialised — call connect() first");
+		}
+		return this.client;
+	}
+
 	constructor(config?: AzureServiceBusConfig) {
 		this.config = {
 			connectionString: config?.connectionString || process.env.AZURE_SERVICE_BUS_CONNECTION_STRING,
@@ -63,8 +80,7 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 			console.log("[AzureServiceBusAdapter] Connected to Azure Service Bus");
 		} catch (error) {
 			throw new Error(
-				`Failed to connect to Azure Service Bus: ${(error as Error).message}. ` +
-					`Make sure @azure/service-bus is installed: npm install @azure/service-bus`,
+				`Failed to connect to Azure Service Bus: ${(error as Error).message}. Make sure @azure/service-bus is installed: npm install @azure/service-bus`,
 			);
 		}
 	}
@@ -82,7 +98,7 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 			}
 			this.receivers.clear();
 
-			await this.client.close();
+			await this.requireClient().close();
 			this.connected = false;
 			console.log("[AzureServiceBusAdapter] Disconnected from Azure Service Bus");
 		} catch (error) {
@@ -98,17 +114,18 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 			throw new Error("Not connected to Azure Service Bus. Call connect() first.");
 		}
 
-		let receiver: any;
+		const client = this.requireClient();
+		let receiver: ServiceBusReceiver;
 
 		// Determine if this is a topic subscription or a queue
 		if (config.subscription && config.topic) {
 			// Topic with subscription
-			receiver = this.client.createReceiver(config.topic, config.subscription, {
+			receiver = client.createReceiver(config.topic, config.subscription, {
 				receiveMode: config.ack !== false ? "peekLock" : "receiveAndDelete",
 			});
 		} else {
 			// Queue
-			receiver = this.client.createReceiver(config.subscription || config.topic, {
+			receiver = client.createReceiver(config.subscription || config.topic, {
 				receiveMode: config.ack !== false ? "peekLock" : "receiveAndDelete",
 			});
 		}
@@ -116,7 +133,7 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 		const subscriptionKey = `${config.topic}/${config.subscription}`;
 
 		// Message handler
-		const processMessage = async (sbMessage: any) => {
+		const processMessage = async (sbMessage: ServiceBusReceivedMessage) => {
 			// Parse message body
 			let body: unknown;
 			try {
@@ -139,7 +156,8 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 
 			// Create pub/sub message
 			const pubsubMessage: PubSubMessage = {
-				id: sbMessage.messageId || uuid(),
+				// `messageId` may be string | number | Buffer per Azure SDK; coerce to string.
+				id: sbMessage.messageId !== undefined ? String(sbMessage.messageId) : uuid(),
 				body,
 				attributes,
 				raw: sbMessage,
@@ -162,9 +180,10 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 			}
 		};
 
-		// Error handler
-		const processError = async (error: Error) => {
-			console.error(`[AzureServiceBusAdapter] Error: ${error.message}`);
+		// Error handler — Azure SDK passes a `ProcessErrorArgs` with the
+		// underlying error inside `args.error` plus contextual fields.
+		const processError = async (args: ProcessErrorArgs) => {
+			console.error(`[AzureServiceBusAdapter] Error: ${args.error.message}`);
 		};
 
 		// Subscribe to messages
@@ -197,6 +216,30 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 		return this.connected;
 	}
 
+	/**
+	 * v0.7 PR 6 — publish to an Azure Service Bus topic.
+	 *
+	 * `partitionKey` maps to Service Bus's `partitionKey`; `orderingKey`
+	 * maps to `sessionId` (for session-enabled topics).
+	 */
+	async publish(
+		topic: string,
+		payload: unknown,
+		opts?: { partitionKey?: string; orderingKey?: string },
+	): Promise<void> {
+		if (!this.connected) throw new Error("[blok][pubsub-azure] not connected. Call connect() first.");
+		const sender = this.requireClient().createSender(topic);
+		try {
+			await sender.sendMessages({
+				body: payload,
+				partitionKey: opts?.partitionKey,
+				sessionId: opts?.orderingKey,
+			});
+		} finally {
+			await sender.close();
+		}
+	}
+
 	/**
 	 * Health check - verify Azure Service Bus connectivity
 	 */
@@ -205,7 +248,7 @@ export class AzureServiceBusAdapter implements PubSubAdapter {
 
 		try {
 			// Create a temporary receiver to test connectivity
-			const testReceiver = this.client.createReceiver("$default", {
+			const testReceiver = this.requireClient().createReceiver("$default", {
 				receiveMode: "peekLock",
 			});
 			await testReceiver.close();

package/src/adapters/GCPPubSubAdapter.ts

@@ -11,6 +11,7 @@
  */
 
 import type { PubSubTriggerOpts } from "@blokjs/helper";
+import type { Message, PubSub, Subscription } from "@google-cloud/pubsub";
 import { v4 as uuid } from "uuid";
 import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
 
@@ -31,11 +32,22 @@ export interface GCPPubSubConfig {
 export class GCPPubSubAdapter implements PubSubAdapter {
 	readonly provider = "gcp" as const;
 
-	private client: any;
-	private subscriptions: Map<string, any> = new Map();
+	private client: PubSub | undefined;
+	private subscriptions: Map<string, Subscription> = new Map();
 	private connected = false;
 	private config: GCPPubSubConfig;
 
+	/**
+	 * Type-narrowing accessor for `this.client`. Field is undefined until
+	 * `connect()` runs.
+	 */
+	private requireClient(): PubSub {
+		if (!this.client) {
+			throw new Error("[GCPPubSubAdapter] client is not initialised — call connect() first");
+		}
+		return this.client;
+	}
+
 	constructor(config?: GCPPubSubConfig) {
 		this.config = {
 			projectId: config?.projectId || process.env.GOOGLE_CLOUD_PROJECT,
@@ -62,8 +74,7 @@ export class GCPPubSubAdapter implements PubSubAdapter {
 			console.log(`[GCPPubSubAdapter] Connected to GCP Pub/Sub: ${this.config.projectId}`);
 		} catch (error) {
 			throw new Error(
-				`Failed to connect to GCP Pub/Sub: ${(error as Error).message}. ` +
-					`Make sure @google-cloud/pubsub is installed: npm install @google-cloud/pubsub`,
+				`Failed to connect to GCP Pub/Sub: ${(error as Error).message}. Make sure @google-cloud/pubsub is installed: npm install @google-cloud/pubsub`,
 			);
 		}
 	}
@@ -81,7 +92,7 @@ export class GCPPubSubAdapter implements PubSubAdapter {
 			}
 			this.subscriptions.clear();
 
-			await this.client.close();
+			await this.requireClient().close();
 			this.connected = false;
 			console.log("[GCPPubSubAdapter] Disconnected from GCP Pub/Sub");
 		} catch (error) {
@@ -97,18 +108,26 @@ export class GCPPubSubAdapter implements PubSubAdapter {
 			throw new Error("Not connected to GCP Pub/Sub. Call connect() first.");
 		}
 
+		if (!config.subscription) {
+			throw new Error("[GCPPubSubAdapter] `subscription` is required — must be the GCP subscription name.");
+		}
 		const subscriptionName = config.subscription;
 
-		// Get the subscription
-		const subscription = this.client.subscription(subscriptionName, {
+		// Get the subscription. The GCP SDK calls the per-subscription
+		// deadline `maxAckDeadline` (a `Duration`); our author-facing
+		// field is `ackDeadline` (seconds) for parity with other
+		// providers. `Duration` is the GCP SDK's tc39-Temporal-shaped
+		// shim — construct via `Duration.from({seconds})`.
+		const { Duration } = await import("@google-cloud/pubsub");
+		const subscription = this.requireClient().subscription(subscriptionName, {
 			flowControl: {
 				maxMessages: config.maxMessages || 10,
 			},
-			ackDeadline: config.ackDeadline || 30,
+			maxAckDeadline: Duration.from({ seconds: config.ackDeadline || 30 }),
 		});
 
 		// Message handler
-		const messageHandler = async (gcpMessage: any) => {
+		const messageHandler = async (gcpMessage: Message) => {
 			// Parse message data
 			let body: unknown;
 			try {
@@ -177,6 +196,27 @@ export class GCPPubSubAdapter implements PubSubAdapter {
 		return this.connected;
 	}
 
+	/**
+	 * v0.7 PR 6 — publish to a GCP Pub/Sub topic.
+	 *
+	 * `partitionKey` / `orderingKey` map to GCP's `orderingKey` (the
+	 * topic must have message ordering enabled — otherwise the field
+	 * is ignored by the broker).
+	 */
+	async publish(
+		topic: string,
+		payload: unknown,
+		opts?: { partitionKey?: string; orderingKey?: string },
+	): Promise<void> {
+		if (!this.connected) throw new Error("[blok][pubsub-gcp] not connected. Call connect() first.");
+		const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+		const t = this.requireClient().topic(topic);
+		await t.publishMessage({
+			data: Buffer.from(body),
+			orderingKey: opts?.orderingKey ?? opts?.partitionKey,
+		});
+	}
+
 	/**
 	 * Health check - verify GCP Pub/Sub connectivity
 	 */
@@ -185,7 +225,7 @@ export class GCPPubSubAdapter implements PubSubAdapter {
 
 		try {
 			// List subscriptions as a health check
-			const [subscriptions] = await this.client.getSubscriptions({ pageSize: 1 });
+			const [subscriptions] = await this.requireClient().getSubscriptions({ pageSize: 1 });
 			return true;
 		} catch {
 			return false;

package/src/adapters/KafkaPubSubAdapter.ts

@@ -0,0 +1,194 @@
+/**
+ * KafkaPubSubAdapter — v0.7 PR 6 — Pub/Sub adapter backed by Apache
+ * Kafka via `kafkajs`.
+ *
+ * Pub/Sub vs Worker semantics: this adapter uses **per-subscriber
+ * consumer groups** so multiple subscribers each receive every message
+ * (fan-out). When `consumerGroup` is explicitly set, all subscribers
+ * share that group and compete (1 of N gets each message).
+ *
+ * Replay cursors via `startFrom`:
+ *   - `"earliest"` → `fromBeginning: true` on first subscribe.
+ *   - `"latest"` (default) → only new messages.
+ *   - `{seq: N}` / `{timestamp: ms}` — provider-specific. Cleanest
+ *     long-term path is Kafka's `admin.seek({offset|timestamp})` post-
+ *     subscribe; v1 honors `earliest` / `latest` and `{seq}` via
+ *     `auto.offset.reset` only.
+ *
+ * Requires `kafkajs` as a peer dependency.
+ *
+ * Environment variables:
+ *   - `KAFKA_BROKERS`           — comma-separated (default `localhost:9092`).
+ *   - `KAFKA_CLIENT_ID`         — default `"blok-pubsub"`.
+ *   - `KAFKA_SASL_USERNAME` / `KAFKA_SASL_PASSWORD`  — SASL/PLAIN.
+ *   - `KAFKA_SSL`               — `"true"` enables TLS.
+ */
+
+import type { PubSubTriggerOpts } from "@blokjs/helper";
+import { v4 as uuid } from "uuid";
+import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
+
+export interface KafkaPubSubConfig {
+	brokers: string[];
+	clientId: string;
+	saslUsername?: string;
+	saslPassword?: string;
+	ssl: boolean;
+}
+
+interface KafkaConsumerHandle {
+	disconnect: () => Promise<void>;
+	stop: () => Promise<void>;
+}
+
+export class KafkaPubSubAdapter implements PubSubAdapter {
+	readonly provider = "kafka" as const;
+	private readonly config: KafkaPubSubConfig;
+	// biome-ignore lint/suspicious/noExplicitAny: kafkajs's exported `Kafka` constructor is loosely typed.
+	private kafka: any = null;
+	// biome-ignore lint/suspicious/noExplicitAny: producer is created lazily and typed loosely.
+	private producer: any = null;
+	private consumers: Map<string, KafkaConsumerHandle> = new Map();
+	private connected = false;
+
+	constructor(config?: Partial<KafkaPubSubConfig>) {
+		this.config = {
+			brokers: config?.brokers ?? (process.env.KAFKA_BROKERS ?? "localhost:9092").split(",").map((s) => s.trim()),
+			clientId: config?.clientId ?? process.env.KAFKA_CLIENT_ID ?? "blok-pubsub",
+			saslUsername: config?.saslUsername ?? process.env.KAFKA_SASL_USERNAME,
+			saslPassword: config?.saslPassword ?? process.env.KAFKA_SASL_PASSWORD,
+			ssl: config?.ssl ?? process.env.KAFKA_SSL === "true",
+		};
+	}
+
+	async connect(): Promise<void> {
+		if (this.connected) return;
+		try {
+			// biome-ignore lint/suspicious/noExplicitAny: kafkajs is a runtime peer dep.
+			const kafkajs: any = await import("kafkajs");
+			const sasl =
+				this.config.saslUsername && this.config.saslPassword
+					? { mechanism: "plain", username: this.config.saslUsername, password: this.config.saslPassword }
+					: undefined;
+			this.kafka = new kafkajs.Kafka({
+				clientId: this.config.clientId,
+				brokers: this.config.brokers,
+				ssl: this.config.ssl,
+				sasl,
+			});
+			this.producer = this.kafka.producer();
+			await this.producer.connect();
+			this.connected = true;
+		} catch (err) {
+			throw new Error(
+				`[blok][pubsub-kafka] connect failed: ${(err as Error).message}. Install kafkajs as a peer dependency: bun add kafkajs`,
+			);
+		}
+	}
+
+	async disconnect(): Promise<void> {
+		if (!this.connected) return;
+		for (const consumer of this.consumers.values()) {
+			try {
+				await consumer.disconnect();
+			} catch {
+				/* ignore */
+			}
+		}
+		this.consumers.clear();
+		try {
+			await this.producer?.disconnect();
+		} catch {
+			/* ignore */
+		}
+		this.producer = null;
+		this.connected = false;
+	}
+
+	async subscribe(config: PubSubTriggerOpts, handler: (message: PubSubMessage) => Promise<void>): Promise<void> {
+		if (!this.connected) throw new Error("[blok][pubsub-kafka] not connected. Call connect() first.");
+		// Fan-out: distinct group id per subscriber instance. Competing-
+		// consumer: explicit consumerGroup shared across all subscribers.
+		const groupId =
+			config.consumerGroup ?? `blok-fanout-${uuid().slice(0, 8)}-${config.topic.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+		const consumer = this.kafka.consumer({ groupId });
+		await consumer.connect();
+		const fromBeginning = config.startFrom === "earliest";
+		await consumer.subscribe({ topic: config.topic, fromBeginning });
+		this.consumers.set(`${config.topic}#${groupId}`, consumer);
+
+		await consumer.run({
+			autoCommit: config.ack !== false,
+			eachMessage: async ({
+				message,
+			}: {
+				message: { key?: Buffer; value?: Buffer; offset: string; timestamp: string; headers?: Record<string, Buffer> };
+			}) => {
+				const text = message.value?.toString("utf8") ?? "";
+				let body: unknown = text;
+				try {
+					body = text.length > 0 ? JSON.parse(text) : null;
+				} catch {
+					/* leave as text */
+				}
+				const attributes: Record<string, string> = {};
+				if (message.headers) {
+					for (const [k, v] of Object.entries(message.headers)) attributes[k] = v?.toString("utf8") ?? "";
+				}
+				const msg: PubSubMessage = {
+					id: `${config.topic}:${message.offset}`,
+					body,
+					attributes,
+					raw: message,
+					topic: config.topic,
+					subscription: groupId,
+					publishTime: new Date(Number.parseInt(message.timestamp, 10)),
+					ack: async () => {
+						/* autoCommit handles ack */
+					},
+					nack: async () => {
+						/* kafkajs has no per-message nack; the offset commit is suppressed by throwing */
+					},
+				};
+				// On handler failure: re-throw so kafkajs suppresses the
+				// offset commit; the consumer will re-poll the message
+				// on the next cycle. The throw is intentional.
+				await handler(msg);
+			},
+		});
+	}
+
+	async unsubscribe(subscription: string): Promise<void> {
+		const consumer = this.consumers.get(subscription);
+		if (!consumer) return;
+		try {
+			await consumer.stop();
+			await consumer.disconnect();
+		} catch {
+			/* ignore */
+		}
+		this.consumers.delete(subscription);
+	}
+
+	async publish(
+		topic: string,
+		payload: unknown,
+		opts?: { partitionKey?: string; orderingKey?: string },
+	): Promise<void> {
+		if (!this.connected || !this.producer) throw new Error("[blok][pubsub-kafka] not connected. Call connect() first.");
+		const body = typeof payload === "string" ? payload : JSON.stringify(payload);
+		const key = opts?.partitionKey ?? opts?.orderingKey;
+		await this.producer.send({
+			topic,
+			messages: [{ key, value: body }],
+		});
+	}
+
+	isConnected(): boolean {
+		return this.connected;
+	}
+
+	async healthCheck(): Promise<boolean> {
+		return this.connected;
+	}
+}