@teliagen/plugin-playground

Interactive API playground for Teliagen applications.

Overview

@teliagen/plugin-playground provides an interactive UI for testing your Teliagen actions:

• Action Explorer – Browse all available actions
• Input Builder – Auto-generated forms from schemas
• Response Viewer – Formatted JSON responses
• Authentication – Login and test authenticated actions
• History – Request/response history

Installation

npm install @teliagen/plugin-playground
# or
pnpm add @teliagen/plugin-playground

Quick Start

import { TeliagenApp } from '@teliagen/server';
import { PlaygroundPlugin } from '@teliagen/plugin-playground';

const app = new TeliagenApp();
await app.initialize();

const playground = PlaygroundPlugin({
  name: 'playground',
  path: '/playground'
});

await app.registerPlugins([playground]);
await app.start();

// Access playground at http://localhost:3000/playground

Configuration

interface PlaygroundPluginOptions {
  name: string;                  // Plugin instance name
  path?: string;                 // URL path (default: '/playground')
  
  // Access control
  enabled?: boolean;             // Enable/disable (default: true)
  allowInProduction?: boolean;   // Allow in prod (default: false)
  
  // Authentication
  requireAuth?: boolean;         // Require login (default: false)
  authPlugin?: string;           // Auth plugin name to use
  
  // UI customization
  title?: string;                // Page title
  logo?: string;                 // Logo URL
  theme?: 'light' | 'dark';      // UI theme
}

Examples

Basic Setup

const playground = PlaygroundPlugin({
  name: 'playground',
  path: '/api/playground',
  title: 'My API Playground'
});

Protected Playground

const playground = PlaygroundPlugin({
  name: 'playground',
  requireAuth: true,
  authPlugin: 'auth',  // Use auth plugin for login
  allowInProduction: false
});

Production Setup

const playground = PlaygroundPlugin({
  name: 'playground',
  enabled: process.env.NODE_ENV !== 'production',
  // Or allow in production with auth:
  // enabled: true,
  // allowInProduction: true,
  // requireAuth: true
});

Features

Action Explorer

Browse all registered actions organized by module and provider:

├── auth (module)
│   └── AuthActions (provider)
│       ├── login
│       ├── register
│       └── refreshToken
├── users
│   └── UserActions
│       ├── listUsers
│       ├── getUser
│       └── updateUser
└── orders
    └── OrderActions
        ├── createOrder
        └── getOrderDetails

Input Builder

Auto-generates input forms from your @Input schemas:

class CreateOrderInput {
  @String({ required: true })
  customerId!: string;

  @Array({ itemType: Object })
  items!: OrderItem[];

  @String({ optional: true })
  notes?: string;
}

Generates a form with:

• Text input for customerId
• Array builder for items
• Optional text area for notes

Response Viewer

• Syntax-highlighted JSON
• Collapsible nested objects
• Copy to clipboard
• Response time and status

Authentication

If requireAuth is enabled:

1. User logs in via auth plugin
2. Token is stored in session
3. All requests include auth header
4. Test protected actions easily

Accessing Actions via Playground

GET http://localhost:3000/playground

# Interactive UI at:
http://localhost:3000/playground

The playground fetches action metadata from:

GET /teliagen/metadata

Ensure you have ClientContractSync or ServerContractSync enabled.

Security

Development Only (Default):

PlaygroundPlugin({
  name: 'playground',
  allowInProduction: false  // Disabled in production
});

Production with Auth:

PlaygroundPlugin({
  name: 'playground',
  allowInProduction: true,
  requireAuth: true,
  authPlugin: 'auth'
});

IP Whitelist (Advanced):

PlaygroundPlugin({
  name: 'playground',
  allowInProduction: true,
  middleware: async (ctx, next) => {
    const allowedIPs = ['127.0.0.1', '10.0.0.0/8'];
    if (!isAllowedIP(ctx.ip, allowedIPs)) {
      throw new Error('Access denied');
    }
    await next();
  }
});

Requirements

• Node.js >= 18.0.0
• @teliagen/server >= 0.1.0

Related Packages

• @teliagen/plugin-auth – For authenticated playground

Documentation

For full documentation, visit docs.teliagen.org.

License

MIT © Teliagen Contributors