@questpackages/tours 0.1.0-test.0

package/dist/schema/index.js

@@ -0,0 +1,249 @@
+import { z } from "zod";
+/**
+ * Public data contract between Quest and operator websites (API v1).
+ *
+ * Quest validates every `/api/public/v1` response against these schemas, and the SDK
+ * parses every response with them. A section that Quest does not model has no field
+ * here, so an operator site cannot render it from Quest data.
+ *
+ * Additive changes (new optional fields) are allowed in v1. Removing or renaming a
+ * field requires API v2.
+ */
+export const QUEST_TOURS_API_VERSION = 1;
+export const tourImageSchema = z.object({
+    url: z.string().url(),
+    alt: z.string(),
+    srcSet: z.string().nullable(),
+    width: z.number().int().positive().nullable(),
+    height: z.number().int().positive().nullable(),
+});
+export const tourTagSchema = z.object({
+    slug: z.string().min(1),
+    label: z.string().min(1),
+});
+/** A price as Quest displays it, plus the parsed amount for structured data and sorting. */
+export const tourMoneySchema = z.object({
+    formatted: z.string().min(1),
+    amount: z.number().nonnegative().nullable(),
+    currency: z.string().min(3).max(8),
+});
+export const tourCardSchema = z.object({
+    slug: z.string().min(1),
+    title: z.string().min(1),
+    summary: z.string().nullable(),
+    durationDays: z.number().int().positive(),
+    durationLabel: z.string(),
+    startDestination: z.string().nullable(),
+    endDestination: z.string().nullable(),
+    /** Destinations visited, in itinerary order (e.g. for destination pages on the operator site). */
+    destinations: z.array(z.string()),
+    heroImage: tourImageSchema.nullable(),
+    highlights: z.array(z.string()),
+    includedPreview: z.array(z.string()),
+    tags: z.array(tourTagSchema),
+    featured: z.boolean(),
+    price: z.object({
+        total: tourMoneySchema.nullable(),
+        fromPerPerson: tourMoneySchema.nullable(),
+    }),
+});
+export const tourActivitySchema = z.object({
+    time: z.string().nullable(),
+    name: z.string().min(1),
+    location: z.string().nullable(),
+    notes: z.string().nullable(),
+});
+export const tourDaySchema = z.object({
+    dayLabel: z.string(),
+    dateLabel: z.string().nullable(),
+    destination: z.string(),
+    title: z.string(),
+    description: z.string(),
+    image: tourImageSchema.nullable(),
+    mealPlan: z.string().nullable(),
+    accommodation: z
+        .object({
+        label: z.string(),
+        name: z.string().min(1),
+        detail: z.string(),
+        image: tourImageSchema.nullable(),
+    })
+        .nullable(),
+    activityGroups: z.array(z.object({
+        title: z.string(),
+        activities: z.array(tourActivitySchema),
+    })),
+    activities: z.array(tourActivitySchema),
+    gallery: z.array(tourImageSchema),
+});
+export const tourLodgingSchema = z.object({
+    name: z.string().min(1),
+    label: z.string(),
+    detail: z.string(),
+    image: tourImageSchema.nullable(),
+    nights: z.array(z.string()),
+    mealPlan: z.string().nullable(),
+});
+export const tourVehicleSchema = z.object({
+    name: z.string().min(1),
+    description: z.string(),
+    image: tourImageSchema.nullable(),
+    features: z.array(z.string()),
+    maxPassengers: z.number().int().positive().nullable(),
+});
+export const tourPartyPriceOptionSchema = z.object({
+    adults: z.number().int().positive(),
+    children: z.number().int().nonnegative(),
+    total: z.string(),
+    perPerson: z.string(),
+    vehicleCapacityLabel: z.string().nullable(),
+});
+export const tourPricingSchema = z.object({
+    currency: z.string().min(3).max(8),
+    total: tourMoneySchema.nullable(),
+    perPerson: tourMoneySchema.nullable(),
+    fromPerPerson: tourMoneySchema.nullable(),
+    /** Empty when the operator hides the detailed price breakdown in Quest. */
+    lineItems: z.array(z.object({
+        name: z.string(),
+        qty: z.string(),
+        unitPrice: z.string(),
+        total: z.string(),
+    })),
+    /** Price per party size. Null when the package has no party pricing matrix. */
+    partySize: z
+        .object({
+        minTravellers: z.number().int().positive(),
+        maxTravellers: z.number().int().positive(),
+        baselineAdults: z.number().int().positive(),
+        childrenAllowed: z.boolean(),
+        options: z.array(tourPartyPriceOptionSchema),
+    })
+        .nullable(),
+});
+export const tourOperatorSchema = z.object({
+    name: z.string().min(1),
+    logoUrl: z.string().url().nullable(),
+    website: z.string().nullable(),
+    phone: z.string().nullable(),
+    address: z.string().nullable(),
+});
+export const tourEnquirySchema = z.object({
+    /** Absolute URL the visitor's browser POSTs the inquiry form to. */
+    endpoint: z.string().url(),
+    /** Absolute URL the visitor's browser POSTs the booking request form to. */
+    bookingEndpoint: z.string().url(),
+    minTravellers: z.number().int().positive(),
+    maxTravellers: z.number().int().positive(),
+    childrenAllowed: z.boolean(),
+});
+export const tourSchema = tourCardSchema.extend({
+    overview: z.array(z.string()),
+    gallery: z.array(tourImageSchema),
+    days: z.array(tourDaySchema),
+    lodging: z.array(tourLodgingSchema),
+    vehicle: tourVehicleSchema.nullable(),
+    inclusions: z.array(z.string()),
+    exclusions: z.array(z.string()),
+    paymentTerms: z.array(z.string()),
+    paymentNote: z.string().nullable(),
+    availability: z.object({
+        unlimited: z.boolean(),
+        startDate: z.string().nullable(),
+        endDate: z.string().nullable(),
+    }),
+    pricing: tourPricingSchema,
+    operator: tourOperatorSchema,
+    enquiry: tourEnquirySchema,
+    related: z.array(tourCardSchema),
+});
+/** SEO built by Quest for the operator page URL passed as `?url=`. Follows the Quest SEO guide. */
+export const tourSeoSchema = z.object({
+    title: z.string(),
+    description: z.string(),
+    canonicalUrl: z.string().url(),
+    ogImage: z.string().nullable(),
+    heroPreloadUrl: z.string().nullable(),
+    jsonLd: z.array(z.record(z.string(), z.unknown())),
+});
+export const tourListResponseSchema = z.object({
+    apiVersion: z.literal(QUEST_TOURS_API_VERSION),
+    data: z.object({
+        tours: z.array(tourCardSchema),
+        nextCursor: z.string().nullable(),
+        totalCount: z.number().int().nonnegative(),
+    }),
+});
+export const tourDetailResponseSchema = z.object({
+    apiVersion: z.literal(QUEST_TOURS_API_VERSION),
+    data: z.object({
+        tour: tourSchema,
+        seo: tourSeoSchema.nullable(),
+    }),
+});
+export const tourTagsResponseSchema = z.object({
+    apiVersion: z.literal(QUEST_TOURS_API_VERSION),
+    data: z.object({
+        tags: z.array(tourTagSchema.extend({ count: z.number().int().nonnegative() })),
+    }),
+});
+export const questApiErrorSchema = z.object({
+    apiVersion: z.literal(QUEST_TOURS_API_VERSION),
+    error: z.object({
+        code: z.enum(["not_found", "unavailable", "invalid_request", "internal"]),
+        message: z.string(),
+    }),
+});
+/** Fields the enquiry endpoint accepts. Mirrors Quest's inquiry validation. */
+export const tourEnquiryInputSchema = z.object({
+    name: z.string().trim().min(2, "Please enter your name").max(120),
+    email: z.string().trim().email("Please enter a valid email").max(200),
+    phone: z.string().trim().min(6, "Enter a phone or WhatsApp number").max(50),
+    countryCode: z.string().trim().length(2, "Select a country"),
+    numberOfAdults: z.number().int().min(1).max(30).optional(),
+    numberOfChildren: z.number().int().min(0).max(20).optional(),
+    travelDateMode: z.enum(["flexible", "specific_month", "specific_date"]),
+    preferredStartDate: z.string().trim().optional(),
+    preferredMonth: z.string().trim().regex(/^\d{4}-\d{2}$/).optional(),
+    message: z.string().trim().max(2000).optional(),
+    indicativeTotal: z.string().trim().max(80).optional(),
+    indicativePerPerson: z.string().trim().max(80).optional(),
+    indicativeCurrency: z.string().trim().max(8).optional(),
+});
+/** Fields the booking request endpoint accepts. Mirrors Quest's booking validation. */
+export const tourBookingInputSchema = z.object({
+    name: z.string().trim().min(2).max(120),
+    email: z.string().trim().email().max(200),
+    phone: z.string().trim().min(6).max(50),
+    nationalityCode: z.string().trim().length(2),
+    startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    numberOfAdults: z.number().int().min(1).max(30),
+    numberOfChildren: z.number().int().min(0).max(20),
+    childAges: z.array(z.number().int().min(0).max(17)).max(20),
+    accommodationTier: z.enum(["budget", "mid_range", "luxury"]).optional(),
+    singleSupplement: z.boolean(),
+    specialRequirements: z.string().trim().max(2000).optional(),
+    termsAccepted: z.literal(true),
+    indicativeTotal: z.string().trim().max(80).optional(),
+    indicativePerPerson: z.string().trim().max(80).optional(),
+    indicativeCurrency: z.string().trim().max(8).optional(),
+});
+/** Successful inquiry or booking submission, as returned by Quest. */
+export const tourContactSuccessSchema = z.object({
+    ok: z.literal(true),
+    referenceNumber: z.string(),
+    summary: z.object({
+        packageTitle: z.string(),
+        travelDatesLabel: z.string(),
+        adults: z.number().optional(),
+        children: z.number().optional(),
+        contactName: z.string(),
+    }),
+});
+/** Body of the revalidate webhook Quest sends to the operator site. */
+export const toursChangedEventSchema = z.object({
+    event: z.literal("tours.changed"),
+    siteToken: z.string().min(1),
+    slugs: z.array(z.string()),
+    sentAt: z.string(),
+});

package/dist/server/client.d.ts

@@ -0,0 +1,43 @@
+import { type Tour, type TourCard, type TourSeo, type TourTag } from "../schema/index.js";
+/** Cache tag on every Quest fetch. The revalidate webhook handler expires it. */
+export declare const QUEST_TOURS_CACHE_TAG = "quest-tours";
+export type QuestToursConfig = {
+    /** Public site token from Quest (Website embeds). Defaults to `process.env.QUEST_SITE_TOKEN`. */
+    siteToken?: string;
+    /** Quest app origin, e.g. `https://app.questheaven.com`. Defaults to `process.env.QUEST_ORIGIN`. */
+    questOrigin?: string;
+    /** Fallback refresh interval when the webhook is not set up. Default 300 seconds. */
+    revalidateSeconds?: number;
+    /** Custom fetch (tests). */
+    fetch?: typeof fetch;
+};
+export declare class QuestToursError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(message: string, code: string, status: number);
+}
+export type GetToursOptions = {
+    /** Tag slug, e.g. `gorilla-trekking`. */
+    tag?: string;
+    /** Only tours marked as featured in Quest. */
+    featured?: boolean;
+};
+export type GetTourOptions = {
+    /**
+     * Absolute URL of the page that shows this tour on your site. When set, Quest returns
+     * SEO metadata and JSON-LD built for that URL.
+     */
+    url?: string;
+};
+export type TourWithSeo = {
+    tour: Tour;
+    seo: TourSeo | null;
+};
+export type QuestToursClient = {
+    getTours(options?: GetToursOptions): Promise<TourCard[]>;
+    getTour(slug: string, options?: GetTourOptions): Promise<TourWithSeo | null>;
+    getTags(): Promise<(TourTag & {
+        count: number;
+    })[]>;
+};
+export declare function createQuestTours(config?: QuestToursConfig): QuestToursClient;

package/dist/server/client.js

@@ -0,0 +1,85 @@
+import { questApiErrorSchema, tourDetailResponseSchema, tourListResponseSchema, tourTagsResponseSchema, } from "../schema/index.js";
+/** Cache tag on every Quest fetch. The revalidate webhook handler expires it. */
+export const QUEST_TOURS_CACHE_TAG = "quest-tours";
+const DEFAULT_REVALIDATE_SECONDS = 300;
+const LIST_PAGE_SIZE = 24;
+const MAX_LIST_PAGES = 20;
+export class QuestToursError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = "QuestToursError";
+        this.code = code;
+        this.status = status;
+    }
+}
+function requireValue(value, envName) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        throw new QuestToursError(`Missing ${envName}. Add it to your environment (run \`npx @questpackages/tours init\`).`, "config", 0);
+    }
+    return trimmed;
+}
+export function createQuestTours(config = {}) {
+    const fetchImpl = config.fetch ?? fetch;
+    const revalidate = config.revalidateSeconds ?? DEFAULT_REVALIDATE_SECONDS;
+    function baseUrl() {
+        const origin = requireValue(config.questOrigin ?? process.env.QUEST_ORIGIN, "QUEST_ORIGIN");
+        const siteToken = requireValue(config.siteToken ?? process.env.QUEST_SITE_TOKEN, "QUEST_SITE_TOKEN");
+        return `${origin.replace(/\/+$/, "")}/api/public/v1/sites/${encodeURIComponent(siteToken)}`;
+    }
+    async function request(path) {
+        const response = await fetchImpl(`${baseUrl()}${path}`, {
+            headers: { Accept: "application/json" },
+            next: { tags: [QUEST_TOURS_CACHE_TAG], revalidate },
+        });
+        const body = await response.json().catch(() => null);
+        if (!response.ok) {
+            const parsed = questApiErrorSchema.safeParse(body);
+            throw new QuestToursError(parsed.success ? parsed.data.error.message : `Quest responded with HTTP ${response.status}`, parsed.success ? parsed.data.error.code : "http", response.status);
+        }
+        return { status: response.status, body };
+    }
+    return {
+        async getTours(options = {}) {
+            const tours = [];
+            let cursor = null;
+            for (let page = 0; page < MAX_LIST_PAGES; page += 1) {
+                const params = new URLSearchParams({ limit: String(LIST_PAGE_SIZE) });
+                if (options.tag)
+                    params.set("tag", options.tag);
+                if (options.featured)
+                    params.set("featured", "1");
+                if (cursor)
+                    params.set("cursor", cursor);
+                const { body } = await request(`/tours?${params.toString()}`);
+                const { data } = tourListResponseSchema.parse(body);
+                tours.push(...data.tours);
+                cursor = data.nextCursor;
+                if (!cursor)
+                    break;
+            }
+            return tours;
+        },
+        async getTour(slug, options = {}) {
+            const params = new URLSearchParams();
+            if (options.url)
+                params.set("url", options.url);
+            const query = params.size > 0 ? `?${params.toString()}` : "";
+            try {
+                const { body } = await request(`/tours/${encodeURIComponent(slug)}${query}`);
+                return tourDetailResponseSchema.parse(body).data;
+            }
+            catch (error) {
+                if (error instanceof QuestToursError && error.status === 404)
+                    return null;
+                throw error;
+            }
+        },
+        async getTags() {
+            const { body } = await request("/tags");
+            return tourTagsResponseSchema.parse(body).data.tags;
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,2 @@
+import "server-only";
+export { createQuestTours, QuestToursError, QUEST_TOURS_CACHE_TAG, type GetTourOptions, type GetToursOptions, type QuestToursClient, type QuestToursConfig, type TourWithSeo, } from "./client.js";

package/dist/server/index.js

@@ -0,0 +1,2 @@
+import "server-only";
+export { createQuestTours, QuestToursError, QUEST_TOURS_CACHE_TAG, } from "./client.js";