@quatrain/messaging-firebase 1.0.2 → 1.0.3

package/LICENSE.md

@@ -0,0 +1,15 @@
+# LICENSE UPDATE NOTICE
+
+As of 01/01/2026, Quatrain Core is licensed under the **GNU Affero General Public License v3.0 (AGPL v3)**.
+Previous versions remain under the MIT License.
+
+## Why AGPL?
+
+We believe in open collaboration for the development ecosystem. The AGPL ensures that any modification or deployment of this BaaS stack, including over a network, benefits the entire community.
+
+## Commercial Services & Enterprise Usage
+
+We provide official deployment services, technical training, and certification for Quatrain Core.
+For organizations requiring a non-copyleft license (commercial license) or custom proprietary integrations, please contact the copyright holder: **Quatrain Technologies**.
+
+Copyright © 2024-2026 Quatrain Technologies. All Rights Reserved.

package/package.json

@@ -1,41 +1,40 @@
 {
-  "name": "@quatrain/messaging-firebase",
-  "version": "1.0.2",
-  "license": "MIT",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "files": [
-    "lib/",
-    "README.md"
-  ],
-  "author": "Quatrain Développement SAS <developers@quatrain.com>",
-  "peerDependencies": {
-    "@quatrain/core": "^1.1.19"
-  },
-  "dependencies": {
-    "@quatrain/messaging": "^1.0.3",
-    "firebase-admin": "^13.0.1"
-  },
-  "devDependencies": {
-    "@tsconfig/recommended": "^1.0.1",
-    "@types/jest": "^27.0.3",
-    "@types/node": "^22.10.1",
-    "jest": "^27.4.7",
-    "jest-node-exports-resolver": "^1.1.6",
-    "jest-serial-runner": "^1.2.1",
-    "trace-unhandled": "^2.0.1",
-    "ts-jest": "^27.1.2",
-    "typescript": "^5.1.5"
-  },
-  "scripts": {
-    "build": "tsc",
-    "wbuild": "tsc --watch",
-    "test": "jest",
-    "bump-to": "yarn version",
-    "hash": "node ../../bin/hashFolder.js",
-    "hash:persist": "yarn hash  > .hash_latest.txt",
-    "hash:compare": "yarn hash > .hash_newest.txt && cmp -s .hash_latest.txt .hash_newest.txt",
-    "publish": "yarn hash:compare || yarn publish:process",
-    "publish:process": "yarn version patch && yarn build && yarn npm publish --access public && yarn hash:persist"
-  }
-}
+   "name": "@quatrain/messaging-firebase",
+   "version": "1.0.3",
+   "license": "AGPL-3.0-only",
+   "main": "lib/index.js",
+   "types": "lib/index.d.ts",
+   "bun": "src/index.ts",
+   "files": [
+      "LICENSE.md",
+      "src/",
+      "lib/",
+      "README.md"
+   ],
+   "author": "Quatrain Développement SAS <developers@quatrain.com>",
+   "peerDependencies": {
+      "@quatrain/core": "^1.1.43"
+   },
+   "dependencies": {
+      "@quatrain/core": "^1.1.43",
+      "@quatrain/messaging": "^1.0.4",
+      "firebase-admin": "^13.0.1"
+   },
+   "devDependencies": {
+      "@tsconfig/recommended": "^1.0.1",
+      "@types/jest": "^27.0.3",
+      "@types/node": "^22.10.1",
+      "jest": "^30.2.0",
+      "jest-node-exports-resolver": "^1.1.6",
+      "jest-serial-runner": "^1.2.1",
+      "trace-unhandled": "^2.0.1",
+      "ts-jest": "^27.1.2",
+      "typescript": "^5.1.5"
+   },
+   "scripts": {
+      "build": "tsc",
+      "wbuild": "tsc --watch",
+      "test": "jest",
+      "bump-to": "yarn version"
+   }
+}

package/src/FirebaseMessagingAdapter.ts

@@ -0,0 +1,142 @@
+import {
+   AbstractMessagingAdapter,
+   Messaging,
+   MessagingParameters,
+   MessagingRecipient,
+   NotificationCapableAdapter,
+   NotificationMessage,
+} from '@quatrain/messaging'
+import { credential } from 'firebase-admin'
+import { getApps, initializeApp, ServiceAccount } from 'firebase-admin/app'
+import { getMessaging, Message } from 'firebase-admin/messaging'
+
+export class FirebaseMessagingAdapter
+   extends AbstractMessagingAdapter
+   implements NotificationCapableAdapter
+{
+   protected _messaging: any
+
+   constructor(params: MessagingParameters = {}) {
+      super(params)
+      this._initializeFirebase()
+   }
+
+   protected _initializeFirebase() {
+      try {
+         if (getApps().length === 0) {
+            if (!this._params.config) {
+               throw new Error('Firebase config is required')
+            }
+            const serviceAccount: ServiceAccount = this._params.config
+            initializeApp({
+               credential: credential.cert(serviceAccount),
+               databaseURL: this._params.config.databaseURL,
+            })
+         }
+         this._messaging = getMessaging()
+      } catch (error) {
+         Messaging.error(
+            `Failed to initialize Firebase: ${(error as Error).message}`
+         )
+         throw error
+      }
+   }
+
+   /**
+    * Sends a notification to a single recipient via Firebase Cloud Messaging
+    *
+    * @param recipient - The message recipient containing contact info and FCM token
+    * @param message - The notification message with title, body, and optional data
+    * @returns Promise<string> - The Firebase message ID on successful delivery
+    * @throws Error if recipient has no message token or Firebase send fails
+    */
+   async sendNotification(
+      recipient: MessagingRecipient,
+      message: NotificationMessage
+   ): Promise<string> {
+      try {
+         if (!recipient.messageToken) {
+            throw new Error('Recipient message token is required')
+         }
+
+         const firebaseMessage: Message = {
+            token: message.token || recipient.messageToken,
+            notification: {
+               title: message.title,
+               body: message.body || '',
+            },
+            data: this._serializeData(message.data || {}),
+         }
+
+         const response = await this._messaging.send(firebaseMessage)
+
+         Messaging.info(
+            `Notification sent successfully to ${recipient.firstname} ${recipient.lastname}: ${response}`
+         )
+
+         return response
+      } catch (error) {
+         const errorMessage = `Failed to send notification to ${
+            recipient.firstname
+         } ${recipient.lastname}: ${(error as Error).message}`
+         Messaging.error(errorMessage)
+         throw new Error(errorMessage)
+      }
+   }
+
+   async sendNotifications(
+      recipients: MessagingRecipient[],
+      message: NotificationMessage
+   ): Promise<{
+      successCount: number
+      failureCount: number
+      responses: any[]
+   }> {
+      try {
+         const tokens = recipients
+            .map((recipient) => recipient.messageToken)
+            .filter((token) => token) as string[]
+
+         if (tokens.length === 0) {
+            throw new Error('No valid message tokens found')
+         }
+
+         const multicastMessage = {
+            tokens,
+            notification: {
+               title: message.title,
+               body: message.body || '',
+            },
+            data: this._serializeData(message.data || {}),
+         }
+
+         const response = await this._messaging.sendMulticast(multicastMessage)
+
+         Messaging.info(
+            `Multicast notification sent: ${response.successCount} successful, ${response.failureCount} failed`
+         )
+
+         return response
+      } catch (error) {
+         const errorMessage = `Failed to send multicast notification: ${
+            (error as Error).message
+         }`
+         Messaging.error(errorMessage)
+         throw new Error(errorMessage)
+      }
+   }
+
+   private _serializeData(data: any): Record<string, string> {
+      const serialized: Record<string, string> = {}
+
+      for (const [key, value] of Object.entries(data)) {
+         if (typeof value === 'string') {
+            serialized[key] = value
+         } else {
+            serialized[key] = JSON.stringify(value)
+         }
+      }
+
+      return serialized
+   }
+}

package/src/__test__/FirebaseMessagingAdapter.test.ts

@@ -0,0 +1,175 @@
+import { FirebaseMessagingAdapter } from '../FirebaseMessagingAdapter'
+import { MessagingRecipient, NotificationMessage } from '@quatrain/messaging'
+
+// Mock Firebase Admin SDK
+jest.mock('firebase-admin/app', () => ({
+   getApps: jest.fn(() => []),
+   initializeApp: jest.fn()
+}))
+
+jest.mock('firebase-admin/messaging', () => ({
+   getMessaging: jest.fn(() => ({
+      send: jest.fn().mockResolvedValue('message-id-123'),
+      sendMulticast: jest.fn().mockResolvedValue({
+         successCount: 2,
+         failureCount: 0,
+         responses: [
+            { success: true, messageId: 'msg-1' },
+            { success: true, messageId: 'msg-2' }
+         ]
+      })
+   }))
+}))
+
+describe('FirebaseMessagingAdapter', () => {
+   let adapter: FirebaseMessagingAdapter
+   const mockConfig = {
+      projectId: 'test-project',
+      privateKey: 'mock-private-key',
+      clientEmail: 'test@test.com'
+   }
+
+   beforeEach(() => {
+      jest.clearAllMocks()
+      adapter = new FirebaseMessagingAdapter({
+         config: mockConfig
+      })
+   })
+
+   describe('constructor', () => {
+      test('should initialize with config', () => {
+         expect(adapter).toBeInstanceOf(FirebaseMessagingAdapter)
+      })
+
+      test('should throw error without config', () => {
+         expect(() => {
+            new FirebaseMessagingAdapter({})
+         }).toThrow('Firebase config is required')
+      })
+   })
+
+   describe('sendNotification', () => {
+      const mockRecipient: MessagingRecipient = {
+         firstname: 'John',
+         lastname: 'Doe',
+         email: 'john@example.com',
+         messageToken: 'mock-token-123'
+      }
+
+      const mockMessage: NotificationMessage = {
+         title: 'Test Notification',
+         body: 'This is a test message',
+         data: { userId: '123', action: 'test' }
+      }
+
+      test('should send notification successfully', async () => {
+         const result = await adapter.sendNotification(mockRecipient, mockMessage)
+         expect(result).toBe('message-id-123')
+      })
+
+      test('should throw error when recipient has no message token', async () => {
+         const recipientWithoutToken = { ...mockRecipient, messageToken: undefined }
+         
+         await expect(
+            adapter.sendNotification(recipientWithoutToken, mockMessage)
+         ).rejects.toThrow('Recipient message token is required')
+      })
+
+      test('should use message token from message if provided', async () => {
+         const messageWithToken = { ...mockMessage, token: 'custom-token' }
+         
+         const result = await adapter.sendNotification(mockRecipient, messageWithToken)
+         expect(result).toBe('message-id-123')
+      })
+
+      test('should handle empty body gracefully', async () => {
+         const messageWithoutBody = { ...mockMessage, body: undefined }
+         
+         const result = await adapter.sendNotification(mockRecipient, messageWithoutBody)
+         expect(result).toBe('message-id-123')
+      })
+   })
+
+   describe('sendMulticast', () => {
+      const mockRecipients: MessagingRecipient[] = [
+         {
+            firstname: 'John',
+            lastname: 'Doe',
+            email: 'john@example.com',
+            messageToken: 'token-1'
+         },
+         {
+            firstname: 'Jane',
+            lastname: 'Smith',
+            email: 'jane@example.com',
+            messageToken: 'token-2'
+         }
+      ]
+
+      const mockMessage: NotificationMessage = {
+         title: 'Multicast Test',
+         body: 'This is a multicast message'
+      }
+
+      test('should send multicast notification successfully', async () => {
+         const result = await adapter.sendMulticast(mockRecipients, mockMessage)
+         
+         expect(result.successCount).toBe(2)
+         expect(result.failureCount).toBe(0)
+         expect(result.responses).toHaveLength(2)
+      })
+
+      test('should filter out recipients without tokens', async () => {
+         const recipientsWithMissingTokens = [
+            ...mockRecipients,
+            {
+               firstname: 'Bob',
+               lastname: 'Wilson',
+               email: 'bob@example.com',
+               messageToken: undefined
+            }
+         ]
+
+         const result = await adapter.sendMulticast(recipientsWithMissingTokens, mockMessage)
+         expect(result.successCount).toBe(2)
+      })
+
+      test('should throw error when no valid tokens found', async () => {
+         const recipientsWithoutTokens = mockRecipients.map(r => ({ 
+            ...r, 
+            messageToken: undefined 
+         }))
+
+         await expect(
+            adapter.sendMulticast(recipientsWithoutTokens, mockMessage)
+         ).rejects.toThrow('No valid message tokens found')
+      })
+   })
+
+   describe('_serializeData', () => {
+      test('should serialize complex data correctly', () => {
+         const adapter = new FirebaseMessagingAdapter({ config: mockConfig })
+         const testData = {
+            stringValue: 'test',
+            numberValue: 123,
+            booleanValue: true,
+            objectValue: { nested: 'object' },
+            arrayValue: [1, 2, 3]
+         }
+
+         const result = (adapter as any)._serializeData(testData)
+
+         expect(result.stringValue).toBe('test')
+         expect(result.numberValue).toBe('123')
+         expect(result.booleanValue).toBe('true')
+         expect(result.objectValue).toBe('{"nested":"object"}')
+         expect(result.arrayValue).toBe('[1,2,3]')
+      })
+
+      test('should handle empty data', () => {
+         const adapter = new FirebaseMessagingAdapter({ config: mockConfig })
+         const result = (adapter as any)._serializeData({})
+         expect(result).toEqual({})
+      })
+   })
+})

package/src/index.ts

@@ -0,0 +1,3 @@
+import { FirebaseMessagingAdapter } from './FirebaseMessagingAdapter'
+
+export { FirebaseMessagingAdapter }