@aws505/sheetsite 1.0.0

package/src/data/index.ts

@@ -0,0 +1,535 @@
+/**
+ * SheetSite Data Module
+ *
+ * Provides all data-related functionality:
+ * - Google Sheets integration (public CSV and private API modes)
+ * - Type definitions for site data
+ * - CSV parsing utilities
+ * - Google Drive URL utilities
+ * - Default data and fallbacks
+ */
+
+// Types
+export * from './types';
+
+// Google Sheets integration
+export {
+  fetchSheetData,
+  fetchPublicSheetData,
+  fetchPrivateSheetData,
+  fetchInlineData,
+  mergeSiteData,
+  type FetchOptions,
+} from './sheets';
+
+// CSV parsing
+export {
+  parseCSV,
+  normalizeHeader,
+  mapRows,
+  parseBoolean,
+  parseNumber,
+  parseInteger,
+  parseSortOrder,
+  type ParsedRow,
+} from './csv-parser';
+
+// Google Drive utilities
+export {
+  normalizeGoogleDriveUrl,
+  getGoogleDriveThumbnail,
+  isGoogleDriveUrl,
+  extractGoogleDriveFileId,
+  processImageUrls,
+  processImageUrlsInArray,
+} from './google-drive';
+
+// Defaults
+export {
+  DEFAULT_SITE_DATA,
+  createDefaultSiteData,
+  industryDefaults,
+} from './defaults';
+
+// =============================================================================
+// CONVENIENCE FUNCTIONS
+// =============================================================================
+
+import type { SheetConfig, SiteData, PartialSiteData } from './types';
+import { fetchSheetData, mergeSiteData } from './sheets';
+import { DEFAULT_SITE_DATA, createDefaultSiteData, industryDefaults } from './defaults';
+
+/**
+ * In-memory cache for site data.
+ */
+let cachedSiteData: SiteData | null = null;
+let cacheTimestamp: number = 0;
+const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Clear the in-memory cache.
+ * Call this when you need to force a refresh.
+ */
+export function clearSiteDataCache(): void {
+  cachedSiteData = null;
+  cacheTimestamp = 0;
+}
+
+/**
+ * Get site data with caching.
+ * This is the primary function for fetching site data in your application.
+ *
+ * @param config - Sheet configuration (public CSV or private API)
+ * @param defaults - Default data to merge with (optional)
+ * @returns Complete site data
+ */
+export async function getSiteData(
+  config: SheetConfig | undefined,
+  defaults: SiteData = DEFAULT_SITE_DATA
+): Promise<SiteData> {
+  // Check cache
+  const now = Date.now();
+  if (cachedSiteData && now - cacheTimestamp < CACHE_DURATION) {
+    return cachedSiteData;
+  }
+
+  // If no config, return defaults
+  if (!config) {
+    return defaults;
+  }
+
+  try {
+    const partialData = await fetchSheetData(config);
+    const siteData = mergeSiteData(partialData, defaults);
+
+    // Update cache
+    cachedSiteData = siteData;
+    cacheTimestamp = now;
+
+    return siteData;
+  } catch (error) {
+    console.error('Error fetching site data:', error);
+    return defaults;
+  }
+}
+
+/**
+ * Get site data with a custom default based on business type.
+ *
+ * @param config - Sheet configuration
+ * @param businessName - Name of the business
+ * @returns Complete site data
+ */
+export async function getSiteDataWithName(
+  config: SheetConfig | undefined,
+  businessName: string
+): Promise<SiteData> {
+  const defaults = createDefaultSiteData(businessName);
+  return getSiteData(config, defaults);
+}
+
+/**
+ * Create a sheet configuration from environment variables.
+ * This is a convenience function for common setup patterns.
+ *
+ * Expected environment variables for public CSV mode:
+ * - SHEET_MODE=public_csv
+ * - SHEET_CSV_URL_BUSINESS
+ * - SHEET_CSV_URL_HOURS (optional)
+ * - SHEET_CSV_URL_SERVICES (optional)
+ * - SHEET_CSV_URL_GALLERY (optional)
+ * - SHEET_CSV_URL_TESTIMONIALS (optional)
+ * - SHEET_CSV_URL_FAQ (optional)
+ * - SHEET_CSV_URL_TEAM (optional)
+ * - SHEET_CSV_URL_MENU (optional)
+ * - SHEET_CSV_URL_PRODUCTS (optional)
+ * - SHEET_CSV_URL_ANNOUNCEMENTS (optional)
+ *
+ * Expected environment variables for private API mode:
+ * - SHEET_MODE=private_api
+ * - SHEET_ID
+ * - GOOGLE_SERVICE_ACCOUNT_EMAIL
+ * - GOOGLE_PRIVATE_KEY
+ *
+ * For inline mode, use createInlineConfig() instead.
+ */
+export function createSheetConfigFromEnv(): SheetConfig | undefined {
+  const mode = process.env.SHEET_MODE;
+
+  if (mode === 'public_csv') {
+    const businessUrl = process.env.SHEET_CSV_URL_BUSINESS;
+    if (!businessUrl) {
+      console.warn('SHEET_CSV_URL_BUSINESS not set, using defaults');
+      return undefined;
+    }
+
+    return {
+      mode: 'public_csv',
+      tabs: {
+        business: businessUrl,
+        hours: process.env.SHEET_CSV_URL_HOURS,
+        services: process.env.SHEET_CSV_URL_SERVICES,
+        gallery: process.env.SHEET_CSV_URL_GALLERY,
+        testimonials: process.env.SHEET_CSV_URL_TESTIMONIALS,
+        faq: process.env.SHEET_CSV_URL_FAQ,
+        team: process.env.SHEET_CSV_URL_TEAM,
+        menu: process.env.SHEET_CSV_URL_MENU,
+        products: process.env.SHEET_CSV_URL_PRODUCTS,
+        announcements: process.env.SHEET_CSV_URL_ANNOUNCEMENTS,
+      },
+    };
+  }
+
+  if (mode === 'private_api') {
+    const sheetId = process.env.SHEET_ID;
+    const clientEmail = process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL;
+    const privateKey = process.env.GOOGLE_PRIVATE_KEY;
+
+    if (!sheetId || !clientEmail || !privateKey) {
+      console.warn('Missing required environment variables for private API mode');
+      return undefined;
+    }
+
+    return {
+      mode: 'private_api',
+      sheetId,
+      clientEmail,
+      privateKey,
+    };
+  }
+
+  // No valid mode configured
+  return undefined;
+}
+
+// =============================================================================
+// INLINE DATA UTILITIES
+// =============================================================================
+
+import type { InlineDataConfig, BusinessInfo, HoursEntry, DayOfWeek } from './types';
+
+/**
+ * Create an inline configuration for direct data injection.
+ * This bypasses Google Sheets entirely and uses provided data directly.
+ *
+ * Ideal for:
+ * - Automated site generation from CSV/JSON leads
+ * - Rapid prototyping and demos
+ * - Testing without network dependencies
+ *
+ * @example
+ * ```ts
+ * const config = createInlineConfig({
+ *   business: {
+ *     name: "John's Tailor Shop",
+ *     tagline: "Expert Alterations",
+ *     phone: "555-123-4567",
+ *     city: "San Diego",
+ *     state: "CA"
+ *   },
+ *   hours: [
+ *     { day: 'monday', open: '9:00 AM', close: '5:00 PM', closed: false }
+ *   ]
+ * });
+ *
+ * const siteData = await getSiteData(config, industryDefaults.tailor());
+ * ```
+ */
+export function createInlineConfig(data: PartialSiteData): InlineDataConfig {
+  return {
+    mode: 'inline',
+    data,
+  };
+}
+
+/**
+ * Input format for lead data from scraped sources (e.g., Google Maps).
+ * Designed to match common CSV export formats.
+ */
+export interface LeadData {
+  // Required
+  name: string;
+
+  // Contact (at least phone recommended)
+  phone?: string;
+  phoneAlt?: string;
+  email?: string;
+
+  // Address - can be single field or split
+  address?: string; // Full address string (will attempt to parse)
+  addressLine1?: string;
+  addressLine2?: string;
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+
+  // Business info
+  tagline?: string;
+  description?: string;
+  category?: string; // e.g., "Tailor", "Restaurant" - used for preset selection
+  googleMapsUrl?: string;
+
+  // Hours - can be structured or simple
+  hours?: HoursEntry[] | SimpleHours;
+
+  // Images
+  heroImageUrl?: string;
+  logoUrl?: string;
+  galleryUrls?: string[];
+
+  // Social proof
+  rating?: number; // e.g., 4.5
+  reviewCount?: number;
+  testimonialQuote?: string;
+  testimonialAuthor?: string;
+
+  // Social links
+  yelp?: string;
+  instagram?: string;
+  facebook?: string;
+  twitter?: string;
+  website?: string;
+
+  // Additional
+  yearEstablished?: number;
+  priceRange?: '$' | '$$' | '$$$' | '$$$$';
+  timezone?: string;
+}
+
+/**
+ * Simple hours format for common patterns.
+ */
+export interface SimpleHours {
+  weekdays?: { open: string; close: string };
+  saturday?: { open: string; close: string } | 'closed';
+  sunday?: { open: string; close: string } | 'closed';
+}
+
+/**
+ * Convert simple hours format to HoursEntry array.
+ */
+function parseSimpleHours(hours: SimpleHours): HoursEntry[] {
+  const entries: HoursEntry[] = [];
+  const weekdays: DayOfWeek[] = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'];
+
+  if (hours.weekdays) {
+    for (const day of weekdays) {
+      entries.push({
+        day,
+        open: hours.weekdays.open,
+        close: hours.weekdays.close,
+        closed: false,
+      });
+    }
+  }
+
+  if (hours.saturday) {
+    entries.push(
+      hours.saturday === 'closed'
+        ? { day: 'saturday', closed: true }
+        : { day: 'saturday', open: hours.saturday.open, close: hours.saturday.close, closed: false }
+    );
+  }
+
+  if (hours.sunday) {
+    entries.push(
+      hours.sunday === 'closed'
+        ? { day: 'sunday', closed: true }
+        : { day: 'sunday', open: hours.sunday.open, close: hours.sunday.close, closed: false }
+    );
+  }
+
+  return entries;
+}
+
+/**
+ * Parse a full address string into components.
+ * Handles common US address formats.
+ */
+function parseAddressString(
+  address: string
+): Pick<BusinessInfo, 'addressLine1' | 'city' | 'state' | 'zip'> {
+  // Try to match: "123 Main St, City, ST 12345" or similar
+  const parts = address.split(',').map((s) => s.trim());
+
+  if (parts.length >= 3) {
+    // Likely: Street, City, State ZIP
+    const lastPart = parts[parts.length - 1];
+    const stateZipMatch = lastPart.match(/^([A-Z]{2})\s*(\d{5}(?:-\d{4})?)$/);
+
+    if (stateZipMatch) {
+      return {
+        addressLine1: parts.slice(0, -2).join(', '),
+        city: parts[parts.length - 2],
+        state: stateZipMatch[1],
+        zip: stateZipMatch[2],
+      };
+    }
+  }
+
+  if (parts.length === 2) {
+    // Likely: Street, City ST ZIP
+    const cityStateZipMatch = parts[1].match(/^(.+?)\s+([A-Z]{2})\s*(\d{5}(?:-\d{4})?)$/);
+    if (cityStateZipMatch) {
+      return {
+        addressLine1: parts[0],
+        city: cityStateZipMatch[1],
+        state: cityStateZipMatch[2],
+        zip: cityStateZipMatch[3],
+      };
+    }
+  }
+
+  // Fallback: just use as address line 1
+  return { addressLine1: address };
+}
+
+/**
+ * Create PartialSiteData from lead data (e.g., scraped from Google Maps).
+ *
+ * This is the primary function for converting CSV/JSON lead data into
+ * a format suitable for SheetSite. It handles common data formats and
+ * performs sensible normalization.
+ *
+ * @example
+ * ```ts
+ * const lead = {
+ *   name: "John's Tailor Shop",
+ *   phone: "555-123-4567",
+ *   address: "123 Main St, San Diego, CA 92101",
+ *   category: "Tailor",
+ *   rating: 4.8,
+ *   reviewCount: 67,
+ *   hours: {
+ *     weekdays: { open: '9:00 AM', close: '5:00 PM' },
+ *     saturday: { open: '10:00 AM', close: '3:00 PM' },
+ *     sunday: 'closed'
+ *   }
+ * };
+ *
+ * const siteData = createSiteDataFromLead(lead);
+ * const config = createInlineConfig(siteData);
+ * ```
+ */
+export function createSiteDataFromLead(lead: LeadData): PartialSiteData {
+  // Parse address if provided as single string
+  const addressParts =
+    lead.address && !lead.addressLine1 ? parseAddressString(lead.address) : {};
+
+  // Build business info
+  const business: Partial<BusinessInfo> = {
+    name: lead.name,
+    tagline: lead.tagline,
+    description: lead.description,
+    phone: lead.phone,
+    phoneAlt: lead.phoneAlt,
+    email: lead.email,
+    addressLine1: lead.addressLine1 || addressParts.addressLine1,
+    addressLine2: lead.addressLine2,
+    city: lead.city || addressParts.city,
+    state: lead.state || addressParts.state,
+    zip: lead.zip || addressParts.zip,
+    country: lead.country || 'USA',
+    googleMapsUrl: lead.googleMapsUrl,
+    timezone: lead.timezone || 'America/Los_Angeles',
+    heroImageUrl: lead.heroImageUrl,
+    logoUrl: lead.logoUrl,
+    socialYelp: lead.yelp,
+    socialInstagram: lead.instagram,
+    socialFacebook: lead.facebook,
+    socialTwitter: lead.twitter,
+    yearEstablished: lead.yearEstablished,
+    priceRange: lead.priceRange,
+  };
+
+  // Parse hours
+  let hours: HoursEntry[] | undefined;
+  if (lead.hours) {
+    if (Array.isArray(lead.hours)) {
+      hours = lead.hours;
+    } else {
+      hours = parseSimpleHours(lead.hours);
+    }
+  }
+
+  // Build gallery from URLs
+  const gallery = lead.galleryUrls?.map((url, i) => ({
+    id: `gallery-${i}`,
+    imageUrl: url,
+    alt: `${lead.name} - Image ${i + 1}`,
+    featured: false,
+    sortOrder: i,
+  }));
+
+  // Build testimonial from rating/review data
+  const testimonials =
+    lead.testimonialQuote && lead.testimonialAuthor
+      ? [
+          {
+            id: 'testimonial-1',
+            quote: lead.testimonialQuote,
+            name: lead.testimonialAuthor,
+            rating: lead.rating,
+            source: 'Google',
+            featured: false,
+            sortOrder: 0,
+          },
+        ]
+      : lead.rating
+        ? [
+            {
+              id: 'testimonial-1',
+              quote: `Rated ${lead.rating}/5 on Google${lead.reviewCount ? ` based on ${lead.reviewCount} reviews` : ''}`,
+              name: 'Google Reviews',
+              rating: Math.round(lead.rating),
+              source: 'Google',
+              featured: false,
+              sortOrder: 0,
+            },
+          ]
+        : undefined;
+
+  return {
+    business,
+    hours,
+    gallery,
+    testimonials,
+  };
+}
+
+/**
+ * Create a complete site configuration from lead data in one step.
+ *
+ * Combines createSiteDataFromLead with defaults for the specified business type.
+ *
+ * @param lead - Lead data from scraping
+ * @param businessType - Business type for defaults (e.g., 'tailor', 'restaurant')
+ * @returns Complete site data ready for rendering
+ *
+ * @example
+ * ```ts
+ * const lead = { name: "Maria's Alterations", phone: "555-1234", category: "tailor" };
+ * const siteData = await createSiteFromLead(lead, 'tailor');
+ * ```
+ */
+export async function createSiteFromLead(
+  lead: LeadData,
+  businessType?: string
+): Promise<SiteData> {
+  const partialData = createSiteDataFromLead(lead);
+  const config = createInlineConfig(partialData);
+
+  // Get industry-specific defaults if available
+  const type = businessType || lead.category?.toLowerCase().replace(/\s+/g, '-');
+  let defaults = DEFAULT_SITE_DATA;
+
+  if (type) {
+    const typeKey = type as keyof typeof industryDefaults;
+    if (typeKey in industryDefaults) {
+      defaults = industryDefaults[typeKey]();
+    }
+  }
+
+  return getSiteData(config, defaults);
+}