universal-contact-notifier

A generic Node.js/TypeScript notifier library to send “Contact Form” submissions to messaging channels.
v1.0.0 ships with Discord support; future adapters (Telegram, Slack, SMS, email, etc.) can be added under src/sender/.

• Required fields: email, message
• Optional fields: title, name, date, extraFields (any key→value), color, username, avatarUrl

Created by Alberto Linde (https://albertolinde.com)

---

Table of Contents

1. Installation
2. Configuration
3. Project Structure
4. API Reference
5. Usage Examples
6. Publishing to NPM
7. Hosting on Git
8. Troubleshooting
9. License

---

Installation

1npm install universal-contact-notifier
2# or
3yarn add universal-contact-notifier

---

Configuration

1. Create a Discord Webhook
   • In your Discord server → Channel Settings → Integrations → Webhooks → Create Webhook
   • Copy the Webhook URL (e.g. https://discord.com/api/webhooks/...)
2. Set DISCORD_WEBHOOK_URL
   • Locally: copy .env.example → .env, paste your Webhook URL
   • In production: configure DISCORD_WEBHOOK_URL as an environment variable

1# .env
2DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123456789012345678/your-token

---

Project Structure

universal-contact-notifier/
├── package.json
├── tsconfig.json
├── .env.example
├── LICENSE
└── src/
├── colors.ts
├── types.ts
├── errors.ts
├── validation.ts
├── builder.ts
├── sender/
│   ├── index.ts
│   └── discord.ts
└── index.ts

---

API Reference

sendContact(channel, options): Promise<void>

• Parameters
  • channel: currently only 'discord'
  • options: see ContactOptions

1interface ContactOptions {
2    email: string;                              // required
3    message: string;                            // required
4    title?: string;                             // optional embed title
5    name?: string;                              // optional
6    date?: string;                              // optional
7    extraFields?: Record<string,string>;        // optional additional fields
8    color?: ColorName | string;                 // optional palette key (UPPERCASE) or HEX
9    username?: string;                          // optional webhook username override
10    avatarUrl?: string;                         // optional webhook avatar URL override
11}

• Throws DiscordContactError on validation or network errors

---

Usage Examples

1import { sendContact, DiscordContactError, COLORS } from 'universal-contact-notifier';
2
3async function main() {
4    try {
5        await sendContact('discord', {
6            email: 'user@example.com',
7            message: 'Hello world!',
8            title: '🚀 New Inquiry',
9            name: 'Alice',
10            date: '2025-06-08T14:30:00Z',
11            extraFields: { phone: '+1-555-1234' },
12            color: 'PURPLE',       // from COLORS: TEAL, RED, BLUE, GREEN, YELLOW, PURPLE, GRAY
13            username: 'Contact Bot',
14            avatarUrl: 'https://example.com/avatar.png'
15        });
16
17        console.log('Notification sent!');
18    } catch (err) {
19        if (err instanceof DiscordContactError) {
20            console.error('Notify failed:', err.message);
21        } else {
22            console.error('Unexpected error:', err);
23        }
24    }
25}
26
27main();

---

Troubleshooting

• Missing/invalid DISCORD_WEBHOOK_URL
  Ensure it begins with https://discord.com/api/webhooks/....

• Validation errors
  DiscordContactError will explain missing email or message.

• Network/Discord errors
  Check embed size limits (fields ≤1024 chars, description ≤4096 chars).

• Node version
  Requires Node ≥18 for built-in fetch.

---

License

This project is licensed under the MIT License. See LICENSE for details.