update: add new logic for push token

PUSH_NOTIFICATIONS_MULTI_DEVICE.md

@@ -0,0 +1,214 @@
+# Multi-Device Push Notifications Implementation
+
+## Overview
+
+Updated the push notification system to support multiple devices per user. Users can now receive push notifications on all their logged-in devices (mobile, tablet, desktop, etc.).
+
+## Database Changes
+
+### Migration: `update_push_tokens_to_array.sql`
+
+- Converted single `push_token` field to `push_tokens` JSON array
+- Automatically migrates existing single tokens to array format
+- Adds optimized GIN index for JSON array queries
+
+## API Endpoints
+
+### 1. Add Push Token (New Device Login)
+
+```http
+POST /users/push-token
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "pushToken": "device_push_token_from_najva_sdk",
+  "deviceId": "optional_device_identifier"
+}
+```
+
+### 2. Remove Push Token (Device Logout)
+
+```http
+DELETE /users/push-token
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "pushToken": "device_push_token_to_remove"
+}
+```
+
+### 3. Get All Push Tokens
+
+```http
+GET /users/push-tokens
+Authorization: Bearer <jwt_token>
+```
+
+Response:
+
+```json
+{
+  "pushTokens": ["token1", "token2", "token3"],
+  "totalTokens": 3
+}
+```
+
+### 4. Update Profile (Push Token Removed)
+
+```http
+PATCH /users/profile
+Authorization: Bearer <jwt_token>
+Content-Type: application/json
+
+{
+  "profilePic": "https://example.com/profile.jpg"
+}
+```
+
+## Features
+
+### ✅ Multi-Device Support
+
+- Users can have multiple push tokens (one per device)
+- Notifications sent to all registered devices simultaneously
+- Automatic deduplication prevents duplicate tokens
+
+### ✅ Invalid Token Cleanup
+
+- Automatically detects invalid/expired tokens from Najva API response
+- Removes invalid tokens from user's token list
+- Logs cleanup activities for monitoring
+
+### ✅ Device Management
+
+- Add tokens when user logs in on new device
+- Remove tokens when user logs out from device
+- View all registered devices/tokens
+
+### ✅ Backward Compatibility
+
+- Existing single token data automatically migrated to array format
+- No breaking changes to existing notification flow
+
+## Implementation Details
+
+### User Entity Changes
+
+```typescript
+// Before
+@Property({ type: "varchar", nullable: true })
+pushToken?: string;
+
+// After
+@Property({ type: "json", nullable: true })
+pushTokens?: string[];
+```
+
+### Service Methods
+
+```typescript
+// Add token for new device
+await usersService.addPushToken(userId, { pushToken: "token" });
+
+// Remove token when logging out
+await usersService.removePushToken(userId, { pushToken: "token" });
+
+// Send to all user devices
+await notificationsService.sendPushNotificationToUserDevices(userId, userTokens, message);
+```
+
+### Automatic Token Cleanup
+
+When sending notifications, invalid tokens are automatically:
+
+1. Detected from Najva API response
+2. Logged for monitoring
+3. Removed from user's token array
+4. Database updated to clean state
+
+## Frontend Integration
+
+### When User Logs In
+
+```javascript
+// Get push token from Najva SDK
+const pushToken = await najva.getPushToken();
+
+// Register token for this device
+await fetch("/api/users/push-token", {
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${jwt}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    pushToken: pushToken,
+    deviceId: navigator.userAgent, // optional
+  }),
+});
+```
+
+### When User Logs Out
+
+```javascript
+// Remove token for this device
+await fetch("/api/users/push-token", {
+  method: "DELETE",
+  headers: {
+    Authorization: `Bearer ${jwt}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    pushToken: currentDeviceToken,
+  }),
+});
+```
+
+## Environment Variables
+
+```env
+NAJVA_API_KEY=your_najva_api_key
+NAJVA_WEBSITE_ID=your_website_id
+NAJVA_API_URL=https://push.najva.com/v1/send/token/
+PUSH_TTL=24
+FRONTEND_URL=https://your-frontend-domain.com
+```
+
+## Benefits
+
+1. **Multi-Device Support**: Users get notifications on all their devices
+2. **Device Management**: Add/remove devices as needed
+3. **Automatic Cleanup**: Invalid tokens automatically removed
+4. **Scalable**: Efficient JSON array storage with GIN indexing
+5. **Reliable**: Handles edge cases like duplicate tokens and API failures
+6. **Monitoring**: Comprehensive logging for debugging and monitoring
+
+## Migration Steps
+
+1. **Run Database Migration**:
+
+   ```sql
+   -- Execute: database/migrations/update_push_tokens_to_array.sql
+   ```
+
+2. **Update Frontend**:
+   - Use new `/users/push-token` endpoints
+   - Remove `pushToken` field from profile updates
+
+3. **Deploy Backend**:
+   - All changes are backward compatible
+   - Existing tokens automatically migrated
+
+## Testing
+
+Test the multi-device functionality:
+
+1. Login from Device A → Add token A
+2. Login from Device B → Add token B
+3. Create notification → Both devices receive push
+4. Logout from Device A → Remove token A
+5. Create notification → Only device B receives push
+
+The system now properly supports users accessing your application from multiple devices while maintaining reliable push notification delivery!