@kenniy/godeye-event-contracts/README.md

Shared event schemas and stream definitions for 8Medical microservices architecture

# GOD-EYE Event Contracts

Standardized event schemas and stream definitions for 8Medical microservices architecture.

[![npm version](https://badge.fury.io/js/%40kenniy%2Fgodeye-event-contracts.svg)](https://www.npmjs.com/package/@kenniy/godeye-event-contracts)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)](https://github.com/keniiy/event-contracts/actions)

## 🎉 Latest Update: v1.0.11 - COMPLETE STANDARDIZATION ACHIEVED

✅ **ZERO legacy code or hardcoded strings remaining**
✅ **ALL services use standardized constants**
✅ **Event flow mismatches completely resolved**
✅ **Clean, maintainable folder structure**
✅ **100% type safety with TypeScript**

## 🏗️ Architecture

This package provides a unified event-driven communication contract for all microservices in the GOD-EYE Healthcare Platform.

## 📁 Project Structure

```plaintext
@kenniy/godeye-event-contracts/
src/
├── consumers/           # Consumer group definitions
│   └── index.ts        # ConsumerGroups, ConsumerGroupName type
├── events/             # Service-specific event schemas
│   ├── user-service/
│   │   ├── index.ts    # UserServiceEvents
│   │   └── registration.ts
│   ├── hrm-service/
│   │   └── index.ts    # HrmServiceEvents
│   ├── file-notification-service/
│   │   └── index.ts    # NotificationServiceEventTypes
│   └── system/
│       └── index.ts    # SystemEventTypes
├── schemas/            # Base event interfaces
│   └── base-event.ts   # BaseEvent, EventEnvelope, etc.
├── services/           # Service name constants
│   └── index.ts        # ServiceNames, ServiceName type
├── streams/            # Stream definitions
│   └── index.ts        # EventStreams, EventStreamName type
├── config/             # Configuration mappings
│   ├── index.ts        # Barrel file
│   ├── consumer-group-streams.ts
│   └── service-consumer-recommendations.ts
└── index.ts            # Main barrel file
```

## 🚀 Installation

```bash
npm install @kenniy/godeye-event-contracts
```

## 📖 Usage

### Basic Event Publishing

```typescript
import {
  EventStreams,
  UserServiceEvents,
  ServiceNames
} from '@kenniy/godeye-event-contracts';

// Publish a business registration event
await eventPublisher.publish(
  EventStreams.USER_SERVICE_EVENTS,
  UserServiceEvents.BUSINESS_REGISTERED,
  {
    businessId: '123',
    businessName: 'Medical Center',
    email: 'contact@medical.com'
  }
);
```

### Event Consumption

```typescript
import {
  EventStreams,
  UserServiceEvents,
  ConsumerGroups
} from '@kenniy/godeye-event-contracts';

// Listen for business registration events
consumer.subscribe(
  EventStreams.USER_SERVICE_EVENTS,
  ConsumerGroups.EMAIL_PROCESSORS,
  (event) => {
    if (event.eventType === UserServiceEvents.BUSINESS_REGISTERED) {
      // Send welcome email
      console.log(`Welcome ${event.data.businessName}!`);
    }
  }
);
```

### Consumer Group Configuration

```typescript
import {
  ConsumerGroups,
  getConsumerGroupStreams,
  getServiceConsumerGroups
} from '@kenniy/godeye-event-contracts';

// Get recommended consumer groups for a service
const groups = getServiceConsumerGroups(ServiceNames.FILE_NOTIFICATION_SERVICE);
// Returns: [ConsumerGroups.EMAIL_PROCESSORS, ConsumerGroups.SMS_PROCESSORS, ...]

// Get streams for a consumer group
const streams = getConsumerGroupStreams(ConsumerGroups.EMAIL_PROCESSORS);
// Returns: [EventStreams.USER_SERVICE_EVENTS, EventStreams.HRM_SERVICE_EVENTS, ...]
```

## 🎯 Event Types by Service

### User Service Events

- `CUSTOMER_REGISTERED` - New customer registration
- `BUSINESS_REGISTERED` - New business registration
- `ADMIN_CREATED` - Admin user creation
- `CUSTOMER_LOGGED_IN/OUT` - Authentication events
- `EMAIL_VERIFIED` - Email verification completion
- `PASSWORD_RESET_REQUESTED` - Password reset requests

### HRM Service Events

- `HOSPITAL_REGISTERED` - Hospital registration
- `BED_ALLOCATED/RELEASED` - Bed management
- `STAFF_ASSIGNED` - Staff assignments
- `EMERGENCY_ALERT` - Emergency notifications

### File+Notification Service Events

- `EMAIL_SENT/FAILED/DELIVERED` - Email delivery tracking
- `SMS_SENT/FAILED/DELIVERED` - SMS delivery tracking
- `FILE_UPLOADED/PROCESSED` - File processing events

### System Events

- `SERVICE_WELCOME` - Service startup announcements
- `SERVICE_HEARTBEAT` - Health check events

## 🔄 Event Streams

- `USER_SERVICE_EVENTS` - User registration, authentication
- `HRM_SERVICE_EVENTS` - Hospital resource management
- `NOTIFICATION_SERVICE_EVENTS` - Email/SMS delivery
- `BUSINESS_VERIFICATION_EVENTS` - Business verification workflow
- `SERVICE_HEALTH_EVENTS` - System monitoring

## 👥 Consumer Groups

- `EMAIL_PROCESSORS` - Email notification handling
- `SMS_PROCESSORS` - SMS notification handling
- `HRM_PROCESSORS` - Hospital business logic
- `ANALYTICS_PROCESSORS` - Data analytics and reporting
- `AUDIT_PROCESSORS` - Compliance and security logging

## 🏥 Service Names

- `USER_SERVICE` - User management and authentication
- `HRM_SERVICE` - Hospital resource management
- `FILE_NOTIFICATION_SERVICE` - File processing and notifications
- `PAYMENT_SERVICE` - Payment processing
- `TRANSPORT_SERVICE` - Ambulance and logistics
- `AGGREGATOR_SERVICE` - Data aggregation
- `GATEWAY_SERVICE` - API gateway

## 📝 Type Safety

All events are fully typed with TypeScript interfaces:

```typescript
import { BusinessRegisteredEvent, CustomerRegisteredEvent } from '@kenniy/godeye-event-contracts';

function handleBusinessRegistration(event: BusinessRegisteredEvent) {
  // event.data is fully typed
  console.log(`New business: ${event.data.businessName}`);
  console.log(`Contact: ${event.data.email}`);
}
```

## 🔧 Configuration

The package provides configuration helpers for setting up consumer groups and stream mappings:

```typescript
import {
  ServiceConsumerRecommendations,
  ConsumerGroupStreams
} from '@kenniy/godeye-event-contracts';

// Get all recommended setups
const recommendations = ServiceConsumerRecommendations;
const streamMappings = ConsumerGroupStreams;
```

## 📊 Event Flow Examples

### Business Registration Flow

1. **User Service** publishes `UserServiceEvents.BUSINESS_REGISTERED`
2. **File+Notification Service** consumes via `ConsumerGroups.EMAIL_PROCESSORS`
3. **HRM Service** consumes via `ConsumerGroups.HRM_PROCESSORS`
4. Welcome email sent + hospital profile created

### Hospital Bed Management

1. **HRM Service** publishes `HrmServiceEvents.BED_ALLOCATED`
2. **Analytics Service** tracks via `ConsumerGroups.ANALYTICS_PROCESSORS`
3. **Notification Service** sends alerts via `ConsumerGroups.SMS_PROCESSORS`

## 🔄 Migration from Legacy

### Before (Event Mismatches)

```typescript
// File+Notification Service was importing:
import { UserServiceEventTypes } from '@kenniy/godeye-event-contracts'; // ❌ DIDN'T EXIST!

// Causing events to be lost between services
```

### After (Fixed)

```typescript
// Now correctly imports:
import { UserServiceEvents } from '@kenniy/godeye-event-contracts'; // ✅ WORKS!

// Events flow correctly: User Service → File+Notification Service
```

## 🚦 Version History

- **v1.0.11** - Complete standardization with clean folder structure
- **v1.0.10** - Added missing event types and fixed import mismatches
- **v1.0.9** - Event flow mapping and mismatch resolution
- **v1.0.8** - Consumer group reorganization
- **v1.0.7** - Stream standardization
- **v1.0.6** - Initial standardized contracts

## 🛠️ Development

```bash
# Clone and setup
git clone https://github.com/keniiy/event-contracts.git
cd event-contracts
npm install

# Build
npm run build

# Watch mode
npm run dev

# Publish (maintainers only)
npm run prepublishOnly
npm publish
```

## 🔗 Related Packages

This package is part of the GOD-EYE Healthcare Platform:

- `@kenniy/godeye-user-service`
- `@kenniy/godeye-hrm-service`
- `@kenniy/godeye-file-notification-service`

## 📄 License

Private package for 8Medical GOD-EYE Healthcare Platform.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/keniiy/event-contracts/issues)
- **Email**: [kehindekehinde@gmail.com](mailto:kehindekehinde@gmail.com)

---

### 🎯 Complete Event Standardization Achieved

- ✅ Zero legacy code or naming inconsistencies
- ✅ All services use standardized event constants
- ✅ Event flows properly mapped end-to-end
- ✅ Type safety with full TypeScript support
- ✅ Clean, maintainable folder structure
- ✅ All import mismatches resolved
- ✅ Event communication working perfectly