saas-backend-kit 1.0.0 → 1.0.1

package/README.md

@@ -1,459 +1,206 @@
-# SaaS Backend Kit
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/saas-backend-kit">
-    <img src="https://img.shields.io/npm/v/saas-backend-kit.svg" alt="npm version">
-  </a>
-  <a href="https://www.npmjs.com/package/saas-backend-kit">
-    <img src="https://img.shields.io/npm/dt/saas-backend-kit.svg" alt="npm downloads">
-  </a>
-  <a href="https://opensource.org/licenses/MIT">
-    <img src="https://img.shields.io/npm/l/saas-backend-kit.svg" alt="MIT License">
-  </a>
-  <a href="https://github.com/yourusername/saas-backend-kit/actions">
-    <img src="https://github.com/yourusername/saas-backend-kit/workflows/CI/badge.svg" alt="CI">
-  </a>
-</p>
-
-> Production-grade modular backend toolkit for building scalable SaaS applications with Node.js
-
-## Features
-
-- **Authentication Module** - JWT authentication, RBAC, Google OAuth
-- **Task Queue System** - Redis-based job queue (BullMQ)
-- **Notification Service** - Email, SMS (Twilio), Webhooks, Slack
-- **Logger** - Structured JSON logging with Pino
-- **Rate Limiting** - Configurable API rate limiting
-- **Config Manager** - Environment variable validation with Zod
-- **API Response Helpers** - Standardized response format
-- **Plugin Architecture** - Modular enable/disable features
-
-## Installation
+<div align="center">
+
+<!-- ANIMATED PIPELINE BANNER -->
+<img src="./saas-banner.svg" width="100%" alt="saas-backend-kit — Production-grade modular backend toolkit for Node.js, Express, Fastify"/>
+
+<br/>
+
+[![npm version](https://img.shields.io/npm/v/saas-backend-kit.svg?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/saas-backend-kit)
+[![npm downloads](https://img.shields.io/npm/dt/saas-backend-kit.svg?style=for-the-badge&logo=npm&logoColor=white&color=26d97f)](https://www.npmjs.com/package/saas-backend-kit)
+[![License: MIT](https://img.shields.io/npm/l/saas-backend-kit.svg?style=for-the-badge&color=3178c6)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+
+</div>
+
+---
+
+## ✨ Features
+
+| Module | Description | Powered By |
+|--------|-------------|------------|
+| 🔐 **Authentication** | JWT auth, RBAC, Google OAuth | jsonwebtoken, Passport |
+| ⚡ **Task Queue** | Redis-based background jobs | BullMQ |
+| 🔔 **Notifications** | Email, SMS, Webhooks, Slack | Nodemailer, Twilio |
+| ☁️ **File Upload** | Images, videos, docs to S3 | AWS SDK v3 |
+| 📋 **Logger** | Structured JSON logging | Pino |
+| 🛡️ **Rate Limiting** | Configurable API rate limiting | express-rate-limit |
+| ⚙️ **Config Manager** | Env variable validation | Zod |
+| 📦 **API Responses** | Standardized response format | Built-in |
+
+---
+
+## 📦 Installation
 
 ```bash
 npm install saas-backend-kit
 ```
 
-## Quick Start
+---
+
+## 🚀 Quick Start
 
 ```typescript
 import express from 'express';
-import { auth, rateLimit, logger, config, queue, notify, response, createApp } from 'saas-backend-kit';
+import { auth, rateLimit, logger, config } from 'saas-backend-kit';
 
 config.load();
 
 const app = express();
 app.use(express.json());
 
-// Initialize auth
-const authMiddleware = auth.initialize({
-  jwtSecret: process.env.JWT_SECRET,
-  jwtExpiresIn: '7d',
-});
-app.use(authMiddleware);
-
-// Apply rate limiting
+app.use(auth.initialize({ jwtSecret: 'your-secret-key' }));
 app.use(rateLimit({ window: '1m', limit: 100 }));
 
-// Protected route
 app.get('/dashboard', auth.requireUser(), (req, res) => {
-  res.success({ message: 'Welcome to your dashboard', user: req.user });
+  res.success({ message: 'Welcome!', user: req.user });
 });
 
 app.listen(3000, () => logger.info('Server running'));
 ```
 
-## Modules
+---
 
-### Authentication
+## 🔐 Authentication
 
 ```typescript
-import { auth } from 'saas-backend-kit';
-
-const authMiddleware = auth.initialize({
+app.use(auth.initialize({
   jwtSecret: 'your-secret-key',
-  jwtExpiresIn: '7d',
-  refreshExpiresIn: '30d',
-});
-
-app.use(authMiddleware);
-
-// Registration
-app.post('/auth/register', async (req, res) => {
-  const { email, password, name } = req.body;
-  const result = await auth().register({ email, password, name });
-  res.success(result.tokens, 'Registration successful');
-});
-
-// Login
-app.post('/auth/login', async (req, res) => {
-  const { email, password } = req.body;
-  const result = await auth().login({ email, password });
-  res.success(result.tokens, 'Login successful');
-});
-
-// Route protection
-app.get('/dashboard', auth.requireUser(), (req, res) => {
-  res.success({ user: req.user });
-});
-
-app.get('/admin', auth.requireRole('admin'), (req, res) => {
-  res.success({ message: 'Admin area' });
-});
-
-app.get('/protected', auth.requirePermission('read'), (req, res) => {
-  res.success({ message: 'Access granted' });
-});
-```
-
-### Role-Based Access Control (RBAC)
-
-```typescript
-import { rbacService } from 'saas-backend-kit/auth';
+  jwtExpiresIn: '7d'
+}));
 
-rbacService.setPermissions({
-  admin: ['*'],
-  manager: ['read', 'write', 'delete:own'],
-  user: ['read', 'write:own'],
-  guest: ['read:public'],
-});
+await auth().register({ email, password, name });
+await auth().login({ email, password });
 
-// Check permissions
-if (rbacService.hasPermission(user.role, 'write:own')) {
-  // Allow action
-}
+auth.requireUser();
+auth.requireRole('admin');
+auth.requirePermission('read');
 ```
 
-### Google OAuth
-
-```typescript
-// Get Google auth URL
-app.get('/auth/google', async (req, res) => {
-  const url = await auth().getGoogleAuthUrl();
-  res.redirect(url);
-});
-
-// Handle callback
-app.get('/auth/google/callback', async (req, res) => {
-  const { code } = req.query;
-  const result = await auth().handleGoogleCallback(code as string);
-  res.success(result.tokens);
-});
-```
+---
 
-### Task Queue
+## ⚡ Task Queue
 
 ```typescript
 import { queue } from 'saas-backend-kit';
 
-// Create a queue
-const emailQueue = queue.create('email', {
-  defaultJobOptions: {
-    attempts: 3,
-    backoff: { type: 'exponential', delay: 1000 },
-  },
-});
-
-// Add jobs
-await emailQueue.add('sendWelcomeEmail', { userId: '123', email: 'user@example.com' });
+const emailQueue = queue.create('email');
+await emailQueue.add('sendEmail', { to: 'user@example.com' });
 
-// Delayed job
-await emailQueue.add('sendReminder', { userId: '123' }, { delay: 3600000 });
-
-// Process jobs
 queue.process('email', async (job) => {
-  logger.info(`Processing ${job.name}`, { jobId: job.id });
-  await notify.email({
-    to: job.data.email,
-    subject: 'Welcome!',
-    template: 'welcome',
-    templateData: { name: 'User' },
-  });
-  return { sent: true };
+  await notify.email({ to: job.data.to, subject: 'Hello' });
 }, { concurrency: 5 });
 ```
 
-### Notifications
+---
+
+## 🔔 Notifications
 
 ```typescript
 import { notify } from 'saas-backend-kit';
 
-// Email
-await notify.email({
-  to: 'user@example.com',
-  subject: 'Welcome',
-  template: 'welcome',
-  templateData: { name: 'John', appName: 'MyApp' },
-});
+await notify.email({ to: 'user@example.com', subject: 'Welcome' });
+await notify.sms({ to: '+1234567890', message: 'Your code is 123456' });
+await notify.slack({ text: 'New user registered!' });
+```
 
-// SMS
-await notify.sms({
-  to: '+1234567890',
-  message: 'Your verification code is 123456',
-});
+---
 
-// Webhook
-await notify.webhook({
-  url: 'https://api.example.com/webhook',
-  method: 'POST',
-  body: { event: 'user.created', data: { id: '123' } },
-});
+## ☁️ File Upload (S3)
 
-// Slack
-await notify.slack({
-  text: 'New user registered!',
-  blocks: [
-    {
-      type: 'section',
-      text: { type: 'mrkdwn', text: 'New user registered: *john@example.com*' }
-    }
-  ]
+```typescript
+import { upload } from 'saas-backend-kit';
+
+upload.initialize({
+  region: 'us-east-1',
+  accessKeyId: 'your-access-key',
+  secretAccessKey: 'your-secret-key',
+  bucket: 'your-bucket-name'
 });
+
+const result    = await upload.file(fileBuffer, { key: 'documents/file.pdf' });
+const image     = await upload.image(fileBuffer, 'photo.jpg');
+const video     = await upload.video(fileBuffer, 'video.mp4');
+const signedUrl = await upload.getSignedUrl('path/to/file');
+
+await upload.delete('path/to/file');
 ```
 
-### Logger
+---
+
+## 📋 Logger
 
 ```typescript
 import { logger } from 'saas-backend-kit';
 
 logger.info('Server started', { port: 3000 });
-logger.error('Connection failed', { error: err.message });
-logger.warn('Rate limit approaching', { ip: req.ip });
+logger.error('Failed', { error: err.message });
 
-// Child logger
-const childLogger = logger.child({ module: 'auth' });
-childLogger.info('User logged in', { userId: '123' });
+const child = logger.child({ module: 'auth' });
+child.info('User logged in');
 ```
 
-### Rate Limiting
-
-```typescript
-import { rateLimit } from 'saas-backend-kit';
-
-// Global rate limit
-app.use(rateLimit({
-  window: '1m',
-  limit: 100,
-}));
+---
 
-// Per-route rate limit
-app.get('/api/expensive', rateLimit({ window: '1m', limit: 10 }), (req, res) => {
-  res.success({ data: 'expensive operation' });
-});
+## 🛡️ Rate Limiting
 
-// Custom key generator
-app.use(rateLimit({
-  window: '1m',
-  limit: 100,
-  keyGenerator: (req) => req.user?.id || req.ip,
-}));
+```typescript
+app.use(rateLimit({ window: '1m', limit: 100 }));
+app.use(rateLimit({ window: '1m', limit: 10, keyGenerator: (req) => req.user?.id }));
 ```
 
-### Config Manager
+---
 
-```typescript
-import { config } from 'saas-backend-kit';
+## ⚙️ Config
 
-// Load and validate env vars
+```typescript
 config.load();
-
-// Get values
-const port = config.int('PORT');
+const port         = config.int('PORT');
 const isProduction = config.isProduction();
-const dbUrl = config.get('DATABASE_URL');
-
-// Custom schema
-const customConfig = config.create({
-  schema: z.object({
-    API_KEY: z.string(),
-    MAX_CONNECTIONS: z.number().default(100),
-  }),
-  validate: true,
-});
 ```
 
-### API Response Helpers
-
-```typescript
-// Success responses
-res.success({ user }, 'User found');
-res.created({ id: '123' }, 'User created');
-res.updated(user, 'User updated');
-res.deleted Paginated response('User deleted');
-
-//
-res.pag, limit, total);
-
-// Error responses
-inated(users, pageres.badInvalid inputauthorized('Please');
-res.unRequest(' login');
-res.forbidden('Access denied');
-res.notFound('User not found');
-res failed', { fields.validationError('Validation: errors('Something });
-res.internalError went wrong');
-```
+---
 
-### Plugin Architecture
+## 📦 API Responses
 
 ```typescript
-import { createApp, Plugin } from 'saas-backend-kit';
-
-const myPlugin: Plugin = {
-  name: 'my-plugin',
-  initialize: (app) => {
-    console.log('Plugin initialized');
-  },
-};
-
-const app = createApp({
-  auth: true,
-  queue: { redisUrl: 'redis://localhost:6379' },
-  notifications: true,
-  rateLimit: { window: '1m', limit: 100 },
-})
-.use(myPlugin);
-
-await app.initialize(expressApp);
+res.success({ user });
+res.created(user, 'Created');
+res.paginated(users, page, limit, total);
+res.error('Error message');
 ```
 
-## Framework Support
-
-### Express
-
-All examples above use Express. The library automatically extends the Response object with helper methods.
-
-### Fastify
-
-```typescript
-import Fastify from 'fastify';
-import { registerAuthPlugin, registerRateLimitPlugin, auth } from 'saas-backend-kit';
-
-const fastify = Fastify();
-
-fastify.register(registerAuthPlugin, { authService: auth() });
-fastify.register(registerRateLimitPlugin, { window: '1m', limit: 100 });
-
-fastify.get('/dashboard', { preHandler: [fastify.authenticate] }, async (request, reply) => {
-  return { user: request.user };
-});
-```
+---
 
-## Environment Variables
+## 🔧 Environment Variables
 
 ```env
 NODE_ENV=development
 PORT=3000
-
-# JWT
-JWT_SECRET=your-secret-key-min-32-chars
-JWT_EXPIRES_IN=7d
-JWT_REFRESH_SECRET=your-refresh-secret
-JWT_REFRESH_EXPIRES_IN=30d
-
-# Redis
+JWT_SECRET=your-secret-key
 REDIS_URL=redis://localhost:6379
 
-# Google OAuth
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
-GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google/callback
-
-# SMTP
-SMTP_HOST=smtp.example.com
-SMTP_PORT=587
-SMTP_USER=
-SMTP_PASS=
-SMTP_FROM=noreply@domain.com
-
-# Twilio
-TWILIO_ACCOUNT_SID=
-TWILIO_AUTH_TOKEN=
-TWILIO_PHONE_NUMBER=
-
-# Slack
-SLACK_WEBHOOK_URL=
-
-# Rate Limiting
-RATE_LIMIT_WINDOW=1m
-RATE_LIMIT_LIMIT=100
-
-# Logger
-LOG_LEVEL=info
+# AWS S3
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_S3_BUCKET=your-bucket-name
 ```
 
-## Project Structure
-
-```
-saas-backend-kit/
-├── src/
-│   ├── auth/           # Authentication module
-│   │   ├── types.ts
-│   │   ├── jwt.ts
-│   │   ├── rbac.ts
-│   │   ├── oauth.ts
-│   │   ├── express.ts
-│   │   ├── fastify.ts
-│   │   └── index.ts
-│   ├── queue/         # Task queue (BullMQ)
-│   ├── notifications/ # Email, SMS, Webhooks, Slack
-│   ├── logger/        # Pino logger
-│   ├── rate-limit/    # Rate limiting
-│   ├── config/        # Config manager
-│   ├── response/      # Response helpers
-│   ├── utils/         # Utilities
-│   ├── plugin.ts      # Plugin architecture
-│   └── index.ts       # Main exports
-├── examples/
-│   └── express/
-├── package.json
-├── tsconfig.json
-└── tsup.config.ts
-```
-
-## TypeScript
-
-This library is written in TypeScript and provides full type definitions out of the box.
-
-## Tree Shaking
-
-All modules are exported separately for optimal tree shaking:
-
-```typescript
-import { auth } from 'saas-backend-kit/auth';
-import { queue } from 'saas-backend-kit/queue';
-import { logger } from 'saas-backend-kit/logger';
-```
-
-## Testing
-
-```bash
-npm test
-npm run test:watch
-```
-
-## Linting
-
-```bash
-npm run lint
-npm run typecheck
-```
+---
 
-## Building
+## 🤝 Contributing
 
-```bash
-npm run build
-```
+Contributions, issues, and feature requests are welcome! Feel free to open a PR or issue.
 
-## License
-
-MIT License - see [LICENSE](LICENSE) for details.
+---
 
-## Contributing
+<div align="center">
 
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
+**Built with ❤️ by [Ashish Kumar Maurya](https://github.com/AshishK-M)**  
+Senior Full-Stack Developer · Dubai, UAE  
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-0A66C2?style=flat-square&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/ashish-kumar-maurya-fullstack/)
 
----
+<sub>saas-backend-kit · MIT License · Node.js · Express · Fastify · TypeScript · BullMQ · AWS S3 · Pino · Zod</sub>
 
-Built with ❤️ for the SaaS community
-# saas-backend-kit
-
+</div>

package/copy-dts.js

@@ -214,6 +214,64 @@ export declare class ResponseHelper {
 }
 
 export declare const response: typeof ResponseHelper;
+`,
+  'upload/index.d.ts': `export interface S3Config {
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  bucket: string;
+  endpoint?: string;
+  forcePathStyle?: boolean;
+}
+
+export interface UploadOptions {
+  key?: string;
+  contentType?: string;
+  expiresIn?: number;
+  metadata?: Record<string, string>;
+}
+
+export interface UploadResult {
+  key: string;
+  url: string;
+  bucket: string;
+  contentType?: string;
+  size?: number;
+}
+
+export interface SignedUrlOptions {
+  expiresIn?: number;
+}
+
+export interface FileObject {
+  key: string;
+  lastModified?: Date;
+  size?: number;
+  contentType?: string;
+}
+
+export declare const upload: {
+  initialize: (config: S3Config) => void;
+  file: (file: Buffer | Uint8Array | string, options?: UploadOptions) => Promise<UploadResult>;
+  image: (file: Buffer | Uint8Array | string, filename: string, options?: UploadOptions) => Promise<UploadResult>;
+  video: (file: Buffer | Uint8Array | string, filename: string, options?: UploadOptions) => Promise<UploadResult>;
+  delete: (key: string) => Promise<void>;
+  getSignedUrl: (key: string, options?: SignedUrlOptions) => Promise<string>;
+  getPublicUrl: (key: string) => Promise<string>;
+  listFiles: (prefix?: string, maxKeys?: number) => Promise<FileObject[]>;
+};
+
+export declare class S3Service {
+  initialize(config: S3Config): void;
+  isInitialized(): boolean;
+  upload(file: Buffer | Uint8Array | string, options?: UploadOptions): Promise<UploadResult>;
+  uploadImage(file: Buffer | Uint8Array | string, filename: string, options?: UploadOptions): Promise<UploadResult>;
+  uploadVideo(file: Buffer | Uint8Array | string, filename: string, options?: UploadOptions): Promise<UploadResult>;
+  delete(key: string): Promise<void>;
+  getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+  getPublicUrl(key: string): Promise<string>;
+  listFiles(prefix?: string, maxKeys?: number): Promise<FileObject[]>;
+}
 `,
   'index.d.ts': `export * from './auth';
 export * from './queue';
@@ -222,6 +280,7 @@ export * from './logger';
 export * from './rate-limit';
 export * from './config';
 export * from './response';
+export * from './upload';
 
 export interface AppOptions {
   framework?: 'express' | 'fastify';

package/dist/auth/index.js

@@ -130,7 +130,12 @@ var envSchema = zod.z.object({
   SLACK_WEBHOOK_URL: zod.z.string().optional(),
   RATE_LIMIT_WINDOW: zod.z.string().default("1m"),
   RATE_LIMIT_LIMIT: zod.z.string().default("100"),
-  LOG_LEVEL: zod.z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info")
+  LOG_LEVEL: zod.z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info"),
+  AWS_REGION: zod.z.string().default("us-east-1"),
+  AWS_ACCESS_KEY_ID: zod.z.string().optional(),
+  AWS_SECRET_ACCESS_KEY: zod.z.string().optional(),
+  AWS_S3_BUCKET: zod.z.string().optional(),
+  AWS_ENDPOINT: zod.z.string().optional()
 });
 var ConfigManager = class {
   config = null;