@od-oneapp/seo 2026.1.1301

package/src/server.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Server-side SEO exports (non-Next.js)
+ *
+ * This file provides server-side SEO functionality for non-Next.js environments.
+ * For Next.js applications, use '@repo/seo/server/next' instead.
+ *
+ * @module @repo/seo/server
+ *
+ * @example
+ * ```typescript
+ * import { createStructuredData, structuredData } from '@repo/seo/server';
+ *
+ * const article = structuredData.article({
+ *   headline: 'My Article',
+ *   author: 'John Doe',
+ *   datePublished: '2024-01-01',
+ *   publisher: { name: 'Publisher', logo: '/logo.png' }
+ * });
+ * ```
+ */
+
+// Re-export everything from the shared builders
+export { createStructuredData, structuredData } from './utils/structured-data-builders';
+
+// Re-export types
+export type { Thing, WithContext } from 'schema-dts';
+export type { StructuredDataType } from './utils/structured-data-builders';

package/src/types/metadata.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Metadata Type Definitions
+ *
+ * Provides TypeScript types for metadata and OpenGraph structures.
+ * Used for Next.js metadata generation and validation.
+ *
+ * @module @repo/seo/types/metadata
+ */
+
+/**
+ * Enhanced metadata options for SEO generators
+ */
+export interface MetadataOptions {
+  alternates?: {
+    canonical?: string;
+    languages?: Record<string, string>;
+  };
+  article?: {
+    authors?: string[];
+    expirationTime?: string;
+    modifiedTime?: string;
+    publishedTime?: string;
+    section?: string;
+    tags?: string[];
+  };
+  canonical?: string;
+  description: string;
+  image?: string | { alt?: string; height?: number; url: string; width?: number };
+  keywords?: string[];
+  noFollow?: boolean;
+  noIndex?: boolean;
+  title: string;
+}
+
+/**
+ * OpenGraph data structure
+ */
+export interface OpenGraphData {
+  title: string;
+  description: string;
+  type: 'website' | 'article' | 'profile' | 'product';
+  url?: string;
+  siteName?: string;
+  images?: Array<{
+    url: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+  }>;
+  locale?: string;
+  publishedTime?: string;
+  modifiedTime?: string;
+  authors?: string[];
+  tags?: string[];
+  section?: string;
+}
+
+/**
+ * Twitter Card data structure
+ */
+export interface TwitterCardData {
+  card: 'summary' | 'summary_large_image' | 'app' | 'player';
+  site?: string;
+  creator?: string;
+  title?: string;
+  description?: string;
+  images?: string[];
+}
+
+/**
+ * Complete metadata structure
+ */
+export interface CompleteMetadata {
+  title: string;
+  description: string;
+  keywords?: string[];
+  canonical?: string;
+  openGraph?: OpenGraphData;
+  twitter?: TwitterCardData;
+  robots?: {
+    index?: boolean;
+    follow?: boolean;
+  };
+  themeColor?: string;
+}

package/src/types/seo.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Core SEO Type Definitions
+ *
+ * Provides TypeScript types for SEO functionality and configurations.
+ * Includes structured data types and SEO configuration interfaces.
+ *
+ * @module @repo/seo/types/seo
+ */
+
+// Re-export from schema-dts for convenience
+export type { Thing, WithContext } from 'schema-dts';
+
+/**
+ * Common structured data types with better type safety
+ */
+export type StructuredDataType =
+  | 'Article'
+  | 'BlogPosting'
+  | 'BreadcrumbList'
+  | 'Course'
+  | 'Event'
+  | 'FAQPage'
+  | 'HowTo'
+  | 'LocalBusiness'
+  | 'Organization'
+  | 'Person'
+  | 'Product'
+  | 'Recipe'
+  | 'SoftwareApplication'
+  | 'VideoObject'
+  | 'WebSite';
+
+/**
+ * Configuration for SEO setup
+ */
+export interface SEOConfig {
+  applicationName: string;
+  author: {
+    name: string;
+    url: string;
+  };
+  keywords?: string[];
+  locale?: string;
+  publisher: string;
+  themeColor?: string;
+  twitterHandle: string;
+}
+
+/**
+ * Basic SEO metadata structure
+ */
+export interface SEOMetadata {
+  title: string;
+  description: string;
+  image?: string;
+  keywords?: string[];
+  canonical?: string;
+  noIndex?: boolean;
+  noFollow?: boolean;
+}

package/src/types/structured-data.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Structured Data Type Definitions
+ *
+ * Provides TypeScript types for schema.org structured data.
+ * Includes input types for common structured data schemas.
+ *
+ * @module @repo/seo/types/structured-data
+ */
+
+// Re-export from schema-dts for convenience
+export type { Thing, WithContext } from 'schema-dts';
+
+/**
+ * Article structured data input
+ */
+export interface ArticleData {
+  author: string | { name: string; url?: string };
+  dateModified?: string;
+  datePublished: string;
+  description?: string;
+  headline: string;
+  image?: string | string[];
+  mainEntityOfPage?: string;
+  publisher: {
+    logo?: string;
+    name: string;
+  };
+}
+
+/**
+ * Product structured data input
+ */
+export interface ProductData {
+  aggregateRating?: {
+    ratingValue: number;
+    reviewCount: number;
+  };
+  brand?: string;
+  description?: string;
+  image?: string | string[];
+  name: string;
+  offers?: {
+    availability?: string;
+    price: string;
+    priceCurrency: string;
+    seller?: string;
+  };
+}
+
+/**
+ * Organization structured data input
+ */
+export interface OrganizationData {
+  contactPoint?: {
+    areaServed?: string | string[];
+    availableLanguage?: string | string[];
+    contactType: string;
+    telephone: string;
+  };
+  description?: string;
+  logo?: string;
+  name: string;
+  sameAs?: string[];
+  url: string;
+}
+
+/**
+ * Website structured data input
+ */
+export interface WebsiteData {
+  description?: string;
+  name: string;
+  potentialAction?: {
+    queryInput: string;
+    target: string;
+  };
+  url: string;
+}
+
+/**
+ * Breadcrumb item
+ */
+export interface BreadcrumbItem {
+  name: string;
+  url: string;
+}
+
+/**
+ * FAQ item
+ */
+export interface FAQItem {
+  answer: string;
+  question: string;
+}

package/src/utils/i18n-enhanced.ts

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview i18n-enhanced SEO utilities
+ *
+ * Provides internationalization-aware SEO metadata generation.
+ * Extends SEOManager with locale-specific metadata and translations support.
+ *
+ * @module @repo/seo/utils/i18n-enhanced
+ */
+
+import { type Metadata } from 'next';
+
+import { SEOManager } from './metadata-enhanced';
+
+interface I18nSEOConfig {
+  defaultLocale: string;
+  localeNames: Record<string, string>;
+  locales: string[];
+  rtlLocales?: string[];
+}
+
+export class I18nSEOManager extends SEOManager {
+  private i18nConfig: I18nSEOConfig;
+
+  constructor(config: ConstructorParameters<typeof SEOManager>[0] & { i18n: I18nSEOConfig }) {
+    super(config);
+    this.i18nConfig = config.i18n;
+  }
+
+  createI18nMetadata(
+    options: Parameters<SEOManager['createMetadata']>[0] & {
+      locale: string;
+      translations?: Record<string, { description: string; title: string }>;
+    },
+  ): Metadata {
+    const { locale, translations, ...baseOptions } = options;
+
+    // Use translated title and description if available
+    const localizedTitle = translations?.[locale]?.title ?? baseOptions.title;
+    const localizedDescription = translations?.[locale]?.description ?? baseOptions.description;
+
+    // Generate language alternates automatically
+    const languageAlternates: Record<string, string> = {};
+    this.i18nConfig.locales.forEach(loc => {
+      if (baseOptions.alternates?.canonical) {
+        const basePath = baseOptions.alternates.canonical.replace(/^\/[a-z]{2}\//, '/');
+        languageAlternates[loc] = `/${loc}${basePath}`;
+      }
+    });
+
+    // Determine OpenGraph locale format
+    const ogLocale = this.formatOpenGraphLocale(locale);
+
+    // Get alternate locales for OpenGraph
+    const alternateLocales = this.i18nConfig.locales
+      .filter(loc => loc !== locale)
+      .map(loc => this.formatOpenGraphLocale(loc));
+
+    const metadata = super.createMetadata({
+      ...baseOptions,
+      alternates: {
+        ...baseOptions.alternates,
+        languages: languageAlternates,
+      },
+      description: localizedDescription,
+      title: localizedTitle,
+    });
+
+    // Enhance OpenGraph with locale information
+    if (metadata.openGraph) {
+      metadata.openGraph.locale = ogLocale;
+      metadata.openGraph.alternateLocale = alternateLocales;
+    }
+
+    // Add language meta tag
+    const otherMetadata: Record<string, (number | string)[] | number | string> = {
+      'content-language': locale,
+    };
+
+    // Handle RTL languages
+    if (this.i18nConfig.rtlLocales?.includes(locale)) {
+      otherMetadata.direction = 'rtl';
+    }
+
+    // Merge with existing metadata.other
+    if (metadata.other) {
+      Object.entries(metadata.other).forEach(([key, value]) => {
+        otherMetadata[key] = value;
+      });
+    }
+
+    metadata.other = otherMetadata;
+
+    return metadata;
+  }
+
+  // Create localized structured data
+  createLocalizedStructuredData<T>(
+    type: string,
+    data: T,
+    locale: string,
+    translations?: Record<string, Partial<T>>,
+  ): T {
+    const localizedData = translations?.[locale] ? { ...data, ...translations[locale] } : data;
+
+    return {
+      ...localizedData,
+      '@context': 'https://schema.org',
+      '@type': type,
+      inLanguage: locale,
+    } as T;
+  }
+
+  // Generate hreflang tags for international SEO
+
+  generateHreflangTags(currentPath: string, _currentLocale: string): Record<string, string> {
+    const hreflangTags: Record<string, string> = {};
+
+    // Add x-default for default locale
+    const basePath = currentPath.replace(/^\/[a-z]{2}\//, '/');
+    hreflangTags['x-default'] = `/${this.i18nConfig.defaultLocale}${basePath}`;
+
+    // Add all locale variations
+    this.i18nConfig.locales.forEach(locale => {
+      hreflangTags[locale] = `/${locale}${basePath}`;
+    });
+
+    return hreflangTags;
+  }
+
+  // Format locale for OpenGraph (e.g., 'en' -> 'en_US', 'fr' -> 'fr_FR')
+  private formatOpenGraphLocale(locale: string): string {
+    const localeMap: Record<string, string> = {
+      ar: 'ar_SA',
+      de: 'de_DE',
+      en: 'en_US',
+      es: 'es_ES',
+      fr: 'fr_FR',
+      it: 'it_IT',
+      ja: 'ja_JP',
+      ko: 'ko_KR',
+      nl: 'nl_NL',
+      pt: 'pt_BR',
+      ru: 'ru_RU',
+      zh: 'zh_CN',
+    };
+    return localeMap[locale] ?? `${locale}_${locale.toUpperCase()}`;
+  }
+}

package/src/utils/metadata-enhanced.ts

@@ -0,0 +1,238 @@
+/**
+ * @fileoverview Enhanced metadata utilities for SEO
+ *
+ * Provides advanced metadata generation with enhanced features including
+ * SEO manager class, viewport configuration, and comprehensive metadata merging.
+ *
+ * @module @repo/seo/utils/metadata-enhanced
+ */
+
+import { type Metadata, type Viewport } from 'next';
+
+import { logWarn } from '@repo/shared/logger';
+import merge from 'lodash.merge';
+
+import { getProtocol, safeEnv } from '../../env';
+
+import { validateUrls } from './validation';
+
+// Constants for Open Graph image dimensions (recommended by OG spec)
+const OG_IMAGE_WIDTH = 1200;
+const OG_IMAGE_HEIGHT = 630;
+
+/**
+ * Safely creates a URL object with error handling
+ */
+function safeCreateUrl(url: string | undefined, protocol: string): URL | undefined {
+  if (!url) return undefined;
+
+  try {
+    const fullUrl = url.startsWith('http') ? url : `${protocol}://${url}`;
+    if (!validateUrls([fullUrl])) {
+      logWarn(`[SEO] Invalid URL provided: ${url}, skipping metadataBase`, { url });
+      return undefined;
+    }
+    return new URL(fullUrl);
+  } catch (error) {
+    logWarn(`[SEO] Failed to create URL from ${url}:`, { error });
+    return undefined;
+  }
+}
+
+interface MetadataGeneratorOptions {
+  alternates?: {
+    canonical?: string;
+    languages?: Record<string, string>;
+  };
+  article?: {
+    authors?: string[];
+    expirationTime?: string;
+    modifiedTime?: string;
+    publishedTime?: string;
+    section?: string;
+    tags?: string[];
+  };
+  canonical?: string;
+  description: string;
+  image?: string | { alt?: string; height?: number; url: string; width?: number };
+  keywords?: string[];
+  noFollow?: boolean;
+  noIndex?: boolean;
+  other?: Record<string, string | number | (string | number)[]>;
+  title: string;
+}
+
+interface SEOConfig {
+  applicationName: string;
+  author: {
+    name: string;
+    url: string;
+  };
+  keywords?: string[];
+  locale?: string;
+  publisher: string;
+  themeColor?: string;
+  twitterHandle: string;
+}
+
+// Enhanced viewport configuration for better mobile experience
+export const viewport: Viewport = {
+  initialScale: 1,
+  maximumScale: 5,
+  userScalable: true,
+  viewportFit: 'cover',
+  width: 'device-width',
+};
+
+export class SEOManager {
+  private config: SEOConfig;
+
+  constructor(config: SEOConfig) {
+    this.config = config;
+  }
+
+  // Generate metadata for error pages
+  createErrorMetadata(statusCode: number): Metadata {
+    const titles: Record<number, string> = {
+      404: 'Page Not Found',
+      500: 'Internal Server Error',
+      503: 'Service Unavailable',
+    };
+
+    return this.createMetadata({
+      description: `Error ${statusCode}`,
+      noFollow: true,
+      noIndex: true,
+      title: titles[statusCode] ?? 'Error',
+    });
+  }
+
+  createMetadata(options: MetadataGeneratorOptions): Metadata {
+    const {
+      alternates,
+      article,
+      canonical,
+      description,
+      image,
+      keywords = [],
+      noFollow = false,
+      noIndex = false,
+      title,
+      ...additionalProperties
+    } = options;
+
+    const protocol = getProtocol();
+    const envVars = safeEnv();
+    const productionUrl = envVars.VERCEL_PROJECT_PRODUCTION_URL ?? envVars.NEXT_PUBLIC_URL;
+    const parsedTitle = `${title} | ${this.config.applicationName}`;
+
+    // Combine default keywords with page-specific ones
+    const allKeywords = [...(this.config.keywords ?? []), ...keywords];
+
+    const defaultMetadata: Metadata = {
+      // Alternates for i18n and canonical URLs
+      alternates: alternates ?? (canonical ? { canonical } : undefined),
+      // Apple Web App
+      appleWebApp: {
+        capable: true,
+        statusBarStyle: 'default',
+        title,
+      },
+      applicationName: this.config.applicationName,
+      // App Links for mobile deep linking
+      appLinks: {},
+      authors: [{ name: this.config.author.name, url: this.config.author.url }],
+      creator: this.config.author.name,
+      description,
+
+      // Enhanced format detection
+      formatDetection: {
+        address: false,
+        date: false,
+        email: false,
+        telephone: false,
+      },
+
+      keywords: allKeywords,
+
+      // Metadata base for absolute URLs
+      metadataBase: safeCreateUrl(productionUrl, protocol),
+
+      // Open Graph
+      openGraph: {
+        description,
+        locale: this.config.locale ?? 'en_US',
+        siteName: this.config.applicationName,
+        title: parsedTitle,
+        type: article ? 'article' : 'website',
+        ...(article && {
+          article: {
+            ...(article.authors && { authors: article.authors }),
+            ...(article.expirationTime && { expirationTime: article.expirationTime }),
+            ...(article.modifiedTime && { modifiedTime: article.modifiedTime }),
+            ...(article.publishedTime && { publishedTime: article.publishedTime }),
+            ...(article.section && { section: article.section }),
+            ...(article.tags && { tags: article.tags }),
+          },
+        }),
+      },
+
+      publisher: this.config.publisher,
+
+      // Robots directives
+      robots: {
+        follow: !noFollow,
+        googleBot: {
+          follow: !noFollow,
+          index: !noIndex,
+          'max-image-preview': 'large',
+          'max-snippet': -1,
+          'max-video-preview': -1,
+        },
+        index: !noIndex,
+      },
+
+      title: {
+        default: parsedTitle,
+        template: `%s | ${this.config.applicationName}`,
+      },
+
+      // Twitter Card
+      twitter: {
+        card: 'summary_large_image',
+        creator: this.config.twitterHandle,
+        description,
+        site: this.config.twitterHandle,
+        title: parsedTitle,
+      },
+
+      // Verification (can be extended)
+      verification: {},
+    };
+
+    // Handle image configuration
+    if (image) {
+      const imageData =
+        typeof image === 'string'
+          ? { alt: title, height: OG_IMAGE_HEIGHT, url: image, width: OG_IMAGE_WIDTH }
+          : { alt: title, height: OG_IMAGE_HEIGHT, width: OG_IMAGE_WIDTH, ...image };
+
+      if (defaultMetadata.openGraph) {
+        defaultMetadata.openGraph.images = [imageData];
+      }
+      if (defaultMetadata.twitter) {
+        defaultMetadata.twitter.images = [imageData.url];
+      }
+    }
+
+    // Theme color
+    if (this.config.themeColor) {
+      defaultMetadata.themeColor = [
+        { color: this.config.themeColor, media: '(prefers-color-scheme: light)' },
+        { color: this.config.themeColor, media: '(prefers-color-scheme: dark)' },
+      ];
+    }
+
+    return merge(defaultMetadata, additionalProperties);
+  }
+}