@squiz/dx-common-lib 1.72.0 → 1.72.3

package/src/events/EventBusService.ts

@@ -0,0 +1,316 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+import { Logger } from '@squiz/dx-logger-lib';
+
+export interface EventBusConfig {
+  eventBusUrl: string;
+  eventBusKey: string;
+  tenantId?: string;
+  deploymentEnvironment: string;
+  squizRegion: string;
+}
+
+/** Matches DXP Event Bus POST /events envelope (flat `metadata` + `event`, not nested under `detail`). */
+export interface EventBusEvent {
+  source: string;
+  'detail-type': string;
+  action: string;
+  eventTime: string;
+  metadata: {
+    tenantID: string;
+    /** Deployment label, e.g. `dev` / `uat` / `prod` (from `EventBusConfig.deploymentEnvironment`). */
+    environment: string;
+    region: string;
+  };
+  event: object;
+}
+
+export interface EventBusResponse {
+  statusCode: number;
+  event: {
+    id: string;
+    source: string;
+    detailType: string;
+    time: string;
+    detail: {
+      metadata: {
+        action: string;
+        tenantID: string;
+        eventTime: string;
+      };
+      event: object;
+    };
+  };
+}
+
+export type EventBusApiResponse = Array<EventBusResponse>;
+
+/** Response bodies can be huge; keep previews bounded. */
+const MAX_RESPONSE_BODY_LOG_CHARS = 16_384;
+
+/**
+ * Request body is the exact JSON string sent to `POST …/events` — log it in full for debugging unless enormous.
+ * (CloudWatch/Lambda still have per-line limits; this cap avoids pathological cases.)
+ */
+const MAX_REQUEST_BODY_LOG_CHARS = 512 * 1024;
+
+function isMissing(value: string | undefined): boolean {
+  return value === undefined || value.trim() === '';
+}
+
+function truncateForLog(value: string, max: number): string {
+  if (value.length <= max) {
+    return value;
+  }
+  return `${value.slice(0, max)}… [truncated, ${value.length - max} more chars]`;
+}
+
+/** Full outbound payload for logs (same bytes as fetch `body`), with a rare size cap. */
+function requestBodyForLog(body: string): string {
+  if (body.length <= MAX_REQUEST_BODY_LOG_CHARS) {
+    return body;
+  }
+  return truncateForLog(body, MAX_REQUEST_BODY_LOG_CHARS);
+}
+
+export interface EventBusServiceInterface {
+  /**
+   * Publishes a single event to the Event Bus via HTTP POST.
+   * @param detailType The type of the event (e.g., 'component.change.create')
+   * @param detail The event payload
+   * @returns The API response containing event IDs and status codes
+   * @throws Error if configuration is missing or API call fails
+   */
+  publishEvent(detailType: string, detail: object): Promise<EventBusApiResponse>;
+  /**
+   * Publishes a single event with safe error handling and response validation.
+   * Catches errors and logs them without throwing, so it doesn't break the calling flow.
+   * Validates that the API returned valid status codes for all events.
+   * @param detailType The type of the event (e.g., 'component.change.create')
+   * @param detail The event payload
+   */
+  publishEventSafely(detailType: string, detail: object): Promise<void>;
+  /**
+   * Publishes multiple events to the Event Bus via HTTP POST in a single request.
+   * @param events Array of events with detailType and detail payload
+   * @returns The API response containing event IDs and status codes
+   * @throws Error if configuration is missing or API call fails
+   */
+  publishEvents(events: Array<{ detailType: string; detail: object }>): Promise<EventBusApiResponse>;
+  /**
+   * Publishes multiple events with safe error handling and response validation.
+   * Catches errors and logs them without throwing, so it doesn't break the calling flow.
+   * @param events Array of events with detailType and detail payload
+   */
+  publishEventsSafely(events: Array<{ detailType: string; detail: object }>): Promise<void>;
+}
+
+export class EventBusService implements EventBusServiceInterface {
+  private readonly validStatusCodes = [200, 201, 202];
+
+  constructor(private logger: Logger, private config: EventBusConfig) {}
+
+  public setTenantId(tenantId: string): void {
+    this.config.tenantId = tenantId;
+  }
+
+  /**
+   * Throws with a specific message so operators know whether URL, API key, or tenant context is missing.
+   */
+  private ensureEventBusCredentials(): void {
+    const missing: string[] = [];
+    if (isMissing(this.config.eventBusUrl)) {
+      missing.push('EVENT_BUS_URL (Event Bus base URL; Lambda receives this at deploy time)');
+    }
+    if (isMissing(this.config.eventBusKey)) {
+      missing.push('EVENT_BUS_KEY (API key sent as x-api-key; set via CDK/CI or Lambda env)');
+    }
+    if (missing.length > 0) {
+      throw new Error(`Event Bus is not configured: missing ${missing.join(' and ')}.`);
+    }
+  }
+
+  private ensureTenantId(): void {
+    if (isMissing(this.config.tenantId)) {
+      throw new Error(
+        'Tenant ID is not set. The stream processor must call setTenantId before publishing (x-dxp-tenant header).',
+      );
+    }
+  }
+
+  private eventBusPostUrl(): string {
+    const base = this.config.eventBusUrl.replace(/\/+$/, '');
+    return `${base}/events`;
+  }
+
+  /** Safe when URL is unset (e.g. logging after a config error). */
+  private safeEventBusEndpointForLog(): string | undefined {
+    if (isMissing(this.config.eventBusUrl)) {
+      return undefined;
+    }
+    return this.eventBusPostUrl();
+  }
+
+  private async postToEventBus(eventsPayload: EventBusEvent[]): Promise<EventBusApiResponse> {
+    const url = this.eventBusPostUrl();
+    const body = JSON.stringify(eventsPayload);
+    const headers: Record<string, string> = {
+      'x-api-key': this.config.eventBusKey,
+      'x-dxp-tenant': this.config.tenantId as string,
+      'Content-Type': 'application/json',
+    };
+
+    const headersForLog = { ...headers, 'x-api-key': '[REDACTED]' };
+
+    let response: Response;
+    try {
+      response = await fetch(url, { method: 'POST', headers, body });
+    } catch (err) {
+      this.logger.error('Event Bus request failed before HTTP response (network/DNS/TLS)', {
+        eventBusEndpoint: url,
+        method: 'POST',
+        tenantId: this.config.tenantId,
+        /** Exact JSON sent as the fetch body (see `requestBodyForLog` for rare truncation). */
+        requestBody: requestBodyForLog(body),
+        headers: headersForLog,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
+    }
+
+    if (!response.ok) {
+      const responseText = await response.text();
+      const responsePreview = truncateForLog(responseText, MAX_RESPONSE_BODY_LOG_CHARS);
+      this.logger.error('Event Bus API returned a non-success HTTP status', {
+        eventBusEndpoint: url,
+        httpStatus: response.status,
+        httpStatusText: response.statusText,
+        tenantId: this.config.tenantId,
+        /** Full outbound JSON (same as HTTP body); large payloads may be truncated — see `requestBodyForLog`. */
+        requestBody: requestBodyForLog(body),
+        responseBodyPreview: responsePreview,
+        headers: headersForLog,
+      });
+      throw new Error(
+        `Event Bus API error: HTTP ${response.status} ${response.statusText} for POST ${url}. Response body (preview): ${responsePreview}`,
+      );
+    }
+
+    return (await response.json()) as EventBusApiResponse;
+  }
+
+  public async publishEvent(detailType: string, detail: object): Promise<EventBusApiResponse> {
+    this.ensureEventBusCredentials();
+    this.ensureTenantId();
+
+    const eventTime = new Date().toISOString();
+    const event: EventBusEvent = {
+      source: 'component-service',
+      'detail-type': detailType,
+      action: detailType,
+      eventTime,
+      metadata: {
+        tenantID: this.config.tenantId as string,
+        environment: this.config.deploymentEnvironment,
+        region: this.config.squizRegion,
+      },
+      event: detail,
+    };
+
+    const eventsPayload = [event];
+    return this.postToEventBus(eventsPayload);
+  }
+
+  public async publishEvents(events: Array<{ detailType: string; detail: object }>): Promise<EventBusApiResponse> {
+    this.ensureEventBusCredentials();
+
+    if (events.length === 0) {
+      return [];
+    }
+
+    this.ensureTenantId();
+
+    const eventTime = new Date().toISOString();
+    const eventsPayload: EventBusEvent[] = events.map(({ detailType, detail }) => ({
+      source: 'component-service',
+      'detail-type': detailType,
+      action: detailType,
+      eventTime,
+      metadata: {
+        tenantID: this.config.tenantId as string,
+        environment: this.config.deploymentEnvironment,
+        region: this.config.squizRegion,
+      },
+      event: detail,
+    }));
+
+    return this.postToEventBus(eventsPayload);
+  }
+
+  public async publishEventSafely(detailType: string, detail: object): Promise<void> {
+    try {
+      const response = await this.publishEvent(detailType, detail);
+
+      const failedEvents = response.filter(
+        (eventResponse) => !this.validStatusCodes.includes(eventResponse.statusCode),
+      );
+
+      if (failedEvents.length > 0) {
+        const failedStatuses = failedEvents.map((e) => e.statusCode).join(', ');
+        this.logger.error(
+          `Event publishing failed: received non-valid status codes [${failedStatuses}] for event ${detailType}`,
+        );
+        return;
+      }
+
+      const eventIds = response.map((eventResponse) => eventResponse.event.id).join(', ');
+      this.logger.info(
+        `Successfully published event: ${detailType} with IDs [${eventIds}] to ${this.config.eventBusUrl}/events`,
+      );
+    } catch (e) {
+      const errorMessage = `Failed to publish event ${detailType} to event bus: ${
+        e instanceof Error ? e.message : typeof e === 'string' ? e : JSON.stringify(e)
+      }`;
+      this.logger.error(errorMessage, {
+        detailType,
+        tenantId: this.config.tenantId,
+        eventBusEndpoint: this.safeEventBusEndpointForLog(),
+      });
+    }
+  }
+
+  public async publishEventsSafely(events: Array<{ detailType: string; detail: object }>): Promise<void> {
+    try {
+      const response = await this.publishEvents(events);
+
+      const failedEvents = response.filter(
+        (eventResponse) => !this.validStatusCodes.includes(eventResponse.statusCode),
+      );
+
+      if (failedEvents.length > 0) {
+        const failedStatuses = failedEvents.map((e) => e.statusCode).join(', ');
+        const errorMessage = `Event publishing failed: received non-valid status codes [${failedStatuses}] for batch of ${events.length} events`;
+        this.logger.error(errorMessage);
+        throw new Error(errorMessage);
+      }
+
+      const eventIds = response.map((eventResponse) => eventResponse.event.id).join(', ');
+      this.logger.info(
+        `Successfully published batch of ${events.length} events with IDs [${eventIds}] to ${this.config.eventBusUrl}/events`,
+      );
+    } catch (e) {
+      const errorMessage = `Failed to publish batch of ${events.length} events to event bus: ${
+        e instanceof Error ? e.message : typeof e === 'string' ? e : JSON.stringify(e)
+      }`;
+      this.logger.error(errorMessage, {
+        tenantId: this.config.tenantId,
+        eventCount: events.length,
+        detailTypes: events.map((ev) => ev.detailType),
+        eventBusEndpoint: this.safeEventBusEndpointForLog(),
+      });
+      throw new Error(errorMessage);
+    }
+  }
+}

package/src/index.ts

@@ -16,3 +16,8 @@ export * from './edge-components-secret-key-service/EdgeComponentsSecretKeyServi
 export * from './edge-components-secret-key-service/getEdgeComponentsSecretService';
 export * from './esi-mac-token-generator/EsiMacTokenGenerator';
 export * from './secret-api-key-service/SecretApiKeyService';
+export * from './secret-api-key-service/DevSecretApiKeyService';
+export * from './secret-api-key-service/getSecretApiKeyService';
+export * from './events/EventBusService';
+export * from './stream/EventStreamHandler';
+export * from './stream/StreamUtils';

package/src/secret-api-key-service/DevSecretApiKeyService.spec.ts

@@ -0,0 +1,211 @@
+import { DevSecretApiKeyService } from './DevSecretApiKeyService';
+
+describe('DevSecretApiKeyService', () => {
+  describe('Constructor', () => {
+    it('should successfully create service with valid API key', () => {
+      const apiKey = 'test-api-key-12345';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      expect(service).toBeInstanceOf(DevSecretApiKeyService);
+    });
+
+    it('should throw error when API key is empty string', () => {
+      expect(() => new DevSecretApiKeyService('')).toThrow('API key must be a non-empty string');
+    });
+
+    it('should throw error when API key is whitespace only', () => {
+      expect(() => new DevSecretApiKeyService('   ')).toThrow('API key must be a non-empty string');
+    });
+
+    it('should throw error when API key is only tabs', () => {
+      expect(() => new DevSecretApiKeyService('\t\t')).toThrow('API key must be a non-empty string');
+    });
+
+    it('should throw error when API key is only newlines', () => {
+      expect(() => new DevSecretApiKeyService('\n\n')).toThrow('API key must be a non-empty string');
+    });
+
+    it('should accept API key with surrounding whitespace', () => {
+      // Note: The constructor checks trimmed length, but stores the original value
+      const apiKey = '  valid-key  ';
+      expect(() => new DevSecretApiKeyService(apiKey)).not.toThrow();
+    });
+  });
+
+  describe('getApiKey', () => {
+    it('should return the API key provided in constructor', async () => {
+      const apiKey = 'test-api-key-xyz';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should return same API key on multiple calls', async () => {
+      const apiKey = 'consistent-api-key';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result1 = await service.getApiKey();
+      const result2 = await service.getApiKey();
+      const result3 = await service.getApiKey();
+
+      expect(result1).toBe(apiKey);
+      expect(result2).toBe(apiKey);
+      expect(result3).toBe(apiKey);
+    });
+
+    it('should handle concurrent calls efficiently', async () => {
+      const apiKey = 'concurrent-test-key';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      // Make multiple concurrent calls
+      const promises = Array(10)
+        .fill(null)
+        .map(() => service.getApiKey());
+
+      const results = await Promise.all(promises);
+
+      // All should return the same key
+      expect(results).toEqual(Array(10).fill(apiKey));
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle very long API keys', async () => {
+      const apiKey = 'x'.repeat(1000); // 1000 character API key
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should handle special characters in API key', async () => {
+      const apiKey = 'test-key-!@#$%^&*()_+-=[]{}|;:"<>,.?/~`';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should handle unicode characters in API key', async () => {
+      const apiKey = 'test-key-你好-مرحبا-🔑';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should handle API key with line breaks', async () => {
+      const apiKey = 'key-with\nline\nbreaks';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should handle base64-like API keys', async () => {
+      const apiKey =
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should handle UUID-format API keys', async () => {
+      const apiKey = '550e8400-e29b-41d4-a716-446655440000';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should handle hexadecimal API keys', async () => {
+      const apiKey = 'a1b2c3d4e5f6789012345678901234567890abcdef';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+  });
+
+  describe('Interface Compliance', () => {
+    it('should implement SecretApiKeyServiceInterface', async () => {
+      const service = new DevSecretApiKeyService('test-key');
+
+      // Check that the required methods exist
+      expect(typeof service.getApiKey).toBe('function');
+    });
+
+    it('should return a Promise from getApiKey', () => {
+      const service = new DevSecretApiKeyService('test-key');
+      const result = service.getApiKey();
+
+      expect(result).toBeInstanceOf(Promise);
+    });
+  });
+
+  describe('Memory and Performance', () => {
+    it('should not modify the API key after construction', async () => {
+      const originalKey = 'immutable-key-123';
+      const service = new DevSecretApiKeyService(originalKey);
+
+      // Get the key multiple times
+      await service.getApiKey();
+      await service.getApiKey();
+      await service.getApiKey();
+
+      // Key should still be the same
+      const result = await service.getApiKey();
+      expect(result).toBe(originalKey);
+    });
+
+    it('should handle rapid sequential calls', async () => {
+      const apiKey = 'rapid-call-key';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      // Make rapid sequential calls
+      for (let i = 0; i < 100; i++) {
+        const result = await service.getApiKey();
+        expect(result).toBe(apiKey);
+      }
+    });
+  });
+
+  describe('Real-world Scenarios', () => {
+    it('should work with typical metrics service API key format', async () => {
+      const apiKey = 'metrics-api-key-prod-abc123def456';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should work with AWS-style secret format', async () => {
+      const apiKey = 'aws-secret-key-AKIAIOSFODNN7EXAMPLE';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+
+    it('should work with Bearer token format', async () => {
+      const apiKey = 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9';
+      const service = new DevSecretApiKeyService(apiKey);
+
+      const result = await service.getApiKey();
+
+      expect(result).toBe(apiKey);
+    });
+  });
+});

package/src/secret-api-key-service/DevSecretApiKeyService.ts

@@ -0,0 +1,36 @@
+/*!
+ * @file EnvApiKeyService.ts
+ * @description Retrieves API key from environment variable (for local development).
+ * @author Squiz
+ * @copyright 2025 Squiz
+ * @license MIT
+ */
+
+import { SecretApiKeyServiceInterface } from './SecretApiKeyService';
+
+/**
+ * Service for retrieving API keys from environment variables.
+ * Used for local development as an alternative to AWS Secrets Manager.
+ */
+export class DevSecretApiKeyService implements SecretApiKeyServiceInterface {
+  private readonly apiKey: string;
+
+  /**
+   * Constructor for EnvApiKeyService
+   * @param apiKey The API key value from environment variable
+   */
+  constructor(apiKey: string) {
+    if (!apiKey || apiKey.trim().length === 0) {
+      throw new Error('API key must be a non-empty string');
+    }
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Returns the API key.
+   * @returns The API key string
+   */
+  public async getApiKey(): Promise<string> {
+    return this.apiKey;
+  }
+}

package/src/secret-api-key-service/SecretApiKeyService.spec.ts

@@ -112,52 +112,6 @@ describe('SecretApiKeyService', () => {
       expect(result2).toBe(mockApiKey);
       expect(mockSend).toHaveBeenCalledTimes(1); // Still only 1 call
     });
-
-    it('should clear cache when clearMetricsApiKeyCache is called', async () => {
-      const mockApiKey1 = 'first-api-key';
-      const mockApiKey2 = 'second-api-key';
-
-      mockSend
-        .mockResolvedValueOnce({
-          SecretString: JSON.stringify({ apikey: mockApiKey1 }),
-        })
-        .mockResolvedValueOnce({
-          SecretString: JSON.stringify({ apikey: mockApiKey2 }),
-        });
-
-      // First retrieval
-      const result1 = await service.getApiKey();
-      expect(result1).toBe(mockApiKey1);
-
-      // Clear cache
-      service.clearCache();
-
-      // Second retrieval after cache clear - should fetch again
-      const result2 = await service.getApiKey();
-      expect(result2).toBe(mockApiKey2);
-      expect(mockSend).toHaveBeenCalledTimes(2);
-    });
-
-    it('should create new SecretsManagerClient for each non-cached call', async () => {
-      // This test verifies that a new client is created when cache is cleared
-
-      mockSend
-        .mockResolvedValueOnce({
-          SecretString: JSON.stringify({ apikey: 'key1' }),
-        })
-        .mockResolvedValueOnce({
-          SecretString: JSON.stringify({ apikey: 'key2' }),
-        });
-
-      await service.getApiKey();
-      service.clearCache(); // Clears API key cache
-      await service.getApiKey();
-
-      // The mock send should be called twice (once for each call after clearing cache)
-      expect(mockSend).toHaveBeenCalledTimes(2);
-      // SecretsManagerClient should be created twice (once per non-cached call)
-      expect(mockSecretsManagerClient).toHaveBeenCalledTimes(2);
-    });
   });
 
   describe('Error Handling', () => {

package/src/secret-api-key-service/SecretApiKeyService.ts

@@ -20,11 +20,6 @@ export interface SecretApiKeyServiceInterface {
    * @returns The API key string
    */
   getApiKey(): Promise<string>;
-
-  /**
-   * Clears the cached API key (useful for testing)
-   */
-  clearCache(): void;
 }
 
 /**
@@ -110,12 +105,4 @@ export class SecretApiKeyService implements SecretApiKeyServiceInterface {
       throw wrappedError;
     }
   }
-
-  /**
-   * Clears the cached API key and client (useful for testing)
-   * @returns void
-   */
-  public clearCache(): void {
-    this.cachedApiKey = undefined;
-  }
 }