apptise-component/README.md

React components for Apprise notification channel configuration

# 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

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

## Quick Start

### Basic Usage

```tsx
import React, { useState } from 'react';
import { NotificationChannelInput } from 'apptise-component';
import 'apptise-component/dist/styles.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

```tsx
import React, { useState } from 'react';
import { 
  NotificationChannelConfig,
  NOTIFICATION_CHANNELS,
  getChannelByProtocol 
} from 'apptise-component';
import 'apptise-component/dist/styles.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:

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

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

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

## Types

#### `NotificationChannel`

```typescript
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`

```typescript
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`

```typescript
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:

```tsx
import 'apptise-component/dist/styles.css';
```

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

## Development

### Building the Package

```bash
pnpm build
```

### Running Storybook

```bash
pnpm storybook
```

### Running Tests

```bash
pnpm test
```

## Examples

### Discord Webhook Configuration

```tsx
import { NotificationChannelInput } from 'apptise-component';

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

### Telegram Bot Configuration

```tsx
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

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

const emailChannel = getChannelByProtocol('mailto');

<NotificationChannelConfig
  channel={emailChannel}
  onUrlChange={setEmailUrl}
  initialValues={{
    userid: 'sender@gmail.com',
    domain: 'smtp.gmail.com',
    targets: ['recipient@example.com']
  }}
/>
```

## License

MIT