crowd-funder-for-time-pwa/doc/web-push-cleanup-guide.md

TimeSafari Web-Push Cleanup Guide

Status: 🚀 Native-First Implementation
Date: 2025-01-27T14:30Z (UTC)
Author: Matthew Raymer
Scope: Web-push code cleanup and deprecation
Goal: Remove or quarantine all web-push code paths and mark as deprecated.

---

Executive Summary

This document provides a comprehensive cleanup guide for removing web-push code paths from TimeSafari. Web-push has been retired for unreliability, and the system now focuses on native mobile reliability with Electron best-effort support.

---

Cleanup Strategy

Phase 1: Identify Web-Push Code Paths

Service Worker Files

• sw_scripts/notification-click.js - Mark as deprecated
• sw_scripts/ directory - Review for web-push dependencies
• Service worker registration code - Remove or quarantine

Web-Specific Code

• Web push notification handlers
• Service worker event listeners
• Web notification API usage
• Push subscription management

Configuration Files

• VitePWA plugin configuration
• Service worker build configuration
• Web push manifest files

Phase 2: Mark as Deprecated

Code Comments

// DEPRECATED: Web-push notification handling
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

Documentation Updates

• Mark web-push sections as deprecated
• Add deprecation notices
• Update README files
• Update API documentation

Phase 3: Remove or Quarantine

Complete Removal

• Web push subscription code
• Service worker notification handlers
• Web-specific notification APIs
• Push message handling

Quarantine (Keep for Reference)

• Service worker registration code
• Web push configuration
• Historical web-push tests

---

Detailed Cleanup Tasks

1. Service Worker Cleanup

Files to Deprecate

sw_scripts/notification-click.js

// DEPRECATED: Service worker notification handling
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

// Original web-push notification click handler
self.addEventListener('notificationclick', (event) => {
  // DEPRECATED: Web-push only
  event.notification.close();

  const slotId = event.notification.data?.slotId;
  const route = slotId ? '/#/daily' : '/#/notifications';

  event.waitUntil(
    clients.openWindow(route).catch(() => {
      return clients.openWindow('/');
    })
  );
});

Service Worker Registration

// DEPRECATED: Service worker registration
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

if ('serviceWorker' in navigator && process.env.VITE_PLATFORM === 'web') {
  // DEPRECATED: Web-push only
  navigator.serviceWorker.register('/sw.js')
    .then(registration => {
      console.log('Service Worker registered:', registration);
    })
    .catch(error => {
      console.error('Service Worker registration failed:', error);
    });
}

2. Web Push API Cleanup

Push Subscription Management

// DEPRECATED: Web push subscription management
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

class WebPushManager {
  // DEPRECATED: Web-push only
  async subscribeToPush() {
    // Implementation kept for reference
  }

  // DEPRECATED: Web-push only
  async unsubscribeFromPush() {
    // Implementation kept for reference
  }
}

Push Message Handling

// DEPRECATED: Push message handling
// This code is kept for reference but not used in production
// Replaced by Native-First notification system

self.addEventListener('push', (event) => {
  // DEPRECATED: Web-push only
  const data = event.data ? event.data.json() : {};

  const options = {
    body: data.body,
    icon: '/icon-192x192.png',
    badge: '/badge-72x72.png',
    data: data
  };

  event.waitUntil(
    self.registration.showNotification(data.title, options)
  );
});

3. Configuration Cleanup

VitePWA Plugin Configuration

// DEPRECATED: VitePWA plugin configuration
// This configuration is kept for reference but not used in production
// Replaced by Native-First notification system

import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    VitePWA({
      // DEPRECATED: Web-push only
      registerType: 'autoUpdate',
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}']
      },
      includeAssets: ['favicon.ico', 'apple-touch-icon.png', 'masked-icon.svg'],
      manifest: {
        name: 'TimeSafari',
        short_name: 'TimeSafari',
        description: 'TimeSafari App',
        theme_color: '#ffffff',
        icons: [
          {
            src: 'pwa-192x192.png',
            sizes: '192x192',
            type: 'image/png'
          }
        ]
      }
    })
  ]
})

Service Worker Build Configuration

// DEPRECATED: Service worker build configuration
// This configuration is kept for reference but not used in production
// Replaced by Native-First notification system

export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        // DEPRECATED: Web-push only
        sw: 'sw_scripts/notification-click.js'
      }
    }
  }
})

4. Test Cleanup

Web Push Tests

// DEPRECATED: Web push tests
// These tests are kept for reference but not used in production
// Replaced by Native-First notification system

describe('Web Push Notifications (DEPRECATED)', () => {
  // DEPRECATED: Web-push only
  it('should handle push notifications', async () => {
    // Test implementation kept for reference
  });

  // DEPRECATED: Web-push only
  it('should handle notification clicks', async () => {
    // Test implementation kept for reference
  });
});

Service Worker Tests

// DEPRECATED: Service worker tests
// These tests are kept for reference but not used in production
// Replaced by Native-First notification system

describe('Service Worker (DEPRECATED)', () => {
  // DEPRECATED: Web-push only
  it('should register service worker', async () => {
    // Test implementation kept for reference
  });

  // DEPRECATED: Web-push only
  it('should handle push events', async () => {
    // Test implementation kept for reference
  });
});

5. Documentation Cleanup

README Updates

# TimeSafari Native-First Notification System

## Web-Push Status: DEPRECATED

Web-push has been retired for unreliability. The system now focuses on native mobile reliability with Electron best-effort support.

### Deprecated Features
- ❌ Web push notifications
- ❌ Service worker notification handling
- ❌ Web notification API

### Active Features
- ✅ Native mobile notifications (Android/iOS)
- ✅ Electron notifications (best-effort)
- ✅ OS-scheduled background prefetch
- ✅ Rolling window safety

API Documentation Updates

## Notification API (Native-First)

### Deprecated Methods
- `subscribeToPush()` - DEPRECATED: Web-push only
- `unsubscribeFromPush()` - DEPRECATED: Web-push only
- `handlePushMessage()` - DEPRECATED: Web-push only

### Active Methods
- `scheduleExact()` - Native exact scheduling
- `scheduleWindow()` - Native windowed scheduling
- `schedulePrefetch()` - Native background prefetch

---

File-by-File Cleanup Checklist

Service Worker Files

• sw_scripts/notification-click.js - Mark as deprecated
• sw_scripts/ directory - Review for web-push dependencies
• Service worker build configuration - Remove or quarantine

Web-Specific Code

• src/main.web.ts - Remove service worker registration
• src/services/webPush.ts - Mark as deprecated
• src/utils/serviceWorker.ts - Mark as deprecated
• Web notification API usage - Remove or quarantine

Configuration Files

• vite.config.web.mts - Remove VitePWA plugin
• package.json - Remove web-push dependencies
• public/manifest.json - Mark as deprecated
• Service worker build scripts - Remove or quarantine

Test Files

• test-playwright/web-push.spec.ts - Mark as deprecated
• test/services/webPush.test.ts - Mark as deprecated
• Service worker tests - Mark as deprecated

Documentation Files

• README.md - Update to reflect native-first approach
• doc/web-push.md - Mark as deprecated
• API documentation - Remove web-push references

---

Dependencies to Remove

NPM Packages

{
  "dependencies": {
    // DEPRECATED: Web-push only
    "web-push": "^7.4.0",
    "vite-plugin-pwa": "^0.17.0"
  },
  "devDependencies": {
    // DEPRECATED: Web-push only
    "workbox-webpack-plugin": "^6.5.0"
  }
}

Build Scripts

{
  "scripts": {
    // DEPRECATED: Web-push only
    "build:sw": "workbox generateSW",
    "test:sw": "jest --testPathPattern=serviceWorker"
  }
}

---

Migration Guide

From Web-Push to Native-First

Step 1: Remove Web-Push Dependencies

# Remove web-push packages
npm uninstall web-push vite-plugin-pwa workbox-webpack-plugin

# Remove service worker files
rm -rf sw_scripts/
rm -f public/sw.js
rm -f public/workbox-*.js

Step 2: Update Configuration

// Remove VitePWA plugin from vite.config.web.mts
export default defineConfig({
  plugins: [
    // Remove VitePWA plugin
    // VitePWA({ ... })
  ]
})

Step 3: Update Service Registration

// Remove service worker registration from main.web.ts
// if ('serviceWorker' in navigator) {
//   navigator.serviceWorker.register('/sw.js')
// }

Step 4: Update Tests

// Remove web-push tests
// describe('Web Push Notifications', () => { ... })

---

Verification Checklist

Code Removal Verification

• No web-push imports remain
• No service worker registration code
• No push subscription management
• No web notification API usage
• No VitePWA plugin configuration

Documentation Verification

• All web-push references marked as deprecated
• README updated to reflect native-first approach
• API documentation updated
• Test documentation updated

Build Verification

• Web build succeeds without service worker
• No service worker files generated
• No web-push dependencies in bundle
• Native builds work correctly

Test Verification

• Web-push tests are marked as deprecated
• Native notification tests pass
• No web-push test failures
• Test suite runs successfully

---

Rollback Plan

Emergency Rollback

If native-first implementation fails, web-push code can be restored:

1. Restore Dependencies

npm install web-push vite-plugin-pwa workbox-webpack-plugin

2. Restore Service Worker Files

git checkout HEAD~1 -- sw_scripts/
git checkout HEAD~1 -- public/sw.js

3. Restore Configuration

git checkout HEAD~1 -- vite.config.web.mts
git checkout HEAD~1 -- package.json

4. Restore Tests

git checkout HEAD~1 -- test-playwright/web-push.spec.ts
git checkout HEAD~1 -- test/services/webPush.test.ts

Rollback Verification

• Web-push functionality restored
• Service worker registration works
• Push notifications work
• Tests pass

---

Post-Cleanup Tasks

Code Review

• Review all changes for completeness
• Verify no web-push code remains
• Check for orphaned references
• Validate native-first implementation

Testing

• Run full test suite
• Verify native notifications work
• Check Electron functionality
• Validate mobile builds

Documentation

• Update all documentation
• Remove web-push references
• Update API documentation
• Update user guides

---

Success Criteria

Complete Web-Push Removal

• All web-push code marked as deprecated
• Service worker files quarantined
• Dependencies removed
• Configuration updated

Native-First Implementation

• Native notifications work on Android
• Native notifications work on iOS
• Electron notifications work
• Background prefetch works

Documentation Updated

• All docs reflect native-first approach
• Web-push marked as deprecated
• Migration guide provided
• Rollback plan documented

---

This cleanup guide provides comprehensive instructions for removing web-push code paths from TimeSafari. Web-push has been retired for unreliability, and the system now focuses on native mobile reliability with Electron best-effort support.