@aws505/sheetsite 1.0.0

package/src/data/types.ts

@@ -0,0 +1,379 @@
+/**
+ * SheetSite Data Types
+ *
+ * These types define the structure of data fetched from Google Sheets.
+ * All data flows through these types, providing type safety across the entire site.
+ */
+
+import { z } from 'zod';
+
+// =============================================================================
+// BUSINESS INFO
+// =============================================================================
+
+export const BusinessInfoSchema = z.object({
+  name: z.string().min(1),
+  tagline: z.string().optional(),
+  description: z.string().optional(),
+  aboutShort: z.string().optional(),
+  aboutLong: z.string().optional(),
+
+  // Contact
+  phone: z.string().optional(),
+  phoneAlt: z.string().optional(),
+  email: z.string().email().optional().or(z.literal('')),
+
+  // Address
+  addressLine1: z.string().optional(),
+  addressLine2: z.string().optional(),
+  city: z.string().optional(),
+  state: z.string().optional(),
+  zip: z.string().optional(),
+  country: z.string().default('USA'),
+
+  // Location
+  googleMapsUrl: z.string().url().optional().or(z.literal('')),
+  mapsEmbedUrl: z.string().url().optional().or(z.literal('')),
+  timezone: z.string().default('America/Los_Angeles'),
+
+  // Images
+  logoUrl: z.string().optional(),
+  heroImageUrl: z.string().optional(),
+  ogImageUrl: z.string().optional(),
+
+  // Social
+  socialYelp: z.string().url().optional().or(z.literal('')),
+  socialInstagram: z.string().url().optional().or(z.literal('')),
+  socialFacebook: z.string().url().optional().or(z.literal('')),
+  socialTwitter: z.string().url().optional().or(z.literal('')),
+  socialLinkedIn: z.string().url().optional().or(z.literal('')),
+  socialYoutube: z.string().url().optional().or(z.literal('')),
+  socialTiktok: z.string().url().optional().or(z.literal('')),
+
+  // CTAs
+  primaryCtaText: z.string().optional(),
+  primaryCtaUrl: z.string().optional(),
+  secondaryCtaText: z.string().optional(),
+  secondaryCtaUrl: z.string().optional(),
+  bookingUrl: z.string().url().optional().or(z.literal('')),
+
+  // Banner
+  bannerEnabled: z.boolean().default(false),
+  bannerText: z.string().optional(),
+  bannerUrl: z.string().optional(),
+
+  // Business metadata
+  priceRange: z.enum(['$', '$$', '$$$', '$$$$']).optional(),
+  yearEstablished: z.number().optional(),
+  licenseNumber: z.string().optional(),
+});
+
+export type BusinessInfo = z.infer<typeof BusinessInfoSchema>;
+
+// =============================================================================
+// HOURS
+// =============================================================================
+
+export const DayOfWeek = z.enum(['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']);
+export type DayOfWeek = z.infer<typeof DayOfWeek>;
+
+export const HoursEntrySchema = z.object({
+  day: DayOfWeek,
+  open: z.string().optional(), // e.g., "9:00 AM"
+  close: z.string().optional(), // e.g., "5:00 PM"
+  closed: z.boolean().default(false),
+});
+
+export type HoursEntry = z.infer<typeof HoursEntrySchema>;
+
+export const HoursSchema = z.array(HoursEntrySchema);
+export type Hours = z.infer<typeof HoursSchema>;
+
+// =============================================================================
+// SERVICES
+// =============================================================================
+
+export const ServiceSchema = z.object({
+  id: z.string().optional(),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  priceNote: z.string().optional(), // e.g., "Starting at $15" or "Call for quote"
+  price: z.number().optional(), // Exact price if applicable
+  duration: z.string().optional(), // e.g., "30 min"
+  icon: z.string().optional(), // Icon identifier
+  imageUrl: z.string().optional(),
+  featured: z.boolean().default(false),
+  sortOrder: z.number().default(0),
+  category: z.string().optional(),
+});
+
+export type Service = z.infer<typeof ServiceSchema>;
+
+export const ServicesSchema = z.array(ServiceSchema);
+export type Services = z.infer<typeof ServicesSchema>;
+
+// =============================================================================
+// GALLERY
+// =============================================================================
+
+export const GalleryItemSchema = z.object({
+  id: z.string().optional(),
+  imageUrl: z.string().min(1),
+  alt: z.string().optional(),
+  caption: z.string().optional(),
+  featured: z.boolean().default(false),
+  sortOrder: z.number().default(0),
+  category: z.string().optional(),
+});
+
+export type GalleryItem = z.infer<typeof GalleryItemSchema>;
+
+export const GallerySchema = z.array(GalleryItemSchema);
+export type Gallery = z.infer<typeof GallerySchema>;
+
+// =============================================================================
+// TESTIMONIALS / REVIEWS
+// =============================================================================
+
+export const TestimonialSchema = z.object({
+  id: z.string().optional(),
+  quote: z.string().min(1),
+  name: z.string().min(1),
+  context: z.string().optional(), // e.g., "Wedding alterations"
+  rating: z.number().min(1).max(5).optional(),
+  source: z.string().optional(), // e.g., "Google", "Yelp"
+  date: z.string().optional(),
+  imageUrl: z.string().optional(), // Reviewer photo
+  featured: z.boolean().default(false),
+  sortOrder: z.number().default(0),
+});
+
+export type Testimonial = z.infer<typeof TestimonialSchema>;
+
+export const TestimonialsSchema = z.array(TestimonialSchema);
+export type Testimonials = z.infer<typeof TestimonialsSchema>;
+
+// =============================================================================
+// FAQ
+// =============================================================================
+
+export const FAQItemSchema = z.object({
+  id: z.string().optional(),
+  question: z.string().min(1),
+  answer: z.string().min(1),
+  category: z.string().optional(),
+  sortOrder: z.number().default(0),
+});
+
+export type FAQItem = z.infer<typeof FAQItemSchema>;
+
+export const FAQSchema = z.array(FAQItemSchema);
+export type FAQ = z.infer<typeof FAQSchema>;
+
+// =============================================================================
+// TEAM MEMBERS (for businesses that want to showcase staff)
+// =============================================================================
+
+export const TeamMemberSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().min(1),
+  role: z.string().optional(),
+  bio: z.string().optional(),
+  imageUrl: z.string().optional(),
+  email: z.string().email().optional().or(z.literal('')),
+  phone: z.string().optional(),
+  sortOrder: z.number().default(0),
+});
+
+export type TeamMember = z.infer<typeof TeamMemberSchema>;
+
+export const TeamSchema = z.array(TeamMemberSchema);
+export type Team = z.infer<typeof TeamSchema>;
+
+// =============================================================================
+// MENU ITEMS (for restaurants, cafes, food businesses)
+// =============================================================================
+
+export const MenuItemSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  price: z.number().optional(),
+  priceNote: z.string().optional(),
+  category: z.string().optional(),
+  imageUrl: z.string().optional(),
+  dietary: z.array(z.string()).optional(), // e.g., ["vegetarian", "gluten-free"]
+  featured: z.boolean().default(false),
+  available: z.boolean().default(true),
+  sortOrder: z.number().default(0),
+});
+
+export type MenuItem = z.infer<typeof MenuItemSchema>;
+
+export const MenuSchema = z.array(MenuItemSchema);
+export type Menu = z.infer<typeof MenuSchema>;
+
+// =============================================================================
+// PRODUCTS (for craft sellers, retail)
+// =============================================================================
+
+export const ProductSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().min(1),
+  description: z.string().optional(),
+  price: z.number().optional(),
+  priceNote: z.string().optional(),
+  category: z.string().optional(),
+  imageUrl: z.string().optional(),
+  images: z.array(z.string()).optional(),
+  inStock: z.boolean().default(true),
+  featured: z.boolean().default(false),
+  sortOrder: z.number().default(0),
+  sku: z.string().optional(),
+  purchaseUrl: z.string().url().optional().or(z.literal('')),
+});
+
+export type Product = z.infer<typeof ProductSchema>;
+
+export const ProductsSchema = z.array(ProductSchema);
+export type Products = z.infer<typeof ProductsSchema>;
+
+// =============================================================================
+// ANNOUNCEMENTS / SPECIALS
+// =============================================================================
+
+export const AnnouncementSchema = z.object({
+  id: z.string().optional(),
+  title: z.string().min(1),
+  content: z.string().optional(),
+  imageUrl: z.string().optional(),
+  linkUrl: z.string().optional(),
+  linkText: z.string().optional(),
+  startDate: z.string().optional(),
+  endDate: z.string().optional(),
+  active: z.boolean().default(true),
+  sortOrder: z.number().default(0),
+});
+
+export type Announcement = z.infer<typeof AnnouncementSchema>;
+
+export const AnnouncementsSchema = z.array(AnnouncementSchema);
+export type Announcements = z.infer<typeof AnnouncementsSchema>;
+
+// =============================================================================
+// COMPLETE SITE DATA
+// =============================================================================
+
+export const SiteDataSchema = z.object({
+  business: BusinessInfoSchema,
+  hours: HoursSchema,
+  services: ServicesSchema,
+  gallery: GallerySchema,
+  testimonials: TestimonialsSchema,
+  faq: FAQSchema,
+  team: TeamSchema.optional(),
+  menu: MenuSchema.optional(),
+  products: ProductsSchema.optional(),
+  announcements: AnnouncementsSchema.optional(),
+});
+
+export type SiteData = z.infer<typeof SiteDataSchema>;
+
+// =============================================================================
+// PARTIAL SITE DATA (for merging with defaults)
+// =============================================================================
+
+export const PartialSiteDataSchema = z.object({
+  business: BusinessInfoSchema.partial().optional(),
+  hours: HoursSchema.optional(),
+  services: ServicesSchema.optional(),
+  gallery: GallerySchema.optional(),
+  testimonials: TestimonialsSchema.optional(),
+  faq: FAQSchema.optional(),
+  team: TeamSchema.optional(),
+  menu: MenuSchema.optional(),
+  products: ProductsSchema.optional(),
+  announcements: AnnouncementsSchema.optional(),
+});
+
+export type PartialSiteData = z.infer<typeof PartialSiteDataSchema>;
+
+// =============================================================================
+// SHEET CONFIGURATION
+// =============================================================================
+
+export type SheetMode = 'public_csv' | 'private_api';
+
+export interface SheetTabConfig {
+  name: string;
+  required: boolean;
+  csvUrl?: string;
+}
+
+export interface PublicCsvConfig {
+  mode: 'public_csv';
+  tabs: {
+    business: string;
+    hours?: string;
+    services?: string;
+    gallery?: string;
+    testimonials?: string;
+    faq?: string;
+    team?: string;
+    menu?: string;
+    products?: string;
+    announcements?: string;
+  };
+}
+
+export interface PrivateApiConfig {
+  mode: 'private_api';
+  sheetId: string;
+  clientEmail: string;
+  privateKey: string;
+  tabs?: {
+    business?: string;
+    hours?: string;
+    services?: string;
+    gallery?: string;
+    testimonials?: string;
+    faq?: string;
+    team?: string;
+    menu?: string;
+    products?: string;
+    announcements?: string;
+  };
+}
+
+/**
+ * Inline data configuration - pass data directly without Google Sheets.
+ * This is useful for:
+ * - Rapid prototyping
+ * - Automated site generation from CSV/JSON leads
+ * - Testing without network requests
+ * - Demo sites with pre-populated content
+ */
+export interface InlineDataConfig {
+  mode: 'inline';
+  data: PartialSiteData;
+}
+
+export type SheetConfig = PublicCsvConfig | PrivateApiConfig | InlineDataConfig;
+
+// =============================================================================
+// UTILITY TYPES
+// =============================================================================
+
+export interface ContactFormData {
+  name: string;
+  email: string;
+  phone?: string;
+  service?: string;
+  message: string;
+}
+
+export interface ContactFormResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}

package/src/seo/index.ts

@@ -0,0 +1,272 @@
+/**
+ * SheetSite SEO Module
+ *
+ * Utilities for generating SEO metadata, JSON-LD structured data,
+ * sitemaps, and robots.txt.
+ */
+
+import type { BusinessInfo, HoursEntry, SiteData } from '../data/types';
+
+// =============================================================================
+// METADATA GENERATION
+// =============================================================================
+
+export interface MetadataOptions {
+  titleTemplate?: string;
+  baseUrl?: string;
+}
+
+/**
+ * Generate metadata for a page.
+ */
+export function generateMetadata(
+  business: BusinessInfo,
+  pageTitle?: string,
+  pageDescription?: string,
+  options: MetadataOptions = {}
+) {
+  const { titleTemplate = '%s', baseUrl } = options;
+
+  const title = pageTitle
+    ? titleTemplate.replace('%s', pageTitle)
+    : business.name;
+
+  const description = pageDescription || business.description || business.aboutShort || '';
+
+  const locationString = [business.city, business.state].filter(Boolean).join(', ');
+
+  return {
+    title,
+    description,
+    keywords: [
+      business.name,
+      locationString,
+      // Add more keywords based on business type
+    ].filter(Boolean),
+    openGraph: {
+      title,
+      description,
+      type: 'website',
+      ...(baseUrl && { url: baseUrl }),
+      ...(business.ogImageUrl && { images: [{ url: business.ogImageUrl }] }),
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description,
+      ...(business.ogImageUrl && { images: [business.ogImageUrl] }),
+    },
+  };
+}
+
+// =============================================================================
+// JSON-LD STRUCTURED DATA
+// =============================================================================
+
+export type JsonLdType =
+  | 'LocalBusiness'
+  | 'Restaurant'
+  | 'Store'
+  | 'ProfessionalService'
+  | 'HealthAndBeautyBusiness'
+  | 'FoodEstablishment'
+  | 'HomeAndConstructionBusiness'
+  | 'AutomotiveBusiness';
+
+/**
+ * Convert 12-hour time to 24-hour format for JSON-LD.
+ */
+function convertTo24Hour(time: string): string {
+  const match = time.match(/(\d{1,2}):?(\d{2})?\s*(AM|PM)?/i);
+  if (!match) return time;
+
+  let hours = parseInt(match[1], 10);
+  const minutes = match[2] || '00';
+  const period = match[3]?.toUpperCase();
+
+  if (period === 'PM' && hours !== 12) hours += 12;
+  if (period === 'AM' && hours === 12) hours = 0;
+
+  return `${hours.toString().padStart(2, '0')}:${minutes}`;
+}
+
+/**
+ * Generate opening hours specification for JSON-LD.
+ */
+function generateOpeningHoursSpec(hours: HoursEntry[]) {
+  const dayMap: Record<string, string> = {
+    monday: 'Monday',
+    tuesday: 'Tuesday',
+    wednesday: 'Wednesday',
+    thursday: 'Thursday',
+    friday: 'Friday',
+    saturday: 'Saturday',
+    sunday: 'Sunday',
+  };
+
+  return hours
+    .filter((h) => !h.closed && h.open && h.close)
+    .map((h) => ({
+      '@type': 'OpeningHoursSpecification',
+      dayOfWeek: dayMap[h.day],
+      opens: convertTo24Hour(h.open!),
+      closes: convertTo24Hour(h.close!),
+    }));
+}
+
+/**
+ * Generate JSON-LD structured data for a local business.
+ */
+export function generateLocalBusinessJsonLd(
+  data: SiteData,
+  options: {
+    type?: JsonLdType;
+    baseUrl?: string;
+  } = {}
+): object {
+  const { business, hours, testimonials } = data;
+  const { type = 'LocalBusiness', baseUrl } = options;
+
+  const address = {
+    '@type': 'PostalAddress',
+    streetAddress: [business.addressLine1, business.addressLine2].filter(Boolean).join(', '),
+    addressLocality: business.city,
+    addressRegion: business.state,
+    postalCode: business.zip,
+    addressCountry: business.country || 'US',
+  };
+
+  const jsonLd: Record<string, unknown> = {
+    '@context': 'https://schema.org',
+    '@type': type,
+    name: business.name,
+    description: business.description || business.aboutShort,
+    ...(baseUrl && { url: baseUrl }),
+    ...(business.phone && { telephone: business.phone }),
+    ...(business.email && { email: business.email }),
+    ...(business.logoUrl && { logo: business.logoUrl }),
+    ...(business.heroImageUrl && { image: business.heroImageUrl }),
+    ...(business.addressLine1 && { address }),
+    ...(business.priceRange && { priceRange: business.priceRange }),
+    ...(hours.length > 0 && { openingHoursSpecification: generateOpeningHoursSpec(hours) }),
+  };
+
+  // Add aggregate rating if testimonials exist
+  if (testimonials.length > 0) {
+    const ratings = testimonials.filter((t) => t.rating).map((t) => t.rating!);
+    if (ratings.length > 0) {
+      const avgRating = ratings.reduce((a, b) => a + b, 0) / ratings.length;
+      jsonLd.aggregateRating = {
+        '@type': 'AggregateRating',
+        ratingValue: avgRating.toFixed(1),
+        reviewCount: ratings.length,
+        bestRating: 5,
+        worstRating: 1,
+      };
+    }
+  }
+
+  return jsonLd;
+}
+
+/**
+ * Generate the script tag content for JSON-LD.
+ */
+export function generateJsonLdScript(jsonLd: object): string {
+  return JSON.stringify(jsonLd, null, 2);
+}
+
+// =============================================================================
+// SITEMAP GENERATION
+// =============================================================================
+
+export interface SitemapUrl {
+  loc: string;
+  lastmod?: string;
+  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  priority?: number;
+}
+
+/**
+ * Generate sitemap URLs for common pages.
+ */
+export function generateSitemapUrls(
+  baseUrl: string,
+  pages: string[] = ['/', '/services', '/gallery', '/about', '/contact', '/faq', '/privacy']
+): SitemapUrl[] {
+  const now = new Date().toISOString().split('T')[0];
+
+  return pages.map((page) => ({
+    loc: `${baseUrl}${page}`,
+    lastmod: now,
+    changefreq: page === '/' ? 'weekly' : 'monthly',
+    priority: page === '/' ? 1.0 : 0.8,
+  }));
+}
+
+/**
+ * Generate XML sitemap content.
+ */
+export function generateSitemapXml(urls: SitemapUrl[]): string {
+  const urlEntries = urls
+    .map(
+      (url) => `
+  <url>
+    <loc>${url.loc}</loc>
+    ${url.lastmod ? `<lastmod>${url.lastmod}</lastmod>` : ''}
+    ${url.changefreq ? `<changefreq>${url.changefreq}</changefreq>` : ''}
+    ${url.priority !== undefined ? `<priority>${url.priority}</priority>` : ''}
+  </url>`
+    )
+    .join('');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlEntries}
+</urlset>`;
+}
+
+// =============================================================================
+// ROBOTS.TXT GENERATION
+// =============================================================================
+
+/**
+ * Generate robots.txt content.
+ */
+export function generateRobotsTxt(baseUrl?: string): string {
+  return `User-agent: *
+Allow: /
+${baseUrl ? `\nSitemap: ${baseUrl}/sitemap.xml` : ''}`;
+}
+
+// =============================================================================
+// CANONICAL URL HELPERS
+// =============================================================================
+
+/**
+ * Generate canonical URL.
+ */
+export function getCanonicalUrl(baseUrl: string, path: string): string {
+  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  return `${baseUrl}${cleanPath}`;
+}
+
+// =============================================================================
+// META TAGS HELPERS
+// =============================================================================
+
+/**
+ * Generate common meta tags as an object.
+ */
+export function generateCommonMetaTags(business: BusinessInfo) {
+  const location = [business.city, business.state].filter(Boolean).join(', ');
+
+  return {
+    'geo.region': business.state ? `US-${business.state}` : undefined,
+    'geo.placename': business.city,
+    'og:locale': 'en_US',
+    'og:site_name': business.name,
+    'twitter:card': 'summary_large_image',
+    ...(location && { 'geo.position': location }),
+  };
+}