@getvitops/utils 6.0.0 → 8.0.0

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"}

package/dist/schema/index.mjs

@@ -0,0 +1,241 @@
+//#region src/schema/article.ts
+/** Build a schema.org Article JSON-LD graph. */
+function articleGraph(options) {
+	const { headline, description, image, datePublished, dateModified, author, publisher, mainEntityOfPage, articleSection, wordCount, keywords } = options;
+	const authors = Array.isArray(author) ? author : [author];
+	return {
+		"@context": "https://schema.org",
+		"@type": "Article",
+		headline,
+		...description && { description },
+		...image && { image: Array.isArray(image) ? image : [image] },
+		datePublished,
+		...dateModified && { dateModified },
+		author: authors.map((a) => ({
+			"@type": "Person",
+			name: a.name,
+			...a.url && { url: a.url }
+		})),
+		...publisher && { publisher: {
+			"@type": "Organization",
+			name: publisher.name,
+			...publisher.logo && { logo: {
+				"@type": "ImageObject",
+				url: publisher.logo
+			} }
+		} },
+		...mainEntityOfPage && { mainEntityOfPage: {
+			"@type": "WebPage",
+			"@id": mainEntityOfPage
+		} },
+		...articleSection && { articleSection },
+		...wordCount && { wordCount },
+		...keywords && { keywords: keywords.join(", ") }
+	};
+}
+
+//#endregion
+//#region src/schema/breadcrumb.ts
+/** Build a schema.org BreadcrumbList JSON-LD graph. */
+function breadcrumbGraph(options) {
+	return {
+		"@context": "https://schema.org",
+		"@type": "BreadcrumbList",
+		itemListElement: options.items.map((item, index) => ({
+			"@type": "ListItem",
+			position: index + 1,
+			name: item.name,
+			item: item.url
+		}))
+	};
+}
+
+//#endregion
+//#region src/schema/faq.ts
+/**
+* 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.
+*/
+function faqGraph(options) {
+	return {
+		"@context": "https://schema.org",
+		"@type": "FAQPage",
+		mainEntity: options.items.map((item) => ({
+			"@type": "Question",
+			name: item.question,
+			acceptedAnswer: {
+				"@type": "Answer",
+				text: item.answer
+			}
+		}))
+	};
+}
+
+//#endregion
+//#region src/schema/itemList.ts
+/** Build a schema.org ItemList JSON-LD graph (e.g. for a carousel rich result). */
+function itemListGraph(options) {
+	const { items, name } = options;
+	return {
+		"@context": "https://schema.org",
+		"@type": "ItemList",
+		...name && { name },
+		itemListElement: items.map((item, index) => ({
+			"@type": "ListItem",
+			position: index + 1,
+			item: {
+				"@type": item.type,
+				name: item.name,
+				url: item.url,
+				...item.image && { image: item.image },
+				...item.description && { description: item.description }
+			}
+		}))
+	};
+}
+
+//#endregion
+//#region src/schema/localBusiness.ts
+/** Build a schema.org LocalBusiness (or subtype) JSON-LD graph. */
+function localBusinessGraph(options) {
+	const { type = "LocalBusiness", name, description, url, telephone, email, image, priceRange, address, geo, openingHoursSpecification, specialOpeningHoursSpecification, aggregateRating, review, paymentAccepted, currenciesAccepted, areaServed, sameAs, knowsLanguage } = options;
+	const hours = [...(openingHoursSpecification ?? []).map((spec) => ({
+		"@type": "OpeningHoursSpecification",
+		dayOfWeek: spec.dayOfWeek,
+		opens: spec.opens,
+		closes: spec.closes
+	})), ...(specialOpeningHoursSpecification ?? []).map((spec) => ({
+		"@type": "OpeningHoursSpecification",
+		validFrom: spec.validFrom,
+		...spec.validThrough && { validThrough: spec.validThrough },
+		...spec.opens && { opens: spec.opens },
+		...spec.closes && { closes: spec.closes }
+	}))];
+	return {
+		"@context": "https://schema.org",
+		"@type": type,
+		name,
+		...description && { description },
+		...url && { url },
+		...telephone && { telephone },
+		...email && { email },
+		...image && { image: Array.isArray(image) ? image : [image] },
+		...priceRange && { priceRange },
+		...address && { address: {
+			"@type": "PostalAddress",
+			...address.streetAddress && { streetAddress: address.streetAddress },
+			...address.addressLocality && { addressLocality: address.addressLocality },
+			...address.addressRegion && { addressRegion: address.addressRegion },
+			...address.postalCode && { postalCode: address.postalCode },
+			...address.addressCountry && { addressCountry: address.addressCountry }
+		} },
+		...geo && { geo: {
+			"@type": "GeoCoordinates",
+			latitude: geo.latitude,
+			longitude: geo.longitude
+		} },
+		...hours.length > 0 && { openingHoursSpecification: hours },
+		...aggregateRating && { aggregateRating: {
+			"@type": "AggregateRating",
+			ratingValue: aggregateRating.ratingValue,
+			...aggregateRating.reviewCount && { reviewCount: aggregateRating.reviewCount },
+			...aggregateRating.ratingCount && { ratingCount: aggregateRating.ratingCount },
+			bestRating: aggregateRating.bestRating ?? 5,
+			worstRating: aggregateRating.worstRating ?? 1
+		} },
+		...review && { review: review.map((r) => ({
+			"@type": "Review",
+			author: {
+				"@type": "Person",
+				name: r.author
+			},
+			datePublished: r.datePublished,
+			reviewBody: r.reviewBody,
+			...r.reviewRating && { reviewRating: {
+				"@type": "Rating",
+				ratingValue: r.reviewRating.ratingValue,
+				bestRating: r.reviewRating.bestRating ?? 5,
+				worstRating: r.reviewRating.worstRating ?? 1
+			} }
+		})) },
+		...paymentAccepted && { paymentAccepted },
+		...currenciesAccepted && { currenciesAccepted },
+		...areaServed && { areaServed },
+		...sameAs && { sameAs },
+		...knowsLanguage && { knowsLanguage }
+	};
+}
+
+//#endregion
+//#region src/schema/organization.ts
+/** Build a schema.org Organization JSON-LD graph. */
+function organizationGraph(options) {
+	const { name, url, logo, description, email, telephone, address, sameAs, foundingDate, founders, numberOfEmployees, parentOrganization, subOrganization, contactPoint, areaServed, brand, award, memberOf } = options;
+	return {
+		"@context": "https://schema.org",
+		"@type": "Organization",
+		name,
+		...url && { url },
+		...logo && { logo },
+		...description && { description },
+		...email && { email },
+		...telephone && { telephone },
+		...address && { address: {
+			"@type": "PostalAddress",
+			...address.streetAddress && { streetAddress: address.streetAddress },
+			...address.addressLocality && { addressLocality: address.addressLocality },
+			...address.addressRegion && { addressRegion: address.addressRegion },
+			...address.postalCode && { postalCode: address.postalCode },
+			...address.addressCountry && { addressCountry: address.addressCountry }
+		} },
+		...sameAs && { sameAs },
+		...foundingDate && { foundingDate },
+		...founders && { founders: founders.map((f) => ({
+			"@type": "Person",
+			name: f
+		})) },
+		...numberOfEmployees && { numberOfEmployees: typeof numberOfEmployees === "number" ? {
+			"@type": "QuantitativeValue",
+			value: numberOfEmployees
+		} : {
+			"@type": "QuantitativeValue",
+			minValue: numberOfEmployees.minValue,
+			maxValue: numberOfEmployees.maxValue
+		} },
+		...parentOrganization && { parentOrganization: {
+			"@type": "Organization",
+			name: parentOrganization.name,
+			...parentOrganization.url && { url: parentOrganization.url }
+		} },
+		...subOrganization && { subOrganization: subOrganization.map((sub) => ({
+			"@type": "Organization",
+			name: sub.name,
+			...sub.url && { url: sub.url }
+		})) },
+		...contactPoint && { contactPoint: contactPoint.map((cp) => ({
+			"@type": "ContactPoint",
+			telephone: cp.telephone,
+			contactType: cp.contactType,
+			...cp.email && { email: cp.email },
+			...cp.availableLanguage && { availableLanguage: cp.availableLanguage },
+			...cp.areaServed && { areaServed: cp.areaServed }
+		})) },
+		...areaServed && { areaServed },
+		...brand && { brand: {
+			"@type": "Brand",
+			name: brand
+		} },
+		...award && { award },
+		...memberOf && { memberOf: memberOf.map((m) => ({
+			"@type": "Organization",
+			name: m.name,
+			...m.url && { url: m.url }
+		})) }
+	};
+}
+
+//#endregion
+export { articleGraph, breadcrumbGraph, faqGraph, itemListGraph, localBusinessGraph, organizationGraph };
+//# sourceMappingURL=index.mjs.map

package/dist/schema/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","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"],"sourcesContent":["export interface ArticleAuthor {\n  name: string;\n  url?: string;\n}\n\nexport interface ArticleGraphOptions {\n  headline: string;\n  description?: string;\n  image?: string | string[];\n  datePublished: string;\n  dateModified?: string;\n  author: ArticleAuthor | ArticleAuthor[];\n  publisher?: {\n    name: string;\n    logo?: string;\n  };\n  mainEntityOfPage?: string;\n  articleSection?: string;\n  wordCount?: number;\n  keywords?: string[];\n}\n\n/** Build a schema.org Article JSON-LD graph. */\nexport function articleGraph(options: ArticleGraphOptions): Record<string, unknown> {\n  const {\n    headline,\n    description,\n    image,\n    datePublished,\n    dateModified,\n    author,\n    publisher,\n    mainEntityOfPage,\n    articleSection,\n    wordCount,\n    keywords,\n  } = options;\n\n  const authors = Array.isArray(author) ? author : [author];\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'Article',\n    headline,\n    ...(description && { description }),\n    ...(image && { image: Array.isArray(image) ? image : [image] }),\n    datePublished,\n    ...(dateModified && { dateModified }),\n    author: authors.map((a) => ({\n      '@type': 'Person',\n      name: a.name,\n      ...(a.url && { url: a.url }),\n    })),\n    ...(publisher && {\n      publisher: {\n        '@type': 'Organization',\n        name: publisher.name,\n        ...(publisher.logo && { logo: { '@type': 'ImageObject', url: publisher.logo } }),\n      },\n    }),\n    ...(mainEntityOfPage && { mainEntityOfPage: { '@type': 'WebPage', '@id': mainEntityOfPage } }),\n    ...(articleSection && { articleSection }),\n    ...(wordCount && { wordCount }),\n    ...(keywords && { keywords: keywords.join(', ') }),\n  };\n}\n","export interface BreadcrumbItem {\n  name: string;\n  url: string;\n}\n\nexport interface BreadcrumbGraphOptions {\n  items: BreadcrumbItem[];\n}\n\n/** Build a schema.org BreadcrumbList JSON-LD graph. */\nexport function breadcrumbGraph(options: BreadcrumbGraphOptions): Record<string, unknown> {\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'BreadcrumbList',\n    itemListElement: options.items.map((item, index) => ({\n      '@type': 'ListItem',\n      position: index + 1,\n      name: item.name,\n      item: item.url,\n    })),\n  };\n}\n","export interface FAQItem {\n  question: string;\n  answer: string;\n}\n\nexport interface FAQGraphOptions {\n  items: FAQItem[];\n}\n\n/**\n * Build a schema.org FAQPage JSON-LD graph.\n *\n * NOTE: Google recommends FAQ markup only for authoritative government\n * and health sites. For other sites, consider using QAPage schema instead.\n */\nexport function faqGraph(options: FAQGraphOptions): Record<string, unknown> {\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'FAQPage',\n    mainEntity: options.items.map((item) => ({\n      '@type': 'Question',\n      name: item.question,\n      acceptedAnswer: {\n        '@type': 'Answer',\n        text: item.answer,\n      },\n    })),\n  };\n}\n","export type ItemListEntryType =\n  | 'Article'\n  | 'Recipe'\n  | 'Movie'\n  | 'Course'\n  | 'Restaurant'\n  | 'Product'\n  // Anything else is still valid ItemList markup, just not a Google\n  // carousel rich-result candidate — those six are the full supported set.\n  | (string & {});\n\nexport interface ItemListEntry {\n  type: ItemListEntryType;\n  name: string;\n  /**\n   * Summary-page format: the item's own detail page (unique, same domain).\n   * All-in-one-page format: this page's URL plus an HTML anchor pointing at\n   * the item on it.\n   */\n  url: string;\n  image?: string;\n  description?: string;\n}\n\nexport interface ItemListGraphOptions {\n  items: ItemListEntry[];\n  /** Recommended, not required by the spec — names the list itself. */\n  name?: string;\n}\n\n/** Build a schema.org ItemList JSON-LD graph (e.g. for a carousel rich result). */\nexport function itemListGraph(options: ItemListGraphOptions): Record<string, unknown> {\n  const { items, name } = options;\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'ItemList',\n    ...(name && { name }),\n    itemListElement: items.map((item, index) => ({\n      '@type': 'ListItem',\n      position: index + 1,\n      item: {\n        '@type': item.type,\n        name: item.name,\n        url: item.url,\n        ...(item.image && { image: item.image }),\n        ...(item.description && { description: item.description }),\n      },\n    })),\n  };\n}\n","export interface OpeningHoursSpecification {\n  dayOfWeek: ('Monday' | 'Tuesday' | 'Wednesday' | 'Thursday' | 'Friday' | 'Saturday' | 'Sunday')[];\n  opens: string;\n  closes: string;\n}\n\n/**\n * A dated deviation from the recurring `openingHoursSpecification` — holiday\n * hours, a one-off closure, a temporary schedule. Same schema.org shape\n * (`OpeningHoursSpecification`), distinguished by carrying `validFrom`. A full\n * closure omits `opens`/`closes` rather than encoding it as an open interval.\n */\nexport interface SpecialHoursSpecification {\n  validFrom: string;\n  validThrough?: string;\n  opens?: string;\n  closes?: string;\n}\n\nexport interface LocalBusinessGraphOptions {\n  /** schema.org `LocalBusiness` subtype, e.g. `'Restaurant'`, `'ProfessionalService'`. Defaults to `'LocalBusiness'`. */\n  type?: string;\n  name: string;\n  description?: string;\n  url?: string;\n  telephone?: string;\n  email?: string;\n  image?: string | string[];\n  priceRange?: string;\n  address?: {\n    streetAddress?: string;\n    addressLocality?: string;\n    addressRegion?: string;\n    postalCode?: string;\n    addressCountry?: string;\n  };\n  geo?: {\n    latitude: number;\n    longitude: number;\n  };\n  openingHoursSpecification?: OpeningHoursSpecification[];\n  specialOpeningHoursSpecification?: SpecialHoursSpecification[];\n  aggregateRating?: {\n    ratingValue: number;\n    reviewCount?: number;\n    ratingCount?: number;\n    bestRating?: number;\n    worstRating?: number;\n  };\n  review?: {\n    author: string;\n    datePublished: string;\n    reviewBody: string;\n    reviewRating?: {\n      ratingValue: number;\n      bestRating?: number;\n      worstRating?: number;\n    };\n  }[];\n  paymentAccepted?: string[];\n  currenciesAccepted?: string;\n  areaServed?: string[];\n  sameAs?: string[];\n  knowsLanguage?: string[];\n}\n\n/** Build a schema.org LocalBusiness (or subtype) JSON-LD graph. */\nexport function localBusinessGraph(options: LocalBusinessGraphOptions): Record<string, unknown> {\n  const {\n    type = 'LocalBusiness',\n    name,\n    description,\n    url,\n    telephone,\n    email,\n    image,\n    priceRange,\n    address,\n    geo,\n    openingHoursSpecification,\n    specialOpeningHoursSpecification,\n    aggregateRating,\n    review,\n    paymentAccepted,\n    currenciesAccepted,\n    areaServed,\n    sameAs,\n    knowsLanguage,\n  } = options;\n\n  const hours = [\n    ...(openingHoursSpecification ?? []).map((spec) => ({\n      '@type': 'OpeningHoursSpecification',\n      dayOfWeek: spec.dayOfWeek,\n      opens: spec.opens,\n      closes: spec.closes,\n    })),\n    ...(specialOpeningHoursSpecification ?? []).map((spec) => ({\n      '@type': 'OpeningHoursSpecification',\n      validFrom: spec.validFrom,\n      ...(spec.validThrough && { validThrough: spec.validThrough }),\n      ...(spec.opens && { opens: spec.opens }),\n      ...(spec.closes && { closes: spec.closes }),\n    })),\n  ];\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': type,\n    name,\n    ...(description && { description }),\n    ...(url && { url }),\n    ...(telephone && { telephone }),\n    ...(email && { email }),\n    ...(image && { image: Array.isArray(image) ? image : [image] }),\n    ...(priceRange && { priceRange }),\n    ...(address && {\n      address: {\n        '@type': 'PostalAddress',\n        ...(address.streetAddress && { streetAddress: address.streetAddress }),\n        ...(address.addressLocality && { addressLocality: address.addressLocality }),\n        ...(address.addressRegion && { addressRegion: address.addressRegion }),\n        ...(address.postalCode && { postalCode: address.postalCode }),\n        ...(address.addressCountry && { addressCountry: address.addressCountry }),\n      },\n    }),\n    ...(geo && {\n      geo: {\n        '@type': 'GeoCoordinates',\n        latitude: geo.latitude,\n        longitude: geo.longitude,\n      },\n    }),\n    ...(hours.length > 0 && { openingHoursSpecification: hours }),\n    ...(aggregateRating && {\n      aggregateRating: {\n        '@type': 'AggregateRating',\n        ratingValue: aggregateRating.ratingValue,\n        ...(aggregateRating.reviewCount && { reviewCount: aggregateRating.reviewCount }),\n        ...(aggregateRating.ratingCount && { ratingCount: aggregateRating.ratingCount }),\n        bestRating: aggregateRating.bestRating ?? 5,\n        worstRating: aggregateRating.worstRating ?? 1,\n      },\n    }),\n    ...(review && {\n      review: review.map((r) => ({\n        '@type': 'Review',\n        author: { '@type': 'Person', name: r.author },\n        datePublished: r.datePublished,\n        reviewBody: r.reviewBody,\n        ...(r.reviewRating && {\n          reviewRating: {\n            '@type': 'Rating',\n            ratingValue: r.reviewRating.ratingValue,\n            bestRating: r.reviewRating.bestRating ?? 5,\n            worstRating: r.reviewRating.worstRating ?? 1,\n          },\n        }),\n      })),\n    }),\n    ...(paymentAccepted && { paymentAccepted }),\n    ...(currenciesAccepted && { currenciesAccepted }),\n    ...(areaServed && { areaServed }),\n    ...(sameAs && { sameAs }),\n    ...(knowsLanguage && { knowsLanguage }),\n  };\n}\n","export interface OrganizationGraphOptions {\n  name: string;\n  url?: string;\n  logo?: string;\n  description?: string;\n  email?: string;\n  telephone?: string;\n  address?: {\n    streetAddress?: string;\n    addressLocality?: string;\n    addressRegion?: string;\n    postalCode?: string;\n    addressCountry?: string;\n  };\n  sameAs?: string[];\n  foundingDate?: string;\n  founders?: string[];\n  numberOfEmployees?: number | { minValue: number; maxValue: number };\n  parentOrganization?: {\n    name: string;\n    url?: string;\n  };\n  subOrganization?: {\n    name: string;\n    url?: string;\n  }[];\n  contactPoint?: {\n    type?: 'customer service' | 'technical support' | 'sales' | 'billing support' | 'reservations';\n    telephone: string;\n    email?: string;\n    contactType: string;\n    availableLanguage?: string[];\n    areaServed?: string[];\n  }[];\n  areaServed?: string[];\n  brand?: string;\n  award?: string[];\n  memberOf?: {\n    name: string;\n    url?: string;\n  }[];\n}\n\n/** Build a schema.org Organization JSON-LD graph. */\nexport function organizationGraph(options: OrganizationGraphOptions): Record<string, unknown> {\n  const {\n    name,\n    url,\n    logo,\n    description,\n    email,\n    telephone,\n    address,\n    sameAs,\n    foundingDate,\n    founders,\n    numberOfEmployees,\n    parentOrganization,\n    subOrganization,\n    contactPoint,\n    areaServed,\n    brand,\n    award,\n    memberOf,\n  } = options;\n\n  return {\n    '@context': 'https://schema.org',\n    '@type': 'Organization',\n    name,\n    ...(url && { url }),\n    ...(logo && { logo }),\n    ...(description && { description }),\n    ...(email && { email }),\n    ...(telephone && { telephone }),\n    ...(address && {\n      address: {\n        '@type': 'PostalAddress',\n        ...(address.streetAddress && { streetAddress: address.streetAddress }),\n        ...(address.addressLocality && { addressLocality: address.addressLocality }),\n        ...(address.addressRegion && { addressRegion: address.addressRegion }),\n        ...(address.postalCode && { postalCode: address.postalCode }),\n        ...(address.addressCountry && { addressCountry: address.addressCountry }),\n      },\n    }),\n    ...(sameAs && { sameAs }),\n    ...(foundingDate && { foundingDate }),\n    ...(founders && {\n      founders: founders.map((f) => ({\n        '@type': 'Person',\n        name: f,\n      })),\n    }),\n    ...(numberOfEmployees && {\n      numberOfEmployees:\n        typeof numberOfEmployees === 'number'\n          ? { '@type': 'QuantitativeValue', value: numberOfEmployees }\n          : {\n              '@type': 'QuantitativeValue',\n              minValue: numberOfEmployees.minValue,\n              maxValue: numberOfEmployees.maxValue,\n            },\n    }),\n    ...(parentOrganization && {\n      parentOrganization: {\n        '@type': 'Organization',\n        name: parentOrganization.name,\n        ...(parentOrganization.url && { url: parentOrganization.url }),\n      },\n    }),\n    ...(subOrganization && {\n      subOrganization: subOrganization.map((sub) => ({\n        '@type': 'Organization',\n        name: sub.name,\n        ...(sub.url && { url: sub.url }),\n      })),\n    }),\n    ...(contactPoint && {\n      contactPoint: contactPoint.map((cp) => ({\n        '@type': 'ContactPoint',\n        telephone: cp.telephone,\n        contactType: cp.contactType,\n        ...(cp.email && { email: cp.email }),\n        ...(cp.availableLanguage && { availableLanguage: cp.availableLanguage }),\n        ...(cp.areaServed && { areaServed: cp.areaServed }),\n      })),\n    }),\n    ...(areaServed && { areaServed }),\n    ...(brand && { brand: { '@type': 'Brand', name: brand } }),\n    ...(award && { award }),\n    ...(memberOf && {\n      memberOf: memberOf.map((m) => ({\n        '@type': 'Organization',\n        name: m.name,\n        ...(m.url && { url: m.url }),\n      })),\n    }),\n  };\n}\n"],"mappings":"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"}

package/dist/security/index.d.mts

@@ -0,0 +1,48 @@
+//#region src/security/turnstile.d.ts
+/**
+ * Cloudflare Turnstile server-side verification.
+ *
+ * `site.security.turnstile.siteKey` is public and lives in the config; the
+ * matching **secret** key never does — same rule as every other credential in
+ * this toolchain (`CLOUDFLARE_API_TOKEN`, the Google OAuth/service-account
+ * grants) and the same reason: an env var, injected by the caller, never
+ * imported here. Before this module existed, `siteKey` was read by the legal
+ * templates (`legal/providers.ts`, `legal/derive.ts`) to *name* Turnstile in the
+ * generated privacy policy, with nothing in the toolchain that verified a token
+ * — a config field asserting a fact the site didn't actually implement, which is
+ * exactly what the legal system's own rule ("the config records facts; the
+ * template owns prose") argues against. `verifyTurnstileToken` plus
+ * `createConversionRoute()`'s `turnstile` option (`@getvitops/astro/routes`) is
+ * what lets that field describe something real.
+ *
+ * A separate `@getvitops/utils/security` subpath for the same reason
+ * `notify`/`tracking` are: this runs in a **Worker**, on every submission, and
+ * must not pull in anything build-time.
+ *
+ * The widget itself — `<script src="https://challenges.cloudflare.com/turnstile/
+ * v0/api.js" async defer></script>` plus a `<div class="cf-turnstile"
+ * data-sitekey="…">` — is the consumer's own markup, on their own hand-written
+ * form. There is no `FormRenderer` (removed 2026-07-27, see `AGENTS.md`) for this
+ * to hook into generically, so wiring the widget follows the same pattern a
+ * consumer already uses for the rest of their form: write the HTML, submit it to
+ * `createConversionRoute()`.
+ */
+interface TurnstileVerifyResult {
+  success: boolean;
+  /** Cloudflare's own codes (e.g. `timeout-or-duplicate`), present iff not successful. */
+  errorCodes?: string[];
+}
+/**
+ * Verify a submitted `cf-turnstile-response` token against Cloudflare's
+ * siteverify endpoint.
+ *
+ * Never throws — a network failure or a malformed response both come back as
+ * `{ success: false }` with an error code the caller can log, the same
+ * "structured result, not an exception" rule `indexing`/`notify` follow. A
+ * failed verification is not this module's business to act on; the caller
+ * (`createConversionRoute`) decides what a failure means for the request.
+ */
+declare function verifyTurnstileToken(token: string, secretKey: string, remoteIp?: string, fetchImpl?: typeof fetch): Promise<TurnstileVerifyResult>;
+//#endregion
+export { type TurnstileVerifyResult, verifyTurnstileToken };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/security/turnstile.ts"],"mappings":";;AA+BA;;;;AAGY;AAaZ;;;;;;;;;;;;;;;;AAKgC;;;;;;UArBf,qBAAA;EACf,OAAA;;EAEA,UAAU;AAAA;;;;;;;;;;;iBAaU,oBAAA,CACpB,KAAA,UACA,SAAA,UACA,QAAA,WACA,SAAA,UAAkB,KAAA,GACjB,OAAA,CAAQ,qBAAA"}

package/dist/security/index.mjs

@@ -0,0 +1,80 @@
+//#region src/security/turnstile.ts
+/**
+* Cloudflare Turnstile server-side verification.
+*
+* `site.security.turnstile.siteKey` is public and lives in the config; the
+* matching **secret** key never does — same rule as every other credential in
+* this toolchain (`CLOUDFLARE_API_TOKEN`, the Google OAuth/service-account
+* grants) and the same reason: an env var, injected by the caller, never
+* imported here. Before this module existed, `siteKey` was read by the legal
+* templates (`legal/providers.ts`, `legal/derive.ts`) to *name* Turnstile in the
+* generated privacy policy, with nothing in the toolchain that verified a token
+* — a config field asserting a fact the site didn't actually implement, which is
+* exactly what the legal system's own rule ("the config records facts; the
+* template owns prose") argues against. `verifyTurnstileToken` plus
+* `createConversionRoute()`'s `turnstile` option (`@getvitops/astro/routes`) is
+* what lets that field describe something real.
+*
+* A separate `@getvitops/utils/security` subpath for the same reason
+* `notify`/`tracking` are: this runs in a **Worker**, on every submission, and
+* must not pull in anything build-time.
+*
+* The widget itself — `<script src="https://challenges.cloudflare.com/turnstile/
+* v0/api.js" async defer><\/script>` plus a `<div class="cf-turnstile"
+* data-sitekey="…">` — is the consumer's own markup, on their own hand-written
+* form. There is no `FormRenderer` (removed 2026-07-27, see `AGENTS.md`) for this
+* to hook into generically, so wiring the widget follows the same pattern a
+* consumer already uses for the rest of their form: write the HTML, submit it to
+* `createConversionRoute()`.
+*/
+const VERIFY_ENDPOINT = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+/**
+* Verify a submitted `cf-turnstile-response` token against Cloudflare's
+* siteverify endpoint.
+*
+* Never throws — a network failure or a malformed response both come back as
+* `{ success: false }` with an error code the caller can log, the same
+* "structured result, not an exception" rule `indexing`/`notify` follow. A
+* failed verification is not this module's business to act on; the caller
+* (`createConversionRoute`) decides what a failure means for the request.
+*/
+async function verifyTurnstileToken(token, secretKey, remoteIp, fetchImpl = fetch) {
+	const body = new URLSearchParams({
+		secret: secretKey,
+		response: token
+	});
+	if (remoteIp) body.set("remoteip", remoteIp);
+	let res;
+	try {
+		res = await fetchImpl(VERIFY_ENDPOINT, {
+			method: "POST",
+			body
+		});
+	} catch (e) {
+		return {
+			success: false,
+			errorCodes: [`network-error: ${e.message}`]
+		};
+	}
+	if (!res.ok) return {
+		success: false,
+		errorCodes: [`http-${res.status}`]
+	};
+	let data;
+	try {
+		data = await res.json();
+	} catch {
+		return {
+			success: false,
+			errorCodes: ["malformed-response"]
+		};
+	}
+	return data.success === true ? { success: true } : {
+		success: false,
+		errorCodes: data["error-codes"] ?? ["unknown-error"]
+	};
+}
+
+//#endregion
+export { verifyTurnstileToken };
+//# sourceMappingURL=index.mjs.map