@codaijs/keel 0.1.0

package/sails/push-notifications/README.md

@@ -0,0 +1,163 @@
+# Push Notifications Sail
+
+Adds push notification support to your keel application using Capacitor and Firebase Cloud Messaging (FCM).
+
+## Features
+
+- Firebase Cloud Messaging for push delivery (iOS, Android)
+- Capacitor integration for native device token management
+- Device token registration and storage in PostgreSQL
+- Server-side notification sending via firebase-admin
+- React hook for permission handling, token lifecycle, and notification taps
+- Automatic deep-link navigation on notification tap
+
+## Prerequisites
+
+- A Firebase project (https://console.firebase.google.com)
+- Cloud Messaging API (V1) enabled in the Firebase project
+- A Firebase service account JSON key file
+- For iOS: An APNs authentication key from Apple Developer
+
+## Installation
+
+```bash
+npx tsx sails/push-notifications/install.ts
+```
+
+The installer will guide you through Firebase setup and collect your service account credentials.
+
+## Manual Setup
+
+### 1. Firebase Project
+
+1. Go to https://console.firebase.google.com
+2. Create a new project (or select existing)
+3. Go to **Project Settings > Cloud Messaging**
+4. Ensure Cloud Messaging API (V1) is enabled
+
+### 2. Service Account Key
+
+1. Go to **Project Settings > Service Accounts**
+2. Click **Generate new private key**
+3. Download the JSON file
+4. Extract these values for your `.env`:
+
+```env
+FIREBASE_PROJECT_ID=your-project-id
+FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com
+```
+
+### 3. iOS Configuration (APNs)
+
+1. Go to https://developer.apple.com/account/resources/authkeys/list
+2. Create a new key, check **Apple Push Notifications service (APNs)**
+3. Download the `.p8` key file
+4. In Firebase Console > Project Settings > Cloud Messaging > iOS app:
+   - Upload the APNs authentication key
+   - Enter the Key ID and Team ID
+5. Run `npx cap sync ios`
+
+### 4. Android Configuration
+
+1. In Firebase Console, add an Android app (use your app's package name)
+2. Download `google-services.json`
+3. Place it at `android/app/google-services.json`
+4. Run `npx cap sync android`
+
+## Architecture
+
+### Database Schema
+
+**push_tokens**
+| Column | Type | Description |
+|--------|------|-------------|
+| id | text | Primary key (UUID) |
+| user_id | text | FK to users table (cascade delete) |
+| token | text | FCM device token |
+| platform | varchar(20) | ios, android, or web |
+| created_at | timestamp | Registration time |
+
+### API Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /api/notifications/register | Yes | Register a device push token |
+| DELETE | /api/notifications/unregister | Yes | Remove a device push token |
+| POST | /api/notifications/send | Yes | Send a notification to a user |
+
+### Backend Service
+
+The `notifications` service provides two functions:
+
+```typescript
+import {
+  sendPushNotification,
+  sendMultiplePushNotifications,
+} from "./services/notifications.js";
+
+// Send to a single device
+await sendPushNotification(token, "Title", "Body", { route: "/notifications" });
+
+// Send to multiple devices
+await sendMultiplePushNotifications(tokens, "Title", "Body");
+```
+
+### Frontend Hook
+
+```tsx
+import { usePushNotifications } from "@/hooks/usePushNotifications";
+
+function MyComponent() {
+  const { isRegistered, permissionStatus, register, unregister } =
+    usePushNotifications();
+
+  return (
+    <div>
+      <p>Permission: {permissionStatus}</p>
+      <p>Registered: {isRegistered ? "Yes" : "No"}</p>
+      <button onClick={register}>Enable Notifications</button>
+      <button onClick={unregister}>Disable Notifications</button>
+    </div>
+  );
+}
+```
+
+### PushNotificationInit Component
+
+The `<PushNotificationInit />` component is placed in `Layout.tsx` and silently handles push registration on app mount. It renders nothing visible.
+
+### Deep Linking
+
+When a user taps a notification, the hook checks for a `route` field in the notification data payload and navigates to it:
+
+```typescript
+// When sending a notification, include a route:
+await sendPushNotification(token, "New Message", "You have a new message", {
+  route: "/messages/123",
+});
+```
+
+## Testing
+
+Push notifications **only work on physical devices**, not simulators or emulators.
+
+### Sending Test Notifications
+
+1. **Firebase Console**: Go to Messaging > Create your first campaign > Notifications
+2. **API endpoint**: `POST /api/notifications/send` with body:
+   ```json
+   {
+     "userId": "user-id-here",
+     "title": "Test Notification",
+     "body": "This is a test push notification",
+     "data": { "route": "/profile" }
+   }
+   ```
+
+### Debugging
+
+- Check the browser/device console for registration logs
+- Check server logs for firebase-admin errors
+- Verify the FCM token is stored in the `push_tokens` table
+- Make sure APNs (iOS) or google-services.json (Android) are configured correctly

package/sails/push-notifications/addon.json

@@ -0,0 +1,31 @@
+{
+  "name": "push-notifications",
+  "displayName": "Push Notifications",
+  "description": "Push notifications via Capacitor + Firebase Cloud Messaging with device token management and server-side sending",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [
+    { "key": "FIREBASE_PROJECT_ID", "description": "Firebase project ID (from Firebase Console > Project Settings)" },
+    { "key": "FIREBASE_PRIVATE_KEY", "description": "Firebase service account private key (the full PEM key including -----BEGIN/END-----)" },
+    { "key": "FIREBASE_CLIENT_EMAIL", "description": "Firebase service account client email (e.g., firebase-adminsdk-xxxxx@project.iam.gserviceaccount.com)" }
+  ],
+  "dependencies": {
+    "backend": { "firebase-admin": "^13.0.0" },
+    "frontend": { "@capacitor/push-notifications": "^6.0.0" }
+  },
+  "modifies": {
+    "backend": ["src/index.ts", "src/db/schema/index.ts", "src/env.ts"],
+    "frontend": ["src/components/layout/Layout.tsx"]
+  },
+  "adds": {
+    "backend": [
+      "src/db/schema/notifications.ts",
+      "src/routes/notifications.ts",
+      "src/services/notifications.ts"
+    ],
+    "frontend": [
+      "src/hooks/usePushNotifications.ts",
+      "src/components/PushNotificationInit.tsx"
+    ]
+  }
+}

package/sails/push-notifications/files/backend/routes/notifications.ts

@@ -0,0 +1,153 @@
+import { Router, type Request, type Response } from "express";
+import { eq, and } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { pushTokens } from "../db/schema/notifications.js";
+import {
+  sendPushNotification,
+  sendMultiplePushNotifications,
+} from "../services/notifications.js";
+import { requireAuth } from "../middleware/auth.js";
+
+export const notificationsRouter = Router();
+
+// ---------------------------------------------------------------------------
+// POST /register — Register a device push token
+// ---------------------------------------------------------------------------
+
+notificationsRouter.post(
+  "/register",
+  requireAuth,
+  async (req: Request, res: Response) => {
+    try {
+      const { token, platform } = req.body;
+
+      if (!token || typeof token !== "string") {
+        return res.status(400).json({ error: "token is required" });
+      }
+
+      const userId = req.user!.id;
+
+      // Check if this token is already registered for this user
+      const existing = await db.query.pushTokens.findFirst({
+        where: and(
+          eq(pushTokens.userId, userId),
+          eq(pushTokens.token, token),
+        ),
+      });
+
+      if (existing) {
+        return res.json({ message: "Token already registered", id: existing.id });
+      }
+
+      // Insert the new token
+      const [inserted] = await db
+        .insert(pushTokens)
+        .values({
+          userId,
+          token,
+          platform: platform ?? null,
+        })
+        .returning({ id: pushTokens.id });
+
+      return res.status(201).json({ message: "Token registered", id: inserted.id });
+    } catch (error) {
+      console.error("Error registering push token:", error);
+      return res.status(500).json({ error: "Failed to register push token" });
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// DELETE /unregister — Remove a device push token
+// ---------------------------------------------------------------------------
+
+notificationsRouter.delete(
+  "/unregister",
+  requireAuth,
+  async (req: Request, res: Response) => {
+    try {
+      const { token } = req.body;
+
+      if (!token || typeof token !== "string") {
+        return res.status(400).json({ error: "token is required" });
+      }
+
+      const userId = req.user!.id;
+
+      await db
+        .delete(pushTokens)
+        .where(
+          and(
+            eq(pushTokens.userId, userId),
+            eq(pushTokens.token, token),
+          ),
+        );
+
+      return res.json({ message: "Token unregistered" });
+    } catch (error) {
+      console.error("Error unregistering push token:", error);
+      return res.status(500).json({ error: "Failed to unregister push token" });
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// POST /send — Send a notification to a user (admin/internal use)
+// ---------------------------------------------------------------------------
+
+notificationsRouter.post(
+  "/send",
+  requireAuth,
+  async (req: Request, res: Response) => {
+    try {
+      const { userId, title, body, data } = req.body;
+
+      if (!userId || typeof userId !== "string") {
+        return res.status(400).json({ error: "userId is required" });
+      }
+      if (!title || typeof title !== "string") {
+        return res.status(400).json({ error: "title is required" });
+      }
+      if (!body || typeof body !== "string") {
+        return res.status(400).json({ error: "body is required" });
+      }
+
+      // Fetch all tokens for the target user
+      const tokens = await db.query.pushTokens.findMany({
+        where: eq(pushTokens.userId, userId),
+      });
+
+      if (tokens.length === 0) {
+        return res.status(404).json({ error: "No push tokens found for user" });
+      }
+
+      const tokenStrings = tokens.map((t) => t.token);
+
+      if (tokenStrings.length === 1) {
+        const messageId = await sendPushNotification(
+          tokenStrings[0],
+          title,
+          body,
+          data,
+        );
+        return res.json({ message: "Notification sent", messageId });
+      }
+
+      const result = await sendMultiplePushNotifications(
+        tokenStrings,
+        title,
+        body,
+        data,
+      );
+
+      return res.json({
+        message: "Notifications sent",
+        successCount: result.successCount,
+        failureCount: result.failureCount,
+      });
+    } catch (error) {
+      console.error("Error sending push notification:", error);
+      return res.status(500).json({ error: "Failed to send notification" });
+    }
+  },
+);

package/sails/push-notifications/files/backend/schema/notifications.ts

@@ -0,0 +1,31 @@
+import { pgTable, text, varchar, timestamp } from "drizzle-orm/pg-core";
+import { relations } from "drizzle-orm";
+import { users } from "./users.js";
+
+/**
+ * Push notification device tokens table.
+ *
+ * Stores FCM device tokens for each user. A user can have multiple tokens
+ * (one per device). Tokens are registered when the user grants push permission
+ * on a native device and removed on logout or token invalidation.
+ */
+export const pushTokens = pgTable("push_tokens", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  userId: text("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  token: text("token").notNull(),
+  platform: varchar("platform", { length: 20 }),
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+});
+
+export const pushTokensRelations = relations(pushTokens, ({ one }) => ({
+  user: one(users, {
+    fields: [pushTokens.userId],
+    references: [users.id],
+  }),
+}));

package/sails/push-notifications/files/backend/services/notifications.ts

@@ -0,0 +1,117 @@
+import admin from "firebase-admin";
+import { env } from "../env.js";
+
+// ---------------------------------------------------------------------------
+// Firebase Admin initialization
+// ---------------------------------------------------------------------------
+
+if (!admin.apps.length) {
+  admin.initializeApp({
+    credential: admin.credential.cert({
+      projectId: env.FIREBASE_PROJECT_ID,
+      privateKey: env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, "\n"),
+      clientEmail: env.FIREBASE_CLIENT_EMAIL,
+    }),
+  });
+}
+
+const messaging = admin.messaging();
+
+// ---------------------------------------------------------------------------
+// Send a push notification to a single device
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a push notification to a single device token.
+ *
+ * @param token  - The FCM device token
+ * @param title  - Notification title
+ * @param body   - Notification body text
+ * @param data   - Optional key-value data payload (for deep linking, etc.)
+ * @returns The message ID from Firebase
+ */
+export async function sendPushNotification(
+  token: string,
+  title: string,
+  body: string,
+  data?: Record<string, string>,
+): Promise<string> {
+  const message: admin.messaging.Message = {
+    token,
+    notification: {
+      title,
+      body,
+    },
+    data,
+    android: {
+      priority: "high",
+      notification: {
+        sound: "default",
+        channelId: "default",
+      },
+    },
+    apns: {
+      payload: {
+        aps: {
+          sound: "default",
+          badge: 1,
+        },
+      },
+    },
+  };
+
+  return messaging.send(message);
+}
+
+// ---------------------------------------------------------------------------
+// Send push notifications to multiple devices
+// ---------------------------------------------------------------------------
+
+/**
+ * Send a push notification to multiple device tokens.
+ *
+ * Uses `sendEachForMulticast` to handle per-token delivery. Returns the
+ * batch response so callers can check individual success/failure.
+ *
+ * @param tokens - Array of FCM device tokens
+ * @param title  - Notification title
+ * @param body   - Notification body text
+ * @param data   - Optional key-value data payload
+ * @returns The batch response from Firebase
+ */
+export async function sendMultiplePushNotifications(
+  tokens: string[],
+  title: string,
+  body: string,
+  data?: Record<string, string>,
+): Promise<admin.messaging.BatchResponse> {
+  if (tokens.length === 0) {
+    return { responses: [], successCount: 0, failureCount: 0 };
+  }
+
+  const message: admin.messaging.MulticastMessage = {
+    tokens,
+    notification: {
+      title,
+      body,
+    },
+    data,
+    android: {
+      priority: "high",
+      notification: {
+        sound: "default",
+        channelId: "default",
+      },
+    },
+    apns: {
+      payload: {
+        aps: {
+          sound: "default",
+          badge: 1,
+        },
+      },
+    },
+  };
+
+  return messaging.sendEachForMulticast(message);
+}

package/sails/push-notifications/files/frontend/components/PushNotificationInit.tsx

@@ -0,0 +1,12 @@
+import { usePushNotifications } from "@/hooks/usePushNotifications.js";
+
+/**
+ * Invisible component that initializes push notification registration.
+ *
+ * Place this inside Layout.tsx so that push notifications are set up as soon
+ * as the app mounts on a native device. Renders nothing visible.
+ */
+export function PushNotificationInit() {
+  usePushNotifications();
+  return null;
+}

package/sails/push-notifications/files/frontend/hooks/usePushNotifications.ts

@@ -0,0 +1,154 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { useNavigate } from "react-router";
+import { PushNotifications } from "@capacitor/push-notifications";
+import { isNative, platform } from "@/lib/capacitor.js";
+import { useAuth } from "@/hooks/useAuth.js";
+
+type PermissionStatus = "prompt" | "granted" | "denied" | "unknown";
+
+interface UsePushNotificationsResult {
+  isRegistered: boolean;
+  permissionStatus: PermissionStatus;
+  register: () => Promise<void>;
+  unregister: () => Promise<void>;
+}
+
+/**
+ * Hook to manage push notification registration and handling.
+ *
+ * On mount (if running on a native platform), requests push permission,
+ * registers the device token with the backend, and sets up listeners for
+ * incoming notifications and token refreshes.
+ *
+ * On notification tap, navigates to the route specified in the notification
+ * data payload (data.route).
+ */
+export function usePushNotifications(): UsePushNotificationsResult {
+  const [isRegistered, setIsRegistered] = useState(false);
+  const [permissionStatus, setPermissionStatus] = useState<PermissionStatus>("unknown");
+  const currentTokenRef = useRef<string | null>(null);
+  const navigate = useNavigate();
+  const { user } = useAuth();
+
+  // Register token with backend
+  const registerTokenWithBackend = useCallback(
+    async (token: string) => {
+      try {
+        const response = await fetch("/api/notifications/register", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          credentials: "include",
+          body: JSON.stringify({
+            token,
+            platform: platform,
+          }),
+        });
+
+        if (response.ok) {
+          currentTokenRef.current = token;
+          setIsRegistered(true);
+        }
+      } catch (error) {
+        console.error("Failed to register push token with backend:", error);
+      }
+    },
+    [],
+  );
+
+  // Unregister token from backend
+  const unregisterTokenFromBackend = useCallback(async () => {
+    if (!currentTokenRef.current) return;
+
+    try {
+      await fetch("/api/notifications/unregister", {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+        credentials: "include",
+        body: JSON.stringify({ token: currentTokenRef.current }),
+      });
+
+      currentTokenRef.current = null;
+      setIsRegistered(false);
+    } catch (error) {
+      console.error("Failed to unregister push token:", error);
+    }
+  }, []);
+
+  // Request permission and register
+  const register = useCallback(async () => {
+    if (!isNative) return;
+
+    const permResult = await PushNotifications.requestPermissions();
+    setPermissionStatus(permResult.receive as PermissionStatus);
+
+    if (permResult.receive === "granted") {
+      await PushNotifications.register();
+    }
+  }, []);
+
+  // Unregister
+  const unregister = useCallback(async () => {
+    await unregisterTokenFromBackend();
+  }, [unregisterTokenFromBackend]);
+
+  useEffect(() => {
+    if (!isNative || !user) return;
+
+    // Check current permission status
+    PushNotifications.checkPermissions().then((result) => {
+      setPermissionStatus(result.receive as PermissionStatus);
+    });
+
+    // Listen for successful registration (we receive the FCM token)
+    const registrationListener = PushNotifications.addListener(
+      "registration",
+      (token) => {
+        registerTokenWithBackend(token.value);
+      },
+    );
+
+    // Listen for registration errors
+    const registrationErrorListener = PushNotifications.addListener(
+      "registrationError",
+      (error) => {
+        console.error("Push notification registration error:", error);
+      },
+    );
+
+    // Listen for incoming push notifications (app in foreground)
+    const pushReceivedListener = PushNotifications.addListener(
+      "pushNotificationReceived",
+      (notification) => {
+        console.log("Push notification received in foreground:", notification);
+      },
+    );
+
+    // Listen for notification taps (app opened from notification)
+    const pushActionListener = PushNotifications.addListener(
+      "pushNotificationActionPerformed",
+      (action) => {
+        const data = action.notification.data;
+        if (data?.route && typeof data.route === "string") {
+          navigate(data.route);
+        }
+      },
+    );
+
+    // Request permissions and register on mount
+    register();
+
+    return () => {
+      registrationListener.then((l) => l.remove());
+      registrationErrorListener.then((l) => l.remove());
+      pushReceivedListener.then((l) => l.remove());
+      pushActionListener.then((l) => l.remove());
+    };
+  }, [user, register, registerTokenWithBackend, navigate]);
+
+  return {
+    isRegistered,
+    permissionStatus,
+    register,
+    unregister,
+  };
+}