Agentic Suite Event SDK

A secure and efficient wrapper around Confluent Kafka for event emission with built-in data validation.

Features

• Singleton pattern for consistent event emission
  • Ensures only one Kafka connection per application
  • Prevents resource duplication
  • Maintains consistent state across your application
• Schema validation using AJV
• Automatic Kafka connection management
• Built-in GZIP message compression via KafkaJS
• Configurable retry settings:
  • maxRetryTime: Maximum time to retry operations
  • initialRetryTime: Initial delay between retries
  • retries: Number of retry attempts
• Comprehensive logging
• Strict configuration validation

Installation

npm install agentic-suite-event-sdk

Singleton Pattern Explanation

The SDK uses the Singleton pattern to ensure that only one instance of the event emitter exists throughout your application. This is important because:

1. Connection Management: Maintains a single Kafka connection instead of creating multiple connections
2. Resource Efficiency: Prevents memory leaks and resource wastage
3. State Consistency: Ensures all events are emitted through the same connection

Example of how the Singleton pattern works:

// First initialization - creates the instance
const emitter1 = new AnalyticsEventEmitter({
  clientId: 'your-client-id',
  brokers: ['kafka-broker:9092'],
  retryConfig: {
    maxRetryTime: 30000,
    initialRetryTime: 1000,
    retries: 5
  }
}, Logger); //  pass motifer require('motifer').Logger as a param.

// Second initialization - returns the existing instance
const emitter2 = new AnalyticsEventEmitter({
  clientId: 'different-client-id',  // This will be ignored
  brokers: ['different-broker:9092'], // This will be ignored
  retryConfig: {
    maxRetryTime: 20000,  // This will be ignored
    initialRetryTime: 500,
    retries: 3
  }
}, Logger); // pass motifer require('motifer').Logger as a param.

// Both variables reference the same instance
console.log(emitter1 === emitter2); // true

Important Notes:

• The configuration provided in subsequent initializations is ignored
• Always store the initial configuration carefully as it will be used throughout the application's lifecycle
• The same instance is shared across different modules that import the SDK

Configuration

The SDK requires a configuration object that is strictly validated to ensure proper initialization. Here's the detailed configuration structure:

const config = {
  // Required: Client identifier for Kafka (1-255 characters)
  clientId: 'your-client-id',

  // Required: Array of Kafka brokers in host:port format
  // Must have at least one broker
  brokers: [
    'kafka-broker1:9092',
    'kafka-broker2:9092'
  ],

  // Required: Retry configuration for Kafka operations
  retryConfig: {
    // Minimum: 1000ms (1 second)
    maxRetryTime: 30000,    // Maximum retry time in milliseconds
    
    // Minimum: 100ms
    initialRetryTime: 1000, // Initial retry time in milliseconds
    
    // Must be between 1 and 10
    retries: 5             // Number of retries
  }
};

Configuration Validation Rules

The SDK performs strict validation of the configuration object with the following rules:

1. clientId:

   • Required
   • Must be a string
   • Length: 1-255 characters

2. brokers:

   • Required
   • Must be an array with at least one broker
   • Each broker must be in the format hostname:port
   • Example: ['localhost:9092']

3. retryConfig:

   • Required
   • Must include all three retry parameters
   • maxRetryTime:
     • Minimum value: 1000ms (1 second)
   • initialRetryTime:
     • Minimum value: 100ms
   • retries:
     • Must be between 1 and 10

If any of these validation rules are violated, the SDK will throw an error with a detailed message indicating which part of the configuration is invalid.

Example with validation error:

try {
  const emitter = new AnalyticsEventEmitter({
    clientId: "test",
    brokers: ["invalid-broker-format"],  // Missing port number
    retryConfig: {
      maxRetryTime: 500,  // Too low, minimum is 1000ms
      initialRetryTime: 200,
      retries: 3
    }
  }, Logger); //  pass motifer require('motifer').Logger as a param.
} catch (error) {
  console.error(error.message);
  // Output: "Invalid configuration: /brokers/0: must match pattern "^[^:]+:[0-9]+$"; 
  //          /retryConfig/maxRetryTime: must be >= 1000"
}

Usage

const AnalyticsEventEmitter = require('agentic-suite-event-sdk');

// Initialize the emitter
const emitter = new AnalyticsEventEmitter({
  clientId: 'your-client-id',
  brokers: ['kafka-broker-1:9092'],
  retryConfig: {
    maxRetryTime: 30000,
    initialRetryTime: 1000,
    retries: 5
  }
}, Logger); //  pass motifer require('motifer').Logger as a param.

// Emit an event
const eventData = {
  analyticsId: 'analytics_id',  // Required string (1-50 chars)
  tenantId: 'uuid-v4-string',     // Required UUID
  uid: 'uuid-v4-string',          // Required UUID
  entity: 'user',                 // Required string (1-50 chars)
  eventName: 'login',             // Required string (1-50 chars)
  properties: {                   // Required object
    // Any valid JSON object
    source: 'web',
    browser: 'chrome'
  }
};

try {
  await emitter.emit('your-topic-name', eventData);
  console.log('Event emitted successfully');
} catch (error) {
  console.error('Error emitting event:', error);
}

Event Schema

All events must conform to the following schema:

{
  ts: string,              // ISO 8601 date-time (auto-generated)
  analyticsId: string,     // Length: 1-50 characters
  tenantId: string,        // UUID v4
  uid: string,             // UUID v4
  entity: string,          // Length: 1-50 characters
  eventName: string,       // Length: 1-50 characters
  properties: object       // Any valid JSON object
}

Error Handling

The SDK throws errors in the following cases:

• Invalid configuration parameters
• Schema validation failures
• Kafka connection issues
• Message publishing failures

All errors include detailed error messages and are properly logged using the Motifer logger.

Dependencies

• @confluentinc/kafka-javascript: 1.3.1
• ajv: 8.17.1
• ajv-formats: 3.0.1
• motifer: 1.2.5
• uuid: 11.0.5

License

UNLICENSED - All rights reserved by SearchUnify.