@axova/shared 1.0.0

package/src/events/kafka.ts

@@ -0,0 +1,429 @@
+import { createId } from "@paralleldrive/cuid2";
+import {
+	type Consumer,
+	type ConsumerConfig,
+	Kafka,
+	type KafkaConfig,
+	type KafkaMessage,
+	type Producer,
+	type ProducerConfig,
+} from "kafkajs";
+import {
+	type AxovaEvent,
+	KAFKA_TOPICS,
+	type KafkaTopic,
+} from "../types/events";
+
+// Kafka configuration interface
+export interface AxovaKafkaConfig {
+	brokers: string[];
+	clientId: string;
+	ssl?: boolean;
+	sasl?:
+		| {
+				mechanism: "plain";
+				username: string;
+				password: string;
+		  }
+		| {
+				mechanism: "scram-sha-256";
+				username: string;
+				password: string;
+		  }
+		| {
+				mechanism: "scram-sha-512";
+				username: string;
+				password: string;
+		  };
+}
+
+// Event handler type
+export type EventHandler<T = unknown> = (event: T) => Promise<void>;
+
+// Kafka client wrapper
+export class AxovaKafka {
+	private kafka: Kafka;
+	private producer: Producer | null = null;
+	private consumers: Map<string, Consumer> = new Map();
+	private eventHandlers: Map<string, EventHandler[]> = new Map();
+
+	constructor(config: AxovaKafkaConfig) {
+		const kafkaConfig: KafkaConfig = {
+			clientId: config.clientId,
+			brokers: config.brokers,
+		};
+
+		if (config.ssl) {
+			kafkaConfig.ssl = config.ssl;
+		}
+
+		if (config.sasl) {
+			kafkaConfig.sasl = config.sasl;
+		}
+
+		this.kafka = new Kafka(kafkaConfig);
+	}
+
+	// Initialize producer with optimized settings for high throughput and reliability
+	async initializeProducer(config?: ProducerConfig): Promise<void> {
+		if (this.producer) return;
+
+		const optimizedConfig: ProducerConfig = {
+			// Idempotency ensures exactly-once semantics
+			idempotent: true,
+			
+			// Allow up to 5 requests in flight for better throughput
+			// (safe with idempotent=true)
+			maxInFlightRequests: 5,
+			
+			// Batching configuration for better throughput
+			allowAutoTopicCreation: false,
+			transactionTimeout: 60000,
+			
+			// Retry configuration
+			retry: {
+				initialRetryTime: 100,
+				retries: 10,
+				maxRetryTime: 30000,
+				multiplier: 2,
+				factor: 0.2,
+			},
+			
+			// Override with user config if provided
+			...config,
+		};
+
+		this.producer = this.kafka.producer(optimizedConfig);
+		await this.producer.connect();
+		console.log("✅ Kafka producer connected with optimized settings");
+		console.log("   • Idempotent: enabled");
+		console.log("   • Max in-flight: 5");
+	}
+
+	// Initialize consumer with optimized settings for throughput and reliability
+	async initializeConsumer(
+		groupId: string,
+		topics: KafkaTopic[],
+		config?: ConsumerConfig,
+	): Promise<void> {
+		if (this.consumers.has(groupId)) return;
+
+		const optimizedConfig: ConsumerConfig = {
+			groupId,
+			
+			// Session timeout - how long broker waits before considering consumer dead
+			sessionTimeout: 30000,
+			
+			// Rebalance timeout - max time for rebalancing
+			rebalanceTimeout: 60000,
+			
+			// Heartbeat interval - how often to send heartbeats
+			heartbeatInterval: 3000,
+			
+			// Retry configuration
+			retry: {
+				initialRetryTime: 100,
+				retries: 10,
+				maxRetryTime: 30000,
+				multiplier: 2,
+				factor: 0.2,
+			},
+			
+			// Auto-commit configuration
+			// Note: For critical applications, consider manual commits
+			// autoCommit: false, 
+			// autoCommitInterval: 5000,
+			
+			// Performance tuning
+			maxBytesPerPartition: 1048576, // 1MB
+			maxWaitTimeInMs: 500, // Wait up to 500ms for batch
+			
+			// Override with user config if provided
+			...config,
+		};
+
+		const consumer = this.kafka.consumer(optimizedConfig);
+
+		await consumer.connect();
+		await consumer.subscribe({
+			topics: topics,
+			fromBeginning: false,
+		});
+
+		this.consumers.set(groupId, consumer);
+		console.log(`✅ Kafka consumer connected for group: ${groupId}`);
+		console.log(`   • Topics: ${topics.join(", ")}`);
+		console.log("   • Session timeout: 30s");
+		console.log("   • Max bytes per partition: 1MB");
+	}
+
+	// Publish event with optimized batching and error handling
+	async publishEvent(topic: KafkaTopic, event: AxovaEvent): Promise<void> {
+		if (!this.producer) {
+			throw new Error(
+				"Producer not initialized. Call initializeProducer() first.",
+			);
+		}
+
+		// Ensure all header values are strings (KafkaJS requirement)
+		const headers: Record<string, string> = {};
+		if (event.type) headers.eventType = String(event.type);
+		if (event.source) headers.source = String(event.source);
+		if (event.version) headers.version = String(event.version);
+		
+		const message = {
+			key: event.id || createId(), // Use event ID or generate a new one as string key
+			value: JSON.stringify(event),
+			timestamp: Date.now().toString(),
+			headers,
+		};
+
+		try {
+			const result = await this.producer.send({
+				topic,
+				messages: [message],
+				// Require acknowledgment from all in-sync replicas for durability
+				acks: -1, // Wait for all in-sync replicas
+				timeout: 30000,
+				compression: 1, // LZ4 compression
+			});
+
+			console.log(`✅ Event published successfully to ${topic}:`, event.type);
+			console.log(
+				`   • Partition: ${result[0].partition}, Offset: ${result[0].baseOffset}`,
+			);
+		} catch (error) {
+			console.error(`❌ Failed to publish event to ${topic}:`, error);
+			if (error instanceof Error) {
+				if (error.message.includes("UNKNOWN_TOPIC_OR_PARTITION")) {
+					console.error(
+						`   • Topic '${topic}' does not exist. Create it manually or enable auto-creation.`,
+					);
+				} else if (error.message.includes("NOT_LEADER_FOR_PARTITION")) {
+					console.error(
+						"   • Kafka cluster leadership issue. Check broker status.",
+					);
+				} else if (error.message.includes("NOT_ENOUGH_REPLICAS")) {
+					console.error(
+						"   • Not enough in-sync replicas available. Check broker health.",
+					);
+				} else if (error.message.includes("REQUEST_TIMED_OUT")) {
+					console.error(
+						"   • Request timed out. Check network and broker performance.",
+					);
+				}
+			}
+			throw error;
+		}
+	}
+	
+	// Batch publish events for higher throughput
+	async publishEventsBatch(topic: KafkaTopic, events: AxovaEvent[]): Promise<void> {
+		if (!this.producer) {
+			throw new Error(
+				"Producer not initialized. Call initializeProducer() first.",
+			);
+		}
+
+		if (events.length === 0) return;
+		
+		const messages = events.map((event) => {
+			const headers: Record<string, string> = {};
+			if (event.type) headers.eventType = String(event.type);
+			if (event.source) headers.source = String(event.source);
+			if (event.version) headers.version = String(event.version);
+			
+			return {
+				key: event.id || createId(),
+				value: JSON.stringify(event),
+				timestamp: Date.now().toString(),
+				headers,
+			};
+		});
+
+		try {
+			const result = await this.producer.send({
+				topic,
+				messages,
+				acks: -1,
+				timeout: 30000,
+				compression: 1,
+			});
+
+			console.log(`✅ Batch published ${events.length} events to ${topic}`);
+			console.log(`   • Partitions used: ${result.length}`);
+		} catch (error) {
+			console.error(`❌ Failed to batch publish events to ${topic}:`, error);
+			throw error;
+		}
+	}
+
+	// Subscribe to events
+	onEvent<T extends AxovaEvent>(
+		eventType: T["type"],
+		handler: EventHandler<T>,
+	): void {
+		const handlers = this.eventHandlers.get(eventType) || [];
+		handlers.push(handler as EventHandler);
+		this.eventHandlers.set(eventType, handlers);
+	}
+
+	// Start consuming events with optimized batch processing
+	async startConsuming(groupId: string): Promise<void> {
+		const consumer = this.consumers.get(groupId);
+		if (!consumer) {
+			throw new Error(`Consumer for group ${groupId} not initialized`);
+		}
+
+		await consumer.run({
+			// Process messages in batches for better throughput
+			// Can be configured per service based on requirements
+			partitionsConsumedConcurrently: 3, // Process 3 partitions concurrently
+			
+			eachMessage: async ({
+				topic,
+				partition,
+				message,
+			}: {
+				topic: string;
+				partition: number;
+				message: KafkaMessage;
+			}) => {
+				const startTime = Date.now();
+				try {
+					if (!message.value) return;
+
+					const event = JSON.parse(message.value.toString()) as AxovaEvent;
+					const handlers = this.eventHandlers.get(event.type) || [];
+
+					if (handlers.length === 0) {
+						console.warn(`⚠️ No handlers registered for event type: ${event.type}`);
+						return;
+					}
+
+					// Execute all handlers for this event type
+					const handlerPromises = handlers.map(async (handler) => {
+						try {
+							await handler(event);
+						} catch (handlerError) {
+							console.error(
+								`❌ Handler error for event ${event.type}:`,
+								handlerError,
+							);
+							// Log error but don't throw - allows other handlers to execute
+							// TODO: Consider implementing dead letter queue for failed handlers
+						}
+					});
+
+					// Wait for all handlers to complete
+					await Promise.allSettled(handlerPromises);
+
+					const processingTime = Date.now() - startTime;
+					console.log(
+						`✅ Processed ${handlers.length} handler(s) for event: ${event.type} (${processingTime}ms)`,
+					);
+				} catch (error) {
+					const processingTime = Date.now() - startTime;
+					console.error(
+						`❌ Failed to process message from ${topic} [partition ${partition}] (${processingTime}ms):`,
+						error,
+					);
+					// TODO: Implement dead letter queue for failed messages
+					// For now, the message will be retried based on consumer config
+				}
+			},
+		});
+
+		console.log(`✅ Started consuming events for group: ${groupId}`);
+		console.log("   • Processing 3 partitions concurrently");
+		console.log("   • Handlers execute in parallel per message");
+	}
+
+	// Disconnect all connections
+	async disconnect(): Promise<void> {
+		if (this.producer) {
+			await this.producer.disconnect();
+			this.producer = null;
+		}
+
+		for (const [_groupId, consumer] of this.consumers.entries()) {
+			await consumer.disconnect();
+		}
+		this.consumers.clear();
+
+		console.log("All Kafka connections disconnected");
+	}
+
+	// Utility method to create event with base properties
+	createEvent<T extends AxovaEvent>(
+		type: T["type"],
+		data: T["data"],
+		source: string,
+	): T {
+		// Validate required fields
+		if (!type) {
+			throw new Error("Event type is required for Kafka event creation");
+		}
+		if (!source) {
+			throw new Error("Event source is required for Kafka event creation");
+		}
+		
+		return {
+			id: createId(),
+			timestamp: new Date().toISOString(),
+			source: String(source),
+			version: "1.0",
+			type: String(type),
+			data: data || {},
+		} as T;
+	}
+}
+
+// Singleton factory for Kafka instance
+let kafkaInstance: AxovaKafka | null = null;
+
+export function createKafkaInstance(config: AxovaKafkaConfig): AxovaKafka {
+	if (!kafkaInstance) {
+		kafkaInstance = new AxovaKafka(config);
+	}
+	return kafkaInstance;
+}
+
+export function getKafkaInstance(): AxovaKafka {
+	if (!kafkaInstance) {
+		throw new Error(
+			"Kafka instance not created. Call createKafkaInstance() first.",
+		);
+	}
+	return kafkaInstance;
+}
+
+// Utility function to get Kafka config from environment
+export function getKafkaConfigFromEnv(): AxovaKafkaConfig {
+	const brokers = process.env.KAFKA_BROKERS?.split(",") || ["localhost:9092"];
+	const clientId = process.env.KAFKA_CLIENT_ID || "axova-service";
+
+	const config: AxovaKafkaConfig = {
+		brokers,
+		clientId,
+	};
+
+	// Add SSL if configured
+	if (process.env.KAFKA_SSL === "true") {
+		config.ssl = true;
+	}
+
+	// Add SASL if configured
+	if (process.env.KAFKA_USERNAME && process.env.KAFKA_PASSWORD) {
+		config.sasl = {
+			mechanism: "plain",
+			username: process.env.KAFKA_USERNAME,
+			password: process.env.KAFKA_PASSWORD,
+		};
+	}
+
+	return config;
+}
+
+// Export common topics for easy access
+export { KAFKA_TOPICS };

package/src/index.ts

@@ -0,0 +1,26 @@
+// Database
+
+// Service Configuration Profiles
+export * from "./configs";
+// Kafka Events and Utilities
+export * from "./events/kafka";
+// Audit Logging
+export * from "./lib/auditLogger";
+// Auth Organization
+export * from "./lib/authOrganization";
+export { db, pool } from "./lib/db";
+// Service Authentication
+export * from "./middleware/serviceAuth";
+export * from "./middleware/storeOwnership";
+export * from "./middleware/storeValidationMiddleware";
+export * from "./middleware/userAuth";
+
+// Schemas - Organized by Service
+export * from "./schemas";
+
+// Types and Interfaces
+export * from "./types/events";
+
+// Utilities
+export * from "./utils/errorHandler";
+export * from "./utils/subdomain";

package/src/interfaces/customer-events.ts

@@ -0,0 +1,106 @@
+// Customer Service Events Configuration
+export interface CustomerServiceConfig {
+	serviceName: string;
+	version: string;
+	events: CustomerServiceEvents;
+}
+
+export interface CustomerServiceEvents {
+	CUSTOMER_CREATED: "customer.created";
+	CUSTOMER_UPDATED: "customer.updated";
+	CUSTOMER_DELETED: "customer.deleted";
+	CUSTOMER_VISIT_CREATED: "customer.visit.created";
+	CUSTOMER_INTERACTION_CREATED: "customer.interaction.created";
+	CUSTOMER_NOTE_CREATED: "customer.note.created";
+	CUSTOMER_SUPPORT_TICKET_CREATED: "customer.support.ticket.created";
+	CUSTOMER_REVIEW_SUBMITTED: "customer.review.submitted";
+}
+
+// Customer Service Event Types
+export type CustomerEventType =
+	| "customer.created"
+	| "customer.updated"
+	| "customer.deleted"
+	| "customer.visit.created"
+	| "customer.interaction.created"
+	| "customer.note.created"
+	| "customer.support.ticket.created"
+	| "customer.review.submitted";
+
+// Customer Event Payloads
+export interface CustomerCreatedEvent {
+	customerId: string;
+	userId: string;
+	email: string;
+	firstName: string;
+	lastName: string;
+	customerType: string;
+	registrationSource: string;
+	storeLocationId?: string;
+}
+
+export interface CustomerUpdatedEvent {
+	customerId: string;
+	userId: string;
+	changes: Record<string, unknown>;
+	previousValues: Record<string, unknown>;
+	registrationSourceChanged: boolean;
+}
+
+export interface CustomerDeletedEvent {
+	customerId: string;
+	userId: string;
+	email: string;
+	customerType: string;
+	registrationSource: string;
+	totalSpent: string;
+	totalOrders: number;
+	totalVisits: number;
+	totalInteractions: number;
+}
+
+export interface CustomerVisitCreatedEvent {
+	visitId: string;
+	customerId: string;
+	visitType: string;
+	storeLocationId?: string;
+	outcome?: string;
+	duration?: number;
+}
+
+export interface CustomerInteractionCreatedEvent {
+	interactionId: string;
+	customerId: string;
+	interactionType: string;
+	targetType?: string;
+	targetId?: string;
+	outcome?: string;
+	staffId?: string;
+}
+
+export interface CustomerNoteCreatedEvent {
+	noteId: string;
+	customerId: string;
+	noteType: string;
+	priority: string;
+	isAlert: boolean;
+	createdBy: string;
+}
+
+export interface CustomerSupportTicketCreatedEvent {
+	ticketId: string;
+	ticketNumber: string;
+	customerId: string;
+	subject: string;
+	category: string;
+	priority: string;
+}
+
+export interface CustomerReviewSubmittedEvent {
+	reviewId: string;
+	customerId: string;
+	targetType: string;
+	targetId: string;
+	rating: number;
+	isVerifiedPurchase: boolean;
+}