{"_id":"@daregreat4net/talos","name":"@daregreat4net/talos","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@daregreat4net/talos","version":"1.0.0","description":"A unified notification SDK for sending push notifications, emails, and SMS","main":"dist/index.js","module":"dist/index.mjs","type":"module","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup src/index.js --format esm,cjs","dev":"tsup src/index.js --watch --format esm,cjs","prepublishOnly":"npm run build"},"keywords":["notification","push","fcm","firebase","email","sms","sdk","messaging"],"author":"","license":"ISC","dependencies":{"firebase-admin":"^13.6.0"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.9.3"},"engines":{"node":">=14.0.0"},"gitHead":"5abd2717a11c8b2dc27d6515cdaadb1bb1ad256a","_id":"@daregreat4net/talos@1.0.0","_nodeVersion":"22.19.0","_npmVersion":"11.6.4","dist":{"integrity":"sha512-VkV+HEE02HT4pORY5Ik8BADLIVd+YNrjFzbRx1W1QEy7NN4anv1EkhnuzzBllO03YRzr5brqeMckCGV4uiUBFQ==","shasum":"236763b78e14e679e2f663f4a6273c51c1c5cef9","tarball":"https://registry.npmjs.org/@daregreat4net/talos/-/talos-1.0.0.tgz","fileCount":4,"unpackedSize":24576,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDMPO0kQd2xNaj9lu54ZBGe/deDqClDOuIalp/j0G+VBAIhALwsLaInQ9UYfIiZreBrIC44hTUOhk3qpcgEgBsylC3H"}]},"_npmUser":{"name":"daregreat4net","email":"chatzteam@gmail.com"},"directories":{},"maintainers":[{"name":"daregreat4net","email":"chatzteam@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/talos_1.0.0_1765198971817_0.12453556901496565"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-08T13:02:51.739Z","1.0.0":"2025-12-08T13:02:51.982Z","modified":"2025-12-08T13:02:52.222Z"},"maintainers":[{"name":"daregreat4net","email":"chatzteam@gmail.com"}],"description":"A unified notification SDK for sending push notifications, emails, and SMS","keywords":["notification","push","fcm","firebase","email","sms","sdk","messaging"],"license":"ISC","readme":"# 🔔 Talos SDK\r\n\r\nA unified notification SDK for sending push notifications, emails, and SMS from a single, clean API.\r\n\r\n[![npm version](https://img.shields.io/npm/v/talos.svg)](https://www.npmjs.com/package/talos)\r\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\r\n\r\n## ✨ Features\r\n\r\n- 🔔 **Push Notifications** via Firebase Cloud Messaging (FCM) ✅ Fully implemented\r\n- 📧 **Email** (provider stub - ready for SendGrid, AWS SES, or Nodemailer)\r\n- 📱 **SMS** (provider stub - ready for Twilio or AWS SNS)\r\n- 🎯 Simple, promise-based API\r\n- 📦 Supports both ESM and CommonJS\r\n- 🔧 Modular provider system - easy to extend\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install talos\r\n```\r\n\r\n---\r\n\r\n## 🚀 Quick Start\r\n\r\n### 1. Get Firebase Service Account\r\n\r\n1. Go to [Firebase Console](https://console.firebase.google.com/)\r\n2. Select your project → **Project Settings** → **Service Accounts**\r\n3. Click **Generate New Private Key**\r\n4. Download the JSON file and save it securely (e.g., `firebase-service-account.json`)\r\n\r\n> **⚠️ SECURITY WARNING**: Never commit this file to version control! It contains private keys.\r\n\r\n### 2. Basic Usage\r\n\r\n```javascript\r\nimport Notifier from 'talos';\r\n\r\n// Initialize with your Firebase service account\r\nconst notifier = new Notifier({\r\n  fcm: {\r\n    serviceAccountPath: './firebase-service-account.json'\r\n  }\r\n});\r\n\r\n// Send a push notification\r\nawait notifier.push({\r\n  token: 'device-fcm-token',  // Get this from your mobile/web app\r\n  title: 'Hello!',\r\n  body: 'Your notification message here'\r\n});\r\n```\r\n\r\n### 3. Get Device Token (Client-Side)\r\n\r\nIn your **mobile or web app**, get the FCM device token:\r\n\r\n```javascript\r\n// Web (Firebase SDK v9+)\r\nimport { getMessaging, getToken } from 'firebase/messaging';\r\n\r\nconst messaging = getMessaging();\r\nconst token = await getToken(messaging, {\r\n  vapidKey: 'YOUR_VAPID_KEY'\r\n});\r\n\r\nconsole.log('Device Token:', token);\r\n// Send this token to your backend\r\n```\r\n\r\n---\r\n\r\n## 📖 API Reference\r\n\r\n### Constructor\r\n\r\n```javascript\r\nconst notifier = new Notifier(config);\r\n```\r\n\r\n**Configuration Options:**\r\n\r\n| Option | Type | Description |\r\n|--------|------|-------------|\r\n| `fcm.serviceAccountPath` | string | Path to Firebase service account JSON file |\r\n| `email.apiKey` | string | Email service API key (for future implementation) |\r\n| `email.from` | string | Default sender email address |\r\n| `sms.apiKey` | string | SMS service API key (for future implementation) |\r\n| `sms.from` | string | Default sender phone number |\r\n\r\n### Methods\r\n\r\n#### `notifier.push(payload)`\r\n\r\nSend a push notification via Firebase Cloud Messaging.\r\n\r\n```javascript\r\nawait notifier.push({\r\n  token: 'device-fcm-token',     // required\r\n  title: 'Notification Title',   // required\r\n  body: 'Notification message'   // required\r\n});\r\n```\r\n\r\n**Returns:** `Promise<string>` - FCM message ID\r\n\r\n#### `notifier.email(payload)` \r\n\r\nSend an email (requires provider implementation).\r\n\r\n```javascript\r\nawait notifier.email({\r\n  to: 'user@example.com',        // required\r\n  subject: 'Email Subject',       // required\r\n  body: 'Email body text',        // required\r\n  html: '<h1>HTML content</h1>'   // optional\r\n});\r\n```\r\n\r\n**Returns:** `Promise<Object>` - Email service response\r\n\r\n#### `notifier.sms(payload)`\r\n\r\nSend an SMS (requires provider implementation).\r\n\r\n```javascript\r\nawait notifier.sms({\r\n  to: '+1234567890',              // required (E.164 format)\r\n  message: 'SMS message content'  // required\r\n});\r\n```\r\n\r\n**Returns:** `Promise<Object>` - SMS service response\r\n\r\n#### `notifier.getStatus()`\r\n\r\nCheck which providers are initialized.\r\n\r\n```javascript\r\nconst status = notifier.getStatus();\r\n// Returns: { fcm: true, email: false, sms: false }\r\n```\r\n\r\n---\r\n\r\n## 🔧 Setup Instructions\r\n\r\n### For Local Development\r\n\r\n1. **Clone the repository**\r\n   ```bash\r\n   git clone https://github.com/yourusername/talos.git\r\n   cd talos\r\n   ```\r\n\r\n2. **Install dependencies**\r\n   ```bash\r\n   npm install\r\n   ```\r\n\r\n3. **Add your Firebase credentials**\r\n   ```bash\r\n   # Copy the example file\r\n   cp firebase-service-account.example.json your-firebase-service-account.json\r\n   \r\n   # Edit with your actual credentials from Firebase Console\r\n   ```\r\n\r\n4. **Build the SDK**\r\n   ```bash\r\n   npm run build\r\n   ```\r\n\r\n5. **Test (optional)**\r\n   ```bash\r\n   # Copy example test file\r\n   cp test-sdk.example.js test-sdk.js\r\n   \r\n   # Edit test-sdk.js with your credentials and device token\r\n   node test-sdk.js\r\n   ```\r\n\r\n### For Production Use\r\n\r\n```bash\r\nnpm install talos\r\n```\r\n\r\nThen import and use in your Node.js application as shown in [Quick Start](#-quick-start).\r\n\r\n---\r\n\r\n## 🔐 Security Best Practices\r\n\r\n### ⚠️ CRITICAL: Protect Your Credentials\r\n\r\n**Never commit these files to Git:**\r\n- `*-firebase.json` (Firebase service account)\r\n- `.env` files\r\n- `test-sdk.js` (contains real tokens)\r\n\r\nThis project's `.gitignore` is configured to exclude these files automatically.\r\n\r\n### Recommended Setup\r\n\r\n1. **Use environment variables** for sensitive paths:\r\n   ```javascript\r\n   const notifier = new Notifier({\r\n     fcm: {\r\n       serviceAccountPath: process.env.FIREBASE_SERVICE_ACCOUNT_PATH\r\n     }\r\n   });\r\n   ```\r\n\r\n2. **Store credentials securely**:\r\n   - Use secret managers (AWS Secrets Manager, Google Secret Manager)\r\n   - Use environment variables in production\r\n   - Never hardcode paths or credentials\r\n\r\n---\r\n\r\n## 🛠️ Extending Providers\r\n\r\n### Implementing Email Provider\r\n\r\n1. Open `src/providers/email.js`\r\n2. Install your email SDK:\r\n   ```bash\r\n   npm install @sendgrid/mail\r\n   # or\r\n   npm install nodemailer\r\n   ```\r\n\r\n3. Implement the functions:\r\n   ```javascript\r\n   import sgMail from '@sendgrid/mail';\r\n   \r\n   export function initializeEmail(config) {\r\n     sgMail.setApiKey(config.apiKey);\r\n   }\r\n   \r\n   export async function send(payload) {\r\n     const msg = {\r\n       to: payload.to,\r\n       from: config.from,\r\n       subject: payload.subject,\r\n       text: payload.body,\r\n       html: payload.html\r\n     };\r\n     \r\n     return await sgMail.send(msg);\r\n   }\r\n   ```\r\n\r\n4. Rebuild:\r\n   ```bash\r\n   npm run build\r\n   ```\r\n\r\n### Implementing SMS Provider\r\n\r\nSimilar process - open `src/providers/sms.js` and implement using Twilio, AWS SNS, or your preferred service.\r\n\r\n---\r\n\r\n## 📁 Project Structure\r\n\r\n```\r\ntalos/\r\n├── src/\r\n│   ├── providers/\r\n│   │   ├── fcm.js           # Firebase Cloud Messaging ✅\r\n│   │   ├── email.js         # Email provider (stub)\r\n│   │   └── sms.js           # SMS provider (stub)\r\n│   ├── notifier.js          # Main SDK class\r\n│   └── index.js             # Entry point\r\n├── dist/                    # Built files (auto-generated)\r\n│   ├── index.js             # ESM bundle\r\n│   └── index.cjs            # CommonJS bundle\r\n├── firebase-service-account.example.json   # Example config\r\n├── test-sdk.example.js      # Example test script\r\n├── package.json\r\n├── .gitignore\r\n└── README.md\r\n```\r\n\r\n---\r\n\r\n## 🧪 Development\r\n\r\n### Build\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\nBuilds both ESM and CommonJS formats to the `dist/` folder.\r\n\r\n### Watch Mode\r\n\r\n```bash\r\nnpm run dev\r\n```\r\n\r\nAutomatically rebuilds on file changes.\r\n\r\n---\r\n\r\n## 📝 License\r\n\r\nISC\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Here's how you can help:\r\n\r\n1. **Implement Email Provider**: Add SendGrid, AWS SES, or Nodemailer integration\r\n2. **Implement SMS Provider**: Add Twilio or AWS SNS integration\r\n3. **Add Tests**: Write unit tests for providers\r\n4. **Improve Documentation**: Add more examples and use cases\r\n\r\nPlease ensure:\r\n- You don't commit credentials or private keys\r\n- You follow the existing code style\r\n- You test your changes\r\n\r\n---\r\n\r\n## 💡 How FCM Works\r\n\r\nWhen you send a push notification with Talos:\r\n\r\n1. **Your code** calls `notifier.push()` with a device token\r\n2. **Talos SDK** authenticates with Firebase using your service account\r\n3. **Firebase servers** route the notification to the target device\r\n4. **Device receives** the notification instantly via persistent FCM connection\r\n\r\nNo server infrastructure needed on your end - Firebase handles all the heavy lifting! 🚀\r\n\r\n---\r\n\r\n## 📚 Additional Resources\r\n\r\n- [Firebase Cloud Messaging Documentation](https://firebase.google.com/docs/cloud-messaging)\r\n- [Get FCM Device Token (Web)](https://firebase.google.com/docs/cloud-messaging/js/client)\r\n- [Get FCM Device Token (Android)](https://firebase.google.com/docs/cloud-messaging/android/client)\r\n- [Get FCM Device Token (iOS)](https://firebase.google.com/docs/cloud-messaging/ios/client)\r\n\r\n---\r\n\r\n## ⚡ Quick Examples\r\n\r\n### Send notification to multiple devices\r\n\r\n```javascript\r\nconst tokens = ['token1', 'token2', 'token3'];\r\n\r\nfor (const token of tokens) {\r\n  await notifier.push({\r\n    token,\r\n    title: 'Group Notification',\r\n    body: 'Hello everyone!'\r\n  });\r\n}\r\n```\r\n\r\n### Error handling\r\n\r\n```javascript\r\ntry {\r\n  await notifier.push({ token, title, body });\r\n  console.log('✅ Notification sent');\r\n} catch (error) {\r\n  console.error('❌ Failed:', error.message);\r\n}\r\n```\r\n\r\n### Check provider status\r\n\r\n```javascript\r\nconst status = notifier.getStatus();\r\nif (!status.fcm) {\r\n  console.error('FCM not initialized!');\r\n}\r\n```\r\n\r\n---\r\n\r\nMade with ❤️ for seamless notifications\r\n","readmeFilename":"README.md","_rev":"1-925b3c1275f7f7425ffee8ac58c54b2e"}