@rabstack/rab-api 1.0.1

package/README.md

@@ -0,0 +1,393 @@
+# rab-api
+
+A TypeScript REST API framework built on Express.js with decorator-based routing, dependency injection, and built-in validation.
+
+## Features
+
+- 🎯 Decorator-based routing with TypeScript
+- 🔒 Built-in JWT authentication
+- ✅ Request validation with Joi schemas
+- 💉 Dependency injection (TypeDI)
+- 🔐 Role-based access control
+- 📝 Full TypeScript type safety
+- 🚀 Production-ready
+
+## Installation
+
+```bash
+npm install rab-api
+```
+
+**Peer dependencies:**
+```bash
+npm install express joi typedi reflect-metadata jsonwebtoken compose-middleware
+```
+
+## Quick Start
+
+**1. Create a controller:**
+
+```typescript
+import { Get, RabApiGet, GetController } from 'rab-api';
+
+type ControllerT = GetController<{ status: string }>;
+
+@Get('/health')
+export class HealthCheck implements RabApiGet<ControllerT> {
+  handler: ControllerT['request'] = async () => {
+    return { status: 'ok' };
+  };
+}
+```
+
+**2. Bootstrap your app:**
+
+```typescript
+import { RabApi } from 'rab-api';
+import express from 'express';
+
+const app = RabApi.createApp({
+  auth: {
+    jwt: {
+      secret_key: process.env.JWT_SECRET!,
+      algorithms: ['HS256'],
+    },
+  },
+});
+
+app.use(express.json());
+
+app.route({
+  basePath: '/api',
+  controllers: [HealthCheck],
+});
+
+app.listen(3000);
+```
+
+## Core Concepts
+
+### Controllers
+
+Controllers handle HTTP requests using decorators:
+
+```typescript
+import { Post, RabApiPost, PostController } from 'rab-api';
+import * as Joi from 'joi';
+
+type CreateUserBody = { name: string; email: string };
+type UserResponse = { id: string; name: string; email: string };
+type ControllerT = PostController<CreateUserBody, UserResponse>;
+
+const schema = Joi.object({
+  name: Joi.string().required(),
+  email: Joi.string().email().required(),
+});
+
+@Post('/users', { bodySchema: schema })
+export class CreateUser implements RabApiPost<ControllerT> {
+  handler: ControllerT['request'] = async (request) => {
+    return { id: '1', ...request.body };
+  };
+}
+```
+
+**Available decorators:**
+- `@Get(path, options?)` - GET requests
+- `@Post(path, options?)` - POST requests
+- `@Put(path, options?)` - PUT requests
+- `@Patch(path, options?)` - PATCH requests
+- `@Delete(path, options?)` - DELETE requests
+
+### Dependency Injection
+
+Controllers support constructor injection via TypeDI:
+
+```typescript
+import { Injectable } from 'rab-api';
+
+@Injectable()
+class UserService {
+  async findAll() {
+    return [];
+  }
+}
+
+@Get('/users')
+export class ListUsers implements RabApiGet<ControllerT> {
+  constructor(private userService: UserService) {}
+
+  handler: ControllerT['request'] = async () => {
+    return await this.userService.findAll();
+  };
+}
+```
+
+### Routing
+
+Group related controllers with routers:
+
+```typescript
+app.route({
+  basePath: '/users',
+  controllers: [ListUsers, CreateUser, UpdateUser, DeleteUser],
+});
+
+// Nested routes
+app.route({
+  basePath: '/users',
+  controllers: [
+    ListUsers,
+    RabApi.createRouter({
+      basePath: '/:userId/posts',
+      controllers: [ListPosts, CreatePost],
+    }),
+  ],
+});
+```
+
+## Validation
+
+### Request Body
+
+```typescript
+const createProductSchema = Joi.object({
+  name: Joi.string().min(3).required(),
+  price: Joi.number().positive().required(),
+});
+
+@Post('/products', { bodySchema: createProductSchema })
+export class CreateProduct implements RabApiPost<ControllerT> {
+  handler: ControllerT['request'] = async (request) => {
+    const { name, price } = request.body; // validated
+    return { id: '1', name, price };
+  };
+}
+```
+
+### Query Parameters
+
+```typescript
+const listSchema = Joi.object({
+  page: Joi.number().integer().min(1).default(1),
+  limit: Joi.number().integer().min(1).max(100).default(10),
+});
+
+@Get('/products', { querySchema: listSchema })
+export class ListProducts implements RabApiGet<ControllerT> {
+  handler: ControllerT['request'] = async (request) => {
+    const { page, limit } = request.query; // validated
+    return { items: [], page, limit };
+  };
+}
+```
+
+## Authentication
+
+### JWT Setup
+
+```typescript
+const app = RabApi.createApp({
+  auth: {
+    jwt: {
+      secret_key: process.env.JWT_SECRET!,
+      algorithms: ['HS256'],
+    },
+  },
+});
+```
+
+### Protected Routes
+
+Routes are protected by default. Make a route public:
+
+```typescript
+@Post('/auth/login', { isProtected: false })
+export class Login implements RabApiPost<ControllerT> {
+  // Public endpoint
+}
+```
+
+Access authenticated user:
+
+```typescript
+@Get('/profile')
+export class GetProfile implements RabApiGet<ControllerT> {
+  handler: ControllerT['request'] = async (request) => {
+    const user = request.auth; // JWT payload
+    return { userId: user.userId };
+  };
+}
+```
+
+## Authorization
+
+Use permission-based access control:
+
+```typescript
+@Post('/admin/users', { permission: 'canCreateUser' })
+export class CreateUser implements RabApiPost<ControllerT> {
+  // Only users with 'canCreateUser' permission
+}
+```
+
+Integrate with `@softin/rab-access`:
+
+```typescript
+import { Rab } from '@softin/rab-access';
+
+const permissions = Rab.schema({
+  canCreateUser: [Rab.grant('admin'), Rab.grant('superAdmin')],
+  canDeleteUser: [Rab.grant('superAdmin')],
+});
+```
+
+## Error Handling
+
+Built-in exceptions:
+
+```typescript
+import {
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  ConflictException,
+} from 'rab-api';
+
+@Get('/users/:id')
+export class GetUser implements RabApiGet<ControllerT> {
+  handler: ControllerT['request'] = async (request) => {
+    const user = await findUser(request.params.id);
+    if (!user) throw new NotFoundException('User not found');
+    return user;
+  };
+}
+```
+
+Custom error handler:
+
+```typescript
+const app = RabApi.createApp({
+  errorHandler: (err, req, res, next) => {
+    if (err instanceof RabApiError) {
+      return res.status(err.statusCode).json({ error: err.message });
+    }
+    return res.status(500).json({ error: 'Internal error' });
+  },
+});
+```
+
+## Middleware
+
+Apply middleware at different levels:
+
+```typescript
+// Route level
+@Get('/users', { pipes: [loggerMiddleware] })
+export class ListUsers {}
+
+// Router level
+app.route({
+  basePath: '/api',
+  pipes: [corsMiddleware, loggerMiddleware],
+  controllers: [/* ... */],
+});
+
+// Conditional
+const conditionalAuth = (route) => {
+  return route.isProtected ? [authMiddleware] : [];
+};
+
+app.route({
+  pipes: [conditionalAuth],
+  controllers: [/* ... */],
+});
+```
+
+## Advanced Features
+
+### Controller Type Helpers
+
+```typescript
+// Type helpers for controllers
+PostController<TBody, TResponse, TParams?, TUser?, TQuery?>
+GetController<TResponse, TQuery?, TParams?, TUser?>
+PutController<TBody, TResponse, TParams?, TUser?, TQuery?>
+PatchController<TBody, TResponse, TParams?, TUser?, TQuery?>
+DeleteController<TParams?, TUser?>
+
+// Interface implementations
+RabApiPost<T> | AtomApiPost<T>
+RabApiGet<T> | AtomApiGet<T>
+RabApiPut<T> | AtomApiPut<T>
+RabApiPatch<T> | AtomApiPatch<T>
+RabApiDelete<T> | AtomApiDelete<T>
+```
+
+## Route Options
+
+```typescript
+interface RouteOptions {
+  bodySchema?: Joi.ObjectSchema;    // Body validation
+  querySchema?: Joi.ObjectSchema;   // Query validation
+  isProtected?: boolean;            // JWT required (default: true)
+  permission?: string;              // Permission name
+  pipes?: Function[];               // Middleware
+  excludeFromDocs?: boolean;        // Hide from OpenAPI
+  tags?: string[];                  // OpenAPI tags
+}
+```
+
+## Complete Example
+
+```typescript
+import { Get, Post, Put, Delete, RabApi, Injectable } from 'rab-api';
+import * as Joi from 'joi';
+
+// Service
+@Injectable()
+class ProductService {
+  async findAll() { return []; }
+  async create(data: any) { return { id: '1', ...data }; }
+}
+
+// Controllers
+const createSchema = Joi.object({
+  name: Joi.string().required(),
+  price: Joi.number().required(),
+});
+
+@Get('/')
+class ListProducts {
+  constructor(private service: ProductService) {}
+  handler = async () => await this.service.findAll();
+}
+
+@Post('/', { bodySchema: createSchema })
+class CreateProduct {
+  constructor(private service: ProductService) {}
+  handler = async (req) => await this.service.create(req.body);
+}
+
+// App
+const app = RabApi.createApp({
+  auth: { jwt: { secret_key: 'secret', algorithms: ['HS256'] } },
+});
+
+app.use(express.json());
+app.route({
+  basePath: '/products',
+  controllers: [ListProducts, CreateProduct],
+});
+
+app.listen(3000);
+```
+
+## License
+
+MIT © Softin Hub
+
+## Support
+
+Email: softin.developer@gmail.com

package/index.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";