@getvitops/utils 7.0.0 → 8.0.1

package/dist/reviews/index.mjs

@@ -0,0 +1,218 @@
+import { n as writeVersioned, t as readVersioned } from "../json-store-30CFCbZZ.mjs";
+import { a as googleHeaders, i as googleAccessToken, t as SCOPES } from "../token-DkKC5m23.mjs";
+import { n as adcQuotaProject, r as parseAdcUser, t as adcCredentialsPath } from "../adc-D6aw2qgq.mjs";
+
+//#region src/reviews/plan.ts
+/** Decide which locations to fetch, and why any are skipped. */
+function plan(input) {
+	const { config, knownLocations, onlyLocation, hasCredential } = input;
+	const notes = [];
+	if (!config || Object.keys(config.locations).length === 0) return {
+		blocked: "no site.reviews.locations configured — nothing to fetch",
+		locations: [],
+		notes
+	};
+	if (!hasCredential) return {
+		blocked: "no Google credential — set VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET / _REFRESH_TOKEN, or run `gcloud auth application-default login`",
+		locations: [],
+		notes
+	};
+	const entries = onlyLocation ? Object.entries(config.locations).filter(([key]) => key === onlyLocation) : Object.entries(config.locations);
+	if (onlyLocation && entries.length === 0) return {
+		blocked: `--location "${onlyLocation}" is not in site.reviews.locations`,
+		locations: [],
+		notes
+	};
+	const locations = entries.map(([key, loc]) => {
+		if (!knownLocations.has(key)) return {
+			key,
+			skip: `organization.locations has no entry keyed "${key}" with a listings.google id`
+		};
+		const accountId = loc.accountId ?? config.accountId;
+		if (!accountId) return {
+			key,
+			skip: `no accountId — set site.reviews.accountId or locations.${key}.accountId`
+		};
+		return {
+			key,
+			accountId,
+			locationId: loc.locationId
+		};
+	});
+	const blocked = locations.filter((l) => l.skip);
+	if (blocked.length) for (const l of blocked) notes.push(`${l.key}: skipped — ${l.skip}`);
+	return {
+		locations,
+		notes
+	};
+}
+/** Render a plan as the human-readable block `--dry` prints. */
+function formatPlan(p) {
+	if (p.blocked) return `✗ blocked — ${p.blocked}`;
+	const lines = [];
+	const active = p.locations.filter((l) => !l.skip);
+	lines.push(`locations  ${active.length} of ${p.locations.length} will be fetched`);
+	for (const l of active) lines.push(`  ${l.key}  ${l.accountId}/${l.locationId}`);
+	for (const n of p.notes) lines.push(`  ! ${n}`);
+	return lines.join("\n");
+}
+/**
+* Filter and order one location's reviews for display.
+*
+* Featured ids always win and keep the author's order — an explicit choice
+* overrides any automatic ranking. The remainder is filtered by `minRating`
+* (default 4 — a star-rating widget showing a 1-star review it did not have to
+* is a design choice a config field should not have to spell out every time),
+* sorted, then capped by `limit`.
+*/
+function selectReviews(reviews, config) {
+	const featuredIds = config.featured ?? [];
+	const byId = new Map(reviews.map((r) => [r.id, r]));
+	const featured = featuredIds.map((id) => byId.get(id)).filter((r) => !!r);
+	const featuredSet = new Set(featured.map((r) => r.id));
+	const minRating = config.minRating ?? 4;
+	const rest = reviews.filter((r) => !featuredSet.has(r.id) && r.rating >= minRating).sort((a, b) => config.sort === "rating" ? b.rating - a.rating : new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime());
+	const combined = [...featured, ...rest];
+	return config.limit !== void 0 ? combined.slice(0, config.limit) : combined;
+}
+/**
+* Merge a fresh fetch into the existing cache.
+*
+* Only the locations actually fetched this run are replaced; every other
+* location's prior reviews pass through untouched. This is what makes a partial
+* failure (one location's fetch errors) non-destructive — `cmdReviews` merges
+* only the locations that succeeded and leaves the rest of the cache alone.
+*/
+function mergeCache(existing, fetched) {
+	return {
+		version: 1,
+		locations: {
+			...existing?.locations,
+			...fetched
+		}
+	};
+}
+
+//#endregion
+//#region src/reviews/cache.ts
+/** Default location, relative to the consumer's project root. */
+const REVIEWS_CACHE_PATH = ".vitops/reviews.json";
+/**
+* Read the cache, or `undefined` when there isn't a usable one.
+*
+* A corrupt or wrong-version file reads as absent, exactly `readManifest`'s rule:
+* the alternative — reading it as an empty cache — would be indistinguishable
+* from "this business genuinely has no reviews" and silently ship an empty
+* carousel.
+*/
+function readCache(path) {
+	return readVersioned(path, "locations");
+}
+/** Build a cache with its keys and each location's reviews in a stable order. */
+function toCache(locations) {
+	const sorted = {};
+	for (const key of Object.keys(locations).sort()) {
+		const entry = locations[key];
+		sorted[key] = {
+			...entry,
+			reviews: [...entry.reviews].sort((a, b) => a.id.localeCompare(b.id))
+		};
+	}
+	return {
+		version: 1,
+		locations: sorted
+	};
+}
+/** Write the cache, creating its directory. */
+function writeCache(path, cache) {
+	writeVersioned(path, cache);
+}
+
+//#endregion
+//#region src/reviews/gbp.ts
+/**
+* Google Business Profile — fetching one location's reviews.
+*
+* Reviews live only on the legacy v4 Business Information API
+* (`mybusiness.googleapis.com/v4`); the newer split APIs (Account Management,
+* Business Information v1) never grew a reviews resource. **The calling GCP
+* project must be allowlisted by Google before any call here succeeds** — a
+* one-time access-request form, turnaround measured in days to weeks — so a 403
+* is treated as that known state rather than surfaced as a raw failure. Scope:
+* `SCOPES.businessProfile` (`../google/token.ts`).
+*
+* TODO — re-check when Google migrates the Reviews endpoint off v4 onto a
+* successor API. Endpoint, auth, pagination and the review object's fields may
+* all change; this module is the one place that assumption lives.
+*
+* Auth is the shared exchange in `../google/token.ts`, same as `../indexing/gsc.ts`
+* — no `googleapis` dependency, one REST endpoint.
+*/
+const STAR_RATING = {
+	ONE: 1,
+	TWO: 2,
+	THREE: 3,
+	FOUR: 4,
+	FIVE: 5
+};
+function toReview(raw, location) {
+	return {
+		id: raw.reviewId,
+		location,
+		rating: STAR_RATING[raw.starRating ?? ""] ?? 0,
+		author: raw.reviewer?.isAnonymous ? "A Google user" : raw.reviewer?.displayName ?? "A Google user",
+		...raw.reviewer?.profilePhotoUrl ? { authorPhoto: raw.reviewer.profilePhotoUrl } : {},
+		...raw.comment ? { text: raw.comment } : {},
+		publishedAt: raw.createTime,
+		updatedAt: raw.updateTime,
+		...raw.reviewReply ? { reply: {
+			text: raw.reviewReply.comment,
+			at: raw.reviewReply.updateTime
+		} } : {}
+	};
+}
+/**
+* Fetch every review for one location, paginating to completion.
+*
+* Never throws — a per-location failure is a structured result so a run across
+* several locations can fetch what it can and report the rest, the same contract
+* `../indexing/gsc.ts`'s `inspectUrl` keeps.
+*/
+async function fetchReviews(auth, accountId, locationId, fetchImpl = fetch) {
+	const location = locationId.startsWith("locations/") ? locationId : `locations/${locationId}`;
+	const account = accountId.startsWith("accounts/") ? accountId : `accounts/${accountId}`;
+	const reviews = [];
+	let averageRating;
+	let totalReviewCount;
+	let pageToken;
+	do {
+		const url = new URL(`https://mybusiness.googleapis.com/v4/${account}/${location}/reviews`);
+		url.searchParams.set("pageSize", "50");
+		if (pageToken) url.searchParams.set("pageToken", pageToken);
+		const res = await fetchImpl(url, { headers: googleHeaders(auth) });
+		if (!res.ok) {
+			const message = res.status === 403 ? `403 — this GCP project is most likely not allowlisted for the Business Profile API yet (a one-time Google approval, requested separately from every other API here), or the credential is not an owner/manager of ${account}/${location}` : `${res.status}: ${await res.text()}`;
+			return {
+				ok: false,
+				reviews,
+				status: res.status,
+				message
+			};
+		}
+		const body = await res.json();
+		for (const r of body.reviews ?? []) reviews.push(toReview(r, locationId));
+		averageRating = body.averageRating ?? averageRating;
+		totalReviewCount = body.totalReviewCount ?? totalReviewCount;
+		pageToken = body.nextPageToken;
+	} while (pageToken);
+	return {
+		ok: true,
+		reviews,
+		...averageRating !== void 0 ? { averageRating } : {},
+		...totalReviewCount !== void 0 ? { totalReviewCount } : {}
+	};
+}
+
+//#endregion
+export { REVIEWS_CACHE_PATH, SCOPES, adcCredentialsPath, adcQuotaProject, fetchReviews, formatPlan, googleAccessToken, googleHeaders, mergeCache, parseAdcUser, plan, readCache, selectReviews, toCache, writeCache };
+//# sourceMappingURL=index.mjs.map

package/dist/reviews/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/reviews/plan.ts","../../src/reviews/cache.ts","../../src/reviews/gbp.ts"],"sourcesContent":["/**\n * Every decision `vitops reviews` makes, as pure functions.\n *\n * Same split as `../indexing/plan.ts`: no `fetch`, no `fs`, no clock. Which\n * locations to fetch (and why one is blocked), and how a location's reviews are\n * filtered down to what a site actually displays, are decided here — `gbp.ts`\n * and `cache.ts` do what they're told and nothing else. That is what lets Astro's\n * `<ReviewCard>` and a future Bricks renderer both call `selectReviews` instead\n * of each re-implementing \"top 5 by rating, minus the ones already featured\".\n */\nimport type {\n  LocationReviews,\n  Review,\n  ReviewCache,\n  ReviewLocationConfig,\n  ReviewsConfig,\n} from './types.ts';\n\n/** One location's fetch plan, or the reason it was skipped. */\nexport interface LocationPlan {\n  key: string;\n  accountId?: string;\n  locationId?: string;\n  /** Present iff this location will not be fetched. */\n  skip?: string;\n}\n\nexport interface ReviewsPlan {\n  /** Set when the whole run is refused — nothing is fetched. */\n  blocked?: string;\n  locations: LocationPlan[];\n  notes: string[];\n}\n\nexport interface PlanInput {\n  config: ReviewsConfig | undefined;\n  /** Location keys with a Google listing configured (`organization.locations[].listings.google`). */\n  knownLocations: Set<string>;\n  /** `--location`: fetch exactly this one, skipping the rest. */\n  onlyLocation?: string | undefined;\n  /** Whether a Google credential was resolved. */\n  hasCredential: boolean;\n}\n\n/** Decide which locations to fetch, and why any are skipped. */\nexport function plan(input: PlanInput): ReviewsPlan {\n  const { config, knownLocations, onlyLocation, hasCredential } = input;\n  const notes: string[] = [];\n\n  if (!config || Object.keys(config.locations).length === 0) {\n    return {\n      blocked: 'no site.reviews.locations configured — nothing to fetch',\n      locations: [],\n      notes,\n    };\n  }\n\n  if (!hasCredential) {\n    return {\n      blocked:\n        'no Google credential — set VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET / _REFRESH_TOKEN, or run `gcloud auth application-default login`',\n      locations: [],\n      notes,\n    };\n  }\n\n  const entries = onlyLocation\n    ? Object.entries(config.locations).filter(([key]) => key === onlyLocation)\n    : Object.entries(config.locations);\n\n  if (onlyLocation && entries.length === 0) {\n    return {\n      blocked: `--location \"${onlyLocation}\" is not in site.reviews.locations`,\n      locations: [],\n      notes,\n    };\n  }\n\n  const locations: LocationPlan[] = entries.map(([key, loc]) => {\n    if (!knownLocations.has(key))\n      return {\n        key,\n        skip: `organization.locations has no entry keyed \"${key}\" with a listings.google id`,\n      };\n    const accountId = loc.accountId ?? config.accountId;\n    if (!accountId)\n      return {\n        key,\n        skip: `no accountId — set site.reviews.accountId or locations.${key}.accountId`,\n      };\n    return { key, accountId, locationId: loc.locationId };\n  });\n\n  const blocked = locations.filter((l) => l.skip);\n  if (blocked.length) for (const l of blocked) notes.push(`${l.key}: skipped — ${l.skip}`);\n\n  return { locations, notes };\n}\n\n/** Render a plan as the human-readable block `--dry` prints. */\nexport function formatPlan(p: ReviewsPlan): string {\n  if (p.blocked) return `✗ blocked — ${p.blocked}`;\n  const lines: string[] = [];\n  const active = p.locations.filter((l) => !l.skip);\n  lines.push(`locations  ${active.length} of ${p.locations.length} will be fetched`);\n  for (const l of active) lines.push(`  ${l.key}  ${l.accountId}/${l.locationId}`);\n  for (const n of p.notes) lines.push(`  ! ${n}`);\n  return lines.join('\\n');\n}\n\n/**\n * Filter and order one location's reviews for display.\n *\n * Featured ids always win and keep the author's order — an explicit choice\n * overrides any automatic ranking. The remainder is filtered by `minRating`\n * (default 4 — a star-rating widget showing a 1-star review it did not have to\n * is a design choice a config field should not have to spell out every time),\n * sorted, then capped by `limit`.\n */\nexport function selectReviews(reviews: Review[], config: ReviewLocationConfig): Review[] {\n  const featuredIds = config.featured ?? [];\n  const byId = new Map(reviews.map((r) => [r.id, r]));\n  const featured = featuredIds.map((id) => byId.get(id)).filter((r): r is Review => !!r);\n  const featuredSet = new Set(featured.map((r) => r.id));\n\n  const minRating = config.minRating ?? 4;\n  const rest = reviews\n    .filter((r) => !featuredSet.has(r.id) && r.rating >= minRating)\n    .sort((a, b) =>\n      config.sort === 'rating'\n        ? b.rating - a.rating\n        : new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime(),\n    );\n\n  const combined = [...featured, ...rest];\n  return config.limit !== undefined ? combined.slice(0, config.limit) : combined;\n}\n\n/**\n * Merge a fresh fetch into the existing cache.\n *\n * Only the locations actually fetched this run are replaced; every other\n * location's prior reviews pass through untouched. This is what makes a partial\n * failure (one location's fetch errors) non-destructive — `cmdReviews` merges\n * only the locations that succeeded and leaves the rest of the cache alone.\n */\nexport function mergeCache(\n  existing: ReviewCache | undefined,\n  fetched: Record<string, LocationReviews>,\n): ReviewCache {\n  return {\n    version: 1,\n    locations: { ...existing?.locations, ...fetched },\n  };\n}\n","/**\n * The cache — what makes a re-render free and offline.\n *\n * Committed, like `../media/manifest.ts` and for the same reason: reviews change\n * slowly, and a build should not need a live Google credential to render them. The\n * one field that keeps it from being byte-identical across runs is `fetchedAt` per\n * location — acceptable because `vitops reviews` is invoked deliberately\n * (scheduled or manual), not rewritten on every build the way `media-manifest.json`\n * is.\n */\nimport type { LocationReviews, ReviewCache } from './types.ts';\nimport { readVersioned, writeVersioned } from '../json-store.ts';\n\n/** Default location, relative to the consumer's project root. */\nexport const REVIEWS_CACHE_PATH = '.vitops/reviews.json';\n\n/**\n * Read the cache, or `undefined` when there isn't a usable one.\n *\n * A corrupt or wrong-version file reads as absent, exactly `readManifest`'s rule:\n * the alternative — reading it as an empty cache — would be indistinguishable\n * from \"this business genuinely has no reviews\" and silently ship an empty\n * carousel.\n */\nexport function readCache(path: string): ReviewCache | undefined {\n  return readVersioned<ReviewCache, 'locations'>(path, 'locations');\n}\n\n/** Build a cache with its keys and each location's reviews in a stable order. */\nexport function toCache(locations: Record<string, LocationReviews>): ReviewCache {\n  const sorted: Record<string, LocationReviews> = {};\n  for (const key of Object.keys(locations).sort()) {\n    const entry = locations[key] as LocationReviews;\n    sorted[key] = {\n      ...entry,\n      reviews: [...entry.reviews].sort((a, b) => a.id.localeCompare(b.id)),\n    };\n  }\n  return { version: 1, locations: sorted };\n}\n\n/** Write the cache, creating its directory. */\nexport function writeCache(path: string, cache: ReviewCache): void {\n  writeVersioned(path, cache);\n}\n","/**\n * Google Business Profile — fetching one location's reviews.\n *\n * Reviews live only on the legacy v4 Business Information API\n * (`mybusiness.googleapis.com/v4`); the newer split APIs (Account Management,\n * Business Information v1) never grew a reviews resource. **The calling GCP\n * project must be allowlisted by Google before any call here succeeds** — a\n * one-time access-request form, turnaround measured in days to weeks — so a 403\n * is treated as that known state rather than surfaced as a raw failure. Scope:\n * `SCOPES.businessProfile` (`../google/token.ts`).\n *\n * TODO — re-check when Google migrates the Reviews endpoint off v4 onto a\n * successor API. Endpoint, auth, pagination and the review object's fields may\n * all change; this module is the one place that assumption lives.\n *\n * Auth is the shared exchange in `../google/token.ts`, same as `../indexing/gsc.ts`\n * — no `googleapis` dependency, one REST endpoint.\n */\nimport { googleHeaders, type GoogleAuthLike } from '../google/token.ts';\nimport type { Review } from './types.ts';\n\nconst STAR_RATING: Record<string, number> = {\n  ONE: 1,\n  TWO: 2,\n  THREE: 3,\n  FOUR: 4,\n  FIVE: 5,\n};\n\ninterface RawReview {\n  reviewId: string;\n  reviewer?: { displayName?: string; profilePhotoUrl?: string; isAnonymous?: boolean };\n  starRating?: string;\n  comment?: string;\n  createTime: string;\n  updateTime: string;\n  reviewReply?: { comment: string; updateTime: string };\n}\n\nfunction toReview(raw: RawReview, location: string): Review {\n  return {\n    id: raw.reviewId,\n    location,\n    rating: STAR_RATING[raw.starRating ?? ''] ?? 0,\n    author: raw.reviewer?.isAnonymous\n      ? 'A Google user'\n      : (raw.reviewer?.displayName ?? 'A Google user'),\n    ...(raw.reviewer?.profilePhotoUrl ? { authorPhoto: raw.reviewer.profilePhotoUrl } : {}),\n    ...(raw.comment ? { text: raw.comment } : {}),\n    publishedAt: raw.createTime,\n    updatedAt: raw.updateTime,\n    ...(raw.reviewReply\n      ? { reply: { text: raw.reviewReply.comment, at: raw.reviewReply.updateTime } }\n      : {}),\n    // v4 carries no public review URL on the resource itself. The stable link is\n    // `organization.locations[].listings.google` / `sameAs` — the whole profile,\n    // not the single review — which is what a \"read more on Google\" affordance\n    // should point at instead.\n  };\n}\n\n/** One page (or, having paginated, the whole set) of a location's reviews. */\nexport interface FetchReviewsResult {\n  ok: boolean;\n  reviews: Review[];\n  averageRating?: number;\n  totalReviewCount?: number;\n  status?: number;\n  message?: string;\n}\n\n/**\n * Fetch every review for one location, paginating to completion.\n *\n * Never throws — a per-location failure is a structured result so a run across\n * several locations can fetch what it can and report the rest, the same contract\n * `../indexing/gsc.ts`'s `inspectUrl` keeps.\n */\nexport async function fetchReviews(\n  auth: GoogleAuthLike,\n  accountId: string,\n  locationId: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<FetchReviewsResult> {\n  const location = locationId.startsWith('locations/') ? locationId : `locations/${locationId}`;\n  const account = accountId.startsWith('accounts/') ? accountId : `accounts/${accountId}`;\n  const reviews: Review[] = [];\n  let averageRating: number | undefined;\n  let totalReviewCount: number | undefined;\n  let pageToken: string | undefined;\n\n  do {\n    const url = new URL(`https://mybusiness.googleapis.com/v4/${account}/${location}/reviews`);\n    url.searchParams.set('pageSize', '50');\n    if (pageToken) url.searchParams.set('pageToken', pageToken);\n\n    const res = await fetchImpl(url, { headers: googleHeaders(auth) });\n    if (!res.ok) {\n      const message =\n        res.status === 403\n          ? `403 — this GCP project is most likely not allowlisted for the Business Profile API yet ` +\n            `(a one-time Google approval, requested separately from every other API here), or the ` +\n            `credential is not an owner/manager of ${account}/${location}`\n          : `${res.status}: ${await res.text()}`;\n      return { ok: false, reviews, status: res.status, message };\n    }\n\n    const body = (await res.json()) as {\n      reviews?: RawReview[];\n      averageRating?: number;\n      totalReviewCount?: number;\n      nextPageToken?: string;\n    };\n    for (const r of body.reviews ?? []) reviews.push(toReview(r, locationId));\n    averageRating = body.averageRating ?? averageRating;\n    totalReviewCount = body.totalReviewCount ?? totalReviewCount;\n    pageToken = body.nextPageToken;\n  } while (pageToken);\n\n  return {\n    ok: true,\n    reviews,\n    ...(averageRating !== undefined ? { averageRating } : {}),\n    ...(totalReviewCount !== undefined ? { totalReviewCount } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/schema/index.d.mts

@@ -0,0 +1,191 @@
+//#region src/schema/article.d.ts
+interface ArticleAuthor {
+  name: string;
+  url?: string;
+}
+interface ArticleGraphOptions {
+  headline: string;
+  description?: string;
+  image?: string | string[];
+  datePublished: string;
+  dateModified?: string;
+  author: ArticleAuthor | ArticleAuthor[];
+  publisher?: {
+    name: string;
+    logo?: string;
+  };
+  mainEntityOfPage?: string;
+  articleSection?: string;
+  wordCount?: number;
+  keywords?: string[];
+}
+/** Build a schema.org Article JSON-LD graph. */
+declare function articleGraph(options: ArticleGraphOptions): Record<string, unknown>;
+//#endregion
+//#region src/schema/breadcrumb.d.ts
+interface BreadcrumbItem {
+  name: string;
+  url: string;
+}
+interface BreadcrumbGraphOptions {
+  items: BreadcrumbItem[];
+}
+/** Build a schema.org BreadcrumbList JSON-LD graph. */
+declare function breadcrumbGraph(options: BreadcrumbGraphOptions): Record<string, unknown>;
+//#endregion
+//#region src/schema/faq.d.ts
+interface FAQItem {
+  question: string;
+  answer: string;
+}
+interface FAQGraphOptions {
+  items: FAQItem[];
+}
+/**
+ * Build a schema.org FAQPage JSON-LD graph.
+ *
+ * NOTE: Google recommends FAQ markup only for authoritative government
+ * and health sites. For other sites, consider using QAPage schema instead.
+ */
+declare function faqGraph(options: FAQGraphOptions): Record<string, unknown>;
+//#endregion
+//#region src/schema/itemList.d.ts
+type ItemListEntryType = 'Article' | 'Recipe' | 'Movie' | 'Course' | 'Restaurant' | 'Product' | (string & {});
+interface ItemListEntry {
+  type: ItemListEntryType;
+  name: string;
+  /**
+   * Summary-page format: the item's own detail page (unique, same domain).
+   * All-in-one-page format: this page's URL plus an HTML anchor pointing at
+   * the item on it.
+   */
+  url: string;
+  image?: string;
+  description?: string;
+}
+interface ItemListGraphOptions {
+  items: ItemListEntry[];
+  /** Recommended, not required by the spec — names the list itself. */
+  name?: string;
+}
+/** Build a schema.org ItemList JSON-LD graph (e.g. for a carousel rich result). */
+declare function itemListGraph(options: ItemListGraphOptions): Record<string, unknown>;
+//#endregion
+//#region src/schema/localBusiness.d.ts
+interface OpeningHoursSpecification {
+  dayOfWeek: ('Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday')[];
+  opens: string;
+  closes: string;
+}
+/**
+ * A dated deviation from the recurring `openingHoursSpecification` — holiday
+ * hours, a one-off closure, a temporary schedule. Same schema.org shape
+ * (`OpeningHoursSpecification`), distinguished by carrying `validFrom`. A full
+ * closure omits `opens`/`closes` rather than encoding it as an open interval.
+ */
+interface SpecialHoursSpecification {
+  validFrom: string;
+  validThrough?: string;
+  opens?: string;
+  closes?: string;
+}
+interface LocalBusinessGraphOptions {
+  /** schema.org `LocalBusiness` subtype, e.g. `'Restaurant'`, `'ProfessionalService'`. Defaults to `'LocalBusiness'`. */
+  type?: string;
+  name: string;
+  description?: string;
+  url?: string;
+  telephone?: string;
+  email?: string;
+  image?: string | string[];
+  priceRange?: string;
+  address?: {
+    streetAddress?: string;
+    addressLocality?: string;
+    addressRegion?: string;
+    postalCode?: string;
+    addressCountry?: string;
+  };
+  geo?: {
+    latitude: number;
+    longitude: number;
+  };
+  openingHoursSpecification?: OpeningHoursSpecification[];
+  specialOpeningHoursSpecification?: SpecialHoursSpecification[];
+  aggregateRating?: {
+    ratingValue: number;
+    reviewCount?: number;
+    ratingCount?: number;
+    bestRating?: number;
+    worstRating?: number;
+  };
+  review?: {
+    author: string;
+    datePublished: string;
+    reviewBody: string;
+    reviewRating?: {
+      ratingValue: number;
+      bestRating?: number;
+      worstRating?: number;
+    };
+  }[];
+  paymentAccepted?: string[];
+  currenciesAccepted?: string;
+  areaServed?: string[];
+  sameAs?: string[];
+  knowsLanguage?: string[];
+}
+/** Build a schema.org LocalBusiness (or subtype) JSON-LD graph. */
+declare function localBusinessGraph(options: LocalBusinessGraphOptions): Record<string, unknown>;
+//#endregion
+//#region src/schema/organization.d.ts
+interface OrganizationGraphOptions {
+  name: string;
+  url?: string;
+  logo?: string;
+  description?: string;
+  email?: string;
+  telephone?: string;
+  address?: {
+    streetAddress?: string;
+    addressLocality?: string;
+    addressRegion?: string;
+    postalCode?: string;
+    addressCountry?: string;
+  };
+  sameAs?: string[];
+  foundingDate?: string;
+  founders?: string[];
+  numberOfEmployees?: number | {
+    minValue: number;
+    maxValue: number;
+  };
+  parentOrganization?: {
+    name: string;
+    url?: string;
+  };
+  subOrganization?: {
+    name: string;
+    url?: string;
+  }[];
+  contactPoint?: {
+    type?: 'customer service' | 'technical support' | 'sales' | 'billing support' | 'reservations';
+    telephone: string;
+    email?: string;
+    contactType: string;
+    availableLanguage?: string[];
+    areaServed?: string[];
+  }[];
+  areaServed?: string[];
+  brand?: string;
+  award?: string[];
+  memberOf?: {
+    name: string;
+    url?: string;
+  }[];
+}
+/** Build a schema.org Organization JSON-LD graph. */
+declare function organizationGraph(options: OrganizationGraphOptions): Record<string, unknown>;
+//#endregion
+export { type ArticleAuthor, type ArticleGraphOptions, type BreadcrumbGraphOptions, type BreadcrumbItem, type FAQGraphOptions, type FAQItem, type ItemListEntry, type ItemListEntryType, type ItemListGraphOptions, type LocalBusinessGraphOptions, type OpeningHoursSpecification, type OrganizationGraphOptions, type SpecialHoursSpecification, articleGraph, breadcrumbGraph, faqGraph, itemListGraph, localBusinessGraph, organizationGraph };
+//# sourceMappingURL=index.d.mts.map

package/dist/schema/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/schema/article.ts","../../src/schema/breadcrumb.ts","../../src/schema/faq.ts","../../src/schema/itemList.ts","../../src/schema/localBusiness.ts","../../src/schema/organization.ts"],"mappings":";UAAiB,aAAA;EACf,IAAA;EACA,GAAG;AAAA;AAAA,UAGY,mBAAA;EACf,QAAA;EACA,WAAA;EACA,KAAA;EACA,aAAA;EACA,YAAA;EACA,MAAA,EAAQ,aAAA,GAAgB,aAAa;EACrC,SAAA;IACE,IAAA;IACA,IAAA;EAAA;EAEF,gBAAA;EACA,cAAA;EACA,SAAA;EACA,QAAA;AAAA;;iBAIc,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,MAAM;;;UCvBjD,cAAA;EACf,IAAA;EACA,GAAG;AAAA;AAAA,UAGY,sBAAA;EACf,KAAA,EAAO,cAAc;AAAA;;iBAIP,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,MAAM;;;UCVvD,OAAA;EACf,QAAA;EACA,MAAM;AAAA;AAAA,UAGS,eAAA;EACf,KAAA,EAAO,OAAO;AAAA;;;;;;;iBASA,QAAA,CAAS,OAAA,EAAS,eAAA,GAAkB,MAAM;;;KCf9C,iBAAA;AAAA,UAWK,aAAA;EACf,IAAA,EAAM,iBAAiB;EACvB,IAAA;EHZA;AACG;AAGL;;;EGcE,GAAA;EACA,KAAA;EACA,WAAA;AAAA;AAAA,UAGe,oBAAA;EACf,KAAA,EAAO,aAAa;EHdpB;EGgBA,IAAA;AAAA;;iBAIc,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,MAAM;;;UC/BnD,yBAAA;EACf,SAAA;EACA,KAAA;EACA,MAAA;AAAA;AJDG;AAGL;;;;;AAHK,UIUY,yBAAA;EACf,SAAA;EACA,YAAA;EACA,KAAA;EACA,MAAA;AAAA;AAAA,UAGe,yBAAA;EJPf;EISA,IAAA;EACA,IAAA;EACA,WAAA;EACA,GAAA;EACA,SAAA;EACA,KAAA;EACA,KAAA;EACA,UAAA;EACA,OAAA;IACE,aAAA;IACA,eAAA;IACA,aAAA;IACA,UAAA;IACA,cAAA;EAAA;EAEF,GAAA;IACE,QAAA;IACA,SAAA;EAAA;EAEF,yBAAA,GAA4B,yBAAA;EAC5B,gCAAA,GAAmC,yBAAyB;EAC5D,eAAA;IACE,WAAA;IACA,WAAA;IACA,WAAA;IACA,UAAA;IACA,WAAA;EAAA;EAEF,MAAA;IACE,MAAA;IACA,aAAA;IACA,UAAA;IACA,YAAA;MACE,WAAA;MACA,UAAA;MACA,WAAA;IAAA;EAAA;EAGJ,eAAA;EACA,kBAAA;EACA,UAAA;EACA,MAAA;EACA,aAAA;AAAA;;iBAIc,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,MAAM;;;UCnE7D,wBAAA;EACf,IAAA;EACA,GAAA;EACA,IAAA;EACA,WAAA;EACA,KAAA;EACA,SAAA;EACA,OAAA;IACE,aAAA;IACA,eAAA;IACA,aAAA;IACA,UAAA;IACA,cAAA;EAAA;EAEF,MAAA;EACA,YAAA;EACA,QAAA;EACA,iBAAA;IAA+B,QAAA;IAAkB,QAAA;EAAA;EACjD,kBAAA;IACE,IAAA;IACA,GAAA;EAAA;EAEF,eAAA;IACE,IAAA;IACA,GAAA;EAAA;EAEF,YAAA;IACE,IAAA;IACA,SAAA;IACA,KAAA;IACA,WAAA;IACA,iBAAA;IACA,UAAA;EAAA;EAEF,UAAA;EACA,KAAA;EACA,KAAA;EACA,QAAA;IACE,IAAA;IACA,GAAA;EAAA;AAAA;;iBAKY,iBAAA,CAAkB,OAAA,EAAS,wBAAA,GAA2B,MAAM"}