🚀 agent-banner-library

A beautiful, standardized startup banner logger for REST API agents. Display server information, endpoints, and environment details in a clean, professional format.

✨ Features

• 🎨 Beautiful console output with customizable width and emojis
• 🔧 Framework agnostic - works with Express, Fastify, Koa, or any Node.js server
• 📦 Dual module support - ESM and CommonJS
• ⚡ Zero dependencies for production
• 🎯 TypeScript first with full type definitions
• 🧪 98%+ test coverage with comprehensive test suite
• 🔄 Smart defaults with flexible configuration

📦 Installation

npm install agent-banner-library

yarn add agent-banner-library

pnpm add agent-banner-library

🚀 Quick Start

Express.js Example

import express from 'express';
import { printAgentBanner } from 'agent-banner-library';

const app = express();
const PORT = process.env.PORT || 3000;

app.get('/api/v1/users', (req, res) => {
  res.json({ message: 'List users' });
});

app.post('/api/v1/users', (req, res) => {
  res.json({ message: 'Create user' });
});

app.listen(PORT, () => {
  printAgentBanner({
    agentName: 'User Management API',
    baseUrl: `http://localhost:${PORT}`,
    prefix: '/api/v1',
    endpoints: [
      { method: 'GET', path: '/users', description: 'List all users' },
      { method: 'POST', path: '/users', description: 'Create a new user' },
      { method: 'GET', path: '/users/:id', description: 'Get user by ID' },
      { method: 'PUT', path: '/users/:id', description: 'Update user' },
      { method: 'DELETE', path: '/users/:id', description: 'Delete user' },
    ],
  });
});

Output:

════════════════════════════════════════════════════════
🚀 User Management API - 1.0.0
════════════════════════════════════════════════════════
📡 Server running on: http://localhost:3000
📚 API Documentation: http://localhost:3000/api/v1/docs
🏥 Health Check: http://localhost:3000/api/v1/health
📝 Endpoints:
    - GET - List all users - http://localhost:3000/api/v1/users
    - POST - Create a new user - http://localhost:3000/api/v1/users
    - GET - Get user by ID - http://localhost:3000/api/v1/users/:id
    - PUT - Update user - http://localhost:3000/api/v1/users/:id
    - DELETE - Delete user - http://localhost:3000/api/v1/users/:id
════════════════════════════════════════════════════════
Environment: development
Timestamp: 2026-02-05T23:45:12.345Z
════════════════════════════════════════════════════════

Fastify Example

import Fastify from 'fastify';
import { printAgentBanner } from 'agent-banner-library';

const fastify = Fastify({ logger: false });
const PORT = 3001;

fastify.get('/api/v1/products', async (request, reply) => {
  return { products: [] };
});

fastify.post('/api/v1/products', async (request, reply) => {
  return { message: 'Product created' };
});

await fastify.listen({ port: PORT });

printAgentBanner({
  agentName: 'E-commerce API',
  baseUrl: `http://localhost:${PORT}`,
  prefix: '/api/v1',
  endpoints: [
    { method: 'GET', path: '/products', description: 'List products' },
    { method: 'POST', path: '/products', description: 'Create product' },
  ],
});

Koa Example

import Koa from 'koa';
import Router from '@koa/router';
import { printAgentBanner } from 'agent-banner-library';

const app = new Koa();
const router = new Router({ prefix: '/api/v1' });
const PORT = 3002;

router.get('/orders', (ctx) => {
  ctx.body = { orders: [] };
});

app.use(router.routes());

app.listen(PORT, () => {
  printAgentBanner({
    agentName: 'Order Management API',
    baseUrl: `http://localhost:${PORT}`,
    prefix: '/api/v1',
    endpoints: [{ method: 'GET', path: '/orders', description: 'List orders' }],
  });
});

📖 API Reference

printAgentBanner(config: AgentBannerConfig): void

Prints the banner directly to console.log(). Best for simple use cases.

renderAgentBanner(config: AgentBannerConfig): string

Returns the banner as a string. Useful when you want to use custom loggers or process the output.

import { renderAgentBanner } from 'agent-banner-library';
import logger from './logger'; // Your custom logger

const banner = renderAgentBanner({
  agentName: 'My API',
  baseUrl: 'http://localhost:3000',
  prefix: '/api',
});

logger.info(banner);

Configuration Options

interface AgentBannerConfig {
  // Required
  agentName: string; // Name of your API/service
  baseUrl: string; // Base URL (e.g., 'http://localhost:3000')
  prefix: string; // API prefix (e.g., '/api/v1')

  // Optional
  packageJsonPath?: string; // Path to package.json (default: process.cwd() + '/package.json')
  version?: string; // Version override (default: from package.json or '0.0.0')
  docsPath?: string; // Docs endpoint (default: '/docs')
  healthPath?: string; // Health endpoint (default: '/health')
  environment?: string; // Environment name (default: process.env.NODE_ENV)
  timestamp?: string | Date; // Timestamp (default: new Date())
  width?: number; // Banner width (default: 48)
  emoji?: boolean; // Enable emojis (default: true)

  // Endpoints
  endpoints?: Array<{
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
    path: string;
    description: string;
  }>;
}

🎨 Customization

Custom Version

printAgentBanner({
  agentName: 'My API',
  baseUrl: 'http://localhost:3000',
  prefix: '/api',
  version: '2.0.0-beta.1', // Override version
});

Custom Paths

printAgentBanner({
  agentName: 'My API',
  baseUrl: 'http://localhost:3000',
  prefix: '/api/v2',
  docsPath: '/swagger', // Custom docs path
  healthPath: '/status', // Custom health path
});

Custom Width and No Emojis

printAgentBanner({
  agentName: 'My API',
  baseUrl: 'http://localhost:3000',
  prefix: '/api',
  width: 60, // Wider banner
  emoji: false, // Disable emojis
});

Production Environment

printAgentBanner({
  agentName: 'My API',
  baseUrl: 'https://api.myservice.com',
  prefix: '/api/v1',
  environment: 'production',
  endpoints: [{ method: 'GET', path: '/health', description: 'Health check' }],
});

🔧 Module Systems

ESM (Modern)

import { printAgentBanner, renderAgentBanner } from 'agent-banner-library';

CommonJS (Legacy)

const { printAgentBanner, renderAgentBanner } = require('agent-banner-library');

🧪 Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the library
npm run build

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

# Run development script
npm run dev

📄 License

Apache-2.0 © Auronforge

🔗 Links

• npm Package
• GitHub Repository
• Issue Tracker

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

⭐ Show your support

Give a ⭐️ if this project helped you!

👨‍💻 Author

José Eduardo Trindade E Marques

• Company: AuronForge 🚀
• Email: [email protected]
• LinkedIn: linkedin.com/in/edu-marques29

Built with ❤️ using Clean Architecture and SOLID principles