@djangocfg/ext-newsletter 1.0.0

package/src/api/generated/ext_newsletter/storage.ts

@@ -0,0 +1,161 @@
+/**
+ * Storage adapters for cross-platform token storage.
+ *
+ * Supports:
+ * - LocalStorage (browser)
+ * - Cookies (SSR/browser)
+ * - Memory (Node.js/Electron/testing)
+ */
+
+import type { APILogger } from './logger';
+
+/**
+ * Storage adapter interface for cross-platform token storage.
+ */
+export interface StorageAdapter {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/**
+ * LocalStorage adapter with safe try-catch for browser environments.
+ * Works in modern browsers with localStorage support.
+ * 
+ * Note: This adapter uses window.localStorage and should only be used in browser/client environments.
+ * For server-side usage, use MemoryStorageAdapter or CookieStorageAdapter instead.
+ */
+export class LocalStorageAdapter implements StorageAdapter {
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        const value = localStorage.getItem(key);
+        this.logger?.debug(`LocalStorage.getItem("${key}"): ${value ? 'found' : 'not found'}`);
+        return value;
+      }
+      this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+    } catch (error) {
+      this.logger?.error('LocalStorage.getItem failed:', error);
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.setItem(key, value);
+        this.logger?.debug(`LocalStorage.setItem("${key}"): success`);
+      } else {
+        this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+      }
+    } catch (error) {
+      this.logger?.error('LocalStorage.setItem failed:', error);
+    }
+  }
+
+  removeItem(key: string): void {
+    try {
+      if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.removeItem(key);
+        this.logger?.debug(`LocalStorage.removeItem("${key}"): success`);
+      } else {
+        this.logger?.warn('LocalStorage not available: window.localStorage is undefined');
+      }
+    } catch (error) {
+      this.logger?.error('LocalStorage.removeItem failed:', error);
+    }
+  }
+}
+
+/**
+ * Cookie-based storage adapter for SSR and browser environments.
+ * Useful for Next.js, Nuxt.js, and other SSR frameworks.
+ */
+export class CookieStorageAdapter implements StorageAdapter {
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    try {
+      if (typeof document === 'undefined') {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+        return null;
+      }
+      const value = `; ${document.cookie}`;
+      const parts = value.split(`; ${key}=`);
+      if (parts.length === 2) {
+        const result = parts.pop()?.split(';').shift() || null;
+        this.logger?.debug(`CookieStorage.getItem("${key}"): ${result ? 'found' : 'not found'}`);
+        return result;
+      }
+      this.logger?.debug(`CookieStorage.getItem("${key}"): not found`);
+    } catch (error) {
+      this.logger?.error('CookieStorage.getItem failed:', error);
+    }
+    return null;
+  }
+
+  setItem(key: string, value: string): void {
+    try {
+      if (typeof document !== 'undefined') {
+        document.cookie = `${key}=${value}; path=/; max-age=31536000`;
+        this.logger?.debug(`CookieStorage.setItem("${key}"): success`);
+      } else {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+      }
+    } catch (error) {
+      this.logger?.error('CookieStorage.setItem failed:', error);
+    }
+  }
+
+  removeItem(key: string): void {
+    try {
+      if (typeof document !== 'undefined') {
+        document.cookie = `${key}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+        this.logger?.debug(`CookieStorage.removeItem("${key}"): success`);
+      } else {
+        this.logger?.warn('Cookies not available: document is undefined (SSR context?)');
+      }
+    } catch (error) {
+      this.logger?.error('CookieStorage.removeItem failed:', error);
+    }
+  }
+}
+
+/**
+ * In-memory storage adapter for Node.js, Electron, and testing environments.
+ * Data is stored in RAM and cleared when process exits.
+ */
+export class MemoryStorageAdapter implements StorageAdapter {
+  private storage: Map<string, string> = new Map();
+  private logger?: APILogger;
+
+  constructor(logger?: APILogger) {
+    this.logger = logger;
+  }
+
+  getItem(key: string): string | null {
+    const value = this.storage.get(key) || null;
+    this.logger?.debug(`MemoryStorage.getItem("${key}"): ${value ? 'found' : 'not found'}`);
+    return value;
+  }
+
+  setItem(key: string, value: string): void {
+    this.storage.set(key, value);
+    this.logger?.debug(`MemoryStorage.setItem("${key}"): success`);
+  }
+
+  removeItem(key: string): void {
+    this.storage.delete(key);
+    this.logger?.debug(`MemoryStorage.removeItem("${key}"): success`);
+  }
+}

package/src/api/generated/ext_newsletter/validation-events.ts

@@ -0,0 +1,133 @@
+/**
+ * Zod Validation Events - Browser CustomEvent integration
+ *
+ * Dispatches browser CustomEvents when Zod validation fails, allowing
+ * React/frontend apps to listen and handle validation errors globally.
+ *
+ * @example
+ * ```typescript
+ * // In your React app
+ * window.addEventListener('zod-validation-error', (event) => {
+ *   const { operation, path, method, error, response } = event.detail;
+ *   console.error(`Validation failed for ${method} ${path}`, error);
+ *   // Show toast notification, log to Sentry, etc.
+ * });
+ * ```
+ */
+
+import type { ZodError } from 'zod'
+
+/**
+ * Validation error event detail
+ */
+export interface ValidationErrorDetail {
+  /** Operation/function name that failed validation */
+  operation: string
+  /** API endpoint path */
+  path: string
+  /** HTTP method */
+  method: string
+  /** Zod validation error */
+  error: ZodError
+  /** Raw response data that failed validation */
+  response: any
+  /** Timestamp of the error */
+  timestamp: Date
+}
+
+/**
+ * Custom event type for Zod validation errors
+ */
+export type ValidationErrorEvent = CustomEvent<ValidationErrorDetail>
+
+/**
+ * Dispatch a Zod validation error event.
+ *
+ * Only dispatches in browser environment (when window is defined).
+ * Safe to call in Node.js/SSR - will be a no-op.
+ *
+ * @param detail - Validation error details
+ */
+export function dispatchValidationError(detail: ValidationErrorDetail): void {
+  // Check if running in browser
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  try {
+    const event = new CustomEvent<ValidationErrorDetail>('zod-validation-error', {
+      detail,
+      bubbles: true,
+      cancelable: false,
+    })
+
+    window.dispatchEvent(event)
+  } catch (error) {
+    // Silently fail - validation event dispatch should never crash the app
+    console.warn('Failed to dispatch validation error event:', error)
+  }
+}
+
+/**
+ * Add a global listener for Zod validation errors.
+ *
+ * @param callback - Function to call when validation error occurs
+ * @returns Cleanup function to remove the listener
+ *
+ * @example
+ * ```typescript
+ * const cleanup = onValidationError(({ operation, error }) => {
+ *   toast.error(`Validation failed in ${operation}`);
+ *   logToSentry(error);
+ * });
+ *
+ * // Later, remove listener
+ * cleanup();
+ * ```
+ */
+export function onValidationError(
+  callback: (detail: ValidationErrorDetail) => void
+): () => void {
+  if (typeof window === 'undefined') {
+    // Return no-op cleanup function for SSR
+    return () => {}
+  }
+
+  const handler = (event: Event) => {
+    if (event instanceof CustomEvent) {
+      callback(event.detail)
+    }
+  }
+
+  window.addEventListener('zod-validation-error', handler)
+
+  // Return cleanup function
+  return () => {
+    window.removeEventListener('zod-validation-error', handler)
+  }
+}
+
+/**
+ * Format Zod error for logging/display.
+ *
+ * @param error - Zod validation error
+ * @returns Formatted error message
+ */
+export function formatZodError(error: ZodError): string {
+  const issues = error.issues.map((issue, index) => {
+    const path = issue.path.join('.') || 'root'
+    const parts = [`${index + 1}. ${path}: ${issue.message}`]
+
+    if ('expected' in issue && issue.expected) {
+      parts.push(`   Expected: ${issue.expected}`)
+    }
+
+    if ('received' in issue && issue.received) {
+      parts.push(`   Received: ${issue.received}`)
+    }
+
+    return parts.join('\n')
+  })
+
+  return issues.join('\n')
+}

package/src/api/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Newsletter Extension API
+ *
+ * Pre-configured API instance with shared authentication
+ */
+import { API } from './generated/ext_newsletter';
+import { createExtensionAPI } from '@djangocfg/ext-base/api';
+
+export const apiNewsletter = createExtensionAPI(API);

package/src/components/Hero/index.tsx

@@ -0,0 +1,160 @@
+/**
+ * Hero Component with Newsletter Subscription
+ * Landing page hero section with integrated email subscription form
+ */
+
+'use client';
+
+import React, { useState } from 'react';
+import { Button, Input } from '@djangocfg/ui-nextjs';
+import { Mail, CheckCircle2, AlertCircle, Loader2 } from 'lucide-react';
+import { newsletterLogger } from '../../utils/logger';
+import type { HeroProps } from './types';
+
+export function Hero({
+  title,
+  description,
+  primaryAction,
+  secondaryAction,
+  showNewsletter = true,
+  newsletterPlaceholder = 'Enter your email',
+  newsletterButtonText = 'Subscribe',
+  onNewsletterSubmit,
+  className = '',
+}: HeroProps) {
+  const [email, setEmail] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [status, setStatus] = useState<'idle' | 'success' | 'error'>('idle');
+  const [message, setMessage] = useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!email || !onNewsletterSubmit) return;
+
+    setIsLoading(true);
+    setStatus('idle');
+    setMessage('');
+
+    try {
+      const result = await onNewsletterSubmit(email);
+      setStatus('success');
+      setMessage((result && 'message' in result ? result.message : undefined) || 'Successfully subscribed!');
+      setEmail('');
+      newsletterLogger.success('Newsletter subscription successful:', email);
+    } catch (error) {
+      setStatus('error');
+      setMessage(error instanceof Error ? error.message : 'Subscription failed. Please try again.');
+      newsletterLogger.error('Newsletter subscription failed:', error);
+    } finally {
+      setIsLoading(false);
+
+      // Reset status after 5 seconds
+      setTimeout(() => {
+        setStatus('idle');
+        setMessage('');
+      }, 5000);
+    }
+  };
+
+  return (
+    <section className={`relative py-16 sm:py-20 md:py-24 lg:py-32 ${className}`}>
+      <div className="container max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="max-w-3xl mx-auto text-center">
+          {/* Title */}
+          <h1 className="text-4xl sm:text-5xl md:text-6xl font-bold tracking-tight text-foreground mb-6">
+            {title}
+          </h1>
+
+          {/* Description */}
+          {description && (
+            <p className="text-lg sm:text-xl text-muted-foreground mb-8 max-w-2xl mx-auto">
+              {description}
+            </p>
+          )}
+
+          {/* Actions */}
+          <div className="flex flex-col sm:flex-row gap-4 justify-center items-center mb-12">
+            {primaryAction && (
+              <Button
+                size="lg"
+                onClick={primaryAction.onClick}
+                className="w-full sm:w-auto"
+              >
+                {primaryAction.label}
+              </Button>
+            )}
+
+            {secondaryAction && (
+              <Button
+                size="lg"
+                variant="outline"
+                onClick={secondaryAction.onClick}
+                className="w-full sm:w-auto"
+              >
+                {secondaryAction.label}
+              </Button>
+            )}
+          </div>
+
+          {/* Newsletter Subscription */}
+          {showNewsletter && onNewsletterSubmit && (
+            <div className="max-w-md mx-auto">
+              <form onSubmit={handleSubmit} className="space-y-3">
+                <div className="flex flex-col sm:flex-row gap-2">
+                  <div className="relative flex-1">
+                    <Mail className="absolute left-3 top-1/2 -translate-y-1/2 h-5 w-5 text-muted-foreground" />
+                    <Input
+                      type="email"
+                      placeholder={newsletterPlaceholder}
+                      value={email}
+                      onChange={(e) => setEmail(e.target.value)}
+                      disabled={isLoading}
+                      required
+                      className="pl-10"
+                    />
+                  </div>
+                  <Button
+                    type="submit"
+                    disabled={isLoading || !email}
+                    className="w-full sm:w-auto"
+                  >
+                    {isLoading ? (
+                      <>
+                        <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                        Subscribing...
+                      </>
+                    ) : (
+                      newsletterButtonText
+                    )}
+                  </Button>
+                </div>
+
+                {/* Status Messages */}
+                {status === 'success' && (
+                  <div className="flex items-center gap-2 text-sm text-green-600 dark:text-green-400">
+                    <CheckCircle2 className="h-4 w-4" />
+                    <span>{message}</span>
+                  </div>
+                )}
+
+                {status === 'error' && (
+                  <div className="flex items-center gap-2 text-sm text-red-600 dark:text-red-400">
+                    <AlertCircle className="h-4 w-4" />
+                    <span>{message}</span>
+                  </div>
+                )}
+              </form>
+
+              <p className="text-xs text-muted-foreground mt-3">
+                By subscribing, you agree to our Privacy Policy and consent to receive updates.
+              </p>
+            </div>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export default Hero;

package/src/components/Hero/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Hero Component Types
+ */
+
+export interface HeroAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface HeroProps {
+  /** Main heading text */
+  title: string;
+
+  /** Supporting description text */
+  description?: string;
+
+  /** Primary call-to-action button */
+  primaryAction?: HeroAction;
+
+  /** Secondary call-to-action button */
+  secondaryAction?: HeroAction;
+
+  /** Show newsletter subscription form */
+  showNewsletter?: boolean;
+
+  /** Email input placeholder */
+  newsletterPlaceholder?: string;
+
+  /** Subscribe button text */
+  newsletterButtonText?: string;
+
+  /** Newsletter submission handler */
+  onNewsletterSubmit?: (email: string) => Promise<{ message?: string } | void>;
+
+  /** Additional CSS classes */
+  className?: string;
+}

package/src/config.ts

@@ -0,0 +1,20 @@
+/**
+ * Newsletter extension configuration
+ */
+
+import type { ExtensionMetadata } from '@djangocfg/ext-base';
+
+export const extensionConfig: ExtensionMetadata = {
+  name: 'newsletter',
+  version: '1.0.0',
+  author: 'DjangoCFG',
+  displayName: 'Newsletter',
+  description: 'Newsletter subscription and campaign management',
+  icon: '📧',
+  license: 'MIT',
+  githubUrl: 'https://github.com/markolofsen/django-cfg',
+  homepage: 'https://djangocfg.com',
+  keywords: ['newsletter', 'email', 'subscription', 'campaign', 'marketing'],
+  dependencies: [],
+  minVersion: '2.0.0',
+} as const;