@djangocfg/nextjs 1.0.1

package/src/og-image/utils/url.ts

@@ -0,0 +1,327 @@
+/**
+ * URL Generation Helpers for OG Images
+ *
+ * Utilities to generate OG image URLs with proper query parameters
+ */
+
+/**
+ * Encode string to base64 with Unicode support
+ * Works in both browser and Node.js environments
+ */
+function encodeBase64(str: string): string {
+  // Node.js environment
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(str, 'utf-8').toString('base64');
+  }
+  // Browser environment - handle Unicode via UTF-8 encoding
+  return btoa(unescape(encodeURIComponent(str)));
+}
+
+/**
+ * Decode base64 string with Unicode support
+ * Works in both browser, Node.js, and Edge Runtime environments
+ */
+function decodeBase64(str: string): string {
+  // Node.js environment
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(str, 'base64').toString('utf-8');
+  }
+  // Edge Runtime / Browser environment - handle Unicode via UTF-8 decoding
+  // atob is available in Edge Runtime
+  try {
+    const binaryString = atob(str);
+    // Convert binary string to UTF-8
+    return decodeURIComponent(
+      binaryString
+        .split('')
+        .map((c) => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2))
+        .join('')
+    );
+  } catch (error) {
+    // Fallback to simpler method if above fails
+    return decodeURIComponent(escape(atob(str)));
+  }
+}
+
+/**
+ * OG Image URL parameters
+ */
+export interface OgImageUrlParams {
+  /** Page title */
+  title: string;
+  /** Page description (optional) */
+  description?: string;
+  /** Site name (optional) */
+  siteName?: string;
+  /** Logo URL (optional) */
+  logo?: string;
+  /** Additional custom parameters */
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Generate OG image URL with query parameters or base64 encoding
+ *
+ * @param baseUrl - Base URL of the OG image API route (e.g., '/api/og' or 'https://example.com/api/og')
+ * @param params - URL parameters for the OG image
+ * @param useBase64 - If true, encode params as base64 for safer URLs (default: true)
+ * @returns Complete OG image URL with encoded parameters
+ *
+ * @example
+ * ```typescript
+ * // Base64 encoding (safe, default)
+ * const url = generateOgImageUrl('/api/og', {
+ *   title: 'My Page Title',
+ *   description: 'Page description here',
+ * });
+ * // Result: /api/og?data=eyJ0aXRsZSI6Ik15IFBhZ2UgVGl0bGUiLCJkZXNjcmlwdGlvbiI6IlBhZ2UgZGVzY3JpcHRpb24gaGVyZSJ9
+ *
+ * // Query params (legacy)
+ * const url = generateOgImageUrl('/api/og', { title: 'Hello' }, false);
+ * // Result: /api/og?title=Hello
+ * ```
+ */
+export function generateOgImageUrl(
+  baseUrl: string,
+  params: OgImageUrlParams,
+  useBase64: boolean = true
+): string {
+  if (useBase64) {
+    // Clean params - remove undefined/null/empty values
+    const cleanParams: Record<string, string | number | boolean> = {};
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null && value !== '') {
+        cleanParams[key] = value;
+      }
+    });
+
+    // Encode as base64 (Unicode-safe)
+    const jsonString = JSON.stringify(cleanParams);
+    const base64Data = encodeBase64(jsonString);
+
+    // CRITICAL: Use path parameter instead of query parameter
+    // Next.js strips query params in internal requests for metadata generation
+    // Using /api/og/[data] instead of /api/og?data=... preserves the data
+    return `${baseUrl}/${base64Data}`;
+  } else {
+    // Legacy query params mode
+    const searchParams = new URLSearchParams();
+
+    // Add all defined parameters
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null && value !== '') {
+        searchParams.append(key, String(value));
+      }
+    });
+
+    const query = searchParams.toString();
+    return query ? `${baseUrl}?${query}` : baseUrl;
+  }
+}
+
+/**
+ * Get absolute OG image URL from relative path
+ *
+ * Useful for generating absolute URLs required by Open Graph meta tags
+ *
+ * @param relativePath - Relative OG image path (e.g., '/api/og?title=Hello')
+ * @param siteUrl - Base site URL (e.g., 'https://example.com')
+ * @returns Absolute URL
+ *
+ * @example
+ * ```typescript
+ * const absolute = getAbsoluteOgImageUrl(
+ *   '/api/og?title=Hello',
+ *   'https://example.com'
+ * );
+ * // Result: https://example.com/api/og?title=Hello
+ * ```
+ */
+export function getAbsoluteOgImageUrl(
+  relativePath: string,
+  siteUrl: string
+): string {
+  // Remove trailing slash from site URL
+  const cleanSiteUrl = siteUrl.replace(/\/$/, '');
+
+  // Ensure relative path starts with /
+  const cleanPath = relativePath.startsWith('/')
+    ? relativePath
+    : `/${relativePath}`;
+
+  return `${cleanSiteUrl}${cleanPath}`;
+}
+
+/**
+ * Create OG image URL builder with preset configuration
+ *
+ * Useful when you want to reuse the same base URL and default parameters
+ *
+ * @param baseUrl - Base URL of the OG image API route
+ * @param defaults - Default parameters to merge with each URL generation
+ * @returns URL builder function
+ *
+ * @example
+ * ```typescript
+ * const buildOgUrl = createOgImageUrlBuilder('/api/og', {
+ *   siteName: 'My Site',
+ *   logo: '/logo.png'
+ * });
+ *
+ * const url1 = buildOgUrl({ title: 'Page 1' });
+ * const url2 = buildOgUrl({ title: 'Page 2', description: 'Custom desc' });
+ * ```
+ */
+export function createOgImageUrlBuilder(
+  baseUrl: string,
+  defaults: Partial<OgImageUrlParams> = {}
+) {
+  return (params: OgImageUrlParams): string => {
+    return generateOgImageUrl(baseUrl, {
+      ...defaults,
+      ...params,
+    });
+  };
+}
+
+/**
+ * Parse OG image URL parameters from a URL string (legacy query params)
+ *
+ * @param url - Full or relative URL with query parameters
+ * @returns Parsed parameters object
+ *
+ * @example
+ * ```typescript
+ * const params = parseOgImageUrl('/api/og?title=Hello&description=World');
+ * // Result: { title: 'Hello', description: 'World' }
+ * ```
+ */
+export function parseOgImageUrl(url: string): Record<string, string> {
+  try {
+    const urlObj = new URL(url, 'http://dummy.com');
+    const params: Record<string, string> = {};
+
+    urlObj.searchParams.forEach((value, key) => {
+      params[key] = value;
+    });
+
+    return params;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse OG image data from base64-encoded query parameter
+ *
+ * Use this in your API route to decode the `data` parameter
+ * Supports both base64 (new) and legacy query params format
+ *
+ * @param searchParams - URL search params or request object
+ * @returns Parsed OG image parameters
+ *
+ * @example
+ * ```typescript
+ * // In Next.js API route (pages/api/og.ts)
+ * export default function handler(req) {
+ *   const params = parseOgImageData(req.query);
+ *   // { title: 'Hello', description: 'World' }
+ * }
+ *
+ * // In Next.js App Router (app/api/og/route.ts)
+ * export async function GET(request: Request) {
+ *   const { searchParams } = new URL(request.url);
+ *   const params = parseOgImageData(Object.fromEntries(searchParams));
+ *   // { title: 'Hello', description: 'World' }
+ * }
+ * ```
+ */
+export function parseOgImageData(
+  searchParams: Record<string, string | string[] | undefined> | URLSearchParams
+): Record<string, string> {
+  try {
+    // Handle URLSearchParams
+    let params: Record<string, string | undefined>;
+    
+    if (searchParams instanceof URLSearchParams) {
+      // Convert URLSearchParams to object
+      params = {};
+      for (const [key, value] of searchParams.entries()) {
+        params[key] = value;
+      }
+    } else {
+      params = searchParams as Record<string, string | undefined>;
+    }
+
+    // Debug logging
+    if (process.env.NODE_ENV === 'development') {
+      console.log('[parseOgImageData] Input params keys:', Object.keys(params));
+      console.log('[parseOgImageData] Input params:', params);
+    }
+
+    // Check for base64-encoded data parameter
+    const dataParam = params.data;
+    if (dataParam && typeof dataParam === 'string' && dataParam.trim() !== '') {
+      if (process.env.NODE_ENV === 'development') {
+        console.log('[parseOgImageData] Found data param, length:', dataParam.length);
+      }
+      
+      try {
+        const decoded = decodeBase64(dataParam);
+        if (process.env.NODE_ENV === 'development') {
+          console.log('[parseOgImageData] Decoded string:', decoded.substring(0, 100));
+        }
+        
+        const parsed = JSON.parse(decoded);
+        if (process.env.NODE_ENV === 'development') {
+          console.log('[parseOgImageData] Parsed JSON:', parsed);
+        }
+        
+        // Ensure all values are strings
+        const result: Record<string, string> = {};
+        for (const [key, value] of Object.entries(parsed)) {
+          if (value !== undefined && value !== null) {
+            result[key] = String(value);
+          }
+        }
+        
+        if (process.env.NODE_ENV === 'development') {
+          console.log('[parseOgImageData] Result:', result);
+        }
+        
+        return result;
+      } catch (decodeError) {
+        console.error('[parseOgImageData] Error decoding/parsing data param:', decodeError);
+        if (decodeError instanceof Error) {
+          console.error('[parseOgImageData] Error message:', decodeError.message);
+        }
+        // Fall through to legacy query params
+      }
+    } else {
+      if (process.env.NODE_ENV === 'development') {
+        console.log('[parseOgImageData] No data param found or empty');
+      }
+    }
+
+    // Fallback to legacy query params format
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(params)) {
+      if (key !== 'data' && value !== undefined && value !== null) {
+        result[key] = Array.isArray(value) ? value[0] : String(value);
+      }
+    }
+    
+    if (process.env.NODE_ENV === 'development') {
+      console.log('[parseOgImageData] Fallback result:', result);
+    }
+    
+    return result;
+  } catch (error) {
+    console.error('[parseOgImageData] Unexpected error:', error);
+    return {};
+  }
+}
+
+// Export base64 utilities for advanced use cases
+export { encodeBase64, decodeBase64 };
+

package/src/sitemap/generator.ts

@@ -0,0 +1,64 @@
+/**
+ * Sitemap Generator
+ *
+ * Generates XML sitemap from configuration
+ */
+
+import type { SitemapUrl } from '../types';
+
+/**
+ * Generate XML sitemap string from URLs
+ */
+export function generateSitemapXml(urls: SitemapUrl[]): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9
+        http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">
+${urls
+  .map(
+    ({ loc, lastmod, changefreq, priority }) => `  <url>
+    <loc>${escapeXml(loc)}</loc>
+    ${lastmod ? `<lastmod>${formatDate(lastmod)}</lastmod>` : ''}
+    ${changefreq ? `<changefreq>${changefreq}</changefreq>` : ''}
+    ${priority !== undefined ? `<priority>${priority.toFixed(1)}</priority>` : ''}
+  </url>`
+  )
+  .join('\n')}
+</urlset>`;
+}
+
+/**
+ * Format date for sitemap (ISO 8601)
+ */
+function formatDate(date: string | Date): string {
+  if (typeof date === 'string') {
+    return date;
+  }
+  return date.toISOString().split('T')[0];
+}
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(unsafe: string): string {
+  return unsafe
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Normalize URL (ensure absolute)
+ */
+export function normalizeUrl(url: string, siteUrl: string): string {
+  if (url.startsWith('http://') || url.startsWith('https://')) {
+    return url;
+  }
+  const baseUrl = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl;
+  const path = url.startsWith('/') ? url : `/${url}`;
+  return `${baseUrl}${path}`;
+}
+

package/src/sitemap/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Sitemap exports
+ */
+
+export { createSitemapHandler } from './route';
+export { generateSitemapXml, normalizeUrl } from './generator';
+export type { SitemapGeneratorOptions, SitemapRoute } from './types';
+

package/src/sitemap/route.ts

@@ -0,0 +1,74 @@
+/**
+ * Sitemap Route Handler for Next.js App Router
+ *
+ * Usage:
+ * ```tsx
+ * // app/sitemap.ts
+ * import { createSitemapHandler } from '@djangocfg/nextjs/sitemap';
+ *
+ * export default createSitemapHandler({
+ *   siteUrl: 'https://example.com',
+ *   staticPages: [
+ *     { loc: '/', changefreq: 'daily', priority: 1.0 },
+ *     { loc: '/about', changefreq: 'monthly', priority: 0.8 },
+ *   ],
+ *   dynamicPages: async () => {
+ *     // Fetch dynamic pages from API
+ *     const posts = await fetchPosts();
+ *     return posts.map(post => ({
+ *       loc: `/posts/${post.slug}`,
+ *       lastmod: post.updatedAt,
+ *       changefreq: 'weekly',
+ *       priority: 0.7,
+ *     }));
+ *   },
+ * });
+ * ```
+ */
+
+import { NextResponse } from 'next/server';
+import type { SitemapGeneratorOptions } from './types';
+import { generateSitemapXml, normalizeUrl } from './generator';
+import type { SitemapUrl } from '../types';
+
+export function createSitemapHandler(options: SitemapGeneratorOptions) {
+  const {
+    siteUrl,
+    staticPages = [],
+    dynamicPages = [],
+    cacheControl = 'public, s-maxage=86400, stale-while-revalidate',
+  } = options;
+
+  return async function GET() {
+    const urls: SitemapUrl[] = [...staticPages];
+
+    // Add dynamic pages
+    if (dynamicPages) {
+      if (typeof dynamicPages === 'function') {
+        const dynamicUrls = await dynamicPages();
+        urls.push(...dynamicUrls);
+      } else {
+        urls.push(...dynamicPages);
+      }
+    }
+
+    // Normalize all URLs
+    const normalizedUrls = urls.map((url) => ({
+      ...url,
+      loc: normalizeUrl(url.loc, siteUrl),
+    }));
+
+    // Generate XML
+    const sitemap = generateSitemapXml(normalizedUrls);
+
+    // Return response
+    return new NextResponse(sitemap, {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/xml',
+        'Cache-Control': cacheControl,
+      },
+    });
+  };
+}
+

package/src/sitemap/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Sitemap types
+ */
+
+import type { ChangeFreq, SitemapUrl } from '../types';
+
+export interface SitemapGeneratorOptions {
+  siteUrl: string;
+  staticPages?: SitemapUrl[];
+  dynamicPages?: (() => Promise<SitemapUrl[]>) | SitemapUrl[];
+  cacheControl?: string;
+}
+
+export interface SitemapRoute {
+  path: string;
+  lastmod?: string | Date;
+  changefreq?: ChangeFreq;
+  priority?: number;
+}
+

package/src/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Common types for @djangocfg/nextjs package
+ */
+
+export type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+
+export interface SitemapUrl {
+  loc: string;
+  lastmod?: string;
+  changefreq?: ChangeFreq;
+  priority?: number;
+}
+
+export interface SitemapConfig {
+  siteUrl: string;
+  urls: SitemapUrl[];
+  cacheControl?: string;
+}
+
+export interface HealthResponse {
+  status: 'ok' | 'error';
+  timestamp: string;
+  uptime: number;
+  version?: string;
+  checks?: Record<string, boolean>;
+}
+
+
+export interface ErrorPageConfig {
+  code?: string | number;
+  title?: string;
+  description?: string;
+  supportEmail?: string;
+}
+