apptise-component

A React component library for building notification channel configuration forms based on the apprise Python library specifications.

Features

• 🎯 Easy Integration: Simple input component with configuration modal
• 🔧 Dynamic Form Generation: Automatically generates form fields based on channel specifications
• ✅ Built-in Validation: Real-time validation with error messages
• 🔗 URL Building: Automatically constructs notification URLs from form data
• 🎨 Modern UI: Clean, responsive design with modal interface
• 📱 Mobile Friendly: Works seamlessly on desktop and mobile devices
• 🔒 Type Safe: Full TypeScript support with comprehensive type definitions
• 🌐 Multi-Channel Support: Supports Discord, Telegram, Slack, Email, Webhooks, and more

Installation

pnpm add apptise-component
# or
npm install apptise-component
# or
yarn add apptise-component

Quick Start

Basic Usage

import React, { useState } from 'react';
import { NotificationChannelInput } from 'apptise-component';
import 'apptise-component/dist/style.css';

const App = () => {
  const [notificationUrl, setNotificationUrl] = useState('');

  return (
    <div>
      <label>Notification URL:</label>
      <NotificationChannelInput
        value={notificationUrl}
        onChange={setNotificationUrl}
        placeholder="Enter notification URL or click configure button"
      />
      
      {notificationUrl && (
        <div>
          <p>Current URL: <code>{notificationUrl}</code></p>
        </div>
      )}
    </div>
  );
};

Advanced Usage with Custom Channels

import React, { useState } from 'react';
import { 
  NotificationChannelConfig,
  NOTIFICATION_CHANNELS,
  getChannelByProtocol 
} from 'apptise-component';
import 'apptise-component/dist/style.css';

const App = () => {
  const [notificationUrl, setNotificationUrl] = useState('');
  const [isValid, setIsValid] = useState(false);

  // Get Discord channel configuration
  const discordChannel = getChannelByProtocol('discord');

  if (!discordChannel) {
    return <div>Channel not found</div>;
  }

  return (
    <NotificationChannelConfig
      channel={discordChannel}
      onUrlChange={setNotificationUrl}
      onValidationChange={(valid, errors) => setIsValid(valid)}
      initialValues={{
        webhook_id: '123456789',
        format: 'markdown'
      }}
    />
  );
};

Components

NotificationChannelInput

The main component that provides an input field with a configuration button. This is the recommended component for most use cases.

Props

| Prop | Type | Description | |------|------|-------------| | value | string | Current input value (notification URL) | | onChange | (value: string) => void | Callback fired when the input value changes | | placeholder? | string | Placeholder text for the input field | | disabled? | boolean | Whether the input is disabled | | className? | string | Additional CSS class name |

NotificationChannelConfig

A lower-level component for directly configuring a specific notification channel.

Props

| Prop | Type | Description | |------|------|-------------| | channel | NotificationChannel | The notification channel configuration object | | onUrlChange? | (url: string) => void | Callback fired when the constructed URL changes | | onValidationChange? | (isValid: boolean, errors: ValidationError[]) => void | Callback fired when validation state changes | | initialValues? | FieldValue | Initial field values | | className? | string | Additional CSS class name |

ChannelSelector

A dropdown component for selecting notification channels.

Props

| Prop | Type | Description | |------|------|-------------| | selectedChannel | string | Currently selected channel protocol | | onChannelChange | (channelId: string) => void | Callback fired when channel selection changes | | channels | NotificationChannel[] | Array of available channels | | className? | string | Additional CSS class name |

Supported Channels

The library comes with built-in support for 80+ notification services:

Popular Messaging Platforms

• Discord - Webhook notifications
• Telegram - Bot notifications
• Slack - Webhook and bot notifications
• Microsoft Teams - Webhook notifications
• WhatsApp - Business API notifications
• Signal API - Signal messaging
• LINE - LINE messaging platform
• Threema Gateway - Secure messaging

Email Services

• Email (SMTP) - Standard SMTP email
• Mailgun - Email delivery service
• SendGrid - Email marketing platform
• Amazon SES - AWS email service
• SMTP2GO - Email delivery service
• SparkPost - Email delivery platform
• Resend - Modern email API
• Office 365 - Microsoft email service

Push Notification Services

• OneSignal - Multi-platform push notifications
• Firebase Cloud Messaging (FCM) - Google's push service
• Pushover - Simple push notifications
• Pushbullet - Cross-device notifications
• Pushsafer - Push notification service
• PushDeer - Self-hosted push service
• PushPlus - Chinese push service
• Pushy - Real-time push notifications
• SimplePush - Simple push service
• Join - Device synchronization
• Chanify - iOS push notifications
• Bark - iOS push notifications
• Gotify - Self-hosted push server
• ntfy - Simple HTTP-based notifications
• Notica - Browser notifications
• Prowl - iOS push notifications

SMS Services

• Twilio - SMS and voice API
• Vonage (Nexmo) - SMS and voice
• ClickSend - SMS and email service
• MessageBird - Multi-channel messaging
• Africa's Talking - African SMS service
• BulkSMS - Bulk SMS service
• BurstSMS - SMS service
• Clickatell - SMS gateway
• D7Networks - SMS service
• Kavenegar - Persian SMS service
• Sinch - SMS and voice API
• TextBelt - SMS service
• VoIP.ms - VoIP and SMS
• FreeMobile - French SMS service

Team Collaboration

• Mattermost - Team messaging
• RocketChat - Team communication
• Matrix - Decentralized chat
• Zulip - Team chat
• Flock - Team messaging
• Ryver - Team collaboration
• Guilded - Gaming community platform
• Revolt - Discord alternative

Social Media & Forums

• Twitter - Social media posts
• Reddit - Reddit posts
• Mastodon - Decentralized social network
• Bluesky - Social networking

Enterprise & Monitoring

• PagerDuty - Incident management
• Opsgenie - Alert management
• Splunk - Data analytics platform
• Syslog - System logging
• MQTT - IoT messaging protocol
• Home Assistant - Smart home platform
• Nextcloud - Cloud platform
• Emby - Media server

Chinese Platforms

• DingTalk - Enterprise communication
• Feishu/Lark - ByteDance collaboration
• WeCom Bot - WeChat Work bots
• Server酱 - Chinese notification service

Development & Integration

• Webhook - Generic HTTP webhooks (JSON/XML/Form)
• Apprise API - Apprise server integration
• IFTTT - Automation platform
• Custom - Custom notification handlers

Specialized Services

• Google Chat - Google Workspace messaging
• Webex Teams - Cisco collaboration
• LaMetric - Smart display notifications
• Kumulos - Mobile app platform
• Notifico - IRC notifications
• PopcornNotify - Movie notifications
• PushJet - Android push service
• Techulus Push - Push notifications
• Growl - macOS notifications
• APRS - Amateur radio messaging
• DAPNET - Paging network

All channels support dynamic configuration, validation, and URL building through the unified component interface.

You can access all supported channels via:

import { NOTIFICATION_CHANNELS, getChannelByProtocol } from 'apptise-component';

// Get all channels
console.log(NOTIFICATION_CHANNELS);

// Get specific channel
const discordChannel = getChannelByProtocol('discord');

Types

NotificationChannel

interface NotificationChannel {
  service_name: string;
  service_url?: string;
  setup_url?: string;
  protocol: string;
  protocols: string[];
  templates: string[];
  template_tokens: Record<string, TemplateToken>;
  template_args: Record<string, TemplateArg>;
}

TemplateToken

interface TemplateToken {
  name: string;
  type: 'string' | 'int' | 'float' | 'bool' | 'list:string';
  required?: boolean;
  private?: boolean;
  default?: any;
  min?: number;
  max?: number;
  regex?: [string, string]; // [pattern, flags]
  map_to?: string;
  prefix?: string;
  alias_of?: string | string[];
}

TemplateArg

interface TemplateArg {
  name: string;
  type: 'string' | 'int' | 'float' | 'bool' | 'list:string' | 'choice:string';
  default?: any;
  min?: number;
  max?: number;
  map_to?: string;
  alias_of?: string | string[];
  values?: readonly string[]; // For choice:string type
}

Field Types

The component supports various field types based on apprise specifications:

• string: Text input (password input if private: true)
• int: Number input for integers with optional min/max validation
• float: Number input for decimal numbers with optional min/max validation
• bool: Checkbox input
• list:string: Textarea for comma-separated values
• choice:string: Select dropdown with predefined options

Validation

The component includes comprehensive validation:

• Required field validation: Ensures all required fields are filled
• Type validation: Validates data types (string, number, boolean)
• Range validation: Validates min/max values for numeric fields
• Pattern validation: Validates input against regex patterns
• Real-time feedback: Shows validation errors as users type

Styling

The component comes with default styles that you can import:

import 'apptise-component/dist/style.css';

You can also customize the appearance by overriding CSS classes or providing your own styles.

Development

Building the Package

pnpm build

Running Storybook

pnpm storybook

Running Tests

pnpm test

Examples

Discord Webhook Configuration

import { NotificationChannelInput } from 'apptise-component';

<NotificationChannelInput
  value={discordUrl}
  onChange={setDiscordUrl}
  placeholder="Configure Discord webhook"
/>

Telegram Bot Configuration

import { getChannelByProtocol, NotificationChannelConfig } from 'apptise-component';

const telegramChannel = getChannelByProtocol('tgram');

<NotificationChannelConfig
  channel={telegramChannel}
  onUrlChange={setTelegramUrl}
  initialValues={{
    bot_token: '123456789:ABCdefGHIjklMNOpqrsTUVwxyz',
    targets: ['@username', '123456789']
  }}
/>

Email SMTP Configuration

import { getChannelByProtocol, NotificationChannelConfig } from 'apptise-component';

const emailChannel = getChannelByProtocol('mailto');

<NotificationChannelConfig
  channel={emailChannel}
  onUrlChange={setEmailUrl}
  initialValues={{
    userid: '[email protected]',
    domain: 'smtp.gmail.com',
    targets: ['[email protected]']
  }}
/>

License

MIT