Package Exports

@el_saintt/adapter-express

Readme

@el_saintt/adapter-express

Express.js adapter for Portfolio API - Provides middleware and route handlers for easy Express integration.

Installation

npm install @el_saintt/adapter-express @el_saintt/core express

Quick Start

import express from 'express';
import { PortfolioClient } from '@el_saintt/core';
import { githubPlugin } from '@el_saintt/plugin-github';
import { createPortfolioRouter, portfolioErrorHandler } from '@el_saintt/adapter-express';

// Initialize portfolio client
const client = new PortfolioClient({
  cache: {
    provider: 'memory',
    defaultTTL: 3600,
  },
  services: {
    github: {
      enabled: true,
      credentials: {
        username: 'your-username',
      },
    },
  },
});

// Register plugins
client.use(githubPlugin);

// Create Express app
const app = express();

// Mount portfolio routes
const portfolioRouter = createPortfolioRouter({ client });
app.use('/api/portfolio', portfolioRouter);

// Error handling
app.use(portfolioErrorHandler());

// Start server
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

API Endpoints

The adapter automatically creates the following REST API endpoints:

Services

GET /api/portfolio/services

List all configured services
Response: { success: true, data: { services: [...] } }

GET /api/portfolio/services/:service

Get information about a specific service
Example: /api/portfolio/services/github
Response: Service details (name, version, description)

GET /api/portfolio/services/:service/health

Check health of a specific service
Example: /api/portfolio/services/github/health
Response: Health check status

Content

GET /api/portfolio/content

Get all content from all services
Query params:
- limit - Number of items (default: 10)
- offset - Pagination offset
- since - ISO date string (filter by date)
- until - ISO date string (filter by date)
- skipCache - Skip cache (true/false)

GET /api/portfolio/content/:service

Get content from a specific service
Example: /api/portfolio/content/github?limit=5
Query params: Same as above

Health & Validation

GET /api/portfolio/health

Check health of all services
Response: Overall health status + individual service health

GET /api/portfolio/validate

Validate configuration
Response: Validation results with errors/warnings

Advanced Usage

Custom Base Path

const portfolioRouter = createPortfolioRouter({
  client,
  basePath: '/v1/portfolio' // Custom base path
});

app.use(portfolioRouter);

Enable CORS

const portfolioRouter = createPortfolioRouter({
  client,
  enableCors: true // Enable CORS headers
});

Custom Error Handling

import { portfolioErrorHandler } from '@el_saintt/adapter-express';

app.use(portfolioErrorHandler({
  includeStack: process.env.NODE_ENV === 'development',
  logErrors: true
}));

Async Route Wrapper

import { asyncHandler } from '@el_saintt/adapter-express';

app.get('/custom', asyncHandler(async (req, res) => {
  const content = await client.fetch('github');
  res.json(content);
}));

Custom Routes

import { formatSuccessResponse, formatErrorResponse } from '@el_saintt/adapter-express';

app.get('/custom-endpoint', async (req, res) => {
  try {
    const data = await client.fetch('github', { limit: 5 });
    res.json(formatSuccessResponse(data, { count: data.length }));
  } catch (error) {
    res.status(500).json(formatErrorResponse(error.message));
  }
});

Response Format

All responses follow a consistent format:

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2024-10-10T12:00:00.000Z",
    "count": 10,
    "service": "github"
  }
}

Error Response

{
  "success": false,
  "error": {
    "message": "Service not found",
    "code": "SERVICE_NOT_FOUND",
    "details": { ... }
  },
  "meta": {
    "timestamp": "2024-10-10T12:00:00.000Z"
  }
}

Middleware

Portfolio Router

import { createPortfolioRouter } from '@el_saintt/adapter-express';

const router = createPortfolioRouter({
  client: portfolioClient,
  enableCors: true,
});

app.use('/api', router);

Error Handler

import { portfolioErrorHandler, notFoundHandler } from '@el_saintt/adapter-express';

// 404 handler (place before error handler)
app.use(notFoundHandler());

// Error handler (place at the end)
app.use(portfolioErrorHandler({
  includeStack: false,
  logErrors: true
}));

TypeScript Support

Full TypeScript support with proper types:

import {
  PortfolioRequest,
  PortfolioResponse,
  PortfolioRouterOptions
} from '@el_saintt/adapter-express';

const handler = (req: PortfolioRequest, res: Response) => {
  const client = req.portfolioClient;
  // ... typed client access
};

Examples

See the /examples directory for complete working examples:

Basic Express server
Express with multiple plugins
Express with custom routes
Express with authentication

License

MIT