🔔 Talos SDK

A unified notification SDK for sending push notifications, emails, and SMS from a single, clean API.

✨ Features

• 🔔 Push Notifications via Firebase Cloud Messaging (FCM) ✅ Fully implemented
• 📧 Email (provider stub - ready for SendGrid, AWS SES, or Nodemailer)
• 📱 SMS (provider stub - ready for Twilio or AWS SNS)
• 🎯 Simple, promise-based API
• 📦 Supports both ESM and CommonJS
• 🔧 Modular provider system - easy to extend

📦 Installation

npm install talos

🚀 Quick Start

1. Get Firebase Service Account

1. Go to Firebase Console
2. Select your project → Project Settings → Service Accounts
3. Click Generate New Private Key
4. Download the JSON file and save it securely (e.g., firebase-service-account.json)

⚠️ SECURITY WARNING: Never commit this file to version control! It contains private keys.

2. Basic Usage

import Notifier from 'talos';

// Initialize with your Firebase service account
const notifier = new Notifier({
  fcm: {
    serviceAccountPath: './firebase-service-account.json'
  }
});

// Send a push notification
await notifier.push({
  token: 'device-fcm-token',  // Get this from your mobile/web app
  title: 'Hello!',
  body: 'Your notification message here'
});

3. Get Device Token (Client-Side)

In your mobile or web app, get the FCM device token:

// Web (Firebase SDK v9+)
import { getMessaging, getToken } from 'firebase/messaging';

const messaging = getMessaging();
const token = await getToken(messaging, {
  vapidKey: 'YOUR_VAPID_KEY'
});

console.log('Device Token:', token);
// Send this token to your backend

📖 API Reference

Constructor

const notifier = new Notifier(config);

Configuration Options:

| Option | Type | Description | |--------|------|-------------| | fcm.serviceAccountPath | string | Path to Firebase service account JSON file | | email.apiKey | string | Email service API key (for future implementation) | | email.from | string | Default sender email address | | sms.apiKey | string | SMS service API key (for future implementation) | | sms.from | string | Default sender phone number |

Methods

notifier.push(payload)

Send a push notification via Firebase Cloud Messaging.

await notifier.push({
  token: 'device-fcm-token',     // required
  title: 'Notification Title',   // required
  body: 'Notification message'   // required
});

Returns: Promise<string> - FCM message ID

notifier.email(payload)

Send an email (requires provider implementation).

await notifier.email({
  to: '[email protected]',        // required
  subject: 'Email Subject',       // required
  body: 'Email body text',        // required
  html: '<h1>HTML content</h1>'   // optional
});

Returns: Promise<Object> - Email service response

notifier.sms(payload)

Send an SMS (requires provider implementation).

await notifier.sms({
  to: '+1234567890',              // required (E.164 format)
  message: 'SMS message content'  // required
});

Returns: Promise<Object> - SMS service response

notifier.getStatus()

Check which providers are initialized.

const status = notifier.getStatus();
// Returns: { fcm: true, email: false, sms: false }

🔧 Setup Instructions

For Local Development

1. Clone the repository

   git clone https://github.com/yourusername/talos.git
   cd talos

2. Install dependencies

   npm install

3. Add your Firebase credentials

   # Copy the example file
   cp firebase-service-account.example.json your-firebase-service-account.json
      
   # Edit with your actual credentials from Firebase Console

4. Build the SDK

   npm run build

5. Test (optional)

   # Copy example test file
   cp test-sdk.example.js test-sdk.js
      
   # Edit test-sdk.js with your credentials and device token
   node test-sdk.js

For Production Use

npm install talos

Then import and use in your Node.js application as shown in Quick Start.

🔐 Security Best Practices

⚠️ CRITICAL: Protect Your Credentials

Never commit these files to Git:

• *-firebase.json (Firebase service account)
• .env files
• test-sdk.js (contains real tokens)

This project's .gitignore is configured to exclude these files automatically.

Recommended Setup

1. Use environment variables for sensitive paths:

   const notifier = new Notifier({
     fcm: {
       serviceAccountPath: process.env.FIREBASE_SERVICE_ACCOUNT_PATH
     }
   });

2. Store credentials securely:

   • Use secret managers (AWS Secrets Manager, Google Secret Manager)
   • Use environment variables in production
   • Never hardcode paths or credentials

🛠️ Extending Providers

Implementing Email Provider

1. Open src/providers/email.js

2. Install your email SDK:

   npm install @sendgrid/mail
   # or
   npm install nodemailer

3. Implement the functions:

   import sgMail from '@sendgrid/mail';
      
   export function initializeEmail(config) {
     sgMail.setApiKey(config.apiKey);
   }
      
   export async function send(payload) {
     const msg = {
       to: payload.to,
       from: config.from,
       subject: payload.subject,
       text: payload.body,
       html: payload.html
     };
        
     return await sgMail.send(msg);
   }

4. Rebuild:

   npm run build

Implementing SMS Provider

Similar process - open src/providers/sms.js and implement using Twilio, AWS SNS, or your preferred service.

📁 Project Structure

talos/
├── src/
│   ├── providers/
│   │   ├── fcm.js           # Firebase Cloud Messaging ✅
│   │   ├── email.js         # Email provider (stub)
│   │   └── sms.js           # SMS provider (stub)
│   ├── notifier.js          # Main SDK class
│   └── index.js             # Entry point
├── dist/                    # Built files (auto-generated)
│   ├── index.js             # ESM bundle
│   └── index.cjs            # CommonJS bundle
├── firebase-service-account.example.json   # Example config
├── test-sdk.example.js      # Example test script
├── package.json
├── .gitignore
└── README.md

🧪 Development

Build

npm run build

Builds both ESM and CommonJS formats to the dist/ folder.

Watch Mode

npm run dev

Automatically rebuilds on file changes.

📝 License

ISC

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Implement Email Provider: Add SendGrid, AWS SES, or Nodemailer integration
2. Implement SMS Provider: Add Twilio or AWS SNS integration
3. Add Tests: Write unit tests for providers
4. Improve Documentation: Add more examples and use cases

Please ensure:

• You don't commit credentials or private keys
• You follow the existing code style
• You test your changes

💡 How FCM Works

When you send a push notification with Talos:

1. Your code calls notifier.push() with a device token
2. Talos SDK authenticates with Firebase using your service account
3. Firebase servers route the notification to the target device
4. Device receives the notification instantly via persistent FCM connection

No server infrastructure needed on your end - Firebase handles all the heavy lifting! 🚀

📚 Additional Resources

• Firebase Cloud Messaging Documentation
• Get FCM Device Token (Web)
• Get FCM Device Token (Android)
• Get FCM Device Token (iOS)

⚡ Quick Examples

Send notification to multiple devices

const tokens = ['token1', 'token2', 'token3'];

for (const token of tokens) {
  await notifier.push({
    token,
    title: 'Group Notification',
    body: 'Hello everyone!'
  });
}

Error handling

try {
  await notifier.push({ token, title, body });
  console.log('✅ Notification sent');
} catch (error) {
  console.error('❌ Failed:', error.message);
}

Check provider status

const status = notifier.getStatus();
if (!status.fcm) {
  console.error('FCM not initialized!');
}

Made with ❤️ for seamless notifications