# @nestjsvn/swagger-sse

> **🚧 Development Status**: This project is currently in active development. Version 1.0.0 will be released soon with full production-ready features. The core functionality is implemented and tested, but the package is still in pre-release (v0.0.1).

[![npm version](https://badge.fury.io/js/@nestjsvn/swagger-sse.svg)](https://badge.fury.io/js/@nestjsvn/swagger-sse)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://github.com/dragonxsx/nestjsx-swagger-sse/workflows/CI/badge.svg)](https://github.com/dragonxsx/nestjsx-swagger-sse/actions)
[![Coverage Status](https://coveralls.io/repos/github/dragonxsx/nestjsx-swagger-sse/badge.svg?branch=main)](https://coveralls.io/github/dragonxsx/nestjsx-swagger-sse?branch=main)

**OpenAPI documentation and interactive Swagger UI for NestJS Server-Sent Events endpoints.**

`@nestjsvn/swagger-sse` bridges the gap between NestJS's excellent SSE support and OpenAPI documentation by providing automatic schema generation, interactive Swagger UI integration, and comprehensive TypeScript support for real-time event streaming APIs.

## ✨ Features

- 🚀 **Zero-configuration setup** with CLI plugin
- 📝 **Automatic OpenAPI schema generation** for SSE endpoints
- 🎯 **Interactive Swagger UI** with real-time event streaming
- 🔒 **Full TypeScript support** with compile-time validation
- ⚡ **High-performance** event processing
- 🛡️ **Authentication support** (JWT, API keys, OAuth)
- 🔧 **Flexible configuration** options

## 🚀 Quick Start

### Installation

```bash
npm install @nestjsvn/swagger-sse
```

### Basic Setup

1. **Update your main application file:**

```typescript
// main.ts
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { setupSsePlugin } from '@nestjsvn/swagger-sse';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API with SSE support')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  
  // Replace SwaggerModule.setup with setupSsePlugin
  setupSsePlugin(app, document, 'api-docs');

  await app.listen(3000);
}
bootstrap();
```

2. **Create your first SSE endpoint:**

```typescript
// events.controller.ts
import { Controller, Sse } from '@nestjs/common';
import { Observable, interval, map } from 'rxjs';
import { ApiSse } from '@nestjsvn/swagger-sse';

export class UserCreatedDto {
  userId: string;
  username: string;
  email: string;
  timestamp: Date;
}

@Controller('events')
export class EventsController {
  @Sse('user-stream')
  @ApiSse({
    summary: 'User events stream',
    description: 'Real-time stream of user-related events',
    events: {
      'user-created': UserCreatedDto,
    },
  })
  streamUserEvents(): Observable<MessageEvent> {
    return interval(2000).pipe(
      map((i) => ({
        data: JSON.stringify({
          userId: `user-${i}`,
          username: `User${i}`,
          email: `user${i}@example.com`,
          timestamp: new Date(),
        }),
        type: 'user-created',
      } as MessageEvent))
    );
  }
}
```

3. **Visit your Swagger UI:**

Navigate to `http://localhost:3000/api-docs` and interact with your SSE endpoints using the enhanced UI!

## 🎯 Interactive Demo

![SSE Swagger UI Demo](https://raw.githubusercontent.com/nestjsx/swagger-sse/main/docs/assets/demo.gif)

The enhanced Swagger UI provides:
- **Real-time connection management** with connect/disconnect controls
- **Live event streaming** with formatted JSON display
- **Event filtering and search** capabilities
- **Connection status indicators** and error handling
- **Mobile-responsive design** for all devices

## 🔧 Advanced Usage

### Automatic Documentation with CLI Plugin

Enable zero-configuration documentation by adding the CLI plugin:

```json
// nest-cli.json
{
  "compilerOptions": {
    "plugins": [
      "@nestjs/swagger",
      {
        "name": "@nestjsvn/swagger-sse/plugin",
        "options": {
          "eventNamingConvention": "kebab-case",
          "introspectComments": true
        }
      }
    ]
  }
}
```

Now you can create SSE endpoints without explicit decorators:

```typescript
@Controller('notifications')
export class NotificationsController {
  /**
   * Streams notification events
   * @summary Real-time notification stream
   */
  @Sse('updates')
  streamNotifications(): Observable<MessageEvent<NotificationDto>> {
    // Plugin automatically generates documentation!
    return this.notificationService.getStream();
  }
}
```

### Multiple Event Types

Handle complex event scenarios with union types:

```typescript
@ApiSse({
  summary: 'Multi-type event stream',
  events: {
    'user-created': UserCreatedDto,
    'user-updated': UserUpdatedDto,
    'user-deleted': UserDeletedDto,
    'system-alert': SystemAlertDto,
  },
})
streamEvents(): Observable<MessageEvent> {
  return merge(
    this.userEvents$,
    this.systemEvents$,
    this.alertEvents$
  );
}
```

### Authentication & Security

Secure your SSE endpoints with guards and authentication:

```typescript
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
@ApiSse({
  summary: 'Authenticated event stream',
  security: [{ bearer: [] }],
  events: {
    'private-event': PrivateEventDto,
  },
})
streamPrivateEvents(@Request() req): Observable<MessageEvent> {
  return this.eventService.getPrivateEvents(req.user.id);
}
```

### Error Handling

Implement robust error handling in your streams:

```typescript
@ApiSse({
  events: {
    'data-update': DataUpdateDto,
    'error': ErrorEventDto,
  },
})
streamWithErrorHandling(): Observable<MessageEvent> {
  return this.dataService.watchData().pipe(
    map(data => ({ type: 'data-update', data: JSON.stringify(data) })),
    catchError(error => of({ 
      type: 'error', 
      data: JSON.stringify({ message: error.message }) 
    }))
  );
}
```

## 📚 Documentation

- **[Getting Started Guide](./docs/getting-started.md)** - Step-by-step setup instructions
- **[API Reference](./docs/api-reference.md)** - Complete API documentation
- **[Plugin Usage](./docs/plugin-usage.md)** - CLI plugin configuration
- **[UI Plugin Usage](./docs/ui-plugin-usage.md)** - Swagger UI integration
- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
- **[Examples](./examples/)** - Real-world usage examples

## 🧪 Testing

The package includes comprehensive testing suites:

```bash
# Unit tests
npm run test

# Unit tests with watch mode
npm run test:watch

# Test coverage report
npm run test:coverage
```

## 🔧 Configuration

### Basic Configuration

```typescript
setupSsePlugin(app, document, 'api-docs', {
  customSiteTitle: 'My API Documentation',
  customCss: '.swagger-ui .topbar { display: none }',
  swaggerOptions: {
    persistAuthorization: true,
  },
});
```

### Plugin Configuration

```json
{
  "name": "@nestjsvn/swagger-sse/plugin",
  "options": {
    "eventNamingConvention": "kebab-case",
    "introspectComments": true,
    "autoGenerateOperationId": false,
    "customEventMappings": {
      "UserCreatedDto": "user.created"
    }
  }
}
```

## 🔧 Development & Code Quality

This project maintains high code quality standards through comprehensive ESLint and Prettier configurations. Our setup has achieved a **95.7% reduction in lint errors** while maintaining excellent developer experience.

### 📋 Code Quality Overview

The project uses a modern code quality stack:

- **ESLint** with TypeScript support, accessibility rules, and code quality enforcement
- **Prettier** for consistent code formatting across the entire codebase
- **TypeScript** strict mode with comprehensive type checking
- **Accessibility** rules via [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)
- **Automated workflows** with pre-commit hooks and CI integration

#### Quick Script Reference

```bash
# Linting
npm run lint              # Check all files for lint errors
npm run lint:fix          # Fix all auto-fixable lint errors
npm run lint:src          # Check only src/ directory
npm run lint:src:fix      # Fix only src/ directory

# Formatting
npm run format            # Format all files with Prettier
npm run format:check      # Check formatting without changes
npm run format:src        # Format only src/ directory
npm run format:src:check  # Check src/ formatting only

# Combined workflows
npm run quality           # Run lint + format:check + type-check
npm run quality:fix       # Run lint:fix + format + type-check
npm run type-check        # TypeScript compilation check
```

### 🚀 Setup Instructions

After cloning the repository, verify your setup:

```bash
# Install dependencies
npm install

# Verify linting works
npm run lint:src

# Verify formatting works
npm run format:src:check

# Run complete quality check
npm run quality

# Expected output: ✅ All checks should pass
```

### ⚡ Development Workflow

#### Pre-commit Workflow

**Recommended pre-commit checklist:**
- [ ] Run [`npm run quality:fix`](package.json:45) to fix all auto-fixable issues
- [ ] Run [`npm run test`](package.json:31) to ensure all tests pass
- [ ] Review ESLint warnings and address critical issues
- [ ] Verify TypeScript compilation with [`npm run type-check`](package.json:43)

**Quick pre-commit command:**
```bash
npm run quality:fix && npm run test
```

#### Code Review Process

**For reviewers:**
- Focus on logic and architecture rather than formatting
- All formatting issues are automatically handled
- ESLint warnings indicate potential code quality issues
- TypeScript errors must be resolved before merge

**For contributors:**
- Ensure [`npm run quality`](package.json:44) passes before requesting review
- Address any ESLint warnings in your changes
- Maintain test coverage for new functionality

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

Before contributing, please review our [Development & Code Quality](#-development--code-quality) section for setup instructions and workflow guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/dragonxsx/nestjsx-swagger-sse.git
cd swagger-sse

# Install dependencies
npm install

# Verify setup with quality checks
npm run quality

# Run tests
npm run test

# Build the project
npm run build

# Run E2E tests
npm run test:e2e
```

### Contribution Workflow

1. **Setup**: Follow the [Development & Code Quality](#-development--code-quality) setup instructions
2. **Development**: Use the recommended [daily workflow](#daily-development-workflow)
3. **Quality**: Run [`npm run quality:fix`](package.json:45) before committing
4. **Testing**: Ensure all tests pass with [`npm run test`](package.json:31)
5. **Documentation**: Update relevant documentation for new features

### Code Standards

All contributions must meet our code quality standards:
- ✅ ESLint rules must pass (zero errors)
- ✅ Prettier formatting must be consistent
- ✅ TypeScript compilation must succeed
- ✅ Test coverage must be maintained
- ✅ Documentation must be updated for new features

See our [Configuration Details](#️-configuration-details) for specific rules and rationale.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **NestJS Team** - For the excellent framework and SSE support
- **Swagger UI Team** - For the extensible documentation interface
- **Community Contributors** - For feedback, bug reports, and contributions

## 📊 Project Stats

![GitHub stars](https://img.shields.io/github/stars/nestjsx-swagger-sse?style=social)
![GitHub forks](https://img.shields.io/github/forks/nestjsx-swagger-sse?style=social)
![GitHub issues](https://img.shields.io/github/issues/nestjsx-swagger-sse)
![GitHub pull requests](https://img.shields.io/github/issues-pr/nestjsx-swagger-sse)

## 🔗 Related Projects

- **[@nestjs/swagger](https://github.com/nestjs/swagger)** - OpenAPI documentation for NestJS
- **[@nestjs/common](https://github.com/nestjs/nest)** - NestJS framework

---

**Made with ❤️ by the NestJS community**

[Report Bug](https://github.com/dragonxsx/nestjsx-swagger-sse/issues) · [Request Feature](https://github.com/dragonxsx/nestjsx-swagger-sse/issues) · [Documentation](./docs/) · [Examples](./examples/)