@djangocfg/nextjs 1.0.6 → 2.1.1

package/src/config/utils/deepMerge.ts

@@ -0,0 +1,33 @@
+/**
+ * Deep Merge Utility
+ *
+ * Recursively merges objects, replacing arrays instead of merging them.
+ */
+
+export function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T {
+  const output = { ...target };
+
+  for (const key in source) {
+    if (source[key] === undefined) continue;
+
+    // Arrays: replace (don't merge arrays)
+    if (Array.isArray(source[key])) {
+      output[key] = source[key] as any;
+    }
+    // Objects: deep merge
+    else if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      const targetValue = output[key];
+      if (targetValue && typeof targetValue === 'object' && !Array.isArray(targetValue)) {
+        output[key] = deepMerge(targetValue, source[key] as any);
+      } else {
+        output[key] = source[key] as any;
+      }
+    }
+    // Primitives: replace
+    else {
+      output[key] = source[key] as any;
+    }
+  }
+
+  return output;
+}

package/src/config/utils/env.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment Variable Utilities
+ */
+
+export const isStaticBuild = process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+export const isDev = process.env.NODE_ENV === 'development';
+export const isProduction = process.env.NODE_ENV === 'production';
+export const isCI = process.env.CI === 'true';
+
+/**
+ * Get base path for static builds
+ */
+export function getBasePath(isDefaultCfgAdmin?: boolean): string {
+  if (!isStaticBuild) return '';
+  return isDefaultCfgAdmin ? '/cfg/admin' : '/cfg/nextjs-admin';
+}
+
+/**
+ * Get API URL (empty for static builds)
+ */
+export function getApiUrl(): string {
+  return isStaticBuild ? '' : (process.env.NEXT_PUBLIC_API_URL || '');
+}
+
+/**
+ * Get Site URL (empty for static builds)
+ */
+export function getSiteUrl(): string {
+  return isStaticBuild ? '' : (process.env.NEXT_PUBLIC_SITE_URL || '');
+}

package/src/config/utils/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Utilities exports
+ */
+
+export { deepMerge } from './deepMerge';
+export * from './env';
+export * from './version';

package/src/config/utils/version.ts

@@ -0,0 +1,121 @@
+/**
+ * Version Checking Utilities
+ */
+
+import chalk from 'chalk';
+import semver from 'semver';
+import consola from 'consola';
+import Conf from 'conf';
+import { PACKAGE_NAME, VERSION_CACHE_TTL_MS, DJANGOCFG_PACKAGES } from '../constants';
+
+// Version cache using conf (stores in ~/.config/djangocfg-nextjs/)
+const versionCache = new Conf<{
+  latestVersion?: string;
+  lastCheck?: number;
+}>({
+  projectName: 'djangocfg-nextjs',
+  projectVersion: '1.0.0',
+});
+
+/**
+ * Get current package version from package.json
+ */
+export function getCurrentVersion(): string | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const packageJson = require('../../../package.json');
+    return packageJson.version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch latest version from npm registry (with 1 hour caching via conf)
+ */
+export async function fetchLatestVersion(): Promise<string | null> {
+  // Check cache first
+  const lastCheck = versionCache.get('lastCheck') || 0;
+  const cachedVersion = versionCache.get('latestVersion');
+
+  if (cachedVersion && (Date.now() - lastCheck) < VERSION_CACHE_TTL_MS) {
+    return cachedVersion;
+  }
+
+  // Fetch from npm registry
+  try {
+    const https = await import('https');
+    return new Promise((resolve) => {
+      const req = https.get(
+        `https://registry.npmjs.org/${PACKAGE_NAME}/latest`,
+        { timeout: 5000 },
+        (res: any) => {
+          let data = '';
+          res.on('data', (chunk: string) => { data += chunk; });
+          res.on('end', () => {
+            try {
+              const json = JSON.parse(data);
+              const version = json.version || null;
+              if (version) {
+                versionCache.set('latestVersion', version);
+                versionCache.set('lastCheck', Date.now());
+              }
+              resolve(version);
+            } catch {
+              resolve(cachedVersion || null);
+            }
+          });
+        }
+      );
+      req.on('error', () => resolve(cachedVersion || null));
+      req.on('timeout', () => { req.destroy(); resolve(cachedVersion || null); });
+    });
+  } catch {
+    return cachedVersion || null;
+  }
+}
+
+/**
+ * Check if update is available
+ */
+export async function checkForUpdate(): Promise<{
+  hasUpdate: boolean;
+  currentVersion: string | null;
+  latestVersion: string | null;
+}> {
+  const currentVersion = getCurrentVersion();
+  if (!currentVersion) {
+    return { hasUpdate: false, currentVersion: null, latestVersion: null };
+  }
+
+  const latestVersion = await fetchLatestVersion();
+  const hasUpdate = !!(latestVersion && semver.gt(latestVersion, currentVersion));
+
+  return { hasUpdate, currentVersion, latestVersion };
+}
+
+/**
+ * Get update command for all djangocfg packages
+ */
+export function getUpdateCommand(): string {
+  return `pnpm add ${DJANGOCFG_PACKAGES.map(p => `${p}@latest`).join(' ')}`;
+}
+
+/**
+ * Print version info and update notification
+ */
+export async function printVersionInfo(): Promise<void> {
+  const { hasUpdate, currentVersion, latestVersion } = await checkForUpdate();
+
+  if (!currentVersion) return;
+
+  // Print current version
+  consola.box(`📦 @djangocfg/nextjs v${currentVersion}`);
+
+  // Show update notification if available
+  if (hasUpdate && latestVersion) {
+    consola.warn(`Update Available! ${chalk.red(currentVersion)} → ${chalk.green(latestVersion)}`);
+    consola.info(`Run: ${chalk.cyan(getUpdateCommand())}`);
+    console.log('');
+  }
+}

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

@@ -131,9 +131,8 @@ export function generateOgImageMetadata(
 
   // Generate relative OG image URL
   const relativeOgImageUrl = generateOgImageUrl(
-    ogImageBaseUrl,
     finalOgImageParams,
-    useBase64
+    { baseUrl: ogImageBaseUrl, useBase64 }
   );
 
   // CRITICAL: Use absolute URL to ensure query params are preserved

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

@@ -4,6 +4,9 @@
  * 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
@@ -90,47 +93,53 @@ export interface OgImageUrlParams {
   [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 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)
+ * @param options - Generation options (baseUrl, useBase64)
  * @returns Complete OG image URL with encoded parameters
  *
  * @example
  * ```typescript
- * // Base64 encoding (safe, default) - all parameters can be encoded
- * const url = generateOgImageUrl('/api/og', {
+ * // Using default baseUrl (https://djangocfg.com/api/og)
+ * const url = generateOgImageUrl({
  *   title: 'My Page Title',
  *   description: 'Page description here',
- *   siteName: 'My Site',
- *   logo: '/logo.svg',
- *   backgroundType: 'gradient',
- *   gradientStart: '#0f172a',
- *   gradientEnd: '#334155',
- *   titleSize: 80,
- *   titleWeight: 800,
- *   titleColor: 'white',
- *   descriptionSize: 36,
- *   descriptionColor: 'rgba(226, 232, 240, 0.9)',
- *   siteNameSize: 32,
- *   siteNameColor: 'rgba(255, 255, 255, 0.95)',
- *   padding: 80,
- *   logoSize: 56,
  * });
- * // Result: /api/og/[base64-encoded-json]
  *
- * // Query params (legacy)
- * const url = generateOgImageUrl('/api/og', { title: 'Hello' }, false);
- * // Result: /api/og?title=Hello
+ * // With custom baseUrl
+ * const url = generateOgImageUrl(
+ *   { title: 'My Page' },
+ *   { baseUrl: '/api/og' }
+ * );
  * ```
  */
 export function generateOgImageUrl(
-  baseUrl: string,
   params: OgImageUrlParams,
-  useBase64: boolean = true
+  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> = {};
@@ -186,6 +195,11 @@ 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(/\/$/, '');
 
@@ -202,30 +216,30 @@ export function getAbsoluteOgImageUrl(
  *
  * 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
+ * @param options - Default options (baseUrl, useBase64)
  * @returns URL builder function
  *
  * @example
  * ```typescript
- * const buildOgUrl = createOgImageUrlBuilder('/api/og', {
- *   siteName: 'My Site',
- *   logo: '/logo.png'
- * });
+ * 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(
-  baseUrl: string,
-  defaults: Partial<OgImageUrlParams> = {}
+  defaults: Partial<OgImageUrlParams> = {},
+  options: GenerateOgImageUrlOptions = {}
 ) {
   return (params: OgImageUrlParams): string => {
-    return generateOgImageUrl(baseUrl, {
-      ...defaults,
-      ...params,
-    });
+    return generateOgImageUrl(
+      { ...defaults, ...params },
+      options
+    );
   };
 }
 
@@ -287,7 +301,7 @@ export function parseOgImageData(
   try {
     // Handle URLSearchParams
     let params: Record<string, string | undefined>;
-    
+
     if (searchParams instanceof URLSearchParams) {
       // Convert URLSearchParams to object
       params = {};
@@ -310,18 +324,18 @@ export function parseOgImageData(
       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)) {
@@ -329,11 +343,11 @@ export function parseOgImageData(
             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);
@@ -355,11 +369,11 @@ export function parseOgImageData(
         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);
@@ -369,4 +383,3 @@ export function parseOgImageData(
 
 // Export base64 utilities for advanced use cases
 export { encodeBase64, decodeBase64 };
-