@blokjs/trigger-pubsub 0.2.0

package/src/adapters/AzureServiceBusAdapter.ts

@@ -0,0 +1,220 @@
+/**
+ * AzureServiceBusAdapter - Azure Service Bus adapter for PubSubTrigger
+ *
+ * Uses @azure/service-bus for Azure Service Bus connectivity.
+ * Requires: npm install @azure/service-bus
+ *
+ * Environment variables:
+ * - AZURE_SERVICE_BUS_CONNECTION_STRING: Azure Service Bus connection string
+ * - AZURE_SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE: Fully qualified namespace (if using DefaultAzureCredential)
+ */
+
+import type { PubSubTriggerOpts } from "@blokjs/helper";
+import { v4 as uuid } from "uuid";
+import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
+
+/**
+ * Azure Service Bus configuration
+ */
+export interface AzureServiceBusConfig {
+	connectionString?: string;
+	fullyQualifiedNamespace?: string;
+}
+
+/**
+ * AzureServiceBusAdapter - Azure Service Bus implementation
+ */
+export class AzureServiceBusAdapter implements PubSubAdapter {
+	readonly provider = "azure" as const;
+
+	private client: any;
+	private receivers: Map<string, any> = new Map();
+	private connected = false;
+	private config: AzureServiceBusConfig;
+
+	constructor(config?: AzureServiceBusConfig) {
+		this.config = {
+			connectionString: config?.connectionString || process.env.AZURE_SERVICE_BUS_CONNECTION_STRING,
+			fullyQualifiedNamespace:
+				config?.fullyQualifiedNamespace || process.env.AZURE_SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE,
+		};
+	}
+
+	/**
+	 * Connect to Azure Service Bus
+	 */
+	async connect(): Promise<void> {
+		if (this.connected) return;
+
+		try {
+			// Dynamic import of @azure/service-bus
+			const { ServiceBusClient } = await import("@azure/service-bus");
+
+			if (this.config.connectionString) {
+				this.client = new ServiceBusClient(this.config.connectionString);
+			} else if (this.config.fullyQualifiedNamespace) {
+				// Would need @azure/identity for DefaultAzureCredential
+				throw new Error("Managed identity authentication requires @azure/identity package");
+			} else {
+				throw new Error("Either connectionString or fullyQualifiedNamespace is required");
+			}
+
+			this.connected = true;
+			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`,
+			);
+		}
+	}
+
+	/**
+	 * Disconnect from Azure Service Bus
+	 */
+	async disconnect(): Promise<void> {
+		if (!this.connected) return;
+
+		try {
+			// Close all receivers
+			for (const [name, receiver] of this.receivers) {
+				await receiver.close();
+			}
+			this.receivers.clear();
+
+			await this.client.close();
+			this.connected = false;
+			console.log("[AzureServiceBusAdapter] Disconnected from Azure Service Bus");
+		} catch (error) {
+			console.error(`[AzureServiceBusAdapter] Error disconnecting: ${(error as Error).message}`);
+		}
+	}
+
+	/**
+	 * Subscribe to an Azure Service Bus topic/subscription or queue
+	 */
+	async subscribe(config: PubSubTriggerOpts, handler: (message: PubSubMessage) => Promise<void>): Promise<void> {
+		if (!this.connected) {
+			throw new Error("Not connected to Azure Service Bus. Call connect() first.");
+		}
+
+		let receiver: any;
+
+		// 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, {
+				receiveMode: config.ack !== false ? "peekLock" : "receiveAndDelete",
+			});
+		} else {
+			// Queue
+			receiver = this.client.createReceiver(config.subscription || config.topic, {
+				receiveMode: config.ack !== false ? "peekLock" : "receiveAndDelete",
+			});
+		}
+
+		const subscriptionKey = `${config.topic}/${config.subscription}`;
+
+		// Message handler
+		const processMessage = async (sbMessage: any) => {
+			// Parse message body
+			let body: unknown;
+			try {
+				if (typeof sbMessage.body === "string") {
+					body = JSON.parse(sbMessage.body);
+				} else {
+					body = sbMessage.body;
+				}
+			} catch {
+				body = sbMessage.body;
+			}
+
+			// Extract application properties as attributes
+			const attributes: Record<string, string> = {};
+			if (sbMessage.applicationProperties) {
+				for (const [key, value] of Object.entries(sbMessage.applicationProperties)) {
+					attributes[key] = String(value);
+				}
+			}
+
+			// Create pub/sub message
+			const pubsubMessage: PubSubMessage = {
+				id: sbMessage.messageId || uuid(),
+				body,
+				attributes,
+				raw: sbMessage,
+				topic: config.topic,
+				subscription: config.subscription,
+				publishTime: sbMessage.enqueuedTimeUtc ? new Date(sbMessage.enqueuedTimeUtc) : new Date(),
+				ack: async () => {
+					await receiver.completeMessage(sbMessage);
+				},
+				nack: async () => {
+					await receiver.abandonMessage(sbMessage);
+				},
+			};
+
+			// Process message
+			try {
+				await handler(pubsubMessage);
+			} catch (error) {
+				console.error(`[AzureServiceBusAdapter] Error processing message: ${(error as Error).message}`);
+			}
+		};
+
+		// Error handler
+		const processError = async (error: Error) => {
+			console.error(`[AzureServiceBusAdapter] Error: ${error.message}`);
+		};
+
+		// Subscribe to messages
+		receiver.subscribe({
+			processMessage,
+			processError,
+		});
+
+		this.receivers.set(subscriptionKey, receiver);
+
+		console.log(`[AzureServiceBusAdapter] Subscribed to: ${subscriptionKey}`);
+	}
+
+	/**
+	 * Unsubscribe from Azure Service Bus
+	 */
+	async unsubscribe(subscriptionKey: string): Promise<void> {
+		const receiver = this.receivers.get(subscriptionKey);
+		if (receiver) {
+			await receiver.close();
+			this.receivers.delete(subscriptionKey);
+			console.log(`[AzureServiceBusAdapter] Unsubscribed from: ${subscriptionKey}`);
+		}
+	}
+
+	/**
+	 * Check if connected to Azure Service Bus
+	 */
+	isConnected(): boolean {
+		return this.connected;
+	}
+
+	/**
+	 * Health check - verify Azure Service Bus connectivity
+	 */
+	async healthCheck(): Promise<boolean> {
+		if (!this.connected) return false;
+
+		try {
+			// Create a temporary receiver to test connectivity
+			const testReceiver = this.client.createReceiver("$default", {
+				receiveMode: "peekLock",
+			});
+			await testReceiver.close();
+			return true;
+		} catch {
+			// Queue might not exist but connection is healthy if we got here
+			return this.connected;
+		}
+	}
+}
+
+export default AzureServiceBusAdapter;

package/src/adapters/GCPPubSubAdapter.ts

@@ -0,0 +1,196 @@
+/**
+ * GCPPubSubAdapter - Google Cloud Pub/Sub adapter for PubSubTrigger
+ *
+ * Uses @google-cloud/pubsub for GCP Pub/Sub connectivity.
+ * Requires: npm install @google-cloud/pubsub
+ *
+ * Environment variables:
+ * - GOOGLE_CLOUD_PROJECT: GCP project ID
+ * - GOOGLE_APPLICATION_CREDENTIALS: Path to service account key file (optional if using default credentials)
+ * - PUBSUB_EMULATOR_HOST: Pub/Sub emulator host for local development (optional)
+ */
+
+import type { PubSubTriggerOpts } from "@blokjs/helper";
+import { v4 as uuid } from "uuid";
+import type { PubSubAdapter, PubSubMessage } from "../PubSubTrigger";
+
+/**
+ * GCP Pub/Sub configuration
+ */
+export interface GCPPubSubConfig {
+	projectId?: string;
+	credentials?: {
+		client_email: string;
+		private_key: string;
+	};
+}
+
+/**
+ * GCPPubSubAdapter - Google Cloud Pub/Sub implementation
+ */
+export class GCPPubSubAdapter implements PubSubAdapter {
+	readonly provider = "gcp" as const;
+
+	private client: any;
+	private subscriptions: Map<string, any> = new Map();
+	private connected = false;
+	private config: GCPPubSubConfig;
+
+	constructor(config?: GCPPubSubConfig) {
+		this.config = {
+			projectId: config?.projectId || process.env.GOOGLE_CLOUD_PROJECT,
+			credentials: config?.credentials,
+		};
+	}
+
+	/**
+	 * Connect to GCP Pub/Sub
+	 */
+	async connect(): Promise<void> {
+		if (this.connected) return;
+
+		try {
+			// Dynamic import of @google-cloud/pubsub
+			const { PubSub } = await import("@google-cloud/pubsub");
+
+			this.client = new PubSub({
+				projectId: this.config.projectId,
+				credentials: this.config.credentials,
+			});
+
+			this.connected = true;
+			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`,
+			);
+		}
+	}
+
+	/**
+	 * Disconnect from GCP Pub/Sub
+	 */
+	async disconnect(): Promise<void> {
+		if (!this.connected) return;
+
+		try {
+			// Close all subscriptions
+			for (const [name, subscription] of this.subscriptions) {
+				await subscription.close();
+			}
+			this.subscriptions.clear();
+
+			await this.client.close();
+			this.connected = false;
+			console.log("[GCPPubSubAdapter] Disconnected from GCP Pub/Sub");
+		} catch (error) {
+			console.error(`[GCPPubSubAdapter] Error disconnecting: ${(error as Error).message}`);
+		}
+	}
+
+	/**
+	 * Subscribe to a GCP Pub/Sub topic
+	 */
+	async subscribe(config: PubSubTriggerOpts, handler: (message: PubSubMessage) => Promise<void>): Promise<void> {
+		if (!this.connected) {
+			throw new Error("Not connected to GCP Pub/Sub. Call connect() first.");
+		}
+
+		const subscriptionName = config.subscription;
+
+		// Get the subscription
+		const subscription = this.client.subscription(subscriptionName, {
+			flowControl: {
+				maxMessages: config.maxMessages || 10,
+			},
+			ackDeadline: config.ackDeadline || 30,
+		});
+
+		// Message handler
+		const messageHandler = async (gcpMessage: any) => {
+			// Parse message data
+			let body: unknown;
+			try {
+				const data = gcpMessage.data.toString();
+				body = JSON.parse(data);
+			} catch {
+				body = gcpMessage.data.toString();
+			}
+
+			// Create pub/sub message
+			const pubsubMessage: PubSubMessage = {
+				id: gcpMessage.id || uuid(),
+				body,
+				attributes: gcpMessage.attributes || {},
+				raw: gcpMessage,
+				topic: config.topic,
+				subscription: subscriptionName,
+				publishTime: gcpMessage.publishTime ? new Date(gcpMessage.publishTime) : new Date(),
+				ack: async () => {
+					gcpMessage.ack();
+				},
+				nack: async () => {
+					gcpMessage.nack();
+				},
+			};
+
+			// Process message
+			try {
+				await handler(pubsubMessage);
+			} catch (error) {
+				console.error(`[GCPPubSubAdapter] Error processing message: ${(error as Error).message}`);
+			}
+		};
+
+		// Error handler
+		const errorHandler = (error: Error) => {
+			console.error(`[GCPPubSubAdapter] Subscription error: ${error.message}`);
+		};
+
+		// Attach listeners
+		subscription.on("message", messageHandler);
+		subscription.on("error", errorHandler);
+
+		// Store subscription reference
+		this.subscriptions.set(subscriptionName, subscription);
+
+		console.log(`[GCPPubSubAdapter] Subscribed to: ${subscriptionName}`);
+	}
+
+	/**
+	 * Unsubscribe from a GCP Pub/Sub subscription
+	 */
+	async unsubscribe(subscriptionName: string): Promise<void> {
+		const subscription = this.subscriptions.get(subscriptionName);
+		if (subscription) {
+			await subscription.close();
+			this.subscriptions.delete(subscriptionName);
+			console.log(`[GCPPubSubAdapter] Unsubscribed from: ${subscriptionName}`);
+		}
+	}
+
+	/**
+	 * Check if connected to GCP Pub/Sub
+	 */
+	isConnected(): boolean {
+		return this.connected;
+	}
+
+	/**
+	 * Health check - verify GCP Pub/Sub connectivity
+	 */
+	async healthCheck(): Promise<boolean> {
+		if (!this.connected) return false;
+
+		try {
+			// List subscriptions as a health check
+			const [subscriptions] = await this.client.getSubscriptions({ pageSize: 1 });
+			return true;
+		} catch {
+			return false;
+		}
+	}
+}
+
+export default GCPPubSubAdapter;

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @blokjs/trigger-pubsub
+ *
+ * Pub/Sub-based trigger for Blok workflows.
+ * Supports multiple pub/sub providers:
+ * - Google Cloud Pub/Sub
+ * - AWS SNS/SQS
+ * - Azure Service Bus
+ *
+ * @example GCP Pub/Sub
+ * ```typescript
+ * import { PubSubTrigger, GCPPubSubAdapter } from "@blokjs/trigger-pubsub";
+ *
+ * class MyPubSubTrigger extends PubSubTrigger {
+ *   protected adapter = new GCPPubSubAdapter({
+ *     projectId: "my-project",
+ *   });
+ *
+ *   protected nodes = myNodes;
+ *   protected workflows = myWorkflows;
+ * }
+ *
+ * const trigger = new MyPubSubTrigger();
+ * await trigger.listen();
+ * ```
+ *
+ * @example AWS SNS/SQS
+ * ```typescript
+ * import { PubSubTrigger, AWSSNSAdapter } from "@blokjs/trigger-pubsub";
+ *
+ * class MyPubSubTrigger extends PubSubTrigger {
+ *   protected adapter = new AWSSNSAdapter({
+ *     region: "us-east-1",
+ *   });
+ *   // ...
+ * }
+ * ```
+ *
+ * @example Azure Service Bus
+ * ```typescript
+ * import { PubSubTrigger, AzureServiceBusAdapter } from "@blokjs/trigger-pubsub";
+ *
+ * class MyPubSubTrigger extends PubSubTrigger {
+ *   protected adapter = new AzureServiceBusAdapter({
+ *     connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING,
+ *   });
+ *   // ...
+ * }
+ * ```
+ */
+
+// Core exports
+export {
+	PubSubTrigger,
+	type PubSubAdapter,
+	type PubSubMessage,
+} from "./PubSubTrigger";
+
+// Adapters
+export { GCPPubSubAdapter, type GCPPubSubConfig } from "./adapters/GCPPubSubAdapter";
+export { AWSSNSAdapter, type AWSSNSConfig } from "./adapters/AWSSNSAdapter";
+export { AzureServiceBusAdapter, type AzureServiceBusConfig } from "./adapters/AzureServiceBusAdapter";
+
+// Re-export types from helper for convenience
+export type {
+	PubSubProvider,
+	PubSubTriggerOpts,
+} from "@blokjs/helper";

package/template/.env.example

@@ -0,0 +1,8 @@
+PROJECT_NAME=trigger-pubsub-server
+PROJECT_VERSION=0.0.1
+PORT=4006
+WORKFLOWS_PATH=PROJECT_PATH/workflows
+NODES_PATH=PROJECT_PATH/src/nodes
+CONSOLE_LOG_ACTIVE=true
+APP_NAME=blok-pubsub
+DISABLE_TRIGGER_RUN=false # Set to true to disable trigger run and use this project as a module

package/template/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "blok-pubsub-trigger",
+	"version": "0.1.0",
+	"description": "Pub/Sub trigger for Blok workflows",
+	"type": "module",
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"author": "",
+	"license": "MIT",
+	"scripts": {
+		"dev": "bun --watch run src/index.ts",
+		"start": "bun run dist/index.js",
+		"build": "rimraf ./dist && tsc",
+		"test": "vitest run",
+		"test:dev": "vitest"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.21",
+		"@types/uuid": "^11.0.0",
+		"rimraf": "^6.1.2",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"dependencies": {
+		"@blokjs/api-call": "workspace:*",
+		"@blokjs/helper": "workspace:*",
+		"@blokjs/if-else": "workspace:*",
+		"@blokjs/runner": "workspace:*",
+		"@blokjs/shared": "workspace:*",
+		"@blokjs/trigger-pubsub": "workspace:*",
+		"@opentelemetry/api": "^1.9.0",
+		"@opentelemetry/exporter-prometheus": "^0.57.2",
+		"@opentelemetry/resources": "^1.30.1",
+		"@opentelemetry/sdk-metrics": "^1.30.1",
+		"@opentelemetry/sdk-trace-base": "^1.30.1",
+		"@opentelemetry/semantic-conventions": "^1.39.0",
+		"uuid": "^11.1.0",
+		"zod": "^3.24.2"
+	},
+	"private": true
+}

package/template/src/Nodes.ts

@@ -0,0 +1,10 @@
+import ApiCall from "@blokjs/api-call";
+import IfElse from "@blokjs/if-else";
+import type { BlokService } from "@blokjs/runner";
+
+const nodes: Record<string, BlokService<unknown>> = {
+	"@blokjs/api-call": ApiCall,
+	"@blokjs/if-else": IfElse,
+};
+
+export default nodes;

package/template/src/Workflows.ts

@@ -0,0 +1,8 @@
+import type Workflows from "./runner/types/Workflows";
+import onMessage from "./workflows/messages/on-message";
+
+const workflows: Workflows = {
+	"on-message": onMessage,
+};
+
+export default workflows;

package/template/src/index.ts

@@ -0,0 +1,41 @@
+import { DefaultLogger } from "@blokjs/runner";
+import { type Span, metrics, trace } from "@opentelemetry/api";
+import PubSubServer from "./runner/PubSubServer";
+
+export default class App {
+	private pubsubServer: PubSubServer = <PubSubServer>{};
+	protected trigger_initializer = 0;
+	protected initializer = 0;
+	protected tracer = trace.getTracer(
+		process.env.PROJECT_NAME || "trigger-pubsub-server",
+		process.env.PROJECT_VERSION || "0.0.1",
+	);
+	private logger = new DefaultLogger();
+	protected app_cold_start = metrics.getMeter("default").createGauge("initialization", {
+		description: "Application cold start",
+	});
+
+	constructor() {
+		this.initializer = performance.now();
+		this.pubsubServer = new PubSubServer();
+	}
+
+	async run() {
+		this.tracer.startActiveSpan("initialization", async (span: Span) => {
+			await this.pubsubServer.listen();
+			this.initializer = performance.now() - this.initializer;
+
+			this.logger.log(`Pub/Sub trigger initialized in ${this.initializer.toFixed(2)}ms`);
+			this.app_cold_start.record(this.initializer, {
+				pid: process.pid,
+				env: process.env.NODE_ENV,
+				app: process.env.APP_NAME,
+			});
+			span.end();
+		});
+	}
+}
+
+if (process.env.DISABLE_TRIGGER_RUN !== "true") {
+	new App().run();
+}

package/template/src/runner/PubSubServer.ts

@@ -0,0 +1,39 @@
+import { GCPPubSubAdapter, PubSubTrigger } from "@blokjs/trigger-pubsub";
+import nodes from "../Nodes";
+import workflows from "../Workflows";
+
+/**
+ * PubSubServer - Concrete Pub/Sub trigger implementation
+ *
+ * This server extends the abstract PubSubTrigger and provides:
+ * - A specific adapter (GCP Pub/Sub by default, can be changed to AWS or Azure)
+ * - Node and workflow registries
+ *
+ * To change the provider, replace:
+ * - GCPPubSubAdapter with AWSSNSAdapter or AzureServiceBusAdapter
+ * - Update the adapter configuration accordingly
+ *
+ * @example AWS SNS/SQS
+ * ```typescript
+ * import { AWSSNSAdapter } from "@blokjs/trigger-pubsub";
+ * protected adapter = new AWSSNSAdapter({
+ *   region: process.env.AWS_REGION || "us-east-1",
+ * });
+ * ```
+ *
+ * @example Azure Service Bus
+ * ```typescript
+ * import { AzureServiceBusAdapter } from "@blokjs/trigger-pubsub";
+ * protected adapter = new AzureServiceBusAdapter({
+ *   connectionString: process.env.AZURE_SERVICE_BUS_CONNECTION_STRING || "",
+ * });
+ * ```
+ */
+export default class PubSubServer extends PubSubTrigger {
+	protected adapter = new GCPPubSubAdapter({
+		projectId: process.env.GCP_PROJECT_ID || "my-project",
+	});
+
+	protected nodes = nodes;
+	protected workflows = workflows;
+}

package/template/src/runner/types/Workflows.ts

@@ -0,0 +1,7 @@
+import type { HelperResponse } from "@blokjs/helper";
+
+type Workflows = {
+	[key: string]: HelperResponse;
+};
+
+export default Workflows;

package/template/src/workflows/messages/on-message.ts

@@ -0,0 +1,44 @@
+import { type Step, Workflow } from "@blokjs/helper";
+
+/**
+ * Example Pub/Sub workflow - triggered when a message is received
+ *
+ * The message data is available in ctx.request:
+ * - ctx.request.body: The message payload
+ * - ctx.request.headers: Message attributes
+ * - ctx.request.params.topic: The topic name
+ * - ctx.request.params.subscription: The subscription name
+ * - ctx.request.params.messageId: Unique message ID
+ *
+ * Additional metadata is available in ctx.vars._pubsub_message:
+ * - topic: Topic name
+ * - subscription: Subscription name
+ * - publishTime: When the message was published (ISO string)
+ * - attributes: JSON string of message attributes
+ */
+const step: Step = Workflow({
+	name: "On Pub/Sub Message",
+	version: "1.0.0",
+	description: "Handles incoming Pub/Sub messages",
+})
+	.addTrigger("pubsub", {
+		provider: "gcp",
+		topic: "my-topic",
+		subscription: "my-subscription",
+	})
+	.addStep({
+		name: "log-message",
+		node: "@blokjs/api-call",
+		type: "module",
+		inputs: {
+			url: "https://httpbin.org/post",
+			method: "POST",
+			body: {
+				message: "js/ctx.request.body",
+				topic: "js/ctx.request.params.topic",
+				messageId: "js/ctx.request.params.messageId",
+			},
+		},
+	});
+
+export default step;