@questpackages/tours 0.1.0-test.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `@questpackages/tours`. Versions follow semver. Pre-releases
+(`x.y.z-test.n`) are published on the `test` dist-tag; stable releases on `latest`.
+
+## [0.1.0-test.0] - 2026-09-28
+
+### Added
+- Public API v1 client: `createQuestTours()` with `getTours`, `getTour`, `getTags`.
+- Zod schemas and types for the Quest tours contract (`@questpackages/tours/schema`).
+- React components: `TourGrid`, `TourCard`, `TourDetail` and per-section components.
+- Styled defaults scoped under `.quest-tours`, themeable with `--quest-*` variables.
+- Enquiry form posting to Quest; party-size pricing; gallery lightbox.
+- Next.js helpers: `createRevalidateHandler`, `tourMetadata`, `tourSitemapEntries`, `TourJsonLd`.
+- CLI: `quest-tours init` and `quest-tours doctor`.

package/README.md

@@ -0,0 +1,122 @@
+# @questpackages/tours
+
+Show your Quest tour packages on your own Next.js website, with styled tour cards and
+tour detail pages out of the box. Tours are edited in Quest; your site updates within
+seconds of every change.
+
+- Server-rendered on your domain (good for SEO), with metadata and JSON-LD built by Quest
+- Only renders what Quest models: every field is typed, empty sections render nothing
+- Themeable with CSS variables, section-by-section overrides when you need more
+- Enquiry form sends leads straight into Quest
+
+Requires Next.js 15+ (App Router) and React 19.
+
+## Quick start
+
+1. In Quest, open **Packages > Website embeds > Coded website** and copy your **site token**
+   and **webhook secret**. Add your site's origin (e.g. `https://www.example.com`) to
+   **allowed origins**.
+2. In your Next.js project:
+
+```bash
+npm install @questpackages/tours
+npx @questpackages/tours init \
+  --site-token <site token> \
+  --origin https://app.questheaven.com \
+  --site-url https://www.example.com \
+  --webhook-secret <webhook secret>
+```
+
+`init` adds the env vars to `.env.local` and creates (never overwrites):
+
+| File | Purpose |
+|------|---------|
+| `lib/quest.ts` | Shared Quest client |
+| `app/tours/page.tsx` | Tour list (`--route` changes `tours`) |
+| `app/tours/[slug]/page.tsx` | Tour detail with metadata and JSON-LD |
+| `app/api/quest/revalidate/route.ts` | Quest calls this when a package changes |
+| `AGENTS.md` | Notes for AI coding agents working on your site |
+
+3. In Quest, set the **revalidate URL** to `https://www.example.com/api/quest/revalidate`.
+4. Add the same env vars to your host (e.g. Vercel), deploy, then run:
+
+```bash
+npx @questpackages/tours doctor
+```
+
+## Environment variables
+
+| Name | Required | Example |
+|------|----------|---------|
+| `QUEST_SITE_TOKEN` | yes | from Quest Website embeds |
+| `QUEST_ORIGIN` | yes | `https://app.questheaven.com` |
+| `QUEST_SITE_URL` | recommended | `https://www.example.com` (canonical URLs and JSON-LD) |
+| `QUEST_WEBHOOK_SECRET` | recommended | from Quest Website embeds (instant updates) |
+
+Without the webhook, pages refresh every 5 minutes.
+
+## Usage
+
+```tsx
+import Link from "next/link";
+import { createQuestTours } from "@questpackages/tours/server";
+import { TourGrid } from "@questpackages/tours/react";
+import "@questpackages/tours/styles.css";
+
+const quest = createQuestTours();
+
+export default async function GorillaTours() {
+  const tours = await quest.getTours({ tag: "gorilla-trekking" });
+  return <TourGrid tours={tours} hrefBase="/tours" LinkComponent={Link} />;
+}
+```
+
+### Data
+
+| Call | Returns |
+|------|---------|
+| `quest.getTours({ tag?, featured? })` | `TourCard[]` (all pages) |
+| `quest.getTour(slug, { url? })` | `{ tour, seo }` or `null` |
+| `quest.getTags()` | `{ slug, label, count }[]` |
+
+Types live in `@questpackages/tours/schema` (`Tour`, `TourCard`, `TourDay`, ...).
+
+### Theming
+
+```css
+.quest-tours {
+  --quest-primary: #7a4b2a;
+  --quest-primary-contrast: #fff;
+  --quest-accent: #f5ece4;
+  --quest-font-heading: "Cormorant Garamond", serif;
+  --quest-font-body: "Inter", sans-serif;
+  --quest-radius: 6px;
+}
+```
+
+All variables are listed at the top of `@questpackages/tours/styles.css`.
+
+### Replacing or hiding sections
+
+```tsx
+import { TourDetail, TourSection, type TourSectionProps } from "@questpackages/tours/react";
+
+function MyItinerary({ tour }: TourSectionProps) {
+  return (
+    <TourSection id="quest-itinerary" title="Your journey">
+      {tour.days.map((day) => <p key={day.dayLabel}>{day.title}</p>)}
+    </TourSection>
+  );
+}
+
+<TourDetail tour={tour} components={{ Itinerary: MyItinerary }} hide={["PaymentTerms"]} />;
+```
+
+Sections: `Hero`, `Overview`, `Highlights`, `Itinerary`, `Accommodation`, `Vehicle`, `Gallery`,
+`Inclusions`, `PaymentTerms`, `Pricing`, `Enquiry`, `Related`. Overrides render on the server;
+to use a client component, wrap it and pass only `tour`.
+
+## Versions
+
+- `latest`: production releases.
+- `test`: pre-releases for Quest's test environments (`npm install @questpackages/tours@test`).

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { agentsSectionTemplate, detailPageTemplate, listPageTemplate, questModuleTemplate, revalidateRouteTemplate, } from "./templates.js";
+const USAGE = `Usage:
+  npx @questpackages/tours init [--site-token <token>] [--origin <quest url>] [--site-url <your site url>]
+                                [--webhook-secret <secret>] [--route tours] [--skip-agents-md]
+  npx @questpackages/tours doctor
+
+Find the site token and webhook secret in Quest: Packages > Website embeds > Coded website.`;
+function parseFlags(args) {
+    const flags = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? "";
+        if (!arg.startsWith("--"))
+            continue;
+        const [key, inline] = arg.slice(2).split("=", 2);
+        if (!key)
+            continue;
+        const next = args[index + 1];
+        const hasValue = inline === undefined && next !== undefined && !next.startsWith("--");
+        flags[key] = inline ?? (hasValue ? next : "");
+        if (hasValue)
+            index += 1;
+    }
+    return flags;
+}
+function readEnvFile(path) {
+    if (!existsSync(path))
+        return {};
+    const env = {};
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+        const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+        if (!match?.[1])
+            continue;
+        env[match[1]] = (match[2] ?? "").replace(/^["']|["']$/g, "");
+    }
+    return env;
+}
+function projectEnv(cwd) {
+    return { ...readEnvFile(join(cwd, ".env")), ...readEnvFile(join(cwd, ".env.local")), ...process.env };
+}
+function importPath(fromFile, toFileWithoutExt) {
+    const path = relative(dirname(fromFile), toFileWithoutExt).split("\\").join("/");
+    return path.startsWith(".") ? path : `./${path}`;
+}
+function writeIfMissing(cwd, path, content) {
+    const label = relative(cwd, path);
+    if (existsSync(path)) {
+        console.log(`  skip    ${label} (already exists)`);
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    console.log(`  create  ${label}`);
+}
+async function ask(question, fallback) {
+    if (fallback)
+        return fallback;
+    if (!process.stdin.isTTY)
+        return undefined;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question(`${question}: `)).trim();
+    rl.close();
+    return answer || undefined;
+}
+async function init(cwd, flags) {
+    const packageJsonPath = join(cwd, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        console.error("Run this in the root of your Next.js project (no package.json found).");
+        return 1;
+    }
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (!pkg.dependencies?.next && !pkg.devDependencies?.next) {
+        console.error("This project does not use Next.js. The Quest tours SDK supports Next.js App Router.");
+        return 1;
+    }
+    const srcDir = existsSync(join(cwd, "src", "app")) ? join(cwd, "src") : cwd;
+    const appDir = join(srcDir, "app");
+    if (!existsSync(appDir)) {
+        console.error("No app/ directory found. The Quest tours SDK supports Next.js App Router.");
+        return 1;
+    }
+    const env = projectEnv(cwd);
+    const route = (flags.route ?? "tours").replace(/^\/+|\/+$/g, "");
+    const siteToken = await ask("Quest site token", flags["site-token"] ?? env.QUEST_SITE_TOKEN);
+    const origin = await ask("Quest origin (e.g. https://app.questheaven.com)", flags.origin ?? env.QUEST_ORIGIN);
+    const siteUrl = await ask("Your public site URL (e.g. https://www.example.com)", flags["site-url"] ?? env.QUEST_SITE_URL);
+    const webhookSecret = flags["webhook-secret"] ?? env.QUEST_WEBHOOK_SECRET;
+    if (!siteToken || !origin) {
+        console.error(`Missing --site-token or --origin.\n\n${USAGE}`);
+        return 1;
+    }
+    console.log("\nSetting up Quest tours:\n");
+    const envPath = join(cwd, ".env.local");
+    const existing = readEnvFile(envPath);
+    const additions = Object.entries({
+        QUEST_SITE_TOKEN: siteToken,
+        QUEST_ORIGIN: origin.replace(/\/+$/, ""),
+        QUEST_SITE_URL: siteUrl?.replace(/\/+$/, ""),
+        QUEST_WEBHOOK_SECRET: webhookSecret,
+    }).filter((entry) => Boolean(entry[1]) && !(entry[0] in existing));
+    if (additions.length > 0) {
+        appendFileSync(envPath, `\n# Quest tours\n${additions.map(([key, value]) => `${key}=${value}`).join("\n")}\n`);
+        console.log(`  update  .env.local (${additions.map(([key]) => key).join(", ")})`);
+    }
+    const questModule = join(srcDir, "lib", "quest.ts");
+    const listPage = join(appDir, route, "page.tsx");
+    const detailPage = join(appDir, route, "[slug]", "page.tsx");
+    const questModuleImport = questModule.replace(/\.ts$/, "");
+    writeIfMissing(cwd, questModule, questModuleTemplate(route));
+    writeIfMissing(cwd, listPage, listPageTemplate({
+        route,
+        questImportFromList: importPath(listPage, questModuleImport),
+        questImportFromDetail: importPath(detailPage, questModuleImport),
+    }));
+    writeIfMissing(cwd, detailPage, detailPageTemplate({
+        route,
+        questImportFromList: importPath(listPage, questModuleImport),
+        questImportFromDetail: importPath(detailPage, questModuleImport),
+    }));
+    writeIfMissing(cwd, join(appDir, "api", "quest", "revalidate", "route.ts"), revalidateRouteTemplate);
+    if (flags["skip-agents-md"] === undefined) {
+        // Repos spell it AGENTS.md, Agents.md or agents.md; reuse whichever exists.
+        const agentsFile = readdirSync(cwd).find((name) => name.toLowerCase() === "agents.md") ?? "AGENTS.md";
+        const agentsPath = join(cwd, agentsFile);
+        const agentsContent = existsSync(agentsPath) ? readFileSync(agentsPath, "utf8") : "";
+        if (!agentsContent.includes("@questpackages/tours")) {
+            appendFileSync(agentsPath, agentsSectionTemplate(route));
+            console.log(`  update  ${agentsFile} (Quest tours section)`);
+        }
+    }
+    console.log(`
+Next steps:
+  1. In Quest > Packages > Website embeds, add ${siteUrl ?? "your site origin"} to allowed origins
+     (needed for the enquiry form).
+  2. In Quest, set the revalidate URL to ${siteUrl ? `${siteUrl.replace(/\/+$/, "")}/api/quest/revalidate` : "<your site>/api/quest/revalidate"}
+     and copy the webhook secret into QUEST_WEBHOOK_SECRET${webhookSecret ? " (done)" : ""}.
+  3. Add the same env vars to your hosting provider (e.g. Vercel project settings).
+  4. Run: npx @questpackages/tours doctor
+`);
+    return 0;
+}
+async function check(label, run) {
+    try {
+        console.log(`  ok    ${label}: ${await run()}`);
+        return true;
+    }
+    catch (error) {
+        console.log(`  FAIL  ${label}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+async function doctor(cwd) {
+    const env = projectEnv(cwd);
+    const origin = env.QUEST_ORIGIN?.replace(/\/+$/, "");
+    const siteToken = env.QUEST_SITE_TOKEN;
+    const siteUrl = env.QUEST_SITE_URL?.replace(/\/+$/, "");
+    const results = [];
+    console.log("\nChecking Quest tours setup:\n");
+    results.push(await check("QUEST_SITE_TOKEN", async () => {
+        if (!siteToken)
+            throw new Error("not set");
+        return "set";
+    }), await check("QUEST_ORIGIN", async () => {
+        if (!origin)
+            throw new Error("not set");
+        return origin;
+    }), await check("QUEST_WEBHOOK_SECRET", async () => {
+        if (!env.QUEST_WEBHOOK_SECRET)
+            throw new Error("not set. Tour pages will only refresh every 5 minutes");
+        return "set";
+    }));
+    if (origin && siteToken) {
+        const base = `${origin}/api/public/v1/sites/${encodeURIComponent(siteToken)}`;
+        results.push(await check("Quest API", async () => {
+            const response = await fetch(`${base}/tours?limit=24`);
+            const body = (await response.json().catch(() => null));
+            if (!response.ok)
+                throw new Error(body?.error?.message ?? `HTTP ${response.status}`);
+            if (body?.apiVersion !== 1)
+                throw new Error(`unexpected API version ${body?.apiVersion}`);
+            return `${body.data?.totalCount ?? 0} published tours`;
+        }));
+    }
+    if (siteUrl) {
+        results.push(await check("Revalidate endpoint", async () => {
+            const response = await fetch(`${siteUrl}/api/quest/revalidate`, { method: "POST", body: "{}" });
+            if (response.status === 401)
+                return "reachable and rejecting unsigned requests";
+            if (response.status === 404)
+                throw new Error("not found. Deploy app/api/quest/revalidate/route.ts");
+            if (response.status === 500)
+                throw new Error("QUEST_WEBHOOK_SECRET is not set on the deployed site");
+            throw new Error(`unexpected HTTP ${response.status}`);
+        }));
+    }
+    else {
+        console.log("  skip  Revalidate endpoint: set QUEST_SITE_URL to check the deployed site");
+    }
+    const failed = results.filter((ok) => !ok).length;
+    console.log(failed === 0 ? "\nAll checks passed.\n" : `\n${failed} check(s) failed.\n`);
+    return failed === 0 ? 0 : 1;
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const cwd = process.cwd();
+    if (command === "init")
+        return init(cwd, parseFlags(rest));
+    if (command === "doctor")
+        return doctor(cwd);
+    console.log(USAGE);
+    return command ? 1 : 0;
+}
+main().then((code) => process.exit(code), (error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/cli/templates.d.ts

@@ -0,0 +1,12 @@
+export type TemplateInput = {
+    /** URL path segment for tour pages, e.g. "tours" -> /tours and /tours/<slug>. */
+    route: string;
+    /** Import specifier for the generated quest module from each file. */
+    questImportFromList: string;
+    questImportFromDetail: string;
+};
+export declare function questModuleTemplate(route: string): string;
+export declare function listPageTemplate(input: TemplateInput): string;
+export declare function detailPageTemplate(input: TemplateInput): string;
+export declare const revalidateRouteTemplate = "import { createRevalidateHandler } from \"@questpackages/tours/next\";\n\n// Quest calls this endpoint when a tour package changes, so tour pages refresh within seconds.\nexport const { POST } = createRevalidateHandler();\n";
+export declare function agentsSectionTemplate(route: string): string;

package/dist/cli/templates.js

@@ -0,0 +1,100 @@
+export function questModuleTemplate(route) {
+    return `import { createQuestTours } from "@questpackages/tours/server";
+
+/** Quest tours client. Reads QUEST_SITE_TOKEN and QUEST_ORIGIN from the environment. */
+export const quest = createQuestTours();
+
+/** Base path of the tour pages on this site. */
+export const TOURS_PATH = "/${route}";
+
+/** Absolute public URL of a tour page, used by Quest to build canonical URLs and JSON-LD. */
+export function tourUrl(slug: string): string | undefined {
+  const siteUrl = process.env.QUEST_SITE_URL?.replace(/\\/+$/, "");
+  return siteUrl ? \`\${siteUrl}\${TOURS_PATH}/\${slug}\` : undefined;
+}
+`;
+}
+export function listPageTemplate(input) {
+    return `import type { Metadata } from "next";
+import Link from "next/link";
+import { TourGrid } from "@questpackages/tours/react";
+import "@questpackages/tours/styles.css";
+import { quest, TOURS_PATH } from "${input.questImportFromList}";
+
+export const metadata: Metadata = {
+  title: "Tours",
+  description: "Browse our tours and safaris.",
+};
+
+export default async function ToursPage() {
+  const tours = await quest.getTours();
+
+  return (
+    <main style={{ maxWidth: "80rem", margin: "0 auto", padding: "2.5rem 1rem" }}>
+      <h1 style={{ marginBottom: "2rem" }}>Our tours</h1>
+      <TourGrid tours={tours} hrefBase={TOURS_PATH} LinkComponent={Link} />
+    </main>
+  );
+}
+`;
+}
+export function detailPageTemplate(input) {
+    return `import { notFound } from "next/navigation";
+import Link from "next/link";
+import { tourMetadata } from "@questpackages/tours/next";
+import { TourDetail, TourJsonLd } from "@questpackages/tours/react";
+import "@questpackages/tours/styles.css";
+import { quest, TOURS_PATH, tourUrl } from "${input.questImportFromDetail}";
+
+type TourPageProps = { params: Promise<{ slug: string }> };
+
+// Pre-render known tours at build time. New tours render on first visit.
+export async function generateStaticParams() {
+  const tours = await quest.getTours().catch(() => []);
+  return tours.map((tour) => ({ slug: tour.slug }));
+}
+
+export async function generateMetadata({ params }: TourPageProps) {
+  const { slug } = await params;
+  const result = await quest.getTour(slug, { url: tourUrl(slug) });
+  return result ? tourMetadata(result) : {};
+}
+
+export default async function TourPage({ params }: TourPageProps) {
+  const { slug } = await params;
+  const result = await quest.getTour(slug, { url: tourUrl(slug) });
+  if (!result) notFound();
+
+  return (
+    <main style={{ maxWidth: "80rem", margin: "0 auto", padding: "1.5rem 1rem 4rem" }}>
+      <TourJsonLd seo={result.seo} />
+      <TourDetail tour={result.tour} hrefBase={TOURS_PATH} LinkComponent={Link} />
+    </main>
+  );
+}
+`;
+}
+export const revalidateRouteTemplate = `import { createRevalidateHandler } from "@questpackages/tours/next";
+
+// Quest calls this endpoint when a tour package changes, so tour pages refresh within seconds.
+export const { POST } = createRevalidateHandler();
+`;
+export function agentsSectionTemplate(route) {
+    return `
+## Quest tours (@questpackages/tours)
+
+Tour cards and tour detail pages on this site come from Quest (the operator's tour
+package system) through \`@questpackages/tours\`. Tours are edited in Quest, not in this repo.
+
+- Pages: \`/${route}\` (list) and \`/${route}/[slug]\` (detail). Shared client in the generated \`quest\` module.
+- Env vars: \`QUEST_SITE_TOKEN\`, \`QUEST_ORIGIN\`, \`QUEST_SITE_URL\`, \`QUEST_WEBHOOK_SECRET\`.
+- Content model: only render fields that exist on the SDK types (\`Tour\`, \`TourCard\` from
+  \`@questpackages/tours/schema\`). Do not add tour sections Quest does not provide (for example
+  "What to pack" or FAQs); they cannot be filled from Quest data.
+- Styling: override \`--quest-*\` CSS variables on \`.quest-tours\`, or replace a section with
+  \`<TourDetail components={{ Itinerary: MyItinerary }} />\`. Hide one with \`hide={["PaymentTerms"]}\`.
+- Freshness: Quest POSTs to \`/api/quest/revalidate\` on every package change. Keep that route.
+- Enquiries post from the browser to Quest. This site's origin must be in Quest Website embeds allowed origins.
+- Check the setup: \`npx @questpackages/tours doctor\`.
+`;
+}

package/dist/next/index.d.ts

@@ -0,0 +1,4 @@
+import "server-only";
+export { createRevalidateHandler, type RevalidateHandlerOptions } from "./revalidate-handler.js";
+export { tourMetadata, tourSitemapEntries } from "./metadata.js";
+export { QUEST_SIGNATURE_HEADER, verifyQuestSignature } from "./signature.js";

package/dist/next/index.js

@@ -0,0 +1,4 @@
+import "server-only";
+export { createRevalidateHandler } from "./revalidate-handler.js";
+export { tourMetadata, tourSitemapEntries } from "./metadata.js";
+export { QUEST_SIGNATURE_HEADER, verifyQuestSignature } from "./signature.js";

package/dist/next/metadata.d.ts

@@ -0,0 +1,26 @@
+import type { Metadata, MetadataRoute } from "next";
+import type { TourCard } from "../schema/index.js";
+import type { TourWithSeo } from "../server/client.js";
+/**
+ * Next.js metadata for a tour detail page. Uses the SEO Quest built for this page URL
+ * (pass `url` to `getTour`), falling back to the tour content.
+ *
+ * ```ts
+ * export async function generateMetadata({ params }) {
+ *   const result = await quest.getTour(slug, { url });
+ *   return result ? tourMetadata(result) : {};
+ * }
+ * ```
+ */
+export declare function tourMetadata({ tour, seo }: TourWithSeo): Metadata;
+/**
+ * Sitemap entries for Quest tours, for `app/sitemap.ts`.
+ *
+ * ```ts
+ * tourSitemapEntries(await quest.getTours(), { baseUrl: "https://example.com", path: (slug) => `/tours/${slug}` })
+ * ```
+ */
+export declare function tourSitemapEntries(tours: TourCard[], options: {
+    baseUrl: string;
+    path: (slug: string) => string;
+}): MetadataRoute.Sitemap;

package/dist/next/metadata.js

@@ -0,0 +1,58 @@
+const META_DESCRIPTION_MAX = 160;
+function truncate(text, max) {
+    const clean = text.replace(/\s+/g, " ").trim();
+    if (clean.length <= max)
+        return clean;
+    const cut = clean.slice(0, max - 1);
+    return `${cut.slice(0, Math.max(cut.lastIndexOf(" "), max - 20)).trimEnd()}…`;
+}
+/**
+ * Next.js metadata for a tour detail page. Uses the SEO Quest built for this page URL
+ * (pass `url` to `getTour`), falling back to the tour content.
+ *
+ * ```ts
+ * export async function generateMetadata({ params }) {
+ *   const result = await quest.getTour(slug, { url });
+ *   return result ? tourMetadata(result) : {};
+ * }
+ * ```
+ */
+export function tourMetadata({ tour, seo }) {
+    const title = seo?.title ?? `${tour.title} | ${tour.durationLabel} by ${tour.operator.name}`;
+    const description = truncate(seo?.description ?? tour.summary ?? tour.overview[0] ?? tour.title, META_DESCRIPTION_MAX);
+    const image = seo?.ogImage ?? tour.heroImage?.url ?? null;
+    return {
+        // Quest titles already carry the operator name, so skip the site title template.
+        title: { absolute: title },
+        description,
+        ...(seo ? { alternates: { canonical: seo.canonicalUrl } } : {}),
+        openGraph: {
+            title,
+            description,
+            type: "website",
+            ...(seo ? { url: seo.canonicalUrl } : {}),
+            ...(image ? { images: [{ url: image, alt: tour.title }] } : {}),
+        },
+        twitter: {
+            card: image ? "summary_large_image" : "summary",
+            title,
+            description,
+            ...(image ? { images: [image] } : {}),
+        },
+    };
+}
+/**
+ * Sitemap entries for Quest tours, for `app/sitemap.ts`.
+ *
+ * ```ts
+ * tourSitemapEntries(await quest.getTours(), { baseUrl: "https://example.com", path: (slug) => `/tours/${slug}` })
+ * ```
+ */
+export function tourSitemapEntries(tours, options) {
+    const base = options.baseUrl.replace(/\/+$/, "");
+    return tours.map((tour) => ({
+        url: `${base}${options.path(tour.slug)}`,
+        changeFrequency: "weekly",
+        priority: tour.featured ? 0.9 : 0.8,
+    }));
+}

package/dist/next/revalidate-handler.d.ts

@@ -0,0 +1,18 @@
+export type RevalidateHandlerOptions = {
+    /** Defaults to `process.env.QUEST_WEBHOOK_SECRET`. */
+    secret?: string;
+    /** Defaults to `process.env.QUEST_SITE_TOKEN`. Events for other sites are ignored. */
+    siteToken?: string;
+};
+/**
+ * Route handler for `app/api/quest/revalidate/route.ts`:
+ *
+ * ```ts
+ * export const { POST } = createRevalidateHandler();
+ * ```
+ *
+ * Quest calls it whenever a package changes, so tour pages refresh within seconds.
+ */
+export declare function createRevalidateHandler(options?: RevalidateHandlerOptions): {
+    POST(request: Request): Promise<Response>;
+};

package/dist/next/revalidate-handler.js

@@ -0,0 +1,42 @@
+import { revalidateTag } from "next/cache";
+import { toursChangedEventSchema } from "../schema/index.js";
+import { QUEST_TOURS_CACHE_TAG } from "../server/client.js";
+import { QUEST_SIGNATURE_HEADER, verifyQuestSignature } from "./signature.js";
+/**
+ * Route handler for `app/api/quest/revalidate/route.ts`:
+ *
+ * ```ts
+ * export const { POST } = createRevalidateHandler();
+ * ```
+ *
+ * Quest calls it whenever a package changes, so tour pages refresh within seconds.
+ */
+export function createRevalidateHandler(options = {}) {
+    return {
+        async POST(request) {
+            const secret = (options.secret ?? process.env.QUEST_WEBHOOK_SECRET)?.trim();
+            if (!secret) {
+                return Response.json({ error: "QUEST_WEBHOOK_SECRET is not set on this site." }, { status: 500 });
+            }
+            const body = await request.text();
+            const verified = verifyQuestSignature({
+                secret,
+                header: request.headers.get(QUEST_SIGNATURE_HEADER),
+                body,
+            });
+            if (!verified) {
+                return Response.json({ error: "Invalid signature." }, { status: 401 });
+            }
+            const event = toursChangedEventSchema.safeParse(JSON.parse(body));
+            if (!event.success) {
+                return Response.json({ error: "Unknown event." }, { status: 400 });
+            }
+            const siteToken = (options.siteToken ?? process.env.QUEST_SITE_TOKEN)?.trim();
+            if (siteToken && event.data.siteToken !== siteToken) {
+                return Response.json({ revalidated: false, reason: "Different site." }, { status: 202 });
+            }
+            revalidateTag(QUEST_TOURS_CACHE_TAG, { expire: 0 });
+            return Response.json({ revalidated: true });
+        },
+    };
+}

package/dist/next/signature.d.ts

@@ -0,0 +1,12 @@
+export declare const QUEST_SIGNATURE_HEADER = "x-quest-signature";
+/** Reject events older (or newer) than this, to limit replay of a captured request. */
+export declare const QUEST_SIGNATURE_TOLERANCE_SECONDS = 300;
+/**
+ * Verify `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">` as sent by Quest.
+ */
+export declare function verifyQuestSignature(input: {
+    secret: string;
+    header: string | null;
+    body: string;
+    nowSeconds?: number;
+}): boolean;

package/dist/next/signature.js

@@ -0,0 +1,26 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const QUEST_SIGNATURE_HEADER = "x-quest-signature";
+/** Reject events older (or newer) than this, to limit replay of a captured request. */
+export const QUEST_SIGNATURE_TOLERANCE_SECONDS = 300;
+/**
+ * Verify `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">` as sent by Quest.
+ */
+export function verifyQuestSignature(input) {
+    if (!input.header)
+        return false;
+    const parts = new Map(input.header.split(",").map((part) => {
+        const [key, ...rest] = part.trim().split("=");
+        return [key ?? "", rest.join("=")];
+    }));
+    const timestamp = Number(parts.get("t"));
+    const signature = parts.get("v1") ?? "";
+    if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/.test(signature))
+        return false;
+    const now = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > QUEST_SIGNATURE_TOLERANCE_SECONDS)
+        return false;
+    const expected = createHmac("sha256", input.secret)
+        .update(`${timestamp}.${input.body}`)
+        .digest();
+    return timingSafeEqual(expected, Buffer.from(signature, "hex"));
+}