@flink-app/firebase-messaging-plugin 0.12.1-alpha.4 → 0.12.1-alpha.45

package/.flink/generatedHandlers.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 import { autoRegisteredHandlers, HttpMethod } from "@flink-app/flink";
 import * as PostMessage_0 from "../src/handlers/PostMessage";
 

package/.flink/generatedJobs.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 import { autoRegisteredJobs } from "@flink-app/flink";
 export const jobs = [];
 autoRegisteredJobs.push(...jobs);

package/.flink/generatedRepos.ts

@@ -1,4 +1,4 @@
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
   import { autoRegisteredRepos } from "@flink-app/flink";
   export const repos = [];
   autoRegisteredRepos.push(...repos);

package/.flink/schemas/schemas.ts

@@ -1,7 +1,7 @@
 import Message from "../../src/schemas/Message";
 import SendResult from "../../src/schemas/SendResult";
 
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 export interface PostMessage_12_ReqSchema extends Message {}
 
 export interface PostMessage_12_ResSchema extends SendResult {}

package/.flink/start.ts

@@ -1,5 +1,6 @@
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 import "./generatedHandlers";
 import "./generatedRepos";
 import "./generatedJobs";
 import "../src/index";
+export default {}; // Export an empty object to make it a module

package/dist/.flink/generatedHandlers.js

@@ -24,7 +24,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handlers = void 0;
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 var PostMessage_0 = __importStar(require("../src/handlers/PostMessage"));
 exports.handlers = [{ handler: PostMessage_0, assumedHttpMethod: flink_1.HttpMethod.post }];

package/dist/.flink/generatedJobs.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jobs = void 0;
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.jobs = [];
 flink_1.autoRegisteredJobs.push.apply(flink_1.autoRegisteredJobs, exports.jobs);

package/dist/.flink/generatedRepos.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.repos = void 0;
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 var flink_1 = require("@flink-app/flink");
 exports.repos = [];
 flink_1.autoRegisteredRepos.push.apply(flink_1.autoRegisteredRepos, exports.repos);

package/dist/.flink/start.d.ts

@@ -2,3 +2,5 @@ import "./generatedHandlers";
 import "./generatedRepos";
 import "./generatedJobs";
 import "../src/index";
+declare const _default: {};
+export default _default;

package/dist/.flink/start.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-// Generated Thu Mar 20 2025 15:57:55 GMT+0100 (Central European Standard Time)
+// Generated Sun Nov 23 2025 14:24:04 GMT+0100 (Central European Standard Time)
 require("./generatedHandlers");
 require("./generatedRepos");
 require("./generatedJobs");
 require("../src/index");
+exports.default = {}; // Export an empty object to make it a module

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@flink-app/firebase-messaging-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.45",
     "description": "Flink plugin to send Firebase cloud messages",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
         "build": "flink build",
-        "prepublish": "npm run build",
+        "prepare": "npm run build",
         "watch": "nodemon --exec \"flink build\""
     },
     "author": "joel@frost.se",
@@ -16,11 +16,11 @@
         "access": "public"
     },
     "dependencies": {
-        "@flink-app/management-api-plugin": "^0.12.1-alpha.4",
+        "@flink-app/management-api-plugin": "^0.12.1-alpha.45",
         "firebase-admin": "^12.1.1"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.45",
         "@types/express": "^4.17.12",
         "@types/node": "22.13.10",
         "nodemon": "^2.0.7",
@@ -28,5 +28,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "af426a157217c110ac9c7beb48e2e746968bec33"
 }

package/readme.md

@@ -1,79 +1,633 @@
-# Firebase messaging plugin
+# Firebase Messaging Plugin
 
-**WORK IN PROGRESS 👷‍♀️👷🏻‍♂️**
+A Flink plugin for sending push notifications using Firebase Cloud Messaging (FCM). Send notifications to individual devices or multiple devices with support for both notification and data messages.
 
-A FLINK plugin used for sending push notifications using Firebase (a.k.a. Firebase Cloud Messaging).
+## Installation
 
-## Usage
+Install the plugin to your Flink app project:
 
-Install plugin to your flink app project:
-
-```
-npm i -S @flink-app/firebase-messaging-plugin
+```bash
+npm install @flink-app/firebase-messaging-plugin
 ```
 
-Add and configure plugin in your app startup:
+## Configuration
 
-```
+### Basic Setup
+
+Configure the plugin with your Firebase service account credentials:
+
+```typescript
+import { FlinkApp, FlinkContext } from "@flink-app/flink";
 import { firebaseMessagingPlugin } from "@flink-app/firebase-messaging-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        firebaseMessagingPlugin({
-            serverKey: "YOUR FIREBASE SERVER KEY"
-        })
+      firebaseMessagingPlugin({
+        serviceAccountKey: process.env.FIREBASE_SERVICE_ACCOUNT_KEY_BASE64!,
+        exposeEndpoints: false  // Optional: expose POST /send-message endpoint
+      })
     ],
   }).start();
 }
-
 ```
 
-Add it to your app context (normally `Ctx.ts` in the root folder of your project)
+**Plugin Options:**
 
+```typescript
+interface FirebaseMessagingPluginOptions {
+  serviceAccountKey: string;    // Base64-encoded Firebase service account JSON
+  exposeEndpoints?: boolean;    // Optional: expose HTTP endpoint (default: undefined)
+  permissions?: {
+    send: string;               // Optional: permission required for endpoint
+  };
+}
 ```
+
+### Getting Your Service Account Key
+
+1. Go to Firebase Console > Project Settings > Service Accounts
+2. Click "Generate New Private Key"
+3. Download the JSON file
+4. Base64 encode the JSON file contents:
+   ```bash
+   cat service-account.json | base64
+   ```
+5. Store the base64 string in your environment variable
+
+## TypeScript Setup
+
+Add the plugin context to your app's context type (usually in `Ctx.ts`):
+
+```typescript
+import { FlinkContext } from "@flink-app/flink";
 import { FirebaseMessagingContext } from "@flink-app/firebase-messaging-plugin";
 
 export interface Ctx extends FlinkContext<FirebaseMessagingContext> {
-  ....
+  // Your other context properties
 }
+```
+
+**Plugin Context Interface:**
 
+```typescript
+interface FirebaseMessagingContext {
+  firebaseMessaging: {
+    send: (message: Message) => void;
+  };
+}
 ```
 
-## Configuration
+## Usage in Handlers
+
+### Basic Notification
 
-- `serverKey` - The firebase server key
+Send a simple push notification to a single device:
 
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
+
+const SendNotification: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  await ctx.plugins.firebaseMessaging.send({
+    to: ["device_token_here"],
+    notification: {
+      title: "New Message",
+      body: "You have received a new message"
+    },
+    data: {}
+  });
+
+  return { data: { success: true } };
+};
+
+export default SendNotification;
+```
+
+### Notification to Multiple Devices
+
+Send the same notification to multiple devices:
+
+```typescript
+await ctx.plugins.firebaseMessaging.send({
+  to: [
+    "device_token_1",
+    "device_token_2",
+    "device_token_3"
+  ],
+  notification: {
+    title: "System Update",
+    body: "A new version is available"
+  },
+  data: {
+    version: "2.0.0",
+    updateUrl: "https://example.com/update"
+  }
+});
+```
+
+### Data-Only Message
+
+Send a data message without notification (silent push):
+
+```typescript
+await ctx.plugins.firebaseMessaging.send({
+  to: ["device_token"],
+  data: {
+    type: "sync",
+    timestamp: Date.now().toString(),
+    action: "refresh_data"
+  }
+});
+```
+
+### Rich Notification with Custom Data
+
+```typescript
+const SendOrderUpdate: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  const { userId, orderId, status } = req.body;
+
+  // Get user's device tokens from database
+  const user = await ctx.repos.userRepo.findById(userId);
+  const deviceTokens = user.pushNotificationTokens || [];
+
+  await ctx.plugins.firebaseMessaging.send({
+    to: deviceTokens,
+    notification: {
+      title: "Order Update",
+      body: `Your order #${orderId} is now ${status}`
+    },
+    data: {
+      orderId: orderId,
+      status: status,
+      screen: "order_details",
+      timestamp: Date.now().toString()
+    }
+  });
+
+  return { data: { sent: true } };
+};
+```
 
-## Use as a managementmodule in the management-api-plugin
+## API Reference
+
+### Message Type
+
+```typescript
+interface Message {
+  to: string[];  // Array of FCM device tokens
+
+  notification?: {
+    title?: string;  // Notification title
+    body?: string;   // Notification body text
+  };
+
+  data: { [key: string]: string };  // Custom data payload (all values must be strings)
+}
+```
+
+**Important Notes:**
+- The `data` field is required (can be an empty object `{}`)
+- All values in the `data` object must be strings
+- `notification` is optional - omit it for silent data messages
+- The `send` method processes messages in batches of 500 devices
+
+### Context API
+
+```typescript
+// Send a message
+ctx.plugins.firebaseMessaging.send(message: Message): void
+```
+
+The `send` method:
+- Processes devices in batches of 500 (FCM limitation)
+- Logs success/failure for each device to debug logs
+- Handles errors gracefully without throwing
+
+## Registered Endpoints
+
+If `exposeEndpoints` is enabled, the plugin registers:
+
+### POST /send-message
+
+Send a push notification via HTTP endpoint.
+
+**Request Body:**
+```typescript
+{
+  to: string[];           // Device tokens
+  notification?: {
+    title?: string;
+    body?: string;
+  };
+  data: { [key: string]: string };
+}
+```
+
+**Response:**
+```typescript
+{
+  data: {
+    failedDevices: string[]  // Currently returns empty array
+  }
+}
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:3000/send-message \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": ["device_token_123"],
+    "notification": {
+      "title": "Hello",
+      "body": "World"
+    },
+    "data": {}
+  }'
+```
+
+**Permissions:**
+- Default permission: `firebase-messaging:send`
+- Can be customized via `permissions.send` option
+
+## Complete Example
+
+Here's a complete example showing different notification scenarios:
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import { Ctx } from "../Ctx";
+
+interface NotificationRequest {
+  userIds: string[];
+  type: "message" | "order" | "reminder" | "alert";
+  title: string;
+  body: string;
+  data?: Record<string, any>;
+}
+
+const SendPushNotification: Handler<Ctx, NotificationRequest, { sent: number }> = async ({
+  ctx,
+  req
+}) => {
+  const { userIds, type, title, body, data = {} } = req.body;
+
+  // Collect device tokens from all users
+  const users = await ctx.repos.userRepo.findByIds(userIds);
+  const deviceTokens: string[] = [];
+
+  for (const user of users) {
+    if (user.pushTokens && user.pushTokens.length > 0) {
+      deviceTokens.push(...user.pushTokens);
+    }
+  }
+
+  if (deviceTokens.length === 0) {
+    return { data: { sent: 0 } };
+  }
+
+  // Convert data values to strings (FCM requirement)
+  const stringData: { [key: string]: string } = {};
+  for (const [key, value] of Object.entries(data)) {
+    stringData[key] = String(value);
+  }
+
+  // Add metadata
+  stringData.type = type;
+  stringData.sentAt = new Date().toISOString();
+
+  // Send notification
+  await ctx.plugins.firebaseMessaging.send({
+    to: deviceTokens,
+    notification: {
+      title,
+      body
+    },
+    data: stringData
+  });
 
-Initiate the module and configure it:
+  return { data: { sent: deviceTokens.length } };
+};
 
+export default SendPushNotification;
 ```
-import { GetManagementModule as GetNotificationManagementModule } from "@flink-app/firebase-messaging-plugin"
-const notificationManagementModule = GetNotificationManagementModule({
+
+## Management API Integration
+
+The plugin can be integrated with the Management API for advanced notification management:
+
+### Setup Management Module
+
+```typescript
+import {
+  firebaseMessagingPlugin,
+  GetManagementModule
+} from "@flink-app/firebase-messaging-plugin";
+import { managementApiPlugin } from "@flink-app/management-api-plugin";
+
+// Define user segments for targeting
+const notificationManagementModule = GetManagementModule({
   ui: true,
   uiSettings: {
-      title: "Notifications"
+    title: "Push Notifications"
   },
-  segments : [{
-    id : "all", 
-    description : "All app users", 
-    handler : async (ctx : Ctx) => {
-      const users = await ctx.repos.userRepo.findAll({})
-      return users.map(u=>({
-        userId : u._id.toString(),
-        pushToken : u.pushNotificationTokens.map(p=>p.token)
-      }))
+  segments: [
+    {
+      id: "all",
+      description: "All users",
+      handler: async (ctx: Ctx) => {
+        const users = await ctx.repos.userRepo.findAll({});
+        return users.map(u => ({
+          userId: u._id.toString(),
+          pushToken: u.pushNotificationTokens || []
+        }));
+      }
     },
-   
-  }],
-  data : [],
-})
+    {
+      id: "active",
+      description: "Active users (last 7 days)",
+      handler: async (ctx: Ctx) => {
+        const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+        const users = await ctx.repos.userRepo.findAll({
+          lastActiveAt: { $gte: sevenDaysAgo }
+        });
+        return users.map(u => ({
+          userId: u._id.toString(),
+          pushToken: u.pushNotificationTokens || []
+        }));
+      }
+    }
+  ],
+  data: [
+    {
+      id: "messageType",
+      description: "Message Type",
+      options: ["announcement", "update", "reminder", "alert"]
+    }
+  ],
+  messageSentCallback: async (ctx, targets, message) => {
+    // Log notification send event
+    console.log(`Sent notification to ${targets.length} users`);
+
+    // Store in database
+    await ctx.repos.notificationLogRepo.create({
+      sentAt: new Date(),
+      recipientCount: targets.length,
+      message: message
+    });
+  }
+});
+
+function start() {
+  new FlinkApp<Ctx>({
+    name: "My app",
+    plugins: [
+      firebaseMessagingPlugin({
+        serviceAccountKey: process.env.FIREBASE_SERVICE_ACCOUNT_KEY!
+      }),
+      managementApiPlugin({
+        token: process.env.MGMT_TOKEN!,
+        jwtSecret: process.env.JWT_SECRET!,
+        modules: [notificationManagementModule]
+      })
+    ]
+  }).start();
+}
+```
+
+### Management Module Types
+
+```typescript
+interface GetManagementModuleConfig {
+  pluginId?: string;           // Default: "managementNotificationsApi"
+  ui: boolean;                 // Enable UI in admin panel
+  uiSettings?: {
+    title: string;             // Module title in UI
+  };
+  segments: MessagingSegment[]; // User segments for targeting
+  data?: MessagingData[];      // Additional data fields
+  messageSentCallback?: (      // Callback after sending
+    ctx: any,
+    targets: MessagingTarget[],
+    message: Message
+  ) => void;
+}
+
+interface MessagingSegment {
+  id: string;
+  description: string;
+  handler: (ctx: FlinkContext<any>) => Promise<MessagingTarget[]>;
+}
+
+interface MessagingTarget {
+  userId: string;
+  pushToken: string[];
+}
+
+interface MessagingData {
+  id: string;
+  description: string;
+  options?: string[];
+}
+```
+
+### Management Endpoints
+
+When using the Management Module, these endpoints are registered:
+
+#### GET /managementapi/{pluginId}
+Get module information including segments and data fields.
+
+#### POST /managementapi/{pluginId}/message
+Send notification to a segment.
+
+**Request:**
+```typescript
+{
+  segmentId: string;
+  notification: {
+    title: string;
+    body: string;
+  };
+  data: { [key: string]: string };
+}
+```
+
+## Best Practices
+
+### Device Token Management
+
+Store and manage device tokens properly:
+
+```typescript
+// When user logs in or registers device
+const RegisterDeviceToken: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  const { userId, deviceToken } = req.body;
+
+  await ctx.repos.userRepo.update(userId, {
+    $addToSet: { pushTokens: deviceToken }  // Avoid duplicates
+  });
+
+  return { data: { success: true } };
+};
+
+// When user logs out
+const RemoveDeviceToken: Handler<Ctx, any, any> = async ({ ctx, req }) => {
+  const { userId, deviceToken } = req.body;
+
+  await ctx.repos.userRepo.update(userId, {
+    $pull: { pushTokens: deviceToken }
+  });
+
+  return { data: { success: true } };
+};
 ```
 
+### Data Payload Conversion
 
+Always convert data values to strings:
 
+```typescript
+// Bad - will fail
+data: {
+  userId: 123,           // Number
+  isActive: true,        // Boolean
+  metadata: { foo: "bar" } // Object
+}
+
+// Good - all strings
+data: {
+  userId: "123",
+  isActive: "true",
+  metadata: JSON.stringify({ foo: "bar" })
+}
+```
+
+### Notification vs Data Messages
+
+**Notification Messages:**
+- Display a notification in the system tray
+- Wake up the app when tapped
+- Best for user-facing alerts
+
+**Data Messages:**
+- Silent delivery to app
+- App handles processing
+- Best for background sync, state updates
+
+```typescript
+// Notification message (user sees it)
+{
+  notification: { title: "New message", body: "John sent you a message" },
+  data: { chatId: "123" }
+}
+
+// Data message (silent)
+{
+  data: { type: "sync", lastSyncTimestamp: "1234567890" }
+}
+```
+
+### Batch Processing
+
+The plugin automatically handles batching (500 devices per batch), but you should still consider:
+
+```typescript
+// Good - let the plugin handle batching
+await ctx.plugins.firebaseMessaging.send({
+  to: thousandsOfTokens,  // Plugin splits into batches of 500
+  notification: { title: "Update", body: "New feature available" },
+  data: {}
+});
+
+// Also good - send to specific segments
+const activeUsers = await ctx.repos.userRepo.findActive();
+const tokens = activeUsers.flatMap(u => u.pushTokens || []);
+await ctx.plugins.firebaseMessaging.send({
+  to: tokens,
+  notification: { title: "Hello active users!", body: "..." },
+  data: {}
+});
+```
+
+### Error Handling
+
+The plugin logs errors internally but doesn't throw. Monitor logs:
+
+```typescript
+// The plugin logs:
+// - Success: "[firebaseMessaging] Successfully sent to device {token}"
+// - Failure: "[firebaseMessaging] Failed sending to device {token}: {error}"
+// - Batch error: "[firebaseMessaging] Failed sending batch: {error}"
+
+// You can wrap sends with try-catch if needed
+try {
+  await ctx.plugins.firebaseMessaging.send({
+    to: deviceTokens,
+    notification: { title: "Test", body: "Test" },
+    data: {}
+  });
+} catch (error) {
+  console.error("Unexpected error:", error);
+}
+```
+
+## Troubleshooting
+
+### Notifications Not Received
+
+1. **Invalid device tokens** - Tokens expire or become invalid
+   - Implement token refresh on the client side
+   - Remove invalid tokens from your database
+
+2. **Service account permissions** - Verify the service account has FCM permissions
+   - Check Firebase Console > Project Settings > Service Accounts
+   - Ensure "Firebase Admin SDK" role is granted
+
+3. **Base64 encoding** - Ensure service account key is properly encoded
+   ```bash
+   # Verify decoding works
+   echo $FIREBASE_SERVICE_ACCOUNT_KEY_BASE64 | base64 -d
+   ```
+
+4. **App not running** - Data messages require the app to be running
+   - Use notification messages to wake the app
+   - Combine notification + data for best results
+
+### Invalid Data Format
+
+Error: "All data values must be strings"
+
+```typescript
+// Fix: Convert all values to strings
+data: {
+  count: String(42),
+  timestamp: new Date().toISOString(),
+  metadata: JSON.stringify({ key: "value" })
+}
+```
+
+### Check Debug Logs
+
+Enable Flink debug mode to see detailed FCM logs:
+
+```typescript
+new FlinkApp<Ctx>({
+  name: "My app",
+  debug: true,  // Enable debug logging
+  plugins: [
+    firebaseMessagingPlugin({ ... })
+  ]
+}).start();
+```
 
+## Notes
 
+- Messages are processed in batches of 500 devices (FCM limitation)
+- All data values must be strings (numbers, booleans, objects must be converted)
+- The plugin uses Firebase Admin SDK v11+
+- Device tokens should be stored securely and updated regularly
+- Invalid/expired tokens are logged but don't stop delivery to other devices
+- The `send` method is fire-and-forget (doesn't wait for delivery confirmation)