mallmaverick-store-scraper 0.1.0

package/src/discovery.js

@@ -0,0 +1,298 @@
+'use strict';
+
+const { URL } = require('url');
+const http = require('http');
+const https = require('https');
+const {
+  newPage, autoScroll, attachXhrInterceptor, sleep, XHR_CAPTURE_PATTERNS,
+} = require('./browser');
+
+const STORE_URL_KEYWORDS = [
+  '/store/', '/stores/', '/shop/', '/shops/', '/tenant/', '/tenants/',
+  '/directory/', '/listing/', '/listings/', '/retailer/', '/restaurant/',
+  '/brand/', '/location/', '/vendor/', '/merchant/',
+];
+
+const NON_STORE_PATTERNS = [
+  /\/(about|contact|faq|privacy|terms|careers|news|blog|events|deals|gift|parking|directions|hours|jobs)\b/i,
+  /\/(categories?|category)(\/|$)/i,
+  /\/(shopping-?map|site-?map|map)(\/|$)/i,
+  /\/(a-?z-?listing|a-?z-?list|all-?stores?)(\/|$)/i,
+  /\/(page|tag|filter|search)(\/|$)/i,
+  /\.(pdf|jpg|jpeg|png|gif|svg|css|js|xml|json)$/i,
+];
+
+const NON_STORE_SLUGS = new Set([
+  'shopping-map', 'map', 'directory', 'a-z-listing', 'listing', 'list',
+  'all', 'index', 'category', 'categories', 'about', 'contact', 'hours',
+  'parking', 'careers', 'leasing', 'news', 'events', 'promotions', 'deals',
+  'gift-cards', 'gift', 'jobs', 'blog', 'faq', 'help', 'login', 'register',
+  'cart', 'checkout', 'search', 'filter', 'page',
+]);
+
+/**
+ * Multi-strategy store URL discovery:
+ *   1. XHR/fetch interception (directory APIs returning store JSON)
+ *   2. Directory listing card scan (anchor+img pairs → logoMap)
+ *   3. DOM link scan
+ *   4. sitemap.xml + common variants
+ *   5. /api/stores etc. probing
+ *
+ * Returns { storeUrls, logoMap } where logoMap: Map<normalizedStoreUrl, logoUrl>.
+ */
+async function discoverStores(browser, directoryUrl, logger) {
+  const parsedBase = new URL(directoryUrl);
+  const baseUrl = `${parsedBase.protocol}//${parsedBase.hostname}`;
+
+  const page = await newPage(browser);
+  let result;
+  try {
+    const { interceptedJson, interceptedRaw } = await attachXhrInterceptor(page, { directoryMode: true });
+    await page.goto(directoryUrl, { waitUntil: 'domcontentloaded', timeout: 60000 });
+    await sleep(3000);
+    await autoScroll(page);
+    await sleep(1500);
+    await autoScroll(page, { distance: 300, delay: 100 });
+    await sleep(500);
+
+    const logoMap = await collectDirectoryLogoMap(page, baseUrl);
+    if (logger) logger.info(`   🖼️  Directory logos collected: ${logoMap.size}`);
+
+    const pageUrls = await extractLinksFromPage(page, baseUrl);
+    if (logger) logger.info(`   📄 DOM links: ${pageUrls.length}`);
+
+    const sitemapUrls = await fetchSitemapUrls(baseUrl, logger);
+    if (logger) logger.info(`   🗺️  Sitemap URLs: ${sitemapUrls.length}`);
+
+    const apiUrls = await probeApiEndpoints(baseUrl, logger);
+    if (logger) logger.info(`   📡 API URLs: ${apiUrls.length}`);
+
+    const all = new Set([...logoMap.keys(), ...pageUrls, ...sitemapUrls, ...apiUrls]);
+    for (const { url: src, text } of interceptedRaw) {
+      const extracted = extractUrlsFromJson(text, baseUrl);
+      if (extracted.length && logger) logger.info(`   📦 +${extracted.length} URLs from XHR (${src})`);
+      extracted.forEach(u => all.add(u));
+    }
+
+    const filtered = filterStoreUrls(Array.from(all), directoryUrl, logoMap);
+    // Final dedup: normalize trailing slash so /aw and /aw/ are one URL.
+    const seen = new Set();
+    const storeUrls = [];
+    for (const u of filtered) {
+      const norm = u.replace(/\/+$/, '').toLowerCase();
+      if (seen.has(norm)) continue;
+      seen.add(norm);
+      storeUrls.push(u);
+    }
+    if (logger) logger.info(`✅ Total store URLs: ${storeUrls.length}`);
+    result = { storeUrls, logoMap };
+  } finally {
+    await page.close();
+  }
+  return result;
+}
+
+async function collectDirectoryLogoMap(page, baseUrl) {
+  try {
+    const entries = await page.evaluate((baseUrl) => {
+      const out = [];
+      const anchors = Array.from(document.querySelectorAll('a[href]'));
+      for (const a of anchors) {
+        const href = a.getAttribute('href') || '';
+        const full = href.startsWith('http') ? href : (href.startsWith('/') ? baseUrl + href : null);
+        if (!full) continue;
+        const img = a.querySelector('img');
+        if (!img) continue;
+        const src = img.getAttribute('src') || img.getAttribute('data-src') || img.getAttribute('data-lazy-src') || '';
+        if (!src || src.length < 5) continue;
+        if (/placeholder|spacer|blank/i.test(src)) continue;
+        const fullSrc = src.startsWith('http') ? src : (src.startsWith('//') ? 'https:' + src : (src.startsWith('/') ? baseUrl + src : null));
+        if (fullSrc) out.push({ url: full, logo: fullSrc });
+      }
+      const cardSelectors = [
+        'li', 'article',
+        '[class*="store-item"]', '[class*="store-card"]', '[class*="tenant"]',
+        '[class*="listing-item"]', '[class*="directory-item"]', '[class*="retailer"]',
+        '[class*="brand-item"]', '[class*="shop-item"]',
+      ];
+      for (const sel of cardSelectors) {
+        document.querySelectorAll(sel).forEach(card => {
+          const link = card.querySelector('a[href]');
+          const img = card.querySelector('img');
+          if (!link || !img) return;
+          const href = link.getAttribute('href') || '';
+          const full = href.startsWith('http') ? href : (href.startsWith('/') ? baseUrl + href : null);
+          if (!full) return;
+          const src = img.getAttribute('src') || img.getAttribute('data-src') || img.getAttribute('data-lazy-src') || '';
+          if (!src || /placeholder|spacer/i.test(src)) return;
+          const fullSrc = src.startsWith('http') ? src : (src.startsWith('//') ? 'https:' + src : (src.startsWith('/') ? baseUrl + src : null));
+          if (fullSrc) out.push({ url: full, logo: fullSrc });
+        });
+      }
+      return out;
+    }, baseUrl);
+
+    const map = new Map();
+    for (const { url, logo } of entries) {
+      const normalized = url.replace(/\/$/, '').toLowerCase();
+      if (!map.has(normalized)) map.set(normalized, logo);
+    }
+    return map;
+  } catch (_) {
+    return new Map();
+  }
+}
+
+async function extractLinksFromPage(page, baseUrl) {
+  try {
+    return await page.evaluate((baseUrl) => {
+      return Array.from(document.querySelectorAll('a[href]'))
+        .map(a => {
+          const href = a.getAttribute('href');
+          if (!href) return null;
+          if (href.startsWith('http')) return href;
+          if (href.startsWith('/')) return baseUrl + href;
+          return null;
+        })
+        .filter(Boolean);
+    }, baseUrl);
+  } catch (_) { return []; }
+}
+
+async function fetchSitemapUrls(baseUrl, logger) {
+  const urls = new Set();
+  const locations = [
+    `${baseUrl}/sitemap.xml`,
+    `${baseUrl}/sitemap_index.xml`,
+    `${baseUrl}/sitemap-stores.xml`,
+    `${baseUrl}/sitemap-listings.xml`,
+    `${baseUrl}/sitemaps/sitemap.xml`,
+  ];
+  for (const loc of locations) {
+    const text = await fetchText(loc);
+    if (!text) continue;
+    const matches = text.match(/<loc>(.*?)<\/loc>/g) || [];
+    matches.forEach(m => {
+      const u = m.replace(/<\/?loc>/g, '').trim();
+      if (u) urls.add(u);
+    });
+    if (urls.size > 0) {
+      if (logger) logger.info(`   🗺️  Sitemap: ${loc}`);
+      break;
+    }
+  }
+  return Array.from(urls);
+}
+
+async function probeApiEndpoints(baseUrl, logger) {
+  const urls = [];
+  const endpoints = [
+    `${baseUrl}/api/stores`,
+    `${baseUrl}/api/v1/stores`,
+    `${baseUrl}/api/listings`,
+    `${baseUrl}/api/directory`,
+    `${baseUrl}/wp-json/wp/v2/stores`,
+    `${baseUrl}/stores.json`,
+    `${baseUrl}/directory.json`,
+    `${baseUrl}/listings.json`,
+  ];
+  for (const ep of endpoints) {
+    const text = await fetchText(ep, 5000);
+    if (!text) continue;
+    try {
+      const data = JSON.parse(text);
+      const extracted = extractUrlsFromJson(JSON.stringify(data), baseUrl);
+      if (extracted.length > 0) {
+        if (logger) logger.info(`   📡 API: ${ep} (${extracted.length})`);
+        urls.push(...extracted);
+        break;
+      }
+    } catch (_) {}
+  }
+  return urls;
+}
+
+function extractUrlsFromJson(jsonText, baseUrl) {
+  const urls = [];
+  const urlPattern = /(https?:\/\/[^\s"'<>]+)/g;
+  const relativePattern = /"(?:url|link|href|permalink|slug)"\s*:\s*"(\/[^"]+)"/gi;
+  let m;
+  while ((m = urlPattern.exec(jsonText)) !== null) urls.push(m[1]);
+  while ((m = relativePattern.exec(jsonText)) !== null) urls.push(baseUrl + m[1]);
+  return [...new Set(urls)];
+}
+
+function filterStoreUrls(urls, directoryUrl, logoMap = null) {
+  const parsedDir = new URL(directoryUrl);
+  const dirHostname = parsedDir.hostname;
+  const dirPath = parsedDir.pathname.replace(/\/+$/, '');
+  const dirSegs = dirPath.split('/').filter(Boolean);
+  const parentPath = dirSegs.length > 1 ? '/' + dirSegs.slice(0, -1).join('/') : null;
+
+  const logoMapUrls = new Set();
+  if (logoMap) for (const k of logoMap.keys()) logoMapUrls.add(k.replace(/\/+$/, '').toLowerCase());
+
+  const isChildOf = (p, base) => base && p.startsWith(base + '/') && p !== base;
+
+  return urls.filter(u => {
+    try {
+      const parsed = new URL(u);
+      if (parsed.hostname !== dirHostname) return false;
+      if (NON_STORE_PATTERNS.some(p => p.test(parsed.pathname))) return false;
+      if (u === directoryUrl) return false;
+      const path = parsed.pathname.replace(/\/+$/, '');
+      if (path.length < 4) return false;
+      if (path === dirPath) return false;
+      if (parentPath && path === parentPath) return false;
+      const slug = path.split('/').pop();
+      if (NON_STORE_SLUGS.has((slug || '').toLowerCase())) return false;
+
+      if (logoMapUrls.has(path.toLowerCase()) || logoMapUrls.has(u.replace(/\/+$/, '').toLowerCase())) return true;
+
+      const acceptUnder = (base) => {
+        const remainder = path.slice(base.length + 1);
+        const segs = remainder.split('/').filter(Boolean);
+        if (segs.length === 0 || segs.length > 2) return false;
+        if (!/[a-z]/i.test(segs[0])) return false;
+        if (NON_STORE_SLUGS.has(segs[0].toLowerCase())) return false;
+        return true;
+      };
+
+      if (isChildOf(path, dirPath) && acceptUnder(dirPath)) return true;
+      if (parentPath && isChildOf(path, parentPath) && acceptUnder(parentPath)) return true;
+      if (STORE_URL_KEYWORDS.some(kw => parsed.pathname.toLowerCase().includes(kw))) {
+        // Final slug sanity check
+        return acceptUnder(parsed.pathname.replace(/\/[^/]*$/, ''));
+      }
+      return false;
+    } catch { return false; }
+  });
+}
+
+function fetchText(url, timeout = 8000) {
+  return new Promise(resolve => {
+    const mod = url.startsWith('https') ? https : http;
+    const req = mod.get(url, {
+      headers: {
+        'User-Agent': 'Mozilla/5.0 (compatible; StoreScraperV5/1.0)',
+        'Accept': 'text/html,application/json,*/*',
+      },
+      timeout,
+    }, res => {
+      if (res.statusCode !== 200) { resolve(null); return; }
+      let data = '';
+      res.on('data', c => { data += c; });
+      res.on('end', () => resolve(data));
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+// Backwards-compat for first-slice callers
+async function discoverStoreLinks(browser, directoryUrl) {
+  const { storeUrls } = await discoverStores(browser, directoryUrl, null);
+  return storeUrls;
+}
+
+module.exports = { discoverStores, discoverStoreLinks, collectDirectoryLogoMap };

package/src/externalFollow.js

@@ -0,0 +1,89 @@
+'use strict';
+
+const { URL } = require('url');
+const { loadPage, newPage } = require('./browser');
+const {
+  parseJsonLdHours,
+  parseFreeFormHours,
+  canonicalize,
+  validateCanonical,
+} = require('./hoursParser');
+
+/**
+ * Pick the best external link to follow when the mall page has no hours.
+ *
+ * Heuristics:
+ *   - Prefer links labeled "hours" or "click here for business hours"
+ *   - Then prefer links to known store-locator paths
+ *   - Then the store's own website
+ *
+ * @param {Array<{href:string, text:string}>} links - links scraped from the store page
+ * @param {string} mallOrigin - the mall site origin to exclude
+ */
+function chooseExternalLink(links, mallOrigin) {
+  if (!links || links.length === 0) return null;
+
+  const external = links
+    .filter(l => {
+      try {
+        const u = new URL(l.href);
+        return u.origin !== mallOrigin && /^https?:/.test(u.protocol);
+      } catch { return false; }
+    });
+
+  if (external.length === 0) return null;
+
+  const score = (l) => {
+    let s = 0;
+    const t = (l.text || '').toLowerCase();
+    const h = (l.href || '').toLowerCase();
+    if (/business hours|store hours|hours of operation|click here for.*hours/.test(t)) s += 100;
+    if (/\bhours?\b/.test(t)) s += 30;
+    if (/store-locator|storelocation|store\/[^/]+\/?$|locations?\/|location\/.+/.test(h)) s += 50;
+    if (/locator/.test(h)) s += 25;
+    if (/instagram|facebook|twitter|tiktok|youtube|pinterest|google|maps\./.test(h)) s -= 100;
+    return s;
+  };
+
+  const ranked = external
+    .map(l => ({ ...l, _score: score(l) }))
+    .sort((a, b) => b._score - a._score);
+
+  return ranked[0];
+}
+
+/**
+ * Visit an external URL and try to extract hours via layers 1-2 (JSON-LD + free-form).
+ * Returns { canonical, source: 'external-jsonld' | 'external-freeform' } or null.
+ */
+async function extractHoursFromExternal(browser, url, { logger } = {}) {
+  if (!url) return null;
+  const page = await newPage(browser);
+  try {
+    const data = await loadPage(page, url, { waitUntil: 'networkidle2', timeout: 30000 });
+
+    const ld = parseJsonLdHours(data.jsonLd);
+    if (ld) {
+      const canonical = canonicalize(ld);
+      if (validateCanonical(canonical).ok) {
+        return { canonical, source: 'external-jsonld', sourceUrl: data.finalUrl };
+      }
+    }
+
+    const ff = parseFreeFormHours(data.text);
+    if (ff) {
+      const canonical = canonicalize(ff);
+      if (validateCanonical(canonical).ok) {
+        return { canonical, source: 'external-freeform', sourceUrl: data.finalUrl };
+      }
+    }
+    return null;
+  } catch (err) {
+    if (logger) logger.warn(`   ⚠ External fetch failed (${url}): ${err.message}`);
+    return null;
+  } finally {
+    try { await page.close(); } catch (_) {}
+  }
+}
+
+module.exports = { chooseExternalLink, extractHoursFromExternal };

package/src/hoursParser.js

@@ -0,0 +1,313 @@
+'use strict';
+
+/**
+ * Hours parser: accepts varied free-form and structured inputs, emits canonical
+ * "Monday = 10:00 AM - 9:00 PM;Tuesday = ..." string (v4-compatible).
+ *
+ * Public API:
+ *   parseFreeFormHours(text)   → canonical string | null
+ *   parseJsonLdHours(jsonLdArr)→ canonical string | null
+ *   parseSchemaOpeningHours(s) → canonical string | null  (legacy "Mo-Fr 10:00-21:00" form)
+ *   canonicalize(dayMap)       → canonical string
+ *   validateCanonical(s)       → { ok, missing[], reason }
+ *   normalizeDayName(s)        → "Monday" | null
+ *   normalizeTime(s)           → "10:00 AM" | "Closed" | null
+ */
+
+const DAYS = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+const DAY_INDEX = Object.fromEntries(DAYS.map((d, i) => [d, i]));
+
+// Generous day-name lookup including 2-3 letter abbrevs and Schema.org full forms.
+const DAY_LOOKUP = {
+  mon: 'Monday', monday: 'Monday', mo: 'Monday',
+  tue: 'Tuesday', tues: 'Tuesday', tuesday: 'Tuesday', tu: 'Tuesday',
+  wed: 'Wednesday', weds: 'Wednesday', wednesday: 'Wednesday', we: 'Wednesday',
+  thu: 'Thursday', thur: 'Thursday', thurs: 'Thursday', thursday: 'Thursday', th: 'Thursday',
+  fri: 'Friday', friday: 'Friday', fr: 'Friday',
+  sat: 'Saturday', saturday: 'Saturday', sa: 'Saturday',
+  sun: 'Sunday', sunday: 'Sunday', su: 'Sunday',
+};
+
+function normalizeDayName(raw) {
+  if (!raw) return null;
+  const key = String(raw).trim().toLowerCase().replace(/[\.\s]/g, '');
+  // Handle Schema.org URI form: http://schema.org/Monday
+  const tail = key.split('/').pop();
+  return DAY_LOOKUP[tail] || DAY_LOOKUP[key] || null;
+}
+
+/**
+ * Parse a single time token to "H:MM AM/PM" or "Closed".
+ * Accepts: "10", "10am", "10 am", "10:00am", "10:00 AM", "10:00", "21:00",
+ *          "noon", "midnight", "closed".
+ */
+function normalizeTime(raw) {
+  if (!raw) return null;
+  const s = String(raw).trim().toLowerCase();
+  if (!s) return null;
+
+  if (/^closed$/.test(s) || /^by appointment$/.test(s)) return 'Closed';
+  if (/^noon|^12:?00\s*(p\.?m\.?)?$/.test(s)) return '12:00 PM';
+  if (/^midnight|^12:?00\s*a\.?m\.?$/.test(s)) return '12:00 AM';
+  if (/^24\s*h(ou)?rs?$|^open\s*24/.test(s)) return 'Open 24 Hours';
+
+  // Match "H[:MM][ ]?am|pm" or 24h "HH:MM" or bare "HH"
+  const m = s.match(/^(\d{1,2})(?:[:\.](\d{2}))?\s*([ap])\.?\s*m?\.?$/i)
+         || s.match(/^(\d{1,2})[:\.](\d{2})$/)
+         || s.match(/^(\d{1,2})$/);
+  if (!m) return null;
+
+  let h = parseInt(m[1], 10);
+  const min = m[2] ? parseInt(m[2], 10) : 0;
+  const ampmRaw = m[3];
+
+  if (Number.isNaN(h) || Number.isNaN(min) || h < 0 || h > 24 || min < 0 || min > 59) return null;
+
+  let ampm;
+  if (ampmRaw) {
+    ampm = ampmRaw.toLowerCase() === 'a' ? 'AM' : 'PM';
+    if (h === 12 && ampm === 'AM') h = 0;        // 12am = 00
+    else if (h === 12 && ampm === 'PM') h = 12;  // 12pm = 12
+    else if (ampm === 'PM') h += 12;
+  } else {
+    // No am/pm → assume 24-hour input
+    if (h === 24) h = 0;
+    if (h > 23) return null;
+  }
+
+  const h12 = h === 0 ? 12 : h > 12 ? h - 12 : h;
+  const ampmOut = h < 12 ? 'AM' : 'PM';
+  return `${h12}:${String(min).padStart(2, '0')} ${ampmOut}`;
+}
+
+/**
+ * Expand a day range "mon-fri" to ["Monday","Tuesday",...,"Friday"].
+ * Returns null if either side is unparseable.
+ */
+function expandDayRange(startRaw, endRaw) {
+  const start = normalizeDayName(startRaw);
+  const end = normalizeDayName(endRaw);
+  if (!start || !end) return null;
+  const si = DAY_INDEX[start];
+  const ei = DAY_INDEX[end];
+  if (si === undefined || ei === undefined) return null;
+  const out = [];
+  let i = si;
+  // Allow wrap-around e.g. Fri-Sun
+  while (true) {
+    out.push(DAYS[i]);
+    if (i === ei) break;
+    i = (i + 1) % 7;
+    if (out.length > 7) return null; // safety
+  }
+  return out;
+}
+
+/**
+ * Parse one entry like "Mon-Fri 10am-9pm" or "Saturday 10:00 AM - 9:00 PM" or "Sunday: Closed".
+ * Returns { days: ["Monday",...], open: "10:00 AM", close: "9:00 PM" } or
+ *         { days: [...], closed: true } or null.
+ */
+function parseHoursEntry(text) {
+  if (!text) return null;
+  let s = String(text).trim();
+
+  // Normalize various dashes and "to" separator to ' - '
+  s = s
+    .replace(/[‐-―−]/g, '-')   // hyphen/dash variants
+    .replace(/\s+to\s+/gi, ' - ')
+    .replace(/\s+through\s+/gi, '-')          // for day ranges
+    .replace(/\s+/g, ' ');
+
+  // Strip trailing parenthetical/suffix junk like "(appointment only)",
+  // "* by appointment", "(walk-ins welcome)" — these confuse the regex
+  // anchor but don't affect the times themselves.
+  s = s
+    .replace(/\s*\([^)]*\)\s*$/g, '')
+    .replace(/\s*\*.*$/g, '')
+    .trim();
+
+  // Closed line: "Sunday: Closed", "Monday Closed", "Mon-Fri: Closed"
+  const closedMatch = s.match(/^([a-z]+)(?:\s*[-–—]\s*([a-z]+))?\s*[:\-]?\s*(closed|by appointment(?: only)?)$/i);
+  if (closedMatch) {
+    const days = closedMatch[2]
+      ? expandDayRange(closedMatch[1], closedMatch[2])
+      : [normalizeDayName(closedMatch[1])].filter(Boolean);
+    if (!days || days.length === 0) return null;
+    return { days, closed: true };
+  }
+
+  // Day(-Day)? : open - close
+  // Examples:
+  //   "Monday: 6:00 AM to 8:00 PM"  (already normalized "to" → "-")
+  //   "Mon-Fri 10am-9pm"
+  //   "Saturday 10:00 - 18:00"
+  const m = s.match(
+    /^([a-z]+)(?:\s*[-–—]\s*([a-z]+))?\s*[:\-]?\s*([0-9][0-9:\.\sapm]*?)\s*[-–—]\s*([0-9][0-9:\.\sapm]*)$/i
+  );
+  if (!m) return null;
+
+  const days = m[2]
+    ? expandDayRange(m[1], m[2])
+    : [normalizeDayName(m[1])].filter(Boolean);
+  if (!days || days.length === 0) return null;
+
+  const open = normalizeTime(m[3]);
+  const close = normalizeTime(m[4]);
+  if (!open || !close) return null;
+
+  return { days, open, close };
+}
+
+/**
+ * Parse a free-form hours block: multi-line or comma-separated.
+ * Returns a dayMap { Monday: "10:00 AM - 9:00 PM", ... } or null if nothing recognized.
+ */
+function parseFreeFormHours(text) {
+  if (!text) return null;
+  const raw = String(text);
+
+  // Normalize line breaks and common separators
+  // Split on newlines, semicolons, " | ", and commas-followed-by-day-name
+  const candidates = raw
+    .split(/\n+|;+|\s*\|\s*/)
+    .flatMap(chunk => {
+      // Further split on commas, but only when both halves look like an entry.
+      // Heuristic: if "," appears between two day names, split.
+      const parts = chunk.split(/,\s*(?=(?:mon|tue|wed|thu|fri|sat|sun|mo|tu|we|th|fr|sa|su)[a-z]*\b)/i);
+      return parts;
+    })
+    .map(p => p.trim())
+    .filter(Boolean);
+
+  const dayMap = {};
+  let parsedAny = false;
+  for (const c of candidates) {
+    const entry = parseHoursEntry(c);
+    if (!entry) continue;
+    parsedAny = true;
+    for (const d of entry.days) {
+      dayMap[d] = entry.closed ? 'Closed' : `${entry.open} - ${entry.close}`;
+    }
+  }
+  return parsedAny ? dayMap : null;
+}
+
+/**
+ * Parse Schema.org-style "openingHours" property string.
+ * Format: "Mo-Fr 10:00-21:00, Sa 09:00-19:00, Su 11:00-18:00"
+ * Returns dayMap or null.
+ */
+function parseSchemaOpeningHours(value) {
+  if (!value) return null;
+  if (Array.isArray(value)) {
+    const merged = {};
+    for (const v of value) {
+      const m = parseSchemaOpeningHours(v);
+      if (m) Object.assign(merged, m);
+    }
+    return Object.keys(merged).length ? merged : null;
+  }
+  return parseFreeFormHours(String(value));
+}
+
+/**
+ * Walk a parsed JSON-LD blob and return canonical hours if found.
+ * Supports:
+ *   - LocalBusiness.openingHoursSpecification (array of {dayOfWeek, opens, closes})
+ *   - LocalBusiness.openingHours (string or array of strings, Schema.org compact form)
+ *   - Nested @graph
+ */
+function parseJsonLdHours(jsonLdArr) {
+  if (!jsonLdArr) return null;
+  const arr = Array.isArray(jsonLdArr) ? jsonLdArr : [jsonLdArr];
+  const dayMap = {};
+
+  const visit = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) { node.forEach(visit); return; }
+
+    if (node['@graph']) visit(node['@graph']);
+
+    if (node.openingHoursSpecification) {
+      const specs = Array.isArray(node.openingHoursSpecification)
+        ? node.openingHoursSpecification
+        : [node.openingHoursSpecification];
+      for (const spec of specs) {
+        if (!spec) continue;
+        const days = spec.dayOfWeek;
+        const dayList = Array.isArray(days) ? days : days ? [days] : [];
+        for (const d of dayList) {
+          const dayName = normalizeDayName(d);
+          if (!dayName) continue;
+          const open = normalizeTime(spec.opens);
+          const close = normalizeTime(spec.closes);
+          if (open && close) dayMap[dayName] = `${open} - ${close}`;
+          else if (spec.closes === undefined && spec.opens === undefined) dayMap[dayName] = 'Closed';
+        }
+      }
+    }
+
+    if (node.openingHours) {
+      const compact = parseSchemaOpeningHours(node.openingHours);
+      if (compact) Object.assign(dayMap, compact);
+    }
+
+    // Recurse into common containers
+    for (const key of Object.keys(node)) {
+      if (['openingHoursSpecification', 'openingHours'].includes(key)) continue;
+      const v = node[key];
+      if (v && typeof v === 'object') visit(v);
+    }
+  };
+
+  for (const node of arr) visit(node);
+  return Object.keys(dayMap).length ? dayMap : null;
+}
+
+/**
+ * Convert a dayMap to canonical "Monday = 10:00 AM - 9:00 PM;..." string.
+ * Fills missing days with empty entries (not present at all → caller decides).
+ */
+function canonicalize(dayMap, { fillClosed = false } = {}) {
+  if (!dayMap) return '';
+  const parts = [];
+  for (const day of DAYS) {
+    if (dayMap[day]) {
+      parts.push(`${day} = ${dayMap[day]}`);
+    } else if (fillClosed) {
+      parts.push(`${day} = Closed`);
+    }
+  }
+  return parts.join(';');
+}
+
+/**
+ * Check the canonical string. Returns { ok, missing, reason }.
+ * Strict mode (default): all 7 days must be represented.
+ */
+function validateCanonical(canonical, { strict = false } = {}) {
+  if (!canonical) return { ok: false, missing: DAYS, reason: 'empty' };
+  const present = new Set();
+  for (const seg of canonical.split(';')) {
+    const m = seg.match(/^(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)\s*=/);
+    if (m) present.add(m[1]);
+  }
+  const missing = DAYS.filter(d => !present.has(d));
+  if (strict && missing.length > 0) return { ok: false, missing, reason: 'missing-days' };
+  if (present.size === 0) return { ok: false, missing, reason: 'no-days-parsed' };
+  return { ok: true, missing, reason: null };
+}
+
+module.exports = {
+  DAYS,
+  normalizeDayName,
+  normalizeTime,
+  expandDayRange,
+  parseHoursEntry,
+  parseFreeFormHours,
+  parseSchemaOpeningHours,
+  parseJsonLdHours,
+  canonicalize,
+  validateCanonical,
+};