@goreal-ai/plp-express-middleware

Express middleware for building PLP (Prompt Library Protocol) compliant servers.

Features

• ✅ Fully PLP-compliant - Implements all required endpoints
• 🗄️ File-based storage - Simple JSON file storage out of the box
• 🔒 Optional authentication - Bearer token support
• 🔌 Plug & play - Add to existing Express apps in seconds
• 📦 TypeScript - Full type safety

Installation

npm install @goreal-ai/plp-express-middleware express
# or
yarn add @goreal-ai/plp-express-middleware express

Quick Start

import express from 'express';
import { plpMiddleware } from '@goreal-ai/plp-express-middleware';

const app = express();
app.use(express.json());

// Add PLP endpoints at /v1
app.use('/v1', plpMiddleware({
  storage: './prompts-db'
}));

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

That's it! Your server now supports:

• GET /v1/prompts/{id} - Retrieve prompts
• GET /v1/prompts/{id}/{version} - Retrieve specific versions
• PUT /v1/prompts/{id} - Create/update prompts
• DELETE /v1/prompts/{id} - Delete prompts

Configuration

Basic Options

plpMiddleware({
  storage: './prompts-db',    // Required: Path to storage directory
  apiKey: 'your-secret-key',  // Optional: Simple API key authentication
})

Custom Authentication

plpMiddleware({
  storage: './prompts-db',
  validateApiKey: async (key) => {
    // Your custom authentication logic
    const user = await db.users.findByApiKey(key);
    return user !== null;
  }
})

Examples

Minimal Server

import express from 'express';
import { plpMiddleware } from '@goreal-ai/plp-express-middleware';

const app = express();
app.use(express.json());

app.use('/v1', plpMiddleware({
  storage: './prompts'
}));

app.listen(3000);

With Authentication

import express from 'express';
import { plpMiddleware } from '@goreal-ai/plp-express-middleware';

const app = express();
app.use(express.json());

app.use('/v1', plpMiddleware({
  storage: './prompts',
  apiKey: process.env.PLP_API_KEY
}));

app.listen(3000);

With Custom Storage

import express from 'express';
import { plpMiddleware, Storage, PromptEnvelope } from '@goreal-ai/plp-express-middleware';

// Implement custom storage (e.g., PostgreSQL, MongoDB)
class CustomStorage implements Storage {
  async get(id: string, version?: string): Promise<PromptEnvelope | null> {
    // Your implementation
  }

  async put(id: string, envelope: Omit<PromptEnvelope, 'id'>): Promise<PromptEnvelope> {
    // Your implementation
  }

  async delete(id: string): Promise<boolean> {
    // Your implementation
  }
}

const app = express();
app.use(express.json());

// Use custom storage
const storage = new CustomStorage();
app.use('/v1', plpMiddleware({ storage }));

app.listen(3000);

Testing Your Server

# Create a prompt
curl -X PUT http://localhost:3000/v1/prompts/test/hello \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello {{name}}!",
    "meta": {"version": "1.0.0"}
  }'

# Get the prompt
curl http://localhost:3000/v1/prompts/test/hello

# Delete the prompt
curl -X DELETE http://localhost:3000/v1/prompts/test/hello

API Reference

plpMiddleware(options)

Creates an Express router with PLP endpoints.

Options:

interface PLPMiddlewareOptions {
  storage: string | Storage;  // Path to storage directory or custom Storage implementation
  apiKey?: string;            // Optional API key for Bearer token auth
  validateApiKey?: (key: string) => boolean | Promise<boolean>; // Custom validator
}

Returns: Express Router

Storage Interface

Implement this interface for custom storage:

interface Storage {
  get(id: string, version?: string): Promise<PromptEnvelope | null>;
  put(id: string, envelope: Omit<PromptEnvelope, 'id'>): Promise<PromptEnvelope>;
  delete(id: string): Promise<boolean>;
}

PromptEnvelope Type

interface PromptEnvelope {
  id: string;
  content: string;
  meta: Record<string, any>;
}

File Storage

By default, prompts are stored as JSON files:

./prompts-db/
  marketing__welcome-email.json           # Latest version
  [email protected]     # Versioned copy
  support__faq-bot.json

File naming:

• / in IDs are replaced with __
• Versioned files include @version suffix

Deployment

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

Environment Variables

PORT=3000
PLP_API_KEY=your-secret-key
STORAGE_PATH=./prompts-db

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Lint
npm run lint

License

MIT © GoReal.AI

Contributing

See CONTRIBUTING.md

Learn More

• PLP Specification
• Client SDKs
• GitHub Repository