fix: align service worker background-sync routes with real offline mutation endpoints (#946)

[dedukpe]

Summary

Aligns the service worker's BackgroundSyncPlugin routes with all real offline mutation endpoints and enables actual request replay via workbox-background-sync's built-in queue replay mechanism.

Closes #946

Problem

The service worker had two critical issues preventing offline mutations from being properly queued and replayed:

1. Route ordering bug — background sync route never triggered

Workbox routes are evaluated in registration order, first-match-wins. The generic /api/ NetworkFirst route was registered before the specific PATCH /api/lessons/[id]/progress background sync route, meaning the generic route caught ALL API requests first — preventing the BackgroundSyncPlugin from ever capturing failed mutations.

2. Only one endpoint was registered

Only PATCH /api/lessons/[id]/progress had a background sync route. Mutations to notes, bookmarks, user progress, quiz results, and course progress were never queued for replay when offline.

3. No-op sync handler blocked replay

The sync event listener called event.waitUntil(Promise.resolve()) — effectively doing nothing. While workbox-background-sync's Queue auto-registers its own sync listener to replay queued requests, the manual handler was redundant and confusing.

Solution

Changes to src/serviceWorker.ts

1. Reordered routes: Moved all background sync routes above the generic /api/ NetworkFirst route so they match first for mutation requests.

2. Registered background sync for all mutation endpoints using a single BackgroundSyncPlugin instance ('teachLinkSyncQueue'):

   Endpoint	Methods
   /api/lessons/[id]/progress	PATCH
   /api/notes	POST, PATCH, DELETE
   /api/bookmarks	POST, PATCH, DELETE
   /api/user/progress	POST
   /api/quiz-results	POST
   /api/course-progress	POST

3. Removed the no-op sync event handler — workbox-background-sync's Queue class automatically registers a sync event listener on construction that calls replayRequests(), so manual handling is unnecessary and was previously doing nothing.

4. Switched from NetworkFirst to NetworkOnly strategy for mutation routes — there's no value in caching POST/PATCH/DELETE responses. When online, the request goes through normally. When offline, the BackgroundSyncPlugin queues it in IndexedDB for replay when connectivity returns.

Changes to src/app/services/offlineSync.ts

• Fixed the progress endpoint mapping in simulateApiCall from /api/progress to /api/lessons/[id]/progress to match the actual API route.

How It Works

1. When a user makes an offline mutation (e.g., POST /api/notes), the NetworkOnly strategy fails with a network error.
2. The BackgroundSyncPlugin's fetchDidFail callback captures the failed Request and stores it in workbox's internal IndexedDB queue.
3. When the browser fires a sync event with tag 'teachLinkSyncQueue', workbox's Queue.replayRequests() replays all queued requests in FIFO order.
4. Successfully replayed requests are removed from the queue; failed ones remain for the next sync event (up to maxRetentionTime of 24 hours).

Testing

• npx tsc --noEmit — passes with zero errors
• npx eslint src/serviceWorker.ts src/app/services/offlineSync.ts — passes with zero warnings
• Manual verification: the route ordering ensures that POST/PATCH/DELETE requests to the registered endpoints route through the background sync plugin, while GET requests and other API paths fall through to the generic NetworkFirst cache route.

[drips-wave]

@dedukpe Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[RUKAYAT-CODER]

Thank you for contributing to the project