@sarimarcus/content-sites-core 0.13.0 → 0.15.0

package/dist/schema/hours.js

@@ -0,0 +1,212 @@
+export const DAY_KEYS = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'];
+const WEEKDAY_KEYS = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'];
+const WEEKEND_KEYS = ['saturday', 'sunday'];
+const DAY_LABEL = {
+    monday: 'Monday', tuesday: 'Tuesday', wednesday: 'Wednesday', thursday: 'Thursday',
+    friday: 'Friday', saturday: 'Saturday', sunday: 'Sunday',
+};
+const SHORT_DAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+const SHORT_TO_KEY = {
+    mon: 'monday', tue: 'tuesday', wed: 'wednesday', thu: 'thursday', fri: 'friday', sat: 'saturday', sun: 'sunday',
+};
+/** The value an `openingHours` bucket uses for a day open around the clock. */
+export const HOURS_ALWAYS_OPEN = '24h';
+/**
+ * Splits a (possibly split-shift) bucket value such as `"13:00-16:00, 20:00-23:30"` into one pair per shift.
+ * A shift whose halves are not both clock times is dropped (SLA-2303); `24h` spans the whole day.
+ */
+export function parseHoursShifts(value) {
+    if (value.trim() === HOURS_ALWAYS_OPEN)
+        return [{ opens: '00:00', closes: '23:59' }];
+    return value
+        .split(',')
+        .map((shift) => shift.trim())
+        .filter(Boolean)
+        .map((shift) => {
+        const [opens, closes] = shift.split('-');
+        return { opens: opens?.trim(), closes: closes?.trim() };
+    })
+        .filter((shift) => Boolean(shift.opens && shift.closes)
+        && /^\d{1,2}:\d{2}$/.test(shift.opens)
+        && /^\d{1,2}:\d{2}$/.test(shift.closes));
+}
+/** Days a free-text `closed` field names ("Tuesdays", "Monday and Sunday"), in Monday-first order. */
+export function closedFieldDays(closed) {
+    return new Set(typeof closed === 'string'
+        ? DAY_KEYS.filter((d) => new RegExp(`\\b${d}s?\\b`, 'i').test(closed))
+        : []);
+}
+/**
+ * The day resolution behind `generateOpeningHours`, in emission order: weekdays, weekends, each per-day key,
+ * then `alwaysOpen`. A per-day key wins over a grouped bucket and every `closed` day is subtracted.
+ */
+export function resolveOpeningHours(openingHours) {
+    const closed = closedFieldDays(openingHours.closed);
+    const perDayKeys = DAY_KEYS.filter((d) => openingHours[d]);
+    const overridden = new Set(perDayKeys);
+    const groupDays = (keys) => keys.filter((d) => !closed.has(d) && !overridden.has(d));
+    const buckets = [];
+    if (openingHours.weekdays)
+        buckets.push({ kind: 'grouped', value: openingHours.weekdays, days: groupDays(WEEKDAY_KEYS) });
+    if (openingHours.weekends)
+        buckets.push({ kind: 'grouped', value: openingHours.weekends, days: groupDays(WEEKEND_KEYS) });
+    for (const day of perDayKeys) {
+        if (!closed.has(day))
+            buckets.push({ kind: 'day', value: openingHours[day], days: [day] });
+    }
+    if (openingHours.alwaysOpen)
+        buckets.push({ kind: 'alwaysOpen', value: openingHours.alwaysOpen, days: groupDays(DAY_KEYS) });
+    return buckets;
+}
+/**
+ * Days an `openingHours` object declares open, whether or not each bucket's value parses. The opening-hours gate
+ * asks this, so a malformed bucket still counts as an open claim; the gate reports the malformed value separately.
+ */
+export function assertedOpenDays(openingHours) {
+    const open = new Set();
+    for (const bucket of resolveOpeningHours(openingHours))
+        bucket.days.forEach((d) => open.add(d));
+    return open;
+}
+/** `openingHours` object → schema.org OpeningHoursSpecification list, or undefined when nothing is emitted. */
+export function generateOpeningHours(openingHours) {
+    if (!openingHours)
+        return undefined;
+    const specs = [];
+    for (const bucket of resolveOpeningHours(openingHours)) {
+        const labels = bucket.days.map((d) => DAY_LABEL[d]);
+        if (bucket.kind === 'day') {
+            for (const { opens, closes } of parseHoursShifts(bucket.value)) {
+                specs.push({ '@type': 'OpeningHoursSpecification', dayOfWeek: labels[0], opens, closes });
+            }
+            continue;
+        }
+        if (labels.length === 0)
+            continue;
+        const dayOfWeek = labels.length === 1 ? labels[0] : labels;
+        if (bucket.kind === 'alwaysOpen') {
+            specs.push({ '@type': 'OpeningHoursSpecification', dayOfWeek, opens: '00:00', closes: '23:59' });
+            continue;
+        }
+        for (const { opens, closes } of parseHoursShifts(bucket.value)) {
+            specs.push({ '@type': 'OpeningHoursSpecification', dayOfWeek, opens, closes });
+        }
+    }
+    return specs.length > 0 ? specs : undefined;
+}
+function convertTime(t) {
+    const clean = t.trim();
+    const m12 = clean.match(/^(\d{1,2})(?::(\d{2}))?(am|pm)$/i);
+    if (m12) {
+        let h = parseInt(m12[1]);
+        const min = m12[2] ? parseInt(m12[2]) : 0;
+        const period = m12[3].toLowerCase();
+        if (h < 1 || h > 12)
+            return undefined;
+        if (period === 'pm' && h !== 12)
+            h += 12;
+        if (period === 'am' && h === 12)
+            h = 0;
+        return `${String(h).padStart(2, '0')}:${String(min).padStart(2, '0')}`;
+    }
+    const m24 = clean.match(/^(\d{1,2}):(\d{2})$/);
+    if (m24)
+        return `${String(parseInt(m24[1])).padStart(2, '0')}:${m24[2]}`;
+    return undefined;
+}
+// A side missing am/pm inherits the other side's period, flipped if that inverts the range (SLA-2829).
+function convertTimePair(openRaw, closeRaw) {
+    const suffixOf = (t) => t.trim().match(/(am|pm)$/i)?.[1]?.toLowerCase();
+    const toMinutes = (hhmm) => {
+        const [h, m] = hhmm.split(':').map(Number);
+        return h * 60 + m;
+    };
+    const openSuffix = suffixOf(openRaw);
+    const closeSuffix = suffixOf(closeRaw);
+    if ((openSuffix && closeSuffix) || (!openSuffix && !closeSuffix)) {
+        return { opens: convertTime(openRaw), closes: convertTime(closeRaw) };
+    }
+    const missingIsOpen = !openSuffix;
+    const missingRaw = missingIsOpen ? openRaw : closeRaw;
+    if (parseInt(missingRaw.trim(), 10) > 12) {
+        const opens = convertTime(openRaw);
+        const closes = convertTime(closeRaw);
+        if (opens !== undefined && closes !== undefined && toMinutes(opens) < toMinutes(closes)) {
+            return { opens, closes };
+        }
+        return {};
+    }
+    const known = (missingIsOpen ? closeSuffix : openSuffix);
+    for (const guess of [known, known === 'am' ? 'pm' : 'am']) {
+        const openStr = missingIsOpen ? `${openRaw.trim()}${guess}` : openRaw;
+        const closeStr = missingIsOpen ? closeRaw : `${closeRaw.trim()}${guess}`;
+        const opens = convertTime(openStr);
+        const closes = convertTime(closeStr);
+        if (opens !== undefined && closes !== undefined && toMinutes(opens) < toMinutes(closes)) {
+            return { opens, closes };
+        }
+    }
+    return {};
+}
+// A colon or an am/pm suffix on at least one side, so a date or age range ("Dec 24-26") does not trigger.
+const LOOKS_LIKE_TIME_RANGE = /(?:\d{1,2}:\d{2}|\d{1,2}\s*(?:am|pm))\s*-\s*\d{1,2}(?::\d{2})?\s*(?:am|pm)?|\d{1,2}(?::\d{2})?\s*(?:am|pm)?\s*-\s*(?:\d{1,2}:\d{2}|\d{1,2}\s*(?:am|pm))/i;
+/**
+ * Free-text hours line ("Tue–Sat: 9am–3pm, Sun: 9am–3pm") → OpeningHoursSpecification list. Any time range it
+ * cannot fully represent drops the whole string: partial hours read as closed to Google (SLA-2829).
+ */
+export function parseHoursString(hours) {
+    if (!hours)
+        return undefined;
+    const specs = [];
+    const parts = hours.replace(/–/g, '-').split(/[,.;]/).map((p) => p.trim()).filter(Boolean);
+    for (const part of parts) {
+        const match = part.match(/^([A-Za-z]+-?[A-Za-z]*)[\s:]+(\d[\d:]*(?:am|pm)?)\s*-\s*(\d[\d:]*(?:am|pm)?)/i);
+        if (!match) {
+            if (LOOKS_LIKE_TIME_RANGE.test(part))
+                return undefined;
+            continue;
+        }
+        if (LOOKS_LIKE_TIME_RANGE.test(part.slice(match[0].length)))
+            return undefined;
+        const { opens, closes } = convertTimePair(match[2], match[3]);
+        if (!opens || !closes)
+            return undefined;
+        const dayRangeMatch = match[1].match(/^([A-Za-z]+)-([A-Za-z]+)$/);
+        let dayNames;
+        if (dayRangeMatch) {
+            const startIdx = SHORT_DAYS.indexOf(dayRangeMatch[1].toLowerCase());
+            const endIdx = SHORT_DAYS.indexOf(dayRangeMatch[2].toLowerCase());
+            if (startIdx < 0 || endIdx < 0)
+                return undefined;
+            dayNames = (startIdx <= endIdx
+                ? SHORT_DAYS.slice(startIdx, endIdx + 1)
+                : [...SHORT_DAYS.slice(startIdx), ...SHORT_DAYS.slice(0, endIdx + 1)]).map((d) => DAY_LABEL[SHORT_TO_KEY[d]]);
+            if (dayNames.length === 0)
+                return undefined;
+        }
+        else {
+            const key = SHORT_TO_KEY[match[1].toLowerCase()];
+            if (!key)
+                return undefined;
+            dayNames = [DAY_LABEL[key]];
+        }
+        specs.push({
+            '@type': 'OpeningHoursSpecification',
+            dayOfWeek: dayNames.length === 1 ? dayNames[0] : dayNames,
+            opens,
+            closes,
+        });
+    }
+    return specs.length > 0 ? specs : undefined;
+}
+/** Days the JSON-LD built from a free-text hours line asserts open (the union of its specs' `dayOfWeek`). */
+export function hoursStringOpenDays(hours) {
+    const open = new Set();
+    if (typeof hours !== 'string')
+        return open;
+    for (const spec of parseHoursString(hours) ?? []) {
+        for (const label of [].concat(spec.dayOfWeek))
+            open.add(label.toLowerCase());
+    }
+    return open;
+}

package/dist/schema/index.d.ts

@@ -0,0 +1,14 @@
+export type { JsonLdNode, SchemaEntry, OpeningHoursSpecification, IdRef, SchemaAuthorProfile, ResolvedAuthor, RouteMap, SchemaContextInput, SchemaContext, SchemaBuilder, SchemaBuilders, } from './types.ts';
+export { createSchemaContext, normalizeHomepageUrl, normalizeStructuredDataUrls, formatSchemaDate, createPersonSchema, withAuthorPersonSchema, } from './context.ts';
+export { parsePriceFromString, cleanStreetAddress, normalizePriceRange, normalizeHotelPriceRange, postalCodeOf, dataAddressPolicy, postalAddress, geoCoordinates, aggregateRating, } from './values.ts';
+export type { AddressPolicy, PostalAddressParts } from './values.ts';
+export { DAY_KEYS, HOURS_ALWAYS_OPEN, parseHoursShifts, closedFieldDays, resolveOpeningHours, assertedOpenDays, generateOpeningHours, parseHoursString, hoursStringOpenDays, } from './hours.ts';
+export type { DayKey, OpeningHoursInput, OpeningHoursBucket } from './hours.ts';
+export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } from './graph.ts';
+export type { BreadcrumbInput, PageInput, AssembleOptions } from './graph.ts';
+export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from './pages.ts';
+export type { ArticleOptions, CollectionPageOptions, ItemListOptions, AboutPageOptions, PersonOptions, AggregateOfferOptions, TouristDestinationFields, } from './pages.ts';
+export { hotelBuilder, activityBuilder, touristTripBuilder } from './places.ts';
+export type { HotelOptions, ActivityOptions, TouristTripOptions } from './places.ts';
+export { eventBuilder, eventItemListBuilder } from './events.ts';
+export type { EventPolicy, EventOptions, EventItemListOptions } from './events.ts';

package/dist/schema/index.js

@@ -0,0 +1,7 @@
+export { createSchemaContext, normalizeHomepageUrl, normalizeStructuredDataUrls, formatSchemaDate, createPersonSchema, withAuthorPersonSchema, } from "./context.js";
+export { parsePriceFromString, cleanStreetAddress, normalizePriceRange, normalizeHotelPriceRange, postalCodeOf, dataAddressPolicy, postalAddress, geoCoordinates, aggregateRating, } from "./values.js";
+export { DAY_KEYS, HOURS_ALWAYS_OPEN, parseHoursShifts, closedFieldDays, resolveOpeningHours, assertedOpenDays, generateOpeningHours, parseHoursString, hoursStringOpenDays, } from "./hours.js";
+export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } from "./graph.js";
+export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from "./pages.js";
+export { hotelBuilder, activityBuilder, touristTripBuilder } from "./places.js";
+export { eventBuilder, eventItemListBuilder } from "./events.js";

package/dist/schema/pages.d.ts

@@ -0,0 +1,62 @@
+import type { JsonLdNode, SchemaBuilder } from './types.ts';
+/** FAQPage from `data.questions` (or `data.faq`), with question and answer through `ctx.plainText`. */
+export declare function faqPageBuilder(): SchemaBuilder;
+export interface ArticleOptions {
+    /** Append each existing `data.imageVariants` path to `image`. */
+    imageVariants?: boolean;
+    /** Image used when the article has none. */
+    defaultImage?: string;
+    /** `articleSection` when `data.category` is empty. */
+    defaultSection?: string;
+    inLanguage?: string;
+    speakableSelectors?: string[];
+}
+/**
+ * Article (+ its author's Person first, + a FAQPage from `data.questions`). `citation` comes from `data.sources`.
+ * The FAQPage here keeps question and answer text as given, unlike `faqPageBuilder`.
+ */
+export declare function articleBuilder(options?: ArticleOptions): SchemaBuilder;
+export interface CollectionPageOptions {
+    /** An item typed `Event` is emitted as `WebPage` (its own page carries the full Event). */
+    demoteEvent?: boolean;
+    /** Add each item's dates and its author's full Person node. */
+    itemMeta?: boolean;
+}
+/** CollectionPage whose `mainEntity` lists `data.items`; an item without `url` links to its museum/monument route. */
+export declare function collectionPageBuilder(options?: CollectionPageOptions): SchemaBuilder;
+export interface ItemListOptions {
+    /** `data.itemType` → schema type. Given: each item is a typed nested entity; absent: name/url on the ListItem. */
+    itemTypes?: Record<string, string>;
+}
+/** ItemList of `data.items` linked at `/${data.itemType}/${slug}`. */
+export declare function itemListBuilder(options?: ItemListOptions): SchemaBuilder;
+export declare function howToBuilder(): SchemaBuilder;
+export interface AboutPageOptions {
+    /** When `data.author` resolves, emit their Person first and point `mainEntity` at it. */
+    authorAsMainEntity?: boolean;
+}
+export declare function aboutPageBuilder(options?: AboutPageOptions): SchemaBuilder;
+export declare function contactPageBuilder(): SchemaBuilder;
+export interface PersonOptions {
+    /** Resolve a root-relative `data.url` to an absolute one, so the `@id` names one entity (SLA-2143). */
+    absoluteUrl?: boolean;
+    /** Emit `mainEntityOfPage` only on the person's own page (SLA-2143). */
+    mainEntityOfPageOnOwnPage?: boolean;
+}
+export declare function personBuilder(options?: PersonOptions): SchemaBuilder;
+export interface AggregateOfferOptions {
+    currency?: string;
+}
+export declare function aggregateOfferBuilder(options?: AggregateOfferOptions): SchemaBuilder;
+/** The site-level TouristDestination node; every field but `url` comes from the site. */
+export interface TouristDestinationFields {
+    name: string;
+    description: string;
+    address?: JsonLdNode;
+    containedInPlace?: JsonLdNode;
+    geo?: JsonLdNode;
+    touristType?: string | string[];
+}
+export declare function touristDestinationBuilder(fields: TouristDestinationFields): SchemaBuilder;
+/** The Organization lives in the base graph, so an `organization` entry emits nothing. */
+export declare function organizationBuilder(): SchemaBuilder;

package/dist/schema/pages.js

@@ -0,0 +1,213 @@
+import { toAbsoluteSiteUrl } from "../url/index.js";
+import { createPersonSchema } from "./context.js";
+/** FAQPage from `data.questions` (or `data.faq`), with question and answer through `ctx.plainText`. */
+export function faqPageBuilder() {
+    return (data, ctx) => {
+        const questions = data.questions || data.faq;
+        if (!questions?.length)
+            return null;
+        return {
+            '@type': 'FAQPage',
+            '@id': `${ctx.pageUrl}#faq`,
+            mainEntity: questions.map((q) => ({
+                '@type': 'Question',
+                name: ctx.plainText(q.question),
+                acceptedAnswer: { '@type': 'Answer', text: ctx.plainText(q.answer) },
+            })),
+        };
+    };
+}
+/**
+ * Article (+ its author's Person first, + a FAQPage from `data.questions`). `citation` comes from `data.sources`.
+ * The FAQPage here keeps question and answer text as given, unlike `faqPageBuilder`.
+ */
+export function articleBuilder(options = {}) {
+    const { imageVariants = false, defaultImage = '/og-default.jpg', defaultSection = 'Travel Guide', inLanguage = 'en', speakableSelectors = ['h1', '.article-lede'], } = options;
+    return (data, ctx) => {
+        const articleImageUrl = data.image ? ctx.resolveImageUrl(data.image, data.slug) : ctx.abs(defaultImage);
+        const articleUrl = data.url ? ctx.absOrHttp(data.url) : ctx.pageUrl;
+        const author = ctx.resolveAuthor(data.author);
+        const variants = imageVariants
+            ? (data.imageVariants ?? []).filter((p) => ctx.fileExists(p)).map((p) => ctx.abs(p))
+            : [];
+        const article = {
+            '@type': 'Article',
+            '@id': `${articleUrl}#article`,
+            headline: data.headline || data.title,
+            description: data.description,
+            image: variants.length ? [articleImageUrl, ...variants] : articleImageUrl,
+            datePublished: ctx.formatDate(data.datePublished),
+            dateModified: ctx.formatDate(data.dateModified || data.datePublished),
+            author: author ? { '@id': author.id } : undefined,
+            publisher: ctx.publisherFor(data.author),
+            mainEntityOfPage: { '@id': ctx.pageUrl },
+            articleSection: data.category || defaultSection,
+            inLanguage,
+            citation: Array.isArray(data.sources) && data.sources.length > 0
+                ? data.sources.map((s) => (typeof s === 'string'
+                    ? { '@type': 'WebPage', url: s }
+                    : { '@type': 'WebPage', url: s.url, ...(s.name ? { name: s.name } : {}) }))
+                : undefined,
+            speakable: { '@type': 'SpeakableSpecification', cssSelector: speakableSelectors },
+        };
+        if ((data.questions?.length ?? 0) > 0) {
+            return [
+                ...(author ? [createPersonSchema(author)] : []),
+                article,
+                {
+                    '@type': 'FAQPage',
+                    '@id': `${articleUrl}#faq`,
+                    mainEntity: data.questions.map((q) => ({
+                        '@type': 'Question',
+                        name: q.question,
+                        acceptedAnswer: { '@type': 'Answer', text: q.answer },
+                    })),
+                },
+            ];
+        }
+        return author ? [createPersonSchema(author), article] : article;
+    };
+}
+/** CollectionPage whose `mainEntity` lists `data.items`; an item without `url` links to its museum/monument route. */
+export function collectionPageBuilder(options = {}) {
+    const { demoteEvent = true, itemMeta = false } = options;
+    return (data, ctx) => {
+        const hasItems = data.items && data.items.length > 0;
+        return {
+            '@type': 'CollectionPage',
+            name: data.name,
+            description: data.description,
+            url: data.url ? ctx.abs(data.url) : ctx.siteBaseUrl,
+            mainEntity: hasItems ? {
+                '@type': 'ItemList',
+                name: data.name,
+                numberOfItems: data.items.length,
+                itemListElement: data.items.map((item, index) => {
+                    const itemUrl = item.url
+                        ? ctx.absOrHttp(item.url)
+                        : ctx.route(data.itemType === 'museum' ? 'museum' : 'monument', item.slug);
+                    const rawItemType = item.schemaType || (data.itemType === 'museum' ? 'Museum' : data.itemType === 'page' ? 'WebPage' : 'TouristAttraction');
+                    const itemType = demoteEvent && rawItemType === 'Event' ? 'WebPage' : rawItemType;
+                    const itemAuthor = itemMeta ? ctx.resolveAuthor(item.author) : null;
+                    return {
+                        '@type': 'ListItem',
+                        position: index + 1,
+                        item: {
+                            '@type': itemType,
+                            name: item.name,
+                            url: itemUrl,
+                            description: item.description,
+                            ...(itemMeta && item.datePublished && { datePublished: ctx.formatDate(item.datePublished) }),
+                            ...(itemMeta && item.dateModified && { dateModified: ctx.formatDate(item.dateModified) }),
+                            ...(itemAuthor && { author: createPersonSchema(itemAuthor) }),
+                        },
+                    };
+                }),
+            } : undefined,
+            dateModified: data.dateModified,
+        };
+    };
+}
+/** ItemList of `data.items` linked at `/${data.itemType}/${slug}`. */
+export function itemListBuilder(options = {}) {
+    const { itemTypes } = options;
+    return (data, ctx) => ({
+        '@type': 'ItemList',
+        name: data.name,
+        description: data.description,
+        numberOfItems: data.items?.length || 0,
+        itemListElement: data.items?.map((item, index) => {
+            const url = ctx.abs(`/${data.itemType}/${item.slug}`);
+            return itemTypes
+                ? { '@type': 'ListItem', position: index + 1, item: { '@type': itemTypes[data.itemType] ?? 'WebPage', name: item.name, url } }
+                : { '@type': 'ListItem', position: index + 1, name: item.name, url };
+        }),
+    });
+}
+export function howToBuilder() {
+    return (data) => ({
+        '@type': 'HowTo',
+        name: data.name,
+        description: data.description,
+        totalTime: data.totalTime,
+        step: data.steps?.map((step, i) => ({
+            '@type': 'HowToStep',
+            position: i + 1,
+            name: step.name,
+            text: step.text,
+            url: step.url || undefined,
+        })),
+    });
+}
+export function aboutPageBuilder(options = {}) {
+    return (data, ctx) => {
+        const author = options.authorAsMainEntity ? ctx.resolveAuthor(data.author) : null;
+        const node = {
+            '@type': 'AboutPage',
+            name: data.name,
+            description: data.description,
+            url: ctx.pageUrl,
+            mainEntityOfPage: { '@id': ctx.pageUrl },
+            ...(author ? { mainEntity: { '@id': author.id } } : {}),
+        };
+        return author ? [createPersonSchema(author), node] : node;
+    };
+}
+export function contactPageBuilder() {
+    return (data, ctx) => ({
+        '@type': 'ContactPage',
+        name: data.name,
+        description: data.description,
+        url: ctx.pageUrl,
+        mainEntityOfPage: { '@id': ctx.pageUrl },
+    });
+}
+export function personBuilder(options = {}) {
+    return (data, ctx) => {
+        const personUrl = options.absoluteUrl
+            ? (data.url ? (data.url.startsWith('/') ? toAbsoluteSiteUrl(data.url, ctx.siteUrl, ctx.basePath) : data.url) : ctx.pageUrl)
+            : data.url || ctx.pageUrl;
+        const idBase = options.absoluteUrl ? personUrl : (data.url ? data.url : ctx.pageUrl);
+        const ownPage = !options.mainEntityOfPageOnOwnPage || personUrl === ctx.pageUrl;
+        return {
+            '@type': 'Person',
+            '@id': `${idBase}#person`,
+            name: data.name,
+            description: data.description,
+            url: personUrl,
+            image: data.image ? ctx.absOrHttp(data.image) : undefined,
+            sameAs: data.sameAs,
+            knowsAbout: data.expertise,
+            jobTitle: data.jobTitle,
+            worksFor: { '@id': ctx.orgId },
+            ...(ownPage ? { mainEntityOfPage: { '@id': ctx.pageUrl } } : {}),
+        };
+    };
+}
+export function aggregateOfferBuilder(options = {}) {
+    const { currency = 'EUR' } = options;
+    return (data, ctx) => ({
+        '@type': 'AggregateOffer',
+        priceCurrency: data.priceCurrency || currency,
+        lowPrice: data.lowPrice,
+        highPrice: data.highPrice,
+        offerCount: data.offerCount,
+        url: data.url ? ctx.absOrHttp(data.url) : ctx.pageUrl,
+    });
+}
+export function touristDestinationBuilder(fields) {
+    return (_data, ctx) => ({
+        '@type': 'TouristDestination',
+        name: fields.name,
+        description: fields.description,
+        url: ctx.siteBaseUrl,
+        address: fields.address,
+        containedInPlace: fields.containedInPlace,
+        geo: fields.geo,
+        touristType: fields.touristType,
+    });
+}
+/** The Organization lives in the base graph, so an `organization` entry emits nothing. */
+export function organizationBuilder() {
+    return () => null;
+}

package/dist/schema/places.d.ts

@@ -0,0 +1,27 @@
+import { type AddressPolicy } from './values.ts';
+import type { SchemaBuilder } from './types.ts';
+export interface HotelOptions {
+    address: AddressPolicy;
+    defaultCheckinTime?: string;
+    defaultCheckoutTime?: string;
+}
+/** Hotel at route `hotel`; no `openingHours` means open around the clock. */
+export declare function hotelBuilder(options: HotelOptions): SchemaBuilder;
+export interface ActivityOptions {
+    address: AddressPolicy;
+    touristType?: string;
+    /** `availableLanguage` when the item lists none; absent: omitted. */
+    defaultLanguages?: string[];
+    /** Emit an Offer from `data.priceFrom`. */
+    offers?: boolean;
+    currency?: string;
+}
+/** TouristAttraction at route `activity`; the street falls back to `meetingPoint`. */
+export declare function activityBuilder(options: ActivityOptions): SchemaBuilder;
+export interface TouristTripOptions {
+    touristType?: string;
+    offerDescription?: string;
+    currency?: string;
+}
+/** A free self-guided TouristTrip at route `walk`, its stops as the itinerary. */
+export declare function touristTripBuilder(options?: TouristTripOptions): SchemaBuilder;

package/dist/schema/places.js

@@ -0,0 +1,94 @@
+import { withAuthorPersonSchema } from "./context.js";
+import { generateOpeningHours } from "./hours.js";
+import { aggregateRating, geoCoordinates, normalizeHotelPriceRange, parsePriceFromString, postalAddress, postalCodeOf, } from "./values.js";
+/** Hotel at route `hotel`; no `openingHours` means open around the clock. */
+export function hotelBuilder(options) {
+    const { address, defaultCheckinTime = '14:00', defaultCheckoutTime = '12:00' } = options;
+    return (data, ctx) => {
+        const imageUrl = ctx.resolveImageUrl(data.image, data.slug);
+        return withAuthorPersonSchema(ctx, {
+            '@type': 'Hotel',
+            name: data.name,
+            description: data.description,
+            image: imageUrl ? { '@type': 'ImageObject', url: imageUrl } : undefined,
+            address: postalAddress(address, data, { street: data.address, postalCode: postalCodeOf(data) }),
+            geo: geoCoordinates(data.coordinates),
+            priceRange: normalizeHotelPriceRange(data.priceRange),
+            starRating: data.starRating ? { '@type': 'Rating', ratingValue: data.starRating, bestRating: 5 } : undefined,
+            aggregateRating: aggregateRating(data),
+            amenityFeature: data.amenities?.map((amenity) => ({
+                '@type': 'LocationFeatureSpecification',
+                name: amenity,
+                value: true,
+            })),
+            telephone: data.phone,
+            checkinTime: data.checkinTime || defaultCheckinTime,
+            checkoutTime: data.checkoutTime || defaultCheckoutTime,
+            openingHoursSpecification: generateOpeningHours(data.openingHours || { alwaysOpen: true }),
+            sameAs: data.website ? [data.website] : undefined,
+            mainEntityOfPage: { '@id': ctx.pageUrl },
+            url: ctx.route('hotel', data.slug),
+        }, data.author);
+    };
+}
+/** TouristAttraction at route `activity`; the street falls back to `meetingPoint`. */
+export function activityBuilder(options) {
+    const { address, touristType = 'Cultural', defaultLanguages, offers = false, currency = 'EUR' } = options;
+    return (data, ctx) => withAuthorPersonSchema(ctx, {
+        '@type': 'TouristAttraction',
+        name: data.name,
+        description: data.description,
+        image: ctx.resolveImageUrl(data.image, data.slug),
+        address: postalAddress(address, data, { street: data.address || data.meetingPoint, postalCode: postalCodeOf(data) }),
+        geo: geoCoordinates(data.coordinates),
+        touristType,
+        isAccessibleForFree: parsePriceFromString(data.price) === 0,
+        publicAccess: true,
+        availableLanguage: data.languages || defaultLanguages,
+        telephone: data.phone,
+        aggregateRating: aggregateRating(data),
+        offers: offers && data.priceFrom !== undefined ? {
+            '@type': 'Offer',
+            price: data.priceFrom,
+            priceCurrency: currency,
+            availability: 'https://schema.org/InStock',
+        } : undefined,
+        mainEntityOfPage: { '@id': ctx.pageUrl },
+        url: ctx.route('activity', data.slug),
+    }, data.author);
+}
+/** A free self-guided TouristTrip at route `walk`, its stops as the itinerary. */
+export function touristTripBuilder(options = {}) {
+    const { touristType = 'Cultural', offerDescription = 'Self-guided walking tour — free', currency = 'EUR' } = options;
+    return (data, ctx) => withAuthorPersonSchema(ctx, {
+        '@type': 'TouristTrip',
+        name: data.name,
+        description: data.description,
+        image: ctx.resolveImageUrl(data.image, data.slug),
+        touristType: data.theme || touristType,
+        offers: {
+            '@type': 'Offer',
+            price: 0,
+            priceCurrency: currency,
+            availability: 'https://schema.org/InStock',
+            description: offerDescription,
+        },
+        itinerary: {
+            '@type': 'ItemList',
+            numberOfItems: data.stops?.length || 0,
+            itemListElement: (data.stops || []).map((stop, i) => ({
+                '@type': 'ListItem',
+                position: i + 1,
+                item: {
+                    '@type': 'TouristAttraction',
+                    name: stop.name,
+                    description: stop.description,
+                    geo: geoCoordinates(stop.coordinates),
+                    ...(stop.slug && stop.type !== 'landmark' ? { url: ctx.abs(`/${stop.type}/${stop.slug}`) } : {}),
+                },
+            })),
+        },
+        mainEntityOfPage: { '@id': ctx.pageUrl },
+        url: ctx.route('walk', data.slug),
+    }, data.author);
+}