@axova/shared 1.0.0

package/dist/events/kafka.js

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KAFKA_TOPICS = exports.AxovaKafka = void 0;
+exports.createKafkaInstance = createKafkaInstance;
+exports.getKafkaInstance = getKafkaInstance;
+exports.getKafkaConfigFromEnv = getKafkaConfigFromEnv;
+const cuid2_1 = require("@paralleldrive/cuid2");
+const kafkajs_1 = require("kafkajs");
+const events_1 = require("../types/events");
+Object.defineProperty(exports, "KAFKA_TOPICS", { enumerable: true, get: function () { return events_1.KAFKA_TOPICS; } });
+// Kafka client wrapper
+class AxovaKafka {
+    constructor(config) {
+        this.producer = null;
+        this.consumers = new Map();
+        this.eventHandlers = new Map();
+        const kafkaConfig = {
+            clientId: config.clientId,
+            brokers: config.brokers,
+        };
+        if (config.ssl) {
+            kafkaConfig.ssl = config.ssl;
+        }
+        if (config.sasl) {
+            kafkaConfig.sasl = config.sasl;
+        }
+        this.kafka = new kafkajs_1.Kafka(kafkaConfig);
+    }
+    // Initialize producer with optimized settings for high throughput and reliability
+    async initializeProducer(config) {
+        if (this.producer)
+            return;
+        const optimizedConfig = {
+            // 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, topics, config) {
+        if (this.consumers.has(groupId))
+            return;
+        const optimizedConfig = {
+            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, event) {
+        if (!this.producer) {
+            throw new Error("Producer not initialized. Call initializeProducer() first.");
+        }
+        // Ensure all header values are strings (KafkaJS requirement)
+        const headers = {};
+        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 || (0, cuid2_1.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, events) {
+        if (!this.producer) {
+            throw new Error("Producer not initialized. Call initializeProducer() first.");
+        }
+        if (events.length === 0)
+            return;
+        const messages = events.map((event) => {
+            const headers = {};
+            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 || (0, cuid2_1.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(eventType, handler) {
+        const handlers = this.eventHandlers.get(eventType) || [];
+        handlers.push(handler);
+        this.eventHandlers.set(eventType, handlers);
+    }
+    // Start consuming events with optimized batch processing
+    async startConsuming(groupId) {
+        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, }) => {
+                const startTime = Date.now();
+                try {
+                    if (!message.value)
+                        return;
+                    const event = JSON.parse(message.value.toString());
+                    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() {
+        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(type, data, source) {
+        // 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: (0, cuid2_1.createId)(),
+            timestamp: new Date().toISOString(),
+            source: String(source),
+            version: "1.0",
+            type: String(type),
+            data: data || {},
+        };
+    }
+}
+exports.AxovaKafka = AxovaKafka;
+// Singleton factory for Kafka instance
+let kafkaInstance = null;
+function createKafkaInstance(config) {
+    if (!kafkaInstance) {
+        kafkaInstance = new AxovaKafka(config);
+    }
+    return kafkaInstance;
+}
+function getKafkaInstance() {
+    if (!kafkaInstance) {
+        throw new Error("Kafka instance not created. Call createKafkaInstance() first.");
+    }
+    return kafkaInstance;
+}
+// Utility function to get Kafka config from environment
+function getKafkaConfigFromEnv() {
+    const brokers = process.env.KAFKA_BROKERS?.split(",") || ["localhost:9092"];
+    const clientId = process.env.KAFKA_CLIENT_ID || "axova-service";
+    const config = {
+        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;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./configs";
+export * from "./events/kafka";
+export * from "./lib/auditLogger";
+export * from "./lib/authOrganization";
+export { db, pool } from "./lib/db";
+export * from "./middleware/serviceAuth";
+export * from "./middleware/storeOwnership";
+export * from "./middleware/storeValidationMiddleware";
+export * from "./middleware/userAuth";
+export * from "./schemas";
+export * from "./types/events";
+export * from "./utils/errorHandler";
+export * from "./utils/subdomain";

package/dist/index.js

@@ -0,0 +1,41 @@
+"use strict";
+// Database
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pool = exports.db = void 0;
+// Service Configuration Profiles
+__exportStar(require("./configs"), exports);
+// Kafka Events and Utilities
+__exportStar(require("./events/kafka"), exports);
+// Audit Logging
+__exportStar(require("./lib/auditLogger"), exports);
+// Auth Organization
+__exportStar(require("./lib/authOrganization"), exports);
+var db_1 = require("./lib/db");
+Object.defineProperty(exports, "db", { enumerable: true, get: function () { return db_1.db; } });
+Object.defineProperty(exports, "pool", { enumerable: true, get: function () { return db_1.pool; } });
+// Service Authentication
+__exportStar(require("./middleware/serviceAuth"), exports);
+__exportStar(require("./middleware/storeOwnership"), exports);
+__exportStar(require("./middleware/storeValidationMiddleware"), exports);
+__exportStar(require("./middleware/userAuth"), exports);
+// Schemas - Organized by Service
+__exportStar(require("./schemas"), exports);
+// Types and Interfaces
+__exportStar(require("./types/events"), exports);
+// Utilities
+__exportStar(require("./utils/errorHandler"), exports);
+__exportStar(require("./utils/subdomain"), exports);

package/dist/interfaces/customer-events.d.ts

@@ -0,0 +1,85 @@
+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";
+}
+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";
+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;
+}

package/dist/interfaces/customer-events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });