@od-oneapp/seo 2026.1.1301

package/src/utils/metadata.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview Metadata Utilities
+ *
+ * Core utilities for generating Next.js metadata with validation and error handling.
+ * Provides type-safe metadata creation with OpenGraph and Twitter Card support.
+ *
+ * @module @repo/seo/utils/metadata
+ */
+
+import { type Metadata } from 'next';
+
+import { logWarn } from '@repo/shared/logger';
+import merge from 'lodash.merge';
+
+import { getProtocol, safeEnv } from '../../env';
+
+import { validateUrls } from './validation';
+
+/**
+ * Open Graph image dimensions recommended by OG specification
+ * Aspect ratio: ~1.91:1 (1200x630)
+ * @see https://ogp.me/#structured
+ */
+const OG_IMAGE_WIDTH = 1200;
+const OG_IMAGE_HEIGHT = 630;
+
+/**
+ * Safely creates a URL object with comprehensive error handling
+ *
+ * This function handles URL creation with validation and graceful degradation:
+ * - Returns undefined for empty/null input
+ * - Validates URL format before creating URL object
+ * - Adds protocol if missing
+ * - Logs warnings for invalid URLs but doesn't throw
+ *
+ * @param url - URL string to parse (with or without protocol)
+ * @param protocol - Protocol to use if URL doesn't have one ('http' or 'https')
+ * @returns Parsed URL object or undefined if invalid
+ *
+ * @example
+ * ```typescript
+ * const url = safeCreateUrl('example.com', 'https');
+ * // Returns: URL { href: 'https://example.com', ... }
+ *
+ * const invalid = safeCreateUrl('not a url', 'https');
+ * // Logs warning, returns: undefined
+ * ```
+ */
+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, url });
+    return undefined;
+  }
+}
+
+/**
+ * Metadata generator options
+ */
+type MetadataGenerator = Omit<Metadata, 'description' | 'title'> & {
+  /** Page description (required) */
+  description: string;
+  /** Page title (required, will be combined with applicationName) */
+  title: string;
+  /** Optional Open Graph image URL */
+  image?: string;
+  /** Application name (defaults to 'Application') */
+  applicationName?: string;
+  /** Author information */
+  author?: Metadata['authors'];
+  /** Publisher name */
+  publisher?: string;
+  /** Twitter handle (e.g., '@username') */
+  twitterHandle?: string;
+};
+
+/**
+ * Create comprehensive Next.js metadata with sensible defaults
+ *
+ * Generates a complete metadata object with:
+ * - Title and description
+ * - Open Graph tags for social media
+ * - Twitter Card metadata
+ * - Apple Web App configuration
+ * - Format detection settings
+ *
+ * @param options - Metadata configuration
+ * @returns Complete Next.js Metadata object
+ *
+ * @example
+ * ```typescript
+ * export const metadata = createMetadata({
+ *   title: 'Home Page',
+ *   description: 'Welcome to our site',
+ *   applicationName: 'My App',
+ *   image: '/og-image.png',
+ *   author: { name: 'John Doe', url: 'https://johndoe.com' },
+ *   publisher: 'My Company',
+ *   twitterHandle: '@myapp'
+ * });
+ * ```
+ */
+export const createMetadata = ({
+  description,
+  image,
+  title,
+  applicationName = 'Application',
+  author = { name: 'Author', url: 'https://example.com' },
+  publisher = 'Publisher',
+  twitterHandle = '@site',
+  ...properties
+}: MetadataGenerator): Metadata => {
+  const protocol = getProtocol();
+  const envVars = safeEnv();
+  const productionUrl = envVars.VERCEL_PROJECT_PRODUCTION_URL ?? envVars.NEXT_PUBLIC_URL;
+  const parsedTitle = `${title} | ${applicationName}`;
+  const defaultMetadata: Metadata = {
+    appleWebApp: {
+      capable: true,
+      statusBarStyle: 'default',
+      title: parsedTitle,
+    },
+    applicationName,
+    authors: author ? (Array.isArray(author) ? author : [author]) : undefined,
+    creator: author ? (Array.isArray(author) ? author[0]?.name : author.name) : undefined,
+    description,
+    formatDetection: {
+      telephone: false,
+    },
+    metadataBase: safeCreateUrl(productionUrl, protocol),
+    openGraph: {
+      description,
+      locale: 'en_US',
+      siteName: applicationName,
+      title: parsedTitle,
+      type: 'website',
+    },
+    publisher,
+    title: parsedTitle,
+    twitter: {
+      card: 'summary_large_image',
+      creator: twitterHandle,
+      site: twitterHandle,
+    },
+  };
+
+  const metadata: Metadata = merge(defaultMetadata, properties);
+
+  if (image && metadata.openGraph) {
+    metadata.openGraph.images = [
+      {
+        alt: title,
+        height: OG_IMAGE_HEIGHT,
+        url: image,
+        width: OG_IMAGE_WIDTH,
+      },
+    ];
+  }
+
+  return metadata;
+};

package/src/utils/structured-data-builders.ts

@@ -0,0 +1,322 @@
+/**
+ * @fileoverview Structured Data Builders
+ *
+ * Shared utilities for creating Schema.org structured data (JSON-LD).
+ * This file contains type-safe builders for common schema types.
+ *
+ * Features:
+ * - Type-safe structured data creation
+ * - Schema.org validation
+ * - Common schema builders (Article, Product, Organization, etc.)
+ *
+ * @module @repo/seo/utils/structured-data-builders
+ */
+
+import { logWarn } from '@repo/shared/logger';
+import {
+  type Article,
+  type BreadcrumbList,
+  type FAQPage,
+  type Organization,
+  type Product,
+  type Thing,
+  type WebSite,
+  type WithContext,
+} from 'schema-dts';
+
+import { isProduction } from '../../env';
+
+import { validateSchemaOrgDetailed } from './validation';
+
+/**
+ * Common structured data types with better type safety
+ */
+export type StructuredDataType =
+  | 'Article'
+  | 'BlogPosting'
+  | 'BreadcrumbList'
+  | 'Course'
+  | 'Event'
+  | 'FAQPage'
+  | 'HowTo'
+  | 'LocalBusiness'
+  | 'Organization'
+  | 'Person'
+  | 'Product'
+  | 'Recipe'
+  | 'SoftwareApplication'
+  | 'Thing'
+  | 'VideoObject'
+  | 'WebSite';
+
+/**
+ * Helper function to create structured data with proper typing and validation
+ *
+ * Creates Schema.org compliant structured data with automatic validation in
+ * development mode. Validation errors are logged to console but don't throw
+ * to avoid breaking builds.
+ *
+ * @param type - Schema.org type (e.g., 'Article', 'Product', 'Organization')
+ * @param data - The data object (without @context and @type)
+ * @param options - Optional configuration
+ * @param options.validate - Force validation even in production (default: false)
+ * @returns WithContext<T> structured data ready for JSON-LD
+ * @throws Never throws - validation errors are logged only
+ *
+ * @example
+ * ```typescript
+ * const article = createStructuredData('Article', {
+ *   headline: 'My Article',
+ *   author: { '@type': 'Person', name: 'John Doe' },
+ *   datePublished: '2024-01-01'
+ * });
+ * ```
+ */
+export function createStructuredData<TType extends StructuredDataType, T extends Thing>(
+  type: TType,
+  data: Omit<T, '@context' | '@type'>,
+  options?: { validate?: boolean },
+): WithContext<T> {
+  const structured = {
+    '@context': 'https://schema.org',
+    '@type': type,
+    ...data,
+  } as unknown as WithContext<T>;
+
+  // Validation in development or when explicitly requested
+  const shouldValidate = options?.validate ?? !isProduction();
+
+  if (shouldValidate) {
+    const result = validateSchemaOrgDetailed(structured, type);
+    if (!result.valid) {
+      logWarn(`[SEO] Structured data validation failed for type '${type}'`, {
+        errors: result.errors.join(', '),
+        type,
+      });
+    }
+  }
+
+  return structured;
+}
+
+/**
+ * Pre-built structured data builders for common schema types.
+ * Each builder provides type-safe creation of Schema.org compliant JSON-LD.
+ *
+ * @example
+ * ```typescript
+ * // Article schema
+ * const article = structuredData.article({
+ *   headline: 'My Article',
+ *   author: 'John Doe',
+ *   datePublished: '2024-01-01',
+ *   publisher: { name: 'My Site', logo: '/logo.png' }
+ * });
+ *
+ * // Product schema
+ * const product = structuredData.product({
+ *   name: 'Product Name',
+ *   image: '/product.jpg',
+ *   offers: {
+ *     price: '99.99',
+ *     priceCurrency: 'USD'
+ *   }
+ * });
+ * ```
+ */
+export const structuredData = {
+  /**
+   * Create an Article schema
+   * @param data - Article data
+   * @returns Article structured data
+   */
+  article: (data: {
+    author: string | { name: string; url?: string };
+    dateModified?: string;
+    datePublished: string;
+    description?: string;
+    headline: string;
+    image?: string | string[];
+    mainEntityOfPage?: string;
+    publisher: {
+      logo?: string;
+      name: string;
+    };
+  }): WithContext<Article> =>
+    createStructuredData<'Article', Article>('Article', {
+      author:
+        typeof data.author === 'string'
+          ? { '@type': 'Person', name: data.author }
+          : { '@type': 'Person', ...data.author },
+      dateModified: data.dateModified ?? data.datePublished,
+      datePublished: data.datePublished,
+      description: data.description,
+      headline: data.headline,
+      image: data.image,
+      mainEntityOfPage: data.mainEntityOfPage && {
+        '@id': data.mainEntityOfPage,
+        '@type': 'WebPage',
+      },
+      publisher: {
+        '@type': 'Organization',
+        name: data.publisher.name,
+        ...(data.publisher.logo && {
+          logo: {
+            '@type': 'ImageObject',
+            url: data.publisher.logo,
+          },
+        }),
+      },
+    }),
+
+  /**
+   * Create a BreadcrumbList schema
+   * @param items - Array of breadcrumb items
+   * @returns BreadcrumbList structured data
+   */
+  breadcrumbs: (items: { name: string; url: string }[]): WithContext<BreadcrumbList> =>
+    createStructuredData<'BreadcrumbList', BreadcrumbList>('BreadcrumbList', {
+      itemListElement: items.map((item, index) => ({
+        '@type': 'ListItem',
+        item: item.url,
+        name: item.name,
+        position: index + 1,
+      })),
+    }),
+
+  /**
+   * Create an FAQPage schema
+   * @param items - Array of question/answer pairs
+   * @returns FAQPage structured data
+   */
+  faq: (items: { answer: string; question: string }[]): WithContext<FAQPage> =>
+    createStructuredData<'FAQPage', FAQPage>('FAQPage', {
+      mainEntity: items.map(item => ({
+        '@type': 'Question',
+        acceptedAnswer: {
+          '@type': 'Answer',
+          text: item.answer,
+        },
+        name: item.question,
+      })),
+    }),
+
+  /**
+   * Create an Organization schema
+   * @param data - Organization data
+   * @returns Organization structured data
+   */
+  organization: (data: {
+    contactPoint?: {
+      areaServed?: string | string[];
+      availableLanguage?: string | string[];
+      contactType: string;
+      telephone: string;
+    };
+    description?: string;
+    logo?: string;
+    name: string;
+    sameAs?: string[];
+    url: string;
+  }): WithContext<Organization> =>
+    createStructuredData<'Organization', Organization>('Organization', {
+      description: data.description,
+      logo: data.logo,
+      name: data.name,
+      sameAs: data.sameAs,
+      url: data.url,
+      ...(data.contactPoint && {
+        contactPoint: {
+          '@type': 'ContactPoint',
+          ...data.contactPoint,
+        },
+      }),
+    }),
+
+  /**
+   * Create a Product schema
+   * @param data - Product data
+   * @returns Product structured data
+   */
+  product: (data: {
+    aggregateRating?: {
+      ratingValue: number;
+      reviewCount: number;
+    };
+    brand?: string;
+    description?: string;
+    image?: string | string[];
+    name: string;
+    offers?: {
+      availability?: string;
+      price: string;
+      priceCurrency: string;
+      seller?: string;
+    };
+  }): WithContext<Product> =>
+    createStructuredData<'Product', Product>('Product', {
+      description: data.description,
+      image: data.image,
+      name: data.name,
+      ...(data.brand && {
+        brand: {
+          '@type': 'Brand',
+          name: data.brand,
+        },
+      }),
+      ...(data.offers && {
+        offers: {
+          '@type': 'Offer',
+          availability: (data.offers.availability ?? 'https://schema.org/InStock') as any,
+          price: data.offers.price,
+          priceCurrency: data.offers.priceCurrency,
+          ...(data.offers.seller && {
+            seller: {
+              '@type': 'Organization',
+              name: data.offers.seller,
+            },
+          }),
+        },
+      }),
+      ...(data.aggregateRating && {
+        aggregateRating: {
+          '@type': 'AggregateRating',
+          ratingValue: data.aggregateRating.ratingValue,
+          reviewCount: data.aggregateRating.reviewCount,
+        },
+      }),
+    }),
+
+  /**
+   * Create a WebSite schema
+   * @param data - Website data
+   * @returns WebSite structured data
+   */
+  website: (data: {
+    description?: string;
+    name: string;
+    potentialAction?: {
+      queryInput: string;
+      target: string;
+    };
+    url: string;
+  }): WithContext<WebSite> =>
+    createStructuredData<'WebSite', WebSite>('WebSite', {
+      description: data.description,
+      name: data.name,
+      url: data.url,
+      ...(data.potentialAction && {
+        potentialAction: {
+          '@type': 'SearchAction',
+          'query-input': `required name=${data.potentialAction.queryInput}` as any,
+          target: {
+            '@type': 'EntryPoint',
+            urlTemplate: data.potentialAction.target,
+          },
+        } as any,
+      }),
+    }),
+};
+
+// Re-export types for convenience
+export type { Thing, WithContext } from 'schema-dts';