Manifest Configuration

Overview

The ProviderManifest is a required readonly property on every provider that contains metadata about your plugin. SimpleNS uses this information to:

Register your provider in the provider registry
Display provider information in the Admin Dashboard
Validate required credentials during configuration
Route notifications to the correct channel

interface ProviderManifest {
  name: string;
  version: string;
  channel: string;
  displayName: string;
  description: string;
  author: string;
  homepage?: string;
  requiredCredentials: string[];
  optionalConfig?: string[];
}

Required Fields

`name`

The unique package identifier for your provider. Should follow npm naming conventions.

name: '@simplens/twilio-sms'      // Scoped package (recommended)
name: 'simplens-my-email'          // Unscoped package

Use scoped packages (@simplens/ or @myorg/) to avoid naming conflicts and clearly identify provider authorship.

`version`

Semantic version string following SemVer conventions.

version: '1.0.0'    // Initial release
version: '1.2.3'    // Major.Minor.Patch
version: '2.0.0-beta.1'  // Pre-release

`channel`

The notification channel type this provider handles.

Channel	Description
`email`	Email notifications
`sms`	SMS text messages
`push`	Mobile push notifications
`whatsapp`	WhatsApp messages
`chat`	Chat platforms (Slack, Discord, etc.)

channel: 'email'
channel: 'sms'
channel: 'push'

The channel value must match the channel name used in your notification schema (passed to createNotificationSchema()).

`displayName`

Human-readable name shown in the SimpleNS Dashboard and logs.

displayName: 'Twilio SMS'
displayName: 'SendGrid Email'
displayName: 'Firebase Cloud Messaging'

`description`

Brief description of the provider's functionality.

description: 'Send SMS notifications via Twilio API'
description: 'Transactional emails using SendGrid with template support'

`author`

Provider maintainer's name or organization.

author: 'SimpleNS Team'
author: 'Your Name <email@example.com>'
author: 'My Company Inc.'

`requiredCredentials`

Array of credential field names that must be provided during initialization. These typically correspond to environment variable names.

requiredCredentials: ['API_KEY']
requiredCredentials: ['TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN', 'TWILIO_FROM_NUMBER']
requiredCredentials: ['SMTP_HOST', 'SMTP_PORT', 'SMTP_USER', 'SMTP_PASS']

These keys are used to access values from config.credentials in the initialize() method.

Optional Fields

`homepage`

URL to documentation or the provider's repository.

homepage: 'https://github.com/simplens/twilio-provider'
homepage: 'https://docs.mycompany.com/simplens-provider'

`optionalConfig`

Array of optional configuration field names. These are non-essential settings with defaults.

optionalConfig: ['SENDER_NAME', 'REPLY_TO']
optionalConfig: ['REGION', 'TIMEOUT_MS']

How Optional Config Works

Key Rule: requiredCredentials → config.credentials, optionalConfig → config.options

When you declare optionalConfig in your manifest, SimpleNS automatically:

During plugin install: Adds placeholders to simplens.config.yaml
At startup: Resolves env vars and passes values to your provider

Config File Structure

providers:
  - package: "@simplens/nodemailer-gmail"
    id: nodemailer-gmail
    credentials:                    # From requiredCredentials
      EMAIL_USER: ${EMAIL_USER}
      EMAIL_PASS: ${EMAIL_PASS}
    optionalConfig:                 # From optionalConfig
      EMAIL_HOST: ${EMAIL_HOST}
      EMAIL_PORT: ${EMAIL_PORT}
      EMAIL_FROM: ${EMAIL_FROM}
    options:
      priority: 1

Resolution Flow

simplens.config.yaml              Your Provider's initialize()
────────────────────              ─────────────────────────────
optionalConfig:                   config.options = {
  EMAIL_HOST: ${EMAIL_HOST}  →      EMAIL_HOST: "smtp.gmail.com",  // if set
  EMAIL_FROM: ${EMAIL_FROM}  →      EMAIL_FROM: "noreply@x.com",   // if set
                                    // Missing env vars are omitted
                                  }

Accessing in Your Provider

async initialize(config: ProviderConfig): Promise<void> {
    // Required credentials (always present)
    const user = config.credentials['EMAIL_USER'];
    const pass = config.credentials['EMAIL_PASS'];
    
    // Optional config (may or may not exist)
    const host = (config.options?.['EMAIL_HOST'] as string) || 'smtp.gmail.com';
    const port = parseInt((config.options?.['EMAIL_PORT'] as string) || '587');
    const from = (config.options?.['EMAIL_FROM'] as string) || user;
    
    this.transporter = nodemailer.createTransport({ host, port, auth: { user, pass }});
    this.fromEmail = from;
}

Always provide sensible defaults when accessing optional config since the key won't exist if the env var wasn't set.

Examples by Channel

readonly manifest: ProviderManifest = {
  name: '@simplens/sendgrid',
  version: '1.0.0',
  channel: 'email',
  displayName: 'SendGrid Email',
  description: 'Transactional emails via SendGrid API',
  author: 'SimpleNS Team',
  homepage: 'https://github.com/simplens/sendgrid-provider',
  requiredCredentials: ['SENDGRID_API_KEY'],
  optionalConfig: ['SENDER_EMAIL', 'SENDER_NAME'],
};

readonly manifest: ProviderManifest = {
  name: '@simplens/twilio-sms',
  version: '1.0.0',
  channel: 'sms',
  displayName: 'Twilio SMS',
  description: 'SMS notifications via Twilio',
  author: 'SimpleNS Team',
  requiredCredentials: [
    'TWILIO_ACCOUNT_SID',
    'TWILIO_AUTH_TOKEN', 
    'TWILIO_FROM_NUMBER'
  ],
};

readonly manifest: ProviderManifest = {
  name: '@simplens/fcm',
  version: '1.0.0',
  channel: 'push',
  displayName: 'Firebase Cloud Messaging',
  description: 'Push notifications via FCM',
  author: 'SimpleNS Team',
  requiredCredentials: ['FCM_SERVICE_ACCOUNT_JSON'],
  optionalConfig: ['FCM_PROJECT_ID'],
};

readonly manifest: ProviderManifest = {
  name: '@simplens/twilio-whatsapp',
  version: '1.0.0',
  channel: 'whatsapp',
  displayName: 'Twilio WhatsApp',
  description: 'WhatsApp messages via Twilio API',
  author: 'SimpleNS Team',
  requiredCredentials: [
    'TWILIO_ACCOUNT_SID',
    'TWILIO_AUTH_TOKEN',
    'TWILIO_WHATSAPP_NUMBER'
  ],
};

readonly manifest: ProviderManifest = {
  name: '@simplens/slack',
  version: '1.0.0',
  channel: 'chat',
  displayName: 'Slack Webhooks',
  description: 'Send messages to Slack channels via webhooks',
  author: 'SimpleNS Team',
  requiredCredentials: ['SLACK_WEBHOOK_URL'],
  optionalConfig: ['DEFAULT_CHANNEL', 'BOT_USERNAME'],
};

Best Practices

Use descriptive names: Choose displayName values that clearly identify the service and channel
Be specific with credentials: List exactly what's needed - don't bundle optional items in required
Follow SemVer: Properly version your provider to communicate breaking changes
Include homepage: Help users find documentation by providing a homepage URL
Match channel to schema: Ensure the channel value matches your createNotificationSchema() usage

Manifest Configuration

On this page