@djangocfg/nextjs 2.1.36 → 2.1.38

package/src/pwa/notifications.ts

@@ -0,0 +1,192 @@
+/**
+ * PWA Push Notifications Client Utilities
+ *
+ * Functions for requesting permission, subscribing to push notifications,
+ * and sending test notifications
+ */
+
+/**
+ * Check if push notifications are supported
+ */
+export function isPushNotificationSupported(): boolean {
+  return (
+    'serviceWorker' in navigator &&
+    'PushManager' in window &&
+    'Notification' in window
+  );
+}
+
+/**
+ * Get current notification permission status
+ */
+export function getNotificationPermission(): NotificationPermission {
+  if (!('Notification' in window)) {
+    return 'denied';
+  }
+  return Notification.permission;
+}
+
+/**
+ * Request notification permission from user
+ */
+export async function requestNotificationPermission(): Promise<NotificationPermission> {
+  if (!('Notification' in window)) {
+    throw new Error('Notifications are not supported');
+  }
+
+  const permission = await Notification.requestPermission();
+  return permission;
+}
+
+/**
+ * Convert base64 VAPID key to Uint8Array
+ */
+function urlBase64ToUint8Array(base64String: string): Uint8Array {
+  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+
+  const rawData = window.atob(base64);
+  const outputArray = new Uint8Array(rawData.length);
+
+  for (let i = 0; i < rawData.length; ++i) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+  return outputArray;
+}
+
+export interface PushSubscriptionOptions {
+  /**
+   * VAPID public key (base64 encoded)
+   * Generate with: npx web-push generate-vapid-keys
+   */
+  vapidPublicKey: string;
+
+  /**
+   * User visible only (required for Chrome)
+   * @default true
+   */
+  userVisibleOnly?: boolean;
+}
+
+/**
+ * Subscribe to push notifications
+ *
+ * @example
+ * ```ts
+ * const subscription = await subscribeToPushNotifications({
+ *   vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
+ * });
+ *
+ * // Send subscription to your backend
+ * await fetch('/api/push/subscribe', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify(subscription),
+ * });
+ * ```
+ */
+export async function subscribeToPushNotifications(
+  options: PushSubscriptionOptions
+): Promise<PushSubscription> {
+  if (!isPushNotificationSupported()) {
+    throw new Error('Push notifications are not supported');
+  }
+
+  // Request permission first
+  const permission = await requestNotificationPermission();
+  if (permission !== 'granted') {
+    throw new Error(`Notification permission ${permission}`);
+  }
+
+  // Get service worker registration
+  const registration = await navigator.serviceWorker.ready;
+
+  // Check if already subscribed
+  let subscription = await registration.pushManager.getSubscription();
+
+  if (subscription) {
+    return subscription;
+  }
+
+  // Subscribe to push notifications
+  const convertedVapidKey = urlBase64ToUint8Array(options.vapidPublicKey);
+
+  subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: options.userVisibleOnly ?? true,
+    applicationServerKey: convertedVapidKey as BufferSource,
+  });
+
+  return subscription;
+}
+
+/**
+ * Unsubscribe from push notifications
+ */
+export async function unsubscribeFromPushNotifications(): Promise<boolean> {
+  if (!isPushNotificationSupported()) {
+    return false;
+  }
+
+  const registration = await navigator.serviceWorker.ready;
+  const subscription = await registration.pushManager.getSubscription();
+
+  if (subscription) {
+    return await subscription.unsubscribe();
+  }
+
+  return false;
+}
+
+/**
+ * Get current push subscription
+ */
+export async function getPushSubscription(): Promise<PushSubscription | null> {
+  if (!isPushNotificationSupported()) {
+    return null;
+  }
+
+  const registration = await navigator.serviceWorker.ready;
+  return await registration.pushManager.getSubscription();
+}
+
+/**
+ * Show a local notification (doesn't require push)
+ *
+ * @example
+ * ```ts
+ * await showLocalNotification({
+ *   title: 'Hello!',
+ *   body: 'This is a test notification',
+ *   icon: '/icon.png',
+ *   data: { url: '/some-page' },
+ * });
+ * ```
+ */
+export async function showLocalNotification(options: {
+  title: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  tag?: string;
+  data?: any;
+  requireInteraction?: boolean;
+}): Promise<void> {
+  if (!('Notification' in window)) {
+    throw new Error('Notifications are not supported');
+  }
+
+  const permission = await requestNotificationPermission();
+  if (permission !== 'granted') {
+    throw new Error(`Notification permission ${permission}`);
+  }
+
+  const registration = await navigator.serviceWorker.ready;
+  await registration.showNotification(options.title, {
+    body: options.body,
+    icon: options.icon,
+    badge: options.badge,
+    tag: options.tag,
+    data: options.data,
+    requireInteraction: options.requireInteraction,
+  });
+}

package/src/pwa/plugin.ts

@@ -0,0 +1,194 @@
+/**
+ * PWA (Progressive Web App) Plugin
+ *
+ * Configures Serwist for service worker and offline support
+ * Modern PWA solution for Next.js 15+ with App Router
+ *
+ * @see https://serwist.pages.dev/
+ */
+
+import type { NextConfig } from 'next';
+import { consola } from 'consola';
+
+export interface PWAPluginOptions {
+  /**
+   * Destination directory for service worker files
+   * @default 'public'
+   * @deprecated Use swDest instead
+   */
+  dest?: string;
+
+  /**
+   * Path to service worker source file (relative to project root)
+   * @default 'app/sw.ts'
+   */
+  swSrc?: string;
+
+  /**
+   * Destination for compiled service worker
+   * @default 'public/sw.js'
+   */
+  swDest?: string;
+
+  /**
+   * Disable PWA completely
+   * @default false in production, true in development
+   * @example disable: process.env.NODE_ENV === 'development'
+   */
+  disable?: boolean;
+
+  /**
+   * Cache on navigation - cache pages when navigating
+   * @default true
+   */
+  cacheOnNavigation?: boolean;
+
+  /**
+   * Reload app when device goes back online
+   * @default true
+   */
+  reloadOnOnline?: boolean;
+
+  /**
+   * Additional Serwist options
+   * @see https://serwist.pages.dev/docs/next/configuring
+   */
+  serwistOptions?: Record<string, any>;
+}
+
+/**
+ * Add PWA configuration to Next.js config using Serwist
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createBaseNextConfig, withPWA } from '@djangocfg/nextjs/config';
+ *
+ * const nextConfig = createBaseNextConfig({...});
+ *
+ * export default withPWA(nextConfig, {
+ *   swSrc: 'app/sw.ts',
+ *   disable: process.env.NODE_ENV === 'development',
+ * });
+ * ```
+ *
+ * @example Integrated with createBaseNextConfig
+ * ```ts
+ * import { createBaseNextConfig } from '@djangocfg/nextjs/config';
+ *
+ * const config = createBaseNextConfig({
+ *   pwa: {
+ *     swSrc: 'app/sw.ts',
+ *     disable: false,
+ *   },
+ * });
+ *
+ * export default config;
+ * ```
+ */
+export function withPWA(
+  nextConfig: NextConfig,
+  options: PWAPluginOptions = {}
+): NextConfig {
+  const isDev = process.env.NODE_ENV === 'development';
+
+  const defaultOptions: PWAPluginOptions = {
+    swSrc: 'app/sw.ts',
+    swDest: 'public/sw.js',
+    disable: options.disable !== undefined ? options.disable : isDev,
+    cacheOnNavigation: true,
+    reloadOnOnline: true,
+    ...options,
+  };
+
+  try {
+    const withSerwistInit = require('@serwist/next').default;
+
+    const withSerwist = withSerwistInit({
+      swSrc: defaultOptions.swSrc,
+      swDest: defaultOptions.swDest,
+      disable: defaultOptions.disable,
+      cacheOnNavigation: defaultOptions.cacheOnNavigation,
+      reloadOnOnline: defaultOptions.reloadOnOnline,
+      ...defaultOptions.serwistOptions,
+    });
+
+    return withSerwist(nextConfig);
+  } catch (error) {
+    consola.error('Failed to configure Serwist:', error);
+    return nextConfig;
+  }
+}
+
+/**
+ * Get service worker template content
+ *
+ * Returns ready-to-use service worker code for app/sw.ts
+ *
+ * @example
+ * ```ts
+ * import { getServiceWorkerTemplate } from '@djangocfg/nextjs/config';
+ *
+ * // Copy this to your app/sw.ts file
+ * console.log(getServiceWorkerTemplate());
+ * ```
+ */
+export function getServiceWorkerTemplate(): string {
+  return `/**
+ * Service Worker (Serwist)
+ *
+ * Modern PWA service worker using Serwist
+ */
+
+import { defaultCache } from '@serwist/next/worker';
+import { Serwist } from 'serwist';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare const self: any;
+
+const serwist = new Serwist({
+  // Precache entries injected by Serwist build plugin
+  precacheEntries: self.__SW_MANIFEST,
+
+  // Skip waiting - activate new SW immediately
+  skipWaiting: true,
+
+  // Take control of all clients immediately
+  clientsClaim: true,
+
+  // Enable navigation preload for faster loads
+  navigationPreload: true,
+
+  // Use default Next.js runtime caching strategies
+  runtimeCaching: defaultCache,
+
+  // Fallback pages for offline
+  fallbacks: {
+    entries: [
+      {
+        url: '/_offline',
+        matcher({ request }) {
+          return request.destination === 'document';
+        },
+      },
+    ],
+  },
+});
+
+serwist.addEventListeners();
+`;
+}
+
+// Backward compatibility exports (deprecated)
+export const defaultRuntimeCaching = [];
+export function createApiCacheRule() {
+  consola.warn('createApiCacheRule is deprecated with Serwist. Use defaultCache from @serwist/next/worker');
+  return {};
+}
+export function createStaticAssetRule() {
+  consola.warn('createStaticAssetRule is deprecated with Serwist. Use defaultCache from @serwist/next/worker');
+  return {};
+}
+export function createCdnCacheRule() {
+  consola.warn('createCdnCacheRule is deprecated with Serwist. Use defaultCache from @serwist/next/worker');
+  return {};
+}

package/src/pwa/server/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Server-side PWA Utilities
+ *
+ * Push notifications, VAPID configuration, and route handlers
+ *
+ * @example
+ * ```typescript
+ * // Configure VAPID keys
+ * import { configureVapid } from '@djangocfg/nextjs/pwa/server';
+ * configureVapid();
+ *
+ * // Use ready-made route handlers
+ * // app/api/push/subscribe/route.ts
+ * export { POST, GET } from '@djangocfg/nextjs/pwa/server/routes';
+ *
+ * // Or use utilities directly
+ * import { sendPushNotification } from '@djangocfg/nextjs/pwa/server';
+ * await sendPushNotification(subscription, { title: 'Hello!' });
+ * ```
+ */
+
+export * from './push';
+export * as routes from './routes';

package/src/pwa/server/push.ts

@@ -0,0 +1,166 @@
+/**
+ * Server-side Push Notification Utilities
+ *
+ * VAPID-based Web Push notifications using web-push library
+ */
+
+import webpush, { PushSubscription } from 'web-push';
+import { consola } from 'consola';
+
+let vapidConfigured = false;
+
+/**
+ * Check if VAPID keys are configured
+ */
+export function isVapidConfigured(): boolean {
+  return vapidConfigured;
+}
+
+/**
+ * Get VAPID keys from environment
+ */
+export function getVapidKeys() {
+  const publicKey = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY;
+  const privateKey = process.env.VAPID_PRIVATE_KEY;
+  const mailto = process.env.VAPID_MAILTO || 'mailto:noreply@example.com';
+
+  return { publicKey, privateKey, mailto };
+}
+
+/**
+ * Configure VAPID keys for web-push
+ * Call this once at app startup
+ *
+ * @example
+ * ```typescript
+ * // In your API route or middleware
+ * import { configureVapid } from '@djangocfg/nextjs/pwa/server';
+ *
+ * configureVapid(); // Uses env vars automatically
+ * ```
+ */
+export function configureVapid(options?: {
+  publicKey?: string;
+  privateKey?: string;
+  mailto?: string;
+}): boolean {
+  const { publicKey, privateKey, mailto } = options || getVapidKeys();
+
+  if (!publicKey || !privateKey) {
+    consola.warn(
+      '⚠️  VAPID keys not configured!\n' +
+      '   Generate keys: npx web-push generate-vapid-keys\n' +
+      '   Add to .env.local:\n' +
+      '     NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key\n' +
+      '     VAPID_PRIVATE_KEY=your_private_key\n' +
+      '   Push notifications will not work without VAPID keys.'
+    );
+    return false;
+  }
+
+  try {
+    webpush.setVapidDetails(mailto, publicKey, privateKey);
+    vapidConfigured = true;
+    consola.success('✅ VAPID keys configured for push notifications');
+    return true;
+  } catch (error: any) {
+    consola.error('Failed to configure VAPID keys:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Send push notification to a subscription
+ *
+ * @example
+ * ```typescript
+ * await sendPushNotification(subscription, {
+ *   title: 'Hello!',
+ *   body: 'Test notification',
+ *   data: { url: '/page' },
+ * });
+ * ```
+ */
+export async function sendPushNotification(
+  subscription: PushSubscription,
+  notification: {
+    title: string;
+    body?: string;
+    icon?: string;
+    badge?: string;
+    data?: any;
+    tag?: string;
+    requireInteraction?: boolean;
+  }
+): Promise<void> {
+  if (!vapidConfigured) {
+    const configured = configureVapid();
+    if (!configured) {
+      throw new Error('VAPID keys not configured. Cannot send push notification.');
+    }
+  }
+
+  const payload = JSON.stringify({
+    title: notification.title,
+    body: notification.body || '',
+    icon: notification.icon,
+    badge: notification.badge,
+    data: notification.data,
+    tag: notification.tag,
+    requireInteraction: notification.requireInteraction,
+  });
+
+  const result = await webpush.sendNotification(subscription, payload);
+  console.log('✅ Push Sent to FCM:', {
+    statusCode: result.statusCode,
+    headers: result.headers,
+    bodyLength: result.body?.length
+  });
+}
+
+/**
+ * Send push notification to multiple subscriptions
+ *
+ * @example
+ * ```typescript
+ * const results = await sendPushToMultiple(subscriptions, {
+ *   title: 'Broadcast message',
+ *   body: 'Sent to all users',
+ * });
+ * console.log(`Sent: ${results.successful}, Failed: ${results.failed}`);
+ * ```
+ */
+export async function sendPushToMultiple(
+  subscriptions: PushSubscription[],
+  notification: Parameters<typeof sendPushNotification>[1]
+): Promise<{
+  successful: number;
+  failed: number;
+  errors: Array<{ subscription: PushSubscription; error: Error }>;
+}> {
+  const results = await Promise.allSettled(
+    subscriptions.map((sub) => sendPushNotification(sub, notification))
+  );
+
+  const successful = results.filter((r) => r.status === 'fulfilled').length;
+  const failed = results.filter((r) => r.status === 'rejected').length;
+  const errors = results
+    .map((r, i) => (r.status === 'rejected' ? { subscription: subscriptions[i], error: r.reason } : null))
+    .filter((e): e is NonNullable<typeof e> => e !== null);
+
+  return { successful, failed, errors };
+}
+
+/**
+ * Validate push subscription format
+ */
+export function validateSubscription(subscription: any): subscription is PushSubscription {
+  return (
+    subscription &&
+    typeof subscription === 'object' &&
+    typeof subscription.endpoint === 'string' &&
+    subscription.keys &&
+    typeof subscription.keys.p256dh === 'string' &&
+    typeof subscription.keys.auth === 'string'
+  );
+}

package/src/pwa/server/routes.ts

@@ -0,0 +1,137 @@
+/**
+ * Ready-to-use Push Notification Route Handlers
+ *
+ * Import these in your app/api/push/ routes
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { configureVapid, sendPushNotification, validateSubscription } from './push';
+
+// In-memory storage для demo (в production используй БД)
+const subscriptions = new Set<string>();
+
+/**
+ * POST /api/push/subscribe
+ * Save push subscription
+ *
+ * @example
+ * ```typescript
+ * // app/api/push/subscribe/route.ts
+ * export { POST } from '@djangocfg/nextjs/pwa/server/routes';
+ * ```
+ */
+export async function handleSubscribe(request: NextRequest) {
+  try {
+    const subscription = await request.json();
+
+    if (!validateSubscription(subscription)) {
+      return NextResponse.json(
+        { error: 'Invalid subscription format' },
+        { status: 400 }
+      );
+    }
+
+    // Сохраняем subscription (в demo просто в памяти)
+    subscriptions.add(JSON.stringify(subscription));
+
+    console.log('✅ Push subscription saved:', {
+      endpoint: subscription.endpoint.substring(0, 50) + '...',
+      total: subscriptions.size,
+    });
+
+    return NextResponse.json({
+      success: true,
+      message: 'Subscription saved',
+      totalSubscriptions: subscriptions.size,
+    });
+  } catch (error: any) {
+    console.error('Subscription error:', error);
+
+    return NextResponse.json(
+      {
+        error: 'Failed to save subscription',
+        details: error.message,
+      },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * GET /api/push/subscribe
+ * Get all subscriptions (for testing)
+ */
+export async function handleGetSubscriptions() {
+  return NextResponse.json({
+    totalSubscriptions: subscriptions.size,
+    subscriptions: Array.from(subscriptions).map((sub) => {
+      const parsed = JSON.parse(sub);
+      return {
+        endpoint: parsed.endpoint.substring(0, 50) + '...',
+      };
+    }),
+  });
+}
+
+/**
+ * POST /api/push/send
+ * Send push notification
+ *
+ * @example
+ * ```typescript
+ * // app/api/push/send/route.ts
+ * export { POST as handleSend as POST } from '@djangocfg/nextjs/pwa/server/routes';
+ * ```
+ */
+export async function handleSend(request: NextRequest) {
+  try {
+    const { subscription, notification } = await request.json();
+
+    if (!subscription) {
+      return NextResponse.json(
+        { error: 'Subscription is required' },
+        { status: 400 }
+      );
+    }
+
+    if (!validateSubscription(subscription)) {
+      return NextResponse.json(
+        { error: 'Invalid subscription format' },
+        { status: 400 }
+      );
+    }
+
+    // Configure VAPID if not already configured
+    configureVapid();
+
+    await sendPushNotification(subscription, {
+      title: notification?.title || 'Test Notification',
+      body: notification?.body || 'This is a test push notification',
+      icon: notification?.icon,
+      badge: notification?.badge,
+      data: notification?.data,
+    });
+
+    return NextResponse.json({
+      success: true,
+      message: 'Push notification sent',
+    });
+  } catch (error: any) {
+    console.error('Push notification error:', error);
+
+    return NextResponse.json(
+      {
+        error: 'Failed to send push notification',
+        details: error.message,
+      },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * Combined route handlers
+ * Use like: export { POST, GET } from '@djangocfg/nextjs/pwa/server/routes'
+ */
+export const POST = handleSubscribe;
+export const GET = handleGetSubscriptions;