push

src/app.ts

@@ -18,29 +18,23 @@ import adminRoutes from './routes/adminRoutes';
 
 const app: Application = express();
 
-// Security middleware
 app.use(helmet());
-// CORS configuration - allow Hugging Face Spaces and custom origins
 app.use(cors({
   origin: process.env.CORS_ORIGIN || process.env.FRONTEND_URL || '*',
   credentials: true,
 }));
 
-// Body parsing
 app.use(express.json({ limit: '10mb' }));
 app.use(express.urlencoded({ extended: true, limit: '10mb' }));
-// Note: File uploads are handled by multer in route-specific middleware
 
-// Rate limiting
 const limiter = rateLimit({
-  windowMs: 15 * 60 * 1000, // 15 minutes
-  max: 100, // Limit each IP to 100 requests per windowMs
+  windowMs: 15 * 60 * 1000,
+  max: 100,
   message: 'Too many requests from this IP, please try again later.',
 });
 
 app.use('/api/', limiter);
 
-// Root endpoint
 app.get('/', (req, res) => {
   res.json({
     name: 'Zurri API',
@@ -57,20 +51,20 @@ app.get('/', (req, res) => {
   });
 });
 
-// Health check
 app.get('/health', (req, res) => {
   res.json({ status: 'ok', timestamp: new Date().toISOString() });
 });
 
-// Docs - Swagger UI
 app.use('/docs', swaggerUi.serve);
 app.get('/docs', swaggerUi.setup(swaggerSpec, {
   explorer: true,
   customCss: '.swagger-ui .topbar { display: none }',
   customSiteTitle: 'Zurri API Documentation',
+  swaggerOptions: {
+    persistAuthorization: true,
+  },
 }));
 
-// API routes
 app.use('/api/auth', authRoutes);
 app.use('/api/creator-auth', creatorAuthRoutes);
 app.use('/api/users', userRoutes);
@@ -81,12 +75,10 @@ app.use('/api/chat', chatRoutes);
 app.use('/api/subscriptions', subscriptionRoutes);
 app.use('/api/wallet', walletRoutes);
 
-// 404 handler
 app.use((req, res) => {
   res.status(404).json({ error: 'Route not found' });
 });
 
-// Error handler
 app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
   console.error('Error:', err);
   res.status(500).json({

src/config/database.ts

@@ -12,7 +12,7 @@ export const AppDataSource = new DataSource({
   type: 'postgres',
   url: process.env.DATABASE_URL,
   entities: [Agent, User, Subscription, ApiKey, ChatMessage, Wallet, Transaction, CreatorProfile],
-  synchronize: process.env.DB_SYNCHRONIZE === 'true' || process.env.NODE_ENV !== 'production', // Auto-sync if enabled or in dev
+  synchronize: process.env.DB_SYNCHRONIZE === 'true' || process.env.NODE_ENV !== 'production',
   logging: process.env.NODE_ENV === 'development',
   extra: {
     ssl: process.env.DATABASE_URL?.includes('render.com') || process.env.DATABASE_URL?.includes('dpg-')

src/controllers/walletController.ts

@@ -8,14 +8,17 @@ import { TransactionStatus } from '../entities/Transaction';
 import crypto from 'crypto';
 
 const walletService = new WalletService();
-const paystackService = new PaystackService();
+let paystackService: PaystackService | null = null;
+const getPaystackService = () => {
+  if (!paystackService) {
+    paystackService = new PaystackService();
+  }
+  return paystackService;
+};
 const exchangeRateService = new ExchangeRateService();
 const userRepository = AppDataSource.getRepository(User);
 
 export class WalletController {
-  /**
-   * Get user's wallet balance
-   */
   async getWallet(req: Request, res: Response) {
     try {
       const userId = (req as any).user.id;
@@ -36,14 +39,10 @@ export class WalletController {
     }
   }
 
-  /**
-   * Initiate wallet funding (purchase points)
-   * Returns Paystack initialization data for frontend widget
-   */
   async fundWallet(req: Request, res: Response) {
     try {
       const userId = (req as any).user.id;
-      const { amount } = req.body; // Amount in Naira (NGN)
+      const { amount } = req.body;
 
       if (!amount || amount <= 0) {
         return res.status(400).json({ error: 'Invalid amount. Must be greater than 0' });
@@ -55,19 +54,16 @@ export class WalletController {
         return res.status(404).json({ error: 'User not found' });
       }
 
-      // Convert Naira to points using current exchange rate
       const pointValueUsd = parseFloat(process.env.POINT_VALUE_USD || '0.05');
-      const fx = await exchangeRateService.getNGNToUSDRate(); // Dynamic rate
+      const fx = await exchangeRateService.getNGNToUSDRate();
       const amountInDollars = amount / fx;
       const points = Math.round(amountInDollars / pointValueUsd);
 
-      // Generate unique payment reference
       const paymentReference = `wallet_${userId}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
 
-      // Initialize Paystack transaction
-      const paymentData = await paystackService.initializeTransaction({
+      const paymentData = await getPaystackService().initializeTransaction({
         email: user.email,
-        amount: Math.round(amount * 100), // Convert to kobo (smallest NGN unit)
+        amount: Math.round(amount * 100),
         reference: paymentReference,
         metadata: {
           userId: userId,
@@ -80,7 +76,7 @@ export class WalletController {
 
       // Return payment info for frontend
       res.json({
-        publicKey: paystackService.getPublicKey(),
+        publicKey: getPaystackService().getPublicKey(),
         reference: paymentData.reference,
         authorization_url: paymentData.authorization_url,
         access_code: paymentData.access_code,
@@ -112,7 +108,7 @@ export class WalletController {
       }
 
       // Verify with Paystack
-      const verification = await paystackService.verifyTransaction(reference);
+      const verification = await getPaystackService().verifyTransaction(reference);
 
       // Check if transaction was successful
       if (verification.status !== 'success') {
@@ -226,7 +222,7 @@ export class WalletController {
 
         // Verify with Paystack API (server-to-server verification)
         try {
-          const verification = await paystackService.verifyTransaction(reference);
+          const verification = await getPaystackService().verifyTransaction(reference);
           if (verification.status !== 'success') {
             console.error('Paystack verification failed:', verification);
             return res.status(400).json({ error: 'Transaction verification failed' });
@@ -291,7 +287,7 @@ export class WalletController {
 
       // Verify with Paystack
       try {
-        const verification = await paystackService.verifyTransaction(reference);
+        const verification = await getPaystackService().verifyTransaction(reference);
 
         // Check if transaction was successful
         if (verification.status !== 'success') {

src/docs/swagger.ts

@@ -3,18 +3,37 @@ import path from 'path';
 import fs from 'fs';
 
 // Swagger JSDoc needs the source TypeScript files (not compiled JS) to read JSDoc comments
-// In production, we copy the source route files to the container
-const routesPath = path.join(__dirname, '../routes/*.ts');
+// When running from dist/, we need to look for src/ at the project root
+// When running from src/, we use relative path
+
+// Check if we're running from dist (compiled) or src (development)
+const isRunningFromDist = __dirname.includes('dist');
+const projectRoot = isRunningFromDist 
+  ? path.resolve(__dirname, '../..')  // Go up from dist/docs to project root
+  : path.resolve(__dirname, '..');     // Go up from src/docs to project root
+
+// Always use source TypeScript files from src/routes
+const routesPath = path.join(projectRoot, 'src/routes/*.ts');
+
+console.log(`🔍 Swagger looking for routes at: ${routesPath}`);
+console.log(`📂 Running from: ${isRunningFromDist ? 'dist' : 'src'}`);
+console.log(`📂 Project root: ${projectRoot}`);
 
 // Check if route files exist (for debugging)
 try {
-  const routesDir = path.join(__dirname, '../routes');
+  const routesDir = path.join(projectRoot, 'src/routes');
   if (fs.existsSync(routesDir)) {
     const files = fs.readdirSync(routesDir);
     console.log(`📁 Found ${files.length} route files in ${routesDir}`);
+    const tsFiles = files.filter(f => f.endsWith('.ts'));
+    console.log(`📄 TypeScript route files: ${tsFiles.length}`);
   } else {
     console.warn(`⚠️  Routes directory not found: ${routesDir}`);
   }
+  
+  // Also check if the glob pattern resolves correctly
+  const testPattern = path.join(projectRoot, 'src/routes/*.ts');
+  console.log(`🔍 Using pattern: ${testPattern}`);
 } catch (error) {
   console.warn('⚠️  Could not check routes directory:', error);
 }
@@ -41,6 +60,86 @@ export const swaggerSpec = swaggerJSDoc({
           bearerFormat: 'JWT',
         },
       },
+      schemas: {
+        Agent: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'string',
+              format: 'uuid',
+            },
+            name: {
+              type: 'string',
+              example: 'PixelPainter',
+            },
+            description: {
+              type: 'string',
+              example: 'I turn prompts into AI art!',
+            },
+            endpoint: {
+              type: 'string',
+              format: 'uri',
+              example: 'https://api.pixelpainter.ai/run',
+            },
+            avatar: {
+              type: 'string',
+              format: 'uri',
+              nullable: true,
+              description: 'IPFS gateway URL for avatar image',
+            },
+            category: {
+              type: 'string',
+              example: 'image generation',
+            },
+            reputation: {
+              type: 'number',
+              format: 'float',
+              example: 4.8,
+            },
+            capabilities: {
+              type: 'array',
+              items: {
+                type: 'string',
+              },
+              example: ['text-to-image', 'image-editing'],
+            },
+            pointsPerTask: {
+              type: 'number',
+              format: 'float',
+              example: 10,
+            },
+            status: {
+              type: 'string',
+              enum: ['pending', 'approved', 'rejected', 'suspended'],
+            },
+            usageCount: {
+              type: 'integer',
+              example: 0,
+            },
+            rating: {
+              type: 'number',
+              format: 'float',
+              nullable: true,
+            },
+            ratingCount: {
+              type: 'integer',
+              example: 0,
+            },
+            creatorId: {
+              type: 'string',
+              format: 'uuid',
+            },
+            createdAt: {
+              type: 'string',
+              format: 'date-time',
+            },
+            updatedAt: {
+              type: 'string',
+              format: 'date-time',
+            },
+          },
+        },
+      },
     },
     security: [{ bearerAuth: [] }],
   },

src/middlewares/auth.ts

@@ -12,9 +12,6 @@ export interface AuthRequest extends Request {
   };
 }
 
-/**
- * Verify JWT token and attach user to request
- */
 export const authenticate = (
   req: AuthRequest,
   res: Response,
@@ -47,9 +44,6 @@ export const authenticate = (
   }
 };
 
-/**
- * Optional authentication - doesn't fail if no token
- */
 export const optionalAuth = (
   req: AuthRequest,
   res: Response,
@@ -73,14 +67,10 @@ export const optionalAuth = (
     }
     next();
   } catch (error) {
-    // Continue without auth
     next();
   }
 };
 
-/**
- * Require admin role
- */
 export const requireAdmin = (
   req: AuthRequest,
   res: Response,

src/routes/agentRoutes.ts

@@ -8,6 +8,13 @@ import { Agent, AgentStatus } from '../entities/Agent';
 const router = Router();
 const agentController = new AgentController();
 
+/**
+ * @swagger
+ * tags:
+ *   name: Agents
+ *   description: Agent marketplace and management endpoints
+ */
+
 // Configure multer for avatar image uploads
 const avatarUpload = multer({
   storage: multer.memoryStorage(),
@@ -34,10 +41,162 @@ const avatarUpload = multer({
   },
 });
 
+/**
+ * @swagger
+ * /agents:
+ *   get:
+ *     summary: List agents (marketplace)
+ *     tags: [Agents]
+ *     description: Get a paginated list of approved agents with optional filtering
+ *     security: []
+ *     parameters:
+ *       - in: query
+ *         name: page
+ *         schema:
+ *           type: integer
+ *           default: 1
+ *         description: Page number
+ *       - in: query
+ *         name: limit
+ *         schema:
+ *           type: integer
+ *           default: 20
+ *         description: Items per page
+ *       - in: query
+ *         name: category
+ *         schema:
+ *           type: string
+ *         description: Filter by category
+ *       - in: query
+ *         name: search
+ *         schema:
+ *           type: string
+ *         description: Search by name or description
+ *       - in: query
+ *         name: minReputation
+ *         schema:
+ *           type: number
+ *         description: Minimum reputation score
+ *     responses:
+ *       200:
+ *         description: List of agents
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 agents:
+ *                   type: array
+ *                   items:
+ *                     $ref: '#/components/schemas/Agent'
+ *                 pagination:
+ *                   type: object
+ *                   properties:
+ *                     page:
+ *                       type: integer
+ *                     limit:
+ *                       type: integer
+ *                     total:
+ *                       type: integer
+ *                     totalPages:
+ *                       type: integer
+ */
 // Public routes
 router.get('/', optionalAuth, agentController.listAgents.bind(agentController));
+
+/**
+ * @swagger
+ * /agents/{id}:
+ *   get:
+ *     summary: Get agent details
+ *     tags: [Agents]
+ *     security: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent details
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       404:
+ *         description: Agent not found
+ */
 router.get('/:id', optionalAuth, agentController.getAgent.bind(agentController));
 
+/**
+ * @swagger
+ * /agents:
+ *   post:
+ *     summary: Create a new agent
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         multipart/form-data:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - name
+ *               - description
+ *               - endpoint
+ *               - category
+ *             properties:
+ *               name:
+ *                 type: string
+ *                 example: PixelPainter
+ *               description:
+ *                 type: string
+ *                 example: I turn prompts into AI art!
+ *               endpoint:
+ *                 type: string
+ *                 format: uri
+ *                 example: https://api.pixelpainter.ai/run
+ *               category:
+ *                 type: string
+ *                 example: image generation
+ *               avatar:
+ *                 type: string
+ *                 format: binary
+ *                 description: Agent avatar image (jpg, png, gif, webp, svg, bmp)
+ *               reputation:
+ *                 type: number
+ *                 format: float
+ *                 default: 0
+ *                 example: 4.8
+ *               capabilities:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 example: ["text-to-image", "image-editing"]
+ *               pointsPerTask:
+ *                 type: number
+ *                 format: float
+ *                 default: 0
+ *                 example: 10
+ *     responses:
+ *       201:
+ *         description: Agent created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       400:
+ *         description: Invalid input
+ *       401:
+ *         description: Unauthorized
+ *       500:
+ *         description: Server error
+ */
 // Creator routes (authenticated)
 router.post(
   '/',
@@ -45,15 +204,300 @@ router.post(
   avatarUpload.single('avatar'), // Accept avatar as single file
   agentController.createAgent.bind(agentController)
 );
+
+/**
+ * @swagger
+ * /agents/{id}:
+ *   put:
+ *     summary: Update an agent
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         multipart/form-data:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               name:
+ *                 type: string
+ *               description:
+ *                 type: string
+ *               endpoint:
+ *                 type: string
+ *                 format: uri
+ *               category:
+ *                 type: string
+ *               avatar:
+ *                 type: string
+ *                 format: binary
+ *                 description: Agent avatar image
+ *               reputation:
+ *                 type: number
+ *                 format: float
+ *               capabilities:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *               pointsPerTask:
+ *                 type: number
+ *                 format: float
+ *     responses:
+ *       200:
+ *         description: Agent updated successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       400:
+ *         description: Invalid input
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Not authorized to update this agent
+ *       404:
+ *         description: Agent not found
+ */
 router.put(
   '/:id',
   authenticate,
   avatarUpload.single('avatar'), // Accept avatar as single file
   agentController.updateAgent.bind(agentController)
 );
+
+/**
+ * @swagger
+ * /agents/{id}:
+ *   delete:
+ *     summary: Delete an agent
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent deleted successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 message:
+ *                   type: string
+ *                   example: Agent deleted successfully
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Not authorized to delete this agent
+ *       404:
+ *         description: Agent not found
+ */
 router.delete('/:id', authenticate, agentController.deleteAgent.bind(agentController));
+
+/**
+ * @swagger
+ * /agents/my/list:
+ *   get:
+ *     summary: Get my agents (creator's agents)
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: query
+ *         name: status
+ *         schema:
+ *           type: string
+ *           enum: [pending, approved, rejected]
+ *         description: Filter by status
+ *     responses:
+ *       200:
+ *         description: List of user's agents
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/Agent'
+ *       401:
+ *         description: Unauthorized
+ */
 router.get('/my/list', authenticate, agentController.getMyAgents.bind(agentController));
 
+/**
+ * @swagger
+ * /agents/{id}/delist:
+ *   patch:
+ *     summary: Delist an agent (hide from marketplace)
+ *     tags: [Agents]
+ *     description: Creator can suspend their own approved agent to hide it from the marketplace
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent delisted (suspended)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Not authorized to delist this agent
+ *       404:
+ *         description: Agent not found
+ */
+router.patch(
+  '/:id/delist',
+  authenticate,
+  async (req, res) => {
+    try {
+      const { id } = req.params;
+      const userId = (req as any).user.id;
+      const agentRepository = AppDataSource.getRepository(Agent);
+
+      const agent = await agentRepository.findOne({ where: { id } });
+      if (!agent) {
+        return res.status(404).json({ error: 'Agent not found' });
+      }
+
+      // Only creator can delist their own agent
+      if (agent.creatorId !== userId) {
+        return res.status(403).json({ error: 'Not authorized to delist this agent' });
+      }
+
+      agent.status = AgentStatus.SUSPENDED;
+      await agentRepository.save(agent);
+
+      res.json(agent);
+    } catch (error) {
+      console.error('Delist agent error:', error);
+      res.status(500).json({ error: 'Failed to delist agent' });
+    }
+  }
+);
+
+/**
+ * @swagger
+ * /agents/{id}/relist:
+ *   patch:
+ *     summary: Relist an agent (show in marketplace)
+ *     tags: [Agents]
+ *     description: Creator can relist their own suspended agent back to approved status (if it was previously approved)
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent relisted (approved)
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       400:
+ *         description: Agent was never approved, cannot relist
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Not authorized to relist this agent
+ *       404:
+ *         description: Agent not found
+ */
+router.patch(
+  '/:id/relist',
+  authenticate,
+  async (req, res) => {
+    try {
+      const { id } = req.params;
+      const userId = (req as any).user.id;
+      const agentRepository = AppDataSource.getRepository(Agent);
+
+      const agent = await agentRepository.findOne({ where: { id } });
+      if (!agent) {
+        return res.status(404).json({ error: 'Agent not found' });
+      }
+
+      // Only creator can relist their own agent
+      if (agent.creatorId !== userId) {
+        return res.status(403).json({ error: 'Not authorized to relist this agent' });
+      }
+
+      // Only relist if agent was previously approved (has approvedAt date)
+      if (!agent.approvedAt) {
+        return res.status(400).json({ error: 'Agent was never approved. Cannot relist. Please wait for admin approval.' });
+      }
+
+      agent.status = AgentStatus.APPROVED;
+      await agentRepository.save(agent);
+
+      res.json(agent);
+    } catch (error) {
+      console.error('Relist agent error:', error);
+      res.status(500).json({ error: 'Failed to relist agent' });
+    }
+  }
+);
+
+/**
+ * @swagger
+ * /agents/{id}/approve:
+ *   patch:
+ *     summary: Approve an agent (admin only)
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent approved
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Admin access required
+ *       404:
+ *         description: Agent not found
+ */
 // Admin routes
 router.patch(
   '/:id/approve',
@@ -83,6 +527,36 @@ router.patch(
   }
 );
 
+/**
+ * @swagger
+ * /agents/{id}/reject:
+ *   patch:
+ *     summary: Reject an agent (admin only)
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *           format: uuid
+ *         description: Agent ID
+ *     responses:
+ *       200:
+ *         description: Agent rejected
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Agent'
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Admin access required
+ *       404:
+ *         description: Agent not found
+ */
 router.patch(
   '/:id/reject',
   authenticate,
@@ -110,6 +584,28 @@ router.patch(
   }
 );
 
+/**
+ * @swagger
+ * /agents/admin/pending:
+ *   get:
+ *     summary: Get pending agents (admin only)
+ *     tags: [Agents]
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: List of pending agents
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ *               items:
+ *                 $ref: '#/components/schemas/Agent'
+ *       401:
+ *         description: Unauthorized
+ *       403:
+ *         description: Admin access required
+ */
 router.get(
   '/admin/pending',
   authenticate,

src/routes/authRoutes.ts

@@ -15,7 +15,68 @@ const messageRepository = AppDataSource.getRepository(ChatMessage);
 const walletService = new WalletService();
 
 /**
- * Register new user
+ * @swagger
+ * tags:
+ *   name: Auth
+ *   description: User authentication endpoints
+ */
+
+/**
+ * @swagger
+ * /auth/register:
+ *   post:
+ *     summary: Register a new user
+ *     tags: [Auth]
+ *     security: []
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - email
+ *               - password
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *                 example: user@example.com
+ *               password:
+ *                 type: string
+ *                 format: password
+ *                 minLength: 6
+ *                 example: password123
+ *               name:
+ *                 type: string
+ *                 example: John Doe
+ *     responses:
+ *       201:
+ *         description: User registered successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 token:
+ *                   type: string
+ *                   description: JWT authentication token
+ *                 user:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       format: uuid
+ *                     email:
+ *                       type: string
+ *                     name:
+ *                       type: string
+ *                     isAdmin:
+ *                       type: boolean
+ *       400:
+ *         description: Invalid input or user already exists
+ *       500:
+ *         description: Server error
  */
 router.post('/register', async (req: Request, res: Response) => {
   try {
@@ -67,7 +128,59 @@ router.post('/register', async (req: Request, res: Response) => {
 });
 
 /**
- * Login
+ * @swagger
+ * /auth/login:
+ *   post:
+ *     summary: Login user
+ *     tags: [Auth]
+ *     security: []
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - email
+ *               - password
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *                 example: user@example.com
+ *               password:
+ *                 type: string
+ *                 format: password
+ *                 example: password123
+ *     responses:
+ *       200:
+ *         description: Login successful
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 token:
+ *                   type: string
+ *                   description: JWT authentication token
+ *                 user:
+ *                   type: object
+ *                   properties:
+ *                     id:
+ *                       type: string
+ *                       format: uuid
+ *                     email:
+ *                       type: string
+ *                     name:
+ *                       type: string
+ *                     isAdmin:
+ *                       type: boolean
+ *       401:
+ *         description: Invalid credentials
+ *       403:
+ *         description: Account disabled
+ *       500:
+ *         description: Server error
  */
 router.post('/login', async (req: Request, res: Response) => {
   try {
@@ -116,7 +229,55 @@ router.post('/login', async (req: Request, res: Response) => {
 });
 
 /**
- * Get current user (profile + wallet + counts)
+ * @swagger
+ * /auth/me:
+ *   get:
+ *     summary: Get current user profile with wallet and counts
+ *     tags: [Auth]
+ *     security:
+ *       - bearerAuth: []
+ *     responses:
+ *       200:
+ *         description: User profile with wallet and statistics
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 id:
+ *                   type: string
+ *                   format: uuid
+ *                 email:
+ *                   type: string
+ *                 name:
+ *                   type: string
+ *                 isAdmin:
+ *                   type: boolean
+ *                 createdAt:
+ *                   type: string
+ *                   format: date-time
+ *                 wallet:
+ *                   type: object
+ *                   properties:
+ *                     balance:
+ *                       type: number
+ *                     balanceInDollars:
+ *                       type: number
+ *                     freeTasksRemaining:
+ *                       type: integer
+ *                 counts:
+ *                   type: object
+ *                   properties:
+ *                     agentsCreated:
+ *                       type: integer
+ *                     totalMessages:
+ *                       type: integer
+ *       401:
+ *         description: Unauthorized
+ *       404:
+ *         description: User not found
+ *       500:
+ *         description: Server error
  */
 router.get('/me', authenticate, async (req: Request, res: Response) => {
   try {

src/server.ts

@@ -1,36 +1,56 @@
+const isHuggingFaceSpace = !!process.env.HF_SPACE_ID || !!process.env.SPACE_ID;
+const isProduction = process.env.NODE_ENV === 'production';
+
+if (!isHuggingFaceSpace && !isProduction) {
+  const dotenv = require('dotenv');
+  const path = require('path');
+  const fs = require('fs');
+  
+  const envPath = path.join(__dirname, '../.env');
+  if (fs.existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+    console.log(`📄 Development: Loaded .env from: ${envPath}`);
+  } else {
+    dotenv.config();
+    console.log('📄 Development: Using default .env location');
+  }
+} else {
+  console.log('📄 Production: Using environment variables from platform secrets');
+}
+
 import 'reflect-metadata';
-import dotenv from 'dotenv';
 import { AppDataSource } from './config/database';
 import app from './app';
 
-// Load environment variables
-dotenv.config();
-
-// Hugging Face Spaces uses port 7860 by default, but allow override
 const PORT = parseInt(process.env.PORT || process.env.SPACE_PORT || '7860', 10);
 
 console.log('🔧 Starting server...');
 console.log(`📡 Environment: ${process.env.NODE_ENV || 'development'}`);
 console.log(`🌐 Port: ${PORT}`);
-console.log(`📊 Database URL: ${process.env.DATABASE_URL ? 'Set' : 'Not set'}`);
+if (process.env.DATABASE_URL) {
+  const dbUrl = process.env.DATABASE_URL;
+  const masked = dbUrl.length > 60 
+    ? `${dbUrl.substring(0, 30)}...${dbUrl.substring(dbUrl.length - 10)}`
+    : dbUrl;
+  console.log(`📊 Database URL: Set (${masked})`);
+} else {
+  console.log(`📊 Database URL: ❌ NOT SET`);
+}
 
-// Initialize database connection
 AppDataSource.initialize()
   .then(async () => {
     console.log('✅ Database connected');
     
-    // Run migrations if synchronize is disabled
     if (process.env.DB_SYNCHRONIZE !== 'true' && process.env.NODE_ENV === 'production') {
       try {
         console.log('🔄 Running migrations...');
         await AppDataSource.runMigrations();
         console.log('✅ Migrations completed');
       } catch (migrationError) {
-        console.warn('⚠️  Migration warning (may already be up to date):', migrationError);
+        console.warn('⚠️  Migration warning:', migrationError);
       }
     }
 
-    // Start server
     app.listen(PORT, '0.0.0.0', () => {
       console.log(`🚀 Server running on port ${PORT}`);
       console.log(`🌍 Server accessible at http://0.0.0.0:${PORT}`);

src/services/exchangeRateService.ts

@@ -1,32 +1,21 @@
 import axios from 'axios';
 
-/**
- * Exchange Rate Service
- * Fetches current NGN to USD exchange rate from various APIs
- * Falls back to fixed rate if API fails
- */
 export class ExchangeRateService {
   private cachedRate: number | null = null;
   private cacheExpiry: Date | null = null;
-  private readonly CACHE_DURATION_MS = 60 * 60 * 1000; // 1 hour cache
+  private readonly CACHE_DURATION_MS = 60 * 60 * 1000;
   private readonly FALLBACK_RATE: number;
 
   constructor() {
     this.FALLBACK_RATE = parseFloat(process.env.NGN_PER_USD || '750');
   }
 
-  /**
-   * Get current NGN to USD exchange rate
-   * Uses cache if available and not expired
-   */
   async getNGNToUSDRate(): Promise<number> {
-    // Check cache first
     if (this.cachedRate && this.cacheExpiry && new Date() < this.cacheExpiry) {
       console.log('Using cached exchange rate:', this.cachedRate);
       return this.cachedRate;
     }
 
-    // Try to fetch from API
     try {
       const rate = await this.fetchExchangeRate();
       this.cachedRate = rate;
@@ -39,12 +28,7 @@ export class ExchangeRateService {
     }
   }
 
-  /**
-   * Fetch exchange rate from external API
-   * Tries multiple sources for reliability
-   */
   private async fetchExchangeRate(): Promise<number> {
-    // Option 1: ExchangeRate-API (free, no API key needed)
     try {
       const response = await axios.get('https://api.exchangerate-api.com/v4/latest/USD', {
         timeout: 5000,

src/services/ipfsService.ts

@@ -1,9 +1,5 @@
 import { PinataSDK } from 'pinata';
 
-/**
- * IPFS Service via Pinata SDK
- * Handles storing and retrieving agent metadata from IPFS
- */
 export class IpfsService {
   private pinata: PinataSDK | null;
   private gatewayUrl: string;
@@ -17,13 +13,10 @@ export class IpfsService {
       this.pinata = null;
       this.gatewayUrl = '';
     } else {
-      // Gateway URL should be in format "fun-llama-300.mypinata.cloud" (no https://)
-      // Remove protocol if present, SDK expects just the domain
       const gatewayDomain = gatewayUrl
         ? gatewayUrl.replace(/^https?:\/\//, '').replace(/\/ipfs\/?$/, '')
         : 'gateway.pinata.cloud';
 
-      // Store full URL for direct access
       this.gatewayUrl = `https://${gatewayDomain}/ipfs/`;
 
       if (!gatewayUrl) {
@@ -37,9 +30,6 @@ export class IpfsService {
     }
   }
 
-  /**
-   * Upload agent metadata to IPFS
-   */
   async uploadMetadata(metadata: {
     name: string;
     description: string;

src/services/paystackService.ts

@@ -1,13 +1,14 @@
 const Paystack = require('paystack-node');
 
-/**
- * Paystack Service
- * Handles payment initialization and verification using paystack-node
- */
 export class PaystackService {
   private paystack: any;
+  private initialized: boolean = false;
+
+  private initialize() {
+    if (this.initialized) {
+      return;
+    }
 
-  constructor() {
     const secretKey = process.env.PAYSTACK_SECRET_KEY;
     if (!secretKey) {
       throw new Error('PAYSTACK_SECRET_KEY not configured');
@@ -15,12 +16,9 @@ export class PaystackService {
 
     const environment = process.env.NODE_ENV === 'production' ? 'production' : 'development';
     this.paystack = new Paystack(secretKey, environment);
+    this.initialized = true;
   }
 
-  /**
-   * Initialize transaction
-   * Returns authorization_url for redirect or frontend widget
-   */
   async initializeTransaction(data: {
     email: string;
     amount: number; // Amount in kobo (NGN) or smallest currency unit
@@ -28,11 +26,11 @@ export class PaystackService {
     metadata?: Record<string, any>;
     callback_url?: string;
   }) {
+    this.initialize();
     try {
-      // paystack-node expects metadata as JSON string, not object
       const payload: any = {
         email: data.email,
-        amount: data.amount, // Already in kobo/smallest unit
+        amount: data.amount,
         reference: data.reference,
       };
 
@@ -64,6 +62,7 @@ export class PaystackService {
    * Verify transaction by reference
    */
   async verifyTransaction(reference: string) {
+    this.initialize();
     try {
       const response = await this.paystack.verifyTransaction({
         reference: reference,
@@ -109,5 +108,12 @@ export class PaystackService {
     }
     return publicKey;
   }
+  
+  /**
+   * Check if Paystack is configured
+   */
+  isConfigured(): boolean {
+    return !!(process.env.PAYSTACK_SECRET_KEY && process.env.PAYSTACK_PUBLIC_KEY);
+  }
 }