npm package: @harmonixjs/express
Description: Express plugin for Harmonix Discord framework - Simple & Flexible
Author: Maxence Bessi
Latest version: 1.0.0

# @harmonixjs/express

A powerful Express-based HTTP API plugin for the Harmonix Discord framework.  
This plugin provides decorators, routing, authentication, and direct bot access — allowing developers to build REST APIs that seamlessly integrate with their Discord bot logic.

---

## 🚀 Features

- ✔️ Express integration with automatic route binding  
- ✔️ Decorator-based controllers & routes (`@Controller()`, `@Get()`, `@Post()`, etc.)  
- ✔️ Decorator-based property injection (`@Inject("...")`) to automatically inject values from ExpressPluginConfig or the bot instance
- ✔️ Parameter injection (`@Query()`, `@Params()`, `@Body()`, `@Headers()`, `@Req()`, `@Res()`, `@Bot()`)  
- ✔️ JWT authentication support (`@RequireAuth()`)  
- ✔️ Custom middlewares + per-route middlewares  
- ✔️ CORS configuration  
- ✔️ Session support (cookies)  
- ✔️ Auto-loading of controllers from a directory  
- ✔️ Direct access to the Harmonix bot instance in any route  
- ✔️ Fully type-safe with TypeScript  

---

## 📦 Installation

```bash
npm install @harmonixjs/express express jsonwebtoken cookie-parser
npm install --save-dev @types/express @types/jsonwebtoken @types/cookie-parser
```

## ✨ Quick Start

```js
import { Harmonix } from '@harmonixjs/core';
import { ExpressPlugin } from '@harmonixjs/express';

const bot = new Harmonix({
  bot: {
    token: "YOUR_BOT_TOKEN",
    id: "YOUR_BOT_CLIENT_ID"
  }
  intents: [...],
  plugins: [
    new ExpressPlugin({
      port: 3000,
      controllersPath: './controllers'
    })
  ]
});

bot.start();
```

## 📁 Example Project Structure

```pgsql
project/
├── controllers/
│   ├── UserController.ts
│   └── AuthController.ts
├── src/
│   └── index.ts
└── package.json
```

## 🧩 Creating a Controller

```ts
// controllers/UserController.ts
import { Controller, Get, Params, Bot } from '@harmonixjs/express';
import { Harmonix } from '@harmonixjs/core';

@Controller({ path: '/users' })
export class UserController {

  @Get('/:id')
  async getUser(@Params('id') id: string, @Bot() bot: Harmonix) {
    const user = await bot.users.fetch(id);
    return user ? { id: user.id, username: user.username } : { error: 'User not found' };
  }

  @Get('/search')
  async search(@Query('q') query: string, @Bot() bot: Harmonix) {
    const results = bot.users.cache.filter(u =>
      u.username.toLowerCase().includes(query.toLowerCase())
    );

    return results.map(u => ({
      id: u.id,
      username: u.username,
      tag: u.tag
    }));
  }
}
```

🔧 Auto-loading Controllers
Enable automatic controller loading:

```ts
new ExpressPlugin({
  controllersPath: './controllers'
});
```

All `.ts`/`.js` files inside the folder will be scanned and registered.

## ⚙️ Configuration Options

| Option             | Type                      | Description                                 |
|--------------------|---------------------------|---------------------------------------------|
| `port`             | `number`                  | Server port (default: `3000`)               |
| `cors`             | `boolean` or `object`     | Enable and configure CORS                   |
| `jwt`              | `JwtConfig`               | Enable JWT authentication                   |
| `controllersPath`  | `string`                  | Directory to auto-load controllers from     |
| `middlewares`      | `RequestHandler[]`        | Global middlewares                          |
| `rateLimit`        | `object`                  | Enable rate limit on each routes            |

---

## 🛡️ Security

### Rate Limiting Example

```ts
new ExpressPlugin({
  rateLimit: {
    windowMs: 15 * 60 * 1000,
    max: 100
  }
});
```

### CORS Example

```ts
new ExpressPlugin({
  cors: {
    origin: 'https://yourdomain.com',
    credentials: true
  }
});
```

## 📜 License

MIT © HarmonixJS