npm package: @idealite/web-services
Description: Comprehensive web services library with webhook system and Mux integration
Latest version: 0.0.1

# @idealite/web-services

A comprehensive web services library with advanced webhook system and Mux video integration.

## Features

- 🔗 **Complete Webhook System** - Extensible webhook handling with signature verification
- 🎬 **Mux Integration** - Full support for Mux video service webhooks
- 🔐 **Security First** - Built-in signature verification and timing attack protection
- 📦 **TypeScript Ready** - Full type safety and excellent developer experience
- 🏗️ **NestJS Compatible** - Seamless integration with NestJS applications
- ⚡ **Express Support** - Ready-to-use Express middleware

## Installation

```bash
npm install @idealite/web-services
```

### Dependencies

The package requires these peer dependencies:

```bash
npm install @nestjs/common express @mux/mux-node
```

## Quick Start

### Basic Mux Webhook Setup

```typescript
import { WebhookFactory } from '@idealite/web-services';
import express from 'express';

const app = express();

// Create Mux webhook receiver
const muxReceiver = WebhookFactory.createMuxReceiver('your-webhook-secret');

// Setup raw body middleware for signature verification
app.use('/webhooks/mux', 
  express.raw({ type: 'application/json' }),
  (req, res, next) => {
    (req as any).rawBody = req.body;
    req.body = JSON.parse(req.body.toString());
    next();
  }
);

// Mount webhook endpoint
app.post('/webhooks/mux', muxReceiver.getMiddleware());

app.listen(3000, () => {
  console.log('Server running on port 3000');
});
```

### NestJS Integration

```typescript
import { Module } from '@nestjs/common';
import { WebServicesModule } from '@idealite/web-services';

@Module({
  imports: [WebServicesModule],
  // ... other modules
})
export class AppModule {}
```

### Custom Webhook Handlers

```typescript
import { WebhookFactory } from '@idealite/web-services';

const { receiver } = WebhookFactory.createMuxSetup('your-webhook-secret');

// Add custom handler for video assets
receiver.registerMuxHandler('video.asset.ready', async (payload) => {
  console.log('Video is ready:', payload.data.id);
  
  // Your business logic here
  await processVideo(payload.data);
});

// Handle live streams
receiver.registerMuxHandler('video.live_stream.connected', async (payload) => {
  console.log('Live stream started:', payload.data.id);
  await notifyViewers(payload.data);
});
```
- **HMAC signature verification** for secure webhooks
- **Event handler system** with built-in handlers for common events
- **Factory pattern** for easy component creation
- **TypeScript support** with full type safety

### 🛠 Core Services
- Utility functions for common web service operations
- Email validation, ID generation, and service status monitoring
- NestJS integration ready

## Installation

```bash
npm install @your-org/web-services
```

## Quick Start

### Sending Webhooks

```typescript
import { WebhookFactory } from '@your-org/web-services';

const sender = WebhookFactory.createHttpSender({
  url: 'https://your-endpoint.com/webhook',
  secret: 'your-secret',
  retryAttempts: 3,
});

const result = await sender.send({
  id: 'unique-id',
  timestamp: new Date().toISOString(),
  type: 'user.registered',
  data: { userId: '123', email: 'user@example.com' },
});
```

### Receiving Webhooks

```typescript
import express from 'express';
import { WebhookFactory } from '@your-org/web-services';

const app = express();
app.use(express.json());

const receiver = WebhookFactory.createCompleteReceiver({
  enableLogging: true,
});

app.post('/webhook', receiver.createMiddleware());
```

## Documentation

- [Webhook System Guide](./README-WEBHOOKS.md) - Comprehensive webhook documentation
- [API Reference](#api-reference) - Complete API documentation

## Building

Run `nx build web-services` to build the library.

## Running unit tests

Run `nx test web-services` to execute the unit tests via [Jest](https://jestjs.io).

## Architecture

This library follows enterprise patterns:

- **Abstract classes** for extensibility
- **Factory pattern** for easy object creation
- **Interface segregation** for clean APIs
- **Dependency injection** ready for NestJS
- **Error handling** with proper logging
- **Type safety** throughout

## Contributing

See [CONTRIBUTING.md](../../docs/CONTRIBUTING.md) for contribution guidelines.