@djangocfg/nextjs 2.1.224 → 2.1.226

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

@@ -1,269 +0,0 @@
-/**
- * Metadata Utilities for OG Images
- *
- * Helpers to automatically add og:image to Next.js metadata
- */
-
-import type { Metadata } from 'next';
-import { generateOgImageUrl, getAbsoluteOgImageUrl, OgImageUrlParams } from './url';
-
-/**
- * Options for generating OG image metadata
- */
-export interface AppMetadataOptions {
-  /** Base URL of the OG image API route (e.g., '/api/og') */
-  ogImageBaseUrl?: string;
-  /** Site URL for absolute URLs (e.g., 'https://example.com') */
-  siteUrl?: string;
-  /** Default parameters to merge with page-specific params */
-  defaultParams?: Partial<OgImageUrlParams>;
-  /** Whether to use base64 encoding (default: true) */
-  useBase64?: boolean;
-  /** Favicon URL (e.g., '/favicon.png') - automatically added to metadata.icons */
-  favicon?: string;
-  /** Apple touch icon URL (e.g., '/apple-icon.png') - automatically added to metadata.icons */
-  appleIcon?: string;
-}
-
-/**
- * Extract title from metadata
- */
-function extractTitle(metadata: Metadata): string {
-  if (typeof metadata.title === 'string') {
-    return metadata.title;
-  }
-  if (metadata.title) {
-    if ('default' in metadata.title) {
-      return metadata.title.default;
-    }
-    if ('absolute' in metadata.title) {
-      return metadata.title.absolute;
-    }
-  }
-  return '';
-}
-
-/**
- * Extract description from metadata
- */
-function extractDescription(metadata: Metadata): string {
-  if (typeof metadata.description === 'string') {
-    return metadata.description;
-  }
-  return '';
-}
-
-/**
- * Generate Next.js metadata with OG image
- *
- * Automatically adds og:image, twitter:image, and other OG meta tags
- * Automatically extracts title and description from metadata if not provided
- *
- * @param metadata - Base metadata object
- * @param ogImageParams - Optional parameters for OG image generation (if not provided, extracted from metadata)
- * @param options - Configuration options
- * @returns Enhanced metadata with OG image
- *
- * @example
- * ```typescript
- * // In page.tsx or layout.tsx
- * import { generateAppMetadata } from '@djangocfg/nextjs/og-image';
- * import { settings } from '@/core/settings';
- *
- * export const metadata = generateAppMetadata(
- *   {
- *     title: 'My Page',
- *     description: 'Page description',
- *   },
- *   undefined, // Will auto-extract from metadata
- *   {
- *     ogImageBaseUrl: '/api/og',
- *     siteUrl: settings.app.siteUrl,
- *     favicon: settings.app.icons.favicon,
- *     appleIcon: settings.app.icons.logo192,
- *     defaultParams: {
- *       siteName: settings.app.name,
- *       logo: settings.app.icons.logoVector,
- *     },
- *   }
- * );
- * ```
- */
-/**
- * Get site URL automatically from environment
- * Priority: NEXT_PUBLIC_SITE_URL > VERCEL_URL > fallback
- */
-function getSiteUrl(): string {
-  // Try NEXT_PUBLIC_SITE_URL first (most reliable)
-  if (typeof process !== 'undefined' && process.env.NEXT_PUBLIC_SITE_URL) {
-    return process.env.NEXT_PUBLIC_SITE_URL;
-  }
-  
-  // Development fallback
-  return '';
-}
-
-export function generateAppMetadata(
-  metadata: Metadata,
-  ogImageParams?: Partial<OgImageUrlParams>,
-  options: AppMetadataOptions = {}
-): Metadata {
-  const {
-    ogImageBaseUrl = 'https://djangocfg.com/api/og',
-    siteUrl: providedSiteUrl,
-    defaultParams = {},
-    useBase64 = true,
-    favicon,
-    appleIcon,
-  } = options;
-
-  // Automatically determine siteUrl if not provided or is undefined
-  const siteUrl = providedSiteUrl && providedSiteUrl !== 'undefined' 
-    ? providedSiteUrl 
-    : getSiteUrl();
-
-  // Auto-extract title and description from metadata if not provided
-  const extractedTitle = extractTitle(metadata);
-  const extractedDescription = extractDescription(metadata);
-
-  // Merge with provided params (provided params take precedence)
-  const finalOgImageParams: OgImageUrlParams = {
-    ...defaultParams,
-    title: ogImageParams?.title || extractedTitle || defaultParams.title || '',
-    description: ogImageParams?.description || extractedDescription || defaultParams.description || '',
-    ...ogImageParams,
-  };
-
-  // Get alt text for image (title or siteName as fallback)
-  const imageAlt = finalOgImageParams.title || finalOgImageParams.siteName;
-
-  // Generate relative OG image URL
-  const relativeOgImageUrl = generateOgImageUrl(
-    finalOgImageParams,
-    { baseUrl: ogImageBaseUrl, useBase64 }
-  );
-
-  // CRITICAL: Use absolute URL to ensure query params are preserved
-  // Next.js might strip query params from relative URLs in some cases
-  // Absolute URLs ensure the full URL with params is used
-  const ogImageUrl = siteUrl
-    ? getAbsoluteOgImageUrl(relativeOgImageUrl, siteUrl)
-    : relativeOgImageUrl;
-
-  // Normalize existing images to arrays
-  const existingOgImages = metadata.openGraph?.images
-    ? Array.isArray(metadata.openGraph.images)
-      ? metadata.openGraph.images
-      : [metadata.openGraph.images]
-    : [];
-
-  const existingTwitterImages = metadata.twitter?.images
-    ? Array.isArray(metadata.twitter.images)
-      ? metadata.twitter.images
-      : [metadata.twitter.images]
-    : [];
-
-  // Build final metadata object
-  const finalMetadata: Metadata = {
-    ...metadata,
-    openGraph: {
-      ...metadata.openGraph,
-      images: [
-        ...existingOgImages,
-        {
-          url: ogImageUrl,
-          width: 1200,
-          height: 630,
-          alt: imageAlt,
-        },
-      ],
-    },
-    twitter: {
-      ...metadata.twitter,
-      card: 'summary_large_image',
-      images: [
-        ...existingTwitterImages,
-        {
-          url: ogImageUrl,
-          alt: imageAlt,
-        },
-      ],
-    },
-  };
-
-  // Automatically add metadataBase if siteUrl is an absolute URL
-  // metadataBase requires absolute URL - skip if siteUrl is relative path (like /cfg/admin)
-  // Only add if not already set in input metadata
-  if (!finalMetadata.metadataBase && siteUrl) {
-    // Check if siteUrl is an absolute URL (starts with http:// or https://)
-    if (siteUrl.startsWith('http://') || siteUrl.startsWith('https://')) {
-      try {
-        finalMetadata.metadataBase = new URL(siteUrl);
-      } catch (e) {
-        // If URL construction fails, skip metadataBase
-        // This shouldn't happen if we check for http/https, but just in case
-      }
-    }
-  }
-
-  // Add favicon and apple icon if provided
-  if (favicon || appleIcon) {
-    // metadata.icons can be string, array, or object - only spread if it's an object
-    const existingIcons = metadata.icons && typeof metadata.icons === 'object' && !Array.isArray(metadata.icons)
-      ? metadata.icons
-      : {};
-    finalMetadata.icons = {
-      ...existingIcons,
-      ...(favicon && { icon: favicon }),
-      ...(appleIcon && { apple: appleIcon }),
-    };
-  }
-
-  return finalMetadata;
-}
-
-/**
- * Create OG image metadata generator with preset configuration
- *
- * Useful when you want to reuse the same configuration across multiple pages
- *
- * @param options - Configuration options
- * @returns Metadata generator function
- *
- * @example
- * ```typescript
- * // In a shared file (e.g., lib/metadata.ts)
- * import { createAppMetadataGenerator } from '@djangocfg/nextjs/og-image';
- * import { settings } from '@/core/settings';
- *
- * export const generateMetadata = createAppMetadataGenerator({
- *   ogImageBaseUrl: '/api/og',
- *   siteUrl: settings.app.siteUrl,
- *   favicon: settings.app.icons.favicon,
- *   appleIcon: settings.app.icons.logo192,
- *   defaultParams: {
- *     siteName: settings.app.name,
- *     logo: settings.app.icons.logoVector,
- *   },
- * });
- *
- * // In page.tsx
- * import { generateMetadata } from '@/lib/metadata';
- *
- * export const metadata = generateMetadata({
- *   title: 'My Page',
- *   description: 'Description',
- * });
- * ```
- */
-export function createAppMetadataGenerator(
-  options: AppMetadataOptions
-) {
-  return (
-    metadata: Metadata,
-    ogImageParams?: Partial<OgImageUrlParams>
-  ): Metadata => {
-    return generateAppMetadata(metadata, ogImageParams, options);
-  };
-}
-

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

@@ -1,386 +0,0 @@
-/**
- * URL Generation Helpers for OG Images
- *
- * Utilities to generate OG image URLs with proper query parameters
- */
-
-/** Default OG Image API base URL */
-const DEFAULT_OG_IMAGE_BASE_URL = 'https://djangocfg.com/api/og';
-
-/**
- * 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
- * All parameters can be encoded in URL via base64
- */
-export interface OgImageUrlParams {
-  /** Page title */
-  title: string;
-  /** Page description (optional) */
-  description?: string;
-  /** Site name (optional) */
-  siteName?: string;
-  /** Logo URL (optional) */
-  logo?: string;
-  /** Background type: 'gradient' or 'solid' */
-  backgroundType?: 'gradient' | 'solid';
-  /** Gradient start color (hex) */
-  gradientStart?: string;
-  /** Gradient end color (hex) */
-  gradientEnd?: string;
-  /** Background color (for solid type) */
-  backgroundColor?: string;
-  /** Title font size (px) */
-  titleSize?: number;
-  /** Title font weight */
-  titleWeight?: number;
-  /** Title text color */
-  titleColor?: string;
-  /** Description font size (px) */
-  descriptionSize?: number;
-  /** Description text color */
-  descriptionColor?: string;
-  /** Site name font size (px) */
-  siteNameSize?: number;
-  /** Site name text color */
-  siteNameColor?: string;
-  /** Padding (px) */
-  padding?: number;
-  /** Logo size (px) */
-  logoSize?: number;
-  /** Show logo flag */
-  showLogo?: boolean;
-  /** Show site name flag */
-  showSiteName?: boolean;
-  /** Additional custom parameters */
-  [key: string]: string | number | boolean | undefined;
-}
-
-/**
- * Options for generating OG image URL
- */
-export interface GenerateOgImageUrlOptions {
-  /**
-   * Base URL of the OG image API route
-   * @default 'https://djangocfg.com/api/og'
-   */
-  baseUrl?: string;
-  /**
-   * If true, encode params as base64 for safer URLs
-   * @default true
-   */
-  useBase64?: boolean;
-}
-
-/**
- * Generate OG image URL with query parameters or base64 encoding
- *
- * @param params - URL parameters for the OG image
- * @param options - Generation options (baseUrl, useBase64)
- * @returns Complete OG image URL with encoded parameters
- *
- * @example
- * ```typescript
- * // Using default baseUrl (https://djangocfg.com/api/og)
- * const url = generateOgImageUrl({
- *   title: 'My Page Title',
- *   description: 'Page description here',
- * });
- *
- * // With custom baseUrl
- * const url = generateOgImageUrl(
- *   { title: 'My Page' },
- *   { baseUrl: '/api/og' }
- * );
- * ```
- */
-export function generateOgImageUrl(
-  params: OgImageUrlParams,
-  options: GenerateOgImageUrlOptions = {}
-): string {
-  const {
-    baseUrl = DEFAULT_OG_IMAGE_BASE_URL,
-    useBase64 = true
-  } = options;
-
-  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
-    // IMPORTANT: Add trailing slash to avoid 308 redirects which cause timeouts in crawlers
-    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 {
-  // If path is already an absolute URL, return as-is
-  if (relativePath.startsWith('http://') || relativePath.startsWith('https://')) {
-    return relativePath;
-  }
-
-  // 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 defaults - Default parameters to merge with each URL generation
- * @param options - Default options (baseUrl, useBase64)
- * @returns URL builder function
- *
- * @example
- * ```typescript
- * const buildOgUrl = createOgImageUrlBuilder(
- *   { siteName: 'My Site', logo: '/logo.png' },
- *   { baseUrl: '/api/og' }
- * );
- *
- * const url1 = buildOgUrl({ title: 'Page 1' });
- * const url2 = buildOgUrl({ title: 'Page 2', description: 'Custom desc' });
- * ```
- */
-export function createOgImageUrlBuilder(
-  defaults: Partial<OgImageUrlParams> = {},
-  options: GenerateOgImageUrlOptions = {}
-) {
-  return (params: OgImageUrlParams): string => {
-    return generateOgImageUrl(
-      { ...defaults, ...params },
-      options
-    );
-  };
-}
-
-/**
- * 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 };